schema-components 1.12.10 → 1.13.0

package/README.md

@@ -179,6 +179,37 @@ import { SchemaField } from "schema-components/react/SchemaComponent";
 
 When the schema is a Zod schema or typed `as const`, only valid dot-paths like `"address.city"` are accepted. Invalid paths trigger TypeScript errors. Runtime schemas accept any string.
 
+## Spec support
+
+The walker reads canonical Draft 2020-12 JSON Schema. Older drafts and OpenAPI documents are normalised to that form transparently.
+
+| Spec | Detection | Normalisation | Notes |
+|---|---|---|---|
+| JSON Schema Draft 04 | `http://json-schema.org/draft-04/schema#` | `exclusiveMinimum`/`Maximum` boolean → number; `id` left in place | |
+| JSON Schema Draft 06 | `http://json-schema.org/draft-06/schema#` | Pass-through (canonical for `const`, `examples[]`, `$id`, `propertyNames`, `contains`) | |
+| JSON Schema Draft 07 | `http://json-schema.org/draft-07/schema#` | Pass-through (adds `if`/`then`/`else`, `contentEncoding`, `contentMediaType`) | |
+| JSON Schema Draft 2019-09 | `https://json-schema.org/draft/2019-09/schema` | `$recursiveRef` → `$ref`, `$recursiveAnchor` → `$anchor` | Adds `unevaluatedProperties`/`Items`, `dependentSchemas`/`Required` |
+| JSON Schema Draft 2020-12 | `https://json-schema.org/draft/2020-12/schema` (default) | `$dynamicRef` → `$ref`, `$dynamicAnchor` → `$anchor`; tuple form via `prefixItems` | |
+| OpenAPI 2.0 (Swagger) | `swagger: "2.0"` | Full document restructure → OpenAPI 3.1; `definitions` → `components/schemas`; body params → `requestBody`; `formData` → `multipart/form-data`; `collectionFormat` → `style`/`explode` | |
+| OpenAPI 3.0.x | `openapi: "3.0.x"` | `nullable` → `anyOf [T, null]`; `discriminator` mapping → injected `const`; `example` → `examples[]` | Callbacks, links, security schemes preserved |
+| OpenAPI 3.1.x | `openapi: "3.1.x"` | Direct (already Draft 2020-12) | Webhooks, `components/pathItems`, JSON Schema `type` arrays, `examples[]` |
+
+### Documented type-level fallbacks
+
+A few JSON Schema keywords can't be expressed in TypeScript's type system. They are handled at runtime by the walker, but `FromJSONSchema<S>` falls back as follows (each pinned by `tests/type-inference-advanced.test.ts`):
+
+| Keyword | Type-level result | Why |
+|---|---|---|
+| `not` | `unknown` | TypeScript has no type negation |
+| `if` / `then` / `else` | Base schema (conditions ignored) | Requires value-dependent conditional evaluation |
+| `propertyNames` | Ignored | Cannot constrain object key *shape* |
+| `dependentSchemas` / `dependentRequired` | Ignored | Cross-field runtime conditionals |
+| `unevaluatedProperties` / `unevaluatedItems` | Ignored | Requires whole-tree evaluation context |
+| `contains` / `minContains` / `maxContains` | Element type unchanged | Constraint metadata only |
+| `$recursiveRef` | `unknown` | Recursive types not expressible |
+
+Runtime rendering and validation handle each of these correctly; only the static type widens.
+
 ## OpenAPI components
 
 Render API operations with type-safe field overrides:

package/dist/core/adapter.d.mts

@@ -1,4 +1,4 @@
-import { l as JsonObject, m as SchemaMeta } from "../types-BJzEgJdX.mjs";
+import { m as JsonObject, w as SchemaMeta } from "../types-ag2jYLqQ.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;

package/dist/core/adapter.mjs

@@ -1,4 +1,7 @@
 import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import { dereference } from "./ref.mjs";
+import { detectJsonSchemaDraft, detectOpenApiVersion, isSwagger2 } from "./version.mjs";
+import { normaliseJsonSchema as normaliseJsonSchema$1, normaliseOpenApiSchemas } from "./normalise.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -16,7 +19,7 @@ const schemaCache = /* @__PURE__ */ new WeakMap();
 function detectSchemaKind(input) {
 	if (hasProperty(input, "_zod")) return "zod4";
 	if (hasProperty(input, "_def") && !hasProperty(input, "_zod")) return "zod3";
-	if (hasProperty(input, "openapi")) return "openapi";
+	if (hasProperty(input, "openapi") || hasProperty(input, "swagger")) return "openapi";
 	return "jsonSchema";
 }
 /**
@@ -70,21 +73,41 @@ function normaliseZod4(input) {
 	};
 }
 function normaliseJsonSchema(jsonSchema) {
+	const normalised = normaliseJsonSchema$1(jsonSchema, detectJsonSchemaDraft(jsonSchema));
 	return {
-		jsonSchema,
-		rootMeta: extractRootMetaFromJson(jsonSchema),
-		rootDocument: jsonSchema
+		jsonSchema: normalised,
+		rootMeta: extractRootMetaFromJson(normalised),
+		rootDocument: normalised
 	};
 }
 function normaliseZod3() {
 	throw new Error("Zod 3 schemas are not yet supported. Convert to Zod 4 or provide JSON Schema directly.");
 }
+/**
+* Mapping of Swagger 2.0 $ref prefixes to their OpenAPI 3.x equivalents.
+* Used by the adapter to rewrite user-provided ref strings so they
+* resolve correctly against the normalised document.
+*/
+const REF_REWRITES_ADAPTER = [
+	["#/definitions/", "#/components/schemas/"],
+	["#/parameters/", "#/components/parameters/"],
+	["#/responses/", "#/components/responses/"]
+];
 function normaliseOpenApi(doc, ref) {
-	const resolved = resolveOpenApiRef(doc, ref);
+	const version = detectOpenApiVersion(doc);
+	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version) : doc;
+	let rewrittenRef = ref;
+	if (rewrittenRef !== void 0 && version !== void 0 && isSwagger2(version)) {
+		for (const [from, to] of REF_REWRITES_ADAPTER) if (rewrittenRef.startsWith(from)) {
+			rewrittenRef = to + rewrittenRef.slice(from.length);
+			break;
+		}
+	}
+	const resolved = resolveOpenApiRef(normalisedDoc, rewrittenRef);
 	return {
 		jsonSchema: resolved,
 		rootMeta: extractRootMetaFromJson(resolved),
-		rootDocument: doc
+		rootDocument: normalisedDoc
 	};
 }
 function resolveOpenApiRef(doc, ref) {
@@ -120,11 +143,17 @@ function resolveOpenApiRef(doc, ref) {
 		const content = getProperty(requestBody, "content");
 		if (!isObject(content)) throw new Error(`No content for ${ref}`);
 		const json = getProperty(content, "application/json");
-		if (!isObject(json)) throw new Error(`No application/json for ${ref}`);
-		const schema = getProperty(json, "schema");
+		const multipart = getProperty(content, "multipart/form-data");
+		const mediaType = isObject(json) ? json : isObject(multipart) ? multipart : void 0;
+		if (mediaType === void 0) throw new Error(`No content for ${ref}`);
+		const schema = getProperty(mediaType, "schema");
 		if (!isObject(schema)) throw new Error(`Could not resolve request body schema for ${ref}`);
 		return schema;
 	}
+	if (ref.startsWith("#/")) {
+		const resolved = dereference(ref, doc);
+		if (resolved !== void 0) return resolved;
+	}
 	throw new Error(`Unsupported OpenAPI ref format: ${ref}`);
 }
 function extractRootMetaFromJson(jsonSchema) {

package/dist/core/constraints.d.mts

@@ -0,0 +1,16 @@
+import { E as StringConstraints, b as ObjectConstraints, f as FileConstraints, t as ArrayConstraints, v as NumberConstraints } from "../types-ag2jYLqQ.mjs";
+
+//#region src/core/constraints.d.ts
+declare function extractStringConstraints(schema: Record<string, unknown>): StringConstraints;
+declare function extractNumberConstraints(schema: Record<string, unknown>): NumberConstraints;
+declare function extractArrayConstraints(schema: Record<string, unknown>): ArrayConstraints;
+declare function extractObjectConstraints(schema: Record<string, unknown>): ObjectConstraints;
+declare function extractFileConstraints(schema: Record<string, unknown>): FileConstraints;
+/**
+ * Return a copy of the schema with constraint keywords that don't apply
+ * to the given type removed. Meta keywords (description, title, etc.)
+ * and composition keywords are always preserved.
+ */
+declare function stripInapplicableConstraints(schema: Record<string, unknown>, targetType: string): Record<string, unknown>;
+//#endregion
+export { extractArrayConstraints, extractFileConstraints, extractNumberConstraints, extractObjectConstraints, extractStringConstraints, stripInapplicableConstraints };

package/dist/core/constraints.mjs

@@ -0,0 +1,138 @@
+import { isObject } from "./guards.mjs";
+//#region src/core/constraints.ts
+function getString(obj, key) {
+	const value = obj[key];
+	return typeof value === "string" ? value : void 0;
+}
+function getNumber(obj, key) {
+	const value = obj[key];
+	return typeof value === "number" ? value : void 0;
+}
+function getObject(obj, key) {
+	const value = obj[key];
+	return isObject(value) ? value : void 0;
+}
+function extractStringConstraints(schema) {
+	const c = {};
+	const minLength = getNumber(schema, "minLength");
+	if (minLength !== void 0) c.minLength = minLength;
+	const maxLength = getNumber(schema, "maxLength");
+	if (maxLength !== void 0) c.maxLength = maxLength;
+	const pattern = getString(schema, "pattern");
+	if (pattern !== void 0) c.pattern = pattern;
+	const format = getString(schema, "format");
+	if (format !== void 0) c.format = format;
+	const contentEncoding = getString(schema, "contentEncoding");
+	if (contentEncoding !== void 0) c.contentEncoding = contentEncoding;
+	const contentMediaType = getString(schema, "contentMediaType");
+	if (contentMediaType !== void 0) c.contentMediaType = contentMediaType;
+	return c;
+}
+function extractNumberConstraints(schema) {
+	const c = {};
+	const minimum = getNumber(schema, "minimum");
+	if (minimum !== void 0) c.minimum = minimum;
+	const maximum = getNumber(schema, "maximum");
+	if (maximum !== void 0) c.maximum = maximum;
+	const exclusiveMinimum = getNumber(schema, "exclusiveMinimum");
+	if (exclusiveMinimum !== void 0) c.exclusiveMinimum = exclusiveMinimum;
+	const exclusiveMaximum = getNumber(schema, "exclusiveMaximum");
+	if (exclusiveMaximum !== void 0) c.exclusiveMaximum = exclusiveMaximum;
+	const multipleOf = getNumber(schema, "multipleOf");
+	if (multipleOf !== void 0) c.multipleOf = multipleOf;
+	return c;
+}
+function extractArrayConstraints(schema) {
+	const c = {};
+	const minItems = getNumber(schema, "minItems");
+	if (minItems !== void 0) c.minItems = minItems;
+	const maxItems = getNumber(schema, "maxItems");
+	if (maxItems !== void 0) c.maxItems = maxItems;
+	if (schema.uniqueItems === true) c.uniqueItems = true;
+	const contains = getObject(schema, "contains");
+	if (contains !== void 0) c.contains = contains;
+	const minContains = getNumber(schema, "minContains");
+	if (minContains !== void 0) c.minContains = minContains;
+	const maxContains = getNumber(schema, "maxContains");
+	if (maxContains !== void 0) c.maxContains = maxContains;
+	const unevaluatedItems = getObject(schema, "unevaluatedItems");
+	if (unevaluatedItems !== void 0) c.unevaluatedItems = unevaluatedItems;
+	return c;
+}
+function extractObjectConstraints(schema) {
+	const c = {};
+	const minProperties = getNumber(schema, "minProperties");
+	if (minProperties !== void 0) c.minProperties = minProperties;
+	const maxProperties = getNumber(schema, "maxProperties");
+	if (maxProperties !== void 0) c.maxProperties = maxProperties;
+	return c;
+}
+function extractFileConstraints(schema) {
+	const c = {};
+	const contentMediaType = getString(schema, "contentMediaType");
+	if (contentMediaType !== void 0) c.mimeTypes = [contentMediaType];
+	return c;
+}
+/**
+* Constraint keywords that apply only to specific types.
+* Used to strip inapplicable constraints when expanding type arrays.
+*/
+const STRING_CONSTRAINTS = new Set([
+	"minLength",
+	"maxLength",
+	"pattern"
+]);
+const NUMBER_CONSTRAINTS = new Set([
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"multipleOf"
+]);
+const ARRAY_CONSTRAINTS = new Set([
+	"minItems",
+	"maxItems",
+	"uniqueItems",
+	"contains",
+	"minContains",
+	"maxContains"
+]);
+const OBJECT_CONSTRAINTS = new Set(["minProperties", "maxProperties"]);
+const ALL_CONSTRAINTS = new Set([
+	...STRING_CONSTRAINTS,
+	...NUMBER_CONSTRAINTS,
+	...ARRAY_CONSTRAINTS,
+	...OBJECT_CONSTRAINTS
+]);
+/**
+* Return a copy of the schema with constraint keywords that don't apply
+* to the given type removed. Meta keywords (description, title, etc.)
+* and composition keywords are always preserved.
+*/
+function stripInapplicableConstraints(schema, targetType) {
+	let keepForType;
+	switch (targetType) {
+		case "string":
+			keepForType = STRING_CONSTRAINTS;
+			break;
+		case "number":
+		case "integer":
+			keepForType = NUMBER_CONSTRAINTS;
+			break;
+		case "array":
+			keepForType = ARRAY_CONSTRAINTS;
+			break;
+		case "object":
+			keepForType = OBJECT_CONSTRAINTS;
+			break;
+		default: keepForType = /* @__PURE__ */ new Set();
+	}
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) {
+		if (ALL_CONSTRAINTS.has(key) && !keepForType.has(key)) continue;
+		result[key] = value;
+	}
+	return result;
+}
+//#endregion
+export { extractArrayConstraints, extractFileConstraints, extractNumberConstraints, extractObjectConstraints, extractStringConstraints, stripInapplicableConstraints };

package/dist/core/merge.d.mts

@@ -0,0 +1,32 @@
+//#region src/core/merge.d.ts
+/**
+ * Schema merging, nullable detection, and discriminated union detection.
+ *
+ * Used by the walker to handle `allOf`, `anyOf [T, null]`, and
+ * `oneOf` with discriminator properties.
+ */
+/**
+ * Merge multiple JSON Schema objects from allOf into one.
+ * Merges: properties, required, meta fields, and constraints.
+ */
+declare function mergeAllOf(schemas: unknown[]): Record<string, unknown>;
+interface NormalisedAnyOf {
+  inner: Record<string, unknown>;
+  isNullable: boolean;
+}
+/**
+ * Detect `anyOf: [T, { type: "null" }]` → nullable T.
+ * Returns the non-null schema and a nullable flag.
+ */
+declare function normaliseAnyOf(options: unknown[]): NormalisedAnyOf | undefined;
+interface Discriminated {
+  options: Record<string, unknown>[];
+  discriminator: string;
+}
+/**
+ * Detect oneOf where every option is an object with a property
+ * that has a `const` value → discriminated union.
+ */
+declare function detectDiscriminated(options: unknown[]): Discriminated | undefined;
+//#endregion
+export { Discriminated, NormalisedAnyOf, detectDiscriminated, mergeAllOf, normaliseAnyOf };

package/dist/core/merge.mjs

@@ -0,0 +1,96 @@
+import { isObject } from "./guards.mjs";
+//#region src/core/merge.ts
+/**
+* Schema merging, nullable detection, and discriminated union detection.
+*
+* Used by the walker to handle `allOf`, `anyOf [T, null]`, and
+* `oneOf` with discriminator properties.
+*/
+function getString(obj, key) {
+	const value = obj[key];
+	return typeof value === "string" ? value : void 0;
+}
+function getArray(obj, key) {
+	const value = obj[key];
+	return Array.isArray(value) ? value : void 0;
+}
+function getObject(obj, key) {
+	const value = obj[key];
+	return isObject(value) ? value : void 0;
+}
+/**
+* Merge multiple JSON Schema objects from allOf into one.
+* Merges: properties, required, meta fields, and constraints.
+*/
+function mergeAllOf(schemas) {
+	const merged = {};
+	const properties = {};
+	const required = [];
+	for (const entry of schemas) {
+		if (!isObject(entry)) continue;
+		const props = getObject(entry, "properties");
+		if (props !== void 0) for (const [key, value] of Object.entries(props)) properties[key] = value;
+		const req = getArray(entry, "required");
+		if (req !== void 0) {
+			for (const r of req) if (typeof r === "string" && !required.includes(r)) required.push(r);
+		}
+		for (const [key, value] of Object.entries(entry)) {
+			if (key === "properties" || key === "required" || key === "allOf" || key === "type") continue;
+			if (!(key in merged)) merged[key] = value;
+		}
+		if (!("type" in merged)) {
+			const type = getString(entry, "type");
+			if (type !== void 0) merged.type = type;
+		}
+	}
+	if (Object.keys(properties).length > 0) merged.properties = properties;
+	if (required.length > 0) merged.required = required;
+	return merged;
+}
+/**
+* Detect `anyOf: [T, { type: "null" }]` → nullable T.
+* Returns the non-null schema and a nullable flag.
+*/
+function normaliseAnyOf(options) {
+	if (options.length !== 2) return void 0;
+	let inner;
+	let hasNull = false;
+	for (const opt of options) {
+		if (!isObject(opt)) return void 0;
+		if (opt.type === "null") hasNull = true;
+		else inner = opt;
+	}
+	if (!hasNull || inner === void 0) return void 0;
+	return {
+		inner,
+		isNullable: true
+	};
+}
+/**
+* Detect oneOf where every option is an object with a property
+* that has a `const` value → discriminated union.
+*/
+function detectDiscriminated(options) {
+	if (options.length === 0) return void 0;
+	let discriminator;
+	for (const opt of options) {
+		if (!isObject(opt)) return void 0;
+		const props = getObject(opt, "properties");
+		if (props === void 0) return void 0;
+		let foundKey;
+		for (const [key, value] of Object.entries(props)) if (isObject(value) && "const" in value) {
+			foundKey = key;
+			break;
+		}
+		if (foundKey === void 0) return void 0;
+		if (discriminator === void 0) discriminator = foundKey;
+		else if (discriminator !== foundKey) return;
+	}
+	if (discriminator === void 0) return void 0;
+	return {
+		options: options.filter(isObject),
+		discriminator
+	};
+}
+//#endregion
+export { detectDiscriminated, mergeAllOf, normaliseAnyOf };

package/dist/core/normalise.d.mts

@@ -0,0 +1,40 @@
+import { n as OpenApiVersionInfo, t as JsonSchemaDraft } from "../version-CLchheaH.mjs";
+
+//#region src/core/normalise.d.ts
+type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Deep-normalise a JSON Schema object by applying a per-node transform
+ * and recursing into every sub-schema location.
+ */
+declare function deepNormalise(schema: Record<string, unknown>, transform: NodeTransform): Record<string, unknown>;
+/**
+ * Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
+ * to number form.
+ *
+ * In Draft 04:
+ * - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
+ * - `exclusiveMinimum: false` (or absent) + `minimum: 5` → value must be >= 5
+ *
+ * In Draft 06+:
+ * - `exclusiveMinimum: 5` → value must be > 5 (no separate `minimum`)
+ * - `minimum: 5` → value must be >= 5
+ *
+ * The transform converts boolean form to number form so the walker can
+ * treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+ */
+declare function normaliseDraft04Node(node: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Normalise a JSON Schema to canonical Draft 2020-12 form.
+ * Deep-clones the input — the original is never mutated.
+ */
+declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: JsonSchemaDraft): Record<string, unknown>;
+/**
+ * Normalise an OpenAPI document's schemas for walker consumption.
+ * Handles version-specific keyword transformations.
+ *
+ * Returns the same object reference if no normalisation is needed
+ * (OpenAPI 3.1.x), or a deep-cloned normalised copy otherwise.
+ */
+declare function normaliseOpenApiSchemas(doc: Record<string, unknown>, version: OpenApiVersionInfo): Record<string, unknown>;
+//#endregion
+export { NodeTransform, deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/normalise.mjs

@@ -0,0 +1,171 @@
+import { isObject } from "./guards.mjs";
+import { isOpenApi30, isSwagger2 } from "./version.mjs";
+import { deepNormaliseOpenApi30Doc } from "./openapi30.mjs";
+import { normaliseSwagger2Document } from "./swagger2.mjs";
+//#region src/core/normalise.ts
+/**
+* Keys whose values are `Record<string, SubSchema>` — objects where each
+* property is a sub-schema.
+*/
+const OBJECT_SUBSCHEMA_KEYS = new Set([
+	"properties",
+	"patternProperties",
+	"$defs",
+	"definitions",
+	"dependentSchemas"
+]);
+/**
+* Keys whose values are `SubSchema[]` — arrays of sub-schemas.
+*/
+const ARRAY_SUBSCHEMA_KEYS = new Set([
+	"allOf",
+	"anyOf",
+	"oneOf",
+	"prefixItems"
+]);
+/**
+* Keys whose values are a single sub-schema object.
+*/
+const SINGLE_SUBSCHEMA_KEYS = new Set([
+	"additionalProperties",
+	"not",
+	"contains",
+	"propertyNames",
+	"if",
+	"then",
+	"else",
+	"unevaluatedProperties",
+	"unevaluatedItems"
+]);
+/**
+* Normalise each element of an unknown array by applying deepNormalise
+* to object elements and passing others through unchanged.
+*/
+function normaliseArray(items, transform) {
+	const result = [];
+	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform) : item);
+	return result;
+}
+/**
+* Normalise each value of a sub-schema map (e.g. properties, $defs).
+*/
+function normaliseSubSchemaMap(map, transform) {
+	const result = {};
+	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform) : v;
+	return result;
+}
+/**
+* Deep-normalise a JSON Schema object by applying a per-node transform
+* and recursing into every sub-schema location.
+*/
+function deepNormalise(schema, transform) {
+	const node = transform({ ...schema });
+	const result = {};
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMap(value, transform);
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArray(value, transform);
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormalise(value, transform);
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArray(value, transform);
+	else if (isObject(value)) result[key] = deepNormalise(value, transform);
+	else result[key] = value;
+	else result[key] = value;
+	return result;
+}
+/**
+* Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
+* to number form.
+*
+* In Draft 04:
+* - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
+* - `exclusiveMinimum: false` (or absent) + `minimum: 5` → value must be >= 5
+*
+* In Draft 06+:
+* - `exclusiveMinimum: 5` → value must be > 5 (no separate `minimum`)
+* - `minimum: 5` → value must be >= 5
+*
+* The transform converts boolean form to number form so the walker can
+* treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+*/
+function normaliseDraft04Node(node) {
+	if (node.exclusiveMinimum === true && typeof node.minimum === "number") {
+		node.exclusiveMinimum = node.minimum;
+		delete node.minimum;
+	} else if (node.exclusiveMinimum === false) delete node.exclusiveMinimum;
+	if (node.exclusiveMaximum === true && typeof node.maximum === "number") {
+		node.exclusiveMaximum = node.maximum;
+		delete node.maximum;
+	} else if (node.exclusiveMaximum === false) delete node.exclusiveMaximum;
+	if (typeof node.id === "string" && !("$id" in node)) {
+		node.$id = node.id;
+		delete node.id;
+	}
+	if (Array.isArray(node.items) && !("prefixItems" in node)) {
+		node.prefixItems = node.items;
+		delete node.items;
+		if ("additionalItems" in node) {
+			node.items = node.additionalItems;
+			delete node.additionalItems;
+		}
+	}
+	return node;
+}
+/**
+* Normalise Draft 2019-09 `$recursiveRef` to `$ref`.
+*
+* `$recursiveRef` resolves to the nearest `$recursiveAnchor` in the
+* dynamic scope. For rendering, the common pattern is a root
+* `$recursiveAnchor: true` — the normaliser converts
+* `$recursiveRef: "#"` to `$ref: "#"` pointing to the root.
+*
+* If a `$recursiveAnchor` name is given (non-empty string), the ref
+* is converted to `$ref: "#<anchor>"` so the existing $anchor
+* resolution in ref.ts can find it.
+*/
+function normaliseDraft201909Node(node) {
+	if (typeof node.$recursiveRef === "string") {
+		node.$ref = "#";
+		delete node.$recursiveRef;
+	}
+	if (node.$recursiveAnchor === true) {
+		if (typeof node.$anchor !== "string") node.$anchor = "__recursive__";
+		delete node.$recursiveAnchor;
+	}
+	return node;
+}
+function normaliseDynamicRefNode(node) {
+	if (typeof node.$dynamicRef === "string") {
+		node.$ref = node.$dynamicRef;
+		delete node.$dynamicRef;
+	}
+	if (typeof node.$dynamicAnchor === "string") {
+		if (typeof node.$anchor !== "string") node.$anchor = node.$dynamicAnchor;
+		delete node.$dynamicAnchor;
+	}
+	return node;
+}
+/**
+* Normalise a JSON Schema to canonical Draft 2020-12 form.
+* Deep-clones the input — the original is never mutated.
+*/
+function normaliseJsonSchema(schema, draft) {
+	switch (draft) {
+		case "draft-04": return deepNormalise(schema, normaliseDraft04Node);
+		case "draft-2019-09": return deepNormalise(schema, normaliseDraft201909Node);
+		case "draft-2020-12": return deepNormalise(schema, normaliseDynamicRefNode);
+		case "draft-06":
+		case "draft-07": return schema;
+	}
+}
+/**
+* Normalise an OpenAPI document's schemas for walker consumption.
+* Handles version-specific keyword transformations.
+*
+* Returns the same object reference if no normalisation is needed
+* (OpenAPI 3.1.x), or a deep-cloned normalised copy otherwise.
+*/
+function normaliseOpenApiSchemas(doc, version) {
+	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node);
+	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(doc, deepNormalise);
+	return doc;
+}
+//#endregion
+export { deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/openapi30.d.mts

@@ -0,0 +1,38 @@
+import { NodeTransform } from "./normalise.mjs";
+
+//#region src/core/openapi30.d.ts
+/**
+ * Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
+ *
+ * OpenAPI 3.0 uses `nullable: true` instead of the JSON Schema standard
+ * `anyOf: [T, { type: "null" }]`. The walker understands the latter form
+ * natively, so this normaliser converts `nullable` to `anyOf`.
+ *
+ * Only applied when `nullable` is explicitly `true`. `nullable: false` or
+ * absent is the default and requires no transformation.
+ */
+declare function normaliseOpenApi30Node(node: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Normalise OpenAPI 3.0.x `discriminator` keyword by injecting `const`
+ * values into each `oneOf`/`anyOf` option's discriminator property.
+ *
+ * In OpenAPI 3.0, `discriminator` is a sibling of `oneOf`/`anyOf`:
+ *   discriminator: { propertyName: "type" }
+ * The walker detects discriminated unions from `oneOf` + `const` on a
+ * property, so this normaliser injects the `const` values from the
+ * `mapping` or infers them from `$ref` fragment names.
+ */
+declare function normaliseOpenApi30Discriminator(node: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Combined OpenAPI 3.0.x node transform: nullable + discriminator.
+ * Applied to every schema node in an OpenAPI 3.0 document.
+ */
+declare function normaliseOpenApi30Combined(node: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Deep-normalise all schemas in an OpenAPI 3.0.x document.
+ * Walks components/schemas, path operations, parameters, request bodies,
+ * and responses — applying `nullable` normalisation to each schema.
+ */
+declare function deepNormaliseOpenApi30Doc(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };