Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

SchemaRepresentation

Open, compiler-extensible representation of Effect schemas.

147 exports Since v4.0.0 Source

Annotations

CheckRepresentationAnnotation

interface
Since v4.0.0

Open persistence identity and schema dependencies carried by opaque checks.

Signature

interface CheckRepresentationAnnotation<S> extends RepresentationAnnotation {
  readonly schemas?: readonly Array<S>;
}

RepresentationAnnotation

interface
Since v4.0.0

Open persistence identity carried by declarations and opaque checks.

Signature

interface RepresentationAnnotation {
  readonly id: string;
  readonly payload: Json;
}

Configuration

ToRepresentationOptions

interface
Since v4.0.0

Options for generating schema representations.

Signature

interface ToRepresentationOptions {
  readonly referencePolicy?: ReferencePolicy;
}

Constructors

fromJsonSchemaDocument

Since v4.0.0

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. The input is assumed to be a valid Draft 2020-12 document; this function does not validate it against the meta-schema. Instance validation semantics assume JSON-compatible JavaScript values produced by JSON.parse.

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 minLength and maxLength checks count Unicode code points, except that minLength: 1 uses the equivalent UTF-16 non-empty check. integer uses Schema.isInt, which requires safe integers.
  • Applied patterns use Schema.isPattern with the u flag. Patterns that cannot be compiled in Unicode mode are rejected as unsupported translations with their source path.
  • $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

Signature

declare function fromJsonSchemaDocument(document: Document<"draft-2020-12">, options?: FromJsonSchemaOptions): Top

fromJsonSchemaMultiDocument

Since v4.0.0

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. The input is assumed to be a valid Draft 2020-12 document; this function does not validate it against the meta-schema.

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

Signature

declare function fromJsonSchemaMultiDocument(document: MultiDocument<"draft-2020-12">, options?: FromJsonSchemaOptions): readonly [Top, Top]

makeCode

Since v4.0.0

Creates generated runtime and TypeScript source strings for a schema.

Signature

declare const makeCode: (runtime: string, Type: string) => Code

makeReviverDeclaration

Since v4.0.0

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

Signature

declare const makeReviverDeclaration: <P>(id: string, payloadSchema: Schema.Decoder<P>, revive: DeclarationReviver<P>["revive"]) => DeclarationReviver<P>

makeReviverFilter

Since v4.0.0

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

Signature

declare const makeReviverFilter: <P>(id: string, payloadSchema: Schema.Decoder<P>, revive: FilterReviver<P>["revive"]) => FilterReviver<P>

makeReviverFilterGroup

Since v4.0.0

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

Signature

declare const makeReviverFilterGroup: <P>(id: string, payloadSchema: Schema.Decoder<P>, revive: FilterGroupReviver<P>["revive"]) => FilterGroupReviver<P>

toRepresentation

Since v4.0.0

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. TypeScript-only distinctions such as those added by Schema.brand are absent from the AST and cannot be reconstructed from the resulting document.

See

Signature

declare function toRepresentation(ast: AST, options?: ToRepresentationOptions): Document

toRepresentations

Since v4.0.0

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

Signature

declare function toRepresentations(asts: readonly [AST, AST], options?: ToRepresentationOptions): MultiDocument

Decoding

fromJson

Since v4.0.0

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

Signature

declare function fromJson(input: Json): Document

fromJsonMultiDocument

Since v4.0.0

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

Signature

declare function fromJsonMultiDocument(input: Json): MultiDocument

Encoding

toJson

Since v4.0.0

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

Signature

declare function toJson(document: Document): Json

toJsonMultiDocument

Since v4.0.0

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

Signature

declare function toJsonMultiDocument(document: MultiDocument): Json

Models

Any

interface
Since v4.0.0

The any keyword representation.

Signature

interface Any extends Keyword<"Any"> {}

AnyReviver

type
Since v4.0.0

A reviver erased only at collection boundaries.

Signature

type AnyReviver = Reviver<any>

Arrays

interface
Since v4.0.0

An array or tuple representation.

Signature

interface Arrays extends Keyword<"Arrays"> {
  readonly elements: readonly Array<Element>;
  readonly rest: readonly Array<Representation>;
}

Artifact

type
Since v4.0.0

Auxiliary source artifact emitted while generating schema code.

Signature

type Artifact = {
  readonly _tag: "Symbol";
  readonly code: Code;
  readonly identifier: string;
} | {
  readonly _tag: "Enum";
  readonly code: Code;
  readonly identifier: string;
} | {
  readonly _tag: "Import";
  readonly importDeclaration: string;
}

BigInt

interface
Since v4.0.0

A bigint representation.

Signature

interface BigInt extends Keyword<"BigInt"> {}

Boolean

interface
Since v4.0.0

A boolean representation.

Signature

interface Boolean extends Keyword<"Boolean"> {}

Check

type
Since v4.0.0

A structural check.

Signature

type Check = Filter | FilterGroup

CheckReviver

type
Since v4.0.0

A check reviver.

Signature

type CheckReviver<P> = FilterReviver<P> | FilterGroupReviver<P>

Code

interface
Since v4.0.0

Runtime and TypeScript source generated for one schema.

Signature

interface Code {
  readonly runtime: string;
  readonly Type: string;
}

CodeDocument

interface
Since v4.0.0

Generated schema code together with named references and auxiliary artifacts.

Signature

interface CodeDocument {
  readonly artifacts: readonly Array<Artifact>;
  readonly codes: readonly Array<Code>;
  readonly references: {
    readonly nonRecursives: readonly Array<{
      readonly $ref: string;
      readonly code: Code;
    }>;
    readonly recursives: Readonly<Record<string, Code>>;
  };
}

Declaration

interface
Since v4.0.0

A custom opaque declaration.

Signature

interface Declaration {
  readonly _tag: "Declaration";
  readonly annotations?: Annotations;
  readonly checks: readonly Array<Check>;
  readonly representation?: RepresentationAnnotation;
  readonly typeParameters: readonly Array<Representation>;
}

DeclarationReviver

interface
Since v4.0.0

Reviver for a declaration.

Signature

interface DeclarationReviver<P> {
  readonly id: string;
  readonly payloadSchema: Decoder<P>;
  readonly revive: (input: {
    readonly annotations: Annotations | undefined;
    readonly payload: P;
    readonly typeParameters: readonly Array<Top>;
  }) => Top;
}

Document

interface
Since v4.0.0

A single representation and its definitions.

Signature

interface Document {
  readonly references: References;
  readonly representation: Representation;
}

Element

interface
Since v4.0.0

A tuple element.

Signature

interface Element {
  readonly annotations?: Annotations;
  readonly isOptional: boolean;
  readonly type: Representation;
}

Enum

interface
Since v4.0.0

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.

Signature

interface Enum extends Keyword<"Enum"> {
  readonly enums: readonly Array<readonly [string, string | number]>;
}

Filter

interface
Since v4.0.0

An opaque leaf check.

Signature

interface Filter {
  readonly _tag: "Filter";
  readonly aborted: boolean;
  readonly annotations?: Annotations;
  readonly representation?: CheckRepresentationAnnotation<Representation>;
}

FilterGroup

interface
Since v4.0.0

A non-empty group of checks.

Signature

interface FilterGroup {
  readonly _tag: "FilterGroup";
  readonly annotations?: Annotations;
  readonly checks: readonly [Check, Check];
  readonly representation?: CheckRepresentationAnnotation<Representation>;
}

FilterGroupReviver

interface
Since v4.0.0

Reviver for a check group.

Signature

interface FilterGroupReviver<P> {
  readonly id: string;
  readonly payloadSchema: Decoder<P>;
  readonly revive: (input: {
    readonly annotations: Filter | undefined;
    readonly payload: P;
    readonly schemas: readonly Array<Top>;
  }) => FilterGroup<any>;
}

FilterReviver

interface
Since v4.0.0

Reviver for a leaf check.

Signature

interface FilterReviver<P> {
  readonly id: string;
  readonly payloadSchema: Decoder<P>;
  readonly revive: (input: {
    readonly annotations: Filter | undefined;
    readonly payload: P;
    readonly schemas: readonly Array<Top>;
  }) => Filter<any>;
}

FromJsonSchemaOptions

interface
Since v4.0.0

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 in Unicode mode. Patterns that cannot be compiled with the u flag are rejected with their source path.

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. Input documents are assumed to be valid Draft 2020-12 schemas and are not validated against the meta-schema. 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.

Signature

interface FromJsonSchemaOptions {
  readonly onEnter?: (schema: JsonSchema) => JsonSchema;
  readonly patterns?: "error" | "ignore" | "apply";
}

IndexSignature

interface
Since v4.0.0

An index signature.

Signature

interface IndexSignature {
  readonly parameter: Representation;
  readonly type: Representation;
}

Literal

interface
Since v4.0.0

A literal representation.

Details

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

Signature

interface Literal extends Keyword<"Literal"> {
  readonly literal: LiteralValue;
}

MultiDocument

interface
Since v4.0.0

Multiple representations sharing definitions.

Signature

interface MultiDocument {
  readonly references: References;
  readonly representations: readonly [Representation, Representation];
}

Never

interface
Since v4.0.0

The never keyword representation.

Signature

interface Never extends Keyword<"Never"> {}

Null

interface
Since v4.0.0

The null keyword representation.

Signature

interface Null extends Keyword<"Null"> {}

Number

interface
Since v4.0.0

A number representation.

Signature

interface Number extends Keyword<"Number"> {}

ObjectKeyword

interface
Since v4.0.0

The object keyword representation.

Signature

interface ObjectKeyword extends Keyword<"ObjectKeyword"> {}

Objects

interface
Since v4.0.0

An object representation.

Signature

interface Objects extends Keyword<"Objects"> {
  readonly indexSignatures: readonly Array<IndexSignature>;
  readonly propertySignatures: readonly Array<PropertySignature>;
}

PropertySignature

interface
Since v4.0.0

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.

Signature

interface PropertySignature {
  readonly annotations?: Annotations;
  readonly isMutable: boolean;
  readonly isOptional: boolean;
  readonly name: PropertyKey;
  readonly type: Representation;
}

Reference

interface
Since v4.0.0

A named reference.

Signature

interface Reference {
  readonly _tag: "Reference";
  readonly $ref: string;
}

ReferencePolicy

type
Since v4.0.0

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

Signature

type ReferencePolicy = (input: ReferencePolicyInput) => string | undefined

ReferencePolicyInput

interface
Since v4.0.0

Information supplied to a reference policy for one representation candidate.

Signature

interface ReferencePolicyInput {
  readonly ast: AST;
  readonly identifier: string | undefined;
  readonly occurrences: number;
}

References

interface
Since v4.0.0

Named representation definitions.

Signature

interface References {
  [$ref: string]: Representation;
}

Representation

type
Since v4.0.0

The structural schema representation.

Signature

type Representation = Declaration | Reference | Suspend | Null | Undefined | Void | Never | Unknown | Any | String | Number | Boolean | BigInt | Symbol | Literal | UniqueSymbol | ObjectKeyword | Enum | TemplateLiteral | Arrays | Objects | Union

Reviver

type
Since v4.0.0

A typed reviver.

Signature

type Reviver<P> = DeclarationReviver<P> | CheckReviver<P>

String

interface
Since v4.0.0

A string representation.

Signature

interface String extends Keyword<"String"> {}

Suspend

interface
Since v4.0.0

A lazily resolved representation.

Signature

interface Suspend {
  readonly _tag: "Suspend";
  readonly annotations?: Annotations;
  readonly checks: readonly [];
  readonly thunk: Representation;
}

Symbol

interface
Since v4.0.0

A symbol representation.

Signature

interface Symbol extends Keyword<"Symbol"> {}

TemplateLiteral

interface
Since v4.0.0

A template literal representation.

Signature

interface TemplateLiteral extends Keyword<"TemplateLiteral"> {
  readonly parts: readonly Array<Representation>;
}

Undefined

interface
Since v4.0.0

The undefined keyword representation.

Signature

interface Undefined extends Keyword<"Undefined"> {}

Union

interface
Since v4.0.0

A union representation.

Signature

interface Union extends Keyword<"Union"> {
  readonly options?: UnionOptions;
  readonly types: readonly Array<Representation>;
}

UniqueSymbol

interface
Since v4.0.0

A unique symbol representation.

Details

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

Signature

interface UniqueSymbol extends Keyword<"UniqueSymbol"> {
  readonly symbol: symbol;
}

Unknown

interface
Since v4.0.0

The unknown keyword representation.

Signature

interface Unknown extends Keyword<"Unknown"> {}

Void

interface
Since v4.0.0

The void keyword representation.

Signature

interface Void extends Keyword<"Void"> {}

Other

Generation

Since v4.0.0

Input and output contracts for code generation annotations.

ToJsonSchema

Since v4.0.0

Input and output contracts for JSON Schema compiler annotations.

Schemas

BigDecimalReviver

Since v4.0.0

Reviver for persisted Schema.BigDecimal declarations.

When to use

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

See

Signature

declare const BigDecimalReviver: DeclarationReviver<null>

ByteSizeReviver

Since v4.0.0

Reviver for persisted Schema.ByteSize declarations.

Signature

declare const ByteSizeReviver: DeclarationReviver<null>

CauseReasonReviver

Since v4.0.0

Reviver for persisted CauseReason declarations.

When to use

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

See

Signature

declare const CauseReasonReviver: DeclarationReviver<null>

CauseReviver

Since v4.0.0

Reviver for persisted Cause declarations.

When to use

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

See

Signature

declare const CauseReviver: DeclarationReviver<null>

ChunkReviver

Since v4.0.0

Reviver for persisted Schema.Chunk declarations.

When to use

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

See

Signature

declare const ChunkReviver: DeclarationReviver<null>

DateReviver

Since v4.0.0

Reviver for persisted Date declarations.

When to use

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

See

Signature

declare const DateReviver: DeclarationReviver<null>

DateTimeUtcReviver

Since v4.0.0

Reviver for persisted Schema.DateTimeUtc declarations.

When to use

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

See

Signature

declare const DateTimeUtcReviver: DeclarationReviver<null>

DateTimeZonedReviver

Since v4.0.0

Reviver for persisted Schema.DateTimeZoned declarations.

When to use

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

See

Signature

declare const DateTimeZonedReviver: DeclarationReviver<null>

DurationReviver

Since v4.0.0

Reviver for persisted Schema.Duration declarations.

When to use

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

See

Signature

declare const DurationReviver: DeclarationReviver<null>

ErrorInstanceReviver

Since v4.0.0

Reviver for persisted Schema.ErrorInstance declarations.

When to use

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

See

Signature

declare const ErrorInstanceReviver: DeclarationReviver<ErrorRepresentationPayload>

ExitReviver

Since v4.0.0

Reviver for persisted Exit declarations.

When to use

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

See

Signature

declare const ExitReviver: DeclarationReviver<null>

FileReviver

Since v4.0.0

Reviver for persisted File declarations.

When to use

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

See

Signature

declare const FileReviver: DeclarationReviver<null>

FormDataReviver

Since v4.0.0

Reviver for persisted FormData declarations.

When to use

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

See

Signature

declare const FormDataReviver: DeclarationReviver<null>

GraphReviver

Since v4.0.0

Reviver for persisted Schema.Graph declarations.

Signature

declare const GraphReviver: DeclarationReviver<"directed" | "undirected">

HashMapReviver

Since v4.0.0

Reviver for persisted HashMap declarations.

When to use

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

See

Signature

declare const HashMapReviver: DeclarationReviver<null>

HashSetReviver

Since v4.0.0

Reviver for persisted HashSet declarations.

When to use

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

See

Signature

declare const HashSetReviver: DeclarationReviver<null>

JsonReviver

Since v4.0.0

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

Signature

declare const JsonReviver: DeclarationReviver<null>

MutableJsonReviver

Since v4.0.0

Reviver for persisted MutableJson declarations.

When to use

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

See

Signature

declare const MutableJsonReviver: DeclarationReviver<null>

OptionReviver

Since v4.0.0

Reviver for persisted Option declarations.

When to use

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

See

Signature

declare const OptionReviver: DeclarationReviver<null>

ReadonlyMapReviver

Since v4.0.0

Reviver for persisted Schema.ReadonlyMap declarations.

When to use

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

See

Signature

declare const ReadonlyMapReviver: DeclarationReviver<null>

ReadonlySetReviver

Since v4.0.0

Reviver for persisted Schema.ReadonlySet declarations.

When to use

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

See

Signature

declare const ReadonlySetReviver: DeclarationReviver<null>

RedactedReviver

Since v4.0.0

Reviver for persisted Schema.Redacted declarations.

When to use

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

See

Signature

declare const RedactedReviver: DeclarationReviver<RedactedRepresentationPayload>

RegExpReviver

Since v4.0.0

Reviver for persisted RegExp declarations.

When to use

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

See

Signature

declare const RegExpReviver: DeclarationReviver<null>

ResultReviver

Since v4.0.0

Reviver for persisted Schema.Result declarations.

When to use

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

See

Signature

declare const ResultReviver: DeclarationReviver<null>

TimeZoneNamedReviver

Since v4.0.0

Reviver for persisted Schema.TimeZoneNamed declarations.

When to use

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

See

Signature

declare const TimeZoneNamedReviver: DeclarationReviver<null>

TimeZoneOffsetReviver

Since v4.0.0

Reviver for persisted Schema.TimeZoneOffset declarations.

When to use

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

See

Signature

declare const TimeZoneOffsetReviver: DeclarationReviver<null>

TimeZoneReviver

Since v4.0.0

Reviver for persisted Schema.TimeZone declarations.

When to use

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

See

Signature

declare const TimeZoneReviver: DeclarationReviver<null>

Uint8ArrayReviver

Since v4.0.0

Reviver for persisted Uint8Array declarations.

When to use

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

See

Signature

declare const Uint8ArrayReviver: DeclarationReviver<null>

URLReviver

Since v4.0.0

Reviver for persisted URL declarations.

When to use

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

See

Signature

declare const URLReviver: DeclarationReviver<null>

URLSearchParamsReviver

Since v4.0.0

Reviver for persisted URLSearchParams declarations.

When to use

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

See

Signature

declare const URLSearchParamsReviver: DeclarationReviver<null>

Transforming

fromRepresentation

Since v4.0.0

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

Signature

declare function fromRepresentation(document: Document, options: {
  readonly revivers: readonly Array<AnyReviver>;
}): Top

Example Restoring a persisted schema 

import { Schema, SchemaRepresentation } from "effect"


const document = SchemaRepresentation.toRepresentation(Schema.Struct({ name: Schema.String }).ast)
const persisted = SchemaRepresentation.toJson(document)
const restored = SchemaRepresentation.fromJson(persisted)
const schema = SchemaRepresentation.fromRepresentation(restored, { revivers: [] })
const Person = Schema.make<Schema.Codec<{ readonly name: string }>>(schema.ast)


Schema.decodeUnknownSync(Person)({ name: "Ada" }) // => { name: "Ada" }

fromRepresentations

Since v4.0.0

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

Signature

declare function fromRepresentations(document: MultiDocument, options: {
  readonly revivers: readonly Array<AnyReviver>;
}): readonly [Top, Top]

toCodeDocument

Since v4.0.0

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.

Signature

declare function toCodeDocument(document: MultiDocument): CodeDocument

toJsonSchemaDocument

Since v4.0.0

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.

A oneOf union exports as anyOf when any branch contains a known approximation; otherwise it retains oneOf. Approximation propagates through checks, nested schemas, check dependencies, and recursive references. Filters without a toJsonSchema callback and opaque declarations are approximate. Custom callbacks declare their result using ToJsonSchema.CheckOutput.

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, and decoded-object property checks 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 fragment 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.
  • Record keys require an exact translation to a pattern before they can select patternProperties values. Otherwise, "ignore" omits that index-signature constraint. In "error" mode, the compiler emits the generated key schemas under propertyNames and allows unmatched properties to satisfy any candidate index value schema. Exact selectors from other index signatures are retained, even when their value schemas are approximate.

See

Signature

declare function toJsonSchemaDocument(document: Document, options?: ToJsonSchemaOptions): Document<"draft-2020-12">

toJsonSchemaMultiDocument

Since v4.0.0

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.

Details

Uses the same approximation tracking and oneOf and record-key fallbacks as toJsonSchemaDocument, including across shared and recursive 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 fragment 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, and custom check callbacks can differ from Effect validation, as described by toJsonSchemaDocument.

See

Signature

declare function toJsonSchemaMultiDocument(document: MultiDocument, options?: ToJsonSchemaOptions): MultiDocument<"draft-2020-12">

toMultiDocument

Since v4.0.0

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.

Signature

declare function toMultiDocument(document: Document): MultiDocument

Validation

isBase64Reviver

Since v4.0.0

Reviver for persisted isBase64 checks.

When to use

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

See

Signature

declare const isBase64Reviver: FilterReviver<null>

isBase64UrlReviver

Since v4.0.0

Reviver for persisted isBase64Url checks.

When to use

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

See

Signature

declare const isBase64UrlReviver: FilterReviver<null>

isBetweenBigIntReviver

Since v4.0.0

Reviver for persisted isBetweenBigInt checks.

When to use

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

See

Signature

declare const isBetweenBigIntReviver: FilterReviver<{
  readonly exclusiveMaximum?: true;
  readonly exclusiveMinimum?: true;
  readonly maximum: bigint;
  readonly minimum: bigint;
}>

isBetweenCodePointsReviver

Since v4.0.0

Reviver for persisted isBetweenCodePoints checks.

See

Signature

declare const isBetweenCodePointsReviver: FilterReviver<{
  readonly maximum: number;
  readonly minimum: number;
}>

isBetweenDateReviver

Since v4.0.0

Reviver for persisted isBetweenDate checks.

When to use

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

See

Signature

declare const isBetweenDateReviver: FilterReviver<{
  readonly exclusiveMaximum?: true;
  readonly exclusiveMinimum?: true;
  readonly maximum: globalThis.Date;
  readonly minimum: globalThis.Date;
}>

isBetweenLengthReviver

Since v4.0.0

Reviver for persisted isBetweenLength checks.

When to use

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

See

Signature

declare const isBetweenLengthReviver: FilterReviver<{
  readonly maximum: number;
  readonly minimum: number;
}>

isBetweenPropertiesReviver

Since v4.0.0

Reviver for persisted isBetweenProperties checks.

When to use

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

See

Signature

declare const isBetweenPropertiesReviver: FilterReviver<{
  readonly maximum: number;
  readonly minimum: number;
}>

isBetweenReviver

Since v4.0.0

Reviver for persisted isBetween checks.

When to use

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

See

Signature

declare const isBetweenReviver: FilterReviver<{
  readonly exclusiveMaximum?: true;
  readonly exclusiveMinimum?: true;
  readonly maximum: number;
  readonly minimum: number;
}>

isBetweenSizeReviver

Since v4.0.0

Reviver for persisted isBetweenSize checks.

When to use

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

See

Signature

declare const isBetweenSizeReviver: FilterReviver<{
  readonly maximum: number;
  readonly minimum: number;
}>

isCapitalizedReviver

Since v4.0.0

Reviver for persisted isCapitalized checks.

When to use

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

See

Signature

declare const isCapitalizedReviver: FilterReviver<null>

isEndingWithReviver

Since v4.0.0

Reviver for persisted isEndingWith checks.

When to use

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

See

Signature

declare const isEndingWithReviver: FilterReviver<{
  readonly endsWith: string;
}>

isFiniteReviver

Since v4.0.0

Reviver for persisted isFinite checks.

When to use

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

See

Signature

declare const isFiniteReviver: FilterReviver<null>

isGreaterThanBigIntReviver

Since v4.0.0

Reviver for persisted isGreaterThanBigInt checks.

When to use

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

See

Signature

declare const isGreaterThanBigIntReviver: FilterReviver<{
  readonly exclusiveMinimum: bigint;
}>

isGreaterThanDateReviver

Since v4.0.0

Reviver for persisted isGreaterThanDate checks.

When to use

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

See

Signature

declare const isGreaterThanDateReviver: FilterReviver<{
  readonly exclusiveMinimum: globalThis.Date;
}>

isGreaterThanOrEqualToBigIntReviver

Since v4.0.0

Reviver for persisted isGreaterThanOrEqualToBigInt checks.

When to use

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

See

Signature

declare const isGreaterThanOrEqualToBigIntReviver: FilterReviver<{
  readonly minimum: bigint;
}>

isGreaterThanOrEqualToDateReviver

Since v4.0.0

Reviver for persisted isGreaterThanOrEqualToDate checks.

When to use

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

See

Signature

declare const isGreaterThanOrEqualToDateReviver: FilterReviver<{
  readonly minimum: globalThis.Date;
}>

isGreaterThanOrEqualToReviver

Since v4.0.0

Reviver for persisted isGreaterThanOrEqualTo checks.

When to use

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

See

Signature

declare const isGreaterThanOrEqualToReviver: FilterReviver<{
  readonly minimum: number;
}>

isGreaterThanReviver

Since v4.0.0

Reviver for persisted isGreaterThan checks.

When to use

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

See

Signature

declare const isGreaterThanReviver: FilterReviver<{
  readonly exclusiveMinimum: number;
}>

isGUIDReviver

Since v4.0.0

Reviver for persisted isGUID checks.

When to use

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

See

Signature

declare const isGUIDReviver: FilterReviver<null>

isIncludingReviver

Since v4.0.0

Reviver for persisted isIncluding checks.

When to use

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

See

Signature

declare const isIncludingReviver: FilterReviver<{
  readonly includes: string;
}>

isIntReviver

Since v4.0.0

Reviver for persisted isInt checks.

When to use

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

See

Signature

declare const isIntReviver: FilterReviver<null>

isLessThanBigIntReviver

Since v4.0.0

Reviver for persisted isLessThanBigInt checks.

When to use

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

See

Signature

declare const isLessThanBigIntReviver: FilterReviver<{
  readonly exclusiveMaximum: bigint;
}>

isLessThanDateReviver

Since v4.0.0

Reviver for persisted isLessThanDate checks.

When to use

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

See

Signature

declare const isLessThanDateReviver: FilterReviver<{
  readonly exclusiveMaximum: globalThis.Date;
}>

isLessThanOrEqualToBigIntReviver

Since v4.0.0

Reviver for persisted isLessThanOrEqualToBigInt checks.

When to use

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

See

Signature

declare const isLessThanOrEqualToBigIntReviver: FilterReviver<{
  readonly maximum: bigint;
}>

isLessThanOrEqualToDateReviver

Since v4.0.0

Reviver for persisted isLessThanOrEqualToDate checks.

When to use

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

See

Signature

declare const isLessThanOrEqualToDateReviver: FilterReviver<{
  readonly maximum: globalThis.Date;
}>

isLessThanOrEqualToReviver

Since v4.0.0

Reviver for persisted isLessThanOrEqualTo checks.

When to use

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

See

Signature

declare const isLessThanOrEqualToReviver: FilterReviver<{
  readonly maximum: number;
}>

isLessThanReviver

Since v4.0.0

Reviver for persisted isLessThan checks.

When to use

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

See

Signature

declare const isLessThanReviver: FilterReviver<{
  readonly exclusiveMaximum: number;
}>

isLowercasedReviver

Since v4.0.0

Reviver for persisted isLowercased checks.

When to use

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

See

Signature

declare const isLowercasedReviver: FilterReviver<null>

isMaxCodePointsReviver

Since v4.0.0

Reviver for persisted isMaxCodePoints checks.

See

Signature

declare const isMaxCodePointsReviver: FilterReviver<{
  readonly maxCodePoints: number;
}>

isMaxLengthReviver

Since v4.0.0

Reviver for persisted isMaxLength checks.

When to use

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

See

Signature

declare const isMaxLengthReviver: FilterReviver<{
  readonly maxLength: number;
}>

isMaxPropertiesReviver

Since v4.0.0

Reviver for persisted isMaxProperties checks.

When to use

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

See

Signature

declare const isMaxPropertiesReviver: FilterReviver<{
  readonly maxProperties: number;
}>

isMaxSizeReviver

Since v4.0.0

Reviver for persisted isMaxSize checks.

When to use

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

See

Signature

declare const isMaxSizeReviver: FilterReviver<{
  readonly maxSize: number;
}>

isMinCodePointsReviver

Since v4.0.0

Reviver for persisted isMinCodePoints checks.

See

Signature

declare const isMinCodePointsReviver: FilterReviver<{
  readonly minCodePoints: number;
}>

isMinLengthReviver

Since v4.0.0

Reviver for persisted isMinLength checks.

When to use

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

See

Signature

declare const isMinLengthReviver: FilterReviver<{
  readonly minLength: number;
}>

isMinPropertiesReviver

Since v4.0.0

Reviver for persisted isMinProperties checks.

When to use

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

See

Signature

declare const isMinPropertiesReviver: FilterReviver<{
  readonly minProperties: number;
}>

isMinSizeReviver

Since v4.0.0

Reviver for persisted isMinSize checks.

When to use

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

See

Signature

declare const isMinSizeReviver: FilterReviver<{
  readonly minSize: number;
}>

isMultipleOfReviver

Since v4.0.0

Reviver for persisted isMultipleOf checks.

When to use

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

See

Signature

declare const isMultipleOfReviver: FilterReviver<{
  readonly divisor: number;
}>

isPatternReviver

Since v4.0.0

Reviver for persisted isPattern checks.

When to use

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

See

Signature

declare const isPatternReviver: FilterReviver<{
  readonly flags: string;
  readonly source: string;
}>

isPropertyNamesReviver

Since v4.0.0

Reviver for persisted isPropertyNames checks.

When to use

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

See

Signature

declare const isPropertyNamesReviver: FilterReviver<null>

isStartingWithReviver

Since v4.0.0

Reviver for persisted isStartingWith checks.

When to use

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

See

Signature

declare const isStartingWithReviver: FilterReviver<{
  readonly startsWith: string;
}>

isStringBigIntReviver

Since v4.0.0

Reviver for persisted isStringBigInt checks.

When to use

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

See

Signature

declare const isStringBigIntReviver: FilterReviver<null>

isStringFiniteReviver

Since v4.0.0

Reviver for persisted isStringFinite checks.

When to use

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

See

Signature

declare const isStringFiniteReviver: FilterReviver<null>

isStringSymbolReviver

Since v4.0.0

Reviver for persisted isStringSymbol checks.

When to use

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

See

Signature

declare const isStringSymbolReviver: FilterReviver<null>

isTrimmedReviver

Since v4.0.0

Reviver for persisted isTrimmed checks.

When to use

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

See

Signature

declare const isTrimmedReviver: FilterReviver<null>

isULIDReviver

Since v4.0.0

Reviver for persisted isULID checks.

When to use

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

See

Signature

declare const isULIDReviver: FilterReviver<null>

isUncapitalizedReviver

Since v4.0.0

Reviver for persisted isUncapitalized checks.

When to use

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

See

Signature

declare const isUncapitalizedReviver: FilterReviver<null>

isUniqueKeyReviver

Since v4.0.0

Reviver for persisted isUniqueKey checks.

When to use

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

See

Signature

declare const isUniqueKeyReviver: FilterReviver<null>

isUniqueReviver

Since v4.0.0

Reviver for persisted isUnique checks.

When to use

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

See

Signature

declare const isUniqueReviver: FilterReviver<null>

isUppercasedReviver

Since v4.0.0

Reviver for persisted isUppercased checks.

When to use

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

See

Signature

declare const isUppercasedReviver: FilterReviver<null>

isUUIDReviver

Since v4.0.0

Reviver for persisted isUUID checks.

When to use

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

See

Signature

declare const isUUIDReviver: FilterReviver<{
  readonly version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | null;
}>