Skip to content

v3.2: Consider moving guidance on supplying a retrieval URL (and other parts of the spec that justify various features) to the Learn site #4540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
handrews opened this issue Apr 10, 2025 · 0 comments
Labels
deployment Servers and related deployment configuration re-use: ref/id resolution how $ref, operationId, or anything else is resolved

Comments

@handrews
Copy link
Member

From @notEthan in PR #4389:

I think this goes somewhat into the weeds of circumstances when an implementation might need to be told the retrieval URI. But it seems to me that if there is an intended retrieval URI, well, the implementation always needs to be told that. If the implementation is itself retrieving the document from that URI, it must be given that URI for actual retrieval. If the implementation isn't doing the retrieval or is retrieving from a different URI, whatever the reason, it must be given the nominal retrieval URI to use for resolution. Network configuration, test environment, etc are relevant considerations for retrieval, but regardless how those are set up, the base URI has to be given.

Where "this" means the list of use cases for accepting a user-supplied base URI.

The reason that list is present is that, over the past ten years of dealing with this issue for both JSON Schema and OAS, there is tremendous pushback and lack of understanding if the requirement is given without justification.

We could move all such justification to the Learn site, but for now it is in the spec so that implementors understand why they are being asked to support this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
deployment Servers and related deployment configuration re-use: ref/id resolution how $ref, operationId, or anything else is resolved
Projects
None yet
Development

No branches or pull requests

1 participant