@scalar/openapi-to-markdown 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @scalar/openapi-to-markdown
 
+## 1.4.0
+
+### Minor Changes
+
+- [#10394](https://github.com/scalar/scalar/pull/10394): Add opt-in linked schema rendering with caller-supplied model URLs for bounded operation, model, and webhook pages. Keep default expansion unchanged, retain reference siblings and inline schemas, and omit generated examples in linked mode.
+
+## 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

package/README.md

@@ -194,3 +194,54 @@ const markdown = await createMarkdownFromOpenApi(document, {
 
 Use the default entry point for raw JSON, YAML, URLs, or file paths that still need
 loading, migration, and reference resolution.
+
+### Link shared schemas on individual pages
+
+The default renderer expands shared schemas and includes the schemas needed by a
+selected page. For large API descriptions, opt into `schemaReferences.mode:
+'linked'` to expand the root schema of each parameter, request, response, or model
+and replace nested `$ref` occurrences with links. Inline schemas continue to
+render, including composition branches and reference siblings. Operation and
+webhook pages do not collect or append transitive models; a model page includes
+only the selected model.
+
+The documentation generator supplies published URLs. The renderer does not assume
+any routing convention:
+
+```ts
+import { createOpenApiMarkdownRenderer } from '@scalar/openapi-to-markdown'
+
+const renderer = await createOpenApiMarkdownRenderer(apiDescription)
+// Build this map from the pages your generator actually publishes.
+const modelUrls = new Map([
+  ['account', '/reference/models/account'],
+  ['customer', '/reference/models/customer'],
+])
+const markdown = await renderer.render({
+  operation: { path: '/v1/account', method: 'get' },
+  schemaReferences: {
+    mode: 'linked',
+    resolveUrl: ({ name }) => modelUrls.get(name),
+  },
+})
+```
+
+The callback receives the original reference string (`ref`) and its decoded
+component name (`name`). For references outside `#/components/schemas/{name}`,
+`name` is the reference string. Returning `undefined`, an empty URL, or an unsafe
+URL retains the schema name as text. Omitting the callback has the same fallback.
+References remain visible even when no destination page exists.
+
+Use the same option with `{ model: 'account' }`, `{ webhook: { name: 'event',
+method: 'post' } }`, the one-shot `createMarkdownFromOpenApi`, or the browser entry
+point. The browser entry point still requires a workspace-resolved document.
+Options and URL callbacks are isolated per render, including concurrent renders.
+
+Linked mode omits schema-generated examples with an explicit note, avoiding
+expansion through the example generator. Authored media-type and schema examples
+remain available. Their size is not capped. Inline schema content and authored
+text also remain proportional to the source; this mode bounds traversal across
+shared references, not the byte size of arbitrary authored content. Root
+composition branches that contain references link to those schemas rather than
+flattening their constraints. Full-document exports still include every model
+section; use a page selector for individual exports.

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAGnG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,eAAe,EACzB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAAsE,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAGnG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,eAAe,EACzB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAA+E,CAAA"}

package/dist/browser.js

@@ -5,4 +5,4 @@ import { selectDocument } from './select-document.js';
  * References must already be resolved by the store. This entry point does not load
  * files, fetch URLs, or migrate raw API descriptions.
  */
-export const createMarkdownFromOpenApi = async (document, options) => await createDocumentRenderer()(selectDocument(document, options));
+export const createMarkdownFromOpenApi = async (document, options) => await createDocumentRenderer()(selectDocument(document, options), options);

package/dist/create-markdown-from-openapi.js

@@ -8,7 +8,7 @@ import { selectDocument } from './select-document.js';
 export const createOpenApiMarkdownRenderer = async (input) => {
     const content = await loadDocument(input);
     const renderDocument = createDocumentRenderer();
-    const render = async (options) => await renderDocument(selectDocument(content, options));
+    const render = async (options) => await renderDocument(selectDocument(content, options), options);
     return { render };
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */

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

@@ -17,6 +17,10 @@ type MarkdownExample = {
     serializedValue: string;
 } | {
     omitted: true;
+} | {
+    dataValue: unknown;
+} | {
+    error: string;
 });
 /**
  * Estimate how many values an example generated from this schema contains, stopping just past the limit.
@@ -24,6 +28,6 @@ type MarkdownExample = {
  */
 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, linked?: boolean) => 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,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAYtG;;;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,KACvB,eAAe,EA4BjB,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,EACrC,gBAAc,KACb,eAAe,EA2CjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -1,6 +1,7 @@
+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;
 /**
@@ -68,7 +69,9 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
     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, linked = false) => {
     if (source.example !== undefined)
         return [{ value: source.example }];
     if (source.examples && Object.keys(source.examples).length) {
@@ -88,17 +91,34 @@ 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);
+    const schema = linked
+        ? getResolvedRef(source.schema, mergeSiblingReferences)
+        : getResolvedRef(source.schema);
     if (!isObject(schema))
         return [];
+    if (linked) {
+        if (schema.example !== undefined)
+            return [{ value: schema.example }];
+        if (Array.isArray(schema.examples) && schema.examples.length)
+            return schema.examples.map((value) => ({ value }));
+        return [{ omitted: true }];
+    }
     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/index.d.ts

@@ -1,5 +1,5 @@
 export type { HttpMethod } from '@scalar/helpers/http/http-methods';
 export type { OpenApiMarkdownRenderer } from './create-markdown-from-openapi.js';
 export { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
-export type { OpenApiRenderOptions, OperationSelector } from './select-document.js';
+export type { OpenApiRenderOptions, OperationSelector, SchemaReferenceOptions } from './select-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

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

@@ -1,4 +1,5 @@
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { SchemaReferenceOptions } from './select-document.js';
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
-export declare const createDocumentRenderer: () => ((document: OpenApiDocument) => Promise<string>);
+export declare const createDocumentRenderer: () => ((document: OpenApiDocument, options?: SchemaReferenceOptions) => Promise<string>);
 //# sourceMappingURL=render-document.d.ts.map

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,CA6IxF,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;AAYpH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAI/D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,MAAM,CAAC,CA+InB,CAAA"}

package/dist/render-document.js

@@ -14,10 +14,10 @@ const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
     const schemaRenderer = createSchemaRenderer();
-    return async (document) => {
+    return async (document, options) => {
         const description = descriptions();
         // Each page expands a shared schema once, then refers back to it.
-        const schemas = schemaRenderer.forDocument(document.components?.schemas);
+        const schemas = schemaRenderer.forDocument(document.components?.schemas, options);
         const { info } = document;
         const metadata = [
             field('OpenAPI Version', inlineCode(document.openapi)),
@@ -108,7 +108,7 @@ export const createDocumentRenderer = () => {
                     : item(paragraph(strong(text('Type:')))),
             ]), ...(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)));
+                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi, document.openapi, schemas.linked)));
             flush();
         }
         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, linked?: boolean) => 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,CAqCvB,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,EACrC,gBAAc,KACb,OAAO,CAAC,WAAW,EAAE,CAyDvB,CAAA"}

package/dist/render-examples.js

@@ -1,18 +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, linked = false) => {
     const nodes = [];
-    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion)) {
+    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion, schemaOpenapiVersion, linked)) {
         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]')));
+            nodes.push(paragraph(text(`${linked ? '[Generated example omitted in linked schema mode; see the schema documentation]' : '[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;
@@ -20,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;

package/dist/render-operation-details.d.ts

@@ -3,9 +3,9 @@ import type { RootContent } from 'mdast';
 import type { DescriptionParser } from './parse-description.js';
 import type { SchemaRenderer } from './render-schema.js';
 /** Render response or multipart headers, whose names come from their containing map. */
-export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
 /** Preserve explicit encoding settings, including false flags and part headers. */
-export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
 /** Render response link expressions as literal values, without evaluating them. */
 export declare const renderResponseLinks: (links: ResponseObject["links"], description: DescriptionParser) => Promise<RootContent[]>;
 //# sourceMappingURL=render-operation-details.d.ts.map

package/dist/render-operation-details.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAkCvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAuBvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}
+{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA4CvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA6BvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}

package/dist/render-operation-details.js

@@ -2,7 +2,7 @@ import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/
 import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
 import { renderExamples } from './render-examples.js';
 /** Render response or multipart headers, whose names come from their containing map. */
-export const renderHeaders = async (headers, description, schemas, openapiVersion) => {
+export const renderHeaders = async (headers, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion) => {
     const entries = [];
     for (const [name, reference] of Object.entries(headers ?? {})) {
         // OpenAPI reserves Content-Type for the media type map / encoding field.
@@ -18,20 +18,20 @@ export const renderHeaders = async (headers, description, schemas, openapiVersio
         if ('schema' in header && header.schema !== undefined)
             blocks.push(...schemas.render(header.schema));
         if ('example' in header || 'examples' in header) {
-            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion)));
+            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
         }
         for (const [mediaType, content] of Object.entries('content' in header ? (header.content ?? {}) : {})) {
             blocks.push(paragraph(strong(text('Content-Type:')), text(` ${mediaType}`)));
             if (content.schema !== undefined)
                 blocks.push(...schemas.render(content.schema));
-            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion)));
+            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
         }
         entries.push(item(...blocks));
     }
     return entries.length ? [paragraph(strong(text('Headers:'))), list(entries)] : [];
 };
 /** Preserve explicit encoding settings, including false flags and part headers. */
-export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion) => {
+export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion, schemaOpenapiVersion = openapiVersion) => {
     const multipart = mediaType.startsWith('multipart/');
     if (!multipart && mediaType !== 'application/x-www-form-urlencoded')
         return [];
@@ -51,7 +51,7 @@ export const renderEncoding = async (encoding, mediaType, description, schemas,
         if (fields.length)
             blocks.push(list(fields));
         if (multipart)
-            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion)));
+            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion, schemaOpenapiVersion)));
         entries.push(item(...blocks));
     }
     return entries.length ? [paragraph(strong(text('Encoding:'))), list(entries)] : [];

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

@@ -1 +1 @@
-{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CAyGvB,CAAA"}
+{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CA0IvB,CAAA"}

package/dist/render-operation.js

@@ -59,12 +59,12 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         if ('schema' in parameter && parameter.schema !== undefined)
             nodes.push(...schemas.render(parameter.schema));
         if ('example' in parameter || 'examples' in parameter)
-            nodes.push(...(await renderExamples({ example: parameter.example, examples: parameter.examples }, description, 'application/json', 'write', openapiVersion)));
+            nodes.push(...(await renderExamples({ example: parameter.example, examples: parameter.examples }, description, 'application/json', 'write', openapiVersion, document.openapi)));
         for (const [mediaType, content] of Object.entries('content' in parameter ? (parameter.content ?? {}) : {})) {
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, schemas.linked)));
         }
     }
     const body = getResolvedRef(operation.requestBody, mergeSiblingReferences);
@@ -76,8 +76,8 @@ export const renderOperation = async (document, path, method, pathItem, operatio
             nodes.push(heading(5, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion)));
-            nodes.push(...(await renderEncoding(content.encoding, mediaType, description, schemas, openapiVersion)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, schemas.linked)));
+            nodes.push(...(await renderEncoding(content.encoding, mediaType, description, schemas, openapiVersion, document.openapi)));
         }
     }
     const responses = Object.entries(operation.responses ?? {}).flatMap(([status, reference]) => {
@@ -88,12 +88,12 @@ export const renderOperation = async (document, path, method, pathItem, operatio
         nodes.push(heading(4, text('Responses')));
     for (const { status, response } of responses) {
         nodes.push(heading(5, text(`Status: ${status}${response.description ? ` ${response.description}` : ''}`)));
-        nodes.push(...(await renderHeaders(response.headers, description, schemas, openapiVersion)), ...(await renderResponseLinks(response.links, description)));
+        nodes.push(...(await renderHeaders(response.headers, description, schemas, openapiVersion, document.openapi)), ...(await renderResponseLinks(response.links, description)));
         for (const [mediaType, content] of Object.entries(response.content ?? {})) {
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion, document.openapi, schemas.linked)));
         }
     }
     return nodes;

package/dist/render-schema.d.ts

@@ -1,5 +1,6 @@
 import type { MaybeRefSchemaObject, SchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/schema';
 import type { RootContent } from 'mdast';
+import type { SchemaReferenceOptions } from './select-document.js';
 /** Boolean schemas must survive rendering without being coerced into empty objects. */
 type MarkdownSchema = MaybeRefSchemaObject | boolean;
 type SchemaView = {
@@ -56,12 +57,13 @@ type RenderOptions = {
  * run concurrently, and each needs its own record.
  */
 export type SchemaRenderer = {
+    linked: boolean;
     view: (schema: MarkdownSchema) => SchemaView;
     render: (schema: MarkdownSchema, depth?: number, ancestors?: readonly unknown[], options?: RenderOptions) => RootContent[];
     /** Restore the node budget, for example for each operation or model section. */
     beginSection: () => void;
     /** Start a document that shares normalized views, given the models it renders in its own sections. */
-    forDocument: (models?: Record<string, MarkdownSchema>) => SchemaRenderer;
+    forDocument: (models?: Record<string, MarkdownSchema>, options?: SchemaReferenceOptions) => SchemaRenderer;
 };
 type SchemaRendererOptions = {
     /** Upper bound on expanded schema nodes per section, so no description can make a page unbounded. */

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

@@ -1 +1 @@
-{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}

package/dist/render-schema.js

@@ -1,7 +1,6 @@
-import { unescapeJsonPointer } from '@scalar/helpers/json/unescape-json-pointer';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+import { inlineCode, item, link, list, paragraph, safeUrl, strong, text } from './markdown-nodes.js';
 /** Guards against stack exhaustion. Past it, references to models point to their own section instead. */
 const MAX_DEPTH = 64;
 /**
@@ -29,11 +28,10 @@ const referenceKeys = new Set(['$ref', '$ref-value', '$global', '$status']);
 const emphasis = (...children) => ({ type: 'emphasis', children });
 /** Prefer the component name, which is how model sections and other references identify the schema. */
 const getReferenceName = (ref) => {
-    const match = /^#\/components\/schemas\/([^/]+)$/.exec(ref);
-    if (!match)
-        return ref;
     try {
-        return unescapeJsonPointer(match[1]);
+        // URI fragments are decoded before JSON Pointer segments and escapes, exactly once.
+        const match = /^#\/components\/schemas\/([^/]+)$/.exec(decodeURIComponent(ref));
+        return match ? match[1].replaceAll('~1', '/').replaceAll('~0', '~') : ref;
     }
     catch {
         return ref;
@@ -133,7 +131,8 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             nodes.push(text(`${nodes.length ? ' — ' : ''}${value.description}`));
         return nodes;
     };
-    const forDocument = (models = {}) => {
+    const forDocument = (models = {}, settings = {}) => {
+        const linked = settings.schemaReferences?.mode === 'linked';
         /** Shared schemas this document already expanded, with the name later references use. */
         const shown = new Map();
         /** Models that the document renders in their own sections after the operations. */
@@ -152,6 +151,31 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             return nodes;
         };
         const render = (input, depth = 0, ancestors = [], options = {}) => {
+            if (linked && isObject(input) && '$ref' in input && typeof input.$ref === 'string') {
+                const target = getResolvedRef(input);
+                // Reference siblings are independent constraints, not replacements for target keywords.
+                const siblings = Object.fromEntries(Object.entries(input).filter(([key]) => !referenceKeys.has(key)));
+                const hasSiblings = Object.keys(siblings).length > 0;
+                if (depth > 0 || target === undefined) {
+                    const name = getReferenceName(input.$ref);
+                    const url = settings.schemaReferences?.resolveUrl?.({ ref: input.$ref, name });
+                    const nodes = [
+                        paragraph(text('Schema: '), url && safeUrl(url) ? link(url, name) : inlineCode(name)),
+                    ];
+                    if (hasSiblings)
+                        nodes.push(...render(siblings, depth, ancestors));
+                    return nodes;
+                }
+                // An alias with siblings is another reference boundary. Keep its reference visible
+                // instead of overwriting it with the outer reference during normalization.
+                if (hasSiblings || (isObject(target) && '$ref' in target)) {
+                    return [
+                        ...(hasSiblings ? [paragraph(strong(text('All of:')))] : []),
+                        ...render(target, depth + 1, ancestors),
+                        ...(hasSiblings ? render(siblings, depth, ancestors) : []),
+                    ];
+                }
+            }
             // Follow the original target: merging reference siblings creates fresh objects.
             const identity = getResolvedRef(input) ?? input;
             if (typeof identity === 'object' && ancestors.includes(identity)) {
@@ -206,6 +230,13 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
                 if (annotations.length)
                     nodes.push(paragraph(...annotations));
             }
+            if (linked) {
+                // A reference sibling may require a field declared only in the target schema.
+                const declared = new Set(value.properties.map(([name]) => name));
+                const required = [...value.required].filter((name) => !declared.has(name));
+                if (required.length)
+                    nodes.push(paragraph(strong(text('Required fields:')), text(' '), inlineCode(required.join(', '))));
+            }
             if (value.properties.length) {
                 const properties = value.properties.map(([name, schema]) => {
                     const child = view(schema);
@@ -244,6 +275,7 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             return nodes;
         };
         return {
+            linked,
             view,
             render,
             beginSection: () => {

package/dist/restore-boolean-schemas.d.ts

@@ -1,7 +1,14 @@
+/** Where a value sits in an OpenAPI description: a schema, a map of schemas, or anything else. */
+export type SchemaPosition = 'document' | 'schema' | 'map';
+/**
+ * Returns the position of the value stored under `key`, or `undefined` when that value
+ * is not part of the schema tree, such as example payloads and schema metadata.
+ */
+export declare const getChildPosition: (position: SchemaPosition, key: string) => SchemaPosition | undefined;
 /**
  * The workspace schema currently casts boolean JSON Schemas into empty objects.
  * Restore them only in schema positions, never in example payloads or metadata.
  * TODO: Remove this bridge when the shared schema accepts boolean JSON Schemas.
  */
-export declare const restoreBooleanSchemas: (source: unknown, target: unknown) => void;
+export declare const restoreBooleanSchemas: (source: unknown, target: unknown, position?: SchemaPosition) => void;
 //# sourceMappingURL=restore-boolean-schemas.d.ts.map

package/dist/restore-boolean-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"restore-boolean-schemas.d.ts","sourceRoot":"","sources":["../src/restore-boolean-schemas.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,OAAO,EAAE,QAAQ,OAAO,KAAG,IA0DxE,CAAA"}
+{"version":3,"file":"restore-boolean-schemas.d.ts","sourceRoot":"","sources":["../src/restore-boolean-schemas.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAA;AAmB1D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,cAAc,EAAE,KAAK,MAAM,KAAG,cAAc,GAAG,SAWzF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,OAAO,EACf,QAAQ,OAAO,EACf,WAAU,cAA2B,KACpC,IA2BF,CAAA"}

package/dist/restore-boolean-schemas.js

@@ -1,46 +1,50 @@
 import { isObject } from '@scalar/helpers/object/is-object';
+const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const schemaFields = new Set([
+    'items',
+    'not',
+    'additionalProperties',
+    'additionalItems',
+    'contains',
+    'contentSchema',
+    'propertyNames',
+    'if',
+    'then',
+    'else',
+    'unevaluatedProperties',
+    'unevaluatedItems',
+]);
+/**
+ * Returns the position of the value stored under `key`, or `undefined` when that value
+ * is not part of the schema tree, such as example payloads and schema metadata.
+ */
+export const getChildPosition = (position, key) => {
+    if (position === 'map')
+        return 'schema';
+    if (position === 'schema') {
+        if (schemaMaps.has(key))
+            return 'map';
+        if (schemaArrays.has(key) || schemaFields.has(key))
+            return 'schema';
+        return undefined;
+    }
+    if (key === 'schema' || key === 'itemSchema')
+        return 'schema';
+    if (key === 'schemas')
+        return 'map';
+    if (['example', 'examples', 'default', 'const', 'enum'].includes(key))
+        return undefined;
+    return 'document';
+};
 /**
  * The workspace schema currently casts boolean JSON Schemas into empty objects.
  * Restore them only in schema positions, never in example payloads or metadata.
  * TODO: Remove this bridge when the shared schema accepts boolean JSON Schemas.
  */
-export const restoreBooleanSchemas = (source, target) => {
+export const restoreBooleanSchemas = (source, target, position = 'document') => {
     const seen = new WeakSet();
-    const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
-    const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
-    const schemaFields = new Set([
-        'items',
-        'not',
-        'additionalProperties',
-        'additionalItems',
-        'contains',
-        'propertyNames',
-        'if',
-        'then',
-        'else',
-        'unevaluatedProperties',
-        'unevaluatedItems',
-        '$ref-value',
-    ]);
-    const getChildContext = (context, key) => {
-        if (context === 'map')
-            return 'schema';
-        if (context === 'schema') {
-            if (schemaMaps.has(key))
-                return 'map';
-            if (schemaArrays.has(key) || schemaFields.has(key))
-                return 'schema';
-            return undefined;
-        }
-        if (key === 'schema' || key === 'itemSchema')
-            return 'schema';
-        if (key === 'schemas')
-            return 'map';
-        if (['example', 'examples', 'default', 'const', 'enum'].includes(key))
-            return undefined;
-        return 'document';
-    };
-    const visit = (original, coerced, context = 'document') => {
+    const visit = (original, coerced, context) => {
         if (context === 'schema' && typeof original === 'boolean')
             return original;
         if (!original || typeof original !== 'object' || !coerced || typeof coerced !== 'object' || seen.has(coerced))
@@ -61,7 +65,7 @@ export const restoreBooleanSchemas = (source, target) => {
                 const property = Object.getOwnPropertyDescriptor(coerced, key);
                 if (!property || !('value' in property))
                     continue;
-                const childContext = getChildContext(context, key);
+                const childContext = getChildPosition(context, key);
                 if (childContext === undefined)
                     continue;
                 Object.defineProperty(coerced, key, { ...property, value: visit(value, property.value, childContext) });
@@ -69,5 +73,5 @@ export const restoreBooleanSchemas = (source, target) => {
         }
         return coerced;
     };
-    visit(source, target);
+    visit(source, target, position);
 };

package/dist/select-document.d.ts

@@ -10,9 +10,21 @@ export type OperationSelector = {
     pointer: string;
 };
 /** Select one reference page, or omit selectors for the whole document. */
-export type OpenApiRenderOptions = {
+export type OpenApiRenderOptions = SchemaReferenceOptions & ({
     [Key in keyof PageSelectors]: Partial<Record<Exclude<keyof PageSelectors, Key>, never>> & Pick<PageSelectors, Key>;
-}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>;
+}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>);
+/** Control shared-schema expansion without assuming a documentation URL layout. */
+export type SchemaReferenceOptions = {
+    /** Expand root schemas, link nested references, and omit generated examples and the transitive appendix. */
+    schemaReferences?: {
+        mode: 'linked';
+        /** Return a published URL, or undefined to retain the schema name as plain text. */
+        resolveUrl?: (reference: {
+            ref: string;
+            name: string;
+        }) => string | undefined;
+    };
+};
 type PageSelectors = {
     operation: OperationSelector;
     tag: string;

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

@@ -1 +1 @@
-{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eAuN9F,CAAA"}
+{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GACvD,CACI;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GACrF,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CAC3B,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAA;AAEH,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4GAA4G;IAC5G,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAA;QACd,oFAAoF;QACpF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,GAAG,SAAS,CAAA;KAC9E,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eA2N9F,CAAA"}

package/dist/select-document.js

@@ -126,7 +126,7 @@ export const selectDocument = (document, options = {}) => {
     if (!isObject(options)) {
         throw new Error('Render options must be an object');
     }
-    const keys = Object.keys(options).filter((key) => options[key] !== undefined);
+    const keys = Object.keys(options).filter((key) => key !== 'schemaReferences' && options[key] !== undefined);
     if (!keys.length) {
         return document;
     }
@@ -320,9 +320,11 @@ export const selectDocument = (document, options = {}) => {
             }
         }
     };
-    visit({ paths: selected.paths, webhooks: selected.webhooks });
-    for (const root of modelRoots) {
-        visit(root);
+    if (options.schemaReferences?.mode !== 'linked') {
+        visit({ paths: selected.paths, webhooks: selected.webhooks });
+        for (const root of modelRoots) {
+            visit(root);
+        }
     }
     selected.components = {
         ...document.components,

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.2.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "@scalar/code-highlight": "0.4.7",
-    "@scalar/helpers": "0.14.0",
-    "@scalar/json-magic": "0.15.1",
-    "@scalar/openapi-upgrader": "0.3.1",
-    "@scalar/workspace-store": "0.66.0",
+    "@scalar/helpers": "0.16.0",
+    "@scalar/json-magic": "0.15.3",
+    "@scalar/openapi-upgrader": "0.4.1",
+    "@scalar/workspace-store": "0.67.1",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",