Schema TransformationAlpha

Toolkit Reference

Options Reference

Understand how parser and generator options affect inference, semantics, diagnostics, and generated output.

Parser options · json

Document name
outputWeb reference only
Sets the root document name used by downstream generators.
Default: JsonDocument
Affected stages: parse / generate
Semantic effect: Does not change the data shape; it changes the generated root declaration name.
Diagnostic effect: Invalid names can be rejected by a target generator's naming validation.
Examples
Name the generated document
Use a domain name so generated declarations are meaningful.
Parser strictness
semanticsWeb reference only
Controls acceptance policy for JSON decoding and inference.
Default: strict
Affected stages: parse
Semantic effect: Strict mode rejects input or options outside the currently supported JSON boundary.
Diagnostic effect: Invalid JSON or unsupported option values fail explicitly.
Values
Strict (strict)
Use the current strict JSON parsing policy.
Avoids silently accepting invalid or unsupported input.
Examples
Strict JSON parsing
Use for predictable input handling.
Numeric inference
inference
Controls whether integer-looking JSON numbers keep integer semantics.
Default: distinguish
Affected stages: parse
Semantic effect: Controls the scalar node inferred for JSON numbers.
Diagnostic effect: Usually silent; downstream targets may report widening when they cannot preserve integers.
Values
Distinguish integers (distinguish)
Infer whole numbers as integer and fractional numbers as number.
Preserves the integer distinction in Shape IR.
Use number for all values (number-only)
Widen integer-looking values to number during inference.
Removes the integer distinction at parse time.
Examples
Default numeric inference
Preserves integer semantics for later reporting.
{"count": 3}
count: integer
Empty array inference
inferenceWeb reference only
Defines the element type inferred when an array has no observed elements.
Default: unknown-array
Affected stages: parse
Semantic effect: An empty array becomes array<unknown> because no element evidence is available.
Diagnostic effect: The unknown evidence can be reported as empty-array-element or empty-array-only-field.
Values
Unknown elements (unknown-array)
Infer an empty array as array<unknown>.
Preserves the fact that the array shape is known but its element type is not.
Examples
Empty array
The result remains honest without inventing an element type.
{"items": []}
items: array<unknown>
Mixed-type handling
inference
Controls how incompatible observed JSON value types are represented.
Default: error
Affected stages: parse
Semantic effect: Chooses between rejecting mixed evidence, preserving it as a union, or widening it to unknown.
Diagnostic effect: error fails parsing; union may preserve semantics; unknown records a widening explanation.
Values
Reject mixed types (error)
Fail when incompatible value types are observed.
Keeps the inferred schema strict and avoids implicit widening.
Preserve a union (union)
Represent incompatible types as a union.
Retains the observed alternatives in Shape IR.
Widen to unknown (unknown)
Represent incompatible types as unknown.
Keeps the conversion moving while explicitly losing the precise alternatives.
Examples
Preserve mixed alternatives
Use union inference when heterogeneous data is intentional.
[1,"two"]
array<integer | string>
Null handling
semanticsWeb reference only
Controls how null values are represented alongside an inferred type.
Default: nullable
Affected stages: parse
Semantic effect: Preserves null as explicit nullability rather than treating it as missing data.
Diagnostic effect: Usually silent when nullability is representable by the target.
Values
Preserve nullability (nullable)
Represent null alongside the observed value type.
Distinguishes explicit null from optional presence.
Examples
Preserve null
Explicit null remains distinct from an absent field.
{"name": null}
name: null
Tuple inference
inferenceExperimental
Controls whether heterogeneous arrays are inferred as fixed-position tuples.
Default: off
Affected stages: parse
Semantic effect: Changes heterogeneous arrays from homogeneous arrays into ordered tuple positions.
Diagnostic effect: May create target-specific tuple rendering requirements.
Values
Disable tuple inference (off)
Infer arrays using homogeneous element semantics.
Preserves the ordinary array model.
Infer heterogeneous tuples (heterogeneous-only)
Promote heterogeneous arrays to fixed-position tuples.
Preserves observed position-specific types and optional trailing positions.
Examples
Infer tuple positions
Preserves position-specific types.
[1,"two"]
[integer, string]
Record inference
inferenceExperimental
Controls whether object keys with a shared value type become a dynamic record.
Default: off
Affected stages: parse
Semantic effect: Changes a fixed-field object into a Record<string, T> when shared-value evidence supports it.
Diagnostic effect: May reduce named-field detail while preserving dynamic-key semantics.
Values
Keep named fields (off)
Treat observed object keys as explicit fields.
Preserves field names and requiredness.
Infer a record (shared-value-type)
Use Record<string, T> when observed values share a type.
Preserves dynamic-key behavior instead of overfitting to sampled keys.
Examples
Infer a dictionary
Avoids treating sampled dictionary keys as a closed field list.
{"en":"Hello","fr":"Bonjour"}
Record<string, string>
Preserve source information
diagnosticsNot supportedWeb reference only
Requests source-location evidence for parser diagnostics.
Default: false
Affected stages: parse
Semantic effect: Does not change inferred schema semantics.
Diagnostic effect: The true value is not implemented yet and is rejected during option validation.
Values
Disabled (false)
Do not attach source-location metadata.
No semantic change.
Examples
Default diagnostics
Source-location preservation is currently unavailable.

Parser options · json-schema

Document name
outputWeb reference only
Sets the root document name used by downstream generators.
Default: null
Affected stages: parse / generate
Semantic effect: Does not change schema meaning; it supplies a stable name for generated declarations.
Diagnostic effect: Invalid names can be rejected by a target generator.
Examples
Name the generated document
Use a domain name for generated output.
Parser strictness
semanticsWeb reference only
Controls acceptance policy for JSON Schema input.
Default: strict
Affected stages: parse
Semantic effect: Strict mode accepts only the currently supported IR-aligned Draft 2020-12 subset.
Diagnostic effect: Unsupported features fail explicitly instead of being silently approximated.
Values
Strict (strict)
Reject JSON Schema features that cannot be represented truthfully.
Protects shared IR semantics from unsupported keywords.
Examples
Strict JSON Schema parsing
Use for predictable schema conversion.
Preserve source information
diagnosticsNot supportedWeb reference only
Requests source-location evidence for parser diagnostics.
Default: false
Affected stages: parse
Semantic effect: Does not change schema semantics.
Diagnostic effect: The true value is not implemented yet and is rejected during option validation.
Values
Disabled (false)
Use the currently supported diagnostic mode.
No semantic change.
Examples
Default diagnostics
Source-location preservation is currently unavailable.

Parser options · typescript

Document name
outputWeb reference only
Sets the root document name used when the parsed declaration is regenerated.
Default: TypeScriptDocument
Affected stages: parse / generate
Semantic effect: Does not change the selected declaration's shape; it controls the shared document name.
Diagnostic effect: Invalid names can be rejected by a target generator.
Examples
Name the generated document
Use a domain name for generated output.
Entry declaration
selection
Selects the exported type or interface used as the document root.
Default: null
Affected stages: parse
Semantic effect: Changes which declaration is lowered into the shared Shape IR root.
Diagnostic effect: An omitted entry may trigger implicit selection or an ambiguity failure.
Examples
Select a declaration
Use an explicit entry when a file contains multiple exported declarations.
Parser strictness
semanticsWeb reference only
Controls acceptance policy for TypeScript syntax.
Default: strict
Affected stages: parse
Semantic effect: Strict mode accepts the schema-oriented TypeScript subset only.
Diagnostic effect: Unsupported type-level programming constructs fail explicitly.
Values
Strict (strict)
Reject constructs that cannot map safely to serializable schema semantics.
Avoids lossy approximation of TypeScript-only behavior.
Examples
Strict TypeScript parsing
Use for predictable cross-format conversion.
Preserve source information
diagnosticsNot supportedWeb reference only
Requests source-location evidence for parser diagnostics.
Default: false
Affected stages: parse
Semantic effect: Does not change inferred schema semantics.
Diagnostic effect: The true value is not implemented yet and is rejected during option validation.
Values
Disabled (false)
Use the currently supported diagnostic mode.
No semantic change.
Examples
Default diagnostics
Source-location preservation is currently unavailable.

Generator options · typescript

Root object style
formatting
Chooses whether a root object is emitted as an interface or a type alias.
Default: interface
Affected stages: generate
Semantic effect: Changes TypeScript declaration syntax without changing the represented object shape.
Diagnostic effect: No semantic loss is expected; naming collisions are validated in either mode.
Values
Interface (interface)
Emit the root object as an exported interface.
Uses interface declaration syntax.
Type alias (type)
Emit the root object as an exported type alias.
Uses type-alias syntax and composes naturally with unions.
Examples
Choose type aliases
Switches only the declaration style of root objects.
Array syntax
formatting
Controls whether arrays use compact bracket syntax or generic Array<T> syntax.
Default: smart
Affected stages: generate
Semantic effect: Changes TypeScript surface syntax without changing array semantics.
Diagnostic effect: No semantic loss is expected.
Values
Smart (smart)
Use compact syntax where it is unambiguous and generic syntax where needed.
Selects readable syntax based on the element type.
Compact (compact)
Prefer T[] syntax.
Uses bracket array syntax where supported.
Generic (generic)
Use Array<T> syntax.
Uses generic array syntax consistently.
Examples
Use generic arrays
Useful when a project standardizes on Array<T>.
Naming strategy
extensionWeb reference only
Provides custom functions for rendering document, definition, and field names.
Default: default strategy
Affected stages: generate
Semantic effect: Changes emitted identifiers and property names, not the underlying schema meaning.
Diagnostic effect: Invalid names and rendered-name collisions fail generation with structured diagnostics.
Examples
Custom naming
Use a custom strategy when generated names must follow a project convention.

Generator options · json-schema

Include schema URI
output
Controls whether the Draft 2020-12 $schema declaration is emitted.
Default: true
Affected stages: generate
Semantic effect: Adds an output-document declaration without changing the schema shape.
Diagnostic effect: No semantic loss is expected.
Values
Include (true)
Emit the Draft 2020-12 schema URI.
Makes the target draft explicit to validators and consumers.
Omit (false)
Do not emit the schema URI.
Leaves draft identification to the consuming context.
Examples
Emit the draft declaration
Keep the target draft explicit.
Include schema ID
output
Controls whether an $id is emitted for the generated document.
Default: false
Affected stages: generate
Semantic effect: Adds document identity metadata without changing validation shape.
Diagnostic effect: No semantic loss is expected.
Values
Include (true)
Emit an $id based on the document name.
Provides an identifier for schema resolution contexts.
Omit (false)
Do not emit an $id.
Keeps the document free of generated identity metadata.
Examples
Add a schema ID
Give the generated document a stable identity.
Unknown rendering
semanticsWeb reference only
Controls how unknown Shape IR nodes are represented in JSON Schema.
Default: true
Affected stages: generate
Semantic effect: Unknown is rendered as the widest valid JSON Schema so generation remains truthful.
Diagnostic effect: Unknown evidence may appear as a widening caveat; only the current true strategy is supported.
Values
Any value (true)
Render unknown as the boolean schema true.
Accepts any JSON value without inventing constraints.
Examples
Render unknown safely
Use the widest valid schema for unresolved meaning.
Object additional properties
semantics
Controls whether ordinary object nodes explicitly close additional properties.
Default: omit
Affected stages: generate
Semantic effect: Changes whether unlisted object keys are allowed in generated JSON Schema.
Diagnostic effect: Closing objects is a target policy and can produce a policy caveat.
Values
Leave unspecified (omit)
Do not emit additionalProperties for ordinary objects.
Keeps ordinary objects open by default.
Close objects (false)
Emit additionalProperties: false for ordinary objects.
Rejects keys not listed in the generated properties.
Examples
Close generated objects
Use for strict object validation.
Union composition
semantics
Selects oneOf or anyOf when rendering shared union semantics.
Default: oneOf
Affected stages: generate
Semantic effect: Changes the JSON Schema composition keyword used for unions.
Diagnostic effect: Composition choice is reported as target policy when it changes validation behavior.
Values
Exactly one (oneOf)
Render unions with oneOf.
Requires exactly one branch to validate.
At least one (anyOf)
Render unions with anyOf.
Requires at least one branch to validate and permits overlap.
Examples
Allow overlapping branches
Use anyOf when branch overlap is intentional.
Constraint document
semanticsWeb reference only
Supplies portable validation constraints and annotations to the target generator.
Default: null
Affected stages: generate
Semantic effect: Adds representable string, numeric, collection, object, and annotation constraints.
Diagnostic effect: Unsupported or target-specific constraints are reported rather than silently discarded.
Examples
Add constraints
Use advanced constraints when validation requirements are available separately from Shape IR.