Order of resolution of references - resolve remotes first? about swagger-parser

[whitlockjc]

No problem. The good news is this feature was a pain to implement anyways so removing it makes my life easier. 👍

[JamesMessinger]

Hi. Sorry for not replying sooner. I've been away on holiday.

The $ref in responses.yaml is invalid, because it's pointing to a definition within the same file, which doesn't exist (see the JSON Reference spec for details).

Instead of referencing a type definition, you need to directly reference the extended_error_model.yaml file instead, like this:

# Common responses
200:
  description: OK
  schema:
    type: string

DefaultError:
  description: Error payload
  schema:
    $ref: 'definitions/error/extended_error_model.yaml'     # <-- referencing the file

[JamesMessinger]

Another way to fix the problem would be to point to the type definition in your index.yaml or definitions/index.yaml file, like this:

# Common responses
200:
  description: OK
  schema:
    type: string

DefaultError:
  description: Error payload
  schema:
    $ref: 'index.yaml#/definitions/ExtendedErrorModel'     # <-- referencing the type definition

[mrchief]

Thanks for pointing to the spec.

I couldn't find anything definitive and the closest I found indicated that this is tooling issue. sway and its predecessor swagger-tools seem to do it the other way (remotes first and then local).

So I wasn't sure which way is the right way. @whitlockjc If this is invalid per spec, why Sway and swagger-tool support it?

I'm asking so that I can present a good case for going back and changing the few dozen APIs in my org who are already doing this (i.e. relative refs that are in other files).

[whitlockjc]

When I read the spec, I didn't feel it was very clear. I am sure the point where you suggest I deviate from the spec falls in this statement:

If a URI contains a fragment identifier, then the fragment should be
resolved per the fragment resolution mechansim of the referrant
document.

While this does explain that local references should be resolved against the local document, the specification leaves a lot to interpretation when it comes to the order in which resolution happens. It's this that I think causes the discrepancy. I'll file a bug in json-refs and reference this issue in the report. I'm currently rewriting json-refs anyways and we'll just not do the hierarchical resolution for local references in remote documents. Thanks for bringing this up.

[JamesMessinger]

@mrchief - Just to clarify... It's not a matter of "remotes first" vs "local first". The order is irrelevant. The issue is scope resolution. A $ref such as #/foo/bar is relative to the root of the current file, not to the root of the entire JSON schema. That said, the JSON Reference spec does allow the resolution scope to be changed using special id properties, but I don't think that feature of JSON Reference is supported by Swagger.

[whitlockjc]

Well, what I meant by order was if you just create a composite document by including the remote document first and then resolving the local references, the local reference in your remote document could possibly apply to the original (remote) document or the composite document that the remote document was just included into. In fact, that's why it was written the way it was. In all fairness, I do think there was some invalid Swagger usage that led to this.

[JamesMessinger]

@whitlockjc - Ah, ok. I see what you mean by "order" now. Thanks for the clarification. 👍

[JamesMessinger]

Closing this issue, since Swagger Parser is working as intended.