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

Open
@handrews

Description

@handrews

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    deploymentServers and related deployment configurationre-use: ref/id resolutionhow $ref, operationId, or anything else is resolved

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions