OAD Structure and referencing in OpenAPI 3.1 #4114
Replies: 3 comments 15 replies
-
I'll try to summarize my understanding of how document structure and referencing works in OAS 3.1, quoting the 3.1.1 spec or borrowing words from @handrews and others in places. From the 3.1.0 spec, the general concept is this:
As for how references work, the 3.1.0 spec says this:
which was also the case in OAS 3.0, but the difference in 3.1 is that URI references are resolved differently. In OAS 3.1:
and
There's more to the story but I'm going to save this and amend with more content later. |
Beta Was this translation helpful? Give feedback.
-
tdc notes: resource , documents, and description. (rework, should be addressed before patch release?) |
Beta Was this translation helpful? Give feedback.
-
We had a lively discussion of this topic in the TDC meeting yesterday. Trying to tease apart what is meant by "OpenAPI Description" vs "OpenAPI Document" has been challenging. And connecting these to related terms used in the OAS or referenced RFCs, such as "resource", "entity", adds yet more complexity. There were differing views on what should be considered "the referring document" in this sentence taken from the OAS 3.1.0:
There was the view I presented in the comment above, which is basically that the JSON value found at the fragment could be considered the referring document (ignoring the outer "document" in which it was contained). Henry argued that this interpretation is invalid -- that the referring document must be considered to the document/resource referenced by the "absolute" part of the URI (fragment removed). As support for this view, Henry pointed out that fragment processing must be done based on the MIME type of the resource and "application/json" has no defined fragment identification syntax, citing RFC 6901 (section 5). As such, referencing a fragment in a "plain JSON" document is undefined and (as spec writers) we should disallow it. At the end of the meeting we agreed to attempt to formalize the "description", "document", "resource" terminology and then use that as a way of clarifying this whole area. |
Beta Was this translation helpful? Give feedback.
-
We've been having a lot of discussions about document structure and how OAS and JSON Schema references work in various places, such as
I think we can continue discussing the 3.0 behavior in #4100, but (to the degree that these can be separated) thought it would be a good idea to start a discussion focused primarily on the behavior in 3.1, which I think most folks feel is what we want going forward.
Beta Was this translation helpful? Give feedback.
All reactions