Skip to content

v3.2: Allow Media Type Object re-use #4728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 20, 2025
Merged

v3.2: Allow Media Type Object re-use #4728

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
747ccc8
Allow Media Type Object re-use
handrews Jul 19, 2025
ec1e510
Fix inadvertent plural
handrews Jul 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -633,6 +633,7 @@ All objects defined within the Components Object will have no effect on the API
| <a name="components-links"></a> links | Map[`string`, [Link Object](#link-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Link Objects](#link-object). |
| <a name="components-callbacks"></a> callbacks | Map[`string`, [Callback Object](#callback-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Callback Objects](#callback-object). |
| <a name="components-path-items"></a> pathItems | Map[`string`, [Path Item Object](#path-item-object)] | An object to hold reusable [Path Item Objects](#path-item-object). |
| <a name="components-media-types"></a> mediaTypes | Map[`string`, [Media Type Objects](#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).

Expand Down Expand Up @@ -1014,7 +1015,7 @@ For use with `in: "querystring"` and `application/x-www-form-urlencoded`, see [E

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="parameter-content"></a>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. |
| <a name="parameter-content"></a>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

Expand Down Expand Up @@ -1204,7 +1205,7 @@ Describes a single request body.
| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="request-body-description"></a>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. |
| <a name="request-body-content"></a>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/*"` |
| <a name="request-body-content"></a>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/*"` |
| <a name="request-body-required"></a>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).
Expand Down Expand Up @@ -1944,7 +1945,7 @@ Describes a single response from an API operation, including design-time, static
| <a name="response-summary"></a>summary | `string` | A short summary of the meaning of the response. |
| <a name="response-description"></a>description | `string` | A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
| <a name="response-headers"></a>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. |
| <a name="response-content"></a>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/*"` |
| <a name="response-content"></a>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/*"` |
| <a name="response-links"></a>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).
Expand Down Expand Up @@ -2445,7 +2446,7 @@ Using `content` with a `text/plain` media type is RECOMMENDED for headers where

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="header-content"></a>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. |
| <a name="header-content"></a>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

Expand Down
20 changes: 18 additions & 2 deletions src/schemas/validation/schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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._-]+$'
Expand Down Expand Up @@ -517,14 +521,16 @@ $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

media-type:
$comment: https://spec.openapis.org/oas/v3.2#media-type-object
type: object
properties:
description:
type: string
schema:
$dynamicRef: '#meta'
itemSchema:
Expand All @@ -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
Expand Down
14 changes: 12 additions & 2 deletions tests/schema/pass/media-type-examples.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down