Clarify trailing slash ref-resolution weirdness #678
Conversation
| @@ -2051,7 +2057,7 @@ Link: <https://api.example.com/trees/1/nodes/456>; rev="up" | |||
| <![CDATA[{ | |||
| "$id": "https://schema.example.com/thing-collection", | |||
| "$schema": "http://json-schema.org/draft-08/hyper-schema#", | |||
| "base": "https://api.example.com/", | |||
| "base": "https://example.com/api/", | |||
| "type": "object", | |||
| "required": ["elements"], | |||
| "properties": { | |||
There was a problem hiding this comment.
For the other instance of a trailing slash, you added a note stating that it was included intentionally to show its confusing nature. Is this one also intentional?
There was a problem hiding this comment.
That was for the "href": "../api" line, not the base. I'll try to make that more clear.
There was a problem hiding this comment.
@gregsdennis reworked it with more detail, see if that makes sense now.
There was a problem hiding this comment.
So base URIs require trailing slashes so that relative URIs can be resolved against them. Is there any concern about attempting to resolve one relative URI against another?
There was a problem hiding this comment.
this is all RFC 3986 stuff, nothing is required. But OpenAPI and other systems have, very annoyingly, messed up their concept of a base URI so that it is concatenation instead of reference resolution, and if you do that with reference resolution nothing will work right. You can go look at OpenAPI if you want to dig into it.
This is why I hate writing examples. How much of RFC 3986 do I need to explain here? That is not a rhetorical question. Something needs to be explained because popular formats have done it wrong, but I do not want to put a whole URI reference resolution tutorial here. It's an incredibly complicated process if you go into all of it, but in practice it's mostly pretty straightforward except for the slash thing.
There is no way to do RFC 3986 reference resolution that just removes a trailing slash without duplicating things. Every option is confusing and weird, but avoiding trailing slashes is increasingly common. Let's just face that and explain that it's weird and this is the best that can be done.
handrews
force-pushed
the
trailing-slash
branch
from
d7a943b to
960069e
Compare
gregsdennis
added
clarification
Addresses #559 (paging @mokkabonna)
There is no way to do RFC 3986 reference resolution that just
removes a trailing slash without duplicating things. Every
option is confusing and weird, but avoiding trailing slashes
is increasingly common.
Let's just face that and explain that it's weird and this is
the best that can be done.