schema-components 1.17.0 → 1.18.1

package/dist/html/renderers.mjs

@@ -1,3 +1,4 @@
+import { sortFieldsByOrder } from "../core/fieldOrder.mjs";
 import { h, raw, serialize } from "./html.mjs";
 import { ariaDescribedByAttrs, ariaLabelAttrs, ariaReadonlyAttrs, ariaRequiredAttrs, buildHintElement, buildInputId, requiredIndicator } from "./a11y.mjs";
 //#region src/html/renderers.ts
@@ -7,11 +8,12 @@ function dateInputType(format) {
 	if (format === "date-time" || format === "datetime") return "datetime-local";
 }
 /**
-* Normalise a dot-separated path into a valid, `sc-` prefixed HTML ID.
-* Dots in paths (from nested objects) become hyphens.
+* Normalise a structural path into a valid, `sc-` prefixed HTML ID.
+* Dots (object nesting) and brackets (array indices) become hyphens so
+* the id remains a valid CSS selector and predictable in test queries.
 */
 function fieldId(path) {
-	return `sc-${path.replace(/\./g, "-")}`;
+	return `sc-${path.replace(/[.[\]]+/g, "-").replace(/-+$/g, "")}`;
 }
 function renderStringHtml(props) {
 	if (props.readOnly) return serialize(renderStringReadOnly(props));
@@ -134,7 +136,8 @@ function renderEnumEditable(props) {
 	const enumValue = typeof props.value === "string" ? props.value : "";
 	const id = fieldId(props.path);
 	const selectedValue = props.writeOnly ? "" : enumValue;
-	const optionNodes = [h("option", { value: "" }, "Select…"), ...(props.enumValues ?? []).map((v) => {
+	const enumValues = props.tree.type === "enum" ? props.tree.enumValues : [];
+	const optionNodes = [h("option", { value: "" }, "Select…"), ...enumValues.map((v) => {
 		const display = v === null ? "null" : typeof v === "string" ? v : String(v);
 		const attrs = { value: display };
 		if (display === selectedValue) attrs.selected = true;
@@ -152,22 +155,20 @@ function renderObjectHtml(props) {
 	return serialize(renderObjectNode(props));
 }
 function renderObjectNode(props) {
-	const fields = props.fields;
-	if (fields === void 0) return "";
+	if (props.tree.type !== "object") return "";
+	const fields = props.tree.fields;
 	const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 	const obj = isRecord(props.value) ? props.value : {};
 	const descriptionText = typeof props.meta.description === "string" ? props.meta.description : void 0;
 	const legend = descriptionText !== void 0 ? h("legend", {}, descriptionText) : void 0;
-	const sortedEntries = Object.entries(fields).sort((a, b) => {
-		return (typeof a[1].meta.order === "number" ? a[1].meta.order : Infinity) - (typeof b[1].meta.order === "number" ? b[1].meta.order : Infinity);
-	}).filter(([, field]) => field.meta.visible !== false);
+	const sortedEntries = sortFieldsByOrder(fields).filter(([, field]) => field.meta.visible !== false);
 	if (props.readOnly) {
 		const children = [];
 		if (legend !== void 0) children.push(legend);
 		for (const [key, field] of sortedEntries) {
 			const label = typeof field.meta.description === "string" ? field.meta.description : key;
 			const childValue = obj[key];
-			const childHtml = props.renderChild(field, childValue, props.path ? `${props.path}.${key}` : key);
+			const childHtml = props.renderChild(field, childValue, key);
 			children.push(h("dt", { class: "sc-label" }, label));
 			children.push(h("dd", { class: "sc-value" }, raw(childHtml)));
 		}
@@ -180,9 +181,8 @@ function renderObjectNode(props) {
 	for (const [key, field] of sortedEntries) {
 		const label = typeof field.meta.description === "string" ? field.meta.description : key;
 		const fieldId = buildInputId(props.path, key);
-		const childPath = props.path ? `${props.path}.${key}` : key;
 		const childValue = obj[key];
-		const childHtml = props.renderChild(field, childValue, childPath);
+		const childHtml = props.renderChild(field, childValue, key);
 		const required = requiredIndicator(field);
 		const labelContent = [label];
 		if (required !== void 0) labelContent.push(required);
@@ -203,24 +203,20 @@ function renderArrayHtml(props) {
 }
 function renderArrayNode(props) {
 	const arr = Array.isArray(props.value) ? props.value : [];
-	const element = props.element;
+	const element = props.tree.type === "array" ? props.tree.element : void 0;
 	if (element === void 0) return "";
-	const items = arr.map((item) => {
-		return h("li", { class: "sc-item" }, raw(props.renderChild(element, item)));
-	});
-	if (props.readOnly) return h("ul", { class: "sc-array" }, ...items);
-	return h("div", { class: "sc-array" }, ...arr.map((item) => {
-		return h("div", {}, raw(props.renderChild(element, item)));
-	}));
+	const childHtmls = arr.map((item, i) => props.renderChild(element, item, `[${String(i)}]`));
+	if (props.readOnly) return h("ul", { class: "sc-array" }, ...childHtmls.map((childHtml) => h("li", { class: "sc-item" }, raw(childHtml))));
+	return h("div", { class: "sc-array" }, ...childHtmls.map((childHtml) => h("div", {}, raw(childHtml))));
 }
 function renderRecordHtml(props) {
 	return serialize(renderRecordNode(props));
 }
 function renderRecordNode(props) {
+	if (props.tree.type !== "record") return "";
 	const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 	const obj = isRecord(props.value) ? props.value : {};
-	const valueType = props.valueType;
-	if (valueType === void 0) return "";
+	const valueType = props.tree.valueType;
 	const attrs = {
 		class: "sc-record",
 		role: "group"
@@ -242,12 +238,13 @@ function renderRecordNode(props) {
 	return h("div", attrs, ...children);
 }
 function renderLiteralHtml(props) {
-	const values = props.literalValues;
-	if (values === void 0 || values.length === 0) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
+	if (props.tree.type !== "literal") return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
+	const values = props.tree.literalValues;
+	if (values.length === 0) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 	return serialize(h("span", { class: "sc-value" }, values.map((v) => v === null ? "null" : String(v)).join(", ")));
 }
 function renderUnionHtml(props) {
-	const options = props.options;
+	const options = props.tree.type === "union" || props.tree.type === "discriminatedUnion" ? props.tree.options : void 0;
 	if (options === void 0 || options.length === 0) {
 		if (props.value === void 0 || props.value === null) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 		return serialize(h("span", { class: "sc-value" }, JSON.stringify(props.value)));
@@ -259,8 +256,8 @@ function renderUnionHtml(props) {
 	return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 }
 function renderDiscriminatedUnionHtml(props) {
-	const options = props.options;
-	const discriminator = props.discriminator;
+	const options = props.tree.type === "discriminatedUnion" ? props.tree.options : void 0;
+	const discriminator = props.tree.type === "discriminatedUnion" ? props.tree.discriminator : void 0;
 	if (options === void 0 || options.length === 0) {
 		if (props.value === void 0 || props.value === null) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 		return serialize(h("span", { class: "sc-value" }, JSON.stringify(props.value)));
@@ -289,7 +286,9 @@ function renderDiscriminatedUnionHtml(props) {
 		if (activeOption !== void 0) return props.renderChild(activeOption, props.value);
 		return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 	}
-	const panelId = `sc-${props.path}-panel`;
+	const baseId = fieldId(props.path);
+	const panelId = `${baseId}-panel`;
+	const tabId = (i) => `${baseId}-tab-${String(i)}`;
 	const children = [h("div", {
 		role: "tablist",
 		class: "sc-tabs",
@@ -299,7 +298,7 @@ function renderDiscriminatedUnionHtml(props) {
 			type: "button",
 			role: "tab",
 			class: i === activeIndex ? "sc-tab sc-tab--active" : "sc-tab",
-			id: `sc-${props.path}-tab-${String(i)}`,
+			id: tabId(i),
 			"aria-selected": i === activeIndex ? "true" : void 0,
 			"aria-controls": panelId,
 			tabindex: i === activeIndex ? "0" : "-1"
@@ -310,7 +309,7 @@ function renderDiscriminatedUnionHtml(props) {
 		children.push(h("div", {
 			role: "tabpanel",
 			id: panelId,
-			"aria-labelledby": `sc-${props.path}-tab-${String(activeIndex)}`
+			"aria-labelledby": tabId(activeIndex)
 		}, raw(childHtml)));
 	}
 	return serialize(h("div", { class: "sc-discriminated-union" }, ...children));
@@ -335,7 +334,7 @@ function renderFileHtml(props) {
 	return serialize(h("input", attrs));
 }
 function renderRecursiveHtml(props) {
-	const refTarget = props.refTarget ?? "";
+	const refTarget = props.tree.type === "recursive" ? props.tree.refTarget : "";
 	return serialize(h("fieldset", { class: "sc-recursive" }, `↻ ${typeof props.meta.description === "string" ? props.meta.description : refTarget} (recursive)`));
 }
 function renderUnknownHtml(props) {
@@ -354,9 +353,9 @@ function renderUnknownHtml(props) {
 	return serialize(h("input", attrs));
 }
 function renderTupleHtml(props) {
+	if (props.tree.type !== "tuple") return renderUnknownHtml(props);
 	const arr = Array.isArray(props.value) ? props.value : [];
-	const prefixItems = props.prefixItems;
-	if (prefixItems === void 0) return renderUnknownHtml(props);
+	const prefixItems = props.tree.prefixItems;
 	const children = [];
 	for (let i = 0; i < prefixItems.length; i++) {
 		const itemValue = arr[i];
@@ -369,9 +368,11 @@ function renderTupleHtml(props) {
 }
 function renderConditionalHtml(props) {
 	const children = [];
-	if (props.ifClause !== void 0) children.push(h("div", { class: "sc-conditional-if" }, raw("if: ...")));
-	if (props.thenClause !== void 0) children.push(h("div", { class: "sc-conditional-then" }, raw("then: ...")));
-	if (props.elseClause !== void 0) children.push(h("div", { class: "sc-conditional-else" }, raw("else: ...")));
+	if (props.tree.type === "conditional") {
+		children.push(h("div", { class: "sc-conditional-if" }, raw("if: ...")));
+		if (props.tree.thenClause !== void 0) children.push(h("div", { class: "sc-conditional-then" }, raw("then: ...")));
+		if (props.tree.elseClause !== void 0) children.push(h("div", { class: "sc-conditional-else" }, raw("else: ...")));
+	}
 	return serialize(h("div", { class: "sc-conditional" }, ...children));
 }
 function renderNegationHtml(props) {

package/dist/html/streamRenderers.d.mts

@@ -1,5 +1,5 @@
 import { M as WalkedField } from "../types-D_5ST7SS.mjs";
-import { o as HtmlResolver } from "../renderer-B3s8o2B8.mjs";
+import { o as HtmlResolver } from "../renderer-BAGoX4AK.mjs";
 import { HtmlElement } from "./html.mjs";
 
 //#region src/html/streamRenderers.d.ts

package/dist/html/streamRenderers.mjs

@@ -14,27 +14,16 @@ function yieldClose(el) {
 }
 function renderLeaf(tree, value, mergedResolver, path) {
 	const renderFn = getHtmlRenderFn(tree.type, mergedResolver);
-	if (renderFn !== void 0) {
-		const props = {
-			value,
-			readOnly: tree.editability === "presentation",
-			writeOnly: tree.editability === "input",
-			meta: tree.meta,
-			constraints: tree.constraints,
-			path,
-			tree,
-			renderChild: () => ""
-		};
-		if (tree.type === "enum") props.enumValues = tree.enumValues;
-		if (tree.type === "literal") props.literalValues = tree.literalValues;
-		if (tree.type === "array" && tree.element !== void 0) props.element = tree.element;
-		if (tree.type === "object") props.fields = tree.fields;
-		if (tree.type === "union") props.options = tree.options;
-		if (tree.type === "discriminatedUnion") props.discriminator = tree.discriminator;
-		if (tree.type === "record") props.keyType = tree.keyType;
-		if (tree.type === "record") props.valueType = tree.valueType;
-		return renderFn(props);
-	}
+	if (renderFn !== void 0) return renderFn({
+		value,
+		readOnly: tree.editability === "presentation",
+		writeOnly: tree.editability === "input",
+		meta: tree.meta,
+		constraints: tree.constraints,
+		path,
+		tree,
+		renderChild: () => ""
+	});
 	if (value === void 0 || value === null) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
 	return serialize(h("span", { class: "sc-value" }, typeof value === "string" ? value : JSON.stringify(value)));
 }

package/dist/openapi/ApiSecurity.mjs

@@ -13,7 +13,7 @@ function ApiSecurity({ requirements, schemes }) {
 						"data-security-name": true,
 						children: req.name
 					}),
-					scheme !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+					scheme !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [scheme.type !== void 0 && /* @__PURE__ */ jsx("span", {
 						"data-security-type": true,
 						children: scheme.type
 					}), scheme.description && /* @__PURE__ */ jsx("span", {

package/dist/openapi/bundle.d.mts

@@ -34,13 +34,18 @@ type BundleResolver = (uri: string) => unknown;
  *
  * Walks every $ref in the document. For external refs (not starting with `#`),
  * calls the resolver to fetch the external document, extracts the referenced
- * schema, inlines it into `components.schemas` with a synthesised name, and
- * rewrites the $ref to point to the inlined copy.
+ * schema, inlines it into `components.schemas` under a synthesised name, and
+ * rewrites the original $ref to point at the new internal location
+ * (`#/components/schemas/<name>`).
+ *
+ * Identical external refs share a single entry — the second occurrence of
+ * the same `(uri, fragment)` pair reuses the name produced for the first.
+ * Name collisions between different refs are resolved by suffixing a counter.
  *
  * The resolver is called once per unique URI and the result is cached.
  *
- * Returns a deep-cloned document with all external refs resolved.
- * The original document is never mutated.
+ * Returns a deep-cloned document with all external refs replaced by internal
+ * refs. The original document is never mutated.
  */
 declare function bundleOpenApiDoc(doc: Record<string, unknown>, resolver: BundleResolver): Promise<Record<string, unknown>>;
 //#endregion

package/dist/openapi/bundle.mjs

@@ -29,28 +29,38 @@ import { isObject } from "../core/guards.mjs";
 *
 * Walks every $ref in the document. For external refs (not starting with `#`),
 * calls the resolver to fetch the external document, extracts the referenced
-* schema, inlines it into `components.schemas` with a synthesised name, and
-* rewrites the $ref to point to the inlined copy.
+* schema, inlines it into `components.schemas` under a synthesised name, and
+* rewrites the original $ref to point at the new internal location
+* (`#/components/schemas/<name>`).
+*
+* Identical external refs share a single entry — the second occurrence of
+* the same `(uri, fragment)` pair reuses the name produced for the first.
+* Name collisions between different refs are resolved by suffixing a counter.
 *
 * The resolver is called once per unique URI and the result is cached.
 *
-* Returns a deep-cloned document with all external refs resolved.
-* The original document is never mutated.
+* Returns a deep-cloned document with all external refs replaced by internal
+* refs. The original document is never mutated.
 */
 async function bundleOpenApiDoc(doc, resolver) {
 	const result = structuredClone(doc);
 	const uriCache = /* @__PURE__ */ new Map();
+	const inlineCache = /* @__PURE__ */ new Map();
 	if (!isObject(result.components)) result.components = {};
-	if (!isObject(result.components)) result.components = {};
-	if (isObject(result.components) && !isObject(result.components.schemas)) result.components.schemas = {};
-	await walkAndInline(result, uriCache, resolver);
+	const components = result.components;
+	if (!isObject(components)) throw new Error("bundleOpenApiDoc: components is not an object");
+	if (!isObject(components.schemas)) components.schemas = {};
+	const schemasNode = components.schemas;
+	if (!isObject(schemasNode)) throw new Error("bundleOpenApiDoc: components.schemas is not an object");
+	await walkAndInline(result, schemasNode, uriCache, inlineCache, resolver);
 	return result;
 }
 /**
 * Walk a document tree, find external $ref strings, resolve them,
-* inline the targets, and rewrite the refs.
+* inline the targets into `components.schemas`, and rewrite each $ref
+* to point at the new internal location.
 */
-async function walkAndInline(node, uriCache, resolver) {
+async function walkAndInline(node, schemasNode, uriCache, inlineCache, resolver) {
 	if (!isObject(node)) return;
 	if (typeof node.$ref === "string" && !node.$ref.startsWith("#")) {
 		const ref = node.$ref;
@@ -66,15 +76,22 @@ async function walkAndInline(node, uriCache, resolver) {
 			}
 		}
 		if (externalDoc !== void 0) {
-			const target = resolveFragment(externalDoc, fragment);
-			if (isObject(target)) {
-				delete node.$ref;
-				for (const [key, value] of Object.entries(target)) node[key] = value;
+			const cacheKey = `${uri}${fragment}`;
+			let inlinedName = inlineCache.get(cacheKey);
+			if (inlinedName === void 0) {
+				const target = resolveFragment(externalDoc, fragment);
+				if (isObject(target)) {
+					inlinedName = registerInline(schemasNode, uri, fragment, target);
+					inlineCache.set(cacheKey, inlinedName);
+					await walkAndInline(schemasNode[inlinedName], schemasNode, uriCache, inlineCache, resolver);
+				}
 			}
+			if (inlinedName !== void 0) node.$ref = `#/components/schemas/${inlinedName}`;
 		}
+		return;
 	}
-	for (const value of Object.values(node)) if (isObject(value)) await walkAndInline(value, uriCache, resolver);
-	else if (Array.isArray(value)) for (const item of value) await walkAndInline(item, uriCache, resolver);
+	for (const value of Object.values(node)) if (isObject(value)) await walkAndInline(value, schemasNode, uriCache, inlineCache, resolver);
+	else if (Array.isArray(value)) for (const item of value) await walkAndInline(item, schemasNode, uriCache, inlineCache, resolver);
 }
 /**
 * Resolve a JSON Pointer fragment within a document.
@@ -91,5 +108,47 @@ function resolveFragment(doc, fragment) {
 	}
 	return isObject(current) ? current : void 0;
 }
+/**
+* Derive a candidate identifier for an inlined external schema. Prefers
+* the last meaningful segment of the JSON Pointer fragment; falls back
+* to the URI's filename (sans extension), then to a generic prefix.
+*/
+function deriveCandidateName(uri, fragment) {
+	if (fragment.startsWith("#/")) {
+		const last = fragment.slice(2).split("/").at(-1);
+		if (last !== void 0 && last.length > 0) return sanitiseName(last);
+	}
+	const pathOnly = uri.split(/[?#]/)[0] ?? uri;
+	const lastSlash = pathOnly.lastIndexOf("/");
+	const filename = lastSlash >= 0 ? pathOnly.slice(lastSlash + 1) : pathOnly;
+	const dot = filename.lastIndexOf(".");
+	const stem = dot > 0 ? filename.slice(0, dot) : filename;
+	if (stem.length > 0) return sanitiseName(stem);
+	return "ExternalSchema";
+}
+/**
+* Sanitise a string into a JSON Pointer-safe identifier: alphanumerics
+* and underscores only. An empty result falls back to "Schema".
+*/
+function sanitiseName(raw) {
+	const cleaned = raw.replace(/[^A-Za-z0-9_]/g, "_");
+	return cleaned.length > 0 ? cleaned : "Schema";
+}
+/**
+* Place the resolved target into `components.schemas` under a unique
+* name derived from the ref, and return the chosen name. Collisions
+* with existing entries are resolved by suffixing a counter.
+*/
+function registerInline(schemasNode, uri, fragment, target) {
+	const base = deriveCandidateName(uri, fragment);
+	let name = base;
+	let counter = 2;
+	while (name in schemasNode) {
+		name = `${base}_${String(counter)}`;
+		counter++;
+	}
+	schemasNode[name] = structuredClone(target);
+	return name;
+}
 //#endregion
 export { bundleOpenApiDoc };

package/dist/openapi/components.d.mts

@@ -1,5 +1,5 @@
 import { T as SchemaMeta, u as FieldOverride } from "../types-D_5ST7SS.mjs";
-import { i as InferResponseFields, n as InferParameterOverrides, r as InferRequestBodyFields, u as UnsafeFields } from "../typeInference-k7FXfTVO.mjs";
+import { a as InferResponseFields, d as UnsafeFields, i as InferRequestBodyFields, r as InferParameterOverrides } from "../typeInference-5JiqIZ8t.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/components.mjs

@@ -1,6 +1,4 @@
-import { toRecordOrUndefined } from "../core/guards.mjs";
-import { SchemaNormalisationError } from "../core/errors.mjs";
-import { normaliseSchema } from "../core/adapter.mjs";
+import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
 import { walk } from "../core/walker.mjs";
 import { ApiCallbacks } from "./ApiCallbacks.mjs";
 import { ApiLinks } from "./ApiLinks.mjs";
@@ -27,25 +25,17 @@ import { useId } from "react";
 */
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
-	let jsonSchema;
-	let rootMeta;
-	try {
-		const normalised = normaliseSchema(schema);
-		jsonSchema = normalised.jsonSchema;
-		rootMeta = normalised.rootMeta;
-	} catch (err) {
-		throw new SchemaNormalisationError(err instanceof Error ? err.message : "Failed to normalise schema", schema, "unknown");
-	}
+	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
+	const rootMeta = extractRootMetaFromSchema(schema);
 	const componentMeta = {};
 	if (options.readOnly === true) componentMeta.readOnly = true;
 	if (options.meta !== void 0) for (const [k, v] of Object.entries(options.meta)) componentMeta[k] = v;
-	const walkOpts = {
+	const tree = walk(schema, {
 		componentMeta,
 		rootMeta,
 		fieldOverrides: toRecordOrUndefined(options.fields),
 		rootDocument
-	};
-	const tree = walk(jsonSchema, walkOpts);
+	});
 	const makeRenderChild = (parentPath) => (childTree, childValue, childOnChange, pathSuffix) => {
 		const childPath = joinPath(parentPath, pathSuffix);
 		return renderField(childTree, childValue, childOnChange, void 0, makeRenderChild(childPath), childPath, options.widgets);
@@ -262,5 +252,20 @@ function buildParamMeta(param, overrides, meta) {
 	if (meta !== void 0) for (const [k, v] of Object.entries(meta)) result[k] = v;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+/**
+* Extract root-level meta (title, description, readOnly, etc.) from a
+* JSON Schema node. Mirrors `extractRootMetaFromJson` in the adapter so
+* pre-normalised schemas (extracted from `getParsed`) still surface root
+* meta to the walker without an extra adapter round-trip.
+*/
+function extractRootMetaFromSchema(jsonSchema) {
+	const meta = {};
+	if (jsonSchema.readOnly === true) meta.readOnly = true;
+	if (jsonSchema.writeOnly === true) meta.writeOnly = true;
+	if (typeof jsonSchema.description === "string") meta.description = jsonSchema.description;
+	if (typeof jsonSchema.title === "string") meta.title = jsonSchema.title;
+	if (typeof jsonSchema.deprecated === "boolean") meta.deprecated = jsonSchema.deprecated;
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
 //#endregion
 export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };

package/dist/openapi/parser.d.mts

@@ -41,7 +41,7 @@ interface SecurityRequirement {
   scopes: string[];
 }
 interface SecurityScheme {
-  type: string;
+  type: string | undefined;
   description: string | undefined;
   name: string | undefined;
   location: string | undefined;
@@ -92,7 +92,7 @@ declare function getRequestBody(parsed: OpenApiDocument, path: string, method: s
 declare function getResponses(parsed: OpenApiDocument, path: string, method: string): ResponseInfo[];
 declare function getSecurityRequirements(parsed: OpenApiDocument, path: string, method: string): SecurityRequirement[];
 declare function getSecuritySchemes(parsed: OpenApiDocument): Map<string, SecurityScheme>;
-declare function getResponseHeaders(response: JsonObject): Map<string, HeaderInfo>;
+declare function getResponseHeaders(response: JsonObject, doc?: JsonObject): Map<string, HeaderInfo>;
 declare function listWebhooks(parsed: OpenApiDocument): WebhookInfo[];
 declare function getExternalDocs(obj: JsonObject): ExternalDocs | undefined;
 declare function getXmlInfo(schema: JsonObject): XmlInfo | undefined;

package/dist/openapi/parser.mjs

@@ -79,22 +79,22 @@ function getParameters(parsed, path, method) {
 	if (pathItem === void 0) return [];
 	const operation = getProperty(pathItem, method);
 	if (!isObject(operation)) return [];
-	const pathParams = extractParameterList(getProperty(pathItem, "parameters"));
-	const opParams = extractParameterList(getProperty(operation, "parameters"));
+	const pathParams = extractParameterList(parsed.doc, getProperty(pathItem, "parameters"));
+	const opParams = extractParameterList(parsed.doc, getProperty(operation, "parameters"));
 	const map = /* @__PURE__ */ new Map();
 	for (const param of pathParams) map.set(`${param.name}:${param.location}`, param);
 	for (const param of opParams) map.set(`${param.name}:${param.location}`, param);
 	return [...map.values()];
 }
-function extractParameterList(parameters) {
+function extractParameterList(doc, parameters) {
 	if (!Array.isArray(parameters)) return [];
 	const result = [];
 	for (const param of parameters) {
 		if (!isObject(param)) continue;
-		const name = getProperty(param, "name");
-		const location = getProperty(param, "in");
+		const resolved = resolveParam(doc, param);
+		const name = getProperty(resolved, "name");
+		const location = getProperty(resolved, "in");
 		if (typeof name !== "string" || typeof location !== "string") continue;
-		const resolved = resolveParam(param);
 		const schema = getProperty(resolved, "schema");
 		result.push({
 			name,
@@ -107,10 +107,10 @@ function extractParameterList(parameters) {
 	}
 	return result;
 }
-function resolveParam(param) {
+function resolveParam(doc, param) {
 	const ref = getProperty(param, "$ref");
 	if (typeof ref === "string" && ref.startsWith("#/")) {
-		const resolved = resolveRefInDoc(param, ref);
+		const resolved = resolveRefInDoc(doc, ref);
 		if (resolved !== void 0) return resolved;
 	}
 	return param;
@@ -143,7 +143,7 @@ function getResponses(parsed, path, method) {
 		const content = getProperty(response, "content");
 		const contentTypes = isObject(content) ? Object.keys(content) : [];
 		const schema = isObject(content) ? extractSchemaFromContent(content) : void 0;
-		const headers = getResponseHeaders(response);
+		const headers = getResponseHeaders(response, parsed.doc);
 		result.push({
 			statusCode,
 			description: getString(response, "description"),
@@ -196,7 +196,7 @@ function getSecuritySchemes(parsed) {
 		if (!isObject(scheme)) continue;
 		const flowsProp = getProperty(scheme, "flows");
 		result.set(name, {
-			type: getString(scheme, "type") ?? "",
+			type: getString(scheme, "type"),
 			description: getString(scheme, "description"),
 			name: getString(scheme, "name"),
 			location: getString(scheme, "in"),
@@ -208,14 +208,14 @@ function getSecuritySchemes(parsed) {
 	}
 	return result;
 }
-function getResponseHeaders(response) {
+function getResponseHeaders(response, doc) {
 	const result = /* @__PURE__ */ new Map();
 	const headers = getProperty(response, "headers");
 	if (!isObject(headers)) return result;
 	for (const [name, headerObj] of Object.entries(headers)) {
 		if (!isObject(headerObj)) continue;
 		const ref = getString(headerObj, "$ref");
-		const header = (ref !== void 0 ? resolveRefInDoc(headerObj, ref) : void 0) ?? headerObj;
+		const header = (ref !== void 0 && doc !== void 0 ? resolveRefInDoc(doc, ref) : void 0) ?? headerObj;
 		const schemaProp = getProperty(header, "schema");
 		result.set(name, {
 			name,

package/dist/openapi/resolve.d.mts

@@ -2,8 +2,19 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
 
 //#region src/openapi/resolve.d.ts
 /**
- * Parse and cache an OpenAPI document. Returns cached version if
- * the same object identity has been seen before.
+ * Parse and cache an OpenAPI document. Returns the cached parse for the
+ * same object identity.
+ *
+ * Before parsing, the document is run through the version-aware
+ * normalisation pipeline (`normaliseOpenApiSchemas`) so OpenAPI 3.0.x
+ * keywords (`nullable`, `discriminator`, `example`) and Swagger 2.0
+ * documents are converted to canonical Draft 2020-12 form. The parser
+ * and downstream extractors (`getRequestBody`, `getResponses`, etc.) then
+ * observe schemas in the same form `<SchemaComponent>` does, keeping the
+ * OpenAPI components on the same pipeline as the top-level adapter.
+ *
+ * The cache is keyed by the caller-supplied document so subsequent calls
+ * with the same input bypass both normalisation and parsing.
  */
 declare function getParsed(doc: Record<string, unknown>): OpenApiDocument;
 /**

package/dist/openapi/resolve.mjs

@@ -1,4 +1,6 @@
 import { isObject } from "../core/guards.mjs";
+import { detectOpenApiVersion } from "../core/version.mjs";
+import { i as normaliseOpenApiSchemas } from "../normalise-tL9FckAk.mjs";
 import { getParameters, getRequestBody, getResponses, listOperations, parseOpenApiDocument } from "./parser.mjs";
 //#region src/openapi/resolve.ts
 /**
@@ -10,14 +12,28 @@ import { getParameters, getRequestBody, getResponses, listOperations, parseOpenA
 */
 const docCache = /* @__PURE__ */ new WeakMap();
 /**
-* Parse and cache an OpenAPI document. Returns cached version if
-* the same object identity has been seen before.
+* Parse and cache an OpenAPI document. Returns the cached parse for the
+* same object identity.
+*
+* Before parsing, the document is run through the version-aware
+* normalisation pipeline (`normaliseOpenApiSchemas`) so OpenAPI 3.0.x
+* keywords (`nullable`, `discriminator`, `example`) and Swagger 2.0
+* documents are converted to canonical Draft 2020-12 form. The parser
+* and downstream extractors (`getRequestBody`, `getResponses`, etc.) then
+* observe schemas in the same form `<SchemaComponent>` does, keeping the
+* OpenAPI components on the same pipeline as the top-level adapter.
+*
+* The cache is keyed by the caller-supplied document so subsequent calls
+* with the same input bypass both normalisation and parsing.
 */
 function getParsed(doc) {
 	const cached = docCache.get(doc);
 	if (cached !== void 0) return cached;
-	const parsed = parseOpenApiDocument(doc);
+	const version = detectOpenApiVersion(doc);
+	const normalisedDoc = version !== void 0 ? normaliseOpenApiSchemas(doc, version) : doc;
+	const parsed = parseOpenApiDocument(normalisedDoc);
 	docCache.set(doc, parsed);
+	if (normalisedDoc !== doc) docCache.set(normalisedDoc, parsed);
 	return parsed;
 }
 /**

package/dist/react/SchemaComponent.d.mts

@@ -1,8 +1,8 @@
 import { M as WalkedField, T as SchemaMeta, d as FieldOverrides, u as FieldOverride } from "../types-D_5ST7SS.mjs";
-import { t as Diagnostic } from "../diagnostics-DzbZmcLI.mjs";
+import { t as Diagnostic } from "../diagnostics-BYk63jsC.mjs";
 import { t as SchemaError } from "../errors-C5zRC2PU.mjs";
-import { l as RenderProps, r as ComponentResolver } from "../renderer-B3s8o2B8.mjs";
-import { c as ResolveOpenAPIRef, s as PathOfType, t as FromJSONSchema } from "../typeInference-k7FXfTVO.mjs";
+import { l as RenderProps, r as ComponentResolver } from "../renderer-BAGoX4AK.mjs";
+import { c as PathOfType, l as ResolveOpenAPIRef, n as FromJSONSchema } from "../typeInference-5JiqIZ8t.mjs";
 import { z } from "zod";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { ReactNode } from "react";