Skip to content

"Object" definition, etc. (3.1.1 port of #4050) #4052

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 28, 2024
Merged

"Object" definition, etc. (3.1.1 port of #4050) #4052

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f547da
"Object" def, "with" in titles, fix level
handrews Aug 26, 2024
fdace9f
Fix two capital-O Objects
handrews Aug 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions versions/3.1.1.md
View file
Open in desktop
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 @@ -135,8 +139,8 @@ Implementations MAY support complete-document parsing in any of the following wa
* Detecting OpenAPI or JSON Schema documents using media types
* Detecting OpenAPI documents through the root `openapi` field
* Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification
* Detecting a document containing a referenceable object at its root based on the expected type of the reference
* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root object
* Detecting a document containing a referenceable Object at its root based on the expected type of the reference
* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object

Implementations that parse referenced fragments of OpenAPI content without regard for the content of the rest of the containing document will miss keywords that change the meaning and behavior of the reference target.
In particular, failing to take into account keywords that change the base URI introduces security risks by causing references to resolve to unintended URIs, with unpredictable results.
Expand Down Expand Up @@ -229,7 +233,7 @@ The formats defined by the OAS are:

As noted under [Data Type](#data-types), both `type: number` and `type: integer` are considered to be numbers in the data model.

#### Working With Binary Data
#### Working with Binary Data

The OAS can describe either _raw_ or _encoded_ binary data.

Expand Down Expand Up @@ -2199,7 +2203,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 @@ -2697,7 +2701,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 @@ -4295,7 +4299,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