$ref value must be accessible URL for external reference?

[Shulamite]

Based on JSON reference spec, the $ref value is an URI, which by definition is a resource identifier only, and is independent of access.
It seems it is valid to use a well formed URI, but not an accessible URL (assuming http).
However, if it is not a valid URL for external reference, how would different tools resolve the references?

[handrews]

$ref takes a URI. Some URIs are also URLs. I don't see a contradiction here. There is no need to call out JSON Pointers specifically for $ref, as fragment syntax is a function of the target resource's media type. The OAS document media type uses JSON Pointer fragments, so that follows naturally.

[whitlockjc]

I removed my comment, I had the same thought there is no contradiction but I overthought it.

[Shulamite]

Is it accurate to say that URI must be addressable?

[handrews]

@Shulamite there are no restrictions on the value of $ref other than "it MUST be a URI reference" (meaning it can either be a full URI starting with a scheme, or a relative URI). Some sorts of URIs are more convenient than others, but all are valid.

[handrews]

Some sorts of URI will also no doubt have much better tooling support.

[handrews]

@darrelmiller @webron @tedepstein I think we touched on this related to #2092. There is a valid reading of JSON Reference that requires the value of $ref to be a URL rather than a URI, but in OAS 3.1 with the new JSON Schema that is relaxed, and any valid URI is legal.

So I think this should be closed as answered in 3.0 and fixed in 3.1? Or maybe tracked under #2099 if we think we need to explain this further in OAS 3.1 and can't just fold it into #2092.

[philsturgeon]

I vote for "fixed in v3.1" and close this.

[handrews]

@Shulamite for OAS 3.0.x, the relevant language from the JSON Reference draft is (bolding added):

The "$ref" string value contains a URI [RFC3986], which identifies the location of the JSON value being referenced.

Per discussion with @darrelmiller in a recent TSC meeting, that is interpreted to require a URL, not just a URI. So OAS 3.0.x does not allow non-URL URIs, and therefore doesn't need to explain how one might resolve them.

In OAS 3.1 that draft is no longer referenced, and we are tracking the implications of that through #2099 and related issues.