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

Translates a Draft 2020-12 subset using Effect schemas and built-in checks. Validation follows those checks and the decoder's parse options, so import and re-export do not guarantee identical accepted values or a lossless round trip. Import errors explain the unsupported constraint or reference and include its source path.

Gotchas

• { not: {} } imports as Never. Other uses of not are unsupported.
• When additionalProperties is true, {}, or omitted, additional values use Schema.Json and are retained. Closed objects normally strip excess properties by default; pass onExcessProperty: "error" to reject them. Closed empty objects instead use Schema.Record(Schema.String, Schema.Never) and reject string-keyed entries regardless of that option. Object keyword scopes still constrain declared properties in intersections. Combinations requiring index signatures that exclude explicit properties or patterned keys are rejected with an explanation of the limitation.
• Property count and name checks run on the decoded object, after excess properties have been stripped.
• String length checks count UTF-16 code units. integer uses Schema.isInt, which requires safe integers. Applied patterns use Schema.isPattern without adding a Unicode flag.
• $dynamicRef, contains, dependentRequired, dependentSchemas, active if / then / else, unevaluatedItems, and unevaluatedProperties are rejected with an error identifying the unsupported keyword. 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 are rejected. Only strings, numbers, booleans, and null are supported.
• 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, are rejected.
• 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 are rejected with the supported reference format. Missing definitions are reported by name. References reached inside nested schema resources introduced by $id are rejected instead of resolved against the top-level definitions.
• 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 skip them. Ignoring patterns can both admit invalid values and reject valid values when oneOf branches start overlapping.
• onEnter results replace the corresponding input nodes before translation.
• 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.

Details

Uses the same best-effort translation, built-in checks, and excess-property behavior as fromJsonSchemaDocument.

Gotchas

• Only definitions reachable from a root are translated.
• Unsupported standard validation and applicator keywords are rejected with an error identifying the keyword. Unknown extension keywords are ignored and their semantics are not enforced.
• Objects and arrays used as const values or enum members are rejected. Only strings, numbers, booleans, and null are supported.
• 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, are rejected.
• 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 are rejected with the supported reference format. Missing definitions are reported by name. References reached inside nested schema resources introduced by $id are rejected instead of resolved against the top-level definitions.
• Pattern constraints reached during translation cause an error by default. Use patterns: "apply" only for trusted documents, or patterns: "ignore" to skip them. Ignoring patterns can both admit invalid values and reject valid values when oneOf branches start overlapping.
• 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 reviver while inferring its payload type from payloadSchema.

Creates a filter group 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 finite 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" can admit values the source rejects, but can also reject previously valid values inside oneOf when removing constraints makes multiple branches match. 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 symbol representation.

Details

Globally registered symbols have an exact JSON string representation. Local symbols have no JSON representation.

The unknown keyword representation.

The void keyword representation.

Input and output contracts for code generation annotations.

Input passed to JSON Schema compiler annotations.

Reviver for persisted Schema.BigDecimal declarations.

When to use

Use when reconstructing documents that may contain the Schema.BigDecimal schema.

See

• Schema.BigDecimal for the corresponding schema

Reviver for persisted Schema.ByteSize declarations.

Reviver for persisted CauseReason declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.CauseReason.

See

• Schema.CauseReason for creating the corresponding schema

Reviver for persisted Cause declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Cause.

See

• Schema.Cause for creating the corresponding schema

Reviver for persisted Schema.Chunk declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Chunk.

See

• Schema.Chunk for creating the corresponding schema

Reviver for persisted Date declarations.

When to use

Use when reconstructing documents that may contain the Schema.Date schema.

See

• Schema.Date for the corresponding schema

Reviver for persisted Schema.DateTimeUtc declarations.

When to use

Use when reconstructing documents that may contain the Schema.DateTimeUtc schema.

See

• Schema.DateTimeUtc for the corresponding schema

Reviver for persisted Schema.DateTimeZoned declarations.

When to use

Use when reconstructing documents that may contain the Schema.DateTimeZoned schema.

See

• Schema.DateTimeZoned for the corresponding schema

Reviver for persisted Schema.Duration declarations.

When to use

Use when reconstructing documents that may contain the Schema.Duration schema.

See

• Schema.Duration for the corresponding schema

Reviver for persisted Schema.ErrorInstance declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.ErrorInstance.

See

• Schema.ErrorInstance for creating the corresponding schema

Reviver for persisted Exit declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Exit.

See

• Schema.Exit for creating the corresponding schema

Reviver for persisted File declarations.

When to use

Use when reconstructing documents that may contain the Schema.File schema.

See

• Schema.File for the corresponding schema

Reviver for persisted FormData declarations.

When to use

Use when reconstructing documents that may contain the Schema.FormData schema.

See

• Schema.FormData for the corresponding schema

Reviver for persisted Schema.Graph declarations.

Reviver for persisted HashMap declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.HashMap.

See

• Schema.HashMap for creating the corresponding schema

Reviver for persisted HashSet declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.HashSet.

See

• Schema.HashSet for creating the corresponding schema

Reviver for persisted Json declarations.

When to use

Use when reconstructing documents that may contain the Schema.Json schema.

See

• Schema.Json for the corresponding immutable JSON schema

Reviver for persisted MutableJson declarations.

When to use

Use when reconstructing documents that may contain the Schema.MutableJson schema.

See

• Schema.MutableJson for the corresponding mutable JSON schema

Reviver for persisted Option declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Option.

See

• Schema.Option for creating the corresponding schema

Reviver for persisted Schema.ReadonlyMap declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.ReadonlyMap.

See

• Schema.ReadonlyMap for creating the corresponding schema

Reviver for persisted Schema.ReadonlySet declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.ReadonlySet.

See

• Schema.ReadonlySet for creating the corresponding schema

Reviver for persisted Schema.Redacted declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Redacted.

See

• Schema.Redacted for creating the corresponding schema

Reviver for persisted RegExp declarations.

When to use

Use when reconstructing documents that may contain the Schema.RegExp schema.

See

• Schema.RegExp for the corresponding schema

Reviver for persisted Schema.Result declarations.

When to use

Use when reconstructing documents that may contain schemas created by Schema.Result.

See

• Schema.Result for creating the corresponding schema

Reviver for persisted Schema.TimeZoneNamed declarations.

When to use

Use when reconstructing documents that may contain the Schema.TimeZoneNamed schema.

See

• Schema.TimeZoneNamed for the corresponding schema

Reviver for persisted Schema.TimeZoneOffset declarations.

When to use

Use when reconstructing documents that may contain the Schema.TimeZoneOffset schema.

See

• Schema.TimeZoneOffset for the corresponding schema

Reviver for persisted Schema.TimeZone declarations.

When to use

Use when reconstructing documents that may contain the Schema.TimeZone schema.

See

• Schema.TimeZone for the corresponding schema

Reviver for persisted Uint8Array declarations.

When to use

Use when reconstructing documents that may contain the Schema.Uint8Array schema.

See

• Schema.Uint8Array for the corresponding schema

Reviver for persisted URL declarations.

When to use

Use when reconstructing documents that may contain the Schema.URL schema.

See

• Schema.URL for the corresponding schema

Reviver for persisted URLSearchParams declarations.

When to use

Use when reconstructing documents that may contain the Schema.URLSearchParams schema.

See

• Schema.URLSearchParams for the corresponding schema

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

The generated document is intended for preliminary validation. JSON Schema and Effect checks do not always have identical semantics, so the Effect decoder remains the final authority. Passing JSON Schema validation does not guarantee that Effect decoding will succeed.

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.
• String length, RegExp flags, decoded-object property checks, and oneOf can differ from Effect validation.
• Opaque declarations are represented by an unconstrained JSON Schema.
• 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. The callback author is responsible for the emitted semantics.
• Local definition references returned by callbacks are resolved together with compiler-generated references. Invalid JSON Pointer URI fragments throw an Error.
• The default onExcessProperty: "ignore" matches the decoder default. Use onExcessProperty: "error" in both places when a closed object contract is required.

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. Invalid JSON Pointer URI fragments throw an Error.
• String length, RegExp flags, decoded-object property checks, oneOf, and custom check callbacks can differ from Effect validation, as described by toJsonSchemaDocument.

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.

Reviver for persisted isBase64 checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isBase64.

See

• Schema.isBase64 for creating the corresponding check

Reviver for persisted isBase64Url checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isBase64Url.

See

• Schema.isBase64Url for creating the corresponding check

Reviver for persisted isBetweenBigInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isBetweenBigInt.

See

• Schema.isBetweenBigInt for creating the corresponding check

Reviver for persisted isBetweenDate checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isBetweenDate.

See

• Schema.isBetweenDate for creating the corresponding check

Reviver for persisted isBetween checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isBetween.

See

• Schema.isBetween for creating the corresponding check

Reviver for persisted isCapitalized checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isCapitalized.

See

• Schema.isCapitalized for creating the corresponding check

Reviver for persisted isEndsWith checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isEndsWith.

See

• Schema.isEndsWith for creating the corresponding check

Reviver for persisted isFinite checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isFinite.

See

• Schema.isFinite for creating the corresponding check

Reviver for persisted isGreaterThanBigInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThanBigInt.

See

• Schema.isGreaterThanBigInt for creating the corresponding check

Reviver for persisted isGreaterThanDate checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThanDate.

See

• Schema.isGreaterThanDate for creating the corresponding check

Reviver for persisted isGreaterThanOrEqualToBigInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThanOrEqualToBigInt.

See

• Schema.isGreaterThanOrEqualToBigInt for creating the corresponding check

Reviver for persisted isGreaterThanOrEqualToDate checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThanOrEqualToDate.

See

• Schema.isGreaterThanOrEqualToDate for creating the corresponding check

Reviver for persisted isGreaterThanOrEqualTo checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThanOrEqualTo.

See

• Schema.isGreaterThanOrEqualTo for creating the corresponding check

Reviver for persisted isGreaterThan checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGreaterThan.

See

• Schema.isGreaterThan for creating the corresponding check

Reviver for persisted isGUID checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isGUID.

See

• Schema.isGUID for creating the corresponding check

Reviver for persisted isIncludes checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isIncludes.

See

• Schema.isIncludes for creating the corresponding check

Reviver for persisted isInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isInt.

See

• Schema.isInt for creating the corresponding check

Reviver for persisted isLengthBetween checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLengthBetween.

See

• Schema.isLengthBetween for creating the corresponding check

Reviver for persisted isLessThanBigInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThanBigInt.

See

• Schema.isLessThanBigInt for creating the corresponding check

Reviver for persisted isLessThanDate checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThanDate.

See

• Schema.isLessThanDate for creating the corresponding check

Reviver for persisted isLessThanOrEqualToBigInt checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThanOrEqualToBigInt.

See

• Schema.isLessThanOrEqualToBigInt for creating the corresponding check

Reviver for persisted isLessThanOrEqualToDate checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThanOrEqualToDate.

See

• Schema.isLessThanOrEqualToDate for creating the corresponding check

Reviver for persisted isLessThanOrEqualTo checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThanOrEqualTo.

See

• Schema.isLessThanOrEqualTo for creating the corresponding check

Reviver for persisted isLessThan checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLessThan.

See

• Schema.isLessThan for creating the corresponding check

Reviver for persisted isLowercased checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isLowercased.

See

• Schema.isLowercased for creating the corresponding check

Reviver for persisted isMaxLength checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMaxLength.

See

• Schema.isMaxLength for creating the corresponding check

Reviver for persisted isMaxProperties checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMaxProperties.

See

• Schema.isMaxProperties for creating the corresponding check

Reviver for persisted isMaxSize checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMaxSize.

See

• Schema.isMaxSize for creating the corresponding check

Reviver for persisted isMinLength checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMinLength.

See

• Schema.isMinLength for creating the corresponding check

Reviver for persisted isMinProperties checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMinProperties.

See

• Schema.isMinProperties for creating the corresponding check

Reviver for persisted isMinSize checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMinSize.

See

• Schema.isMinSize for creating the corresponding check

Reviver for persisted isMultipleOf checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isMultipleOf.

See

• Schema.isMultipleOf for creating the corresponding check

Reviver for persisted isPattern checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isPattern.

See

• Schema.isPattern for creating the corresponding check

Reviver for persisted isPropertiesLengthBetween checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isPropertiesLengthBetween.

See

• Schema.isPropertiesLengthBetween for creating the corresponding check

Reviver for persisted isPropertyNames checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isPropertyNames.

See

• Schema.isPropertyNames for creating the corresponding check

Reviver for persisted isSizeBetween checks.

When to use

Use when reconstructing documents that may contain checks created by Schema.isSizeBetween.

See

• Schema.isSizeBetween for creating the corresponding check