Merge pull request #4050 from handrews/obj-with

"Object" definition, "with" in titles, fix level of "Working with Examples"

Author: ralfhandl

versions/3.0.4.md

@@ -28,6 +28,10 @@ A "schema" is a formal description of syntax and structure.
 This document serves as the [schema](#schema) for the OpenAPI Specification format; a non-authoritative JSON Schema based on this document is also provided on [spec.openapis.org](https://spec.openapis.org) for informational purposes.
 This specification also _uses_ schemas in the form of the [Schema Object](#schema-object).
 
+### Object
+
+When capitalized, the word "Object" refers to any of the Objects that are named by section headings in this document.
+
 ### Path Templating
 
 Path templating refers to the usage of template expressions, delimited by curly braces (`{}`), to mark a section of a URL path as replaceable using path parameters.
@@ -199,7 +203,7 @@ The formats defined by the OAS are:
 | `string`             | `date-time`                 | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) |
 | `string`             | `password`                  | A hint to obscure the value.                                                              |
 
-#### Working With Binary Data
+#### Working with Binary Data
 
 Two formats, `binary` and `byte`, describe different ways to work with binary data:
 
@@ -2125,7 +2129,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten
 In all cases, the example value SHOULD be compatible with the schema of its associated value.
 Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.
 
-#### Working With Examples
+##### Working with Examples
 
 Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object).
 In both objects, this is done through the `examples` (plural) field.
@@ -2618,7 +2622,7 @@ $ref: '#/components/schemas/Pet'
 $ref: Pet.yaml
 ```
 
-##### Relative Documents With Embedded Schema Example
+##### Relative Documents with Embedded Schema Example
 
 ```json
 {
@@ -4087,7 +4091,7 @@ when expanded with the data given earlier, we get:
 ?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun
 ```
 
-#### Expansion With Non-RFC6570-Supported Options
+#### Expansion with Non-RFC6570-Supported Options
 
 But now let's say that (for some reason), we really want that `/` in the `b` formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase.
 To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: "spaceDelimited"` for `words`: