From 00b75dd1267d4cb3bc1b15a9084a7351789b1eb5 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 14:04:59 -0700 Subject: [PATCH 01/15] Link to the Learn and Spec sites Guide readers to supplemental documentation, examples, related specificatioins, and extension registries. These sites answer many questions that otherwise get raised as GitHub issues. --- versions/3.0.4.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 12b2375a79..9c15a83024 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -12,6 +12,10 @@ The OpenAPI Specification (OAS) defines a standard, language-agnostic interface An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. +For examples of OpenAPI usage and additional documentation, please visit [learn.openapis.org](https://learn.openapis.org/). + +For extension registries and other specifications published by the OpenAPI Initiative, please visit [spec.openapis.org](https://spec.openapis.org/) + ## Table of Contents From ce05949e3cdd421f9ac07092d6a05e826155cd74 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 14:10:42 -0700 Subject: [PATCH 02/15] Clarify "Schema" --- versions/3.0.4.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 9c15a83024..65ec4122c6 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -218,6 +218,11 @@ Relative references used in `$ref` are processed as per [JSON Reference](https:/ ### Schema +This section describes the structure of the OpenAPI Description format. +This text is the only normative description of the format. +A JSON Schema is hosted on [spec.openapis.org](https://spec.openapis.org) for informational purposes. +If the JSON Schema differs from this section, then this section MUST be considered authoritative. + In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object From 41d2a52062e55f650c6daa383a6170113e5718d9 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 14:17:21 -0700 Subject: [PATCH 03/15] Global HTTP case-(in)sensitivity rule --- versions/3.0.4.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 65ec4122c6..cac0f99710 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -100,6 +100,10 @@ Some examples of possible media type definitions: The HTTP Status Codes are used to indicate the status of the executed operation. Status codes SHOULD be selected from the available status codes registered in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). +##### HTTP and Case Sensitivity +As most field names and values in the OpenAPI Specification are case-sensitive, this document endeavors to call out any case-insensitive names and values. +However, the case sensitivity of field names and values that map directly to HTTP concepts follow the case sensitivity rules of HTTP, even if this document does not make a note of every concept. + ##### Undefined and Implementation-Defined Behavior This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior. From 79ed97214577bc8053f9fd69782e4b25f6cc1b3a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 14:25:46 -0700 Subject: [PATCH 04/15] Improved description of XML examples --- versions/3.0.4.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index cac0f99710..dbb5565162 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2926,7 +2926,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ##### XML Object Examples -The examples of the XML object definitions are included inside a property definition of a [Schema Object](#schemaObject) with a sample of the XML representation of it. +Each of the following examples represent the value of the `properties` keyword in a [Schema Object](#schemaObject) that is omitted for brevity. +The JSON and YAML representations of the `properties` value are followed by an example XML representation produced for the single property shown. ###### No XML Element From 02df67541fad8677d0eb3d96707941c565711c84 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 14:45:49 -0700 Subject: [PATCH 05/15] Clarify CommonMark extensibility. --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index dbb5565162..b5ba8642aa 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -211,7 +211,7 @@ Note that the encoding indicated by `byte`, which inflates the size of data in o ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. -Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. +Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to implement extensions on top of CommonMark 0.27, and MAY choose to ignore some CommonMark or extension features to address security concerns. ### Relative References in URLs From 4cdcab329ca49e746fd469652cb8bdb7fe3a3af0 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 27 May 2024 15:11:58 -0700 Subject: [PATCH 06/15] Add description to the Example Object --- versions/3.0.4.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index b5ba8642aa..c01339faab 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1997,6 +1997,10 @@ transactionCallback: ``` #### Example Object +An object grouping an internal or external example value with basic `summary` and `description` metadata. +This object is typically used in properties named `examples` (plural), and is a [referenceable](#referenceObject) alternative to older `example` (singular) fields that do not support referencing or metadata. + +Allows sharing an example to demonstrate the usage of properties, parameters and objects within OpenAPI. ##### Fixed Fields Field Name | Type | Description From 9b4982152d1bcfdde63b31acbb05d5491178a77d Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 3 Jun 2024 10:33:37 -0700 Subject: [PATCH 07/15] Mention the format registry in the data types section --- versions/3.0.4.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index c01339faab..c5e882c790 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -182,6 +182,8 @@ Models are defined using the [Schema Object](#schemaObject), which is an extende OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification. +The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registry format is strictly OPTIONAL, and support for one registry format does not imply support for any others. + Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: From 7e141bb8aa3cbec3831ee3802b1619a7e10e80e0 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 4 Jun 2024 08:09:16 -0700 Subject: [PATCH 08/15] Wording improvement (review feedback) Co-authored-by: Ralf Handl --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index c5e882c790..8de3ea202f 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -182,7 +182,7 @@ Models are defined using the [Schema Object](#schemaObject), which is an extende OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification. -The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registry format is strictly OPTIONAL, and support for one registry format does not imply support for any others. +The OpenAPI Initiative also hosts a [Format Registry](https://spec.openapis.org/registry/format/) for formats defined by OAS users and other specifications. Support for any registered format is strictly OPTIONAL, and support for one registered format does not imply support for any others. Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. From d6b71cdf052636fcbc0a73c2a773d6d8feb32ae1 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 4 Jun 2024 08:28:05 -0700 Subject: [PATCH 09/15] Note extension registry in extensions section. --- versions/3.0.4.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 8de3ea202f..2edcf3f448 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -3510,9 +3510,14 @@ The extensions properties are implemented as patterned fields that are always pr Field Pattern | Type | Description ---|:---:|--- -^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. +^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be any valid JSON format value (`null`, a primitive, an array or an object.) -The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). +The OpenAPI Initiative maintains several [extension registries](https://spec.openapis.org/registry/index.html), including registries for [individual extension keywords](https://spec.openapis.org/registry/extension/) and [extension keyword namespaces](https://spec.openapis.org/registry/namespace/). + +Extensions are one of the best ways to prove the viability of proposed additions to the specification. +It is therefore RECOMMENDED that implementations be designed for extensibility to support community experimentation. + +Support for any one extension is OPTIONAL, and support for one extension does not imply support for others. ### Security Filtering From 96f8989bab2e8ef4fad430fde996627effa7c48a Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 4 Jun 2024 13:27:58 -0700 Subject: [PATCH 10/15] Better wording from review feedback Co-authored-by: Lorna Jane Mitchell --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 2edcf3f448..b05a267fe6 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2002,7 +2002,7 @@ transactionCallback: An object grouping an internal or external example value with basic `summary` and `description` metadata. This object is typically used in properties named `examples` (plural), and is a [referenceable](#referenceObject) alternative to older `example` (singular) fields that do not support referencing or metadata. -Allows sharing an example to demonstrate the usage of properties, parameters and objects within OpenAPI. +Examples allow demonstration of the usage of properties, parameters and objects within OpenAPI. ##### Fixed Fields Field Name | Type | Description From f9dc67b7f6c41b336b9bb3ada6893120c926b646 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 4 Jun 2024 13:28:50 -0700 Subject: [PATCH 11/15] Better formatting (review feedback) Co-authored-by: Lorna Jane Mitchell --- versions/3.0.4.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index b05a267fe6..98ce89d305 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -101,6 +101,7 @@ The HTTP Status Codes are used to indicate the status of the executed operation. Status codes SHOULD be selected from the available status codes registered in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ##### HTTP and Case Sensitivity + As most field names and values in the OpenAPI Specification are case-sensitive, this document endeavors to call out any case-insensitive names and values. However, the case sensitivity of field names and values that map directly to HTTP concepts follow the case sensitivity rules of HTTP, even if this document does not make a note of every concept. From e25e23c1ae0e9d0167f2dcc4147818dde2012831 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 4 Jun 2024 13:29:20 -0700 Subject: [PATCH 12/15] better formatting (review feedback) Co-authored-by: Lorna Jane Mitchell --- versions/3.0.4.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 98ce89d305..1cf0fa2d00 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2000,6 +2000,7 @@ transactionCallback: ``` #### Example Object + An object grouping an internal or external example value with basic `summary` and `description` metadata. This object is typically used in properties named `examples` (plural), and is a [referenceable](#referenceObject) alternative to older `example` (singular) fields that do not support referencing or metadata. From 43618e21a0b1520de55bad814df8cdd2824f1a4a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 5 Jun 2024 11:28:32 -0700 Subject: [PATCH 13/15] Warn of interop issues w/Markdown extensions Thanks to @lornajane for the review feedback. --- versions/3.0.4.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 1cf0fa2d00..47855ac9fc 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -214,7 +214,11 @@ Note that the encoding indicated by `byte`, which inflates the size of data in o ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. -Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to implement extensions on top of CommonMark 0.27, and MAY choose to ignore some CommonMark or extension features to address security concerns. +Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark or extension features to address security concerns. + +While the framing of CommonMark 0.27 as a minimum requirement means that tooling MAY choose to implement extensions on top of it, note that any such extensions are by definition implementation-defined and will not be interoperable. +OpenAPI Description authors SHOULD consider how text using such extensions will be rendered by tools that offer only the minimum support. + ### Relative References in URLs From f9813cd85c9d873ea408fe394e5d51a944be8abb Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 5 Jun 2024 11:41:16 -0700 Subject: [PATCH 14/15] Clarify version (Info Object) further --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 47855ac9fc..6841ebbd5c 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -269,7 +269,7 @@ Field Name | Type | Description termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. -version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). +version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the version of API being described). This object MAY be extended with [Specification Extensions](#specificationExtensions). From fdb9570529d4488eb86dd1ee726c8054ef8f2675 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 8 Jun 2024 13:45:01 -0700 Subject: [PATCH 15/15] Clarify confusing use of YAML "JSON Schema" When we mention YAML's "Failsafe schema" we give it a lower-case "schem", as the YAML documentatio does. We also prefix it with "YAML". However, we capitalize "Schema" in "JSON Schema ruleset", which (given how much JSON Schema is used in the OAS) is a jarring overlap with "JSON Schema". This change aligns "YAML JSON schema ruleset" with "YAML Failsafe ruleset" and explicitly calls out that it is unrelated to JSON Schema. --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 6841ebbd5c..17cd536775 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -148,7 +148,7 @@ Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: -- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). +- Tags MUST be limited to those allowed by [YAML's JSON schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231), which defines a subset of the YAML syntax and is unrelated to [JSON Schema](https://tools.ietf.org/html/draft-wright-json-schema-00). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.