diff --git a/src/oas.md b/src/oas.md index d0c355d0a3..43b8724f08 100644 --- a/src/oas.md +++ b/src/oas.md @@ -633,6 +633,7 @@ All objects defined within the Components Object will have no effect on the API | links | Map[`string`, [Link Object](#link-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Link Objects](#link-object). | | callbacks | Map[`string`, [Callback Object](#callback-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Callback Objects](#callback-object). | | pathItems | Map[`string`, [Path Item Object](#path-item-object)] | An object to hold reusable [Path Item Objects](#path-item-object). | +| mediaTypes | Map[`string`, [Media Type Object](#media-type-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Media Type Objects](#media-type-object). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -1014,7 +1015,7 @@ For use with `in: "querystring"` and `application/x-www-form-urlencoded`, see [E | Field Name | Type | Description | | ---- | :----: | ---- | -| content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. | +| content | Map[`string`, [Media Type Object](#media-type-object) \| [Reference Object](#reference-object)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. | ##### Style Values @@ -1204,7 +1205,7 @@ Describes a single request body. | Field Name | Type | Description | | ---- | :----: | ---- | | description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| content | Map[`string`, [Media Type Object](#media-type-object)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://www.rfc-editor.org/rfc/rfc9110.html#appendix-A) and the value describes it. The map SHOULD have at least one entry; if it does not, the behavior is implementation-defined. For requests that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` | +| content | Map[`string`, [Media Type Object](#media-type-object) \| [Reference Object](#reference-object)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://www.rfc-editor.org/rfc/rfc9110.html#appendix-A) and the value describes it. The map SHOULD have at least one entry; if it does not, the behavior is implementation-defined. For requests that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` | | required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -1944,7 +1945,7 @@ Describes a single response from an API operation, including design-time, static | summary | `string` | A short summary of the meaning of the response. | | description | `string` | A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | Maps a header name to its definition. [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.1) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. | -| content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://www.rfc-editor.org/rfc/rfc9110.html#appendix-A) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` | +| content | Map[`string`, [Media Type Object](#media-type-object) \| [Reference Object](#reference-object)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://www.rfc-editor.org/rfc/rfc9110.html#appendix-A) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. `"text/plain"` overrides `"text/*"` | | links | Map[`string`, [Link Object](#link-object) \| [Reference Object](#reference-object)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#components-object). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -2445,7 +2446,7 @@ Using `content` with a `text/plain` media type is RECOMMENDED for headers where | Field Name | Type | Description | | ---- | :----: | ---- | -| content | Map[`string`, [Media Type Object](#media-type-object)] | A map containing the representations for the header. The key is the media type and the value describes it. The map MUST only contain one entry. | +| content | Map[`string`, [Media Type Object](#media-type-object) \| [Reference Object](#reference-object)] | A map containing the representations for the header. The key is the media type and the value describes it. The map MUST only contain one entry. | ##### Modeling Link Headers diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 9990fefb67..f94a73dfec 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -199,8 +199,12 @@ $defs: type: object additionalProperties: $ref: '#/$defs/path-item' + mediaTypes: + type: object + additionalProperties: + $ref: '#/$defs/media-type-or-reference' patternProperties: - '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': + '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems|mediaTypes)$': $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected propertyNames: pattern: '^[a-zA-Z0-9._-]+$' @@ -517,7 +521,7 @@ $defs: $comment: https://spec.openapis.org/oas/v3.2#fixed-fields-10 type: object additionalProperties: - $ref: '#/$defs/media-type' + $ref: '#/$defs/media-type-or-reference' propertyNames: format: media-range @@ -525,6 +529,8 @@ $defs: $comment: https://spec.openapis.org/oas/v3.2#media-type-object type: object properties: + description: + type: string schema: $dynamicRef: '#meta' itemSchema: @@ -538,6 +544,16 @@ $defs: - $ref: '#/$defs/examples' unevaluatedProperties: false + media-type-or-reference: + if: + type: object + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/media-type' + encoding: $comment: https://spec.openapis.org/oas/v3.2#encoding-object type: object diff --git a/tests/schema/pass/media-type-examples.yaml b/tests/schema/pass/media-type-examples.yaml index 2ab4e68076..0a4ef9cb0f 100644 --- a/tests/schema/pass/media-type-examples.yaml +++ b/tests/schema/pass/media-type-examples.yaml @@ -3,6 +3,15 @@ openapi: 3.2.0 info: title: API version: 1.0.0 +components: + mediaTypes: + StreamingPets: + description: | + Streaming sequence of JSON pet representations, + suitable for use with any of the streaming JSON + media types. + itemSchema: + $ref: '#components/schemas/Pet' paths: /something: put: @@ -31,8 +40,9 @@ paths: frog: $ref: '#/components/examples/frog-example' application/jsonl: - itemSchema: - $ref: '#components/schemas/Pet' + $ref: '#/components/mediaTypes/StreamingPets' + application/x-ndjson: + $ref: '#/components/mediaTypes/StreamingPets' application/xml: schema: type: object