Write ADR for identity vs location

[handrews]

As part of the larger discussion on referencing and imports (#72, #73), @darrelmiller suggested deciding on using IRIs as identifiers rather than locators as a first step. Part of the context is his discussions with his team around the impact of using $ref URLs as strict locators that must be read separately each time, plus the complexity of how to write changes back to such a separately-loaded reference that may be loaded in many different (possibly somehow conflicting) places within the OAD.

[handrews]

This is related to the OASComply reports and I might start by adding a supplementary report there as it has impacts on Moonwalk, OAS 3.x, and OASComply. Then I'll link from an ADR that addresses the Moonwalk-specific concerns.

[handrews]

After much research, I determined that OAS 3.1 already separated identity and location, but did so in an unclear manner. Specifically, the OAS 3.1 Schema Object requires that separation, which de-facto requires it for all URI-based connections within a multi-document OpenAPI Description. This is reflected in calling those URIs "URIs" and discussing them separately from API "URLs", including when it comes to base URIs.

The following PRs clarify this area in 3.1, with the last one in the list proposing a self field for 3.2 to complete the separation and enable bundling, a.k.a. a consumer-optimized format:

• Clarify how Schema Objects require full-document parsing (3.1.1) OpenAPI-Specification#3758
• Clarify entry/complete document terminology (3.1.1 port of #3820) OpenAPI-Specification#3839
• Clarify "URI" and "URL" meaning and usage (3.1.1) OpenAPI-Specification#3838
• Proposal: Bundled streams w/ self-identification OpenAPI-Specification#3875

Assuming the 3.2.0 PR for self goes through, there will be no need for this ADR as we will just be continuing what 3.x does, and we can move on to the mechanism of how it works in Moonwalk.