Skip to content
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

Clarify File Structure and use of $ref JSON Reference/Pointer #648

Closed
DavidBiesack opened this issue Apr 12, 2016 · 6 comments
Closed

Clarify File Structure and use of $ref JSON Reference/Pointer #648

DavidBiesack opened this issue Apr 12, 2016 · 6 comments

Comments

@DavidBiesack
Copy link

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.

@ralfhandl
Copy link
Contributor

+1

@handrews
Copy link
Member

@DavidBiesack @ralfhandl The definition of $ref moved into the JSON Schema specification as of draft-wright-00 a.k.a. draft-05, which is what OpenAPI 3.0 uses.

§7 of draft-wright-00 (and the analogous sections in later drafts) are the current definitions of $ref. Earlier it was a separate JSON Reference specification, but that seemed overly complicated. However, if there is clear demand it can be split out again and both JSON Schema and OpenAPI could simply define how and where they allow it.

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).

@ralfhandl
Copy link
Contributor

@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 $ref to document B, then relative $ref URLs in document B are resolved relative to document B, which is a necessity for providing reusable schema documents.

One caveat: 7. Schema references with $ref of draft-wright-00 aka draft-05 states that

A schema MUST NOT be run into an infinite loop against a schema.

While I fully agree with the given example of not having cyclic allOf constructs, I want to point out that "cyclic" property references are the rule (and not the exception) in my line of work: customers place orders, and orders are placed by customers, so the Customer schema will have an optional array-valued property whose items are $refing the Order schema, which in turn will have an optional single-valued property that is $refing the Customer schema. Which luckily works fine with Swagger UI 3.x, see my People and Products examples with lots of "cyclic" property references within and across OpenAPI documents.

Maybe a future draft of JSON Schema could explicitly state property references as an allowed use case for "cyclic" references.

@handrews
Copy link
Member

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.

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 $refs referring to each other in a loop (in the simplest form, a $ref referring to itself). In this case, regardless of the instance, an implementation attempting to dereference things to find a directly usable schema (not a reference) will never find one. When fetching schemas over a network, an attacker could insert such a schema and cause the validator to go into an infinite loop if the validator does not detect such situations.

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 $ref as a subschema will only be followed if there is instance data to which that subschema applies.

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).

@ralfhandl
Copy link
Contributor

@handrews Thanks for the clarification on cyclic references!

And +1 to citing a "living" document instead of an expired draft.

@handrews
Copy link
Member

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants