From 9da10c5b5722d5a21fd27719ba25468290cf68be Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 26 Apr 2024 10:32:30 -0700 Subject: [PATCH 1/3] Clarify how Schema Objs require full-doc parsing JSON Schema draft 2020-12 includes numerous keywords that require parsing the entire document prior to deeming a reference unresolvable. This makes that more clear and outlines several approaches. The practice of embedding OpenAPI fragments in other formats is deemed to have implementation-defined (non-interoperable) behavior, as the potential complications that might arise are not predictable. --- versions/3.1.1.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 3737ffcf3c..328107c090 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -140,6 +140,22 @@ 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`. +#### Parsing Documents + +In order to properly handle [Schema Objects](#schemaObject), OAS 3.1 inherits the parsing requirements of [JSON Schema draft 2020-12 ยง9](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relativeReferencesURI). + +This includes a requirement to parse complete documents before deeming a Schema object reference to be unresolvable, in order to detect keywords that might provide the reference target or impact the determination of the appropriate base URI. + +Implementations MAY support complete-document parsing in any of the following ways: + +* Detecting OpenAPI or JSON Schema documents using media types +* Detecting OpenAPI documents through the root `openapi` property +* Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification +* Detecting a document containing a referenceable Object at its root based on the expected type of the reference +* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object + +Embedding fragments of OpenAPI content in other formats can produce unexpected interactions among the enclosing format, the OAS, and JSON Schema. While implementations MAY choose to support such arrangements, the resulting behavior is _implementation defined_. This includes parsing fragments of OpenAPI out of a complete OpenAPI document while treating the rest of the document as arbitrary JSON or 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: From 3f60c515664594b8b0ad994b36cbdbb8f579ceee Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 2 May 2024 11:27:09 -0700 Subject: [PATCH 2/3] Add advice to OAD authors related to doc 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 328107c090..9ea88dbe4f 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -154,7 +154,7 @@ Implementations MAY support complete-document parsing in any of the following wa * Detecting a document containing a referenceable Object at its root based on the expected type of the reference * Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object -Embedding fragments of OpenAPI content in other formats can produce unexpected interactions among the enclosing format, the OAS, and JSON Schema. While implementations MAY choose to support such arrangements, the resulting behavior is _implementation defined_. This includes parsing fragments of OpenAPI out of a complete OpenAPI document while treating the rest of the document as arbitrary JSON or YAML. +Embedding fragments of OpenAPI content in other formats can produce unexpected interactions among the enclosing format, the OAS, and JSON Schema. While implementations MAY choose to support such arrangements, the resulting behavior is _implementation defined_. This includes parsing fragments of OpenAPI out of a complete OpenAPI document while treating the rest of the document as arbitrary JSON or YAML. Since parsing isolated fragments in this way will fail to notice keywords that might impact meaning or behavior, including in ways that contradict this specification's requirements, it is RECOMMENDED that OpenAPI Description authors avoid depending on such behavior. #### Structural Interoperability From ffe04346fac9921ab4e1147065b03d6a11b19c85 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 3 May 2024 10:50:14 -0700 Subject: [PATCH 3/3] Rework the guidance around fragmentary parsing. This goes into more detail and uses "undefined" instead of "implementation-defined" as the behavior is likely to be incorrect (rather than just a different interpretationof an ambiguous requirement), and may result in security concerns as well. --- versions/3.1.1.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 9ea88dbe4f..fab3a8295b 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -154,7 +154,16 @@ Implementations MAY support complete-document parsing in any of the following wa * Detecting a document containing a referenceable Object at its root based on the expected type of the reference * Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object -Embedding fragments of OpenAPI content in other formats can produce unexpected interactions among the enclosing format, the OAS, and JSON Schema. While implementations MAY choose to support such arrangements, the resulting behavior is _implementation defined_. This includes parsing fragments of OpenAPI out of a complete OpenAPI document while treating the rest of the document as arbitrary JSON or YAML. Since parsing isolated fragments in this way will fail to notice keywords that might impact meaning or behavior, including in ways that contradict this specification's requirements, it is RECOMMENDED that OpenAPI Description authors avoid depending on such behavior. +Implementations that parse referenced fragments of OpenAPI content without regard for the content of the rest of the containing document will miss keywords that change the meaning and behavior of the reference target. +In particular, failing to take into account keywords that change the base URI introduces security risks by causing references to resolve to unintended URIs, with unpredictable results. +While some implementations support this sort of parsing due to the requirements of past versions of this specification, in version 3.1, the result of parsing fragments in isolation is _undefined_ and likely to contradict the requirements of this specification. + +While it is possible to structure certain OpenAPI Descriptions to ensure that they will behave correctly when references are parsed as isolated fragments, depending on this is NOT RECOMMENDED. +This specification does not explicitly enumerate the conditions under which such behavior is safe, and provides no guarantee for continued safety in any future versions of the OAS. + +A special case of parsing fragments of OAS content would be if such fragments are embedded in another format, referred to as an _embedding format_ with respect to the OAS. +Note that the OAS itself is an embedding format with respect to JSON Schema, which is embedded as Schema Objects. +It is the responsibility of an embedding format to define how to parse embedded content, and OAS implementations that do not document support for an embedding format cannot be expected to parse embedded OAS content correctly. #### Structural Interoperability