Skip to content
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

Jump to bottom

Clarify how Schema Objects require full-document parsing (3.1.1) #3758

Merged
merged 3 commits into from
May 14, 2024
Merged

Clarify how Schema Objects require full-document parsing (3.1.1) #3758

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9da10c5
Clarify how Schema Objs require full-doc parsing
handrews Apr 26, 2024
3f60c51
Add advice to OAD authors related to doc parsing
handrews May 2, 2024
ffe0434
Rework the guidance around fragmentary parsing.
handrews May 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 16 additions & 0 deletions versions/3.1.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,22 @@ An OpenAPI Description (OAD) MAY be made up of a single document or be divided i

It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`.

#### <a name="parsingDocuments"></a>Parsing Documents

In order to properly handle [Schema Objects](#schemaObject), OAS 3.1 inherits the parsing requirements of [JSON Schema draft 2020-12 §9](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relativeReferencesURI).

This includes a requirement to parse complete documents before deeming a Schema object reference to be unresolvable, in order to detect keywords that might provide the reference target or impact the determination of the appropriate base URI.

Implementations MAY support complete-document parsing in any of the following ways:

* Detecting OpenAPI or JSON Schema documents using media types
* Detecting OpenAPI documents through the root `openapi` property
* 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

Embedding fragments of OpenAPI content in other formats can produce unexpected interactions among the enclosing format, the OAS, and JSON Schema. While implementations MAY choose to support such arrangements, the resulting behavior is _implementation defined_. This includes parsing fragments of OpenAPI out of a complete OpenAPI document while treating the rest of the document as arbitrary JSON or YAML. Since parsing isolated fragments in this way will fail to notice keywords that might impact meaning or behavior, including in ways that contradict this specification's requirements, it is RECOMMENDED that OpenAPI Description authors avoid depending on such behavior.
handrews marked this conversation as resolved.
Show resolved Hide resolved

#### <a name="structuralInteroperability"></a>Structural Interoperability

When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operationObject), [Response Objects](#responseObject), [Reference Objects](#referenceObject), etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts:
Expand Down