Expand description
One definition of a JSON shape that validates documents and writes the JSON Schema and TypeScript declarations for them, so the three cannot disagree.
A type derives Shape, reading the serde attributes it already carries. Deserialising it through serde is
validating, and the same descriptor writes the JSON Schema (json_schema, schema_definitions) and the
declarations (typescript_declarations).
§Compile-time checks
The derive refuses at compile time what could never validate: a constraint on a type it does not apply to, a
pattern outside the supported subset, a flattened field or newtype variant that is not a struct, a property key
used twice once a tag and flattened fields are counted, an attribute it does not read, and two unit variants in an
untagged enum. Two different types with one definition name cannot be told apart at compile time, because they may
live in different crates, so Definitions::of panics naming both; #[shape(name = "...")] renames one.
§Limits that follow from JSON text, and from JSON Schema
- Numbers are
f64s, and a literal is read as the nearest double, asJSON.parsereads it (serde_jsonis built withfloat_roundtripfor that). Written back,Value’sDisplayis the textJSON.stringifywrites, and itsSerializewrites the same text, for every finite double, throughserde_json’s raw value (seeValue): it is written forserde_json’s serialisers, and another serialiser shows a number that is not a whole number below 2^53 as that type’s marker, not as a number. Integer types are bounded byMAX_SAFE_INTEGERin both the validator and the schema. - Reading goes through
serde_json, which refuses nesting deeper than 128 levels and an unpaired surrogate escape. A JSON Schema validator in JavaScript accepts both, so the schema accepts documents this crate cannot read; the agreement tests leave them out for that reason. - A union is checked in time linear in the document: alternatives that cannot match the value’s kind or lack a required key are discarded first, and an alternative that accepted a value is remembered.
- Patterns are a subset of ECMAScript regular expressions over Unicode scalar values, compiled to an automaton, so matching is linear in the text.
- In draft-07 a
$refignores its sibling keywords, so a field of a named type that carries a description is written as{"$ref": ..., "description": ...}and a validator that follows the draft to the letter drops the description (and only the description: every validation keyword is in the referenced definition). Draft 2020-12 applies both. The consumer that publishes draft-07 decides, against its own published file, whether that matters to it.
Structs§
- Definitions
- The named shapes a document is described by, in the order they were first reached.
- Field
Def - One field of an object.
- Issue
- One problem with a document, at the path of the value it is about.
- Issues
- Every problem a validation found, never empty when it is an error.
- Map
- An object whose values all have one shape, kept in input order. A key called
__proto__is dropped when the map is built, as it is when a document is read as the shape (seecrate::normalise): a consumer that assigns the keys to an object of its own would otherwise change that object’s prototype. - Object
Def - An object with named fields.
- Open
Object - An object with any keys and any values, kept in input order.
- Path
- The steps from the root of a document to a value inside it. It also carries what a conversion of one document
remembers between its nodes (which alternative of a union accepted which value), so that choosing among
alternatives costs each value once.
Only this crate makes one (
Shape::from_jsonmakes a fresh one for each document), so what it remembers cannot outlive the document it was made on. - Pattern
- A compiled pattern, matched by simulating a Thompson automaton: no backtracking and no recursion over the text, so matching costs time linear in the text times the size of the pattern, and constant stack, whatever the text.
- Pattern
Error - Why a pattern is not in the supported subset.
- Registry
- Collects definitions while a type registers itself and what it refers to.
- Schema
Options - How a standalone schema document is written.
- Shape
Def - A shape with the description that documents it.
Enums§
- Class
- The class of a type’s shape, which decides at compile time which
#[shape(...)]constraints may apply to a field of that type. A named type (a derived struct or enum) is written as a reference to its definition, so no constraint applies to the field itself. - Constraint
- A constraint a field attribute adds to the shape of the field’s type.
- Draft
- The JSON Schema draft to write.
- Kind
- What a value of a shape looks like.
- Path
Segment - One step into a document: an object key or an array index.
- Value
- A JSON value.
Constants§
- MAX_
SAFE_ INTEGER - The largest integer that a JavaScript number, and so a JSON document read by JavaScript, holds exactly.
Traits§
- Shape
- A type with a shape.
#[derive(Shape)]implements it from the type’s serde attributes and#[shape(...)].
Functions§
- accepts
- Whether
valuematchesshape. - check
- Every way
valuedoes not matchshape, with the path of the value each is about. Empty when it matches. - check_
with_ work checkand the number of shapes it visited, which is at most a constant times the size of the document times the size of the shape.- json_
schema - A standalone document for
root, written inline at the top with every other definition under$defs(ordefinitions).root_nameis the root’s own definition, dropped from the block unless another definition refers to it. - normalise
- The document as
shapereads it, for a document thatcheckaccepted: an object keeps the keys its shape names, in the order the shape lists them (a tag first), then the keys its shape types without naming (in the document’s order), a map drops a key called__proto__, and a union is read as the alternative that matches. A closed object that strips (seecrate::ObjectDef::strips) loses the keys it does not name. The value is undefined for a documentcheckrefused. - number_
to_ string - A number as
JSON.stringifywrites it (ECMAScript’s Number-to-string): the shortest digits that read back as the double, written as digits and zeros for magnitudes from 1e-6 up to below 1e21 and with an exponent outside that. Both zeros are0, and NaN and the infinities are the textsNaN,Infinityand-Infinity. - schema_
definitions - Just the definitions, each as a schema whose references are written under
pointer, a JSON Pointer fragment such as#/definitions/trilean, which is where the document that embeds them holds them. - schema_
of - The standalone document for the type
T, named byroot_name, with the definitions it needs. - typescript_
declarations - One
export typedeclaration per definition, in the order the definitions were reached. The types describe the values a document holds once it has been validated: an object that is not closed has an index signature, and a field that may be absent is optional.