From 32c92aad7e3b36fbf86d57eee178345d1fa97945 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 20 Apr 2024 20:44:52 -0700 Subject: [PATCH 1/2] Limit interoperable parsing expectations As discovered through the OASComply project, certain referencing scenarios are ambiguous, with different authorities holding contradictory interpretations regarding whether and how they are to be supported. As a result, it is impossible to define compliance, as all of the interpretations can be argued to be "correct" in some sense. This change excludes some particularly challenging scenarios from compliance testing by making their behavior explicitly implementation-defined. This has several benefits: * No current implementation is rendered non-compliant * No currently usable OAD is rendered invalid * New implementers need not put effort into handling these scenarios * User expectations are set to _not_ expect consistent behavior * Linters can write a rule to match these expectations * Everyone is guided towards straightforwad best practices Includes substantially better wording from ralfhandl from review comments for the 3.1.1 version of this change. Co-authored-by: Ralf Handl --- versions/3.0.4.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index b125dab467..d56ec0b108 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -146,10 +146,20 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### 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), [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`. +#### 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. + ### 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). From 5573dc6e544c2101204803cae13b0039b9b1364a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 16 May 2024 11:59:49 -0700 Subject: [PATCH 2/2] Schema Object does not have $ref in 3.0 --- 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 d56ec0b108..7b1845c06d 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -146,7 +146,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### OpenAPI Description Structure -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.** +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.** It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`.