@skmtc/core 0.29.0 → 0.31.0

package/script/helpers/naming.d.ts

@@ -4,7 +4,7 @@ import type { Method } from '../types/Method.js';
  * Determines the endpoint type based on HTTP method.
  *
  * @param operation - The OpenAPI operation to analyze
- * @returns 'query' for GET operations, 'mutation' for all others
+ * @returns 'query' for GET and QUERY operations, 'mutation' for all others
  *
  * @example
  * ```typescript
@@ -67,6 +67,7 @@ export declare const toArgsName: (operation: OasOperation) => string;
  * console.log(toMethodVerb('put'));  // 'Update'
  * console.log(toMethodVerb('get'));  // 'get'
  * console.log(toMethodVerb('delete')); // 'delete'
+ * console.log(toMethodVerb('query')); // 'Query'
  * ```
  */
 export declare const toMethodVerb: (method: Method) => string;

package/script/helpers/naming.js

@@ -6,7 +6,7 @@ const strings_js_1 = require("./strings.js");
  * Determines the endpoint type based on HTTP method.
  *
  * @param operation - The OpenAPI operation to analyze
- * @returns 'query' for GET operations, 'mutation' for all others
+ * @returns 'query' for GET and QUERY operations, 'mutation' for all others
  *
  * @example
  * ```typescript
@@ -18,7 +18,8 @@ const strings_js_1 = require("./strings.js");
  * ```
  */
 const toEndpointType = (operation) => {
-    return operation.method === 'get' ? 'query' : 'mutation';
+    // QUERY is safe and idempotent, like GET.
+    return operation.method === 'get' || operation.method === 'query' ? 'query' : 'mutation';
 };
 exports.toEndpointType = toEndpointType;
 /**
@@ -85,6 +86,7 @@ exports.toArgsName = toArgsName;
  * console.log(toMethodVerb('put'));  // 'Update'
  * console.log(toMethodVerb('get'));  // 'get'
  * console.log(toMethodVerb('delete')); // 'delete'
+ * console.log(toMethodVerb('query')); // 'Query'
  * ```
  */
 const toMethodVerb = (method) => {

package/script/mod.d.ts

@@ -146,6 +146,7 @@ export * from './oas/info/info-types.js';
 export * from './oas/license/License.js';
 export * from './oas/license/license-types.js';
 export * from './oas/mediaType/MediaType.js';
+export * from './oas/mediaType/jsonMediaType.js';
 export * from './oas/integer/Integer.js';
 export * from './oas/integer/integer-types.js';
 export * from './parse/v3-0/integer/toInteger.js';

package/script/mod.js

@@ -162,6 +162,7 @@ __exportStar(require("./oas/info/info-types.js"), exports);
 __exportStar(require("./oas/license/License.js"), exports);
 __exportStar(require("./oas/license/license-types.js"), exports);
 __exportStar(require("./oas/mediaType/MediaType.js"), exports);
+__exportStar(require("./oas/mediaType/jsonMediaType.js"), exports);
 __exportStar(require("./oas/integer/Integer.js"), exports);
 __exportStar(require("./oas/integer/integer-types.js"), exports);
 __exportStar(require("./parse/v3-0/integer/toInteger.js"), exports);

package/script/oas/discriminator/Discriminator.d.ts

@@ -2,10 +2,13 @@ import "../../_dnt.polyfills.js";
 export type DiscriminatorFields = {
     propertyName: string;
     mapping?: Record<string, string>;
+    /** Schema to use when the discriminating value has no mapping entry (OpenAPI 3.2) */
+    defaultMapping?: string;
 };
 export declare class OasDiscriminator {
     oasType: 'discriminator';
     propertyName: string;
     mapping?: Record<string, string>;
+    defaultMapping?: string;
     constructor(fields: DiscriminatorFields);
 }

package/script/oas/discriminator/Discriminator.js

@@ -22,8 +22,15 @@ class OasDiscriminator {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "defaultMapping", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.propertyName = fields.propertyName;
         this.mapping = fields.mapping;
+        this.defaultMapping = fields.defaultMapping;
     }
 }
 exports.OasDiscriminator = OasDiscriminator;

package/script/oas/document/Document.d.ts

@@ -20,6 +20,11 @@ import type { OasExternalDocs } from '../externalDocs/ExternalDocs.js';
 export type DocumentFields = {
     /** OpenAPI specification version (e.g., '3.0.0', '3.1.0') */
     openapi: string;
+    /**
+     * The document's own URI (OpenAPI 3.2 `$self`). Stored only: reference
+     * resolution does not use it.
+     */
+    $self?: string | undefined;
     /** API metadata including title, version, description */
     info: OasInfo;
     /** Array of server objects providing connectivity information */
@@ -215,6 +220,8 @@ export declare class OasDocument {
     set fields(fields: DocumentFields);
     /** OpenAPI specification version */
     get openapi(): string;
+    /** The document's own URI (OpenAPI 3.2 `$self`) */
+    get $self(): string | undefined;
     /** API metadata */
     get info(): OasInfo;
     get servers(): OasServer[] | undefined;

package/script/oas/document/Document.js

@@ -228,6 +228,13 @@ class OasDocument {
         }
         return __classPrivateFieldGet(this, _OasDocument_fields, "f").openapi;
     }
+    /** The document's own URI (OpenAPI 3.2 `$self`) */
+    get $self() {
+        if (!__classPrivateFieldGet(this, _OasDocument_fields, "f")) {
+            throw new Error(`Accessing '$self' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _OasDocument_fields, "f").$self;
+    }
     /** API metadata */
     get info() {
         if (!__classPrivateFieldGet(this, _OasDocument_fields, "f")) {
@@ -314,6 +321,7 @@ class OasDocument {
     toJSON() {
         return {
             openapi: this.openapi,
+            ...(this.$self !== undefined ? { $self: this.$self } : {}),
             info: this.info,
             servers: this.servers,
             operations: this.operations,

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

@@ -11,6 +11,10 @@ export type ExampleFields = {
     description?: string;
     /** The example value — absent when the example is given as an `externalValue` */
     value?: unknown;
+    /** The example as data that is valid against its schema (OpenAPI 3.2) */
+    dataValue?: unknown;
+    /** The example in its serialized form (OpenAPI 3.2) */
+    serializedValue?: string;
     /** The external value of the example */
     externalValue?: string;
     /** Custom extension fields (x-* properties) */
@@ -23,6 +27,8 @@ export declare class OasExample {
     summary?: string;
     description?: string;
     value?: unknown;
+    dataValue?: unknown;
+    serializedValue?: string;
     externalValue?: string;
     extensionFields?: Record<string, unknown>;
     constructor(fields: ExampleFields);
@@ -31,5 +37,8 @@ export declare class OasExample {
     /** Returns itself */
     resolve(): OasExample;
     resolveOnce(): OasExample;
-    toJsonSchema(_options: ToJsonSchemaOptions): OpenAPIV3.ExampleObject;
+    toJsonSchema(_options: ToJsonSchemaOptions): OpenAPIV3.ExampleObject & {
+        dataValue?: unknown;
+        serializedValue?: string;
+    };
 }

package/script/oas/example/Example.js

@@ -29,6 +29,18 @@ class OasExample {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "dataValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "serializedValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "externalValue", {
             enumerable: true,
             configurable: true,
@@ -44,6 +56,8 @@ class OasExample {
         this.summary = fields.summary;
         this.description = fields.description;
         this.value = fields.value;
+        this.dataValue = fields.dataValue;
+        this.serializedValue = fields.serializedValue;
         this.externalValue = fields.externalValue;
         this.extensionFields = fields.extensionFields;
     }
@@ -63,6 +77,8 @@ class OasExample {
             summary: this.summary,
             description: this.description,
             value: this.value,
+            ...(this.dataValue !== undefined ? { dataValue: this.dataValue } : {}),
+            ...(this.serializedValue !== undefined ? { serializedValue: this.serializedValue } : {}),
             // 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/oas/header/Header.d.ts

@@ -77,9 +77,11 @@ export declare class OasHeader {
     resolve(): OasHeader;
     resolveOnce(): OasHeader;
     /** Returns schema for the header. Either, `schema` property if
-     * definedor value matching `mediaType` from `content` property.
+     * defined or value matching `mediaType` from `content` property. When
+     * `content` has exactly one entry (the spec requires one), its schema is
+     * used whatever the media type, as in `OasParameter.toSchema`.
      *
-     * @param mediaType - Optional media type to get schema for. Defaults to `application/json`
+     * @param mediaType - Optional media type to get schema for, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      */
     toSchema(mediaType?: string): OasSchema | OasRef<'schema'>;
     toJsonSchema(options: ToJsonSchemaOptions): OpenAPIV3.HeaderObject;

package/script/oas/header/Header.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasHeader = void 0;
+const toContentSchema_js_1 = require("../mediaType/toContentSchema.js");
 /**
  * Represents a Header Object in the OpenAPI Specification.
  *
@@ -109,17 +110,23 @@ class OasHeader {
         return this;
     }
     /** Returns schema for the header. Either, `schema` property if
-     * definedor value matching `mediaType` from `content` property.
+     * defined or value matching `mediaType` from `content` property. When
+     * `content` has exactly one entry (the spec requires one), its schema is
+     * used whatever the media type, as in `OasParameter.toSchema`.
      *
-     * @param mediaType - Optional media type to get schema for. Defaults to `application/json`
+     * @param mediaType - Optional media type to get schema for, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      */
-    toSchema(mediaType = 'application/json') {
+    toSchema(mediaType) {
         if (this.schema) {
             return this.schema;
         }
-        const schema = this.content?.[mediaType]?.schema;
+        const contentEntries = Object.values(this.content ?? {});
+        const onlyEntry = contentEntries.length === 1 ? contentEntries[0] : undefined;
+        const schema = (0, toContentSchema_js_1.toContentSchema)(this.content, mediaType) ?? onlyEntry?.schema;
         if (!schema) {
-            throw new Error(`Schema not found for media type ${mediaType}`);
+            throw new Error(mediaType === undefined
+                ? 'Schema not found for a JSON media type'
+                : `Schema not found for media type "${mediaType}"`);
         }
         return schema;
     }

package/script/oas/mediaType/MediaType.d.ts

@@ -13,12 +13,18 @@ export type MediaTypeFields = {
     mediaType: string;
     /** The schema defining the structure of the content */
     schema?: OasSchema | OasRef<'schema'> | undefined;
+    /** The schema of each item in a sequential media type (OpenAPI 3.2) */
+    itemSchema?: OasSchema | OasRef<'schema'> | undefined;
     /** Example values for the media type */
     examples?: Record<string, OasExample | OasRef<'example'>> | undefined;
     /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
     /** Encoding information for multipart or form data */
     encoding?: Record<string, unknown> | undefined;
+    /** Positional Encoding Objects for a multipart array (OpenAPI 3.2) */
+    prefixEncoding?: Record<string, unknown>[] | undefined;
+    /** Encoding Object for each array item (OpenAPI 3.2) */
+    itemEncoding?: Record<string, unknown> | undefined;
 };
 /**
  * Represents a Media Type Object in the OpenAPI Specification.
@@ -104,12 +110,18 @@ export declare class OasMediaType extends OasBase {
     mediaType: string;
     /** The schema defining the structure and validation rules for the content */
     schema: OasSchema | OasRef<'schema'> | undefined;
+    /** The schema of each item in a sequential media type (OpenAPI 3.2) */
+    itemSchema: OasSchema | OasRef<'schema'> | undefined;
     /** Example values demonstrating the media type content */
     examples: Record<string, OasExample | OasRef<'example'>> | undefined;
     /** Custom extension fields (x-* properties) defined for this media type */
     extensionFields: Record<string, unknown> | undefined;
     /** Encoding information for multipart and form data serialization */
     encoding?: Record<string, unknown> | undefined;
+    /** Positional Encoding Objects for a multipart array (OpenAPI 3.2), stored as-is */
+    prefixEncoding?: Record<string, unknown>[] | undefined;
+    /** Encoding Object for each array item (OpenAPI 3.2), stored as-is */
+    itemEncoding?: Record<string, unknown> | undefined;
     /**
      * Creates a new OasMediaType instance.
      *

package/script/oas/mediaType/MediaType.js

@@ -108,6 +108,13 @@ class OasMediaType extends OasBase_js_1.OasBase {
             writable: true,
             value: void 0
         });
+        /** The schema of each item in a sequential media type (OpenAPI 3.2) */
+        Object.defineProperty(this, "itemSchema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /** Example values demonstrating the media type content */
         Object.defineProperty(this, "examples", {
             enumerable: true,
@@ -129,10 +136,27 @@ class OasMediaType extends OasBase_js_1.OasBase {
             writable: true,
             value: void 0
         });
+        /** Positional Encoding Objects for a multipart array (OpenAPI 3.2), stored as-is */
+        Object.defineProperty(this, "prefixEncoding", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Encoding Object for each array item (OpenAPI 3.2), stored as-is */
+        Object.defineProperty(this, "itemEncoding", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.mediaType = fields.mediaType;
         this.schema = fields.schema;
+        this.itemSchema = fields.itemSchema;
         this.examples = fields.examples;
         this.encoding = fields.encoding;
+        this.prefixEncoding = fields.prefixEncoding;
+        this.itemEncoding = fields.itemEncoding;
         this.extensionFields = fields.extensionFields;
     }
     /**

package/script/oas/mediaType/jsonMediaType.d.ts

@@ -0,0 +1,50 @@
+import type { OasRef } from '../ref/Ref.js';
+import type { OasSchema } from '../schema/Schema.js';
+import type { OasMediaType } from './MediaType.js';
+/**
+ * The media type without its parameters, trimmed and lowercased:
+ * `Application/JSON; charset=utf-8` → `application/json`.
+ */
+export declare const toMediaTypeEssence: (mediaType: string) => string;
+/**
+ * True when a body of this media type is one JSON value: `application/json`,
+ * or any `application/…+json` (the RFC 6839 structured syntax suffix, e.g.
+ * `application/vnd.api+json`, `application/ld+json`,
+ * `application/problem+json`). Parameters and case are ignored, so
+ * `application/json;v=1.0` is JSON.
+ *
+ * False for everything else, including:
+ * - `text/json`: not registered; RFC 8259 registers only `application/json`.
+ * - `application/x-ndjson`, `application/jsonl`: a stream of JSON values, not
+ *   one value.
+ * - ranges such as `*\/*`, `application/*` and `application/*+json`: they do
+ *   not name one type.
+ * - names without the suffix, such as `application/vnd.goa.error`, even when
+ *   the API sends JSON under them.
+ */
+export declare const isJsonMediaType: (mediaType: string) => boolean;
+/** True when the media type is the full range `*\/*`, parameters and case ignored. */
+export declare const isAnyMediaType: (mediaType: string) => boolean;
+/** The media type a body is read from, and its schema. */
+export type JsonContent = {
+    /** The key in `content`: a JSON-like media type, or `*\/*` (with any parameters). */
+    mediaType: string;
+    /**
+     * The media type to send or expect the body as: `mediaType` when it is
+     * JSON-like, `application/json` when the body is read from `*\/*`.
+     */
+    contentType: string;
+    schema: OasSchema | OasRef<'schema'> | undefined;
+};
+/**
+ * Choose the media type a body is read from: `application/json` exactly when
+ * it is a key, else the first JSON-like key in document order (see
+ * {@link isJsonMediaType}), else the `*\/*` key when its schema is an object,
+ * array, union or `$ref`. `*\/*` admits JSON, and documents use it for JSON
+ * bodies (springdoc writes it for every response); the parser logs
+ * `WILDCARD_MEDIA_TYPE` for every body read this way. `undefined` otherwise:
+ * there is no fall back to a specific non-JSON type, to a narrower range such
+ * as `application/*`, or to a scalar schema under `*\/*`, since a consumer
+ * would read that body as JSON.
+ */
+export declare const toJsonContent: (content: Record<string, OasMediaType> | undefined) => JsonContent | undefined;

package/script/oas/mediaType/jsonMediaType.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonContent = exports.isAnyMediaType = exports.isJsonMediaType = exports.toMediaTypeEssence = void 0;
+/**
+ * The media type without its parameters, trimmed and lowercased:
+ * `Application/JSON; charset=utf-8` → `application/json`.
+ */
+const toMediaTypeEssence = (mediaType) => (mediaType.split(';')[0] ?? '').trim().toLowerCase();
+exports.toMediaTypeEssence = toMediaTypeEssence;
+/**
+ * True when a body of this media type is one JSON value: `application/json`,
+ * or any `application/…+json` (the RFC 6839 structured syntax suffix, e.g.
+ * `application/vnd.api+json`, `application/ld+json`,
+ * `application/problem+json`). Parameters and case are ignored, so
+ * `application/json;v=1.0` is JSON.
+ *
+ * False for everything else, including:
+ * - `text/json`: not registered; RFC 8259 registers only `application/json`.
+ * - `application/x-ndjson`, `application/jsonl`: a stream of JSON values, not
+ *   one value.
+ * - ranges such as `*\/*`, `application/*` and `application/*+json`: they do
+ *   not name one type.
+ * - names without the suffix, such as `application/vnd.goa.error`, even when
+ *   the API sends JSON under them.
+ */
+const isJsonMediaType = (mediaType) => {
+    const essence = (0, exports.toMediaTypeEssence)(mediaType);
+    return essence === 'application/json' || /^application\/[^/*\s]+\+json$/.test(essence);
+};
+exports.isJsonMediaType = isJsonMediaType;
+/** True when the media type is the full range `*\/*`, parameters and case ignored. */
+const isAnyMediaType = (mediaType) => (0, exports.toMediaTypeEssence)(mediaType) === '*/*';
+exports.isAnyMediaType = isAnyMediaType;
+/**
+ * True when a schema under `*\/*` can be read as one JSON value: an object,
+ * array, union or `$ref`. A scalar is not: under `*\/*` a `string` is usually
+ * a text body, and `string` with `format: binary` a file.
+ */
+const isJsonShaped = (schema) => schema !== undefined &&
+    (schema.isRef() || schema.type === 'object' || schema.type === 'array' || schema.type === 'union');
+/**
+ * Choose the media type a body is read from: `application/json` exactly when
+ * it is a key, else the first JSON-like key in document order (see
+ * {@link isJsonMediaType}), else the `*\/*` key when its schema is an object,
+ * array, union or `$ref`. `*\/*` admits JSON, and documents use it for JSON
+ * bodies (springdoc writes it for every response); the parser logs
+ * `WILDCARD_MEDIA_TYPE` for every body read this way. `undefined` otherwise:
+ * there is no fall back to a specific non-JSON type, to a narrower range such
+ * as `application/*`, or to a scalar schema under `*\/*`, since a consumer
+ * would read that body as JSON.
+ */
+const toJsonContent = (content) => {
+    if (!content) {
+        return undefined;
+    }
+    const mediaTypes = Object.keys(content);
+    const jsonMediaType = 'application/json' in content ? 'application/json' : mediaTypes.find(exports.isJsonMediaType);
+    if (jsonMediaType !== undefined) {
+        return {
+            mediaType: jsonMediaType,
+            contentType: jsonMediaType,
+            schema: content[jsonMediaType]?.schema
+        };
+    }
+    const anyMediaType = mediaTypes.find(exports.isAnyMediaType);
+    const schema = anyMediaType === undefined ? undefined : content[anyMediaType]?.schema;
+    return anyMediaType !== undefined && isJsonShaped(schema)
+        ? { mediaType: anyMediaType, contentType: 'application/json', schema }
+        : undefined;
+};
+exports.toJsonContent = toJsonContent;

package/script/oas/mediaType/toContentSchema.d.ts

@@ -0,0 +1,8 @@
+import type { OasRef } from '../ref/Ref.js';
+import type { OasSchema } from '../schema/Schema.js';
+import type { OasMediaType } from './MediaType.js';
+/**
+ * The schema a `toSchema(mediaType?)` lookup returns: an exact key lookup when
+ * `mediaType` is given, else the schema of `toJsonContent`.
+ */
+export declare const toContentSchema: (content: Record<string, OasMediaType> | undefined, mediaType: string | undefined) => OasSchema | OasRef<"schema"> | undefined;

package/script/oas/mediaType/toContentSchema.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toContentSchema = void 0;
+const jsonMediaType_js_1 = require("./jsonMediaType.js");
+/**
+ * The schema a `toSchema(mediaType?)` lookup returns: an exact key lookup when
+ * `mediaType` is given, else the schema of `toJsonContent`.
+ */
+const toContentSchema = (content, mediaType) => mediaType === undefined ? (0, jsonMediaType_js_1.toJsonContent)(content)?.schema : content?.[mediaType]?.schema;
+exports.toContentSchema = toContentSchema;

package/script/oas/operation/Operation.d.ts

@@ -60,6 +60,14 @@ export type OperationFields = {
 export type ToRequestBodyMapArgs = {
     schema: OasSchema | OasRef<'schema'>;
     requestBody: OasRequestBody;
+    /** The `content` key the schema was read from. */
+    mediaType: string;
+    /**
+     * The media type to send the body as: the explicit media type when one was
+     * passed, else `contentType` of `OasRequestBody.toJsonContent` (the
+     * JSON-like key, or `application/json` for a body read from `*\/*`).
+     */
+    contentType: string;
 };
 export declare class OasOperation extends OasBase {
     /** Type identifier for OAS operation objects */
@@ -120,7 +128,7 @@ export declare class OasOperation extends OasBase {
      * Maps the request body schema to a custom value using the provided mapping function.
      *
      * @param map - Function to transform the request body schema and metadata
-     * @param mediaType - Media type to extract schema from (default: 'application/json')
+     * @param mediaType - Media type to extract schema from, an exact lookup. Omitted: the media type `OasRequestBody.toJsonContent` picks.
      * @returns Mapped value or undefined if no request body schema found
      */
     toRequestBody<V>(map: ({ schema, requestBody }: ToRequestBodyMapArgs) => V, mediaType?: string): V | undefined;
@@ -133,7 +141,7 @@ export declare class OasOperation extends OasBase {
      * {@link traverseSchema}.
      *
      * @param path - Schema path; `path[0]` must be `'SuccessResponse'` or `'RequestBody'`.
-     * @param mediaType - Media type the body schema is read from (default `application/json`).
+     * @param mediaType - Media type the body schema is read from, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      * @returns The schema at the path (may be an unresolved `$ref`).
      * @throws Error on an unknown root, a missing response/request body, or a non-navigable segment.
      */

package/script/oas/operation/Operation.js

@@ -167,13 +167,25 @@ class OasOperation extends OasBase_js_1.OasBase {
      * Maps the request body schema to a custom value using the provided mapping function.
      *
      * @param map - Function to transform the request body schema and metadata
-     * @param mediaType - Media type to extract schema from (default: 'application/json')
+     * @param mediaType - Media type to extract schema from, an exact lookup. Omitted: the media type `OasRequestBody.toJsonContent` picks.
      * @returns Mapped value or undefined if no request body schema found
      */
-    toRequestBody(map, mediaType = 'application/json') {
+    toRequestBody(map, mediaType) {
         const requestBody = this.requestBody?.resolve();
-        const schema = requestBody?.content[mediaType]?.schema;
-        return schema ? map({ schema, requestBody }) : undefined;
+        if (!requestBody) {
+            return undefined;
+        }
+        const chosen = mediaType === undefined
+            ? requestBody.toJsonContent()
+            : { mediaType, contentType: mediaType, schema: requestBody.toSchema(mediaType) };
+        return chosen?.schema
+            ? map({
+                schema: chosen.schema,
+                requestBody,
+                mediaType: chosen.mediaType,
+                contentType: chosen.contentType
+            })
+            : undefined;
     }
     /**
      * Navigate into this operation's response or request body schema along an
@@ -184,11 +196,11 @@ class OasOperation extends OasBase_js_1.OasBase {
      * {@link traverseSchema}.
      *
      * @param path - Schema path; `path[0]` must be `'SuccessResponse'` or `'RequestBody'`.
-     * @param mediaType - Media type the body schema is read from (default `application/json`).
+     * @param mediaType - Media type the body schema is read from, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      * @returns The schema at the path (may be an unresolved `$ref`).
      * @throws Error on an unknown root, a missing response/request body, or a non-navigable segment.
      */
-    traverse(path, mediaType = 'application/json') {
+    traverse(path, mediaType) {
         const [root, ...rest] = path;
         let rootSchema;
         switch (root) {
@@ -203,7 +215,8 @@ class OasOperation extends OasBase_js_1.OasBase {
         }
         if (!rootSchema) {
             const label = root === 'SuccessResponse' ? 'success response' : 'request body';
-            throw new Error(`Operation "${this.method} ${this.path}" has no ${label} schema for media type "${mediaType}"`);
+            const mediaTypeLabel = mediaType === undefined ? 'a JSON media type' : `media type "${mediaType}"`;
+            throw new Error(`Operation "${this.method} ${this.path}" has no ${label} schema for ${mediaTypeLabel}`);
         }
         return (0, traverseSchema_js_1.traverseSchema)(rootSchema, rest);
     }

package/script/oas/parameter/Parameter.d.ts

@@ -240,9 +240,10 @@ export declare class OasParameter extends OasBase {
      * Extracts the schema for this parameter.
      *
      * Returns the direct schema if available, or extracts schema from content
-     * for the specified media type.
+     * for the specified media type. When `content` has exactly one entry, its
+     * schema is used whatever the media type.
      *
-     * @param mediaType - Media type to extract schema from when using content definitions
+     * @param mediaType - Media type to extract schema from when using content definitions, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      * @returns The parameter's schema object
      * @throws Error if no schema is found for the specified media type
      */

package/script/oas/parameter/Parameter.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasParameter = void 0;
 require("../../_dnt.polyfills.js");
 const OasBase_js_1 = require("../../types/OasBase.js");
+const toContentSchema_js_1 = require("../mediaType/toContentSchema.js");
 /**
  * Represents a Parameter Object in the OpenAPI Specification.
  *
@@ -295,19 +296,24 @@ class OasParameter extends OasBase_js_1.OasBase {
      * Extracts the schema for this parameter.
      *
      * Returns the direct schema if available, or extracts schema from content
-     * for the specified media type.
+     * for the specified media type. When `content` has exactly one entry, its
+     * schema is used whatever the media type.
      *
-     * @param mediaType - Media type to extract schema from when using content definitions
+     * @param mediaType - Media type to extract schema from when using content definitions, an exact lookup. Omitted: the JSON media type (`application/json`, else the first JSON-like type, else `*\/*`).
      * @returns The parameter's schema object
      * @throws Error if no schema is found for the specified media type
      */
-    toSchema(mediaType = 'application/json') {
+    toSchema(mediaType) {
         if (this.schema) {
             return this.schema;
         }
-        const schema = this.content?.[mediaType]?.schema;
+        const contentEntries = Object.values(this.content ?? {});
+        const onlyEntry = contentEntries.length === 1 ? contentEntries[0] : undefined;
+        const schema = (0, toContentSchema_js_1.toContentSchema)(this.content, mediaType) ?? onlyEntry?.schema;
         if (!schema) {
-            throw new Error(`Schema not found for media type ${mediaType}`);
+            throw new Error(mediaType === undefined
+                ? 'Schema not found for a JSON media type'
+                : `Schema not found for media type "${mediaType}"`);
         }
         return schema;
     }

package/script/oas/parameter/parameter-types.d.ts

@@ -1,5 +1,13 @@
 import * as v from 'valibot';
-export type OasParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+/**
+ * Parameter locations across OpenAPI 3.0 to 3.2. `querystring` is new in
+ * 3.2; each parser tree accepts its own subset.
+ */
+export type OasParameterLocation = 'query' | 'querystring' | 'header' | 'path' | 'cookie';
 export declare const oasParameterLocation: v.GenericSchema<OasParameterLocation>;
-export type OasParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+/**
+ * Parameter styles across OpenAPI 3.0 to 3.2. `cookie` is new in 3.2; each
+ * parser tree accepts its own subset.
+ */
+export type OasParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject' | 'cookie';
 export declare const oasParameterStyle: v.GenericSchema<OasParameterStyle>;