Merge pull request #3861 from handrews/editorial-304

Various minor editorial improvements (3.0.4)

Author: lornajane

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
 <!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
 
@@ -96,6 +100,11 @@ 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).
 
+##### <a name="httpAndCaseSensitivity"></a>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.
+
 ##### <a name="undefinedAndImplementationDefinedBehavior"></a>Undefined and Implementation-Defined Behavior
 
 This specification deems certain situations to have either _undefined_ or _implementation-defined_ behavior.
@@ -139,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.
@@ -176,6 +185,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 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.
 
 The formats defined by the OAS are:
@@ -205,7 +216,11 @@ Note that the encoding indicated by `byte`, which inflates the size of data in o
 
 ### <a name="richText"></a>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 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.
+
 
 ### <a name="relativeReferences"></a>Relative References in URLs
 
@@ -218,6 +233,11 @@ Relative references in CommonMark hyperlinks are resolved in their rendered cont
 
 ### 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.
 
 #### <a name="oasObject"></a>OpenAPI Object
@@ -253,7 +273,7 @@ Field Name | Type | Description
 <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
-<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+<a name="infoVersion"></a>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).
@@ -2002,6 +2022,11 @@ transactionCallback:
 
 #### <a name="exampleObject"></a>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.
+
+Examples allow demonstration of the usage of properties, parameters and objects within OpenAPI.
+
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
@@ -3094,7 +3119,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
 
@@ -3671,9 +3697,14 @@ The extensions properties are implemented as patterned fields that are always pr
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="infoExtensions"></a>^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.
+<a name="infoExtensions"></a>^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 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.
 
-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).
+Support for any one extension is OPTIONAL, and support for one extension does not imply support for others.
 
 ### <a name="securityFiltering"></a>Security Filtering