Terminology: relative URI reference

[mikekistler]

Apologies if this has been discussed before, but I just came across this when reviewing the v1.2 Overlays spec and I had to dig into it.

Several places in the Overlays spec (some existing in v1.1) use the terminology "relative URI reference". (This also occurs in several places in the OpenAPI spec). I wanted to make sure I understood exactly what this is, since these things have always confused me, so I went to RFC 3986 to get the official definition. What I found was that RFC 3986 does not define "relative URI reference" -- in fact that term is never used in the RFC. It does define:

• URI
• URI reference
• relative reference

In most of the places I've looked at, the term "relative URI reference" probably means what RFC 3986 calls a "relative reference", e.g.

Relative URI references are resolved using the appropriate base URI,

probably means the same thing as

Relative references are resolved using the appropriate base URI,

The Overlays spec does use the term "relative references" in several places -- more often than "relative URI references" in fact.

This may seem like I am picking nits here but I honestly find URI references / resolution confusing enough (for my little brain) without throwing in extra terminology.

Is anyone else bothered by this?

[baywet]

Thanks for calling this out Mike. I had a look at the PRs that lead to 1.2 and couldn't find a single discussion along the lines of "we should name them relative URI reference because". And in the fields definitions, we do use URI reference (for $self, $ref has the issue as well but it points to the RFC section that calls it URI reference).

So in case of overlay, I can make a last minute PR to align the wording, not sure what that means for the vote though? we'd probably have to restart it?

Note: this issue dates from Overlay 1.0 which has

The extends property can also specify a relative URI reference.

This is probably the initial source of the "nomenclature slip" for overlays.

We could produce patches for 1.1 and 1.0 is we absolutely think it's crucial.

For OAS, I think a broader discussion would be required.