Misuse of "URI" in definition of $ref

[chris-martin]

https://swagger.io/docs/specification/v3_0/using-ref/ says

the $ref string value (JSON Reference) should contain a URI,

but the examples given show that it is not actually a URI. It seems like the correct term here would be "URI reference."

From https://www.ietf.org/rfc/rfc3986.txt -

A URI-reference is either a URI or a relative reference.

 URI-reference = URI / relative-ref

Most of the examples are relative references.

[frankkilcommins]

Hi @chris-martin,

Thanks for raising the issue.

As described in OpenAPI 3.2:

Unless specified otherwise, all fields that are URIs MAY be relative references as defined by RFC3986 Section 4.2.

We could add a similar clarification to the docs here.

[chris-martin]

Instead of OpenAPI redefining the term "URI" to mean "either URI or relative reference," why not consistently use the term "URI reference," which RFC 3986 already defines to mean exactly that?

[frankkilcommins]

@chris-martin Yeah that OpenAPI wording here will hopefully be improved in future versions (although we might miss the boat for 3.2).

Right now OpenAPI is saying when ever you see URI think URI-reference unless explicitly stated that it's not.

In the interim, I'm supportive of changing the swagger guide documentation related to this.

Would you be interested in raising a PR?