Skip to content
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

Clarify "URI" and "URL" meaning and usage (3.1.1) #3838

Merged
merged 3 commits into from
Jun 6, 2024

Conversation

handrews
Copy link
Member

@handrews handrews commented May 22, 2024

NOTE 1: This is not as long as it looks! After the first block, it's just a word here and a word there to make things consistent throughout the spec.

NOTE 2: This is not at all relevant to 3.0.4

NOTE 3: This does not address links in CommonMark text, which is being discussed in issue #1701

Fixes:

I went through many iterations on this, some of which went into much more detail. In the end I decided to do just a few things:

  • State an overall criteria for URLs vs URIs rather than just mentioning a few fields or trying to include a complete list:
    • API interaction involves URLs (by definition, really)
    • Connecting pieces of the API description involves identifier-not-necessarily-locator URIs (because JSON Schema requires it, and the text mostly uses "URI" including for the Reference Object and operationRef)
  • Make sure all fields with URI behavior are described as URIs and not URLs
  • Add minimal commentary on URI behavior
    • Reference the "Document Parsing" section which mentions configuration options for identifier-base loading
    • Briefly mention key use cases as this can feel like a puzzling or overly-academic requirement
    • It's worth noting that several tools actually allow "faking" the document location already

For those who want the full backstory (everyone else can skip the rest of this)

The most likely point of controversy would be removing "location of" from "identifies the location of the value being referenced" in the Reference Object. The "identifies the location" phrasing was copied over from the (not cited in 3.1) JSON Reference draft, and indicates location-based (URL) behavior. However, the new wording added in 3.1 calls the Reference Object's $ref a URI rather than a URL, and includes the Reference Object in the list in 3.1.0's URI section.

The history of this apparent contradiction is rather muddled:

My take on this is that the general URI/URL split, and the clear presence of the Reference Object in the URI section, means that it has URI behavior, and the "identifies the location" wording is something that never got taken out after that was resolved. So I'm taking it out now, because different parts of the spec treat it differently, and URI seems more consistent with more parts of the spec.

This clarifies that using the APIs involves URLs, while describing
the API involves URIs.  It ensures that all URIs involved in
the API description are called "URIs", and briefly mentions
how using URIs is different from URLs.
@handrews handrews added clarification requests to clarify, but not change, part of the spec re-use: ref/id resolution how $ref, operationId, or anything else is resolved labels May 22, 2024
@handrews handrews requested a review from a team May 22, 2024 02:54
@handrews handrews added this to the v3.1.1 milestone May 22, 2024
versions/3.1.1.md Outdated Show resolved Hide resolved
versions/3.1.1.md Outdated Show resolved Hide resolved
Copy link
Contributor

@ralfhandl ralfhandl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nits

handrews and others added 2 commits May 22, 2024 07:25
It's not entirely clear how these should resolve.
Copy link
Contributor

@lornajane lornajane left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@lornajane lornajane merged commit 5d5669e into OAI:v3.1.1-dev Jun 6, 2024
1 check passed
@handrews handrews deleted the ref-uriurl-311 branch June 10, 2024 19:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification requests to clarify, but not change, part of the spec re-use: ref/id resolution how $ref, operationId, or anything else is resolved
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants