Skip to content

Clarify interoperable parsing expectations (3.0.4 port of #3732) #3772

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
May 22, 2024
Merged

Clarify interoperable parsing expectations (3.0.4 port of #3732) #3772

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32c92aa
Limit interoperable parsing expectations
handrews Apr 21, 2024
5573dc6
Schema Object does not have $ref in 3.0
handrews May 16, 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.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,10 +146,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, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions. 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) and [Path Item Object](#pathItemObject) `$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.**
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

be divided into multiple, connected parts (called a "multi-document description")
(to unambiguously define a term that is used later)


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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does item 2 allow for a $ref to refer to a JSON schema document (or a schema within a JSON schema, such as to schema a in a schema bundle containing a schema named a and perhaps other schemas that a references and perhaps other unrelated schemas)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JSON Schema bundles aren't supported in 3.0, because id/$id is not supported (nor are any other keywords that would require scanning a whole document - see #3758 for how that is handled in 3.1).

These bullet points are not intended to allow anything as much as they are to describe what implementations already do. Otherwise I'd have probably thrown in a MAY.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DavidBiesack let me know if I did not answer your question fully - I'm not sure if you were just talking about formal bundling or something else.

* 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

Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
Expand Down