SchemaRepresentation

Open persistence identity and schema dependencies carried by opaque checks.

Open persistence identity carried by declarations and opaque checks.

Options for generating schema representations.

Imports a JSON Schema Draft 2020-12 document as a runtime schema.

When to use

Use when you need to validate or transform values described by an external JSON Schema document.

Details

For the Draft 2020-12 subset translated exactly by this importer, compiling the imported schema through toRepresentation and toJsonSchemaDocument produces a document that accepts the same JSON values as the input. This is a semantic round-trip guarantee; keyword layout, definitions, and annotations may be normalized.

Gotchas

• $dynamicRef, contains, dependentRequired, dependentSchemas, not, active if / then / else, unevaluatedItems, and unevaluatedProperties throw an Unsupported JSON Schema keyword error. Inactive conditional keywords and minContains / maxContains without contains have no validation effect and are ignored.
• Objects and arrays used as const values or enum members throw an Unsupported structured JSON Schema value error.
• Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive anyOf literal sets. Other union intersections, including cases that would duplicate a nested choice, throw an Unsupported intersection of overlapping unions error.
• Unknown extension keywords are ignored and their semantics are not enforced.
• Only direct local references to top-level definitions in the form #/$defs/<escaped-token> are supported. Root references, external references, and pointers below a definition throw an Unsupported reference error. A direct reference to a missing definition throws an Invalid reference error.
• Built-in declarations and checks are reconstructed with importer-owned revivers.
• Pattern constraints reached during translation cause an error by default. Use patterns: "apply" only for trusted documents, or patterns: "ignore" to weaken validation explicitly; ignored patterns are outside the round-trip guarantee.
• onEnter results replace the corresponding input nodes, so the round-trip guarantee applies to the rewritten document.
• Callback results are used directly, and exceptions raised by a callback pass through unchanged.

See

• fromJsonSchemaMultiDocument for multiple roots sharing definitions
• toRepresentation for converting the result to a representation document

Imports multiple JSON Schema Draft 2020-12 roots as runtime schemas with shared definitions.

When to use

Use when multiple imported roots share reachable definitions, aliases, or recursion.

Gotchas

• Only definitions reachable from a root are translated.
• Unsupported standard validation and applicator keywords throw an Unsupported JSON Schema keyword error. Unknown extension keywords are ignored and their semantics are not enforced.
• Objects and arrays used as const values or enum members throw an Unsupported structured JSON Schema value error.
• Intersections of overlapping unions are limited to disjoint root-type partitions and finite primitive anyOf literal sets. Other union intersections, including cases that would duplicate a nested choice, throw an Unsupported intersection of overlapping unions error.
• Only direct local references to top-level definitions in the form #/$defs/<escaped-token> are supported. Root references, external references, and pointers below a definition throw an Unsupported reference error. A direct reference to a missing definition throws an Invalid reference error.
• Pattern constraints reached during translation cause an error by default. Use patterns: "apply" only for trusted documents, or patterns: "ignore" to weaken validation explicitly.
• Callback results are used directly, and exceptions raised by a callback pass through unchanged.

See

• fromJsonSchemaDocument for a single root
• toRepresentations for converting the returned schema ASTs to a representation document

Creates generated runtime and TypeScript source strings for a schema.

Creates a declaration reviver while inferring its payload type from payloadSchema.

Creates a filter group reviver while inferring its payload type from payloadSchema.

Creates a filter reviver while inferring its payload type from payloadSchema.

Lowers the encoded side of an AST to a live representation document.

When to use

Use when you have one SchemaAST.AST and need a live Document for inspection, persistence, or compilation.

Details

Apply SchemaAST.toType to the AST first to lower its type side instead. The optional reference policy controls which candidates are moved into the document's shared reference table.

See

• toRepresentations for multiple roots sharing one reference table

Lowers one or more AST encoded sides in a shared reference environment.

When to use

Use when several AST roots must share identifiers, occurrence counts, recursion, and allocated reference names.

Details

Apply SchemaAST.toType to an AST first to lower its type side instead. The reference policy observes candidates from every root before any representation is emitted.

See

• toRepresentation for a single AST root

Decodes a persisted single-root representation document from JSON.

When to use

Use when reading a representation document from storage or transport before inspecting it or passing it to fromRepresentation.

Gotchas

Invalid documents throw a schema decoding error. Decoding does not reconstruct runtime callbacks.

See

• toJson for encoding a document
• fromRepresentation for reconstructing a runtime schema
• fromJsonMultiDocument for multiple roots sharing references

Decodes a persisted multi-root representation document from JSON.

When to use

Use when reading multiple representation roots that share references before inspecting them or passing them to fromRepresentations.

Gotchas

Invalid documents throw a schema decoding error. Decoding does not reconstruct runtime callbacks.

See

• toJsonMultiDocument for encoding a multi-document
• fromRepresentations for reconstructing runtime schemas
• fromJson for a single root

Projects a live single-root representation document and encodes it as JSON.

When to use

Use when you need a stable JSON value for storage or transport after calling toRepresentation.

Gotchas

Generic annotations that are not JSON are omitted. Invalid persistence identities and unsupported structural values throw an Error containing their representation path.

See

• toRepresentation for constructing the live document
• toJsonMultiDocument for documents with multiple roots

Projects a live multi-root representation document and encodes it as JSON.

When to use

Use when you need one JSON value for multiple live roots that share a reference environment.

Gotchas

The root order and shared reference keys are preserved, while non-JSON generic annotations are omitted.

See

• toRepresentations for constructing the live multi-document
• toJson for a single-root document

The any keyword representation.

A reviver erased only at collection boundaries.

An array or tuple representation.

Auxiliary source artifact emitted while generating schema code.

A bigint representation.

A boolean representation.

A structural check.

A check reviver.

Runtime and TypeScript source generated for one schema.

Generated schema code together with named references and auxiliary artifacts.

A custom opaque declaration.

Reviver for a declaration.

A single representation and its definitions.

A tuple element.

An enum representation.

Details

Enum members are stored as native string or number values. Persistent codecs add an explicit type discriminator when encoding them.

An opaque leaf check.

A non-empty group of checks.

Reviver for a check group.

Reviver for a leaf check.

Options for importing JSON Schema Draft 2020-12 documents.

When to use

Use when you need to configure pattern handling or transform each JSON Schema node before translation.

Details

patterns controls pattern constraints reached during best-effort translation, including pattern, the keys of patternProperties, and patterns nested in propertyNames:

• "error" rejects the document and is the default.
• "ignore" skips the constraint.
• "apply" compiles and enforces the constraint with the runtime's native regular expression engine.

Gotchas

Use patterns: "apply" only for trusted documents because regular expression evaluation may block for an unbounded amount of time. patterns: "ignore" weakens validation by accepting values that the source document may reject. Ignoring patternProperties also skips its value constraints and additionalProperties, because matching keys cannot be determined without evaluating the patterns. onEnter must return a JSON Schema object. Its result is used directly, and exceptions raised by the callback pass through unchanged.

An index signature.

A literal representation.

Details

The live representation stores the native literal value. Persistent codecs add an explicit type discriminator when encoding it.

Multiple representations sharing definitions.

The never keyword representation.

The null keyword representation.

A number representation.

The object keyword representation.

An object representation.

A property signature.

Details

The live representation stores the native property key. Persistent codecs add an explicit type discriminator when encoding it.

Gotchas

Local symbols can be represented while the schema is live, but persistent codecs reject them because they cannot be reconstructed by identity.

A named reference.

Function that chooses whether a representation candidate is emitted as a named reference.

When to use

Use when you need reference allocation based on schema identity, occurrence counts, identifiers, or another application-specific rule.

Details

Return a reference name to extract the candidate, or undefined to keep it inline. The policy is called once per candidate after all occurrences have been counted. The identifier is the resolved identifier for the encoded AST, including an Encoded suffix when an identifier is inherited from the source side of an encoding. If different candidates request the same name, later names receive numeric suffixes in encounter order.

Gotchas

Recursive candidates always require a reference. When the policy returns undefined for one, the generator assigns a synthetic name. Treat the input AST as immutable and keep the policy deterministic.

See

• ToRepresentationOptions for configuring representation generation

Information supplied to a reference policy for one representation candidate.

Named representation definitions.

The structural schema representation.

A typed reviver.

A string representation.

A lazily resolved representation.

A symbol representation.

A template literal representation.

The undefined keyword representation.

A union representation.

A unique global symbol representation.

The unknown keyword representation.

The void keyword representation.

Input and output contracts for code generation annotations.

Input passed to JSON Schema compiler annotations.

Reconstructs a runtime schema from a representation document.

When to use

Use when you have decoded or constructed a document whose declaration and check annotations may require revivers.

Gotchas

Revivers are resolved locally by id; none are installed implicitly. Reviver results are used directly, and exceptions raised by a reviver pass through unchanged.

See

• fromJson for decoding a persisted document
• fromRepresentations for multiple roots sharing references

Reconstructs multiple runtime schemas from a representation multi-document.

When to use

Use when multiple roots must be rebuilt in one shared reference environment.

Gotchas

Only references reachable from a root are revived. Revivers are resolved locally by id; none are installed implicitly.

See

• fromJsonMultiDocument for decoding a persisted multi-document
• fromRepresentation for a single root

Generates TypeScript source for live schema representations and their definitions.

When to use

Use when custom declarations and checks provide toCode callbacks and must be emitted without a central handler registry.

Gotchas

Opaque declarations and leaf checks require toCode callbacks. Callback results are used directly, and exceptions raised by a callback pass through unchanged.

Compiles a live representation document to JSON Schema Draft 2020-12.

When to use

Use when you need JSON Schema output from a representation whose checks carry compiler annotations.

Details

For representation documents whose validation semantics can be expressed exactly in JSON Schema, importing the emitted document with fromJsonSchemaDocument reconstructs a schema that accepts the same JSON values. This is a semantic round-trip guarantee; the emitted document and reconstructed representation may have different shapes.

Gotchas

• Reference allocation is already fixed in the input Document. The inherited referencePolicy option has no effect here; pass it to toRepresentation when creating the document.
• Opaque declarations are represented by an unconstrained JSON Schema and are outside the exact round-trip subset.
• Check callback results are used directly, and exceptions raised by a callback pass through unchanged. Callbacks must treat their input schemas as immutable. Each returned value must be a valid JSON Schema object graph and must not be mutated after the callback returns.
• Local definition references returned by callbacks are resolved together with compiler-generated references.
• Effect decoding may discard excess object properties by default. Use onExcessProperty: "error" when comparing validation semantics with the emitted JSON Schema.

See

• toJsonSchemaMultiDocument for multiple roots sharing definitions

Compiles multiple live representations to a shared JSON Schema Draft 2020-12 document.

When to use

Use when several representation roots must share the same JSON Schema definitions.

Gotchas

• Reference allocation is already fixed in the input MultiDocument. The inherited referencePolicy option has no effect here; pass it to toRepresentations when creating the document.
• Every definition is compiled, including definitions that are not reachable from a root. Check callbacks must treat their input schemas as immutable. Each returned value must be a valid JSON Schema object graph and must not be mutated after the callback returns. Local definition references returned by callbacks are resolved together with compiler-generated references.

See

• toJsonSchemaDocument for a single root

Wraps a single representation document as a multi-document with one root.

When to use

Use when an API such as toCodeDocument requires a MultiDocument.