From cc8df9d53fc79c18a1779cd88e6762a885ff1fb4 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 7 Sep 2024 09:07:05 -0700 Subject: [PATCH 1/2] Clarify complete vs self-contained documents --- versions/3.0.4.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 46005e9eb7..086de31642 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -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`. @@ -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 From c11668cd4eed364256a6ed46b150d393794a6d3b Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Sat, 7 Sep 2024 18:41:17 +0200 Subject: [PATCH 2/2] Update versions/3.0.4.md --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 086de31642..8bffc966e6 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -122,7 +122,7 @@ 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 **syntactically complete OpenAPI document**. -An OpenAPI document that does ***not*** reference any other documents is known as a **self-contained 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**.