diff --git a/src/oas.md b/src/oas.md index e91c9cb08a..610a71fe8d 100644 --- a/src/oas.md +++ b/src/oas.md @@ -627,6 +627,8 @@ 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 Objects](#media-type-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Media Type Objects](#media-type-object). | +| encodings | Map[`string`, [Encoding Objects](#encoding-object) \| [Reference Object](#reference-object)] | An object to hold reusable [Encoding Objects](#encoding-object). | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -1008,7 +1010,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 @@ -1198,7 +1200,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). @@ -1249,11 +1251,12 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | Field Name | Type | Description | | ---- | :----: | ---- | +| description | `string` | A brief description of the media type. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | schema | [Schema Object](#schema-object) | A schema describing the complete content of the request, response, parameter, or header. | | itemSchema | [Schema Object](#schema-object) | A schema describing each item within a [sequential media type](#sequential-media-types). | | example | Any | Example of the media type; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). | -| encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). The `encoding` field SHALL only apply when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. | +| encoding | Map[`string`, [Encoding Object](#encoding-object) \| [Reference Object](#reference-object)] | A map between a property name and its encoding information, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). The `encoding` field SHALL only apply when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -1639,6 +1642,7 @@ These fields MAY be used either with or without the RFC6570-style serialization | Field Name | Type | Description | | ---- | :----: | ---- | +| description | `string` | A brief description of the media type. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`). Default value depends on the property type as shown in the table below. | | headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | A map allowing additional information to be provided as headers. `Content-Type` is described separately and SHALL be ignored in this section. This field SHALL be ignored if the media type is not a `multipart`. | @@ -1929,7 +1933,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). @@ -2449,7 +2453,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. | ##### Header Object Example diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 9990fefb67..7069b84034 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -199,8 +199,16 @@ $defs: type: object additionalProperties: $ref: '#/$defs/path-item' + mediaTypes: + type: object + additionalProperties: + $ref: '#/$defs/media-type-or-reference' + encodings: + type: object + additionalProperties: + $ref: '#/$defs/encoding-or-reference' patternProperties: - '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': + '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems|mediaTypes|encodings)$': $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 +525,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 +533,8 @@ $defs: $comment: https://spec.openapis.org/oas/v3.2#media-type-object type: object properties: + description: + type: string schema: $dynamicRef: '#meta' itemSchema: @@ -532,16 +542,28 @@ $defs: encoding: type: object additionalProperties: - $ref: '#/$defs/encoding' + $ref: '#/$defs/encoding-or-reference' allOf: - $ref: '#/$defs/specification-extensions' - $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 properties: + description: + type: string contentType: type: string format: media-range @@ -566,6 +588,16 @@ $defs: - $ref: '#/$defs/styles-for-form' unevaluatedProperties: false + encoding-or-reference: + if: + type: object + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/encoding' + responses: $comment: https://spec.openapis.org/oas/v3.2#responses-object type: object diff --git a/tests/schema/pass/media-type-examples.yaml b/tests/schema/pass/media-type-examples.yaml index 2ab4e68076..9523a39367 100644 --- a/tests/schema/pass/media-type-examples.yaml +++ b/tests/schema/pass/media-type-examples.yaml @@ -3,6 +3,25 @@ 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' + encodings: + ReservedNoExplode: + description: | + This allows multiple values under the same name, + and disables reserved percent-encoding. + Clients are responsible for adequately percent-encoding + the values in advance. + style: form + explode: false + allowReserved: true paths: /something: put: @@ -31,8 +50,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 @@ -132,9 +152,7 @@ paths: schema: type: integer forCoverage: - style: form - explode: false - allowReserved: true + $ref: '#/components/encodings/ReservedNoExplode' forCoverage2: style: spaceDelimited explode: true