@scalar/openapi-to-markdown 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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

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) => 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,KACpC,eAAe,EAoCjB,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) => {
     if (source.example !== undefined)
         return [{ value: source.example }];
     if (source.examples && Object.keys(source.examples).length) {
@@ -88,7 +91,7 @@ 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 [];
         });
     }
@@ -97,8 +100,16 @@ export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3
         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-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,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,KACpC,OAAO,CAAC,WAAW,EAAE,CAmDvB,CAAA"}

package/dist/render-examples.js

@@ -1,10 +1,13 @@
-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]')));
@@ -13,6 +16,10 @@ export const renderExamples = async (source, description, mediaType = 'applicati
         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,CA0CvB,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)));
         }
         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)));
         }
         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,CA4GvB,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)));
         }
     }
     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)));
+            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)));
         }
     }
     return nodes;

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/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.2.0",
+  "version": "1.3.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.15.0",
+    "@scalar/json-magic": "0.15.2",
+    "@scalar/openapi-upgrader": "0.4.0",
+    "@scalar/workspace-store": "0.67.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",