OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Clarify how Schema Objects require full-document parsing (3.1.1)
This is the next step in un-blocking OASComply. Unlike the previous OASComply-related PR, this PR does not apply to v3.0.4. What, if any, wording about document parsing needs to go in 3.0.4 is something we can sort out later.
The implied requirement might be surprising to some, but is an unambiguous result of normatively citing JSON Schema 2020-12. Resolution of references to $id values that do not match the document's location (e.g. are resolved as URIs rather than URLs, including by noticing them in already-parsed content) was affirmed multiple times by TSC decisions during the work on OAS 3.1:
- https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-571665656
- https://github.com/OAI/OpenAPI-Specification/issues/2092#issuecomment-585881781
- https://github.com/OAI/OpenAPI-Specification/issues/2159#issuecomment-601283402
Unfortunately, it seems like we never did get around to adding explicit wording highlighting this. Which does not change the fact that a.) it was decided and re-affirmed, and b.) normatively citing JSON Schema 2020-12 mandates this behavior as the only possible way to satisfy its requirements.
There might be further changes related to this in the "Resolving Relative References in URIs", but I'll deal with that when I fix #3545, which covers both that section and "Resolving Relative References in URLs".
I also expect we'll want to add further guidance for both implementors and description authors on the Learn site. I tried to keep the text here as minimal as possible while heading off the misunderstandings we've seen as folks implement 3.1.
Commit message:
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.
This PR IMHO is very clear. I am very much tempted to merge this before the TDC call. @lornajane , @ralfhandl thoughts?
@miqui this one has some pretty deep impacts so I'd rather leave it open for longer.
@ralfhandl I've pushed a new commit with the following commit message:
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.
I don't know that it's a simplification, but I think it's more explicit and should be easier to follow. Please do continue to suggest simplified wording - it's something I struggle with sometimes.
