Skip to main content

Crate trilean_json_shape

Crate trilean_json_shape 

Source
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, as JSON.parse reads it (serde_json is built with float_roundtrip for that). Written back, Value’s Display is the text JSON.stringify writes, and its Serialize writes the same text, for every finite double, through serde_json’s raw value (see Value): it is written for serde_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 by MAX_SAFE_INTEGER in 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 $ref ignores 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.
FieldDef
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 (see crate::normalise): a consumer that assigns the keys to an object of its own would otherwise change that object’s prototype.
ObjectDef
An object with named fields.
OpenObject
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_json makes 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.
PatternError
Why a pattern is not in the supported subset.
Registry
Collects definitions while a type registers itself and what it refers to.
SchemaOptions
How a standalone schema document is written.
ShapeDef
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.
PathSegment
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 value matches shape.
check
Every way value does not match shape, with the path of the value each is about. Empty when it matches.
check_with_work
check and 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 (or definitions). root_name is the root’s own definition, dropped from the block unless another definition refers to it.
normalise
The document as shape reads it, for a document that check accepted: 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 (see crate::ObjectDef::strips) loses the keys it does not name. The value is undefined for a document check refused.
number_to_string
A number as JSON.stringify writes 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 are 0, and NaN and the infinities are the texts NaN, Infinity and -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 by root_name, with the definitions it needs.
typescript_declarations
One export type declaration 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.

Derive Macros§

Shape