v3.2: $self field (Alternative Approach)

[handrews]

This is an alternative to PR #4389. The only functional difference is that $self is required to be absolute (a change that @karenetheridge and @mikekistler are debating).

The main difference is that I drastically reduced the normative specification text and instead gave examples of all of the different ways to establish a base URI. [EDIT: and put the examples in an appendix] This is probably more understandable than trying to explain the options in prose.

@notEthan I also dumped a lot of the use cases as I think I figured out a more concise way to get the point across.

This adds $self as a way for a document to define its own URI for use in reference targets, and as the base URI for relative URI references in the document.

This does not impact the resolution of relative API URLs.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

After staring at the giant examples section a lot, I decided it works better as an appendix. (force push is just because I accidentally picked up a stray file in the commit and had to edit it to pull that out).

[lornajane]

This is the most readable of the lot, and I think I "get" the whole thing a lot more now. Thank you for doing this work and all the iterations!

Minor points/suggestions from me (I'm not ready to approve but I've only got small questions):

• in the proposal we called it self but it looks like now it is $self. We have other URI fields with plain-text names, why does this one need the $? Since it's being added at the top level, we can be confident of not having name clashes. (why isn't it in info with the other document information like license? Am I asking too many questions?)
• I'd like to propose we move the appendix to the learn site and link to it. Is the learn site really good/mature/stable enough to link to from a spec file? I think it is, and the information would be better there (but needs to be very well signposted since we haven't done this for other content).

[lornajane]

Good discussion in the meeting:

• content does need to go to the learn site, but we're not going to block this change for it
• $self makes sense because it's like $ref in being "special" and related to how references work

[karenetheridge]

I am in agreement with the shuffling of the examples to the learn site rather than in the main spec, but not with the change from relative to absolute uri.

[mikeschinkel]

@handrews — A big +1 from me for including examples in the spec. I would prefer them to be in-line so a reader does not have to jump around to follow them, but if those examples need to be in an appendix that is better than not having any or having a link to someplace that might eventually 404.

My biggest pet peeve about specs in general is that they do not include examples which make most specs all-but-inaccessible to those like me who need examples to understand the prose.

P.S. Moving to the learn site only works IMO if there is a guarantee that the learn site will never change those examples nor take them down which, I believe, is impossible to guarantee. FTW.

[ralfhandl]

Relative vs. absolute $self doesn't seem to make much of a difference.

• A relative $ref is now relative to the retrieval URL. Making it relative to a relative $self which is itself relative to the retrieval URL only adds the convenience of making the $ref value shorter. It does not add a feature.

• A relative $ref that is relative to an absolute $self also only adds the convenience of making the $ref value shorter (and relative instead of absolute). It does not add a feature.

Seems the only feature added by $self is an in-document identifier for an OpenAPI description, and that feature seems to benefit from an absolute URI value.

What am I missing?

[mikekistler]

I think there may be some errors in the examples of URI resolution in Appendix G. I pointed out two and I think the rest should probably be checked for accuracy before we merge this.

[mikekistler]

This did not look right to me, but I am far from an expert on URI resolution, so I had GitHub Copilot create a Jupyter notebook to implement the URI resolution logic in RFC 3986 Section 5.2. According to this program, the target URI is actually "https://example.com/api/shared#/components/requestBodies/Foo".

Here's a link to the code if you want to have a look.

https://github.com/mikekistler/UriResolution

The notebook includes 42 tests that it extracted from the RFC and these all pass, I have some confidence that it is working correctly.

[mikekistler]

This too does not jive with the resolver that Copilot built. It says that the target URI is actually "https://example.com/api/schemas/foo".

[handrews]

@mikekistler should be fixed. Really, "these look wrong" would have been sufficient here. The errors were just because I reworked the various paths at some point to make the examles cover more cases, and some things didn't get updated post-rework. Nothing obscure was going on.

Although it sounds like you produced something useful beyond this which is cool!