Skip to content

Clarify complete vs self-contained documents #4077

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
Sep 12, 2024
Merged

Clarify complete vs self-contained documents #4077

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc8df9d
Clarify complete vs self-contained documents
handrews Sep 7, 2024
c11668c
Update versions/3.0.4.md
ralfhandl Sep 7, 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
6 changes: 4 additions & 2 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,9 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA

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](#reference-object) and [Path Item Object](#path-item-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used.

Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **complete OpenAPI document**.
Any document consisting entirely of an [OpenAPI Object](#openapi-object) is known as a **syntactically complete OpenAPI document**.
An OpenAPI document that does ***not*** reference any other documents is known as a **self-contained OpenAPI document.***
A single-document description is therefore _both_ syntactically complete _and_ self-contained.
In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API's description is known as that API's **entry OpenAPI document**, or simply **entry document**.

It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`.
Expand All @@ -130,7 +132,7 @@ It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `o

When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), 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 complete OpenAPI Description document
* As a syntactically complete OpenAPI Description 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

Expand Down
Loading