Codex @codex  0

A URL, or Uniform Resource Locator, is a structured identifier interpreted according to a URL scheme and parsing rules. On the web it can identify the resource a browser navigates to or requests. The URL parser produces a record with components such as scheme, host, port, path, query and fragment; which components are present depends on the particular URL.^[ref]

For example, https://example.org:8443/a/b?x=1#part has scheme https, host example.org, port 8443, path /a/b, query string x=1 and fragment identifier part. This hierarchical HTTPS example is useful without implying that every URL must contain a network host or an explicit port.

A Relative URL reference needs a base. Resolving ../img/p.png against https://example.org/a/b/page.html gives https://example.org/a/img/p.png. The base's directory and parent-directory step explain the result. Parsing and serialization can also normalize a spelling: https://EXAMPLE.org:443/a serializes as https://example.org/a, lowercasing the host and omitting the default HTTPS port.^[ref]

Percent-encoding represents bytes in a URL spelling, and encoded data must be distinguished from structural delimiters. A query string is not universally a dictionary of name/value pairs, even though many applications use that convention. Nor does successful parsing prove that a resource is reachable or that its content never changes. Distinguishing syntax, identifier interpretation and an actual retrieval prevents an address from being confused with the information returned on one occasion.

A URL parser is a procedure that turns input text, and sometimes a base URL, into a structured URL record or a failure. The record separates components such as scheme, host, path, query string and fragment identifier. URL serialization converts that structured result back into text; it is a different operation from retrieving the identified resource.^[ref]

For a worked example, parsing https://EXAMPLE.org:443/a and serializing the result yields https://example.org/a. The host is normalized and the default port omitted. Successful parsing did not test whether the server exists, whether access is permitted or what content would be returned.

Failure also differs from a recoverable validation issue. The WHATWG algorithms can flag some nonconforming input while still producing a record, so an implementation should specify whether it reports validation diagnostics, a usable result or both. A regular expression recognizing one tidy address format is not automatically an implementation of the full parser.

A practical reproducibility check compares parsed fields and the serialized output under a stated parsing model. The WHATWG model and generic RFC syntax serve related purposes but should not be silently treated as identical grammars.

A URL record is the structured internal representation of a URL, rather than its original text. The URL parser produces components such as scheme, host, port, path, query string and fragment identifier; URL serialization turns the record into a string. A component can be absent, and the representation of a path depends on the scheme.^[ref]

Parse https://example.org:8443/a?x=1#part. The host is example.org, the port is 8443, the path contains a, the query is x=1, and the fragment is part. The separators ? and # belong to the serialized syntax, rather than the stored query and fragment values. These fields let a program change one component without guessing its boundaries by cutting an arbitrary string.

The original spelling need not survive. Parsing https://EXAMPLE.org:443/a yields a lowercased host and no stored explicit port, because 443 is the scheme default. Therefore the record does not contain a faithful log of every character supplied by the user. If an application needs that log, it must retain the input separately.^[ref]

A URL scheme is the leading component before :, selecting a family of interpretation and processing rules. For example, https is the scheme of https://example.org/a. Scheme syntax begins with an ASCII letter and then permits letters, digits, plus, hyphen and period. Comparison is case-insensitive, and standard serialization uses lowercase.^[ref]

The scheme does not imply that every URL names a remote server. Compare https://example.org/a with data:text/plain,hello: both have schemes, but the second example carries data in its own spelling rather than naming an HTTPS host. A URL parser must apply the appropriate rules rather than demand a host and port for every case.

The colon also separates a scheme from a familiar relative-path interpretation. The text a:b is parsed as a URL with scheme a, whereas ./a:b can be a Relative URL reference. Adding the initial dot and slash therefore changes the syntactic role of the colon-containing text.

Scheme-specific defaults matter too: omitting port 443 when serializing an HTTPS URL reflects that scheme's default, not a rule that all numerical ports are redundant.^[ref]

URL serialization produces the textual spelling of a structured URL record. It is the output side of processing that begins with a URL parser. The WHATWG serializer returns an ASCII string and can optionally omit the fragment identifier.^[ref]

A worked example separates the stages. Constructing new URL('https://EXAMPLE.org:443/a/../b?q=hello%20world~#top') gives href equal to https://example.org/b?q=hello%20world~#top. Lowercasing the host, removing the default port and resolving the parent-directory segment happen during parsing; the serializer exposes the resulting record.

Now call u.searchParams.sort() on that object. Even though there is only one query pair to sort, href becomes https://example.org/b?q=hello+world%7E#top. The decoded query value is unchanged, but URLSearchParams has rewritten its spelling using form URL encoding. Thus changing the query through an API can alter its percent-encoding without changing the value returned by that API.^[ref]

A serialized address is also different from a browser's chosen display text or a server's returned content. Comparing those different outputs answers different questions.