schema-components 1.12.11 → 1.14.0

package/README.md

@@ -14,6 +14,10 @@ npm install schema-components
 
 Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`.
 
+### Zod version requirement
+
+schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). The library detects Zod 3 inputs and throws a descriptive error rather than silently misbehaving.
+
 ## `SchemaComponent`
 
 The single entry point. Accepts Zod schemas, JSON Schema objects, or OpenAPI documents:
@@ -179,6 +183,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,5 @@
-import { l as JsonObject, m as SchemaMeta } from "../types-BJzEgJdX.mjs";
+import { T as SchemaMeta, m as JsonObject } from "../types-D_5ST7SS.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-DzbZmcLI.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;
@@ -14,6 +15,10 @@ interface NormalisedSchema {
   /** The root document for $ref resolution. */
   rootDocument: JsonObject;
 }
-declare function normaliseSchema(input: unknown, ref?: string): NormalisedSchema;
+interface NormaliseOptions {
+  /** Diagnostics channel for surfacing silent fallbacks. */
+  diagnostics?: DiagnosticsOptions;
+}
+declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
 //#endregion
-export { type JsonObject, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, detectSchemaKind, normaliseSchema };
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, detectSchemaKind, normaliseSchema };

package/dist/core/adapter.mjs

@@ -1,4 +1,8 @@
 import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import { emitDiagnostic } from "./diagnostics.mjs";
+import { dereference } from "./ref.mjs";
+import { detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2 } from "./version.mjs";
+import { i as normaliseOpenApiSchemas, r as normaliseJsonSchema$1 } from "../normalise-tL9FckAk.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -16,7 +20,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";
 }
 /**
@@ -30,7 +34,7 @@ function detectSchemaKind(input) {
 function callToJsonSchema(schema) {
 	return z.toJSONSchema(schema);
 }
-function normaliseSchema(input, ref) {
+function normaliseSchema(input, ref, options) {
 	if (ref === void 0 && isObject(input)) {
 		const cached = schemaCache.get(input);
 		if (cached !== void 0) return cached;
@@ -46,11 +50,11 @@ function normaliseSchema(input, ref) {
 			break;
 		case "openapi":
 			if (!isObject(input)) throw new Error("Invalid OpenAPI document");
-			result = normaliseOpenApi(input, ref);
+			result = normaliseOpenApi(input, ref, options);
 			break;
 		case "jsonSchema":
 			if (!isObject(input)) throw new Error("Invalid JSON Schema");
-			result = normaliseJsonSchema(input);
+			result = normaliseJsonSchema(input, options?.diagnostics);
 			break;
 	}
 	if (ref === void 0 && isObject(input)) schemaCache.set(input, result);
@@ -69,22 +73,56 @@ function normaliseZod4(input) {
 		rootDocument: jsonSchema
 	};
 }
-function normaliseJsonSchema(jsonSchema) {
+function normaliseJsonSchema(jsonSchema, diagnostics) {
+	let draft;
+	if (typeof jsonSchema.$schema !== "string") {
+		const inferred = inferJsonSchemaDraftWithReason(jsonSchema);
+		draft = inferred.draft;
+		emitDiagnostic(diagnostics, {
+			code: "assumed-draft",
+			message: `No $schema present; inferred ${inferred.draft} from keywords (${inferred.inferredFrom})`,
+			pointer: "",
+			detail: {
+				inferredFrom: inferred.inferredFrom,
+				draft: inferred.draft
+			}
+		});
+	} else draft = detectJsonSchemaDraft(jsonSchema);
+	const normalised = normaliseJsonSchema$1(jsonSchema, draft);
 	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.");
+	throw new Error("Zod 3 schemas are not supported. schema-components requires Zod 4. Detected: Zod 3 (has _def without _zod). See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4");
 }
-function normaliseOpenApi(doc, ref) {
-	const resolved = resolveOpenApiRef(doc, ref);
+/**
+* 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, options) {
+	const version = detectOpenApiVersion(doc);
+	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version, options?.diagnostics) : 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 +158,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,17 @@
+import { D as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-D_5ST7SS.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-DzbZmcLI.mjs";
+
+//#region src/core/constraints.d.ts
+declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): 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,150 @@
+import { isObject } from "./guards.mjs";
+import { emitDiagnostic } from "./diagnostics.mjs";
+import { FORMAT_PATTERNS } from "./formats.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, diagnostics, pointer = "") {
+	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 pattern = FORMAT_PATTERNS[format];
+		if (pattern !== void 0) c.formatPattern = pattern;
+		else if (format !== "binary") emitDiagnostic(diagnostics, {
+			code: "unknown-format",
+			message: `Unknown format: ${format}`,
+			pointer,
+			detail: { 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/diagnostics.d.mts

@@ -0,0 +1,2 @@
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-DzbZmcLI.mjs";
+export { Diagnostic, DiagnosticCode, DiagnosticSink, DiagnosticsOptions, appendPointer, emitDiagnostic };

package/dist/core/diagnostics.mjs

@@ -0,0 +1,33 @@
+import { SchemaNormalisationError } from "./errors.mjs";
+//#region src/core/diagnostics.ts
+/**
+* Diagnostics channel for schema-components.
+*
+* Provides a structured way to surface silent fallbacks — unresolved `$ref`,
+* unknown keywords, unknown `format` values, invalid `const` values,
+* unsupported `type` entries, dropped Swagger 2.0 features, external
+* `$ref`, type-negation fallbacks, and conditional fallbacks.
+*
+* Consumers pass a `DiagnosticSink` callback to receive diagnostics
+* as they occur. By default, diagnostics are silently discarded.
+* Setting `strict: true` converts any diagnostic into a thrown
+* `SchemaCompatibilityError`.
+*/
+/**
+* Emit a diagnostic through the configured sink.
+* When `strict` is enabled, throws a `SchemaCompatibilityError` instead.
+*/
+function emitDiagnostic(opts, diagnostic) {
+	if (opts?.strict === true) throw new SchemaNormalisationError(`[${diagnostic.code}] ${diagnostic.message} (at ${diagnostic.pointer})`, diagnostic.detail, "unknown");
+	if (opts?.diagnostics !== void 0) opts.diagnostics(diagnostic);
+}
+/**
+* Append a segment to a JSON Pointer.
+* Encodes `/` and `~` per RFC 6901.
+*/
+function appendPointer(base, segment) {
+	const escaped = segment.replace(/~/g, "~0").replace(/\//g, "~1");
+	return base === "" ? `/${escaped}` : `${base}/${escaped}`;
+}
+//#endregion
+export { appendPointer, emitDiagnostic };

package/dist/core/errors.d.mts

@@ -1,2 +1,2 @@
-import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-DIKI2C78.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-C5zRC2PU.mjs";
 export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/formats.d.mts

@@ -0,0 +1,33 @@
+//#region src/core/formats.d.ts
+/**
+ * Built-in format patterns for JSON Schema string validation.
+ *
+ * Maps standard JSON Schema/OpenAPI `format` values to RegExp patterns
+ * or predicate validators. Used by the constraint extractor to derive
+ * `formatPattern` alongside the existing `format` string, and by the
+ * `validate` helper for runtime format checking.
+ *
+ * Formats that cannot be validated by regex (iri, regex) use predicate
+ * functions instead. `validateFormat` dispatches to whichever is available.
+ *
+ * The user's explicit `pattern` constraint always takes precedence —
+ * `formatPattern` is exposed as a separate field for renderers.
+ */
+/**
+ * A format validator: either a RegExp pattern or a predicate function.
+ */
+type FormatValidator = RegExp | ((value: string) => boolean);
+/**
+ * Recognised JSON Schema formats with their validation patterns.
+ * Unknown formats emit an `unknown-format` diagnostic and skip derivation.
+ */
+declare const FORMAT_PATTERNS: Readonly<Record<string, RegExp>>;
+/**
+ * Validate a string value against format constraints.
+ * Returns `true` when the value matches the format,
+ * `false` when it does not, and `undefined` when the format
+ * is not recognised (no validator available).
+ */
+declare function validateFormat(value: string, format: string): boolean | undefined;
+//#endregion
+export { FORMAT_PATTERNS, FormatValidator, validateFormat };

package/dist/core/formats.mjs

@@ -0,0 +1,67 @@
+//#region src/core/formats.ts
+/**
+* Recognised JSON Schema formats with their validation patterns.
+* Unknown formats emit an `unknown-format` diagnostic and skip derivation.
+*/
+const FORMAT_PATTERNS = {
+	uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+	email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+	"date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/,
+	date: /^\d{4}-\d{2}-\d{2}$/,
+	time: /^\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
+	ipv4: /^(\d{1,3}\.){3}\d{1,3}$/,
+	ipv6: /^([0-9a-f]{0,4}:){2,7}[0-9a-f]{0,4}$/i,
+	uri: /^[a-z][a-z0-9+\-.]*:/i,
+	hostname: /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i,
+	"uri-reference": /^(|[a-z][a-z0-9+\-.]*:|[?#][^\s]*)/i,
+	"uri-template": /^([^{}]|[{][+#/.;?&=,!@|]([a-zA-Z0-9_%.]+)?(:[1-9][0-9]*)?(,[a-zA-Z0-9_%.]+)*[}])*$/,
+	"json-pointer": /^(([/]([^/~]|~0|~1)*)*|)$/,
+	"relative-json-pointer": /^(0|[1-9][0-9]*)(#?([/]([^/~]|~0|~1)*)*)?$/,
+	duration: /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/,
+	"idn-email": /^[^\s@]+@[^\s@]+\.[^\s@]+$/u,
+	"idn-hostname": /^[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?(\.[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?)*$/iu
+};
+/**
+* Format validators that use predicate functions instead of regex.
+* These are checked in `validateFormat` when no regex pattern exists.
+*/
+const PREDICATE_VALIDATORS = {
+	iri: (value) => {
+		try {
+			return new URL(value).protocol.length > 0;
+		} catch {
+			return false;
+		}
+	},
+	"iri-reference": (value) => {
+		if (value === "") return true;
+		try {
+			new URL(value);
+			return true;
+		} catch {
+			return !/\s/.test(value);
+		}
+	},
+	regex: (value) => {
+		try {
+			new RegExp(value);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+/**
+* Validate a string value against format constraints.
+* Returns `true` when the value matches the format,
+* `false` when it does not, and `undefined` when the format
+* is not recognised (no validator available).
+*/
+function validateFormat(value, format) {
+	const pattern = FORMAT_PATTERNS[format];
+	if (pattern !== void 0) return pattern.test(value);
+	const predicate = PREDICATE_VALIDATORS[format];
+	if (predicate !== void 0) return predicate(value);
+}
+//#endregion
+export { FORMAT_PATTERNS, validateFormat };

package/dist/core/merge.d.mts

@@ -0,0 +1,48 @@
+//#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.
+ */
+/**
+ * Annotation keywords that can appear as siblings of `$ref` per
+ * Draft 2020-12 / OpenAPI 3.1. Structural keywords (type, properties,
+ * etc.) are NOT annotation siblings and should not be merged.
+ */
+declare const ANNOTATION_SIBLINGS: ReadonlySet<string>;
+/**
+ * Merge annotation siblings from the referencing node onto the
+ * resolved target's annotations. The referencer wins for annotations.
+ *
+ * Structural keywords on the referencer are NOT merged — per spec,
+ * `$ref` with structural siblings was invalid pre-2019-09.
+ *
+ * Returns a new meta object with the merged annotations.
+ */
+declare function mergeRefSiblings(referencer: Record<string, unknown>, resolvedMeta: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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 { ANNOTATION_SIBLINGS, Discriminated, NormalisedAnyOf, detectDiscriminated, mergeAllOf, mergeRefSiblings, normaliseAnyOf };