-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Description
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.