search

OAI / Overlay-Specification

The OAI Overlay Specification
Apache License 2.0
57 stars 15 forks source link

Updated use of URL to URI #76

Closed darrelmiller closed 1 month ago

darrelmiller commented 1 month ago

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.

ralfhandl commented 1 month ago

Committed @handrews' suggestion