SchemaRepresentation
Open, compiler-extensible representation of Effect schemas.
Annotations
CheckRepresentationAnnotation interface
Signature
interface CheckRepresentationAnnotation<S> extends RepresentationAnnotation {
readonly schemas?: readonly Array<S>;
}RepresentationAnnotation interface
Open persistence identity carried by declarations and opaque checks.
Signature
interface RepresentationAnnotation {
readonly id: string;
readonly payload: Json;
}Constructors
fromJsonSchemaDocument
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.
Gotchas
Import is best-effort. Built-in declarations and checks are reconstructed with importer-owned revivers. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
See
fromJsonSchemaMultiDocumentfor multiple roots sharing definitionstoRepresentationfor converting the result to a representation document
Signature
declare function fromJsonSchemaDocument(
document: Document<"draft-2020-12">,
options?: FromJsonSchemaOptions,
): Top;fromJsonSchemaMultiDocument
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. Callback results are used directly, and exceptions raised by a callback pass through unchanged.
See
fromJsonSchemaDocumentfor a single roottoRepresentationsfor converting the returned schema ASTs to a representation document
Signature
declare function fromJsonSchemaMultiDocument(
document: MultiDocument<"draft-2020-12">,
options?: FromJsonSchemaOptions,
): readonly [Top, Top];Creates generated runtime and TypeScript source strings for a schema.
Signature
declare const makeCode: (runtime: string, Type: string) => Code;makeDeclarationReviver
Creates a declaration reviver while inferring its payload type from payloadSchema.
Signature
declare const makeDeclarationReviver: <P>(
id: string,
payloadSchema: Schema.Decoder<P>,
revive: DeclarationReviver<P>["revive"],
) => DeclarationReviver<P>;makeFilterGroupReviver
Creates a filter group reviver while inferring its payload type from payloadSchema.
Signature
declare const makeFilterGroupReviver: <P>(
id: string,
payloadSchema: Schema.Decoder<P>,
revive: FilterGroupReviver<P>["revive"],
) => FilterGroupReviver<P>;makeFilterReviver
Creates a filter reviver while inferring its payload type from payloadSchema.
Signature
declare const makeFilterReviver: <P>(
id: string,
payloadSchema: Schema.Decoder<P>,
revive: FilterReviver<P>["revive"],
) => FilterReviver<P>;toRepresentation
Lowers the encoded side of an AST to a live representation document.
Details
Apply SchemaAST.toType to the AST first to lower its type side instead.
Signature
declare function toRepresentation(ast: AST): Document;toRepresentations
Lowers one or more AST encoded sides in a shared reference environment.
Details
Apply SchemaAST.toType to an AST first to lower its type side instead.
Signature
declare function toRepresentations(asts: readonly [AST, AST]): MultiDocument;Decoding
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
toJsonfor encoding a documentfromRepresentationfor reconstructing a runtime schemafromJsonMultiDocumentfor multiple roots sharing references
Signature
declare function fromJson(input: Json): Document;fromJsonMultiDocument
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
toJsonMultiDocumentfor encoding a multi-documentfromRepresentationsfor reconstructing runtime schemasfromJsonfor a single root
Signature
declare function fromJsonMultiDocument(input: Json): MultiDocument;Encoding
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
toRepresentationfor constructing the live documenttoJsonMultiDocumentfor documents with multiple roots
Signature
declare function toJson(document: Document): Json;toJsonMultiDocument
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
toRepresentationsfor constructing the live multi-documenttoJsonfor a single-root document
Signature
declare function toJsonMultiDocument(document: MultiDocument): Json;Models
The any keyword representation.
Signature
interface Any extends Keyword<"Any"> {}AnyReviver type
A reviver erased only at collection boundaries.
Signature
type AnyReviver = Reviver<any>;An array or tuple representation.
Signature
interface Arrays extends Keyword<"Arrays"> {
readonly elements: readonly Array<Element>;
readonly rest: readonly Array<Representation>;
}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;
};A bigint representation.
Signature
interface BigInt extends Keyword<"BigInt"> {}A boolean representation.
Signature
interface Boolean extends Keyword<"Boolean"> {}A structural check.
Signature
type Check = Filter | FilterGroup;CheckReviver type
A check reviver.
Signature
type CheckReviver<P> = FilterReviver<P> | FilterGroupReviver<P>;Runtime and TypeScript source generated for one schema.
Signature
interface Code {
readonly runtime: string;
readonly Type: string;
}CodeDocument interface
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
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
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;
}A single representation and its definitions.
Signature
interface Document {
readonly references: References;
readonly representation: Representation;
}A tuple element.
Signature
interface Element {
readonly annotations?: Annotations;
readonly isOptional: boolean;
readonly type: Representation;
}An enum representation.
Details
Enum members are stored as native string or 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]>;
}An opaque leaf check.
Signature
interface Filter {
readonly _tag: "Filter";
readonly aborted: boolean;
readonly annotations?: Annotations;
readonly representation?: CheckRepresentationAnnotation<Representation>;
}FilterGroup interface
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
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
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
Options for importing JSON Schema Draft 2020-12 documents.
When to use
Use when each JSON Schema node must be transformed before it is translated.
Gotchas
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;
}IndexSignature interface
An index signature.
Signature
interface IndexSignature {
readonly parameter: Representation;
readonly type: Representation;
}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
Multiple representations sharing definitions.
Signature
interface MultiDocument {
readonly references: References;
readonly representations: readonly [Representation, Representation];
}The never keyword representation.
Signature
interface Never extends Keyword<"Never"> {}The null keyword representation.
Signature
interface Null extends Keyword<"Null"> {}A number representation.
Signature
interface Number extends Keyword<"Number"> {}ObjectKeyword interface
The object keyword representation.
Signature
interface ObjectKeyword extends Keyword<"ObjectKeyword"> {}An object representation.
Signature
interface Objects extends Keyword<"Objects"> {
readonly indexSignatures: readonly Array<IndexSignature>;
readonly propertySignatures: readonly Array<PropertySignature>;
}PropertySignature interface
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;
}A named reference.
Signature
interface Reference {
readonly _tag: "Reference";
readonly $ref: string;
}References interface
Named representation definitions.
Signature
interface References {
[$ref: string]: Representation;
}Representation type
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;A typed reviver.
Signature
type Reviver<P> = DeclarationReviver<P> | CheckReviver<P>;A string representation.
Signature
interface String extends Keyword<"String"> {}A lazily resolved representation.
Signature
interface Suspend {
readonly _tag: "Suspend";
readonly annotations?: Annotations;
readonly checks: readonly [];
readonly thunk: Representation;
}A symbol representation.
Signature
interface Symbol extends Keyword<"Symbol"> {}TemplateLiteral interface
A template literal representation.
Signature
interface TemplateLiteral extends Keyword<"TemplateLiteral"> {
readonly parts: readonly Array<Representation>;
}The undefined keyword representation.
Signature
interface Undefined extends Keyword<"Undefined"> {}A union representation.
Signature
interface Union extends Keyword<"Union"> {
readonly mode: "anyOf" | "oneOf";
readonly types: readonly Array<Representation>;
}UniqueSymbol interface
A unique global symbol representation.
Signature
interface UniqueSymbol extends Keyword<"UniqueSymbol"> {
readonly symbol: symbol;
}The unknown keyword representation.
Signature
interface Unknown extends Keyword<"Unknown"> {}The void keyword representation.
Signature
interface Void extends Keyword<"Void"> {}Other
Generation
Input and output contracts for code generation annotations.
ToJsonSchema
Input passed to JSON Schema compiler annotations.
Transforming
fromRepresentation
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
fromJsonfor decoding a persisted documentfromRepresentationsfor multiple roots sharing references
Signature
declare function fromRepresentation(document: Document, options: {
readonly revivers: readonly Array<AnyReviver>;
}): TopfromRepresentations
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
fromJsonMultiDocumentfor decoding a persisted multi-documentfromRepresentationfor a single root
Signature
declare function fromRepresentations(document: MultiDocument, options: {
readonly revivers: readonly Array<AnyReviver>;
}): readonly [Top, Top]toCodeDocument
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
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.
Gotchas
Opaque declarations are represented by an unconstrained JSON Schema. Check callback results are used directly, and exceptions raised by a callback pass through unchanged.
See
toJsonSchemaMultiDocumentfor multiple roots sharing definitions
Signature
declare function toJsonSchemaDocument(
document: Document,
options?: ToJsonSchemaOptions,
): Document<"draft-2020-12">;toJsonSchemaMultiDocument
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
Every definition is compiled, including definitions that are not reachable from a root.
See
toJsonSchemaDocumentfor a single root
Signature
declare function toJsonSchemaMultiDocument(
document: MultiDocument,
options?: ToJsonSchemaOptions,
): MultiDocument<"draft-2020-12">;toMultiDocument
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;
Open persistence identity and schema dependencies carried by opaque checks.