Skip to content

Commit

Permalink
"Object" def, "with" in titles, fix level
Browse files Browse the repository at this point in the history
Define capital-O "Object" to make it clear why it is only occasionally
capitalized.

Use lowercase "with" in titles consistently (it was more common than
capitalized "With".  This is one of those rules that is different
depending on whose style guide you use- about half the major guides
say always lowercase, the other say always captial.  We were using
lowercase more often.

Also, fix "Working with Examples" to be a subsection of the
Example Object as otherwise it breaks the pattern of all of the
headings of its level being Object definitions.  I remember messing
with this a lot when I first posted that PR and either I just
missed this or I had some reason I have now forgotten to do it
this way.
  • Loading branch information
handrews committed Aug 26, 2024
1 parent 57a9bc6 commit 55e87c3
Showing 1 changed file with 8 additions and 4 deletions.
12 changes: 8 additions & 4 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -2618,7 +2622,7 @@ $ref: '#/components/schemas/Pet'
$ref: Pet.yaml
```

##### Relative Documents With Embedded Schema Example
##### Relative Documents with Embedded Schema Example

```json
{
Expand Down Expand Up @@ -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`:
Expand Down

0 comments on commit 55e87c3

Please sign in to comment.