Toolkit Reference

Options Reference

了解 parser 和 generator options 如何影响推断、语义、diagnostics 以及最终输出。

Parser 选项 · json

Document name

output仅作 Web 参考

Sets the root document name used by downstream generators.

默认值: JsonDocument

影响阶段: parse / generate

语义影响: Does not change the data shape; it changes the generated root declaration name.

Diagnostic 影响: Invalid names can be rejected by a target generator's naming validation.

示例

Name the generated document

Use a domain name so generated declarations are meaningful.

Parser strictness

semantics仅作 Web 参考

Controls acceptance policy for JSON decoding and inference.

默认值: strict

影响阶段: parse

语义影响: Strict mode rejects input or options outside the currently supported JSON boundary.

Diagnostic 影响: Invalid JSON or unsupported option values fail explicitly.

取值

Strict (strict)

Use the current strict JSON parsing policy.

Avoids silently accepting invalid or unsupported input.

示例

Strict JSON parsing

Use for predictable input handling.

Numeric inference

inference

Controls whether integer-looking JSON numbers keep integer semantics.

默认值: distinguish

影响阶段: parse

语义影响: Controls the scalar node inferred for JSON numbers.

Diagnostic 影响: Usually silent; downstream targets may report widening when they cannot preserve integers.

取值

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.

示例

Default numeric inference

Preserves integer semantics for later reporting.

{"count": 3}

count: integer

Empty array inference

inference仅作 Web 参考

Defines the element type inferred when an array has no observed elements.

默认值: unknown-array

影响阶段: parse

语义影响: An empty array becomes array<unknown> because no element evidence is available.

Diagnostic 影响: The unknown evidence can be reported as empty-array-element or empty-array-only-field.

取值

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.

示例

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.

默认值: error

影响阶段: parse

语义影响: Chooses between rejecting mixed evidence, preserving it as a union, or widening it to unknown.

Diagnostic 影响: error fails parsing; union may preserve semantics; unknown records a widening explanation.

取值

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.

示例

Preserve mixed alternatives

Use union inference when heterogeneous data is intentional.

[1,"two"]

array<integer | string>

Null handling

semantics仅作 Web 参考

Controls how null values are represented alongside an inferred type.

默认值: nullable

影响阶段: parse

语义影响: Preserves null as explicit nullability rather than treating it as missing data.

Diagnostic 影响: Usually silent when nullability is representable by the target.

取值

Preserve nullability (nullable)

Represent null alongside the observed value type.

Distinguishes explicit null from optional presence.

示例

Preserve null

Explicit null remains distinct from an absent field.

{"name": null}

name: null

Tuple inference

inference实验性

Controls whether heterogeneous arrays are inferred as fixed-position tuples.

默认值: off

影响阶段: parse

语义影响: Changes heterogeneous arrays from homogeneous arrays into ordered tuple positions.

Diagnostic 影响: May create target-specific tuple rendering requirements.

取值

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.

示例

Infer tuple positions

Preserves position-specific types.

[1,"two"]

[integer, string]

Record inference

inference实验性

Controls whether object keys with a shared value type become a dynamic record.

默认值: off

影响阶段: parse

语义影响: Changes a fixed-field object into a Record<string, T> when shared-value evidence supports it.

Diagnostic 影响: May reduce named-field detail while preserving dynamic-key semantics.

取值

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.

示例

Infer a dictionary

Avoids treating sampled dictionary keys as a closed field list.

{"en":"Hello","fr":"Bonjour"}

Record<string, string>

Preserve source information

diagnostics当前不支持仅作 Web 参考

Requests source-location evidence for parser diagnostics.

默认值: false

影响阶段: parse

语义影响: Does not change inferred schema semantics.

Diagnostic 影响: The true value is not implemented yet and is rejected during option validation.

取值

Disabled (false)

Do not attach source-location metadata.

No semantic change.

示例

Default diagnostics

Source-location preservation is currently unavailable.

Parser 选项 · json-schema

Document name

output仅作 Web 参考

Sets the root document name used by downstream generators.

默认值: null

影响阶段: parse / generate

语义影响: Does not change schema meaning; it supplies a stable name for generated declarations.

Diagnostic 影响: Invalid names can be rejected by a target generator.

示例

Name the generated document

Use a domain name for generated output.

Parser strictness

semantics仅作 Web 参考

Controls acceptance policy for JSON Schema input.

默认值: strict

影响阶段: parse

语义影响: Strict mode accepts only the currently supported IR-aligned Draft 2020-12 subset.

Diagnostic 影响: Unsupported features fail explicitly instead of being silently approximated.

取值

Strict (strict)

Reject JSON Schema features that cannot be represented truthfully.

Protects shared IR semantics from unsupported keywords.

示例

Strict JSON Schema parsing

Use for predictable schema conversion.

Preserve source information

diagnostics当前不支持仅作 Web 参考

Requests source-location evidence for parser diagnostics.

默认值: false

影响阶段: parse

语义影响: Does not change schema semantics.

Diagnostic 影响: The true value is not implemented yet and is rejected during option validation.

取值

Disabled (false)

Use the currently supported diagnostic mode.

No semantic change.

示例

Default diagnostics

Source-location preservation is currently unavailable.

Parser 选项 · typescript

Document name

output仅作 Web 参考

Sets the root document name used when the parsed declaration is regenerated.

默认值: TypeScriptDocument

影响阶段: parse / generate

语义影响: Does not change the selected declaration's shape; it controls the shared document name.

Diagnostic 影响: Invalid names can be rejected by a target generator.

示例

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.

默认值: null

影响阶段: parse

语义影响: Changes which declaration is lowered into the shared Shape IR root.

Diagnostic 影响: An omitted entry may trigger implicit selection or an ambiguity failure.

示例

Select a declaration

Use an explicit entry when a file contains multiple exported declarations.

Parser strictness

semantics仅作 Web 参考

Controls acceptance policy for TypeScript syntax.

默认值: strict

影响阶段: parse

语义影响: Strict mode accepts the schema-oriented TypeScript subset only.

Diagnostic 影响: Unsupported type-level programming constructs fail explicitly.

取值

Strict (strict)

Reject constructs that cannot map safely to serializable schema semantics.

Avoids lossy approximation of TypeScript-only behavior.

示例

Strict TypeScript parsing

Use for predictable cross-format conversion.

Preserve source information

diagnostics当前不支持仅作 Web 参考

Requests source-location evidence for parser diagnostics.

默认值: false

影响阶段: parse

语义影响: Does not change inferred schema semantics.

Diagnostic 影响: The true value is not implemented yet and is rejected during option validation.

取值

Disabled (false)

Use the currently supported diagnostic mode.

No semantic change.

示例

Default diagnostics

Source-location preservation is currently unavailable.

Generator 选项 · typescript

Root object style

formatting

Chooses whether a root object is emitted as an interface or a type alias.

默认值: interface

影响阶段: generate

语义影响: Changes TypeScript declaration syntax without changing the represented object shape.

Diagnostic 影响: No semantic loss is expected; naming collisions are validated in either mode.

取值

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.

示例

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.

默认值: smart

影响阶段: generate

语义影响: Changes TypeScript surface syntax without changing array semantics.

Diagnostic 影响: No semantic loss is expected.

取值

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.

示例

Use generic arrays

Useful when a project standardizes on Array<T>.

Naming strategy

extension仅作 Web 参考

Provides custom functions for rendering document, definition, and field names.

默认值: default strategy

影响阶段: generate

语义影响: Changes emitted identifiers and property names, not the underlying schema meaning.

Diagnostic 影响: Invalid names and rendered-name collisions fail generation with structured diagnostics.

示例

Custom naming

Use a custom strategy when generated names must follow a project convention.

Generator 选项 · json-schema

Include schema URI

output

Controls whether the Draft 2020-12 $schema declaration is emitted.

默认值: true

影响阶段: generate

语义影响: Adds an output-document declaration without changing the schema shape.

Diagnostic 影响: No semantic loss is expected.

取值

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.

示例

Emit the draft declaration

Keep the target draft explicit.

Include schema ID

output

Controls whether an $id is emitted for the generated document.

默认值: false

影响阶段: generate

语义影响: Adds document identity metadata without changing validation shape.

Diagnostic 影响: No semantic loss is expected.

取值

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.

示例

Add a schema ID

Give the generated document a stable identity.

Unknown rendering

semantics仅作 Web 参考

Controls how unknown Shape IR nodes are represented in JSON Schema.

默认值: true

影响阶段: generate

语义影响: Unknown is rendered as the widest valid JSON Schema so generation remains truthful.

Diagnostic 影响: Unknown evidence may appear as a widening caveat; only the current true strategy is supported.

取值

Any value (true)

Render unknown as the boolean schema true.

Accepts any JSON value without inventing constraints.

示例

Render unknown safely

Use the widest valid schema for unresolved meaning.

Object additional properties

semantics

Controls whether ordinary object nodes explicitly close additional properties.

默认值: omit

影响阶段: generate

语义影响: Changes whether unlisted object keys are allowed in generated JSON Schema.

Diagnostic 影响: Closing objects is a target policy and can produce a policy caveat.

取值

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.

示例

Close generated objects

Use for strict object validation.

Union composition

semantics

Selects oneOf or anyOf when rendering shared union semantics.

默认值: oneOf

影响阶段: generate

语义影响: Changes the JSON Schema composition keyword used for unions.

Diagnostic 影响: Composition choice is reported as target policy when it changes validation behavior.

取值

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.

示例

Allow overlapping branches

Use anyOf when branch overlap is intentional.

Constraint document

semantics仅作 Web 参考

Supplies portable validation constraints and annotations to the target generator.

默认值: null

影响阶段: generate

语义影响: Adds representable string, numeric, collection, object, and annotation constraints.

Diagnostic 影响: Unsupported or target-specific constraints are reported rather than silently discarded.

示例

Add constraints

Use advanced constraints when validation requirements are available separately from Shape IR.