Updated use of URL to URI #76
Conversation
Co-authored-by: Henry Andrews <[email protected]>
|
Committed @handrews' suggestion |
There was a problem hiding this comment.
The changes here seem fine, though I'm not really sure how they address this concern:
it could lead to users to assume that they can pass an overlay with the extends keyword to tooling that expect to receive an OpenAPI document, because it appears that the Overlay is self contained.
Also I wonder if we need to define the base URI for relative references as we do in OAS.
|
|
||
| Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). | ||
| Unless specified otherwise, relative references are resolved using the URL of the referring document. | ||
| Unless specified otherwise, all fields that are URI references MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). |
There was a problem hiding this comment.
Do we need to say what the Base URI is here? I think we do in the OAS.
There was a problem hiding this comment.
@mikekistler no, because RFC3986 takes care of it, and the Overlay Specification does not define an internal base URI-setting mechanism under RFC3986 §5.1.1. Most of the weird problems regarding base URIs in the OpenAPI Specification are because someone tried to re-write things already covered by RFC3986 and messed it up (e.g. forgetting about §5.1.2, or creating ambiguity around the term "document'), so let's not do that here. Just referencing RFC3986 is sufficient.
This PR attempts to clean up some of the language that was copied from OAS that we have since realized was ambiguous. It also changes the specification to use URI references instead of URLs for the field extends.
The reason for this change is that we want to give the option for tooling to choose whether to treat the URI reference as an identifier or a locator. With the previous wording a tooling author may interpret the specification as saying that the tooling is required to dereference the extends URI reference to acquire the target document. That wouldn't be good, for security reasons and it could lead to users to assume that they can pass an overlay with the extends keyword to tooling that expect to receive an OpenAPI document, because it appears that the Overlay is self contained. (This is similar to how Kubernetes Kustomize overlays can be used https://kubectl.docs.kubernetes.io/guides/config_management/introduction/)
This aligns Overlay's use of URI references with the OAS's use of URI references.