Skip to content

v3.2: Consider additional guidance around $self usage #4539

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
Open

v3.2: Consider additional guidance around $self usage #4539

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

Comments

@handrews
Copy link
Member

From @karenetheridge in PR #4389

Perhaps we can simplify this by simply strongly recommending that $self is an absolute URI (i.e. fully resolved; resolving it against another base URI is a no-op), and point to the RFC to explain why.

"this" refers to the guidance on how to resolve relative $self values, which walks through the RFC3986§5.1.1-4 options to explain the process, since older OAS versions just mentioned the retrieval URI (§5.1.3) and not the steps in §5.1.2 or §5.1.4.

I would love to just say "resolve per RFC3986" but in my experience that is not sufficient for many people to implement it properlly. However, I would be happy to kick that content over to the learn site if there is consensus to do so, perhaps along with the further $self recommendations that @karenetheridge is suggesting.

I do think that anytihng we can do to streamline the actual specification in favor of moving explanations to the Learn site would be a good thing. I have tended to put more in the spec because historically our spec explains a lot, but I'd support moving in the other direction.

@handrews handrews changed the title v3.2: Consider additional guidance around $self usage` v3.2: Consider additional guidance around $self usage Apr 10, 2025
@handrews handrews added the re-use: ref/id resolution how $ref, operationId, or anything else is resolved label Apr 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
re-use: ref/id resolution how $ref, operationId, or anything else is resolved
Projects
None yet
Development

No branches or pull requests

1 participant