@scalar/openapi-to-markdown 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @scalar/openapi-to-markdown
 
+## 1.3.0
+
+### Minor Changes
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Mock-server XML response bytes now use the shared schema-aware serializer instead of `json2xml`, including attributes, namespaces, and root naming. Existing XML response snapshots may need updating. Supplied serialized XML remains unchanged.
+
+  Generate XML examples from schema metadata, preserving attributes, namespaces, array wrappers, repeated elements, and OpenAPI 3.2 text and CDATA nodes. Use the same XML serialization for request bodies, code snippets, response examples, mock responses, and Markdown documentation. Preserve serialized media examples and escape schema string examples as element text.
+
+  Explain XML generation failures in response example panels, including the serialized-example escape hatch for large payloads. Expose XML generation failures in mock response headers with `X-Scalar-XML-Error`, containing the first error diagnostic code. Report diagnostics to other consumers through a callback or the developer console, and format element-only descendants within mixed content without changing text values.
+
+### Patch Changes
+
+- [#10356](https://github.com/scalar/scalar/pull/10356): Load densely cross-linked API descriptions with far less memory. References are now linked after coercion, so TypeBox no longer copies the reference graph each time it checks a union or array. Stripe's API description loads in about 2 seconds with a peak of about 190 MB, down from about 17 seconds and 1.4 GB, so it now loads and renders with a 768 MB heap limit.
+
+  Coercion now checks each reference target in its own position, not through every reference that points to it. Before, a target that failed a strict schema check (for example, a schema with `oneOf` references) could turn the reference into an empty schema and drop sibling `x-` extensions. Those references and extensions are now kept, so affected response schemas render in full.
+
+  References to targets that coercion drops, such as a root-level `definitions` block, now link to a copy cast as the schema, parameter, response or other object the reference stands in for, and their anchors resolve against the resource that contains them. A `$ref: '#'` inside a schema with an `$id` now links to that schema.
+
+  Coerce reference targets stored in extension data and schema siblings on fallback references before rendering, avoiding crashes from malformed fields while preserving recursive links.
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Apply edited XML bodies instead of their original serialized or data examples, render schema-free XML examples in Markdown, and share reference decoding and response provenance selection.
+
+## 1.2.0
+
+### Minor Changes
+
+- [#10186](https://github.com/scalar/scalar/pull/10186): Support document-defined additional operations in Markdown operation, webhook, and tag selections. Preserve custom method spelling and inherited parameters, servers, and security when copying an operation as Markdown.
+
+### Patch Changes
+
+- [#10329](https://github.com/scalar/scalar/pull/10329): Render each shared schema once per page. The first reference to a structured schema expands it and labels it with its name (for example `schema: Account`). Later references print "Schema `Account` is shown above." instead of expanding it again. Model sections for schemas already expanded on the page refer back to them too. True cycles still print `[Circular Reference]`. This keeps Markdown output proportional to the schema graph, rather than to the number of paths through it. Before this change, densely linked descriptions such as Stripe's ran out of memory when rendering a single operation.
+
+  A node budget per operation and model section adds a visible `[Schema output truncated]` marker as a last resort. Generated examples that would exceed 10,000 values are omitted with a note. References past the depth limit now point to the model's own section instead of being cut off.
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/get-markdown-examples.d.ts

@@ -15,8 +15,19 @@ type MarkdownExample = {
     externalValue: string;
 } | {
     serializedValue: string;
+} | {
+    omitted: true;
+} | {
+    dataValue: unknown;
+} | {
+    error: string;
 });
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export declare const countGeneratedExampleValues: (root: unknown, limit?: number) => number;
 /** Preserve supplied values; generate a fallback only when examples are not supplied. */
-export declare const getMarkdownExamples: (source: ExampleSource, mediaType: string, mode?: "read" | "write", openapiVersion?: string) => MarkdownExample[];
+export declare const getMarkdownExamples: (source: ExampleSource, mediaType: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string) => MarkdownExample[];
 export {};
 //# sourceMappingURL=get-markdown-examples.d.ts.map

package/dist/get-markdown-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElF,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,eAAe,EA2BjB,CAAA"}
+{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAMA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CACA;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpB,CAAA;AAYD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,OAAO,EAAE,cAAoC,KAAG,MA2CjG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,KACpC,eAAe,EAoCjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -1,8 +1,77 @@
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+import { getExampleFromSchema, getXmlBodyExample } from '@scalar/workspace-store/request-example';
+/** Mirrors the depth at which `getExampleFromSchema` stops following nested schemas. */
+const EXAMPLE_DEPTH = 10;
+/**
+ * Generated examples repeat every shared schema at each place it is used, up to ten levels deep.
+ * A densely shared schema graph therefore produces billions of values, so larger examples are skipped.
+ * The largest generated examples in the Stripe, GitHub, and Cloudflare descriptions have about 7,600 values.
+ */
+const MAX_GENERATED_EXAMPLE_VALUES = 10_000;
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_VALUES) => {
+    const counts = new WeakMap();
+    const count = (input, level) => {
+        if (level > EXAMPLE_DEPTH || !isObject(input))
+            return 1;
+        const cached = counts.get(input)?.get(level);
+        if (cached !== undefined)
+            return cached;
+        const schema = getResolvedRef(input, mergeSiblingReferences);
+        if (!isObject(schema))
+            return 1;
+        // Supplied examples bypass schema expansion in the generator too.
+        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0))
+            return 1;
+        let total = 1;
+        const add = (child) => {
+            if (total <= limit)
+                total += count(child, level + 1);
+        };
+        if (isObject(schema.properties))
+            Object.values(schema.properties).forEach(add);
+        if (isObject(schema.patternProperties))
+            Object.values(schema.patternProperties).forEach(add);
+        if (isObject(schema.additionalProperties))
+            add(schema.additionalProperties);
+        if (schema.items !== undefined)
+            add(schema.items);
+        if (Array.isArray(schema.prefixItems))
+            schema.prefixItems.forEach(add);
+        if (Array.isArray(schema.allOf))
+            schema.allOf.forEach(add);
+        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        // Object and array generation can use the first variant, while other unions skip null.
+        // A discriminator can choose any variant, so bound the largest candidate in that case.
+        const nonNull = variants.find((variant) => {
+            const resolved = getResolvedRef(variant, mergeSiblingReferences);
+            return isObject(resolved) && resolved.type !== 'null';
+        });
+        const candidates = isObject(schema.discriminator) && schema.discriminator.defaultMapping !== undefined
+            ? variants
+            : [variants[0], nonNull];
+        let variantCount = 0;
+        for (const candidate of candidates) {
+            if (candidate !== undefined && total <= limit && variantCount <= limit)
+                variantCount = Math.max(variantCount, count(candidate, level + 1));
+        }
+        total += variantCount;
+        const levels = counts.get(input) ?? new Map();
+        levels.set(level, total);
+        counts.set(input, levels);
+        return total;
+    };
+    return count(root, 0);
+};
 /** Preserve supplied values; generate a fallback only when examples are not supplied. */
-export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0') => {
+export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0', 
+// Schema metadata can be upgraded while example fields still follow the original version.
+schemaOpenapiVersion = openapiVersion) => {
     if (source.example !== undefined)
         return [{ value: source.example }];
     if (source.examples && Object.keys(source.examples).length) {
@@ -22,15 +91,25 @@ export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3
             if (typeof example.externalValue === 'string')
                 return [{ ...metadata, externalValue: example.externalValue }];
             if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined)
-                return [{ ...metadata, value: example.dataValue }];
+                return [{ ...metadata, dataValue: example.dataValue }];
             return [];
         });
     }
     const schema = getResolvedRef(source.schema);
     if (!isObject(schema))
         return [];
+    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
+        return [{ omitted: true }];
+    if (isXmlMediaType(mediaType)) {
+        const result = getXmlBodyExample(source.schema, undefined, {
+            mode,
+            openapiVersion: schemaOpenapiVersion,
+        });
+        return [
+            result.xml === undefined ? { error: 'Unable to generate an XML example.' } : { serializedValue: result.xml },
+        ];
+    }
     const value = getExampleFromSchema(getResolvedRef(source.schema, mergeSiblingReferences), {
-        xml: mediaType.includes('xml'),
         mode,
     });
     return value === undefined ? [] : [{ value }];

package/dist/load-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AA2ErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CA0FzB,CAAA"}
+{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,8DAA8D,CAAA;AA6LrE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CAgGzB,CAAA"}

package/dist/load-document.js

@@ -9,21 +9,99 @@ import { getRaw } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
 import { deepClone } from '@scalar/workspace-store/helpers/deep-clone';
 import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
-import { OpenAPIDocumentSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
-import { restoreBooleanSchemas } from './restore-boolean-schemas.js';
+import { OpenAPIDocumentSchema, SchemaObjectSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { getChildKind, referenceTargetSchemas } from './object-kinds.js';
+import { getChildPosition, restoreBooleanSchemas } from './restore-boolean-schemas.js';
 /**
  * Link references in a private, bundled document without proxies or expanded copies.
  * JSON Magic owns `$id` and anchor indexing, which keeps local-reference behavior
  * aligned with the external-reference bundler without retaining a second resolver.
  * Non-enumerable links preserve serialization and share recursive schema targets.
- * Casting temporarily uses enumerable links to satisfy TypeBox reference branches.
+ * With `detectOnly`, nothing is linked and the pass only looks for external references.
  * Returns whether external references remain and require bundling.
  */
-const attachRefValues = (document, enumerable = false, schemas = getSchemas(document)) => {
-    // A single traversal covers both normal trees and previously linked recursive objects.
+const attachRefValues = (document, schemas = getSchemas(document), { detectOnly = false, fallback } = {}) => {
+    // Fallback targets are linked outside the walked tree and can be reached again from it,
+    // so one set keeps every object to a single visit.
     const seen = new WeakSet();
+    // Large descriptions repeat the same reference strings thousands of times.
+    const targets = new Map();
+    // Share one cast copy between every reference of the same kind to the same dropped target.
+    const castFallbacks = new WeakMap();
     let hasExternalReferences = false;
-    const visit = (node, context = getId(document) ?? '') => {
+    const lookUp = (path, ref) => {
+        // An empty path is a resource root, unless the fragment is the pointer to the empty key.
+        const segments = path === '' && !ref.includes('#/') ? [] : parseJsonPointerSegments(`/${path}`);
+        const linked = getValueByPath(document, segments);
+        let position = 'document';
+        let kind = 'document';
+        let parent = document;
+        for (const key of segments) {
+            kind = kind && getChildKind(kind, key);
+            position = Array.isArray(parent) ? position : position && getChildPosition(position, key);
+            // Arbitrary extension and example data has not passed an OpenAPI object schema.
+            if (position === 'document' && kind === undefined)
+                position = undefined;
+            parent = getValueByPath(parent, [key]).value;
+        }
+        const schema = getTargetSchema(position, kind);
+        if ((linked.value !== undefined && schema !== undefined) || fallback === undefined) {
+            return { ...linked, linked: true, schema };
+        }
+        // The context is the base of the resource that contains the fallback target.
+        return { ...getValueByPath(fallback.source, segments), linked: false };
+    };
+    const resolve = (ref, base) => {
+        const key = `${base}\u0000${ref}`;
+        if (targets.has(key)) {
+            return targets.get(key);
+        }
+        // JSON Magic has no entry for an empty fragment, which names the root of the current resource.
+        const path = ref === '#' ? (schemas.get(base) ?? '') : convertToLocalRef(ref, base, schemas);
+        const resolved = path === undefined ? undefined : lookUp(path, ref);
+        targets.set(key, resolved);
+        return resolved;
+    };
+    // Cast dropped targets like the objects they stand in for, so the renderer never sees uncoerced shapes.
+    const castFallback = (value, schema, position) => {
+        // OpenAPI 3.1 keeps boolean schemas, and a nested reference is linked once it is walked.
+        if (value === undefined || (fallback?.booleanSchemas && position === 'schema' && typeof value === 'boolean')) {
+            return value;
+        }
+        if (!isObject(value)) {
+            return coerceValue(schema, value);
+        }
+        const casts = castFallbacks.get(value) ?? new Map();
+        castFallbacks.set(value, casts);
+        if (!casts.has(schema)) {
+            // Cast schema siblings without losing the reference. Other Reference Objects only
+            // support summary and description; casting them as their targets would add defaults.
+            // Path Item Objects declare their own $ref field, so their siblings are cast normally.
+            const reference = typeof value.$ref === 'string' ? value.$ref : undefined;
+            const cast = reference === undefined || schema === referenceTargetSchemas.pathItem
+                ? coerceValue(schema, value)
+                : position === 'schema'
+                    ? { ...coerceValue(SchemaObjectSchema, value), $ref: reference }
+                    : {
+                        $ref: reference,
+                        ...(typeof value.summary === 'string' ? { summary: value.summary } : {}),
+                        ...(typeof value.description === 'string' ? { description: value.description } : {}),
+                    };
+            if (fallback?.booleanSchemas) {
+                restoreBooleanSchemas(value, cast, position);
+            }
+            casts.set(schema, cast);
+        }
+        return casts.get(schema);
+    };
+    // Schemas are recognized by their position, and every other object by the field that holds it.
+    const getTargetSchema = (position, kind) => {
+        if (position === 'schema') {
+            return SchemaObjectSchema;
+        }
+        return typeof kind === 'string' ? referenceTargetSchemas[kind] : undefined;
+    };
+    const visit = (node, context, position, kind) => {
         if (node === null || typeof node !== 'object' || seen.has(node)) {
             return;
         }
@@ -32,45 +110,40 @@ const attachRefValues = (document, enumerable = false, schemas = getSchemas(docu
         const base = getId(node) ?? context;
         if (isObject(node) && typeof node.$ref === 'string') {
             const ref = node.$ref;
-            const path = ref === '#' ? '' : convertToLocalRef(ref, base, schemas);
-            // Point to the bundled target instead of copying it into every reference.
-            const target = path === undefined ? undefined : getValueByPath(document, parseJsonPointerSegments(`/${path}`)).value;
-            // JSON Magic only needs to bundle references outside this document's resource index.
-            if (path === undefined && ref.split('#')[0]) {
-                hasExternalReferences = true;
-            }
-            if (enumerable) {
-                const followed = new WeakSet();
-                let resolved = target;
-                // TypeBox needs the final target, so collapse a pre-existing reference chain safely.
-                while (isObject(resolved) && '$ref-value' in resolved && !followed.has(resolved)) {
-                    followed.add(resolved);
-                    resolved = resolved['$ref-value'];
+            if (detectOnly) {
+                // JSON Magic only needs to bundle references outside this document's resource index.
+                if (ref.split('#')[0] && convertToLocalRef(ref, base, schemas) === undefined) {
+                    hasExternalReferences = true;
                 }
-                if (resolved !== undefined) {
+            }
+            else if (getTargetSchema(position, kind)) {
+                const resolved = resolve(ref, base);
+                const expectedSchema = getTargetSchema(position, kind);
+                const schema = resolved?.schema === expectedSchema ? undefined : expectedSchema;
+                // Point to the target instead of copying it into every reference.
+                const target = schema ? castFallback(resolved?.value, schema, position ?? 'document') : resolved?.value;
+                if (target !== undefined) {
                     Object.defineProperty(node, '$ref-value', {
-                        value: resolved,
-                        enumerable,
+                        value: target,
+                        enumerable: false,
                         configurable: true,
                         writable: true,
                     });
                 }
-            }
-            else if (target !== undefined) {
-                Object.defineProperty(node, '$ref-value', {
-                    value: target,
-                    enumerable,
-                    configurable: true,
-                    writable: true,
-                });
+                // Fallback targets live outside the walked tree, so link their own references too.
+                if (resolved && (!resolved.linked || schema)) {
+                    visit(target, resolved.context, position, kind);
+                }
             }
         }
         // Preserve the nearest resource base while walking into child schemas.
-        for (const child of Object.values(node)) {
-            visit(child, base);
+        for (const [key, child] of Object.entries(node)) {
+            const childKind = kind && getChildKind(kind, key);
+            const childPosition = Array.isArray(node) ? position : position && getChildPosition(position, key);
+            visit(child, base, childPosition === 'document' && childKind === undefined ? undefined : childPosition, childKind);
         }
     };
-    visit(document);
+    visit(document, getId(document) ?? '', 'document', 'document');
     return hasExternalReferences;
 };
 /** Coerce one plain document and keep references linked to shared targets. */
@@ -108,7 +181,7 @@ export const loadDocument = async (input) => {
     const declaredOpenapiVersion = typeof raw.openapi === 'string' ? raw.openapi : '2.0';
     const { document: upgraded } = upgrade(raw, '3.2', { onIncompatible: 'collect' });
     const upgradedSchemas = getSchemas(upgraded);
-    const hasExternalReferences = attachRefValues(upgraded, false, upgradedSchemas);
+    const hasExternalReferences = attachRefValues(upgraded, upgradedSchemas, { detectOnly: true });
     let document = upgraded;
     let schemas = upgradedSchemas;
     // Resolve external targets only when the initial local-reference pass finds them.
@@ -130,17 +203,21 @@ export const loadDocument = async (input) => {
             throw new Error(errors.join('\n'));
         }
         schemas = getSchemas(document);
-        attachRefValues(document, false, schemas);
     }
-    // TypeBox's reference branches require an enumerable $ref-value during casting.
-    // Restore non-enumerable shared links afterward so rendering never expands the graph.
-    attachRefValues(document, true, schemas);
+    // Cast the document before linking references. TypeBox clones every value that already
+    // matches a union or array schema, and its clone follows all own properties, including
+    // non-enumerable `$ref-value` links. On densely linked descriptions, each clone would copy
+    // most of the reference graph again, which costs gigabytes of transient memory.
+    // Reference branches accept a missing `$ref-value`, and every target is cast in its own
+    // position, so one target that fails a strict check can no longer replace the reference.
     const coerced = coerceValue(OpenAPIDocumentSchema, document);
     // Rendering must use the declared version for features added after OpenAPI 3.1.
     coerced['x-original-oas-version'] = declaredOpenapiVersion;
     // Boolean schemas were introduced in OpenAPI 3.1; older descriptions retain their existing coercion.
-    if (/^3\.[12]\./.test(declaredOpenapiVersion))
+    const booleanSchemas = /^3\.[12]\./.test(declaredOpenapiVersion);
+    if (booleanSchemas) {
         restoreBooleanSchemas(document, coerced);
+    }
     // Keep extension resources that local and bundled references can target.
     for (const [key, value] of Object.entries(document)) {
         if (key.startsWith('x-') && !(key in coerced)) {
@@ -152,7 +229,8 @@ export const loadDocument = async (input) => {
             });
         }
     }
-    // Redefine TypeBox's temporary links as non-enumerable links to coerced targets.
-    attachRefValues(coerced, false, schemas);
+    // Link references to coerced targets. Targets that coercion dropped fall back to source values,
+    // which are cast according to the object kind expected at the reference.
+    attachRefValues(coerced, schemas, { fallback: { source: document, booleanSchemas } });
     return coerced;
 };

package/dist/object-kinds.d.ts

@@ -0,0 +1,14 @@
+import type { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+/** The OpenAPI objects outside of schemas that the linking pass tells apart. */
+export type ObjectKind = 'document' | 'components' | 'pathItem' | 'operation' | 'callback' | 'response' | 'requestBody' | 'mediaType' | 'encoding' | 'parameter' | 'header' | 'example' | 'link' | 'securityScheme';
+/** A value is either one object of a kind, or a map or array whose values all have that kind. */
+export type KindPosition = ObjectKind | {
+    values: ObjectKind;
+};
+type TargetSchema = Parameters<typeof coerceValue>[0];
+/** Returns the kind of the value stored under `key`, or `undefined` outside the known structure. */
+export declare const getChildKind: (position: KindPosition, key: string) => KindPosition | undefined;
+/** Strict schemas for the objects that a Reference Object can stand in for. */
+export declare const referenceTargetSchemas: Partial<Record<ObjectKind, TargetSchema>>;
+export {};
+//# sourceMappingURL=object-kinds.d.ts.map

package/dist/object-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-kinds.d.ts","sourceRoot":"","sources":["../src/object-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gDAAgD,CAAA;AAejF,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,YAAY,GACZ,UAAU,GACV,WAAW,GACX,UAAU,GACV,UAAU,GACV,aAAa,GACb,WAAW,GACX,UAAU,GACV,WAAW,GACX,QAAQ,GACR,SAAS,GACT,MAAM,GACN,gBAAgB,CAAA;AAEpB,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAE9D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;AAmDrD,oGAAoG;AACpG,eAAO,MAAM,YAAY,GAAI,UAAU,YAAY,EAAE,KAAK,MAAM,KAAG,YAAY,GAAG,SAMjF,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAY5E,CAAA"}

package/dist/object-kinds.js

@@ -0,0 +1,70 @@
+import { CallbackObjectSchema, ExampleObjectSchema, HeaderObjectSchema, LinkObjectSchema, MediaTypeObjectSchema, OperationObjectSchema, ParameterObjectSchema, PathItemObjectSchema, RequestBodyObjectSchema, ResponseObjectSchema, SecuritySchemeObjectSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+const methods = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace', 'connect', 'query'];
+/**
+ * Mirrors the OpenAPI 3.2 structure of the strict workspace schemas, so a reference knows which
+ * object it stands in for. A `*` key applies to every field, such as the expressions of a callback.
+ */
+const childKinds = {
+    document: {
+        paths: { values: 'pathItem' },
+        webhooks: { values: 'pathItem' },
+        components: 'components',
+    },
+    components: {
+        responses: { values: 'response' },
+        parameters: { values: 'parameter' },
+        examples: { values: 'example' },
+        requestBodies: { values: 'requestBody' },
+        headers: { values: 'header' },
+        securitySchemes: { values: 'securityScheme' },
+        links: { values: 'link' },
+        callbacks: { values: 'callback' },
+        pathItems: { values: 'pathItem' },
+        mediaTypes: { values: 'mediaType' },
+    },
+    pathItem: {
+        ...Object.fromEntries(methods.map((method) => [method, 'operation'])),
+        additionalOperations: { values: 'operation' },
+        parameters: { values: 'parameter' },
+    },
+    operation: {
+        parameters: { values: 'parameter' },
+        requestBody: 'requestBody',
+        responses: { values: 'response' },
+        callbacks: { values: 'callback' },
+    },
+    callback: { '*': 'pathItem' },
+    response: { headers: { values: 'header' }, content: { values: 'mediaType' }, links: { values: 'link' } },
+    requestBody: { content: { values: 'mediaType' } },
+    mediaType: {
+        examples: { values: 'example' },
+        encoding: { values: 'encoding' },
+        prefixEncoding: { values: 'encoding' },
+        itemEncoding: 'encoding',
+    },
+    encoding: { headers: { values: 'header' } },
+    parameter: { examples: { values: 'example' }, content: { values: 'mediaType' } },
+    header: { examples: { values: 'example' }, content: { values: 'mediaType' } },
+};
+/** Returns the kind of the value stored under `key`, or `undefined` outside the known structure. */
+export const getChildKind = (position, key) => {
+    if (typeof position !== 'string') {
+        return position.values;
+    }
+    const children = childKinds[position];
+    return children?.[key] ?? children?.['*'];
+};
+/** Strict schemas for the objects that a Reference Object can stand in for. */
+export const referenceTargetSchemas = {
+    pathItem: PathItemObjectSchema,
+    operation: OperationObjectSchema,
+    callback: CallbackObjectSchema,
+    response: ResponseObjectSchema,
+    requestBody: RequestBodyObjectSchema,
+    mediaType: MediaTypeObjectSchema,
+    parameter: ParameterObjectSchema,
+    header: HeaderObjectSchema,
+    example: ExampleObjectSchema,
+    link: LinkObjectSchema,
+    securityScheme: SecuritySchemeObjectSchema,
+};

package/dist/render-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAyIxF,CAAA"}
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CA6IxF,CAAA"}

package/dist/render-document.js

@@ -13,9 +13,11 @@ const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
-    const schemas = createSchemaRenderer();
+    const schemaRenderer = createSchemaRenderer();
     return async (document) => {
         const description = descriptions();
+        // Each page expands a shared schema once, then refers back to it.
+        const schemas = schemaRenderer.forDocument(document.components?.schemas);
         const { info } = document;
         const metadata = [
             field('OpenAPI Version', inlineCode(document.openapi)),
@@ -85,6 +87,7 @@ export const createDocumentRenderer = () => {
                         nodes.push(heading(2, text(group.title)));
                         hasOperations = true;
                     }
+                    schemas.beginSection();
                     nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
                         description,
                         schemas,
@@ -97,12 +100,13 @@ export const createDocumentRenderer = () => {
         if (models.length)
             nodes.push(heading(2, text('Schemas')));
         for (const [name, schema] of models) {
+            schemas.beginSection();
             const view = schemas.view(schema);
             nodes.push(heading(3, text(view.title ?? name)), list([
                 view.type
                     ? field('Type', inlineCode(Array.isArray(view.type) ? view.type.join(' | ') : view.type))
                     : item(paragraph(strong(text('Type:')))),
-            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true }));
+            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true, name }));
             if (view.type === 'object')
                 nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi)));
             flush();

package/dist/render-examples.d.ts

@@ -2,5 +2,5 @@ import type { RootContent } from 'mdast';
 import { type ExampleSource } from './get-markdown-examples.js';
 import type { DescriptionParser } from './parse-description.js';
 /** Render supplied examples before considering a schema-generated fallback. */
-export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string) => Promise<RootContent[]>;
+export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
 //# sourceMappingURL=render-examples.d.ts.map

package/dist/render-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,OAAO,CAAC,WAAW,EAAE,CAiCvB,CAAA"}
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CAmDvB,CAAA"}

package/dist/render-examples.js

@@ -1,14 +1,25 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
+import { getXmlBodyExample } from '@scalar/workspace-store/request-example';
 import { getMarkdownExamples } from './get-markdown-examples.js';
 import { link, paragraph, strong, text } from './markdown-nodes.js';
 /** Render supplied examples before considering a schema-generated fallback. */
-export const renderExamples = async (source, description, mediaType = 'application/json', mode, openapiVersion = '3.2.0') => {
+export const renderExamples = async (source, description, mediaType = 'application/json', mode, openapiVersion = '3.2.0', 
+// Schema metadata can be upgraded while example fields still follow the original version.
+schemaOpenapiVersion = openapiVersion) => {
     const nodes = [];
-    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion)) {
+    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion, schemaOpenapiVersion)) {
         nodes.push(paragraph(strong(text(example.name ? `Example: ${example.name}` : 'Example:'))));
+        if ('omitted' in example) {
+            nodes.push(paragraph(text('[Generated example omitted because it is too large]')));
+            continue;
+        }
         if (example.summary)
             nodes.push(paragraph(text(example.summary)));
         nodes.push(...(await description(example.description)));
+        if ('error' in example) {
+            nodes.push(paragraph(text(example.error)));
+            continue;
+        }
         if ('externalValue' in example) {
             nodes.push(paragraph(strong(text('External value:')), text(' '), link(example.externalValue, example.externalValue)));
             continue;
@@ -16,21 +27,31 @@ export const renderExamples = async (source, description, mediaType = 'applicati
         if ('serializedValue' in example) {
             nodes.push({
                 type: 'code',
-                lang: mediaType.includes('xml') ? 'xml' : mediaType.includes('json') ? 'json' : 'text',
+                lang: isXmlMediaType(mediaType) ? 'xml' : mediaType.includes('json') ? 'json' : 'text',
                 value: example.serializedValue,
             });
             continue;
         }
-        const xml = mediaType.includes('xml');
+        const xml = isXmlMediaType(mediaType);
+        const value = 'dataValue' in example ? example.dataValue : example.value;
+        if (xml && !source.schema && 'value' in example && (value === null || typeof value !== 'object')) {
+            nodes.push({ type: 'code', lang: 'xml', value: String(value) });
+            continue;
+        }
+        const result = xml
+            ? getXmlBodyExample(source.schema, example, {
+                mode,
+                openapiVersion: schemaOpenapiVersion,
+            })
+            : undefined;
+        if (xml && result?.xml === undefined) {
+            nodes.push(paragraph(text('Unable to generate an XML example.')));
+            continue;
+        }
         nodes.push({
             type: 'code',
             lang: xml ? 'xml' : 'json',
-            // XML strings are already serialized; primitives must not become object keys.
-            value: xml
-                ? example.value !== null && typeof example.value === 'object'
-                    ? json2xml(example.value)
-                    : String(example.value)
-                : (JSON.stringify(example.value, null, 2) ?? ''),
+            value: result?.xml ?? JSON.stringify(value, null, 2) ?? '',
         });
     }
     return nodes;