@skmtc/core 0.28.3 → 0.28.5

package/esm/helpers/collateExamples.d.ts

@@ -9,6 +9,16 @@ type CollatedExampleArgs = {
     objectSchema: OasSchema | OasRef<'schema'> | undefined;
     /** Current recursion depth (used to prevent infinite loops) */
     depth: number;
+    /**
+     * The `$ref` pointers already entered on THIS path, used to cut reference
+     * cycles. Callers start collation without it; the function threads it.
+     *
+     * Path-scoped rather than global on purpose. A global set would also stop a
+     * cycle, and would additionally drop the example for the SECOND of two
+     * sibling uses of the same schema — silently emptying samples on every
+     * document that reuses a type, which is most of them.
+     */
+    seen?: ReadonlySet<string>;
 };
 /**
  * Recursively collates and builds example values from OpenAPI schemas.
@@ -155,6 +165,6 @@ type CollatedExampleArgs = {
  * }
  * ```
  */
-export declare const collateExamples: ({ objectSchema, depth }: CollatedExampleArgs) => unknown;
+export declare const collateExamples: ({ objectSchema, depth, seen }: CollatedExampleArgs) => unknown;
 export {};
 //# sourceMappingURL=collateExamples.d.ts.map

package/esm/helpers/collateExamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAyF9E,CAAA"}
+{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,+BAA+B,mBAAmB,KAAG,OAyGpF,CAAA"}

package/esm/helpers/collateExamples.js

@@ -145,7 +145,7 @@ import { isEmpty } from './isEmpty.js';
  * }
  * ```
  */
-export const collateExamples = ({ objectSchema, depth }) => {
+export const collateExamples = ({ objectSchema, depth, seen }) => {
     if (!objectSchema) {
         return undefined;
     }
@@ -154,9 +154,21 @@ export const collateExamples = ({ objectSchema, depth }) => {
     }
     switch (objectSchema.type) {
         case 'ref': {
+            // A schema that reaches itself has no finite example, so the recursive
+            // key is omitted and collation continues around it.
+            //
+            // Without this the cycle simply pads the path until the depth limit
+            // throws, roughly sixteen steps in — so a self-referential schema and a
+            // legitimately deep one fail identically, and a caller that only wanted a
+            // sample body gets an exception instead. Cutting the cycle here is what
+            // makes the depth limit mean what it says.
+            if (seen?.has(objectSchema.$ref)) {
+                return undefined;
+            }
             return collateExamples({
                 objectSchema: objectSchema.resolve(),
-                depth: depth + 1
+                depth: depth + 1,
+                seen: new Set(seen ?? []).add(objectSchema.$ref)
             });
         }
         case 'object': {
@@ -170,7 +182,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
                 }
                 const propertyExample = collateExamples({
                     objectSchema: value,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (propertyExample) {
                     output[key] = propertyExample;
@@ -184,7 +197,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
             }
             const itemsExample = collateExamples({
                 objectSchema: objectSchema.items,
-                depth: depth + 1
+                depth: depth + 1,
+                seen
             });
             return itemsExample ? [itemsExample] : undefined;
         }
@@ -202,7 +216,8 @@ export const collateExamples = ({ objectSchema, depth }) => {
             for (const member of objectSchema.members) {
                 const unionExample = collateExamples({
                     objectSchema: member,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (unionExample) {
                     return unionExample;

package/esm/oas/example/Example.d.ts

@@ -9,8 +9,8 @@ export type ExampleFields = {
     summary?: string;
     /** Longer description of the example */
     description?: string;
-    /** The example value */
-    value: unknown;
+    /** The example value — absent when the example is given as an `externalValue` */
+    value?: unknown;
     /** The external value of the example */
     externalValue?: string;
     /** Custom extension fields (x-* properties) */

package/esm/oas/example/Example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,UAAU;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;IAC9B,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,MAAM,EAAE,aAAa;IAQjC,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
+{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,UAAU;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;IAC9B,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,MAAM,EAAE,aAAa;IAQjC,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAUrE"}

package/esm/oas/example/Example.js

@@ -59,7 +59,10 @@ export class OasExample {
         return {
             summary: this.summary,
             description: this.description,
-            value: this.value
+            value: this.value,
+            // Without this an `externalValue`-only example round-trips to an Example
+            // Object holding neither an inline value nor a pointer to one.
+            externalValue: this.externalValue
         };
     }
 }

package/esm/parse/v3-0/example/toExamplesV3.d.ts

@@ -4,7 +4,12 @@ import { OasExample } from '../../../oas/example/Example.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 export type ToExampleSimpleV3Args = {
-    example: OpenAPIV3.ExampleObject;
+    /**
+     * The example value itself. The singular `example` field of a media type,
+     * parameter or header is a LITERAL value — not an Example Object — so it
+     * carries no `summary`, `description` or `externalValue` to read.
+     */
+    example: unknown;
     /** The stack trail for tracing */
     stackTrail: StackTrail;
     /** Parse context for tracing and error handling */
@@ -13,8 +18,8 @@ export type ToExampleSimpleV3Args = {
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
@@ -27,8 +32,8 @@ export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) =>
  * with context for tracing and error handling.
  */
 export type ToExamplesV3Args = {
-    /** Single example object (OpenAPI v3 format) */
-    example: OpenAPIV3.ExampleObject | undefined;
+    /** The singular `example` field — a literal value, not an Example Object */
+    example: unknown;
     /** Collection of named examples (OpenAPI v3 format) */
     examples: Record<string, OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject> | undefined;
     /** Key name for the example context */

package/esm/parse/v3-0/example/toExamplesV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAC,aAAa,CAAA;IAChC,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CASvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAoCtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAqBjD,CAAA"}
+{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAIvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAiDtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAyBjD,CAAA"}

package/esm/parse/v3-0/example/toExamplesV3.js

@@ -5,19 +5,14 @@ import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecif
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
  */
 export const toExampleSimpleV3 = ({ example }) => {
-    const fields = {
-        value: example.value,
-        summary: example.summary,
-        description: example.description,
-        externalValue: example.externalValue
-    };
+    const fields = { value: example };
     return new OasExample(fields);
 };
 /**
@@ -31,31 +26,41 @@ export const toExampleSimpleV3 = ({ example }) => {
  * @returns Record of processed examples, or undefined if no examples
  */
 export const toExamplesV3 = ({ example, examples, exampleKey, stackTrail, context }) => {
-    if (example && examples) {
+    // An empty map is declared but carries nothing, so it cannot be the richer
+    // field — letting it win would discard the singular in favour of no examples
+    // at all.
+    const namedExamples = examples && Object.keys(examples).length > 0 ? examples : undefined;
+    // `example` is a literal, so test presence rather than truthiness — `false`,
+    // `0` and `''` are all valid example values.
+    if (example !== undefined && examples !== undefined) {
         context.logIssue({
             key: 'example',
             level: 'warning',
-            message: `Both example and examples are defined for ${exampleKey}`,
+            message: `Both example and examples are defined for ${exampleKey}; using ${namedExamples ? 'examples' : 'example'}`,
             parent: examples,
             stackTrail,
             type: 'EXAMPLE_AND_EXAMPLES_DEFINED'
         });
     }
-    if (example) {
-        return {
-            [exampleKey]: stackTrail.trace('example', st => toExampleSimpleV3({ example, stackTrail: st, context }))
-        };
-    }
-    if (examples) {
+    // The spec makes the two mutually exclusive, so reaching here with both is
+    // malformed input. Prefer `examples`: it is the richer field — many entries,
+    // each with a summary and description — and the singular carries nothing it
+    // cannot express, so this discards strictly less.
+    if (namedExamples) {
         return stackTrail.trace('examples', st => {
             const output = {};
-            const entries = Object.entries(examples);
+            const entries = Object.entries(namedExamples);
             for (const [key, value] of entries) {
                 output[key] = st.trace(key, st2 => toExampleV3({ example: value, stackTrail: st2, context }));
             }
             return output;
         });
     }
+    if (example !== undefined) {
+        return {
+            [exampleKey]: stackTrail.trace('example', st => toExampleSimpleV3({ example, stackTrail: st, context }))
+        };
+    }
     return undefined;
 };
 /**
@@ -72,7 +77,10 @@ export const toExampleV3 = ({ example, stackTrail, context }) => {
     if (isRef(example)) {
         return toRefV31({ ref: example, refType: 'example', stackTrail, context });
     }
-    const { summary, description, value, ...skipped } = example;
+    // `externalValue` is the alternative to `value` — an example too large or too
+    // awkward to inline. Leaving it in `skipped` both loses it and reports a
+    // standard field as an unexpected property.
+    const { summary, description, value, externalValue, ...skipped } = example;
     const extensionFields = toSpecificationExtensionsV3({
         skipped,
         parent: example,
@@ -84,6 +92,7 @@ export const toExampleV3 = ({ example, stackTrail, context }) => {
         summary,
         description,
         value,
+        externalValue,
         extensionFields
     });
 };

package/esm/parse/v3-0/header/toHeadersV3.d.ts

@@ -11,6 +11,8 @@ export type ToHeadersV3Args = {
 export declare const toHeadersV3: ({ headers, stackTrail, context }: ToHeadersV3Args) => Record<string, OasHeader | OasRef<"header">> | undefined;
 export type ToHeaderV3Args = {
     header: OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject;
+    /** The header's name, used to key a singular `example` */
+    name: string;
     stackTrail: StackTrail;
     context: ParseContextType;
 };

package/esm/parse/v3-0/header/toHeadersV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}
+{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}

package/esm/parse/v3-0/header/toHeadersV3.js

@@ -12,11 +12,11 @@ export const toHeadersV3 = ({ headers, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(headers);
     for (const [key, value] of entries) {
-        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, stackTrail: st, context }));
+        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, name: key, stackTrail: st, context }));
     }
     return output;
 };
-const toHeaderV3 = ({ header, stackTrail, context }) => {
+const toHeaderV3 = ({ header, name, stackTrail, context }) => {
     if (isRef(header)) {
         return toRefV31({ ref: header, refType: 'header', stackTrail, context });
     }
@@ -36,7 +36,7 @@ const toHeaderV3 = ({ header, stackTrail, context }) => {
         examples: toExamplesV3({
             examples,
             example,
-            exampleKey: `TEMP`,
+            exampleKey: name,
             stackTrail,
             context
         }),

package/esm/parse/v3-1/example/toExamplesV3.d.ts

@@ -4,7 +4,12 @@ import { OasExample } from '../../../oas/example/Example.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 export type ToExampleSimpleV3Args = {
-    example: OpenAPIV3.ExampleObject;
+    /**
+     * The example value itself. The singular `example` field of a media type,
+     * parameter or header is a LITERAL value — not an Example Object — so it
+     * carries no `summary`, `description` or `externalValue` to read.
+     */
+    example: unknown;
     /** The stack trail for tracing */
     stackTrail: StackTrail;
     /** Parse context for tracing and error handling */
@@ -13,8 +18,8 @@ export type ToExampleSimpleV3Args = {
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
@@ -27,8 +32,8 @@ export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) =>
  * with context for tracing and error handling.
  */
 export type ToExamplesV3Args = {
-    /** Single example object (OpenAPI v3 format) */
-    example: OpenAPIV3.ExampleObject | undefined;
+    /** The singular `example` field — a literal value, not an Example Object */
+    example: unknown;
     /** Collection of named examples (OpenAPI v3 format) */
     examples: Record<string, OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject> | undefined;
     /** Key name for the example context */

package/esm/parse/v3-1/example/toExamplesV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAC,aAAa,CAAA;IAChC,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CASvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAoCtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAqBjD,CAAA"}
+{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAIvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAiDtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAyBjD,CAAA"}

package/esm/parse/v3-1/example/toExamplesV3.js

@@ -5,19 +5,14 @@ import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecif
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
  */
 export const toExampleSimpleV3 = ({ example }) => {
-    const fields = {
-        value: example.value,
-        summary: example.summary,
-        description: example.description,
-        externalValue: example.externalValue
-    };
+    const fields = { value: example };
     return new OasExample(fields);
 };
 /**
@@ -31,31 +26,41 @@ export const toExampleSimpleV3 = ({ example }) => {
  * @returns Record of processed examples, or undefined if no examples
  */
 export const toExamplesV3 = ({ example, examples, exampleKey, stackTrail, context }) => {
-    if (example && examples) {
+    // An empty map is declared but carries nothing, so it cannot be the richer
+    // field — letting it win would discard the singular in favour of no examples
+    // at all.
+    const namedExamples = examples && Object.keys(examples).length > 0 ? examples : undefined;
+    // `example` is a literal, so test presence rather than truthiness — `false`,
+    // `0` and `''` are all valid example values.
+    if (example !== undefined && examples !== undefined) {
         context.logIssue({
             key: 'example',
             level: 'warning',
-            message: `Both example and examples are defined for ${exampleKey}`,
+            message: `Both example and examples are defined for ${exampleKey}; using ${namedExamples ? 'examples' : 'example'}`,
             parent: examples,
             stackTrail,
             type: 'EXAMPLE_AND_EXAMPLES_DEFINED'
         });
     }
-    if (example) {
-        return {
-            [exampleKey]: stackTrail.trace('example', st => toExampleSimpleV3({ example, stackTrail: st, context }))
-        };
-    }
-    if (examples) {
+    // The spec makes the two mutually exclusive, so reaching here with both is
+    // malformed input. Prefer `examples`: it is the richer field — many entries,
+    // each with a summary and description — and the singular carries nothing it
+    // cannot express, so this discards strictly less.
+    if (namedExamples) {
         return stackTrail.trace('examples', st => {
             const output = {};
-            const entries = Object.entries(examples);
+            const entries = Object.entries(namedExamples);
             for (const [key, value] of entries) {
                 output[key] = st.trace(key, st2 => toExampleV3({ example: value, stackTrail: st2, context }));
             }
             return output;
         });
     }
+    if (example !== undefined) {
+        return {
+            [exampleKey]: stackTrail.trace('example', st => toExampleSimpleV3({ example, stackTrail: st, context }))
+        };
+    }
     return undefined;
 };
 /**
@@ -72,7 +77,10 @@ export const toExampleV3 = ({ example, stackTrail, context }) => {
     if (isRef(example)) {
         return toRefV31({ ref: example, refType: 'example', stackTrail, context });
     }
-    const { summary, description, value, ...skipped } = example;
+    // `externalValue` is the alternative to `value` — an example too large or too
+    // awkward to inline. Leaving it in `skipped` both loses it and reports a
+    // standard field as an unexpected property.
+    const { summary, description, value, externalValue, ...skipped } = example;
     const extensionFields = toSpecificationExtensionsV3({
         skipped,
         parent: example,
@@ -84,6 +92,7 @@ export const toExampleV3 = ({ example, stackTrail, context }) => {
         summary,
         description,
         value,
+        externalValue,
         extensionFields
     });
 };

package/esm/parse/v3-1/header/toHeadersV3.d.ts

@@ -11,6 +11,8 @@ export type ToHeadersV3Args = {
 export declare const toHeadersV3: ({ headers, stackTrail, context }: ToHeadersV3Args) => Record<string, OasHeader | OasRef<"header">> | undefined;
 export type ToHeaderV3Args = {
     header: OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject;
+    /** The header's name, used to key a singular `example` */
+    name: string;
     stackTrail: StackTrail;
     context: ParseContextType;
 };

package/esm/parse/v3-1/header/toHeadersV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}
+{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}

package/esm/parse/v3-1/header/toHeadersV3.js

@@ -12,11 +12,11 @@ export const toHeadersV3 = ({ headers, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(headers);
     for (const [key, value] of entries) {
-        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, stackTrail: st, context }));
+        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, name: key, stackTrail: st, context }));
     }
     return output;
 };
-const toHeaderV3 = ({ header, stackTrail, context }) => {
+const toHeaderV3 = ({ header, name, stackTrail, context }) => {
     if (isRef(header)) {
         return toRefV31({ ref: header, refType: 'header', stackTrail, context });
     }
@@ -36,7 +36,7 @@ const toHeaderV3 = ({ header, stackTrail, context }) => {
         examples: toExamplesV3({
             examples,
             example,
-            exampleKey: `TEMP`,
+            exampleKey: name,
             stackTrail,
             context
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.28.3",
+  "version": "0.28.5",
   "description": "Skmtc is a declarative code generation framework",
   "keywords": [
     "openapi",

package/script/helpers/collateExamples.d.ts

@@ -9,6 +9,16 @@ type CollatedExampleArgs = {
     objectSchema: OasSchema | OasRef<'schema'> | undefined;
     /** Current recursion depth (used to prevent infinite loops) */
     depth: number;
+    /**
+     * The `$ref` pointers already entered on THIS path, used to cut reference
+     * cycles. Callers start collation without it; the function threads it.
+     *
+     * Path-scoped rather than global on purpose. A global set would also stop a
+     * cycle, and would additionally drop the example for the SECOND of two
+     * sibling uses of the same schema — silently emptying samples on every
+     * document that reuses a type, which is most of them.
+     */
+    seen?: ReadonlySet<string>;
 };
 /**
  * Recursively collates and builds example values from OpenAPI schemas.
@@ -155,6 +165,6 @@ type CollatedExampleArgs = {
  * }
  * ```
  */
-export declare const collateExamples: ({ objectSchema, depth }: CollatedExampleArgs) => unknown;
+export declare const collateExamples: ({ objectSchema, depth, seen }: CollatedExampleArgs) => unknown;
 export {};
 //# sourceMappingURL=collateExamples.d.ts.map

package/script/helpers/collateExamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAyF9E,CAAA"}
+{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,+BAA+B,mBAAmB,KAAG,OAyGpF,CAAA"}

package/script/helpers/collateExamples.js

@@ -148,7 +148,7 @@ const isEmpty_js_1 = require("./isEmpty.js");
  * }
  * ```
  */
-const collateExamples = ({ objectSchema, depth }) => {
+const collateExamples = ({ objectSchema, depth, seen }) => {
     if (!objectSchema) {
         return undefined;
     }
@@ -157,9 +157,21 @@ const collateExamples = ({ objectSchema, depth }) => {
     }
     switch (objectSchema.type) {
         case 'ref': {
+            // A schema that reaches itself has no finite example, so the recursive
+            // key is omitted and collation continues around it.
+            //
+            // Without this the cycle simply pads the path until the depth limit
+            // throws, roughly sixteen steps in — so a self-referential schema and a
+            // legitimately deep one fail identically, and a caller that only wanted a
+            // sample body gets an exception instead. Cutting the cycle here is what
+            // makes the depth limit mean what it says.
+            if (seen?.has(objectSchema.$ref)) {
+                return undefined;
+            }
             return (0, exports.collateExamples)({
                 objectSchema: objectSchema.resolve(),
-                depth: depth + 1
+                depth: depth + 1,
+                seen: new Set(seen ?? []).add(objectSchema.$ref)
             });
         }
         case 'object': {
@@ -173,7 +185,8 @@ const collateExamples = ({ objectSchema, depth }) => {
                 }
                 const propertyExample = (0, exports.collateExamples)({
                     objectSchema: value,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (propertyExample) {
                     output[key] = propertyExample;
@@ -187,7 +200,8 @@ const collateExamples = ({ objectSchema, depth }) => {
             }
             const itemsExample = (0, exports.collateExamples)({
                 objectSchema: objectSchema.items,
-                depth: depth + 1
+                depth: depth + 1,
+                seen
             });
             return itemsExample ? [itemsExample] : undefined;
         }
@@ -205,7 +219,8 @@ const collateExamples = ({ objectSchema, depth }) => {
             for (const member of objectSchema.members) {
                 const unionExample = (0, exports.collateExamples)({
                     objectSchema: member,
-                    depth: depth + 1
+                    depth: depth + 1,
+                    seen
                 });
                 if (unionExample) {
                     return unionExample;

package/script/oas/example/Example.d.ts

@@ -9,8 +9,8 @@ export type ExampleFields = {
     summary?: string;
     /** Longer description of the example */
     description?: string;
-    /** The example value */
-    value: unknown;
+    /** The example value — absent when the example is given as an `externalValue` */
+    value?: unknown;
     /** The external value of the example */
     externalValue?: string;
     /** Custom extension fields (x-* properties) */

package/script/oas/example/Example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,UAAU;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;IAC9B,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,MAAM,EAAE,aAAa;IAQjC,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
+{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,UAAU;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;IAC9B,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,MAAM,EAAE,aAAa;IAQjC,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAUrE"}

package/script/oas/example/Example.js

@@ -62,7 +62,10 @@ class OasExample {
         return {
             summary: this.summary,
             description: this.description,
-            value: this.value
+            value: this.value,
+            // Without this an `externalValue`-only example round-trips to an Example
+            // Object holding neither an inline value nor a pointer to one.
+            externalValue: this.externalValue
         };
     }
 }

package/script/parse/v3-0/example/toExamplesV3.d.ts

@@ -4,7 +4,12 @@ import { OasExample } from '../../../oas/example/Example.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 export type ToExampleSimpleV3Args = {
-    example: OpenAPIV3.ExampleObject;
+    /**
+     * The example value itself. The singular `example` field of a media type,
+     * parameter or header is a LITERAL value — not an Example Object — so it
+     * carries no `summary`, `description` or `externalValue` to read.
+     */
+    example: unknown;
     /** The stack trail for tracing */
     stackTrail: StackTrail;
     /** Parse context for tracing and error handling */
@@ -13,8 +18,8 @@ export type ToExampleSimpleV3Args = {
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
@@ -27,8 +32,8 @@ export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) =>
  * with context for tracing and error handling.
  */
 export type ToExamplesV3Args = {
-    /** Single example object (OpenAPI v3 format) */
-    example: OpenAPIV3.ExampleObject | undefined;
+    /** The singular `example` field — a literal value, not an Example Object */
+    example: unknown;
     /** Collection of named examples (OpenAPI v3 format) */
     examples: Record<string, OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject> | undefined;
     /** Key name for the example context */

package/script/parse/v3-0/example/toExamplesV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAC,aAAa,CAAA;IAChC,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CASvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAoCtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAqBjD,CAAA"}
+{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAIvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAiDtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAyBjD,CAAA"}

package/script/parse/v3-0/example/toExamplesV3.js

@@ -8,19 +8,14 @@ const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toS
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
  */
 const toExampleSimpleV3 = ({ example }) => {
-    const fields = {
-        value: example.value,
-        summary: example.summary,
-        description: example.description,
-        externalValue: example.externalValue
-    };
+    const fields = { value: example };
     return new Example_js_1.OasExample(fields);
 };
 exports.toExampleSimpleV3 = toExampleSimpleV3;
@@ -35,31 +30,41 @@ exports.toExampleSimpleV3 = toExampleSimpleV3;
  * @returns Record of processed examples, or undefined if no examples
  */
 const toExamplesV3 = ({ example, examples, exampleKey, stackTrail, context }) => {
-    if (example && examples) {
+    // An empty map is declared but carries nothing, so it cannot be the richer
+    // field — letting it win would discard the singular in favour of no examples
+    // at all.
+    const namedExamples = examples && Object.keys(examples).length > 0 ? examples : undefined;
+    // `example` is a literal, so test presence rather than truthiness — `false`,
+    // `0` and `''` are all valid example values.
+    if (example !== undefined && examples !== undefined) {
         context.logIssue({
             key: 'example',
             level: 'warning',
-            message: `Both example and examples are defined for ${exampleKey}`,
+            message: `Both example and examples are defined for ${exampleKey}; using ${namedExamples ? 'examples' : 'example'}`,
             parent: examples,
             stackTrail,
             type: 'EXAMPLE_AND_EXAMPLES_DEFINED'
         });
     }
-    if (example) {
-        return {
-            [exampleKey]: stackTrail.trace('example', st => (0, exports.toExampleSimpleV3)({ example, stackTrail: st, context }))
-        };
-    }
-    if (examples) {
+    // The spec makes the two mutually exclusive, so reaching here with both is
+    // malformed input. Prefer `examples`: it is the richer field — many entries,
+    // each with a summary and description — and the singular carries nothing it
+    // cannot express, so this discards strictly less.
+    if (namedExamples) {
         return stackTrail.trace('examples', st => {
             const output = {};
-            const entries = Object.entries(examples);
+            const entries = Object.entries(namedExamples);
             for (const [key, value] of entries) {
                 output[key] = st.trace(key, st2 => (0, exports.toExampleV3)({ example: value, stackTrail: st2, context }));
             }
             return output;
         });
     }
+    if (example !== undefined) {
+        return {
+            [exampleKey]: stackTrail.trace('example', st => (0, exports.toExampleSimpleV3)({ example, stackTrail: st, context }))
+        };
+    }
     return undefined;
 };
 exports.toExamplesV3 = toExamplesV3;
@@ -77,7 +82,10 @@ const toExampleV3 = ({ example, stackTrail, context }) => {
     if ((0, refFns_js_1.isRef)(example)) {
         return (0, toRefV31_js_1.toRefV31)({ ref: example, refType: 'example', stackTrail, context });
     }
-    const { summary, description, value, ...skipped } = example;
+    // `externalValue` is the alternative to `value` — an example too large or too
+    // awkward to inline. Leaving it in `skipped` both loses it and reports a
+    // standard field as an unexpected property.
+    const { summary, description, value, externalValue, ...skipped } = example;
     const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
         skipped,
         parent: example,
@@ -89,6 +97,7 @@ const toExampleV3 = ({ example, stackTrail, context }) => {
         summary,
         description,
         value,
+        externalValue,
         extensionFields
     });
 };

package/script/parse/v3-0/header/toHeadersV3.d.ts

@@ -11,6 +11,8 @@ export type ToHeadersV3Args = {
 export declare const toHeadersV3: ({ headers, stackTrail, context }: ToHeadersV3Args) => Record<string, OasHeader | OasRef<"header">> | undefined;
 export type ToHeaderV3Args = {
     header: OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject;
+    /** The header's name, used to key a singular `example` */
+    name: string;
     stackTrail: StackTrail;
     context: ParseContextType;
 };

package/script/parse/v3-0/header/toHeadersV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}
+{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-0/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}

package/script/parse/v3-0/header/toHeadersV3.js

@@ -15,12 +15,12 @@ const toHeadersV3 = ({ headers, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(headers);
     for (const [key, value] of entries) {
-        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, stackTrail: st, context }));
+        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, name: key, stackTrail: st, context }));
     }
     return output;
 };
 exports.toHeadersV3 = toHeadersV3;
-const toHeaderV3 = ({ header, stackTrail, context }) => {
+const toHeaderV3 = ({ header, name, stackTrail, context }) => {
     if ((0, refFns_js_1.isRef)(header)) {
         return (0, toRefV31_js_1.toRefV31)({ ref: header, refType: 'header', stackTrail, context });
     }
@@ -40,7 +40,7 @@ const toHeaderV3 = ({ header, stackTrail, context }) => {
         examples: (0, toExamplesV3_js_1.toExamplesV3)({
             examples,
             example,
-            exampleKey: `TEMP`,
+            exampleKey: name,
             stackTrail,
             context
         }),

package/script/parse/v3-1/example/toExamplesV3.d.ts

@@ -4,7 +4,12 @@ import { OasExample } from '../../../oas/example/Example.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 export type ToExampleSimpleV3Args = {
-    example: OpenAPIV3.ExampleObject;
+    /**
+     * The example value itself. The singular `example` field of a media type,
+     * parameter or header is a LITERAL value — not an Example Object — so it
+     * carries no `summary`, `description` or `externalValue` to read.
+     */
+    example: unknown;
     /** The stack trail for tracing */
     stackTrail: StackTrail;
     /** Parse context for tracing and error handling */
@@ -13,8 +18,8 @@ export type ToExampleSimpleV3Args = {
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
@@ -27,8 +32,8 @@ export declare const toExampleSimpleV3: ({ example }: ToExampleSimpleV3Args) =>
  * with context for tracing and error handling.
  */
 export type ToExamplesV3Args = {
-    /** Single example object (OpenAPI v3 format) */
-    example: OpenAPIV3.ExampleObject | undefined;
+    /** The singular `example` field — a literal value, not an Example Object */
+    example: unknown;
     /** Collection of named examples (OpenAPI v3 format) */
     examples: Record<string, OpenAPIV3.ExampleObject | OpenAPIV3.ReferenceObject> | undefined;
     /** Key name for the example context */

package/script/parse/v3-1/example/toExamplesV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,SAAS,CAAC,aAAa,CAAA;IAChC,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CASvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAA;IAC5C,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAoCtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAqBjD,CAAA"}
+{"version":3,"file":"toExamplesV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/example/toExamplesV3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAE/B,qBAAqB,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAIvD,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzF,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,wDAM1B,gBAAgB,KAAG,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAiDtE,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,CAAC,eAAe,CAAA;IAC5D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,UAAU,GAAG,MAAM,CAAC,SAAS,CAyBjD,CAAA"}

package/script/parse/v3-1/example/toExamplesV3.js

@@ -8,19 +8,14 @@ const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toS
 /**
  * Creates a simple OAS example from a value.
  *
- * Converts a raw example value into an OasExample object with basic
- * fields. Used for simple example scenarios where only the value matters.
+ * Wraps a literal example value as an {@link OasExample}. Used for the singular
+ * `example` field, where only the value exists.
  *
  * @param args - Arguments containing the example value
  * @returns OasExample object with the provided value
  */
 const toExampleSimpleV3 = ({ example }) => {
-    const fields = {
-        value: example.value,
-        summary: example.summary,
-        description: example.description,
-        externalValue: example.externalValue
-    };
+    const fields = { value: example };
     return new Example_js_1.OasExample(fields);
 };
 exports.toExampleSimpleV3 = toExampleSimpleV3;
@@ -35,31 +30,41 @@ exports.toExampleSimpleV3 = toExampleSimpleV3;
  * @returns Record of processed examples, or undefined if no examples
  */
 const toExamplesV3 = ({ example, examples, exampleKey, stackTrail, context }) => {
-    if (example && examples) {
+    // An empty map is declared but carries nothing, so it cannot be the richer
+    // field — letting it win would discard the singular in favour of no examples
+    // at all.
+    const namedExamples = examples && Object.keys(examples).length > 0 ? examples : undefined;
+    // `example` is a literal, so test presence rather than truthiness — `false`,
+    // `0` and `''` are all valid example values.
+    if (example !== undefined && examples !== undefined) {
         context.logIssue({
             key: 'example',
             level: 'warning',
-            message: `Both example and examples are defined for ${exampleKey}`,
+            message: `Both example and examples are defined for ${exampleKey}; using ${namedExamples ? 'examples' : 'example'}`,
             parent: examples,
             stackTrail,
             type: 'EXAMPLE_AND_EXAMPLES_DEFINED'
         });
     }
-    if (example) {
-        return {
-            [exampleKey]: stackTrail.trace('example', st => (0, exports.toExampleSimpleV3)({ example, stackTrail: st, context }))
-        };
-    }
-    if (examples) {
+    // The spec makes the two mutually exclusive, so reaching here with both is
+    // malformed input. Prefer `examples`: it is the richer field — many entries,
+    // each with a summary and description — and the singular carries nothing it
+    // cannot express, so this discards strictly less.
+    if (namedExamples) {
         return stackTrail.trace('examples', st => {
             const output = {};
-            const entries = Object.entries(examples);
+            const entries = Object.entries(namedExamples);
             for (const [key, value] of entries) {
                 output[key] = st.trace(key, st2 => (0, exports.toExampleV3)({ example: value, stackTrail: st2, context }));
             }
             return output;
         });
     }
+    if (example !== undefined) {
+        return {
+            [exampleKey]: stackTrail.trace('example', st => (0, exports.toExampleSimpleV3)({ example, stackTrail: st, context }))
+        };
+    }
     return undefined;
 };
 exports.toExamplesV3 = toExamplesV3;
@@ -77,7 +82,10 @@ const toExampleV3 = ({ example, stackTrail, context }) => {
     if ((0, refFns_js_1.isRef)(example)) {
         return (0, toRefV31_js_1.toRefV31)({ ref: example, refType: 'example', stackTrail, context });
     }
-    const { summary, description, value, ...skipped } = example;
+    // `externalValue` is the alternative to `value` — an example too large or too
+    // awkward to inline. Leaving it in `skipped` both loses it and reports a
+    // standard field as an unexpected property.
+    const { summary, description, value, externalValue, ...skipped } = example;
     const extensionFields = (0, toSpecificationExtensionsV3_js_1.toSpecificationExtensionsV3)({
         skipped,
         parent: example,
@@ -89,6 +97,7 @@ const toExampleV3 = ({ example, stackTrail, context }) => {
         summary,
         description,
         value,
+        externalValue,
         extensionFields
     });
 };

package/script/parse/v3-1/header/toHeadersV3.d.ts

@@ -11,6 +11,8 @@ export type ToHeadersV3Args = {
 export declare const toHeadersV3: ({ headers, stackTrail, context }: ToHeadersV3Args) => Record<string, OasHeader | OasRef<"header">> | undefined;
 export type ToHeaderV3Args = {
     header: OpenAPIV3.ReferenceObject | OpenAPIV3.HeaderObject;
+    /** The header's name, used to key a singular `example` */
+    name: string;
     stackTrail: StackTrail;
     context: ParseContextType;
 };

package/script/parse/v3-1/header/toHeadersV3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}
+{"version":3,"file":"toHeadersV3.d.ts","sourceRoot":"","sources":["../../../../src/parse/v3-1/header/toHeadersV3.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AAEzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAChE,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IACvF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,kCAIzB,eAAe,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,SAenE,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,YAAY,CAAA;IAC1D,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA"}

package/script/parse/v3-1/header/toHeadersV3.js

@@ -15,12 +15,12 @@ const toHeadersV3 = ({ headers, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(headers);
     for (const [key, value] of entries) {
-        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, stackTrail: st, context }));
+        output[key] = stackTrail.trace(key, st => toHeaderV3({ header: value, name: key, stackTrail: st, context }));
     }
     return output;
 };
 exports.toHeadersV3 = toHeadersV3;
-const toHeaderV3 = ({ header, stackTrail, context }) => {
+const toHeaderV3 = ({ header, name, stackTrail, context }) => {
     if ((0, refFns_js_1.isRef)(header)) {
         return (0, toRefV31_js_1.toRefV31)({ ref: header, refType: 'header', stackTrail, context });
     }
@@ -40,7 +40,7 @@ const toHeaderV3 = ({ header, stackTrail, context }) => {
         examples: (0, toExamplesV3_js_1.toExamplesV3)({
             examples,
             example,
-            exampleKey: `TEMP`,
+            exampleKey: name,
             stackTrail,
             context
         }),