search

OAI / sig-moonwalk

Version 4.x of the OpenAPI Specification is known as "Moonwalk," and has a goal to ship in 2024.
https://www.openapis.org/blog/2023/12/06/openapi-moonwalk-2024
Apache License 2.0
266 stars 11 forks source link

Write ADR for identity vs location #92

Open handrews opened 4 months ago

handrews commented 4 months ago

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 commented 4 months ago

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 commented 2 months ago

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:

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.