silk.schema.json.

When to use#

Call SchemaJson.decode to read a value of a silk.schema.schema.Schema type from JSON text, and SchemaJson.encode to write one to the ambient Writer. Use silk.json.value.Json to work with a JSON document whose shape is not known in advance.

Details#

Decoding streams over the text with silk.json.scanner.JsonScanner and builds the value directly, with no tree of JSON values in between. Object members may come in any order, and members the type does not name are skipped. Encoding writes compact JSON, with struct fields in declaration order.

Examples#

Report where a value failed#

import silk.collections.list { List }
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.schema.issue { IssueReason, SchemaError }
import silk.schema.json { SchemaJson }
import silk.schema.schema { Schema }

struct Limits {
  pub ports: List<u16>,
}

impl Schema for Limits {}

pub effect fn main() -> i32 ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let decoded = run Effect.result(SchemaJson.decode<Limits>(b"{\"ports\": [80, 70000]}"))
    |> Effect.provideMut<Allocator>(&mut allocator)
  return match move decoded {
    Result<Limits, SchemaError | OutOfMemoryError>.Success {..} => 1
    Result<Limits, SchemaError | OutOfMemoryError>.Failure {error} => match move error {
      SchemaError {path, issue} => if path.view() == "ports[1]" && issue.reason == IssueReason.InvalidValue { 0 } else { 2 }
      OutOfMemoryError {} => 3
    }
  }
}

Import as SchemaJson with import silk.schema.json { SchemaJson }.

Public declarations: 3.

SchemaJson#

pub struct SchemaJson

The owner of the JSON entry points. It has no fields and is never constructed.

Implementation SchemaJson#

impl SchemaJson

Associated function decode#

pub effect fn decode<T: Schema>(bytes: &[u8]) -> T ! SchemaError | OutOfMemoryError ? &mut Allocator

Reads one value of type T from the JSON text bytes.

Details#

The whole input must be one JSON value, with optional white space around it.

Errors#

• SchemaError if the text is not valid JSON or does not hold a T. Its path names the part that failed, and its issue has the byte offset when the problem is in the text.

• OutOfMemoryError if the Allocator cannot supply the value.

Associated function decodeAll#

pub effect fn decodeAll<T: Schema>(bytes: &[u8]) -> T ! SchemaErrors | OutOfMemoryError ? &mut Allocator

Reads one value of type T from the JSON text bytes, reporting every failed check.

Details#

Each failed Schema.check is recorded and reading goes on, so one call lists every field that is out of range. Reading stops at the first part whose shape is wrong, such as text where a number belongs, which is listed last.

Errors#

• SchemaErrors with every problem found, in input order.

• OutOfMemoryError if the Allocator cannot supply the value.

Associated function encode#

pub effect fn encode<T: Schema>(value: &T)
    -> () ! SchemaError | WriterError | OutOfMemoryError ? &mut Writer | &mut Allocator

Writes value as compact JSON to the ambient Writer.

Errors#

• SchemaError if JSON cannot hold the value, such as a NaN or an infinity, or a value nested more than 64 levels deep. Its path is empty.

• WriterError if the Writer fails. Bytes that it accepted before the failure stay written.

• OutOfMemoryError if a codec needs memory that the Allocator cannot supply.

JsonSchemaReader#

pub struct JsonSchemaReader<'input>

A SchemaReader over JSON text.

When to use#

SchemaJson.decode uses it. Use it directly to read a value from the middle of a larger program's own JSON handling.

Implementation JsonSchemaReader<'input>#

impl<'input> JsonSchemaReader<'input>

Associated function make#

pub fn make(input: &'input [u8]) -> JsonSchemaReader<'input>

Returns a reader at the start of input.

Associated function collectingAll#

pub fn collectingAll(input: &'input [u8]) -> JsonSchemaReader<'input>

Returns a reader at the start of input that records every failed check instead of stopping at the first. Read them with JsonSchemaReader.intoErrors.

Method intoErrors#

pub fn intoErrors(self: Self) -> List<SchemaError>

Returns the failed checks the reader recorded, in the order they were found.

Implementation SchemaReader for JsonSchemaReader<'input>#

impl<'input> SchemaReader for JsonSchemaReader<'input>

Operation path#

fn path(self: &mut Self) -> &mut SchemaPath

Returns the path of the part being read.

Operation checkFailed#

effect fn checkFailed(self: &mut Self, field: Option<string<'static>>, expected: string<'static>)
    -> () ! Issue | OutOfMemoryError ? &mut Allocator

Fails with the check, or records it and returns when the reader collects every problem.

Operation boolean#

effect fn boolean(self: &mut Self) -> bool ! Issue | OutOfMemoryError ? &mut Allocator

Reads true or false.

Operation signed#

effect fn signed(self: &mut Self) -> i64 ! Issue | OutOfMemoryError ? &mut Allocator

Reads a JSON number as an i64.

Operation unsigned#

effect fn unsigned(self: &mut Self) -> u64 ! Issue | OutOfMemoryError ? &mut Allocator

Reads a JSON number as a u64.

Operation float#

effect fn float(self: &mut Self) -> f64 ! Issue | OutOfMemoryError ? &mut Allocator

Reads a JSON number as an f64.

Operation text#

effect fn text(self: &mut Self) -> String ! Issue | OutOfMemoryError ? &mut Allocator

Reads a JSON string, with its escapes decoded.

Operation null#

effect fn null(self: &mut Self) -> bool ! Issue | OutOfMemoryError ? &mut Allocator

Reads past null and returns true, or returns false for another value.

Operation beginList#

effect fn beginList(self: &mut Self) -> () ! Issue | OutOfMemoryError ? &mut Allocator

Reads past [.

Operation nextElement#

effect fn nextElement(self: &mut Self) -> bool ! Issue | OutOfMemoryError ? &mut Allocator

Returns true at the next element, or reads past ] and returns false.

Operation beginObject#

effect fn beginObject(self: &mut Self) -> () ! Issue | OutOfMemoryError ? &mut Allocator

Checks that an object comes next and remembers where it starts.

Operation member#

effect fn member(self: &mut Self, key: string) -> bool ! Issue | OutOfMemoryError ? &mut Allocator

Searches the object being read for the member key and leaves the reader at its value.

Operation endObject#

effect fn endObject(self: &mut Self) -> () ! Issue | OutOfMemoryError ? &mut Allocator

Reads past the whole object being read.

JsonSchemaWriter#

pub struct JsonSchemaWriter

A SchemaWriter that writes compact JSON to the ambient Writer.

When to use#

SchemaJson.encode uses it. Use it directly to write a value inside JSON that the program writes itself.

Implementation JsonSchemaWriter#

impl JsonSchemaWriter

Associated function make#

pub fn make() -> JsonSchemaWriter

Returns a writer for one top-level value.

Implementation SchemaWriter for JsonSchemaWriter#

impl SchemaWriter for JsonSchemaWriter

Operation boolean#

effect fn boolean(self: &mut Self, value: bool) -> () ! Issue | WriterError ? &mut Writer

Writes true or false.

Operation signed#

effect fn signed(self: &mut Self, value: i64) -> () ! Issue | WriterError ? &mut Writer

Writes the integer in decimal.

Operation unsigned#

effect fn unsigned(self: &mut Self, value: u64) -> () ! Issue | WriterError ? &mut Writer

Writes the integer in decimal.

Operation float#

effect fn float(self: &mut Self, value: f64) -> () ! Issue | WriterError ? &mut Writer

Writes the number. A NaN or an infinity fails with IssueReason.InvalidValue.

Operation text#

effect fn text(self: &mut Self, value: string) -> () ! Issue | WriterError ? &mut Writer

Writes a JSON string, with the escapes JSON needs.

Operation null#

effect fn null(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes null.

Operation beginList#

effect fn beginList(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes [.

Operation element#

effect fn element(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes , before every element but the first.

Operation endList#

effect fn endList(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes ].

Operation beginObject#

effect fn beginObject(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes {.

Operation key#

effect fn key(self: &mut Self, name: string) -> () ! Issue | WriterError ? &mut Writer

Writes , before every member but the first, then the key and :.

Operation endObject#

effect fn endObject(self: &mut Self) -> () ! Issue | WriterError ? &mut Writer

Writes }.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.