From 814e0d5a89e7de9519cce4f7d87d6aa50bb905b2 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 20 Apr 2024 20:44:52 -0700 Subject: [PATCH 1/4] 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 --- versions/3.1.1.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e4423df5b2..aeb2110750 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -136,10 +136,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, [`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`. +### 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 contexts requiring it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios. + ### 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). From dd8c0aa6ec6e029b67cf67a0038ecb8e94ad7faf Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 21 Apr 2024 10:09:05 -0700 Subject: [PATCH 2/4] Add an example of non-interoperable parsing --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index aeb2110750..cfdf9cfe6c 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -148,7 +148,7 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such * 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 contexts requiring it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios. +If the same JSON/YAML object is parsed multiple times contexts requiring 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 From e2dd78c48cb09d540e389a079b5270ec67836446 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 21 Apr 2024 17:49:15 -0700 Subject: [PATCH 3/4] Fix header level for new section The Structural Interoperability section should be a subsection of the OpenAPI Description Structure section. --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index cfdf9cfe6c..3424eb4d68 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -140,7 +140,7 @@ An OpenAPI Description (OAD) MAY be made up of a single document or be divided i It is RECOMMENDED that the entry OpenAPI document be named: `openapi.json` or `openapi.yaml`. -### Structural Interoperability +#### 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: From ea38588b2e06005f27ead0fda0b78f88be4053ae Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 25 Apr 2024 07:48:56 -0700 Subject: [PATCH 4/4] Substantially better wording from ralfhandl in review comments Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 3424eb4d68..f3631dee35 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -148,7 +148,7 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such * 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 contexts requiring 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. +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