Resolving relative references - improve topic

[hamishwillee]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/URL_API/Resolving_relative_references

What specific section or headline is this issue about?

Whole thing

What information was incorrect, unhelpful, or incomplete?

The information is incomplete in that resolving URLs is more complicated than described in the associated RFC.

What did you expect to see?

@wbamberg Proposed a more comprehensive approach in #33207 (comment). Reproduced below.

I think relative URL resolution is quite an important thing that AFAIK is documented nowhere on MDN. The nearest thing is https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL which doesn't do into enough detail.

It is better to present this as a generic algorithm - "how browsers handle relative URLs" - rather than specifically as a feature of the URL interface. Because it is an algorithm for how browsers handle relative paths in general, and URL is just referring to that.

Second, I like that you have lots of examples and I appreciate explaining it in a fairly informal way. But it would be great if we could also present it in a more rigorous/precise way. The trick is to explain https://datatracker.ietf.org/doc/html/rfc3986.html#section-5.2 in a way that is more comprehensible but just as precise.

I've had a shot at writing this up below, perhaps we could work out some version of this? What do you think?

---

We could present URL resolution as a three-step process:

• split both URLs into their components
• calculate the value of each combined component
• compose the components

Split URLs

First, split base and relative URLs into their components (we already define the components in https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL):

• scheme
• authority
• path
• query
• fragment

Calculate component values

• if relative.scheme exists, components are:

  • relative.scheme, relative.authority, remove_dots(relative.path), relative.query, relative.fragment

• if relative.authority exists, components are:

  • base.scheme, relative.authority, remove_dots(relative.path), relative.query. relative.fragment

• if relative.path is "" and !relative.query, components are:

  • base.scheme, base.authority, base.path, base.query. relative.fragment

• if relative.path is "" and relative.query, components are:

  • base.scheme, base.authority, base.path, relative.query. relative.fragment

• if relative.path starts with "/", components are:

  • base.scheme, base.authority, remove_dots(relative.path), relative.query. relative.fragment

• if relative.path does not start with "/", components are:

  • base.scheme, base.authority, remove_dots(merge(base.path, relative.path)), relative.query. relative.fragment

Merging base and relative paths

• if base has an authority and an empty path, then path is "/" followed by relative.path
• otherwise, remove from base.path all characters after the rightmost "/", (or the whole of base.path if base.path does not contain "/"), then append relative.path

(I'm not sure if we can assume that base must have an authority, and therefore simplify this a bit?)

Remove dots

This is the process of removing "./" characters and processing "../" to remove parents. This is quite hard to explain precisely...

Compose components

Finally we combine the components to produce a single URL:

• if scheme: add scheme + ":"
• if authority: add "//" + authority
• add path
• if query: add "?" + query
• if fragment: add "#" + fragment

Again, can we assume that scheme and authority are required for HTTPS URLs, so as to simplify the explanation?

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

Doing this work makes sense. Doesn't meet my urgent priorities, but is important, and this is to prevent the work getting lost.

[Josh-Cena]

This would be very helpful for the JS module docs too!

[hamishwillee]

@Josh-Cena I bet. Will is taking first shot at it.