-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Clarify File Structure and use of $ref JSON Reference/Pointer #648
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
+1 |
@DavidBiesack @ralfhandl The definition of §7 of draft-wright-00 (and the analogous sections in later drafts) are the current definitions of Since OpenAPI does point to the correct current definition, at least for OpenAPI 3.0, I suggest that this could be closed. If you do not find the way it is documented in JSON Schema to be appropriate, please first check the latest work-in-progress wording, and if that is still not sufficient, please file a JSON Schema issue and I'll be happy to follow up on it there (I'm currently the more active of the two JSON Schema spec editors). |
@handrews I’m fine with closing this issue. Note that OpenAPI 3.0.0 section Relative References in URLs cites https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 with respect to resolving relative references. OpenAPI 3.0.1 could instead cite section 7. Schema references with $ref of draft-wright-00 aka draft-05, which describes the same relative resolution mechanism, i.e. if document A contains a One caveat: 7. Schema references with $ref of draft-wright-00 aka draft-05 states that
While I fully agree with the given example of not having cyclic Maybe a future draft of JSON Schema could explicitly state property references as an allowed use case for "cyclic" references. |
Ah, I missed this. Although I have some vague recollection of discussing whether it made sense to keep referencing the separate JSON Reference draft, although that may or may not have even been here. IETF I-Ds are not intended to be cite-able at all, but an I-D that expired in 2013 with a viable, un-expired alternative definitely should not be cited (although again, someone could revive that draft or request that the JSON Schema project do so). JSON Schema is in a weird space with drafts and citing, because it became a de-facto "standard" while the project was more or less abandoned for a few years. But I think specs should attempt to cite current drafts, as was done with other citations of draft-wright-*-00. So this is probably worth keeping open to track that (or should we file a new issue for that for clarity?) Regarding cyclic/infinite loop, cyclic references do not inherently produce infinite loops. The meta-schemas themselves are cyclic. What this is referring to is when the cycle only consists of In the sort of cyclic systems you are talking about, during validation, you will eventually run out of instance data and will stop following the cycle in the schema. A If you are statically analyzing the schema to generate docs or code, presumably you do something to detect cycles and replace them with links or notes or something. The spec doesn't really get into that because it hasn't directly addressed that sort of usage (although it gets mentioned in the forthcoming hyper-schema draft). |
@handrews Thanks for the clarification on cyclic references! And +1 to citing a "living" document instead of an expired draft. |
OAS 3.1 will cite JSON Schema draft 2019-09 or 2020-0?, which covers all of this much, much more directly. 2020-0? will consolidate information on how to load and process schemas, including references, with and without an instance (see json-schema-org/json-schema-spec#849 for details- probably more details than most people want, really) |
File Structure section says
The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.
However, the cited http://json-schema.org/ page does not define
$ref
-- one must dig to find a mention of it or here but even those do not define what$ref
is or can express.I think a better link might be JSON Reference and JSON Pointer.
This would help improve #636 for example making clearer that examples could be outside the spec file in linked (relative or http://) resources. Both links are necessary because the former is not clear about links outside of the document that contains the JSON Reference.
The text was updated successfully, but these errors were encountered: