schema-components 1.22.0 → 1.23.0

package/dist/{normalise-DVEJQmF7.mjs → normalise-DCYp06Sr.mjs}

@@ -1,6 +1,9 @@
 import { isObject } from "./core/guards.mjs";
 import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
-import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./core/version.mjs";
+import { RECURSIVE_ANCHOR_SENTINEL } from "./core/ref.mjs";
+import { isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri, readJsonSchemaDialect } from "./core/version.mjs";
+import { SWAGGER_2_METHODS, rewriteSwaggerRefPrefix } from "./core/openapiConstants.mjs";
+import { resolveRefChain } from "./core/refChain.mjs";
 //#region src/core/openapi30.ts
 /**
 * OpenAPI 3.0.x schema normalisation.
@@ -10,6 +13,29 @@ import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./c
 * responses, headers, callbacks, links, examples) to apply normalisation.
 */
 /**
+* Lift OpenAPI 3.x singular `example` onto the plural `examples` key.
+*
+* Two output shapes are spec-correct depending on the parent object type:
+*   - `"array"` — Schema Object: `examples: [example]` (Draft 2020-12 plural).
+*   - `"map"`   — Parameter / Header / Media Type Object: an Examples Map
+*                 keyed by name. The single value is wrapped under the
+*                 synthetic key `default` to produce a valid one-entry map
+*                 of one Example Object.
+*
+* When both `example` and `examples` coexist the spec declares them mutually
+* exclusive — `example` is dropped and `examples` wins.
+*/
+function liftExampleToExamples(node, shape) {
+	if (!("example" in node)) return;
+	if ("examples" in node) {
+		delete node.example;
+		return;
+	}
+	if (shape === "array") node.examples = [node.example];
+	else node.examples = { default: { value: node.example } };
+	delete node.example;
+}
+/**
 * Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
 *
 * OpenAPI 3.0 uses `nullable: true` instead of the JSON Schema standard
@@ -20,24 +46,32 @@ import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./c
 * absent is the default and requires no transformation.
 */
 function normaliseOpenApi30Node(node) {
-	if ("example" in node && !("examples" in node)) {
-		node.examples = [node.example];
-		delete node.example;
-	} else if ("example" in node) delete node.example;
+	liftExampleToExamples(node, "array");
 	if (node.nullable !== true) {
 		if ("nullable" in node) delete node.nullable;
 		return node;
 	}
 	const nullOption = { type: "null" };
-	if (typeof node.$ref === "string") return { anyOf: [{ $ref: node.$ref }, nullOption] };
-	if (Array.isArray(node.enum) && !node.enum.includes(null)) node.enum = [...node.enum, null];
+	if (typeof node.$ref === "string") {
+		const wrapper = { anyOf: [{ $ref: node.$ref }, nullOption] };
+		for (const key of REF_DOC_SIBLINGS) if (key in node) wrapper[key] = node[key];
+		return wrapper;
+	}
+	if (Array.isArray(node.enum)) {
+		if (node.enum.includes(null)) {
+			delete node.nullable;
+			return node;
+		}
+	}
 	if (Array.isArray(node.anyOf)) {
-		node.anyOf = [...node.anyOf, nullOption];
+		const existing = node.anyOf;
+		node.anyOf = compositeAlreadyAllowsNull(existing) ? existing : [...existing, nullOption];
 		delete node.nullable;
 		return node;
 	}
 	if (Array.isArray(node.oneOf)) {
-		node.anyOf = [...node.oneOf, nullOption];
+		const existing = node.oneOf;
+		node.anyOf = compositeAlreadyAllowsNull(existing) ? existing : [...existing, nullOption];
 		delete node.oneOf;
 		delete node.nullable;
 		return node;
@@ -53,6 +87,39 @@ function normaliseOpenApi30Node(node) {
 	return { anyOf: [wrapper, nullOption] };
 }
 /**
+* Documentary keys that may legitimately sit alongside a `$ref` in an
+* OpenAPI 3.0 Schema Object. They carry author-facing metadata, not
+* validation semantics, so lifting them onto the `anyOf` wrapper
+* preserves authorial intent without violating the spec rule that a
+* Reference Object itself only carry `$ref`.
+*/
+const REF_DOC_SIBLINGS = [
+	"description",
+	"summary",
+	"title",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"example",
+	"examples",
+	"default"
+];
+/**
+* Returns `true` when at least one option in a composite (`anyOf` /
+* `oneOf`) already permits `null` — either a literal `{ type: "null" }`
+* branch or an `enum` containing `null`. Used to dedup the synthetic
+* null option appended when normalising `nullable: true`.
+*/
+function compositeAlreadyAllowsNull(options) {
+	for (const option of options) {
+		if (!isObject(option)) continue;
+		if (option.type === "null") return true;
+		if (Array.isArray(option.type) && option.type.includes("null")) return true;
+		if (Array.isArray(option.enum) && option.enum.includes(null)) return true;
+	}
+	return false;
+}
+/**
 * Normalise OpenAPI 3.0.x `discriminator` keyword by injecting `const`
 * values into each `oneOf`/`anyOf` option's discriminator property.
 *
@@ -80,7 +147,7 @@ function normaliseOpenApi30Discriminator(node) {
 			normalisedComposite.push(option);
 			continue;
 		}
-		const props = isObject(option.properties) ? { ...option.properties } : void 0;
+		const props = isObject(option.properties) ? option.properties : void 0;
 		const discProp = props?.[propertyName];
 		if (isObject(discProp) && "const" in discProp) {
 			normalisedComposite.push(option);
@@ -102,7 +169,7 @@ function normaliseOpenApi30Discriminator(node) {
 			if (entry !== void 0) constValue = entry[0];
 		}
 		if (constValue !== void 0) {
-			const normalisedProps = props ?? {};
+			const normalisedProps = { ...props };
 			normalisedProps[propertyName] = {
 				...isObject(discProp) ? discProp : {},
 				const: constValue
@@ -487,10 +554,7 @@ function normaliseParameter(param, normaliseSchema) {
 	if (isObject(schema)) result.schema = normaliseSchema(schema);
 	const content = param.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
-	if ("example" in result && !("examples" in result)) {
-		result.examples = { default: { value: result.example } };
-		delete result.example;
-	} else if ("example" in result) delete result.example;
+	liftExampleToExamples(result, "map");
 	return result;
 }
 function normaliseRequestBody(requestBody, normaliseSchema) {
@@ -513,10 +577,7 @@ function normaliseHeader(header, normaliseSchema) {
 	if (isObject(schema)) result.schema = normaliseSchema(schema);
 	const content = header.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
-	if ("example" in result && !("examples" in result)) {
-		result.examples = { default: { value: result.example } };
-		delete result.example;
-	} else if ("example" in result) delete result.example;
+	liftExampleToExamples(result, "map");
 	return result;
 }
 /**
@@ -539,10 +600,7 @@ function normaliseContentMap(content, normaliseSchema) {
 		if (isObject(schema)) normalised.schema = normaliseSchema(schema);
 		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 = { default: { value: normalised.example } };
-			delete normalised.example;
-		} else if ("example" in normalised) delete normalised.example;
+		liftExampleToExamples(normalised, "map");
 		result[mediaType] = normalised;
 	}
 	return result;
@@ -639,16 +697,34 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 			const resolved = resolution.param;
 			const location = resolved.in;
 			if (location === "body") {
-				if (consumesResolution.source === "synthesised") emitDiagnostic(diagnostics, {
-					code: "swagger-missing-consumes",
-					message: "Global body parameter declared but document-level `consumes` is absent; defaulting to application/json",
-					pointer: appendPointer(appendPointer("", "parameters"), name),
-					detail: {
-						level: "document",
-						name
-					}
-				});
-				requestBodies[name] = buildRequestBody(resolved, globalConsumes);
+				const paramPointer = appendPointer(appendPointer("", "parameters"), name);
+				let bodyContentTypes;
+				if (consumesResolution.source === "synthesised") {
+					bodyContentTypes = globalConsumes;
+					emitDiagnostic(diagnostics, {
+						code: "swagger-missing-consumes",
+						message: "Global body parameter declared but document-level `consumes` is absent; defaulting to application/json",
+						pointer: paramPointer,
+						detail: {
+							level: "document",
+							name
+						}
+					});
+				} else if (globalConsumes.length === 0) {
+					bodyContentTypes = [];
+					emitDiagnostic(diagnostics, {
+						code: "swagger-missing-consumes",
+						message: "Global body parameter declared but document-level `consumes` is an explicit empty array; preserving an empty content map",
+						pointer: paramPointer,
+						detail: {
+							level: "document",
+							name,
+							reason: "explicitly-cleared",
+							source: consumesResolution.source
+						}
+					});
+				} else bodyContentTypes = globalConsumes;
+				requestBodies[name] = buildRequestBody(resolved, bodyContentTypes);
 			} else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
 			else {
 				const normalised = normaliseSwaggerParameter(resolved, doc, diagnostics, appendPointer(appendPointer("", "parameters"), name));
@@ -668,7 +744,11 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 	const securityDefinitions = doc.securityDefinitions;
 	if (isObject(securityDefinitions)) {
 		const translated = {};
-		for (const [name, scheme] of Object.entries(securityDefinitions)) translated[name] = isObject(scheme) ? translateSwaggerSecurityScheme(scheme) : scheme;
+		const securityDefinitionsPointer = appendPointer("", "securityDefinitions");
+		for (const [name, scheme] of Object.entries(securityDefinitions)) {
+			const schemePointer = appendPointer(securityDefinitionsPointer, name);
+			translated[name] = isObject(scheme) ? translateSwaggerSecurityScheme(scheme, diagnostics, schemePointer, name) : scheme;
+		}
 		components.securitySchemes = translated;
 	}
 	if (Object.keys(components).length > 0) result.components = components;
@@ -676,7 +756,7 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 	if (isObject(doc.externalDocs)) result.externalDocs = doc.externalDocs;
 	if (Array.isArray(doc.security)) result.security = doc.security;
 	rewriteSwaggerRefs(result);
-	if (hasXmlAnywhere(doc.definitions) || hasXmlAnywhere(doc.paths) || hasXmlAnywhere(doc.parameters) || hasXmlAnywhere(doc.responses)) emitDiagnostic(diagnostics, {
+	if (documentContainsKeyword(doc.definitions, "xml") || documentContainsKeyword(doc.paths, "xml") || documentContainsKeyword(doc.parameters, "xml") || documentContainsKeyword(doc.responses, "xml")) emitDiagnostic(diagnostics, {
 		code: "dropped-swagger-feature",
 		message: "Swagger 2.0 xml markup is not supported and will be dropped",
 		pointer: "",
@@ -686,22 +766,13 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 }
 function normaliseSwaggerPaths(paths, doc, diagnostics) {
 	const result = {};
-	const METHODS = [
-		"get",
-		"post",
-		"put",
-		"patch",
-		"delete",
-		"head",
-		"options"
-	];
 	for (const [path, pathItem] of Object.entries(paths)) {
 		if (!isObject(pathItem)) {
 			result[path] = pathItem;
 			continue;
 		}
 		const normalisedPath = {};
-		for (const method of METHODS) {
+		for (const method of SWAGGER_2_METHODS) {
 			const operation = pathItem[method];
 			if (!isObject(operation)) continue;
 			normalisedPath[method] = normaliseSwaggerOperation(operation, doc, path, method, diagnostics);
@@ -783,16 +854,34 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 		}
 		if (nonBodyParams.length > 0) result.parameters = nonBodyParams;
 		if (bodyParam !== void 0) {
-			const bodyContentTypes = usesFormData ? formDataContentTypes(consumes) : consumes;
-			if (!usesFormData && consumesResolution.source === "synthesised") emitDiagnostic(diagnostics, {
-				code: "swagger-missing-consumes",
-				message: "Operation declares a body parameter but neither operation-level nor document-level `consumes` is set; defaulting to application/json",
-				pointer: appendPointer(appendPointer(appendPointer("", "paths"), path), method),
-				detail: {
-					level: "operation",
-					method
-				}
-			});
+			const operationPointer = appendPointer(appendPointer(appendPointer("", "paths"), path), method);
+			let bodyContentTypes;
+			if (usesFormData) bodyContentTypes = formDataContentTypes(consumes);
+			else if (consumesResolution.source === "synthesised") {
+				bodyContentTypes = consumes;
+				emitDiagnostic(diagnostics, {
+					code: "swagger-missing-consumes",
+					message: "Operation declares a body parameter but neither operation-level nor document-level `consumes` is set; defaulting to application/json",
+					pointer: operationPointer,
+					detail: {
+						level: "operation",
+						method
+					}
+				});
+			} else if (consumes.length === 0) {
+				bodyContentTypes = [];
+				emitDiagnostic(diagnostics, {
+					code: "swagger-missing-consumes",
+					message: "Operation declares a body parameter but `consumes` is an explicit empty array; preserving an empty content map",
+					pointer: operationPointer,
+					detail: {
+						level: "operation",
+						method,
+						reason: "explicitly-cleared",
+						source: consumesResolution.source
+					}
+				});
+			} else bodyContentTypes = consumes;
 			result.requestBody = buildRequestBody(bodyParam, bodyContentTypes);
 		}
 	}
@@ -895,34 +984,37 @@ function buildSchemaFromSwaggerParameterShape(node) {
 * decide how to surface the failure. Non-ref parameters resolve to
 * themselves; ref targets that don't exist also resolve to the input
 * (the caller treats unknown refs the same as bare parameters).
-*/
-function resolveSwaggerParameter(param, doc, visited = /* @__PURE__ */ new Set()) {
-	const ref = param.$ref;
-	if (typeof ref !== "string" || !ref.startsWith("#/parameters/")) return {
-		kind: "ok",
-		param
-	};
-	if (visited.has(ref)) return {
+*
+* Uses the shared {@link resolveRefChain} helper so cycle detection
+* and hop accounting stay consistent with the other OpenAPI $ref
+* walkers.
+*/
+function resolveSwaggerParameter(param, doc) {
+	let cyclicRef;
+	const finalNode = resolveRefChain(param, {
+		extractRef: (node) => {
+			const ref = node.$ref;
+			if (typeof ref !== "string") return void 0;
+			return ref.startsWith("#/parameters/") ? ref : void 0;
+		},
+		lookup: (ref) => {
+			const name = ref.slice(13);
+			const globalParams = doc.parameters;
+			if (!isObject(globalParams)) return void 0;
+			const resolved = globalParams[name];
+			return isObject(resolved) ? resolved : void 0;
+		},
+		onCycle: (ref) => {
+			cyclicRef = ref;
+		}
+	});
+	if (cyclicRef !== void 0) return {
 		kind: "cycle",
-		ref
+		ref: cyclicRef
 	};
-	const nextVisited = new Set(visited);
-	nextVisited.add(ref);
-	const name = ref.slice(13);
-	const globalParams = doc.parameters;
-	if (isObject(globalParams)) {
-		const resolved = globalParams[name];
-		if (isObject(resolved)) {
-			if (typeof resolved.$ref === "string") return resolveSwaggerParameter(resolved, doc, nextVisited);
-			return {
-				kind: "ok",
-				param: resolved
-			};
-		}
-	}
 	return {
 		kind: "ok",
-		param
+		param: finalNode ?? param
 	};
 }
 /**
@@ -966,7 +1058,7 @@ function normaliseSwaggerParameter(param, doc, diagnostics, pointer = "") {
 	const cf = param.collectionFormat;
 	if (typeof cf === "string") switch (cf) {
 		case "csv":
-			result.style = "form";
+			result.style = param.in === "path" || param.in === "header" ? "simple" : "form";
 			result.explode = false;
 			break;
 		case "ssv":
@@ -974,8 +1066,15 @@ function normaliseSwaggerParameter(param, doc, diagnostics, pointer = "") {
 			result.explode = false;
 			break;
 		case "tsv":
-			result.style = "tabDelimited";
-			result.explode = false;
+			emitDiagnostic(diagnostics, {
+				code: "swagger-collection-format-dropped",
+				message: "Swagger 2.0 collectionFormat: \"tsv\" has no OpenAPI 3.x equivalent; dropping the keyword",
+				pointer,
+				detail: {
+					feature: "collectionFormat:tsv",
+					location: "parameter"
+				}
+			});
 			break;
 		case "pipes":
 			result.style = "pipeDelimited";
@@ -1022,12 +1121,18 @@ function buildFormDataBody(param, allParams) {
 }
 /**
 * Build an OpenAPI 3.x request body from a Swagger 2.0 body parameter.
+*
+* `consumes` is taken at face value — the caller is responsible for
+* deciding whether an absent value should fall back to a default
+* (and emitting `swagger-missing-consumes`) or be preserved as an
+* empty content map (an explicit clear). Inventing a default here
+* would mask the difference and silently override the upstream
+* resolution.
 */
 function buildRequestBody(bodyParam, consumes) {
 	const schema = bodyParam.schema;
 	const content = {};
-	const contentTypes = consumes.length > 0 ? consumes : ["application/json"];
-	for (const ct of contentTypes) if (typeof ct === "string") content[ct] = isObject(schema) ? { schema } : {};
+	for (const ct of consumes) if (typeof ct === "string") content[ct] = isObject(schema) ? { schema } : {};
 	const result = { content };
 	if (bodyParam.required === true) result.required = true;
 	if (typeof bodyParam.description === "string") result.description = bodyParam.description;
@@ -1035,23 +1140,28 @@ function buildRequestBody(bodyParam, consumes) {
 }
 /**
 * Resolve a Swagger 2.0 response `$ref` (e.g. `#/responses/NotFound`).
-*/
-function resolveSwaggerResponse(response, doc, visited = /* @__PURE__ */ new Set()) {
-	const ref = response.$ref;
-	if (typeof ref !== "string" || !ref.startsWith("#/responses/")) return response;
-	if (visited.has(ref)) return response;
-	const nextVisited = new Set(visited);
-	nextVisited.add(ref);
-	const name = ref.slice(12);
-	const globalResponses = doc.responses;
-	if (isObject(globalResponses)) {
-		const resolved = globalResponses[name];
-		if (isObject(resolved)) {
-			if (typeof resolved.$ref === "string") return resolveSwaggerResponse(resolved, doc, nextVisited);
-			return resolved;
-		}
-	}
-	return response;
+*
+* Uses the shared {@link resolveRefChain} helper so cycle detection
+* and hop accounting stay consistent with the other OpenAPI $ref
+* walkers. On cycle the original wrapper is returned (legacy
+* behaviour), preserving the existing response-resolution contract.
+*/
+function resolveSwaggerResponse(response, doc) {
+	return resolveRefChain(response, {
+		extractRef: (node) => {
+			const ref = node.$ref;
+			if (typeof ref !== "string") return void 0;
+			return ref.startsWith("#/responses/") ? ref : void 0;
+		},
+		lookup: (ref) => {
+			const name = ref.slice(12);
+			const globalResponses = doc.responses;
+			if (!isObject(globalResponses)) return void 0;
+			const resolved = globalResponses[name];
+			return isObject(resolved) ? resolved : void 0;
+		},
+		onCycle: () => response
+	}) ?? response;
 }
 function normaliseSwaggerResponses(responses, doc, produces, producesSource, diagnostics, path, method) {
 	const result = {};
@@ -1096,7 +1206,11 @@ function normaliseSwaggerSingleResponse(response, doc, produces, producesSource
 	const headers = resolved.headers;
 	if (isObject(headers)) {
 		const convertedHeaders = {};
-		for (const [name, header] of Object.entries(headers)) convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header) : header;
+		const headersPointer = appendPointer(path !== void 0 && method !== void 0 && statusCode !== void 0 ? appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "responses"), statusCode) : "", "headers");
+		for (const [name, header] of Object.entries(headers)) {
+			const headerPointer = appendPointer(headersPointer, name);
+			convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header, diagnostics, headerPointer) : header;
+		}
 		normalised.headers = convertedHeaders;
 	}
 	return normalised;
@@ -1114,7 +1228,7 @@ function normaliseSwaggerSingleResponse(response, doc, produces, producesSource
 * `simple`/`explode: false` rather than the `form` style used for query
 * parameters.
 */
-function normaliseSwaggerHeader(header) {
+function normaliseSwaggerHeader(header, diagnostics, pointer = "") {
 	const result = {};
 	for (const [key, value] of Object.entries(header)) {
 		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) continue;
@@ -1132,8 +1246,15 @@ function normaliseSwaggerHeader(header) {
 			result.explode = false;
 			break;
 		case "tsv":
-			result.style = "tabDelimited";
-			result.explode = false;
+			emitDiagnostic(diagnostics, {
+				code: "swagger-collection-format-dropped",
+				message: "Swagger 2.0 collectionFormat: \"tsv\" has no OpenAPI 3.x equivalent; dropping the keyword",
+				pointer,
+				detail: {
+					feature: "collectionFormat:tsv",
+					location: "header"
+				}
+			});
 			break;
 		case "pipes":
 			result.style = "pipeDelimited";
@@ -1143,29 +1264,15 @@ function normaliseSwaggerHeader(header) {
 	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.
-*/
-const REF_REWRITES = [
-	["#/definitions/", "#/components/schemas/"],
-	["#/parameters/", "#/components/parameters/"],
-	["#/responses/", "#/components/responses/"]
-];
-/**
 * Deep-rewrite $ref strings in a normalised Swagger 2.0 document
-* from Swagger 2.0 locations to OpenAPI 3.x locations.
-* Mutates the object in place \u2014 called only on the fresh clone
-* produced by normaliseSwagger2Document.
+* from Swagger 2.0 locations to OpenAPI 3.x locations using the
+* shared {@link rewriteSwaggerRefPrefix} mapping. Mutates the object
+* in place \u2014 called only on the fresh clone produced by
+* normaliseSwagger2Document.
 */
 function rewriteSwaggerRefs(node) {
 	if (!isObject(node)) return;
-	if (typeof node.$ref === "string") {
-		for (const [from, to] of REF_REWRITES) if (node.$ref.startsWith(from)) {
-			node.$ref = to + node.$ref.slice(from.length);
-			break;
-		}
-	}
+	if (typeof node.$ref === "string") node.$ref = rewriteSwaggerRefPrefix(node.$ref);
 	for (const value of Object.values(node)) if (isObject(value)) rewriteSwaggerRefs(value);
 	else if (Array.isArray(value)) for (const item of value) rewriteSwaggerRefs(item);
 }
@@ -1195,7 +1302,7 @@ const SWAGGER_OAUTH_FLOW_RENAME = {
 * (`unknown-security-scheme-type` diagnostic in the parser) handles
 * those cases.
 */
-function translateSwaggerSecurityScheme(scheme) {
+function translateSwaggerSecurityScheme(scheme, diagnostics, pointer = "", name) {
 	const type = scheme.type;
 	if (type === "basic") {
 		const result = {
@@ -1207,10 +1314,21 @@ function translateSwaggerSecurityScheme(scheme) {
 	}
 	if (type === "oauth2") {
 		const flowName = scheme.flow;
-		if (typeof flowName !== "string") return {
-			...scheme,
-			type: "oauth2"
-		};
+		if (typeof flowName !== "string") {
+			emitDiagnostic(diagnostics, {
+				code: "swagger-malformed-oauth-flow",
+				message: `Swagger 2.0 oauth2 security scheme${name !== void 0 ? ` "${name}"` : ""} is missing the required \`flow\` field; preserving the original shape verbatim`,
+				pointer,
+				detail: {
+					name,
+					flow: flowName
+				}
+			});
+			return {
+				...scheme,
+				type: "oauth2"
+			};
+		}
 		const renamedFlow = SWAGGER_OAUTH_FLOW_RENAME[flowName] ?? flowName;
 		const flowBody = {};
 		if (typeof scheme.authorizationUrl === "string") flowBody.authorizationUrl = scheme.authorizationUrl;
@@ -1227,24 +1345,6 @@ function translateSwaggerSecurityScheme(scheme) {
 	}
 	return { ...scheme };
 }
-/**
-* Recursively check whether any node in the supplied subtree carries an
-* `xml` annotation. Walks both objects and arrays so the check works for
-* schemas (definitions, parameter schemas, response schemas, request body
-* schemas) as well as operations and parameters that may carry `xml`
-* metadata at any depth.
-*/
-function hasXmlAnywhere(node) {
-	if (!isObject(node)) {
-		if (Array.isArray(node)) {
-			for (const item of node) if (hasXmlAnywhere(item)) return true;
-		}
-		return false;
-	}
-	if ("xml" in node) return true;
-	for (const value of Object.values(node)) if (hasXmlAnywhere(value)) return true;
-	return false;
-}
 //#endregion
 //#region src/core/normalise.ts
 /**
@@ -1432,17 +1532,24 @@ function collectDependencyStrings(items, property, keyword, ctx) {
 * After splitting, `dependencies` is removed from the node.
 *
 * When `ctx` is supplied, diagnostics are emitted for:
-* - `legacy-dependencies-split` once per node that contained the
-*   deprecated keyword (callers pass this only on draft paths where
-*   the keyword is unexpected, e.g. 2020-12).
+* - The supplied `legacyDiagnostic` code (if any) once per node that
+*   contained the deprecated keyword. Callers pass
+*   `legacy-dependencies-split-2019` on the 2019-09 path (the draft
+*   that introduced the split — authors should already have migrated)
+*   and `legacy-dependencies-split` on the defensive 2020-12 path.
 * - `dependent-required-invalid` for each array entry whose element is
 *   not a string.
+* - `dependencies-conflict` when both the legacy `dependencies` keyword
+*   and a pre-existing `dependentRequired`/`dependentSchemas` declare
+*   the same key with different values. The pre-existing modern
+*   keyword wins and the legacy value is discarded — silently
+*   overwriting would mask the author's bug.
 */
-function splitDependencies(node, ctx, emitLegacyDiagnostic) {
+function splitDependencies(node, ctx, legacyDiagnostic) {
 	const deps = node.dependencies;
 	if (!isObject(deps)) return;
-	if (emitLegacyDiagnostic && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
-		code: "legacy-dependencies-split",
+	if (legacyDiagnostic !== void 0 && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+		code: legacyDiagnostic,
 		message: "Legacy `dependencies` keyword was split into `dependentRequired`/`dependentSchemas`; `dependencies` was deprecated in Draft 2019-09",
 		pointer: appendPointer(ctx.pointer, "dependencies"),
 		detail: { keys: Object.keys(deps) }
@@ -1455,17 +1562,61 @@ function splitDependencies(node, ctx, emitLegacyDiagnostic) {
 	} else if (isObject(value)) schemaEntries[key] = value;
 	if (Object.keys(requiredEntries).length > 0) {
 		const existing = node.dependentRequired;
-		if (isObject(existing)) for (const [k, v] of Object.entries(requiredEntries)) existing[k] = v;
+		if (isObject(existing)) for (const [k, v] of Object.entries(requiredEntries)) {
+			if (k in existing) {
+				if (ctx !== void 0 && !arraysEqual(existing[k], v)) emitDiagnostic(ctx.diagnostics, {
+					code: "dependencies-conflict",
+					message: `Legacy \`dependencies.${k}\` conflicts with the pre-existing \`dependentRequired.${k}\`; keeping the modern keyword and discarding the legacy value`,
+					pointer: appendPointer(ctx.pointer, "dependencies"),
+					detail: {
+						key: k,
+						kept: existing[k],
+						discarded: v,
+						keyword: "dependentRequired"
+					}
+				});
+				continue;
+			}
+			existing[k] = v;
+		}
 		else node.dependentRequired = requiredEntries;
 	}
 	if (Object.keys(schemaEntries).length > 0) {
 		const existing = node.dependentSchemas;
-		if (isObject(existing)) for (const [k, v] of Object.entries(schemaEntries)) existing[k] = v;
+		if (isObject(existing)) for (const [k, v] of Object.entries(schemaEntries)) {
+			if (k in existing) {
+				if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+					code: "dependencies-conflict",
+					message: `Legacy \`dependencies.${k}\` conflicts with the pre-existing \`dependentSchemas.${k}\`; keeping the modern keyword and discarding the legacy value`,
+					pointer: appendPointer(ctx.pointer, "dependencies"),
+					detail: {
+						key: k,
+						kept: existing[k],
+						discarded: v,
+						keyword: "dependentSchemas"
+					}
+				});
+				continue;
+			}
+			existing[k] = v;
+		}
 		else node.dependentSchemas = schemaEntries;
 	}
 	delete node.dependencies;
 }
 /**
+* Compare two values that should both be string arrays. Returns true
+* when both are arrays of equal length holding the same strings in
+* the same order. Used to skip the `dependencies-conflict` diagnostic
+* when the legacy and modern keywords agree.
+*/
+function arraysEqual(a, b) {
+	if (!Array.isArray(a) || !Array.isArray(b)) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+/**
 * Emit diagnostics for any non-string entries inside a pre-existing
 * `dependentRequired` keyword. Used on draft paths where the author may
 * have already migrated to the Draft 2019-09 form but still produced
@@ -1563,7 +1714,7 @@ function applyDraft04Translations(node, ctx) {
 		delete node.id;
 	}
 	translateTupleItems(node);
-	splitDependencies(node, ctx, false);
+	splitDependencies(node, ctx, void 0);
 	validateDependentRequired(node, ctx);
 }
 /**
@@ -1616,7 +1767,7 @@ function normaliseDraft04NodeWithContext(node, ctx) {
 */
 function normaliseDraft06Or07NodeWithContext(node, ctx) {
 	translateTupleItems(node);
-	splitDependencies(node, ctx, false);
+	splitDependencies(node, ctx, void 0);
 	validateDependentRequired(node, ctx);
 	return node;
 }
@@ -1635,6 +1786,12 @@ function normaliseDraft06Or07NodeWithContext(node, ctx) {
 * `$recursiveAnchor` names are likewise preserved as `$anchor`.
 */
 function normaliseDraft201909NodeWithContext(node, ctx) {
+	if (node.$anchor === "__recursive__" && node.$recursiveAnchor !== true) emitDiagnostic(ctx.diagnostics, {
+		code: "recursive-anchor-collision",
+		message: `User-supplied \`$anchor: "${RECURSIVE_ANCHOR_SENTINEL}"\` collides with the canonical sentinel synthesised by the Draft 2019-09 \`$recursiveAnchor: true\` rewrite; lookups for this anchor may resolve to either declaration`,
+		pointer: appendPointer(ctx.pointer, "$anchor"),
+		detail: { anchor: RECURSIVE_ANCHOR_SENTINEL }
+	});
 	const recursiveRef = node.$recursiveRef;
 	if (typeof recursiveRef === "string") {
 		if (!recursiveRef.startsWith("#")) emitDiagnostic(ctx.diagnostics, {
@@ -1650,13 +1807,13 @@ function normaliseDraft201909NodeWithContext(node, ctx) {
 		delete node.$recursiveRef;
 	}
 	if (node.$recursiveAnchor === true) {
-		if (typeof node.$anchor !== "string") node.$anchor = "__recursive__";
+		if (typeof node.$anchor !== "string") node.$anchor = RECURSIVE_ANCHOR_SENTINEL;
 		delete node.$recursiveAnchor;
 	} else if (typeof node.$recursiveAnchor === "string") {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
 		delete node.$recursiveAnchor;
 	}
-	splitDependencies(node, ctx, false);
+	splitDependencies(node, ctx, "legacy-dependencies-split-2019");
 	validateDependentRequired(node, ctx);
 	return node;
 }
@@ -1680,7 +1837,8 @@ function normaliseDynamicRefNodeWithContext(node, ctx) {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$dynamicAnchor;
 		delete node.$dynamicAnchor;
 	}
-	splitDependencies(node, ctx, true);
+	translateTupleItems(node);
+	splitDependencies(node, ctx, "legacy-dependencies-split");
 	validateDependentRequired(node, ctx);
 	return node;
 }
@@ -1948,9 +2106,41 @@ function normaliseOpenApiSchemas(doc, version, diagnostics) {
 	}
 	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => {
 		let intermediate = schema;
-		if (dialectDraft !== void 0 && dialectDraft !== "draft-2020-12") intermediate = deepNormaliseWithContext(intermediate, selectDraftTransform(dialectDraft), buildRootContext(intermediate, diagnostics, dialectDraft));
+		const effectiveDraft = resolveSchemaLocalDialect(intermediate, diagnostics) ?? dialectDraft;
+		if (effectiveDraft !== void 0 && effectiveDraft !== "draft-2020-12") intermediate = deepNormaliseWithContext(intermediate, selectDraftTransform(effectiveDraft), buildRootContext(intermediate, diagnostics, effectiveDraft));
 		return resolveRelativeRefs(deepNormalise(intermediate, normaliseOpenApi30Discriminator), diagnostics);
 	});
 }
+/**
+* Resolve a Schema-Object-level `$schema` declaration to a
+* `JsonSchemaDraft`. Returns `undefined` when the keyword is absent or
+* its value is not a string; emits `unknown-json-schema-dialect` and
+* returns `undefined` when the value is a string that does not match
+* any supported draft URI. The caller falls back to the document-level
+* dialect (or 2020-12) in that case.
+*
+* Per OpenAPI 3.1 §4.7.5, the override applies to the Schema Object
+* and its subschemas. Nested overrides inside individual sub-schemas
+* are not currently honoured — the dispatch happens once at the top
+* of each Schema Object surfaced by `deepNormaliseOpenApiDoc`.
+*/
+function resolveSchemaLocalDialect(schema, diagnostics) {
+	const value = schema.$schema;
+	if (typeof value !== "string") return void 0;
+	const draft = matchJsonSchemaDraftUri(value);
+	if (draft === void 0) {
+		emitDiagnostic(diagnostics, {
+			code: "unknown-json-schema-dialect",
+			message: `Schema Object-level \`$schema\` URI "${value}" does not match a supported JSON Schema draft; falling back to the document dialect`,
+			pointer: "/$schema",
+			detail: {
+				uri: value,
+				level: "schema-object"
+			}
+		});
+		return;
+	}
+	return draft;
+}
 //#endregion
-export { normaliseOpenApiSchemas as a, applyDiscriminatorAllOfPrepass as c, normaliseOpenApi30Combined as d, normaliseOpenApi30Discriminator as f, normaliseJsonSchema as i, deepNormaliseOpenApi30Doc as l, deepNormaliseWithContext as n, selectDraftTransform as o, normaliseOpenApi30Node as p, normaliseDraft04Node as r, normaliseSwagger2Document as s, deepNormalise as t, deepNormaliseOpenApiDoc as u };
+export { normaliseJsonSchema as a, normaliseSwagger2Document as c, deepNormaliseOpenApiDoc as d, liftExampleToExamples as f, normaliseOpenApi30Node as h, normaliseDraft04Node as i, applyDiscriminatorAllOfPrepass as l, normaliseOpenApi30Discriminator as m, deepNormaliseWithContext as n, normaliseOpenApiSchemas as o, normaliseOpenApi30Combined as p, documentContainsKeyword as r, selectDraftTransform as s, deepNormalise as t, deepNormaliseOpenApi30Doc as u };