Merge pull request #4728 from handrews/mt-e-components

Author: ralfhandl

src/oas.md

@@ -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 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 |
 | ---- | :----: | ---- |
-| <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
 
@@ -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).
@@ -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).
@@ -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
 

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,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:
@@ -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

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