schema-components 1.21.0 → 1.22.0

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

@@ -29,6 +29,8 @@ function normaliseOpenApi30Node(node) {
 		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 (Array.isArray(node.anyOf)) {
 		node.anyOf = [...node.anyOf, nullOption];
 		delete node.nullable;
@@ -113,7 +115,13 @@ function normaliseOpenApi30Discriminator(node) {
 	}
 	if ("oneOf" in node) node.oneOf = normalisedComposite;
 	else if ("anyOf" in node) node.anyOf = normalisedComposite;
-	delete node.discriminator;
+	const extensions = {};
+	for (const [key, value] of Object.entries(discriminator)) if (key.startsWith("x-")) extensions[key] = value;
+	if (Object.keys(extensions).length > 0) node.discriminator = {
+		propertyName,
+		...extensions
+	};
+	else delete node.discriminator;
 	return node;
 }
 /**
@@ -480,7 +488,7 @@ function normaliseParameter(param, normaliseSchema) {
 	const content = param.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	if ("example" in result && !("examples" in result)) {
-		result.examples = [result.example];
+		result.examples = { default: { value: result.example } };
 		delete result.example;
 	} else if ("example" in result) delete result.example;
 	return result;
@@ -506,7 +514,7 @@ function normaliseHeader(header, normaliseSchema) {
 	const content = header.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	if ("example" in result && !("examples" in result)) {
-		result.examples = [result.example];
+		result.examples = { default: { value: result.example } };
 		delete result.example;
 	} else if ("example" in result) delete result.example;
 	return result;
@@ -579,9 +587,19 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 			version: "0.0.0"
 		}
 	};
-	if (typeof doc.host === "string" || typeof doc.basePath === "string" || Array.isArray(doc.schemes)) {
-		const host = typeof doc.host === "string" ? doc.host : "localhost";
-		const basePath = typeof doc.basePath === "string" ? doc.basePath : "/";
+	if (typeof doc.host !== "string") {
+		if (Array.isArray(doc.schemes) || typeof doc.basePath === "string") emitDiagnostic(diagnostics, {
+			code: "swagger-missing-host",
+			message: "Swagger 2.0 document declares schemes or basePath without host; skipping server URL synthesis",
+			pointer: "",
+			detail: {
+				hasSchemes: Array.isArray(doc.schemes),
+				hasBasePath: typeof doc.basePath === "string"
+			}
+		});
+	} else {
+		const host = doc.host;
+		const basePath = typeof doc.basePath === "string" ? doc.basePath : "";
 		const schemes = Array.isArray(doc.schemes) ? doc.schemes : ["https"];
 		result.servers = [{ url: `${typeof schemes[0] === "string" ? schemes[0] : "https"}://${host}${basePath}` }];
 	}
@@ -597,31 +615,62 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 	const parameters = doc.parameters;
 	const requestBodies = {};
 	if (isObject(parameters)) {
-		const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
+		const consumesResolution = resolveSwaggerContentTypes(void 0, doc.consumes);
+		const globalConsumes = consumesResolution.types;
 		const convertedParameters = {};
 		for (const [name, param] of Object.entries(parameters)) {
 			if (!isObject(param)) {
 				convertedParameters[name] = param;
 				continue;
 			}
-			const resolved = resolveSwaggerParameter(param, doc);
+			const resolution = resolveSwaggerParameter(param, doc);
+			if (resolution.kind === "cycle") {
+				emitDiagnostic(diagnostics, {
+					code: "swagger-cyclic-parameter-ref",
+					message: `Cyclic Swagger 2.0 parameter $ref "${resolution.ref}"; skipping entry`,
+					pointer: appendPointer(appendPointer("", "parameters"), name),
+					detail: {
+						ref: resolution.ref,
+						name
+					}
+				});
+				continue;
+			}
+			const resolved = resolution.param;
 			const location = resolved.in;
-			if (location === "body") requestBodies[name] = buildRequestBody(resolved, globalConsumes);
-			else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
-			else convertedParameters[name] = normaliseSwaggerParameter(resolved, doc);
+			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);
+			} else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
+			else {
+				const normalised = normaliseSwaggerParameter(resolved, doc, diagnostics, appendPointer(appendPointer("", "parameters"), name));
+				if (normalised !== void 0) convertedParameters[name] = normalised;
+			}
 		}
 		if (Object.keys(convertedParameters).length > 0) components.parameters = convertedParameters;
 	}
 	const responses = doc.responses;
 	if (isObject(responses)) {
-		const globalProduces = Array.isArray(doc.produces) ? doc.produces : ["application/json"];
+		const producesResolution = resolveSwaggerContentTypes(void 0, doc.produces);
 		const convertedResponses = {};
-		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, globalProduces) : response;
+		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, producesResolution.types, producesResolution.source, diagnostics, void 0, void 0, name) : response;
 		components.responses = convertedResponses;
 	}
 	if (Object.keys(requestBodies).length > 0) components.requestBodies = requestBodies;
 	const securityDefinitions = doc.securityDefinitions;
-	if (isObject(securityDefinitions)) components.securitySchemes = { ...securityDefinitions };
+	if (isObject(securityDefinitions)) {
+		const translated = {};
+		for (const [name, scheme] of Object.entries(securityDefinitions)) translated[name] = isObject(scheme) ? translateSwaggerSecurityScheme(scheme) : scheme;
+		components.securitySchemes = translated;
+	}
 	if (Object.keys(components).length > 0) result.components = components;
 	if (Array.isArray(doc.tags)) result.tags = doc.tags;
 	if (isObject(doc.externalDocs)) result.externalDocs = doc.externalDocs;
@@ -658,17 +707,29 @@ function normaliseSwaggerPaths(paths, doc, diagnostics) {
 			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);
+		if (Array.isArray(pathParams)) {
+			const paramsPointer = appendPointer(appendPointer(appendPointer("", "paths"), path), "parameters");
+			const out = [];
+			for (const [index, p] of pathParams.entries()) {
+				if (!isObject(p)) {
+					out.push(p);
+					continue;
+				}
+				const normalised = normaliseSwaggerParameter(p, doc, diagnostics, appendPointer(paramsPointer, String(index)));
+				if (normalised !== void 0) out.push(normalised);
+			}
+			normalisedPath.parameters = out;
+		}
 		result[path] = normalisedPath;
 	}
 	return result;
 }
 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"];
-	const produces = Array.isArray(operation.produces) ? operation.produces : globalProduces;
-	const consumes = Array.isArray(operation.consumes) ? operation.consumes : globalConsumes;
+	const consumesResolution = resolveSwaggerContentTypes(operation.consumes, doc.consumes);
+	const producesResolution = resolveSwaggerContentTypes(operation.produces, doc.produces);
+	const produces = producesResolution.types;
+	const consumes = consumesResolution.types;
 	for (const [key, value] of Object.entries(operation)) if (key !== "parameters" && key !== "responses" && key !== "produces" && key !== "consumes") result[key] = value;
 	const params = operation.parameters;
 	if (Array.isArray(params)) {
@@ -681,7 +742,17 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 				nonBodyParams.push(param);
 				continue;
 			}
-			const resolvedParam = resolveSwaggerParameter(param, doc);
+			const paramResolution = resolveSwaggerParameter(param, doc);
+			if (paramResolution.kind === "cycle") {
+				emitDiagnostic(diagnostics, {
+					code: "swagger-cyclic-parameter-ref",
+					message: `Cyclic Swagger 2.0 parameter $ref "${paramResolution.ref}"; skipping entry`,
+					pointer: appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"), String(index)),
+					detail: { ref: paramResolution.ref }
+				});
+				continue;
+			}
+			const resolvedParam = paramResolution.param;
 			const location = resolvedParam.in;
 			if (location === "body") {
 				if (bodyParam !== void 0) {
@@ -705,16 +776,51 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 					bodyParam = buildFormDataBody(resolvedParam, params);
 					usesFormData = true;
 				}
-			} else nonBodyParams.push(normaliseSwaggerParameter(resolvedParam, doc));
+			} else {
+				const normalised = normaliseSwaggerParameter(resolvedParam, doc, diagnostics, appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"), String(index)));
+				if (normalised !== void 0) nonBodyParams.push(normalised);
+			}
 		}
 		if (nonBodyParams.length > 0) result.parameters = nonBodyParams;
-		if (bodyParam !== void 0) result.requestBody = buildRequestBody(bodyParam, usesFormData ? formDataContentTypes(consumes) : consumes);
+		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
+				}
+			});
+			result.requestBody = buildRequestBody(bodyParam, bodyContentTypes);
+		}
 	}
 	const responses = operation.responses;
-	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces);
+	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces, producesResolution.source, diagnostics, path, method);
 	return result;
 }
 /**
+* Resolve a Swagger 2.0 `consumes` or `produces` array, recording
+* where the value came from so callers can decide whether to emit a
+* "missing content type" diagnostic. Per the Swagger 2.0 spec, absence
+* at BOTH levels means no body — not an implicit `application/json`.
+*/
+function resolveSwaggerContentTypes(operationLevel, documentLevel) {
+	if (Array.isArray(operationLevel)) return {
+		types: operationLevel,
+		source: "operation"
+	};
+	if (Array.isArray(documentLevel)) return {
+		types: documentLevel,
+		source: "document"
+	};
+	return {
+		types: ["application/json"],
+		source: "synthesised"
+	};
+}
+/**
 * 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
@@ -729,12 +835,77 @@ function formDataContentTypes(consumes) {
 	return ["multipart/form-data"];
 }
 /**
-* Resolve a Swagger parameter that may be a `$ref`.
+* Every JSON-Schema-compatible constraint keyword Swagger 2.0 allows on
+* a Parameter Object or Header Object alongside `type`/`format`. These
+* lift into the synthesised `schema` so consumers see the original
+* validation semantics under OAS 3.x's parameter shape.
+*
+* `allowEmptyValue` is included even though it is a Swagger 2.0
+* parameter-level keyword in the source (not a schema keyword) — OAS
+* 3.x defines it at the Parameter Object root, so the calling function
+* keeps it at the parameter root rather than copying it into `schema`.
+*/
+const SWAGGER_PARAM_SCHEMA_KEYWORDS = [
+	"enum",
+	"default",
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"multipleOf",
+	"minLength",
+	"maxLength",
+	"pattern",
+	"minItems",
+	"maxItems",
+	"uniqueItems"
+];
+/**
+* Set of every Swagger 2.0 parameter-root keyword that must be lifted
+* into the synthesised `schema` rather than copied onto the OAS 3.x
+* parameter root. Includes `type`, `format`, `items` (Swagger 2.0
+* parameter-shaped array element descriptor), `collectionFormat`
+* (handled separately by the caller as `style`/`explode`), and every
+* entry from {@link SWAGGER_PARAM_SCHEMA_KEYWORDS}.
+*/
+const PARAM_KEYWORDS_LIFTED_INTO_SCHEMA = new Set([
+	"type",
+	"format",
+	"items",
+	"collectionFormat",
+	...SWAGGER_PARAM_SCHEMA_KEYWORDS
+]);
+/**
+* Synthesise an OpenAPI 3.x `schema` object from a Swagger 2.0
+* parameter-shaped node (parameter or header). Copies `type`,
+* `format`, and every JSON-Schema-compatible constraint that Swagger
+* 2.0 places at the parameter root. Nested `items` is recursively
+* synthesised the same way so array element constraints survive.
+*/
+function buildSchemaFromSwaggerParameterShape(node) {
+	const schema = { type: node.type };
+	if (typeof node.format === "string") schema.format = node.format;
+	for (const keyword of SWAGGER_PARAM_SCHEMA_KEYWORDS) if (node[keyword] !== void 0) schema[keyword] = node[keyword];
+	if (isObject(node.items)) schema.items = buildSchemaFromSwaggerParameterShape(node.items);
+	return schema;
+}
+/**
+* Resolve a Swagger parameter that may be a `$ref`. Returns the
+* resolved parameter object, or a cycle marker so the caller can
+* 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 param;
-	if (visited.has(ref)) return param;
+	if (typeof ref !== "string" || !ref.startsWith("#/parameters/")) return {
+		kind: "ok",
+		param
+	};
+	if (visited.has(ref)) return {
+		kind: "cycle",
+		ref
+	};
 	const nextVisited = new Set(visited);
 	nextVisited.add(ref);
 	const name = ref.slice(13);
@@ -743,33 +914,55 @@ function resolveSwaggerParameter(param, doc, visited = /* @__PURE__ */ new Set()
 		const resolved = globalParams[name];
 		if (isObject(resolved)) {
 			if (typeof resolved.$ref === "string") return resolveSwaggerParameter(resolved, doc, nextVisited);
-			return resolved;
+			return {
+				kind: "ok",
+				param: resolved
+			};
 		}
 	}
-	return param;
+	return {
+		kind: "ok",
+		param
+	};
 }
 /**
 * Normalise a single Swagger parameter to OpenAPI 3.x form.
 */
-function normaliseSwaggerParameter(param, doc) {
+function normaliseSwaggerParameter(param, doc, diagnostics, pointer = "") {
 	if (typeof param.$ref === "string") {
-		const resolved = resolveSwaggerParameter(param, doc);
-		if (resolved !== param) return normaliseSwaggerParameter(resolved, doc);
+		const resolution = resolveSwaggerParameter(param, doc);
+		if (resolution.kind === "cycle") {
+			emitDiagnostic(diagnostics, {
+				code: "swagger-cyclic-parameter-ref",
+				message: `Cyclic Swagger 2.0 parameter $ref "${resolution.ref}"; skipping entry`,
+				pointer,
+				detail: { ref: resolution.ref }
+			});
+			return;
+		}
+		const resolved = resolution.param;
+		if (resolved !== param) return normaliseSwaggerParameter(resolved, doc, diagnostics, pointer);
 	}
 	const result = {};
 	for (const [key, value] of Object.entries(param)) {
-		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) continue;
 		result[key] = value;
 	}
-	if (typeof param.type === "string") {
-		const schema = { type: param.type };
-		if (typeof param.format === "string") schema.format = param.format;
-		if (param.enum !== void 0) schema.enum = param.enum;
-		if (param.default !== void 0) schema.default = param.default;
-		if (param.minimum !== void 0) schema.minimum = param.minimum;
-		if (param.maximum !== void 0) schema.maximum = param.maximum;
-		result.schema = schema;
-	}
+	if (typeof param.type === "string") if (param.type === "file" && param.in !== "formData") {
+		emitDiagnostic(diagnostics, {
+			code: "swagger-invalid-file-parameter",
+			message: `Swagger 2.0 type: "file" is only valid under in: formData; converting to { type: "string", format: "binary" }`,
+			pointer,
+			detail: {
+				name: param.name,
+				in: param.in
+			}
+		});
+		result.schema = {
+			type: "string",
+			format: "binary"
+		};
+	} else result.schema = buildSchemaFromSwaggerParameterShape(param);
 	const cf = param.collectionFormat;
 	if (typeof cf === "string") switch (cf) {
 		case "csv":
@@ -860,14 +1053,14 @@ function resolveSwaggerResponse(response, doc, visited = /* @__PURE__ */ new Set
 	}
 	return response;
 }
-function normaliseSwaggerResponses(responses, doc, produces) {
+function normaliseSwaggerResponses(responses, doc, produces, producesSource, diagnostics, path, method) {
 	const result = {};
 	for (const [code, response] of Object.entries(responses)) {
 		if (!isObject(response)) {
 			result[code] = response;
 			continue;
 		}
-		result[code] = normaliseSwaggerSingleResponse(response, doc, produces);
+		result[code] = normaliseSwaggerSingleResponse(response, doc, produces, producesSource, diagnostics, path, method, code);
 	}
 	return result;
 }
@@ -880,7 +1073,7 @@ function normaliseSwaggerResponses(responses, doc, produces) {
 * operation’s `responses` map or under document-level `responses`
 * (now `components.responses`).
 */
-function normaliseSwaggerSingleResponse(response, doc, produces) {
+function normaliseSwaggerSingleResponse(response, doc, produces, producesSource = "synthesised", diagnostics, path, method, statusCode) {
 	const resolved = resolveSwaggerResponse(response, doc);
 	const normalised = {};
 	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") normalised[key] = value;
@@ -890,6 +1083,15 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 		const contentTypes = produces.length > 0 ? produces : ["application/json"];
 		for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
 		normalised.content = content;
+		if (producesSource === "synthesised") emitDiagnostic(diagnostics, {
+			code: "swagger-missing-consumes",
+			message: "Response declares a schema but neither operation-level nor document-level `produces` is set; defaulting to application/json",
+			pointer: path !== void 0 && method !== void 0 && statusCode !== void 0 ? appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "responses"), statusCode) : "",
+			detail: {
+				level: "response",
+				statusCode
+			}
+		});
 	}
 	const headers = resolved.headers;
 	if (isObject(headers)) {
@@ -915,18 +1117,10 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 function normaliseSwaggerHeader(header) {
 	const result = {};
 	for (const [key, value] of Object.entries(header)) {
-		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) 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;
-	}
+	if (typeof header.type === "string") result.schema = buildSchemaFromSwaggerParameterShape(header);
 	const cf = header.collectionFormat;
 	if (typeof cf === "string") switch (cf) {
 		case "csv":
@@ -976,6 +1170,64 @@ function rewriteSwaggerRefs(node) {
 	else if (Array.isArray(value)) for (const item of value) rewriteSwaggerRefs(item);
 }
 /**
+* Map from Swagger 2.0 `oauth2.flow` (singular) to the OAS 3.x flow key
+* under `flows.<key>`. `application` and `accessCode` were renamed in
+* OAS 3.x to align with RFC 6749 grant-type names.
+*/
+const SWAGGER_OAUTH_FLOW_RENAME = {
+	implicit: "implicit",
+	password: "password",
+	application: "clientCredentials",
+	accessCode: "authorizationCode"
+};
+/**
+* Translate a Swagger 2.0 Security Scheme Object into an OpenAPI 3.x
+* Security Scheme Object. The Swagger 2.0 spec defines three types:
+*
+* - `basic` — has no other fields; OAS 3.x represents this as
+*   `{ type: "http", scheme: "basic" }`.
+* - `apiKey` — carries `name`/`in`; OAS 3.x uses the same shape.
+* - `oauth2` — carries `flow`/`authorizationUrl`/`tokenUrl`/`scopes` at
+*   the root. OAS 3.x nests these under `flows.<name>` where the flow
+*   name maps via {@link SWAGGER_OAUTH_FLOW_RENAME}.
+*
+* Unknown `type` values pass through verbatim — downstream validation
+* (`unknown-security-scheme-type` diagnostic in the parser) handles
+* those cases.
+*/
+function translateSwaggerSecurityScheme(scheme) {
+	const type = scheme.type;
+	if (type === "basic") {
+		const result = {
+			type: "http",
+			scheme: "basic"
+		};
+		if (typeof scheme.description === "string") result.description = scheme.description;
+		return result;
+	}
+	if (type === "oauth2") {
+		const flowName = scheme.flow;
+		if (typeof flowName !== "string") return {
+			...scheme,
+			type: "oauth2"
+		};
+		const renamedFlow = SWAGGER_OAUTH_FLOW_RENAME[flowName] ?? flowName;
+		const flowBody = {};
+		if (typeof scheme.authorizationUrl === "string") flowBody.authorizationUrl = scheme.authorizationUrl;
+		if (typeof scheme.tokenUrl === "string") flowBody.tokenUrl = scheme.tokenUrl;
+		if (typeof scheme.refreshUrl === "string") flowBody.refreshUrl = scheme.refreshUrl;
+		const scopes = scheme.scopes;
+		flowBody.scopes = isObject(scopes) ? { ...scopes } : {};
+		const result = {
+			type: "oauth2",
+			flows: { [renamedFlow]: flowBody }
+		};
+		if (typeof scheme.description === "string") result.description = scheme.description;
+		return result;
+	}
+	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
@@ -1075,24 +1327,34 @@ function deepNormalise(schema, transform, visited = /* @__PURE__ */ new WeakSet(
 	} else result[key] = value;
 	return result;
 }
+/**
+* Construct a child {@link NodeContext} that descends to `segment`,
+* preserving document-level flags (`documentHasDynamicAnchor`,
+* `documentHasRecursiveAnchor`, `declaredDraft`). Centralising the copy
+* keeps the recursion in `deepNormaliseWithContext` from drifting from
+* the {@link NodeContext} shape.
+*/
+function childContext(ctx, segment) {
+	return {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, segment),
+		documentHasDynamicAnchor: ctx.documentHasDynamicAnchor,
+		documentHasRecursiveAnchor: ctx.documentHasRecursiveAnchor,
+		declaredDraft: ctx.declaredDraft
+	};
+}
 function normaliseArrayWithContext(items, transform, ctx) {
 	const result = [];
 	for (let i = 0; i < items.length; i++) {
 		const item = items[i];
-		if (isObject(item)) result.push(deepNormaliseWithContext(item, transform, {
-			diagnostics: ctx.diagnostics,
-			pointer: appendPointer(ctx.pointer, String(i))
-		}));
+		if (isObject(item)) result.push(deepNormaliseWithContext(item, transform, childContext(ctx, String(i))));
 		else result.push(item);
 	}
 	return result;
 }
 function normaliseSubSchemaMapWithContext(map, transform, ctx) {
 	const result = {};
-	for (const [k, v] of Object.entries(map)) if (isObject(v)) result[k] = deepNormaliseWithContext(v, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, k)
-	});
+	for (const [k, v] of Object.entries(map)) if (isObject(v)) result[k] = deepNormaliseWithContext(v, transform, childContext(ctx, k));
 	else result[k] = v;
 	return result;
 }
@@ -1108,34 +1370,16 @@ function normaliseSubSchemaMapWithContext(map, transform, ctx) {
 function deepNormaliseWithContext(schema, transform, ctx) {
 	const node = transform({ ...schema }, ctx);
 	const result = {};
-	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMapWithContext(value, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, key)
-	});
-	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArrayWithContext(value, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, key)
-	});
-	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormaliseWithContext(value, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, key)
-	});
-	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArrayWithContext(value, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, key)
-	});
-	else if (isObject(value)) result[key] = deepNormaliseWithContext(value, transform, {
-		diagnostics: ctx.diagnostics,
-		pointer: appendPointer(ctx.pointer, key)
-	});
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMapWithContext(value, transform, childContext(ctx, key));
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArrayWithContext(value, transform, childContext(ctx, key));
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormaliseWithContext(value, transform, childContext(ctx, key));
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArrayWithContext(value, transform, childContext(ctx, key));
+	else if (isObject(value)) result[key] = deepNormaliseWithContext(value, transform, childContext(ctx, key));
 	else result[key] = value;
 	else if (key === "dependencies" && isObject(value)) {
 		const normalised = {};
-		const depsPointer = appendPointer(ctx.pointer, key);
-		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormaliseWithContext(dv, transform, {
-			diagnostics: ctx.diagnostics,
-			pointer: appendPointer(depsPointer, dk)
-		});
+		const depsContext = childContext(ctx, key);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormaliseWithContext(dv, transform, childContext(depsContext, dk));
 		else normalised[dk] = dv;
 		result[key] = normalised;
 	} else result[key] = value;
@@ -1391,8 +1635,18 @@ function normaliseDraft06Or07NodeWithContext(node, ctx) {
 * `$recursiveAnchor` names are likewise preserved as `$anchor`.
 */
 function normaliseDraft201909NodeWithContext(node, ctx) {
-	if (typeof node.$recursiveRef === "string") {
-		node.$ref = node.$recursiveRef;
+	const recursiveRef = node.$recursiveRef;
+	if (typeof recursiveRef === "string") {
+		if (!recursiveRef.startsWith("#")) emitDiagnostic(ctx.diagnostics, {
+			code: "dynamic-ref-degraded",
+			message: `Cross-document \`$recursiveRef\` "${recursiveRef}" rewritten to a static \`$ref\`; dynamic-scope resolution is not preserved`,
+			pointer: appendPointer(ctx.pointer, "$recursiveRef"),
+			detail: {
+				keyword: "$recursiveRef",
+				ref: recursiveRef
+			}
+		});
+		node.$ref = recursiveRef;
 		delete node.$recursiveRef;
 	}
 	if (node.$recursiveAnchor === true) {
@@ -1402,12 +1656,24 @@ function normaliseDraft201909NodeWithContext(node, ctx) {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
 		delete node.$recursiveAnchor;
 	}
+	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 	return node;
 }
 function normaliseDynamicRefNodeWithContext(node, ctx) {
-	if (typeof node.$dynamicRef === "string") {
-		node.$ref = node.$dynamicRef;
+	const dynamicRef = node.$dynamicRef;
+	if (typeof dynamicRef === "string") {
+		const crossDocument = !dynamicRef.startsWith("#");
+		if (crossDocument || ctx.documentHasDynamicAnchor) emitDiagnostic(ctx.diagnostics, {
+			code: "dynamic-ref-degraded",
+			message: crossDocument ? `Cross-document \`$dynamicRef\` "${dynamicRef}" rewritten to a static \`$ref\`; dynamic-scope resolution is not preserved` : `\`$dynamicRef\` "${dynamicRef}" rewritten to a static \`$ref\` in a document declaring \`$dynamicAnchor\`; dynamic-scope resolution is not preserved`,
+			pointer: appendPointer(ctx.pointer, "$dynamicRef"),
+			detail: {
+				keyword: "$dynamicRef",
+				ref: dynamicRef
+			}
+		});
+		node.$ref = dynamicRef;
 		delete node.$dynamicRef;
 	}
 	if (typeof node.$dynamicAnchor === "string") {
@@ -1419,6 +1685,63 @@ function normaliseDynamicRefNodeWithContext(node, ctx) {
 	return node;
 }
 /**
+* Pick the per-node transform that normalises a single Schema Object to
+* canonical Draft 2020-12 form for the supplied draft. Exposed so the
+* OpenAPI 3.1 path can honour a non-default `jsonSchemaDialect`
+* declaration by routing each Schema Object through the matching
+* transform without re-implementing the dispatch.
+*/
+function selectDraftTransform(draft) {
+	switch (draft) {
+		case "draft-04": return normaliseDraft04NodeWithContext;
+		case "draft-06":
+		case "draft-07": return normaliseDraft06Or07NodeWithContext;
+		case "draft-2019-09": return normaliseDraft201909NodeWithContext;
+		case "draft-2020-12": return normaliseDynamicRefNodeWithContext;
+	}
+}
+/**
+* Scan a JSON document body for the presence of a named keyword
+* anywhere in the structure. Walks both arrays and objects without
+* regard to schema-vs-data position — the caller is responsible for
+* passing a keyword whose presence is meaningful at any depth.
+*
+* Cycle-safe: cyclic references introduced by the OpenAPI bundler's
+* `structuredClone` of external refs are short-circuited via the
+* `visited` set so the scan terminates.
+*/
+function documentContainsKeyword(value, keyword, visited = /* @__PURE__ */ new WeakSet()) {
+	if (Array.isArray(value)) {
+		if (visited.has(value)) return false;
+		visited.add(value);
+		for (const item of value) if (documentContainsKeyword(item, keyword, visited)) return true;
+		return false;
+	}
+	if (isObject(value)) {
+		if (visited.has(value)) return false;
+		visited.add(value);
+		if (keyword in value) return true;
+		for (const v of Object.values(value)) if (documentContainsKeyword(v, keyword, visited)) return true;
+		return false;
+	}
+	return false;
+}
+/**
+* Build a root {@link NodeContext} for a document being normalised.
+* Pre-scans for `$dynamicAnchor` and `$recursiveAnchor` so per-node
+* transforms can decide whether a `$dynamicRef`/`$recursiveRef`
+* rewrite needs a `dynamic-ref-degraded` diagnostic.
+*/
+function buildRootContext(schema, diagnostics, declaredDraft) {
+	return {
+		diagnostics,
+		pointer: "",
+		documentHasDynamicAnchor: documentContainsKeyword(schema, "$dynamicAnchor"),
+		documentHasRecursiveAnchor: documentContainsKeyword(schema, "$recursiveAnchor"),
+		declaredDraft
+	};
+}
+/**
 * Normalise a JSON Schema to canonical Draft 2020-12 form.
 * Deep-clones the input — the original is never mutated.
 *
@@ -1428,27 +1751,8 @@ function normaliseDynamicRefNodeWithContext(node, ctx) {
 * `dependencies` reaching the 2020-12 path).
 */
 function normaliseJsonSchema(schema, draft, diagnostics) {
-	const ctx = {
-		diagnostics,
-		pointer: ""
-	};
-	let normalised;
-	switch (draft) {
-		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":
-			normalised = deepNormaliseWithContext(schema, normaliseDraft06Or07NodeWithContext, ctx);
-			break;
-	}
-	return resolveRelativeRefs(normalised, diagnostics);
+	const ctx = buildRootContext(schema, diagnostics, draft);
+	return resolveRelativeRefs(deepNormaliseWithContext(schema, selectDraftTransform(draft), ctx), diagnostics);
 }
 /**
 * Parse a string as an absolute URI, returning `undefined` when it has
@@ -1486,6 +1790,29 @@ function stripFragment(url) {
 	return clone.toString();
 }
 /**
+* Emit an `invalid-id-fragment` diagnostic when an `$id` value carries
+* a fragment that will be stripped during base-URI resolution. Per
+* JSON Schema 2020-12 §8.2.1, the URI in `$id` MUST NOT contain a
+* non-empty fragment (an empty `#` fragment is permitted for historical
+* reasons but conveys nothing). Stripping it silently loses authoring
+* intent — the caller almost certainly meant to declare an `$anchor`
+* or sibling identifier instead.
+*/
+function reportFragmentInId(value, url, pointer, diagnostics) {
+	if (diagnostics === void 0) return;
+	if (typeof value !== "string") return;
+	if (url.hash.length === 0) return;
+	emitDiagnostic(diagnostics, {
+		code: "invalid-id-fragment",
+		message: `\`$id\` URI "${value}" includes the fragment "${url.hash}", which is not permitted by JSON Schema §8.2.1; the fragment is stripped before use`,
+		pointer: appendPointer(pointer, "$id"),
+		detail: {
+			id: value,
+			fragment: url.hash
+		}
+	});
+}
+/**
 * 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
@@ -1519,7 +1846,10 @@ function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostic
 	const nodeId = node.$id;
 	if (typeof nodeId === "string" && nodeId.length > 0) {
 		const resolved = resolveAgainst(nodeId, currentBase);
-		if (resolved !== void 0) nextBase = stripFragment(resolved);
+		if (resolved !== void 0) {
+			reportFragmentInId(nodeId, resolved, pointer, diagnostics);
+			nextBase = stripFragment(resolved);
+		}
 	}
 	const result = {};
 	for (const [key, value] of Object.entries(node)) {
@@ -1588,6 +1918,24 @@ function rewriteRef(ref, currentBase, docBase, pointer, diagnostics) {
 function normaliseOpenApiSchemas(doc, version, diagnostics) {
 	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics);
 	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(applyDiscriminatorAllOfPrepass(doc), deepNormalise);
+	if (!isOpenApi31(version)) {
+		const rawOpenApi = typeof doc.openapi === "string" ? doc.openapi : void 0;
+		const rawSwagger = typeof doc.swagger === "string" ? doc.swagger : void 0;
+		const versionLabel = rawOpenApi ?? rawSwagger ?? `${String(version.major)}.${String(version.minor)}.${String(version.patch)}`;
+		const pointer = rawOpenApi !== void 0 ? "/openapi" : "/swagger";
+		emitDiagnostic(diagnostics, {
+			code: "unknown-openapi-version",
+			message: `Unsupported OpenAPI/Swagger version "${versionLabel}"; falling back to the OpenAPI 3.1 pipeline`,
+			pointer,
+			detail: {
+				version: versionLabel,
+				major: version.major,
+				minor: version.minor,
+				patch: version.patch
+			}
+		});
+	}
+	let dialectDraft;
 	if (isOpenApi31(version)) {
 		const dialect = readJsonSchemaDialect(doc);
 		if (dialect.kind === "unknown") emitDiagnostic(diagnostics, {
@@ -1596,8 +1944,13 @@ function normaliseOpenApiSchemas(doc, version, diagnostics) {
 			pointer: "/jsonSchemaDialect",
 			detail: { uri: dialect.uri }
 		});
+		else if (dialect.kind === "known") dialectDraft = dialect.draft;
 	}
-	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => resolveRelativeRefs(deepNormalise(schema, normaliseOpenApi30Discriminator), 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));
+		return resolveRelativeRefs(deepNormalise(intermediate, normaliseOpenApi30Discriminator), diagnostics);
+	});
 }
 //#endregion
-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 };
+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 };