Improve explanation of Reference Object

[jharmn]

With the addition of relative file references (notably in swagger-js, and samples), there should be an explanation of how that resolves (based on JSON Reference). Samples/petstore-separate provides a reference point that could be utilized.

[jharmn]

On further review, the REUSE guidelines should be updated too:
https://github.com/swagger-api/swagger-spec/blob/master/guidelines/REUSE.md

[webron]

@jasonh-n-austin - are you referring specifically to how relative references are resolved?

[jharmn]

Right, so perhaps examples of what $ref links should/shouldn't look like, and what they should be relative to in pathing.

One example:

swagger.yaml
$ref: 'models/Thing.yaml'

Thing.yaml
$ref: 'models/AnotherThing.yaml' # note path is relative to swagger.yaml, not Thing.yaml

Also, deep links such as:

$ref: 'models/Common.yaml#Address' # an object within a schema file

All of this is really just how JSON Reference works, but some practical examples would probably help devs implementing the Swagger 2 spec get it right more consistently.

[john-kurkowski]

👍 been burning a lot of cycles reverse engineering what references are supported. REUSE.md seems to indicate only absolute references.

[mission-liao]

@jasonh-n-austin Hi, I'm refactoring my python client for external file reference, and feel confused with these:

swagger.yaml
$ref: 'models/Thing.yaml'

Thing.yaml
$ref: 'models/AnotherThing.yaml' # note path is relative to swagger.yaml, not Thing.yaml

In another discussion, one of your comment:

Each file resolves it's own refs, regardless where they're included from. In the swagger.yaml->Category->Person example, the $ref in Category is resolved from it's own location to find Person (as opposed to the location of swagger.yaml).

In the first comment, the base URI used to resolve 'models/AnotherThing.yaml' should be derived from swagger.yaml, although the $ref resides in Thing.yaml. But the comment in another issue states that the base URI should be derived from Thing.yaml.

Which one of my understanding is correct? Thanks for any feedback in advance. 👍

[whitlockjc]

I would expect relative references to be based on the location of the document containing the reference.

[jharmn]

I tend to agree with you @whitlockjc (clearly contradicting my earlier statements). I think I was basing the examples on the way that @BigstickCarpet 's swagger-parser resolves JSON references (which could be incorrect here).

Per the RFC for JSON Reference (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03):

Resolution is performed relative to the referring document.

[whitlockjc]

When working on swagger-tools and sway, I created json-refs just for this. While I'm not saying it's perfect or should be the guide, it's been well received. Ever since supporting relative references in json-refs, relative references have always been resolved as I mentioned above and I'm yet to have anyone complain about it or suggest otherwise. While the sample set is small, this tells me that the intuitive approach matches what I suggested above as well.

[jharmn]

FWIW, I put together a sample spec which has separated files (https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate). IIRC I ran swagger-tools across this to validate that everything was resolving right. This should serve as a working example for other implementers for the time being.

[mission-liao]

I'm still confused with that RFC :(

Resolution is performed relative to the referring document.

In the example above, should the referring document be swagger.yaml or Thing.yaml when resolving 'models/AnotherThing.yaml'?

@BigstickCarpet very clear, thanks.

[JamesMessinger]

I agree with @jasonh-n-austin and @whitlockjc that relative references should be based on the location of the document containing the reference. Swagger Parser 1.x and 2.x both resolved relative paths based on the main document rather than the containing document, but there were at least three problems with that:

1. It proved to be very fragile. Any time you moved files around or changed your folder structure, you had to go find and change every relative reference. It was a pain in the ass.

2. It didn't match the way people were using Swagger in the real world. It was a constant point of confusion/frustration for people who were using Swagger Parser.

3. And this is the big one - the JSON Reference specfication is very clear about how relative path resolution should behave:

   If the URI contained in the JSON Reference value is a relative URI,
   then the base URI resolution MUST be calculated according to
   [RFC3986], section 5.2. Resolution is performed relative to the
   referring document.

Swagger Parser 3.0 was a complete rewrite, and one of the main goals was to make it fully compliant with all of the specifications involved (Swagger 2.0, JSON Schema, JSON Hyper-Schema, JSON Reference, and JSON Pointer). As a result, relative references are now resolved relative to the containing document.

[jharmn]

I'll see what I can do about finally getting around to writing something up in REUSE.md...this discussion helped nail down some of the potential ambiguity.