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

Limit interoperable parsing expectations (avoid type conflicts) #3732

Merged
merged 4 commits into from
Apr 25, 2024
Merged

Limit interoperable parsing expectations (avoid type conflicts) #3732

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
814e0d5
Limit interoperable parsing expectations
handrews Apr 21, 2024
dd8c0aa
Add an example of non-interoperable parsing
handrews Apr 21, 2024
e2dd78c
Fix header level for new section
handrews Apr 22, 2024
ea38588
Substantially better wording from ralfhandl in review comments
handrews Apr 25, 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
12 changes: 11 additions & 1 deletion versions/3.1.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,10 +136,20 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA

### <a name="documentStructure"></a>OpenAPI Description Structure

An OpenAPI Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used. In a multi-document description, the document containing the [OpenAPI Object](#oasObject) is known as the **entry OpenAPI document.**
An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#referenceObject), [Path Item Object](#pathItemObject) and [Schema Object](#schemaObject) `$ref` keywords, as well as the [Link Object](#linkObject) `operationRef` keyword, are used. In a multi-document description, the document containing the [OpenAPI Object](#oasObject) is known as the **entry OpenAPI document.**

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

#### <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:

* As a full OpenAPI Description document (an [OpenAPI Object](#oasObject) taking up an entire document)
* As the Object type implied by its parent Object within the document
* As a reference target, with the Object type matching the reference source's context

If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios.

### <a name="dataTypes"></a>Data Types

Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).
Expand Down