JsonSchema

Helpers for normalizing and converting JSON Schema and OpenAPI schema documents. Supported inputs include JSON Schema Draft-07, Draft 2020-12, OpenAPI 3.0, and OpenAPI 3.1; conversions normalize through Document<"draft-2020-12"> before emitting another dialect, including JSON Schema Draft-04. The module also defines document types, meta-schema constants, OpenAPI component-key helpers, and $ref resolution utilities.

18 exports Added in v4.0.0 Source

Constants

META_SCHEMA_URI_DRAFT_04

Added in v4.0.0 Source

Represents the $schema meta-schema URI for JSON Schema Draft-04.

When to use

Use when constructing a Draft-04 JSON Schema document and you need a stable value for the root $schema field.

See

META_SCHEMA_URI_DRAFT_07 for the Draft-07 $schema URI

Signature

declare const META_SCHEMA_URI_DRAFT_04: "http://json-schema.org/draft-04/schema#";

META_SCHEMA_URI_DRAFT_07

Added in v4.0.0 Source

Represents the $schema meta-schema URI for JSON Schema Draft-07.

When to use

Use when constructing a Draft-07 JSON Schema document and you need a stable value for the root $schema field.

Details

The exported value is the literal string http://json-schema.org/draft-07/schema#.

See

META_SCHEMA_URI_DRAFT_04 for the Draft-04 $schema URI
META_SCHEMA_URI_DRAFT_2020_12 for the Draft 2020-12 $schema URI

Signature

declare const META_SCHEMA_URI_DRAFT_07: "http://json-schema.org/draft-07/schema#";

META_SCHEMA_URI_DRAFT_2020_12

Added in v4.0.0 Source

Represents the $schema meta-schema URI for JSON Schema Draft 2020-12.

When to use

Use when you need to populate the $schema field while emitting a JSON Schema document that should declare JSON Schema Draft 2020-12.

Details

The exported value is the literal string https://json-schema.org/draft/2020-12/schema.

See

META_SCHEMA_URI_DRAFT_07 for the Draft-07 $schema URI

Signature

declare const META_SCHEMA_URI_DRAFT_2020_12: "https://json-schema.org/draft/2020-12/schema";

Decoding

fromSchemaDraft07

Added in v4.0.0 Source

Parses a raw Draft-07 JSON Schema into a Document<"draft-2020-12">.

When to use

Use when you have a raw JSON Schema object that follows Draft-07 conventions and need the canonical Draft-2020-12 document representation.

Details

This converts Draft-07 tuple syntax (items as array plus additionalItems) to Draft-2020-12 form (prefixItems plus items), rewrites #/definitions/... refs to #/$defs/..., and extracts root-level definitions into the definitions field.

Gotchas

Unsupported keywords, such as if/then/else and $id, are dropped.

Signature

declare function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12">;

fromSchemaDraft2020_12

Added in v4.0.0 Source

Parses a raw Draft-2020-12 JSON Schema into a Document<"draft-2020-12">.

When to use

Use when you already have a raw JSON Schema object in Draft-2020-12 format.

Details

This separates $defs from the root schema into the definitions field. Unlike fromSchemaDraft07, this performs no keyword rewriting.

See

fromSchemaDraft07
fromSchemaOpenApi3_1

Signature

declare function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12">;

fromSchemaOpenApi3_0

Added in v4.0.0 Source

Parses a raw OpenAPI 3.0 JSON Schema into a Document<"draft-2020-12">.

When to use

Use when you need to consume raw JSON Schema objects from an OpenAPI 3.0 specification.

Details

This handles OpenAPI 3.0 extensions, including nullable, singular example, and boolean exclusiveMinimum or exclusiveMaximum. It normalizes the schema to Draft-07 first, then converts to Draft-2020-12 via fromSchemaDraft07.

See

fromSchemaOpenApi3_1
fromSchemaDraft07

Signature

declare function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-12">;

fromSchemaOpenApi3_1

Added in v4.0.0 Source

Parses a raw OpenAPI 3.1 JSON Schema into a Document<"draft-2020-12">.

When to use

Use when you need to consume raw JSON Schema objects from an OpenAPI 3.1 specification.

Details

This rewrites #/components/schemas/... refs to #/$defs/..., then delegates to fromSchemaDraft2020_12.

See

fromSchemaOpenApi3_0
toMultiDocumentOpenApi3_1

Signature

declare function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">;

Encoding

toDocumentDraft04

Added in v4.0.0 Source

Converts a Document<"draft-2020-12"> to a Document<"draft-04">.

When to use

Use when you need to output a canonical JSON Schema document in Draft-04 format.

Details

This rewrites #/$defs/... refs to #/definitions/..., converts tuple syntax, lowers const to enum, converts numeric exclusive bounds to the Draft-04 boolean form, and converts both the root schema and all definitions.

Gotchas

Unsupported Draft-2020-12 and Draft-07 keywords are dropped. For example, propertyNames has no general Draft-04 equivalent and is omitted.

See

toDocumentDraft07 for converting to Draft-07

Signature

declare function toDocumentDraft04(document: Document<"draft-2020-12">): Document<"draft-04">;

toDocumentDraft07

Added in v4.0.0 Source

Converts a Document<"draft-2020-12"> to a Document<"draft-07">.

When to use

Use when you need to output a canonical JSON Schema document in Draft-07 format.

Details

This rewrites #/$defs/... refs to #/definitions/..., converts Draft-2020-12 tuple syntax (prefixItems plus items) to Draft-07 form (items as array plus additionalItems), and converts both the root schema and all definitions.

Gotchas

Unsupported Draft-2020-12 keywords are dropped.

See

fromSchemaDraft07
toDocumentDraft04 for converting to Draft-04
toMultiDocumentOpenApi3_1

Signature

declare function toDocumentDraft07(document: Document<"draft-2020-12">): Document<"draft-07">;

toMultiDocumentOpenApi3_1

Added in v4.0.0 Source

Converts a MultiDocument<"draft-2020-12"> to a MultiDocument<"openapi-3.1">.

When to use

Use when you need to emit an OpenAPI 3.1 multi-document from canonical JSON Schema documents.

Details

This rewrites local #/$defs/... refs to #/components/schemas/... and sanitizes definition keys to match the OpenAPI component key pattern (^[a-zA-Z0-9.\-_]+$) by replacing invalid characters with _. Valid keys are preserved. When sanitized keys collide, the converter appends the first available _1, _2, and subsequent suffix, with allocation independent of definition insertion order. All local refs are updated to use the allocated keys, including refs to paths within a definition.

Gotchas

External refs and local refs outside #/$defs are left unchanged.

See

toDocumentDraft07
MultiDocument

Signature

declare function toMultiDocumentOpenApi3_1(
  multiDocument: MultiDocument<"draft-2020-12">,
): MultiDocument<"openapi-3.1">;

Getters

resolve$ref

Added in v4.0.0 Source

Resolves a $ref string by looking up the last path segment in a definitions map.

When to use

Use when you need to dereference a $ref pointer to get the JSON Schema object it points to.

Details

This only resolves the final segment of the ref path, such as "User" from "#/$defs/User". It returns undefined if the definition is not found.

Gotchas

This function does not follow arbitrary JSON Pointer paths.

See

resolveTopLevel$ref
Definitions

Signature

declare function resolve$ref($ref: string, definitions: Definitions): JsonSchema | undefined;

Models

Definitions interface

Added in v4.0.0 Source

A record of named JSON Schema definitions, keyed by definition name.

When to use

Use as the shared lookup table for named JSON Schema nodes that are referenced from JSON Schema documents.

Details

The map is dialect-neutral. Conversion APIs emit it as $defs, definitions, or components.schemas depending on the target format.

See

Document for a single root schema with definitions
MultiDocument for multiple root schemas sharing definitions
resolve$ref for resolving a $ref against definitions

Signature

interface Definitions extends Record<string, JsonSchema> {
  [key: string]: JsonSchema;
}

Dialect type

Added in v4.0.0 Source

The set of JSON Schema dialects supported by this module.

When to use

Use as the dialect marker for JsonSchema documents when parsing, converting, or emitting schemas across the supported formats.

Details

Supported values are "draft-04" for JSON Schema Draft-04, "draft-07" for JSON Schema Draft-07, "draft-2020-12" for JSON Schema Draft 2020-12 and the canonical internal form, "openapi-3.1" for OpenAPI 3.1, and "openapi-3.0" for OpenAPI 3.0.

See

Document for a single root schema tagged with a dialect
MultiDocument for multiple root schemas tagged with a dialect

Signature

type Dialect = "draft-04" | "draft-07" | "draft-2020-12" | "openapi-3.1" | "openapi-3.0";

Document interface

Added in v4.0.0 Source

A structured container for a single JSON Schema and its associated definitions.

When to use

Use when you need to carry a root schema together with its shared definitions, or when converting between dialects with the from* and to* functions.

Details

The schema field holds the root schema *without* the definitions collection. Root definitions are stored separately in definitions and referenced via #/$defs/<name> for Draft-2020-12, #/definitions/<name> for Draft-04 and Draft-07, and #/components/schemas/<name> for OpenAPI 3.1 and OpenAPI 3.0.

See

MultiDocument
fromSchemaDraft2020_12

Signature

interface Document<D extends Dialect> {
  readonly definitions: Definitions;
  readonly dialect: D;
  readonly schema: JsonSchema;
}

JsonSchema interface

Added in v4.0.0 Source

A plain object representing a single JSON Schema node.

When to use

Use to represent an arbitrary JSON Schema object regardless of dialect.

Details

This is an open record type ([x: string]: unknown) so it can hold any JSON Schema keyword. Most functions in this module accept or return this type.

Signature

interface JsonSchema {
  [x: string]: unknown;
}

MultiDocument interface

Added in v4.0.0 Source

Like Document, but carries multiple root schemas that share a single definitions pool.

When to use

Use when generating several schemas, such as a request body and a response body, that reference the same set of definitions.

Details

The schemas tuple is non-empty and contains at least one element.

See

Document
toMultiDocumentOpenApi3_1

Signature

interface MultiDocument<D extends Dialect> {
  readonly definitions: Definitions;
  readonly dialect: D;
  readonly schemas: readonly [JsonSchema, JsonSchema];
}

Type type

Added in v4.0.0 Source

The JSON Schema primitive type names.

When to use

Use to restrict a JSON Schema type keyword to the supported primitive names.

Signature

type Type = "string" | "number" | "boolean" | "array" | "object" | "null" | "integer";

Transforming

resolveTopLevel$ref

Added in v4.0.0 Source

Resolves a document whose root schema is a top-level $ref.

When to use

Use when you need to dereference a top-level $ref before inspecting the root JSON Schema object's properties directly.

Details

This returns the same object if no change is needed, or a shallow copy with the resolved schema.

See

resolve$ref
Document

Signature

declare function resolveTopLevel$ref(
  document: Document<"draft-2020-12">,
): Document<"draft-2020-12">;