From c817eb7fcc6844bc679f6bc18a2236b648c3cdbb Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Tue, 17 Dec 2024 15:41:45 +0100 Subject: [PATCH 01/19] Editorial change: Link Object points to Operation Object --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index f2e4eeb749..351a618664 100644 --- a/src/oas.md +++ b/src/oas.md @@ -230,7 +230,7 @@ In some cases, an unambiguous URI-based alternative is available, and OAD author | [Security Requirement Object](#security-requirement-object) `{name}` | [Security Scheme Object](#security-scheme-object) name under the [Components Object](#components-object) | _n/a_ | | [Discriminator Object](#discriminator-object) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schema-object) name under the Components Object | `mapping` _(explicit URI syntax)_ | | [Operation Object](#operation-object) `tags` | [Tag Object](#tag-object) `name` (in the [OpenAPI Object](#openapi-object)'s `tags` array) | _n/a_ | -| [Link Object](#link-object) `operationId` | [Path Item Object](#path-item-object) `operationId` | `operationRef` | +| [Link Object](#link-object) `operationId` | [Operation Object](#operation-object) `operationId` | `operationRef` | A fifth implicit connection involves appending the templated URL paths of the [Paths Object](#paths-object) to the appropriate [Server Object](#server-object)'s `url` field. This is unambiguous because only the entry document's Paths Object contributes URLs to the described API. From 1b1129690af64382aa46b9987121188045f48ce1 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Wed, 18 Dec 2024 16:53:26 +0100 Subject: [PATCH 02/19] Editorial change: fix typo in Link Object description --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 351a618664..bbf31b4c73 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2773,7 +2773,7 @@ For computing links and providing instructions to execute them, a [runtime expre This object MAY be extended with [Specification Extensions](#specification-extensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. -The identified or reference operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD). +The identified or referenced operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD). Because of the potential for name clashes, the `operationRef` syntax is preferred for multi-document OADs. However, because use of an operation depends on its URL path template in the [Paths Object](#paths-object), operations from any [Path Item Object](#path-item-object) that is referenced multiple times within the OAD cannot be resolved unambiguously. In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error. From dc94d9528c74994a5dfae7303a0605a788a32aa5 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Wed, 18 Dec 2024 18:38:50 +0100 Subject: [PATCH 03/19] Editorial change: add Header Object to Generating and Validating URIs section --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index bbf31b4c73..458858b859 100644 --- a/src/oas.md +++ b/src/oas.md @@ -5024,7 +5024,7 @@ This specification normatively cites the following relevant standards: Style-based serialization is used in the [Parameter Object](#parameter-object) when `schema` is present, and in the [Encoding Object](#encoding-object) when at least one of `style`, `explode`, or `allowReserved` is present. See [Appendix C](#appendix-c-using-rfc6570-based-serialization) for more details of RFC6570's two different approaches to percent-encoding, including an example involving `+`. -Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the fields `style`, `explode`, and `allowReserved` are absent. +Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) and [Header Object](#header-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the fields `style`, `explode`, and `allowReserved` are absent. Each part is encoded based on the media type (e.g. `text/plain` or `application/json`), and must then be percent-encoded for use in a `form-urlencoded` string. Note that content-based serialization for `form-data` does not expect or require percent-encoding in the data, only in per-part header values. From 393ab027d8d985f9caa2d524e3ef25f335c9ac23 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Wed, 18 Dec 2024 14:22:50 +0100 Subject: [PATCH 04/19] Editorial change: Include Header Object into 'Working With Examples' section --- src/oas.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index 458858b859..7b21367993 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2598,19 +2598,19 @@ Tooling implementations MAY choose to validate compatibility automatically, and ##### Working with Examples -Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object). +Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object) and [Media Type Objects](#media-type-object). In both Objects, this is done through the `examples` (plural) field. -However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in both Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of both Objects. +However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in all three Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of all three Objects. Each of these fields has slightly different considerations. The Schema Object's fields are used to show example values without regard to how they might be formatted as parameters or within media type representations. The `examples` array is part of JSON Schema and is the preferred way to include examples in the Schema Object, while `example` is retained purely for compatibility with older versions of the OpenAPI Specification. -The mutually exclusive fields in the Parameter or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation. -The exact serialization and encoding is determined by various fields in the Parameter Object, or in the Media Type Object's [Encoding Object](#encoding-object). +The mutually exclusive fields in the Parameter, Header or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation. +The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object). Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object. -The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. +The singular `example` field in the Parameter, Header or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. Some examples cannot be represented directly in JSON or YAML. For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description. From 840d5acb8f08b216876fa5708d7a36d5956ce9ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Wed, 18 Dec 2024 17:55:32 +0100 Subject: [PATCH 05/19] Update src/oas.md Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 7b21367993..fcc37dc32b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2598,7 +2598,7 @@ Tooling implementations MAY choose to validate compatibility automatically, and ##### Working with Examples -Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object) and [Media Type Objects](#media-type-object). +Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object), and [Media Type Objects](#media-type-object). In both Objects, this is done through the `examples` (plural) field. However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in all three Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of all three Objects. Each of these fields has slightly different considerations. From b25ecf1324401680430b24ecdfb78e722b5b9fa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Wed, 18 Dec 2024 17:55:39 +0100 Subject: [PATCH 06/19] Update src/oas.md Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index fcc37dc32b..d40b544f6e 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2599,7 +2599,7 @@ Tooling implementations MAY choose to validate compatibility automatically, and ##### Working with Examples Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object), and [Media Type Objects](#media-type-object). -In both Objects, this is done through the `examples` (plural) field. +In all three Objects, this is done through the `examples` (plural) field. However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in all three Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of all three Objects. Each of these fields has slightly different considerations. From 6df11ebe889386f27580843a25ead50031354c2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Wed, 18 Dec 2024 17:55:45 +0100 Subject: [PATCH 07/19] Update src/oas.md Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d40b544f6e..bc4cda47dd 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2606,7 +2606,7 @@ Each of these fields has slightly different considerations. The Schema Object's fields are used to show example values without regard to how they might be formatted as parameters or within media type representations. The `examples` array is part of JSON Schema and is the preferred way to include examples in the Schema Object, while `example` is retained purely for compatibility with older versions of the OpenAPI Specification. -The mutually exclusive fields in the Parameter, Header or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation. +The mutually exclusive fields in the Parameter, Header, or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation. The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object). Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object. From 4c3d5e0ba02030072dbcc112e566cc4891c709dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Wed, 18 Dec 2024 17:55:51 +0100 Subject: [PATCH 08/19] Update src/oas.md Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index bc4cda47dd..840e6bf836 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2610,7 +2610,7 @@ The mutually exclusive fields in the Parameter, Header, or Media Type Objects ar The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object). Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object. -The singular `example` field in the Parameter, Header or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. +The singular `example` field in the Parameter, Header, or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`. Some examples cannot be represented directly in JSON or YAML. For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description. From dce4f8adf4bd8293528539af9cb527b7035cc360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Wed, 18 Dec 2024 21:56:13 +0100 Subject: [PATCH 09/19] Update src/oas.md Co-authored-by: Mike Kistler --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 840e6bf836..4a390cb2ea 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2606,7 +2606,7 @@ Each of these fields has slightly different considerations. The Schema Object's fields are used to show example values without regard to how they might be formatted as parameters or within media type representations. The `examples` array is part of JSON Schema and is the preferred way to include examples in the Schema Object, while `example` is retained purely for compatibility with older versions of the OpenAPI Specification. -The mutually exclusive fields in the Parameter, Header, or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation. +The mutually exclusive fields in the Parameter, Header, or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter, serialized header, or within a media type representation. The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object). Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object. From 808506423295aa0e6b9c7386d84d51c7d37e7ee7 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Thu, 19 Dec 2024 21:23:31 +0100 Subject: [PATCH 10/19] Introduce constraints for Server Object url fixed field --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 4a390cb2ea..707bb4370a 100644 --- a/src/oas.md +++ b/src/oas.md @@ -509,7 +509,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST not be part of a URL. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | name | `string` | An optional unique string to refer to the host designated by the URL. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | From a681d3e2e630f46ef782208d938105d2ffb81569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Fri, 20 Dec 2024 12:50:18 +0100 Subject: [PATCH 11/19] Update src/oas.md Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 707bb4370a..e6335f6f08 100644 --- a/src/oas.md +++ b/src/oas.md @@ -509,7 +509,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST not be part of a URL. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST not be part of this URL. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | name | `string` | An optional unique string to refer to the host designated by the URL. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | From 1a65883ab1cfff12367d89619c515c816ea8717c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Fri, 20 Dec 2024 12:59:41 +0100 Subject: [PATCH 12/19] Update src/oas.md --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e6335f6f08..1cfdb9577c 100644 --- a/src/oas.md +++ b/src/oas.md @@ -509,7 +509,7 @@ An object representing a Server. | Field Name | Type | Description | | ---- | :----: | ---- | -| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST not be part of this URL. Variable substitutions will be made when a variable is named in `{`braces`}`. | +| url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST NOT be part of this URL. Variable substitutions will be made when a variable is named in `{`braces`}`. | | description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | name | `string` | An optional unique string to refer to the host designated by the URL. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | From 40c3d5fd13e9aacb047b64843f49e8e2192b15cc Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Fri, 27 Dec 2024 14:58:56 +0100 Subject: [PATCH 13/19] Editorial change: fix anchor to Components.securitySchemes Signed-off-by: Vladimir Gorej --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 1cfdb9577c..fde8587c87 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4506,7 +4506,7 @@ flows: Lists the required security schemes to execute this operation. -The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object), or be the URI of a Security Scheme Object. +The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#components-security-schemes) under the [Components Object](#components-object), or be the URI of a Security Scheme Object. Property names that are identical to a component name under the Components Object MUST be treated as a component name. To reference a Security Scheme with a single-segment relative URI reference (e.g. `foo`) that collides with a component name (e.g. `#/components/securitySchemes/foo`), use the `.` path segment (e.g. `./foo`). From 4e74e52fbfa1e5b7c40455eaaf9f5487e96550f5 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 8 Jan 2025 17:36:20 -0800 Subject: [PATCH 14/19] Fix copy-paste "format: binary" error These examples got copied from 3.0.4 and apparently I forgot to adjust them for 3.1.1 and no one else noticed. --- src/oas.md | 38 +++++++++++++++++--------------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/src/oas.md b/src/oas.md index fde8587c87..52e7d3aeb8 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2186,18 +2186,18 @@ requestBody: schema: type: object properties: + # default for a string without `contentEncoding` is `text/plain` id: - # default for primitives without a special format is text/plain type: string format: uuid - profileImage: - # default for string with binary format is `application/octet-stream` - type: string - format: binary + + # default for a schema withhout `type` is `application/octet-stream` + profileImage: {} + + # for arrays, the Encoding Object applies to each item + # individually based on that item's type, which in this + # example is an object, so `application/json` addresses: - # for arrays, the Encoding Object applies to each item - # individually based on that item's type, which in this - # example is an object, so `application/json` type: array items: $ref: '#/components/schemas/Address' @@ -2215,31 +2215,27 @@ requestBody: schema: type: object properties: + # No Encoding Object, so use default `text/plain` id: - # default is `text/plain` type: string format: uuid + + # Encoding Object overrides the default `application/json` + # for each item in the array with `application/xml; charset=utf-8` addresses: - # default based on the `items` subschema would be - # `application/json`, but we want these address objects - # serialized as `application/xml` instead description: addresses in XML format type: array items: $ref: '#/components/schemas/Address' - profileImage: - # default is application/octet-stream, but we can declare - # a more specific image type or types - type: string - format: binary + + # Encoding Object accepts only PNG or JPEG, and also describes + # a custom header for just this part in the multipart format + profileImage: {} + encoding: addresses: - # require XML Content-Type in utf-8 encoding - # This is applied to each address part corresponding - # to each address in he array contentType: application/xml; charset=utf-8 profileImage: - # only accept png or jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: From 1dd8c5bfd1952f0cb380448ec210ef3a8cdc7667 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 10 Jan 2025 15:49:38 +0100 Subject: [PATCH 15/19] Typo --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 52e7d3aeb8..f7238ce6e5 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2191,7 +2191,7 @@ requestBody: type: string format: uuid - # default for a schema withhout `type` is `application/octet-stream` + # default for a schema without `type` is `application/octet-stream` profileImage: {} # for arrays, the Encoding Object applies to each item From 00b5f8f7bc1f165269d43c03f2abe8f823662448 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 15 Jan 2025 12:18:31 -0800 Subject: [PATCH 16/19] Feedback from mkistler about contentEncoding --- src/oas.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/src/oas.md b/src/oas.md index f7238ce6e5..8e2476cfe1 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2139,8 +2139,9 @@ requestBody: name: type: string icon: - # The default with "contentEncoding" is application/octet-stream, - # so we need to set image media type(s) in the Encoding Object. + # The default content type with "contentEncoding" present + # is application/octet-stream, # so we need to set the correct + # image media type(s) in the Encoding Object. type: string contentEncoding: base64url encoding: @@ -2186,17 +2187,21 @@ requestBody: schema: type: object properties: - # default for a string without `contentEncoding` is `text/plain` + # default content type for a string without `contentEncoding` + # is `text/plain` id: type: string format: uuid - # default for a schema without `type` is `application/octet-stream` + # default content type for a schema without `type` + # is `application/octet-stream` profileImage: {} - # for arrays, the Encoding Object applies to each item - # individually based on that item's type, which in this - # example is an object, so `application/json` + # for arrays, the `encoding` field applies the Encoding Object + # to each item individually and determines the default content type + # based on the type in the `items` subschema, which in this example + # is an object, so the default content type for each item is + # `application/json` addresses: type: array items: @@ -2220,7 +2225,7 @@ requestBody: type: string format: uuid - # Encoding Object overrides the default `application/json` + # Encoding Object overrides the default `application/json` content type # for each item in the array with `application/xml; charset=utf-8` addresses: description: addresses in XML format From 9a1a7c0162dc9923a4c11d3c3cea6a23aded4fb4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 16 Jan 2025 17:26:51 +0100 Subject: [PATCH 17/19] Apply suggestions from code review Co-authored-by: Mike Kistler --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 8e2476cfe1..72d144584b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2140,7 +2140,7 @@ requestBody: type: string icon: # The default content type with "contentEncoding" present - # is application/octet-stream, # so we need to set the correct + # is application/octet-stream, so we need to set the correct # image media type(s) in the Encoding Object. type: string contentEncoding: base64url From 0f6db5f25cc5dbb748491370f493e1358219d8c0 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 13 Feb 2025 23:27:00 +0100 Subject: [PATCH 18/19] Update src schema with changes from #4328 --- src/schemas/validation/schema.yaml | 32 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index f03bc55586..a963aedc2d 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -12,7 +12,7 @@ properties: $ref: '#/$defs/info' jsonSchemaDialect: type: string - format: uri + format: uri-reference default: 'https://spec.openapis.org/oas/3.2/dialect/WORK-IN-PROGRESS' servers: type: array @@ -64,7 +64,7 @@ $defs: type: string termsOfService: type: string - format: uri + format: uri-reference contact: $ref: '#/$defs/contact' license: @@ -85,7 +85,7 @@ $defs: type: string url: type: string - format: uri + format: uri-reference email: type: string format: email @@ -102,7 +102,7 @@ $defs: type: string url: type: string - format: uri + format: uri-reference required: - name dependentSchemas: @@ -319,7 +319,7 @@ $defs: type: string url: type: string - format: uri + format: uri-reference required: - url $ref: '#/$defs/specification-extensions' @@ -620,7 +620,7 @@ $defs: value: true externalValue: type: string - format: uri + format: uri-reference not: required: - value @@ -864,7 +864,7 @@ $defs: properties: openIdConnectUrl: type: string - format: uri + format: uri-reference required: - openIdConnectUrl @@ -900,10 +900,10 @@ $defs: properties: authorizationUrl: type: string - format: uri + format: uri-reference refreshUrl: type: string - format: uri + format: uri-reference scopes: $ref: '#/$defs/map-of-strings' required: @@ -917,10 +917,10 @@ $defs: properties: tokenUrl: type: string - format: uri + format: uri-reference refreshUrl: type: string - format: uri + format: uri-reference scopes: $ref: '#/$defs/map-of-strings' required: @@ -934,10 +934,10 @@ $defs: properties: tokenUrl: type: string - format: uri + format: uri-reference refreshUrl: type: string - format: uri + format: uri-reference scopes: $ref: '#/$defs/map-of-strings' required: @@ -951,13 +951,13 @@ $defs: properties: authorizationUrl: type: string - format: uri + format: uri-reference tokenUrl: type: string - format: uri + format: uri-reference refreshUrl: type: string - format: uri + format: uri-reference scopes: $ref: '#/$defs/map-of-strings' required: From 10fc7c85d19629beb64777abed26bbea0e104c6e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 27 Mar 2025 08:49:58 -0700 Subject: [PATCH 19/19] Discrimator -> Discriminator We do not have a feature that discriminates against tomatoes (this joke may not translate too all English-speaking regions, much less other languages :-) --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 72d144584b..532ae86b8b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -252,7 +252,7 @@ There are no URI-based alternatives for the Operation Object's `tags` field. OAD authors are advised to use external solutions such as the OpenAPI Initiative's Overlay Specification to simulate sharing [Tag Objects](#tag-object) across multiple documents. See [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-in-a-referenced-document) for an example of the possible resolutions, including which one is recommended by this section. -The behavior for Discrimator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles. +The behavior for Discriminator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles. Note that no aspect of implicit connection resolution changes how [URIs are resolved](#relative-references-in-api-description-uris), or restricts their possible targets.