schema-components 1.19.0 → 1.21.0

package/dist/{normalise-C0ofw3W6.mjs → normalise-DaSrnr8g.mjs}

@@ -1,6 +1,6 @@
 import { isObject } from "./core/guards.mjs";
 import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
-import { isOpenApi30, isSwagger2 } from "./core/version.mjs";
+import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./core/version.mjs";
 //#region src/core/openapi30.ts
 /**
 * OpenAPI 3.0.x schema normalisation.
@@ -117,6 +117,260 @@ function normaliseOpenApi30Discriminator(node) {
 	return node;
 }
 /**
+* Returns the schema name a `$ref` points at when it targets
+* `#/components/schemas/<Name>`, or `undefined` otherwise.
+*
+* The walker only resolves intra-document refs and other allOf-base
+* patterns; refs into `definitions` (Swagger 2.0) are already rewritten
+* before this stage.
+*/
+function componentSchemaName(ref) {
+	if (typeof ref !== "string") return void 0;
+	if (!ref.startsWith("#/components/schemas/")) return void 0;
+	const name = ref.slice(21);
+	return name.length > 0 ? name : void 0;
+}
+/**
+* Find every immediate `$ref` that an `allOf` array contains pointing
+* back at a `components/schemas/<Name>` entry. Used to discover
+* "Cat extends Pet"-style inheritance — the subtype's `allOf` lists
+* the base by `$ref` alongside its own local fields.
+*/
+function listAllOfBaseRefs(schema) {
+	const allOf = schema.allOf;
+	if (!Array.isArray(allOf)) return [];
+	const result = [];
+	for (const entry of allOf) {
+		if (!isObject(entry)) continue;
+		const name = componentSchemaName(entry.$ref);
+		if (name !== void 0) result.push(name);
+	}
+	return result;
+}
+/**
+* Collect discriminator subtypes for a base schema. Entries come from:
+*
+* 1. The base's `discriminator.mapping` (explicit author intent — the
+*    mapping key supplies the `const` value, the ref names the subtype).
+* 2. Component schemas whose `allOf` lists this base by `$ref` and
+*    were not already named in the mapping. The `const` value defaults
+*    to the subtype's component name.
+*
+* Returned in deterministic order: mapping entries first (preserving
+* authored order), then implicit subtypes alphabetically.
+*/
+function collectDiscriminatorSubtypes(baseName, discriminator, componentSchemas) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	const mapping = isObject(discriminator.mapping) ? discriminator.mapping : void 0;
+	if (mapping !== void 0) for (const [constValue, ref] of Object.entries(mapping)) {
+		const name = componentSchemaName(ref);
+		if (name === void 0) continue;
+		if (!isObject(componentSchemas[name])) continue;
+		if (seen.has(name)) continue;
+		seen.add(name);
+		result.push({
+			name,
+			constValue
+		});
+	}
+	const implicitNames = [];
+	for (const [name, schema] of Object.entries(componentSchemas)) {
+		if (!isObject(schema)) continue;
+		if (seen.has(name)) continue;
+		if (!listAllOfBaseRefs(schema).includes(baseName)) continue;
+		implicitNames.push(name);
+	}
+	implicitNames.sort();
+	for (const name of implicitNames) {
+		result.push({
+			name,
+			constValue: name
+		});
+		seen.add(name);
+	}
+	return result;
+}
+/**
+* Inject the discriminator `const` on a subtype schema in-place.
+*
+* When the subtype already declares a matching const we leave it
+* alone. Otherwise the const is added in whichever location the walker
+* will actually observe:
+*
+* - Subtype declares `allOf`: append a new `allOf` entry carrying just
+*   `{ properties: { [propertyName]: { const } } }`. The walker's
+*   `mergeAllOf` merges every entry's `properties` into the resolved
+*   schema, so the const propagates through to the merged result. A
+*   top-level `properties` sibling of `allOf` would be ignored by the
+*   merge.
+* - Subtype does not declare `allOf`: extend the top-level `properties`
+*   block — the walker reads this directly.
+*/
+function injectSubtypeConst(subtype, propertyName, constValue) {
+	if (subtypeAlreadyDeclaresConst(subtype, propertyName)) return;
+	const constEntry = { properties: { [propertyName]: { const: constValue } } };
+	if (Array.isArray(subtype.allOf)) {
+		subtype.allOf = [...subtype.allOf, constEntry];
+		return;
+	}
+	const existingProps = isObject(subtype.properties) ? { ...subtype.properties } : {};
+	const existingDisc = existingProps[propertyName];
+	existingProps[propertyName] = {
+		...isObject(existingDisc) ? existingDisc : {},
+		const: constValue
+	};
+	subtype.properties = existingProps;
+}
+/**
+* Check whether a subtype (or any of its `allOf` entries) already
+* carries a `const` for the discriminator property. Used to avoid
+* overwriting an author-supplied const.
+*/
+function subtypeAlreadyDeclaresConst(subtype, propertyName) {
+	if (hasConstProp(subtype.properties, propertyName)) return true;
+	if (Array.isArray(subtype.allOf)) for (const entry of subtype.allOf) {
+		if (!isObject(entry)) continue;
+		if (hasConstProp(entry.properties, propertyName)) return true;
+	}
+	return false;
+}
+function hasConstProp(properties, propertyName) {
+	if (!isObject(properties)) return false;
+	const prop = properties[propertyName];
+	return isObject(prop) && "const" in prop;
+}
+/**
+* Strip every `$ref` entry in a subtype's `allOf` that targets the
+* discriminator base. The base's own schema content (properties,
+* required, type) is replicated into a synthesised `allOf` entry so
+* the subtype remains structurally complete — without this the base's
+* synthesised `oneOf` would cycle through the subtype's `$ref`s on
+* every walk (Dog → Pet.oneOf → Dog → ...).
+*/
+function rewriteSubtypeAllOf(subtype, baseName, baseInherited) {
+	const allOf = subtype.allOf;
+	if (!Array.isArray(allOf)) return;
+	const baseRefPrefix = `#/components/schemas/${baseName}`;
+	const rewritten = [];
+	let removedBaseRef = false;
+	for (const entry of allOf) {
+		if (isObject(entry) && typeof entry.$ref === "string" && entry.$ref === baseRefPrefix) {
+			removedBaseRef = true;
+			continue;
+		}
+		rewritten.push(entry);
+	}
+	if (!removedBaseRef) return;
+	subtype.allOf = [baseInherited, ...rewritten];
+}
+/**
+* Capture the "inheritable" portion of a base schema before rewriting:
+* `properties`, `required`, `type`, and any other constraint that
+* subtypes used to inherit through `$ref`. The discriminator keyword
+* and the synthesised `oneOf` are intentionally excluded — subtypes
+* never inherited those and including them would re-introduce the
+* Pet → Dog → Pet cycle.
+*/
+function captureBaseInherited(base) {
+	const inherited = {};
+	for (const [key, value] of Object.entries(base)) {
+		if (key === "discriminator") continue;
+		if (key === "oneOf") continue;
+		if (key === "anyOf") continue;
+		inherited[key] = value;
+	}
+	return inherited;
+}
+/**
+* Build an inline `oneOf` option that targets a subtype via `$ref` and
+* carries the discriminator property's `const` at the option's top
+* level. The const sibling is what makes `detectDiscriminated` classify
+* the parent `oneOf` as a discriminated union — it inspects each
+* option's literal `properties`, not the resolved schema.
+*/
+function buildDiscriminatorOption(subtype, propertyName) {
+	return {
+		$ref: `#/components/schemas/${subtype.name}`,
+		properties: { [propertyName]: { const: subtype.constValue } }
+	};
+}
+/**
+* Document-level pre-pass for OpenAPI discriminators that are declared
+* on a base schema and inherited by subtypes via `allOf`.
+*
+* The per-node {@link normaliseOpenApi30Discriminator} only handles
+* discriminators that already sit alongside `oneOf`/`anyOf`. For the
+* canonical "Cat extends Pet" pattern — where `Pet` carries the
+* discriminator and `Cat`/`Dog` reference `Pet` via `allOf` — the
+* discriminator is silently lost. This pre-pass:
+*
+* 1. Injects the discriminator `const` on each subtype's local
+*    `properties` (so a direct render of the subtype validates the
+*    discriminator value correctly).
+* 2. Synthesises a `oneOf` on the base whenever it lacks one, listing
+*    each subtype as `{ $ref, properties: { propertyName: { const } } }`.
+*    The per-node discriminator transform then sees `oneOf` and clears
+*    the `discriminator` keyword, and the walker's
+*    `detectDiscriminated` finds the per-option `const`s.
+*
+* Mutates a shallow clone of `components/schemas` — the input document
+* is never modified.
+*/
+function applyDiscriminatorAllOfPrepass(doc) {
+	const components = doc.components;
+	if (!isObject(components)) return doc;
+	const schemas = components.schemas;
+	if (!isObject(schemas)) return doc;
+	const plans = [];
+	for (const [baseName, base] of Object.entries(schemas)) {
+		if (!isObject(base)) continue;
+		const discriminator = base.discriminator;
+		if (!isObject(discriminator)) continue;
+		const propertyName = discriminator.propertyName;
+		if (typeof propertyName !== "string") continue;
+		const subtypes = collectDiscriminatorSubtypes(baseName, discriminator, schemas);
+		if (subtypes.length === 0) continue;
+		plans.push({
+			baseName,
+			propertyName,
+			subtypes,
+			baseHasOneOfOrAnyOf: Array.isArray(base.oneOf) || Array.isArray(base.anyOf),
+			baseInherited: captureBaseInherited(base)
+		});
+	}
+	if (plans.length === 0) return doc;
+	const newSchemas = { ...schemas };
+	const cloneSchema = (name) => {
+		const existing = newSchemas[name];
+		if (!isObject(existing)) throw new Error(`applyDiscriminatorAllOfPrepass: schema "${name}" disappeared between planning and rewrite`);
+		const clone = { ...existing };
+		newSchemas[name] = clone;
+		return clone;
+	};
+	for (const plan of plans) {
+		for (const subtype of plan.subtypes) {
+			const clone = cloneSchema(subtype.name);
+			rewriteSubtypeAllOf(clone, plan.baseName, plan.baseInherited);
+			injectSubtypeConst(clone, plan.propertyName, subtype.constValue);
+		}
+		if (!plan.baseHasOneOfOrAnyOf) {
+			const baseClone = cloneSchema(plan.baseName);
+			baseClone.oneOf = plan.subtypes.map((subtype) => buildDiscriminatorOption(subtype, plan.propertyName));
+			delete baseClone.properties;
+			delete baseClone.required;
+			delete baseClone.type;
+		}
+	}
+	return {
+		...doc,
+		components: {
+			...components,
+			schemas: newSchemas
+		}
+	};
+}
+/**
 * Combined OpenAPI 3.0.x node transform: Draft 04 + nullable + discriminator.
 * Applied to every schema node in an OpenAPI 3.0 document.
 *
@@ -278,7 +532,7 @@ function normaliseContentMap(content, normaliseSchema) {
 		const encoding = mediaObj.encoding;
 		if (isObject(encoding)) normalised.encoding = mapObjectValues(encoding, (enc) => isObject(enc) ? normaliseEncoding(enc, normaliseSchema) : enc);
 		if ("example" in normalised && !("examples" in normalised)) {
-			normalised.examples = { value: normalised.example };
+			normalised.examples = { default: { value: normalised.example } };
 			delete normalised.example;
 		} else if ("example" in normalised) delete normalised.example;
 		result[mediaType] = normalised;
@@ -332,7 +586,7 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 		result.servers = [{ url: `${typeof schemes[0] === "string" ? schemes[0] : "https"}://${host}${basePath}` }];
 	}
 	const paths = doc.paths;
-	if (isObject(paths)) result.paths = normaliseSwaggerPaths(paths, doc);
+	if (isObject(paths)) result.paths = normaliseSwaggerPaths(paths, doc, diagnostics);
 	const components = {};
 	const definitions = doc.definitions;
 	if (isObject(definitions)) {
@@ -353,7 +607,7 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 			const resolved = resolveSwaggerParameter(param, doc);
 			const location = resolved.in;
 			if (location === "body") requestBodies[name] = buildRequestBody(resolved, globalConsumes);
-			else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), ["multipart/form-data"]);
+			else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
 			else convertedParameters[name] = normaliseSwaggerParameter(resolved, doc);
 		}
 		if (Object.keys(convertedParameters).length > 0) components.parameters = convertedParameters;
@@ -381,7 +635,7 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 	});
 	return result;
 }
-function normaliseSwaggerPaths(paths, doc) {
+function normaliseSwaggerPaths(paths, doc, diagnostics) {
 	const result = {};
 	const METHODS = [
 		"get",
@@ -401,7 +655,7 @@ function normaliseSwaggerPaths(paths, doc) {
 		for (const method of METHODS) {
 			const operation = pathItem[method];
 			if (!isObject(operation)) continue;
-			normalisedPath[method] = normaliseSwaggerOperation(operation, doc);
+			normalisedPath[method] = normaliseSwaggerOperation(operation, doc, path, method, diagnostics);
 		}
 		const pathParams = pathItem.parameters;
 		if (Array.isArray(pathParams)) normalisedPath.parameters = pathParams.map((p) => isObject(p) ? normaliseSwaggerParameter(p, doc) : p);
@@ -409,7 +663,7 @@ function normaliseSwaggerPaths(paths, doc) {
 	}
 	return result;
 }
-function normaliseSwaggerOperation(operation, doc) {
+function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 	const result = {};
 	const globalProduces = Array.isArray(doc.produces) ? doc.produces : ["application/json"];
 	const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
@@ -420,28 +674,61 @@ function normaliseSwaggerOperation(operation, doc) {
 	if (Array.isArray(params)) {
 		const nonBodyParams = [];
 		let bodyParam;
+		let firstBodyName;
 		let usesFormData = false;
-		for (const param of params) {
+		for (const [index, param] of params.entries()) {
 			if (!isObject(param)) {
 				nonBodyParams.push(param);
 				continue;
 			}
 			const resolvedParam = resolveSwaggerParameter(param, doc);
 			const location = resolvedParam.in;
-			if (location === "body") bodyParam = resolvedParam;
-			else if (location === "formData") {
-				bodyParam = buildFormDataBody(resolvedParam, params);
-				usesFormData = true;
+			if (location === "body") {
+				if (bodyParam !== void 0) {
+					const duplicateName = typeof resolvedParam.name === "string" ? resolvedParam.name : `parameters[${String(index)}]`;
+					emitDiagnostic(diagnostics, {
+						code: "duplicate-body-parameter",
+						message: `Operation defines more than one "in: body" parameter; keeping the first ("${firstBodyName ?? "(unnamed)"}") and discarding "${duplicateName}"`,
+						pointer: appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"),
+						detail: {
+							kept: firstBodyName,
+							discarded: duplicateName,
+							location: "operation"
+						}
+					});
+					continue;
+				}
+				bodyParam = resolvedParam;
+				firstBodyName = typeof resolvedParam.name === "string" ? resolvedParam.name : void 0;
+			} else if (location === "formData") {
+				if (!usesFormData) {
+					bodyParam = buildFormDataBody(resolvedParam, params);
+					usesFormData = true;
+				}
 			} else nonBodyParams.push(normaliseSwaggerParameter(resolvedParam, doc));
 		}
 		if (nonBodyParams.length > 0) result.parameters = nonBodyParams;
-		if (bodyParam !== void 0) result.requestBody = buildRequestBody(bodyParam, usesFormData ? ["multipart/form-data"] : consumes);
+		if (bodyParam !== void 0) result.requestBody = buildRequestBody(bodyParam, usesFormData ? formDataContentTypes(consumes) : consumes);
 	}
 	const responses = operation.responses;
 	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces);
 	return result;
 }
 /**
+* Determine the request body media type for a Swagger 2.0 formData operation.
+*
+* Per the OAS 3 conversion rules, `application/x-www-form-urlencoded` is
+* preferred when the operation- or document-level `consumes` includes it;
+* otherwise `multipart/form-data` is the default. File uploads (Swagger 2.0
+* `type: file`) still require `multipart/form-data`, but the formData body
+* schema-builder normalises them to `string` + `format: binary` either way
+* and the choice of media type is left to the source document.
+*/
+function formDataContentTypes(consumes) {
+	if (consumes.includes("application/x-www-form-urlencoded")) return ["application/x-www-form-urlencoded"];
+	return ["multipart/form-data"];
+}
+/**
 * Resolve a Swagger parameter that may be a `$ref`.
 */
 function resolveSwaggerParameter(param, doc, visited = /* @__PURE__ */ new Set()) {
@@ -596,7 +883,7 @@ function normaliseSwaggerResponses(responses, doc, produces) {
 function normaliseSwaggerSingleResponse(response, doc, produces) {
 	const resolved = resolveSwaggerResponse(response, doc);
 	const normalised = {};
-	for (const [key, value] of Object.entries(resolved)) if (key !== "schema") normalised[key] = value;
+	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") normalised[key] = value;
 	const schema = resolved.schema;
 	if (isObject(schema)) {
 		const content = {};
@@ -604,9 +891,64 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 		for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
 		normalised.content = content;
 	}
+	const headers = resolved.headers;
+	if (isObject(headers)) {
+		const convertedHeaders = {};
+		for (const [name, header] of Object.entries(headers)) convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header) : header;
+		normalised.headers = convertedHeaders;
+	}
 	return normalised;
 }
 /**
+* Normalise a single Swagger 2.0 response header to OpenAPI 3.x form.
+*
+* Swagger 2.0 headers mirror parameter shape: `type`/`format`/
+* `collectionFormat` live at the root. OpenAPI 3.x requires the type
+* descriptor under `schema`, with collection serialisation expressed via
+* `style`/`explode`. Headers do not carry `name` or `in` — those are not
+* part of either spec at this level — so this is a thin sibling to
+* `normaliseSwaggerParameter` rather than a full reuse. The OpenAPI 3.x
+* default header style is `simple`, so CSV-encoded headers map to
+* `simple`/`explode: false` rather than the `form` style used for query
+* parameters.
+*/
+function normaliseSwaggerHeader(header) {
+	const result = {};
+	for (const [key, value] of Object.entries(header)) {
+		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		result[key] = value;
+	}
+	if (typeof header.type === "string") {
+		const schema = { type: header.type };
+		if (typeof header.format === "string") schema.format = header.format;
+		if (header.enum !== void 0) schema.enum = header.enum;
+		if (header.default !== void 0) schema.default = header.default;
+		if (header.minimum !== void 0) schema.minimum = header.minimum;
+		if (header.maximum !== void 0) schema.maximum = header.maximum;
+		result.schema = schema;
+	}
+	const cf = header.collectionFormat;
+	if (typeof cf === "string") switch (cf) {
+		case "csv":
+			result.style = "simple";
+			result.explode = false;
+			break;
+		case "ssv":
+			result.style = "spaceDelimited";
+			result.explode = false;
+			break;
+		case "tsv":
+			result.style = "tabDelimited";
+			result.explode = false;
+			break;
+		case "pipes":
+			result.style = "pipeDelimited";
+			result.explode = false;
+			break;
+	}
+	return result;
+}
+/**
 * Mapping of Swagger 2.0 $ref prefixes to OpenAPI 3.x equivalents.
 * Applied after document restructuring so all $ref strings point
 * to the correct locations in the normalised document.
@@ -691,35 +1033,43 @@ const SINGLE_SUBSCHEMA_KEYS = new Set([
 * Normalise each element of an unknown array by applying deepNormalise
 * to object elements and passing others through unchanged.
 */
-function normaliseArray(items, transform) {
+function normaliseArray(items, transform, visited) {
 	const result = [];
-	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform) : item);
+	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform, visited) : item);
 	return result;
 }
 /**
 * Normalise each value of a sub-schema map (e.g. properties, $defs).
 */
-function normaliseSubSchemaMap(map, transform) {
+function normaliseSubSchemaMap(map, transform, visited) {
 	const result = {};
-	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform) : v;
+	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform, visited) : v;
 	return result;
 }
 /**
 * Deep-normalise a JSON Schema object by applying a per-node transform
 * and recursing into every sub-schema location.
+*
+* The optional `visited` set guards against shared object references and
+* cycles introduced upstream (e.g. by the OpenAPI bundler's
+* `structuredClone`-based inlining of external refs). The walk skips
+* already-seen nodes by returning the original reference rather than
+* recursing forever.
 */
-function deepNormalise(schema, transform) {
+function deepNormalise(schema, transform, visited = /* @__PURE__ */ new WeakSet()) {
+	if (visited.has(schema)) return schema;
+	visited.add(schema);
 	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);
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMap(value, transform, visited);
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArray(value, transform, visited);
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormalise(value, transform, visited);
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArray(value, transform, visited);
+	else if (isObject(value)) result[key] = deepNormalise(value, transform, visited);
 	else result[key] = value;
 	else if (key === "dependencies" && isObject(value)) {
 		const normalised = {};
-		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormalise(dv, transform);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormalise(dv, transform, visited);
 		else normalised[dk] = dv;
 		result[key] = normalised;
 	} else result[key] = value;
@@ -888,6 +1238,26 @@ function validateDependentRequired(node, ctx) {
 	}
 }
 /**
+* Translate the legacy tuple-form `items: [Schema, Schema]` keyword to
+* Draft 2020-12's `prefixItems`. `additionalItems` becomes the rest-element
+* schema and is rewritten to `items`.
+*
+* Applies to Drafts 04, 06, and 07 — all of which used the tuple form
+* before Draft 2020-12 split positional schemas into `prefixItems`.
+*
+* No-op when `items` is already a single sub-schema, or when `prefixItems`
+* is already present (do not overwrite an explicit author choice).
+*/
+function translateTupleItems(node) {
+	if (!Array.isArray(node.items) || "prefixItems" in node) return;
+	node.prefixItems = node.items;
+	delete node.items;
+	if ("additionalItems" in node) {
+		node.items = node.additionalItems;
+		delete node.additionalItems;
+	}
+}
+/**
 * Apply the version-agnostic Draft 04 keyword translations to a single
 * node: boolean exclusive-min/max → number form, bare `id` → `$id`, and
 * tuple-form `items` → `prefixItems`.
@@ -906,10 +1276,28 @@ function applyDraft04Translations(node, ctx) {
 		node.exclusiveMinimum = node.minimum;
 		delete node.minimum;
 	} else if (node.exclusiveMinimum === false) delete node.exclusiveMinimum;
+	else if (node.exclusiveMinimum === true) {
+		if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+			code: "bare-exclusive-bound",
+			message: "`exclusiveMinimum: true` requires a sibling numeric `minimum` in Draft 04; dropping the keyword",
+			pointer: appendPointer(ctx.pointer, "exclusiveMinimum"),
+			detail: { keyword: "exclusiveMinimum" }
+		});
+		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;
+	else if (node.exclusiveMaximum === true) {
+		if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+			code: "bare-exclusive-bound",
+			message: "`exclusiveMaximum: true` requires a sibling numeric `maximum` in Draft 04; dropping the keyword",
+			pointer: appendPointer(ctx.pointer, "exclusiveMaximum"),
+			detail: { keyword: "exclusiveMaximum" }
+		});
+		delete node.exclusiveMaximum;
+	}
 	const divisibleBy = node.divisibleBy;
 	if (typeof divisibleBy === "number") {
 		const multipleOf = node.multipleOf;
@@ -930,14 +1318,7 @@ function applyDraft04Translations(node, ctx) {
 		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;
-		}
-	}
+	translateTupleItems(node);
 	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 }
@@ -983,8 +1364,14 @@ function normaliseDraft04NodeWithContext(node, ctx) {
 * (already in final form) and `const`/`examples`, but still use the
 * legacy `dependencies` keyword. Split it into `dependentRequired` /
 * `dependentSchemas` so the walker can process them uniformly.
+*
+* Drafts 06 and 07 also use the tuple form
+* `items: [Schema, Schema], additionalItems: Schema` — translate that to
+* Draft 2020-12's `prefixItems` + rest-`items` so the walker produces a
+* `TupleField` rather than silently dropping the positional schemas.
 */
 function normaliseDraft06Or07NodeWithContext(node, ctx) {
+	translateTupleItems(node);
 	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 	return node;
@@ -1045,15 +1432,153 @@ function normaliseJsonSchema(schema, draft, diagnostics) {
 		diagnostics,
 		pointer: ""
 	};
+	let normalised;
 	switch (draft) {
-		case "draft-04": return deepNormaliseWithContext(schema, normaliseDraft04NodeWithContext, ctx);
-		case "draft-2019-09": return deepNormaliseWithContext(schema, normaliseDraft201909NodeWithContext, ctx);
-		case "draft-2020-12": return deepNormaliseWithContext(schema, normaliseDynamicRefNodeWithContext, ctx);
+		case "draft-04":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft04NodeWithContext, ctx);
+			break;
+		case "draft-2019-09":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft201909NodeWithContext, ctx);
+			break;
+		case "draft-2020-12":
+			normalised = deepNormaliseWithContext(schema, normaliseDynamicRefNodeWithContext, ctx);
+			break;
 		case "draft-06":
-		case "draft-07": return deepNormaliseWithContext(schema, normaliseDraft06Or07NodeWithContext, ctx);
+		case "draft-07":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft06Or07NodeWithContext, ctx);
+			break;
+	}
+	return resolveRelativeRefs(normalised, diagnostics);
+}
+/**
+* Parse a string as an absolute URI, returning `undefined` when it has
+* no scheme. Used to detect whether an `$id` value defines a base URI.
+*/
+function parseAbsoluteUri(value) {
+	if (typeof value !== "string" || value.length === 0) return void 0;
+	try {
+		const url = new URL(value);
+		if (url.protocol.length === 0) return void 0;
+		return url;
+	} catch {
+		return;
 	}
 }
 /**
+* Resolve a relative reference against a base URI. Returns `undefined`
+* when the reference cannot be resolved (e.g. malformed input).
+*/
+function resolveAgainst(ref, base) {
+	try {
+		return new URL(ref, base);
+	} catch {
+		return;
+	}
+}
+/**
+* Strip the fragment portion from a URL, returning the canonical
+* `scheme://authority/path?query` form. Used to compare a resolved
+* `$ref` URI against the document's `$id` base.
+*/
+function stripFragment(url) {
+	const clone = new URL(url.toString());
+	clone.hash = "";
+	return clone.toString();
+}
+/**
+* Recursively rewrite relative `$ref`s in a schema so they resolve
+* correctly under the JSON Schema base-URI rules (RFC 3986 + JSON
+* Schema §8.2). Refs that resolve to the document's own `$id` are
+* rewritten to fragment-only form so the existing dereferencer can
+* handle them; refs that resolve outside the document are left as
+* absolute URIs (handled by the external resolver path).
+*
+* Returns the input unchanged when the document has no base URI or
+* no relative refs.
+*/
+function resolveRelativeRefs(schema, diagnostics) {
+	const docBaseUrl = parseAbsoluteUri(schema.$id);
+	if (docBaseUrl === void 0) return schema;
+	const docBase = stripFragment(docBaseUrl);
+	return rewriteRelativeRefsNode(schema, docBase, docBase, "", diagnostics, /* @__PURE__ */ new WeakSet());
+}
+/**
+* Rewrite relative `$ref`s in a single node, recursing into sub-schemas.
+*
+* The `visited` set guards against shared object references and cycles
+* introduced upstream (e.g. by the OpenAPI bundler's `structuredClone`
+* inlining of external refs). When a node is re-encountered the rewrite
+* is short-circuited — returning the original reference unchanged is
+* sound because every relative `$ref` in the subtree was already
+* rewritten on the first visit.
+*/
+function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostics, visited) {
+	if (visited.has(node)) return node;
+	visited.add(node);
+	let nextBase = currentBase;
+	const nodeId = node.$id;
+	if (typeof nodeId === "string" && nodeId.length > 0) {
+		const resolved = resolveAgainst(nodeId, currentBase);
+		if (resolved !== void 0) nextBase = stripFragment(resolved);
+	}
+	const result = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" && typeof value === "string") {
+			result[key] = rewriteRef(value, nextBase, docBase, appendPointer(pointer, key), diagnostics);
+			continue;
+		}
+		result[key] = rewriteRelativeRefsValue(value, nextBase, docBase, appendPointer(pointer, key), diagnostics, visited);
+	}
+	return result;
+}
+function rewriteRelativeRefsValue(value, currentBase, docBase, pointer, diagnostics, visited) {
+	if (Array.isArray(value)) {
+		if (visited.has(value)) return value;
+		visited.add(value);
+		return value.map((item, i) => rewriteRelativeRefsValue(item, currentBase, docBase, appendPointer(pointer, String(i)), diagnostics, visited));
+	}
+	if (isObject(value)) return rewriteRelativeRefsNode(value, currentBase, docBase, pointer, diagnostics, visited);
+	return value;
+}
+/**
+* Rewrite a single `$ref` string. Fragment-only refs and refs that
+* already include a scheme are returned unchanged. Relative refs are
+* resolved against `currentBase`; if the result lives in the same
+* document as `docBase`, the ref is rewritten to fragment form.
+*/
+function rewriteRef(ref, currentBase, docBase, pointer, diagnostics) {
+	if (ref.startsWith("#")) return ref;
+	if (/^[a-z][a-z0-9+\-.]*:/i.test(ref)) return ref;
+	const resolved = resolveAgainst(ref, currentBase);
+	if (resolved === void 0) return ref;
+	if (stripFragment(resolved) === docBase) {
+		const fragment = resolved.hash === "" ? "#" : resolved.hash;
+		emitDiagnostic(diagnostics, {
+			code: "relative-ref-resolved",
+			message: `Relative $ref "${ref}" resolved to "${fragment}" against base "${currentBase}"`,
+			pointer,
+			detail: {
+				ref,
+				base: currentBase,
+				resolved: fragment
+			}
+		});
+		return fragment;
+	}
+	const absolute = resolved.toString();
+	emitDiagnostic(diagnostics, {
+		code: "relative-ref-resolved",
+		message: `Relative $ref "${ref}" resolved to "${absolute}" against base "${currentBase}"`,
+		pointer,
+		detail: {
+			ref,
+			base: currentBase,
+			resolved: absolute
+		}
+	});
+	return absolute;
+}
+/**
 * Normalise an OpenAPI document's schemas for walker consumption.
 * Handles version-specific keyword transformations.
 *
@@ -1062,8 +1587,17 @@ function normaliseJsonSchema(schema, draft, diagnostics) {
 */
 function normaliseOpenApiSchemas(doc, version, diagnostics) {
 	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics);
-	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(doc, deepNormalise);
-	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Discriminator));
+	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(applyDiscriminatorAllOfPrepass(doc), deepNormalise);
+	if (isOpenApi31(version)) {
+		const dialect = readJsonSchemaDialect(doc);
+		if (dialect.kind === "unknown") emitDiagnostic(diagnostics, {
+			code: "unknown-json-schema-dialect",
+			message: `OpenAPI 3.1 \`jsonSchemaDialect\` URI "${dialect.uri}" does not match a supported JSON Schema draft; falling back to Draft 2020-12`,
+			pointer: "/jsonSchemaDialect",
+			detail: { uri: dialect.uri }
+		});
+	}
+	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => resolveRelativeRefs(deepNormalise(schema, normaliseOpenApi30Discriminator), diagnostics));
 }
 //#endregion
-export { normaliseOpenApiSchemas as a, deepNormaliseOpenApiDoc as c, normaliseOpenApi30Node as d, normaliseJsonSchema as i, normaliseOpenApi30Combined as l, deepNormaliseWithContext as n, normaliseSwagger2Document as o, normaliseDraft04Node as r, deepNormaliseOpenApi30Doc as s, deepNormalise as t, normaliseOpenApi30Discriminator as u };
+export { normaliseOpenApiSchemas as a, deepNormaliseOpenApi30Doc as c, normaliseOpenApi30Discriminator as d, normaliseOpenApi30Node as f, normaliseJsonSchema as i, deepNormaliseOpenApiDoc as l, deepNormaliseWithContext as n, normaliseSwagger2Document as o, normaliseDraft04Node as r, applyDiscriminatorAllOfPrepass as s, deepNormalise as t, normaliseOpenApi30Combined as u };