Various minor editorial improvements (3.0.4)

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,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).
 
+##### <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.
@@ -174,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 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:
@@ -203,7 +213,7 @@ 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 implement extensions on top of CommonMark 0.27, and MAY choose to ignore some CommonMark or extension features to address security concerns. 
 
 ### <a name="relativeReferences"></a>Relative References in URLs
 
@@ -214,6 +224,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.
 
 #### <a name="oasObject"></a>OpenAPI Object
@@ -1984,6 +1999,10 @@ 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.
+
+Allows sharing an example to demonstrate the usage of properties, parameters and objects within OpenAPI.
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -2913,7 +2932,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
 
@@ -3490,9 +3510,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