feat: adds support for self in overlay

[baywet]

fixes #310

heavy use of GCC to put this one together. (based on the discussion in the issue, and the arazzo PR as a template)

[handrews]

This is getting quite close! BTW, I have only had time to review the markdown file, I hope someone else can look at the tests and schemas, and just ping me if there are questions you can't resolve.

[handrews]

I'm pretty sure that if there's no $self then whatever the past requirements for extends were would still apply. Presumably that was a "MUST match based on the retrieval URI" or some similar location thing?

I'm guessing that this wording is based on reading this from the OAS:

Implementations MAY support document retrieval, although see the Security Considerations sections for additional guidance.

The MAY there is referring to actually performing an I/O operation to fetch the document. That is optional, and potentially a security issue so it really shouldn't be on by default. But the rest of that paragraph basically says "or you handle this by letting the user tell you what the retrieval URI was."

[baywet]

I re-read your comment, and the paragraph, multiple times to ensure I was understanding things properly here.

I feel this paragraph is actually redundant, the extends behaviour is documented in details for URI retrieval. My suggestion is to remove this entirely.

Essentially here is what we want people to do (in order, read like a truth table):

1. extends, no self, no contextual information => do uri retrievial with extends
2. extends, no self, contextual information => do uri retrieval with extends, then try the contextual information (tool specific)
3. no extends, no self, contextual information => do uri retrivial from the contextual information
4. no extends, no self, no contextual information => fail, there's no way to locate the OAI document
5. extends, self, no contextual information => do uri retrievial with extends, if it's a relative uri, use self to build the uri
6. extends, self, contextual information => do uri retrieval with extends, then try the contextual information (tool specific), if the uri is relative, use self like in 5 to build the uri
7. no extends, self, contextual information => do url retrieval from context information, if the uri is relative, use self like in 5 to build the uri
8. no extends, self, no contextual information => fail, there's no way to locate the OAI document

In any of those cases where uri retrivial is performed, there's a security risk.
In any of those case where self is present, the tool should additionally perform the comparison with the self of the OAD when present. Either with the full URI from extends, or with the resolved uri from overlay self + extends/contextual relative information.

Is that a faire representation? if so, do you think this is captured well enough in the current proposal?

Lastly, cases 1, 2, 3, 4 were already specified by earlier version of the specification. Cases 5, 6, 7, 8 are being added here.