@skmtc/core 0.30.1 → 0.32.0

package/esm/parse/logBodyMediaTypes.js

@@ -0,0 +1,50 @@
+import { isAnyMediaType, toJsonContent, toMediaTypeEssence } from '../oas/mediaType/jsonMediaType.js';
+/**
+ * Log at most one issue for a parsed response or request body, from the same
+ * choice the lookups make (`toJsonContent`), so the issue and the lookup
+ * cannot disagree. Called after the body is built, so a body that fails to
+ * parse logs nothing.
+ *
+ * - `WILDCARD_MEDIA_TYPE` (`warning`): the body is read from `*\/*` as JSON,
+ *   though the document does not say its format.
+ * - `NO_JSON_MEDIA_TYPE` (`debug`): no lookup reads the body, and its keys
+ *   include a range (`*\/*` with a scalar schema, `application/*`), so its
+ *   format is unknown.
+ *
+ * A body with only specific non-JSON types (`multipart/form-data`,
+ * `application/octet-stream`, `text/plain`) logs nothing: that is a normal
+ * text, form or binary body.
+ */
+export const logBodyMediaTypes = ({ content, stackTrail, context }) => {
+    const mediaTypes = Object.keys(content ?? {});
+    if (mediaTypes.length === 0) {
+        return;
+    }
+    const listed = mediaTypes.map(mediaType => `"${mediaType}"`).join(', ');
+    // `parent` is only the keys: the issue log serializes it on every issue.
+    const parent = { mediaTypes };
+    const chosen = toJsonContent(content);
+    if (chosen !== undefined) {
+        if (isAnyMediaType(chosen.mediaType)) {
+            context.logIssue({
+                key: 'content',
+                level: 'warning',
+                type: 'WILDCARD_MEDIA_TYPE',
+                message: `Content has no JSON media type (${listed}), so the body is read from "*/*" as JSON although the document does not say its format`,
+                parent,
+                stackTrail
+            });
+        }
+        return;
+    }
+    if (mediaTypes.some(mediaType => toMediaTypeEssence(mediaType).includes('*'))) {
+        context.logIssue({
+            key: 'content',
+            level: 'debug',
+            type: 'NO_JSON_MEDIA_TYPE',
+            message: `Content names only a media type range or non-JSON types (${listed}), so no lookup without a media type reads its schema`,
+            parent,
+            stackTrail
+        });
+    }
+};

package/esm/parse/v3-0/parameter/toParameterV3.d.ts

@@ -1,10 +1,11 @@
 import type { ParseContextType } from '../../../context/parseTypes.js';
-import type { OasParameterLocation } from '../../../oas/parameter/parameter-types.js';
+import type { OasParameterLocation, OasParameterStyle } from '../../../oas/parameter/parameter-types.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import { OasParameter } from '../../../oas/parameter/Parameter.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 type ParameterLocation = Exclude<OasParameterLocation, 'querystring'>;
+type ParameterStyle = Exclude<OasParameterStyle, 'cookie'>;
 export type ToParameterListV3Args = {
     parameters: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[] | undefined;
     stackTrail: StackTrail;
@@ -35,7 +36,7 @@ export type ToStyleArgs = {
 };
 export type ToExplodeArgs = {
     explode: boolean | undefined;
-    style: string | undefined;
+    style: ParameterStyle;
     stackTrail: StackTrail;
 };
 export {};

package/esm/parse/v3-0/parameter/toParameterV3.js

@@ -72,14 +72,15 @@ const toParameterV3 = ({ parameter, stackTrail, context }) => {
     }
     // Set missing 'required' to true for path parameters and false for others
     const defaultRequired = typeof required === 'undefined' ? (parsedLocation === 'path' ? true : false) : required;
+    const parsedStyle = stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st }));
     const fields = {
         name,
         location: parsedLocation,
         description,
         required: defaultRequired,
         deprecated,
-        style: stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st })),
-        explode: stackTrail.trace('explode', st => toExplode({ explode, style, stackTrail: st })),
+        style: parsedStyle,
+        explode: stackTrail.trace('explode', st => toExplode({ explode, style: parsedStyle, stackTrail: st })),
         allowEmptyValue,
         allowReserved,
         schema: stackTrail.trace('schema', st => toOptionalSchemaV3({ schema, stackTrail: st, context })),

package/esm/parse/v3-0/pathItem/toPathItemV3.js

@@ -1,12 +1,22 @@
 import { toParameterListV3 } from '../parameter/toParameterV3.js';
 import { OasPathItem } from '../../../oas/pathItem/PathItem.js';
+import { toOptionalServersV3 } from '../server/toServerV3.js';
+import { tryParseAt } from '../../../context/tryParseAt.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 export const toPathItemV3 = ({ pathItem, stackTrail, context }) => {
-    const { summary, description, parameters, ...skipped } = pathItem;
+    const { summary, description, parameters, servers, ...skipped } = pathItem;
     return new OasPathItem({
         summary,
         description,
         parameters: stackTrail.trace('parameters', st => toParameterListV3({ parameters, stackTrail: st, context })),
+        servers: tryParseAt({
+            stackTrail,
+            key: 'servers',
+            context,
+            type: 'INVALID_OPERATION',
+            parent: pathItem,
+            fn: st => toOptionalServersV3({ servers, stackTrail: st, context })
+        }),
         extensionFields: toSpecificationExtensionsV3({
             skipped,
             parent: pathItem,

package/esm/parse/v3-0/requestBody/toRequestBodiesV3.js

@@ -3,6 +3,7 @@ import { toRefV31 } from '../ref/toRefV31.js';
 import { toMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasRequestBody } from '../../../oas/requestBody/RequestBody.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -26,7 +27,9 @@ export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    logBodyMediaTypes({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 export const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {
     if (!requestBodies) {

package/esm/parse/v3-0/response/toResponseV3.js

@@ -6,6 +6,7 @@ import { toOptionalMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasResponse } from '../../../oas/response/Response.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { tryParseAt } from '../../../context/tryParseAt.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -45,11 +46,13 @@ export const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => toHeadersV3({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => toLinksV3({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => toOptionalMediaTypeItemsV3({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new OasResponse({
         description,
         headers: parsedHeaders,
         links: parsedLinks,
         content: parsedContent,
         extensionFields
     }, context));
+    logBodyMediaTypes({ content: parsedContent, stackTrail, context });
+    return parsed;
 };

package/esm/parse/v3-1/parameter/toParameterV3.d.ts

@@ -1,10 +1,11 @@
 import type { ParseContextType } from '../../../context/parseTypes.js';
-import type { OasParameterLocation } from '../../../oas/parameter/parameter-types.js';
+import type { OasParameterLocation, OasParameterStyle } from '../../../oas/parameter/parameter-types.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import { OasParameter } from '../../../oas/parameter/Parameter.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
 import type { StackTrail } from '../../../context/StackTrail.js';
 type ParameterLocation = Exclude<OasParameterLocation, 'querystring'>;
+type ParameterStyle = Exclude<OasParameterStyle, 'cookie'>;
 export type ToParameterListV3Args = {
     parameters: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[] | undefined;
     stackTrail: StackTrail;
@@ -35,7 +36,7 @@ export type ToStyleArgs = {
 };
 export type ToExplodeArgs = {
     explode: boolean | undefined;
-    style: string | undefined;
+    style: ParameterStyle;
     stackTrail: StackTrail;
 };
 export {};

package/esm/parse/v3-1/parameter/toParameterV3.js

@@ -72,14 +72,15 @@ const toParameterV3 = ({ parameter, stackTrail, context }) => {
     }
     // Set missing 'required' to true for path parameters and false for others
     const defaultRequired = typeof required === 'undefined' ? (parsedLocation === 'path' ? true : false) : required;
+    const parsedStyle = stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st }));
     const fields = {
         name,
         location: parsedLocation,
         description,
         required: defaultRequired,
         deprecated,
-        style: stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st })),
-        explode: stackTrail.trace('explode', st => toExplode({ explode, style, stackTrail: st })),
+        style: parsedStyle,
+        explode: stackTrail.trace('explode', st => toExplode({ explode, style: parsedStyle, stackTrail: st })),
         allowEmptyValue,
         allowReserved,
         schema: stackTrail.trace('schema', st => toOptionalSchemaV3({ schema, stackTrail: st, context })),

package/esm/parse/v3-1/pathItem/toPathItemV3.js

@@ -1,12 +1,22 @@
 import { toParameterListV3 } from '../parameter/toParameterV3.js';
 import { OasPathItem } from '../../../oas/pathItem/PathItem.js';
+import { toOptionalServersV3 } from '../server/toServerV3.js';
+import { tryParseAt } from '../../../context/tryParseAt.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 export const toPathItemV3 = ({ pathItem, stackTrail, context }) => {
-    const { summary, description, parameters, ...skipped } = pathItem;
+    const { summary, description, parameters, servers, ...skipped } = pathItem;
     return new OasPathItem({
         summary,
         description,
         parameters: stackTrail.trace('parameters', st => toParameterListV3({ parameters, stackTrail: st, context })),
+        servers: tryParseAt({
+            stackTrail,
+            key: 'servers',
+            context,
+            type: 'INVALID_OPERATION',
+            parent: pathItem,
+            fn: st => toOptionalServersV3({ servers, stackTrail: st, context })
+        }),
         extensionFields: toSpecificationExtensionsV3({
             skipped,
             parent: pathItem,

package/esm/parse/v3-1/requestBody/toRequestBodiesV3.js

@@ -3,6 +3,7 @@ import { toRefV31 } from '../ref/toRefV31.js';
 import { toMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasRequestBody } from '../../../oas/requestBody/RequestBody.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -26,7 +27,9 @@ export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    logBodyMediaTypes({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 export const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {
     if (!requestBodies) {

package/esm/parse/v3-1/response/toResponseV3.js

@@ -6,6 +6,7 @@ import { toOptionalMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasResponse } from '../../../oas/response/Response.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { tryParseAt } from '../../../context/tryParseAt.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -45,11 +46,13 @@ export const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => toHeadersV3({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => toLinksV3({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => toOptionalMediaTypeItemsV3({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new OasResponse({
         description,
         headers: parsedHeaders,
         links: parsedLinks,
         content: parsedContent,
         extensionFields
     }, context));
+    logBodyMediaTypes({ content: parsedContent, stackTrail, context });
+    return parsed;
 };

package/esm/parse/v3-2/parameter/toParameterV3.d.ts

@@ -1,5 +1,5 @@
 import type { ParseContextType } from '../../../context/parseTypes.js';
-import { type OasParameterLocation } from '../../../oas/parameter/parameter-types.js';
+import { type OasParameterLocation, type OasParameterStyle } from '../../../oas/parameter/parameter-types.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import { OasParameter } from '../../../oas/parameter/Parameter.js';
 import type { OasRef } from '../../../oas/ref/Ref.js';
@@ -34,6 +34,6 @@ export type ToStyleArgs = {
 };
 export type ToExplodeArgs = {
     explode: boolean | undefined;
-    style: string | undefined;
+    style: OasParameterStyle | undefined;
     stackTrail: StackTrail;
 };

package/esm/parse/v3-2/parameter/toParameterV3.js

@@ -91,14 +91,15 @@ const toParameterV3 = ({ parameter, stackTrail, context }) => {
     }
     // Set missing 'required' to true for path parameters and false for others
     const defaultRequired = typeof required === 'undefined' ? (parsedLocation === 'path' ? true : false) : required;
+    const parsedStyle = stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st }));
     const fields = {
         name,
         location: parsedLocation,
         description,
         required: defaultRequired,
         deprecated,
-        style: stackTrail.trace('style', st => toStyle({ style, location: parsedLocation, stackTrail: st })),
-        explode: stackTrail.trace('explode', st => toExplode({ explode, style, stackTrail: st })),
+        style: parsedStyle,
+        explode: stackTrail.trace('explode', st => toExplode({ explode, style: parsedStyle, stackTrail: st })),
         allowEmptyValue,
         allowReserved,
         schema: stackTrail.trace('schema', st => toOptionalSchemaV3({ schema, stackTrail: st, context })),

package/esm/parse/v3-2/pathItem/toPathItemV3.js

@@ -1,13 +1,23 @@
 import { toParameterListV3 } from '../parameter/toParameterV3.js';
 import { OasPathItem } from '../../../oas/pathItem/PathItem.js';
+import { toOptionalServersV3 } from '../server/toServerV3.js';
+import { tryParseAt } from '../../../context/tryParseAt.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { isEmpty } from '../../../helpers/isEmpty.js';
 export const toPathItemV3 = ({ pathItem, stackTrail, context }) => {
-    const { summary, description, parameters, ...skipped } = pathItem;
+    const { summary, description, parameters, servers, ...skipped } = pathItem;
     return new OasPathItem({
         summary,
         description,
         parameters: stackTrail.trace('parameters', st => toParameterListV3({ parameters, stackTrail: st, context })),
+        servers: tryParseAt({
+            stackTrail,
+            key: 'servers',
+            context,
+            type: 'INVALID_OPERATION',
+            parent: pathItem,
+            fn: st => toOptionalServersV3({ servers, stackTrail: st, context })
+        }),
         extensionFields: toSpecificationExtensionsV3({
             skipped,
             parent: pathItem,

package/esm/parse/v3-2/requestBody/toRequestBodiesV3.js

@@ -3,6 +3,7 @@ import { toRefV31 } from '../ref/toRefV31.js';
 import { toMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasRequestBody } from '../../../oas/requestBody/RequestBody.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -26,7 +27,9 @@ export const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new OasRequestBody(fields, context));
+    logBodyMediaTypes({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 export const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {
     if (!requestBodies) {

package/esm/parse/v3-2/response/toResponseV3.js

@@ -6,6 +6,7 @@ import { toOptionalMediaTypeItemsV3 } from '../mediaType/toMediaTypeItemV3.js';
 import { OasResponse } from '../../../oas/response/Response.js';
 import { toSpecificationExtensionsV3 } from '../specificationExtensions/toSpecificationExtensionsV3.js';
 import { tryParseAt } from '../../../context/tryParseAt.js';
+import { logBodyMediaTypes } from '../../logBodyMediaTypes.js';
 export const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -45,7 +46,7 @@ export const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => toHeadersV3({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => toLinksV3({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => toOptionalMediaTypeItemsV3({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new OasResponse({
         summary,
         description,
         headers: parsedHeaders,
@@ -53,4 +54,6 @@ export const toResponseV3 = ({ response, stackTrail, context }) => {
         content: parsedContent,
         extensionFields
     }, context));
+    logBodyMediaTypes({ content: parsedContent, stackTrail, context });
+    return parsed;
 };

package/package.json

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

package/script/context/generateTypes.d.ts

@@ -154,8 +154,20 @@ export type AnyOasDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3
  * The TS type and the valibot schema below stay in sync via the
  * `v.GenericSchema<OasIssueType>` annotation — adding a variant in one
  * place without the other fails to type-check.
+ *
+ * Media type issues, at most one per response or request body, from the
+ * choice `toJsonContent` makes on its parsed `content`:
+ *
+ * - `WILDCARD_MEDIA_TYPE` (`warning`) — the body has no JSON media type
+ *   (see `isJsonMediaType`) and is read from `*\/*` as JSON, since its schema
+ *   there is an object, array, union or `$ref`. The document does not say the
+ *   format; springdoc writes `*\/*` for every response.
+ * - `NO_JSON_MEDIA_TYPE` (`debug`) — no lookup without a media type reads the
+ *   body, and its keys include a range: `application/*`, or `*\/*` with a
+ *   scalar schema (a text body or a file). A body with only specific
+ *   non-JSON types (`multipart/form-data`, `text/plain`) logs nothing.
  */
-export type OasIssueType = 'UNEXPECTED_PROPERTY' | 'MISSING_OBJECT_TYPE' | 'MISSING_STRING_TYPE' | 'MISSING_ARRAY_TYPE' | 'MISSING_BOOLEAN_TYPE' | 'INVALID_EXAMPLE' | 'INVALID_ENUM' | 'INVALID_DEFAULT' | 'INVALID_NULLABLE' | 'UNEXPECTED_FORMAT' | 'INVALID_RESPONSE' | 'INVALID_FORMAT' | 'INVALID_OPERATION' | 'INVALID_SCHEMA' | 'INVALID_PARAMETER' | 'INVALID_SECURITY_SCHEME' | 'INVALID_DEPENDENCY_REF' | 'EXAMPLE_AND_EXAMPLES_DEFINED' | 'INVALID_TAG_PARENT' | 'UNSUPPORTED_OPERATION_METHOD';
+export type OasIssueType = 'UNEXPECTED_PROPERTY' | 'MISSING_OBJECT_TYPE' | 'MISSING_STRING_TYPE' | 'MISSING_ARRAY_TYPE' | 'MISSING_BOOLEAN_TYPE' | 'INVALID_EXAMPLE' | 'INVALID_ENUM' | 'INVALID_DEFAULT' | 'INVALID_NULLABLE' | 'UNEXPECTED_FORMAT' | 'INVALID_RESPONSE' | 'INVALID_FORMAT' | 'INVALID_OPERATION' | 'INVALID_SCHEMA' | 'INVALID_PARAMETER' | 'INVALID_SECURITY_SCHEME' | 'INVALID_DEPENDENCY_REF' | 'EXAMPLE_AND_EXAMPLES_DEFINED' | 'INVALID_TAG_PARENT' | 'UNSUPPORTED_OPERATION_METHOD' | 'WILDCARD_MEDIA_TYPE' | 'NO_JSON_MEDIA_TYPE';
 /**
  * Valibot schema for {@link OasIssueType}. Annotation deliberately omitted
  * so the precise literal-union output type flows through to consumers
@@ -163,7 +175,7 @@ export type OasIssueType = 'UNEXPECTED_PROPERTY' | 'MISSING_OBJECT_TYPE' | 'MISS
  * this list and {@link OasIssueType} is caught by `assertSchemaMatchesType`
  * below.
  */
-export declare const oasIssueType: v.UnionSchema<[v.LiteralSchema<"UNEXPECTED_PROPERTY", undefined>, v.LiteralSchema<"MISSING_OBJECT_TYPE", undefined>, v.LiteralSchema<"MISSING_STRING_TYPE", undefined>, v.LiteralSchema<"MISSING_ARRAY_TYPE", undefined>, v.LiteralSchema<"MISSING_BOOLEAN_TYPE", undefined>, v.LiteralSchema<"INVALID_EXAMPLE", undefined>, v.LiteralSchema<"INVALID_ENUM", undefined>, v.LiteralSchema<"INVALID_DEFAULT", undefined>, v.LiteralSchema<"INVALID_NULLABLE", undefined>, v.LiteralSchema<"UNEXPECTED_FORMAT", undefined>, v.LiteralSchema<"INVALID_RESPONSE", undefined>, v.LiteralSchema<"INVALID_FORMAT", undefined>, v.LiteralSchema<"INVALID_OPERATION", undefined>, v.LiteralSchema<"INVALID_SCHEMA", undefined>, v.LiteralSchema<"INVALID_PARAMETER", undefined>, v.LiteralSchema<"INVALID_SECURITY_SCHEME", undefined>, v.LiteralSchema<"INVALID_DEPENDENCY_REF", undefined>, v.LiteralSchema<"EXAMPLE_AND_EXAMPLES_DEFINED", undefined>, v.LiteralSchema<"INVALID_TAG_PARENT", undefined>, v.LiteralSchema<"UNSUPPORTED_OPERATION_METHOD", undefined>], undefined>;
+export declare const oasIssueType: v.UnionSchema<[v.LiteralSchema<"UNEXPECTED_PROPERTY", undefined>, v.LiteralSchema<"MISSING_OBJECT_TYPE", undefined>, v.LiteralSchema<"MISSING_STRING_TYPE", undefined>, v.LiteralSchema<"MISSING_ARRAY_TYPE", undefined>, v.LiteralSchema<"MISSING_BOOLEAN_TYPE", undefined>, v.LiteralSchema<"INVALID_EXAMPLE", undefined>, v.LiteralSchema<"INVALID_ENUM", undefined>, v.LiteralSchema<"INVALID_DEFAULT", undefined>, v.LiteralSchema<"INVALID_NULLABLE", undefined>, v.LiteralSchema<"UNEXPECTED_FORMAT", undefined>, v.LiteralSchema<"INVALID_RESPONSE", undefined>, v.LiteralSchema<"INVALID_FORMAT", undefined>, v.LiteralSchema<"INVALID_OPERATION", undefined>, v.LiteralSchema<"INVALID_SCHEMA", undefined>, v.LiteralSchema<"INVALID_PARAMETER", undefined>, v.LiteralSchema<"INVALID_SECURITY_SCHEME", undefined>, v.LiteralSchema<"INVALID_DEPENDENCY_REF", undefined>, v.LiteralSchema<"EXAMPLE_AND_EXAMPLES_DEFINED", undefined>, v.LiteralSchema<"INVALID_TAG_PARENT", undefined>, v.LiteralSchema<"UNSUPPORTED_OPERATION_METHOD", undefined>, v.LiteralSchema<"WILDCARD_MEDIA_TYPE", undefined>, v.LiteralSchema<"NO_JSON_MEDIA_TYPE", undefined>], undefined>;
 export type GenerateResult = {
     files: Map<string, FileBase>;
     previews: Record<string, Preview>;

package/script/context/generateTypes.js

@@ -62,7 +62,9 @@ exports.oasIssueType = v.union([
     v.literal('INVALID_DEPENDENCY_REF'),
     v.literal('EXAMPLE_AND_EXAMPLES_DEFINED'),
     v.literal('INVALID_TAG_PARENT'),
-    v.literal('UNSUPPORTED_OPERATION_METHOD')
+    v.literal('UNSUPPORTED_OPERATION_METHOD'),
+    v.literal('WILDCARD_MEDIA_TYPE'),
+    v.literal('NO_JSON_MEDIA_TYPE')
 ]);
 // Compile-time drift detector: this binding fails to type-check if
 // `OasIssueType` and the literal list above disagree in either

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/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/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;