URL Standard URL Living Standard — Last Updated 18 August 2026 Participate: GitHub whatwg/url (new issue, open issues) Chat on Matrix Commits: GitHub whatwg/url/commits Snapshot as of this commit Tests: web-platform-tests url/ (ongoing work) Translations (non-normative): 日本語 简体中文 한국어 Abstract The URL Standard defines URLs, domains, IP addresses, the application/x-www-form-urlencoded format, and their API. Goals The URL standard takes the following approach towards making URLs fully interoperable: Align RFC 3986 and RFC 3987 with contemporary implementations and obsolete the RFCs in the process. (E.g., spaces, other "illegal" code points, query encoding, equality, canonicalization, are all concepts not entirely shared, or defined.) URL parsing needs to become as solid as HTML parsing. [RFC3986] [RFC3987] Standardize on the term URL. URI and IRI are just confusing. In practice a single algorithm is used for both so keeping them distinct is not helping anyone. URL also easily wins the search result popularity contest. Supplanting Origin of a URI [sic]. [RFC6454] Define URL’s existing JavaScript API in full detail and add enhancements to make it easier to work with. Add a new URL object as well for URL manipulation without usage of HTML elements. (Useful for JavaScript worker environments.) Ensure the combination of parser, serializer, and API guarantee idempotence. For example, a non-failure result of a parse-then-serialize operation will not change with any further parse-then-serialize operations applied to it. Similarly, manipulating a non-failure result through the API will not change from applying any number of serialize-then-parse operations to it. As the editors learn more about the subject matter the goals might increase in scope somewhat. 1. Infrastructure This specification depends on Infra. [INFRA] Some terms used in this specification are defined in the following standards and specifications: Encoding [ENCODING] File API [FILEAPI] HTML [HTML] Unicode IDNA Compatibility Processing [UTS46] Web IDL [WEBIDL] To serialize an integer, represent it as the shortest possible decimal number. 1.1. Writing A validation error indicates a mismatch between input and valid input. User agents, especially conformance checkers, are encouraged to report them somewhere. A validation error does not mean that the parser terminates. Termination of a parser is always stated explicitly, e.g., through a return statement. It is useful to signal validation errors as error-handling can be non-intuitive, legacy user agents might not implement correct error-handling, and the intent of what is written might be unclear to other developers. Error type Error description Failure IDNA domain-to-ASCII Unicode ToASCII records an error when CheckHyphens, UseSTD3ASCIIRules, and VerifyDnsLength are all set to true. [UTS46] If details about Unicode ToASCII errors are recorded, user agents are encouraged to pass those along. Hosts are percent-decoded before being processed when the URL is special, which would result in the following host portion becoming "exa#mple.org" and thus triggering this error. "https://exa%23mple.org" Yes (when beStrict is true, or domain is not an ASCII string and Unicode ToASCII with relaxed parameters also fails) Host parsing domain-percent-encoded The input’s host to be processed as a domain contains a percent-encoded byte. "https://exam%70le.org" · host-invalid-code-point An opaque host (in a URL that is not special) contains a forbidden host code point. "foo://exa[mple.org" Yes IPv4-empty-part An IPv4 address ends with a U+002E (.). "https://127.0.0.1./" · IPv4-too-few-parts An IPv4 address has fewer than 4 parts. "https://1.2.3/" · IPv4-too-many-parts An IPv4 address has more than 4 parts. "https://1.2.3.4.5/" Yes IPv4-non-numeric-part An IPv4 address part is not numeric. "https://test.42" Yes IPv4-non-decimal-part The IPv4 address contains numbers expressed using hexadecimal or octal digits. "https://127.0.0x0.1" · IPv4-out-of-range-part An IPv4 address part exceeds 255. "https://255.255.4000.1" Yes (only if applicable to the last part) IPv4-non-ASCII-input An IPv4 address is derived from a non-ASCII string through IDNA processing. "https://①.②.③.④" · IPv6-unclosed An IPv6 address is missing the closing U+005D (]). "https://[::1" Yes IPv6-invalid-compression An IPv6 address begins with improper compression. "https://[:1]" Yes IPv6-too-many-pieces An IPv6 address contains more than 8 pieces. "https://[1:2:3:4:5:6:7:8:9]" Yes IPv6-multiple-compression An IPv6 address is compressed in more than one spot. "https://[1::1::1]" Yes IPv6-invalid-code-point An IPv6 address contains a code point that is neither an ASCII hex digit nor a U+003A (:). Or it unexpectedly ends. "https://[1:2:3!:4]" "https://[1:2:3:]" Yes IPv6-too-few-pieces An uncompressed IPv6 address contains fewer than 8 pieces. "https://[1:2:3]" Yes IPv6-piece-leading-zero An IPv6 address piece contains a leading U+0030 (0). "https://[::01]" · IPv4-in-IPv6-too-many-pieces An IPv6 address with IPv4 address syntax: the IPv6 address has more than 6 pieces. "https://[1:1:1:1:1:1:1:127.0.0.1]" Yes IPv4-in-IPv6-invalid-code-point An IPv6 address with IPv4 address syntax: An IPv4 part is empty or contains a non-ASCII digit. An IPv4 part contains a leading 0. There are too many IPv4 parts. "https://[ffff::.0.0.1]" "https://[ffff::127.0.xyz.1]" "https://[ffff::127.0xyz]" "https://[ffff::127.00.0.1]" "https://[ffff::127.0.0.1.2]" Yes IPv4-in-IPv6-out-of-range-part An IPv6 address with IPv4 address syntax: an IPv4 part exceeds 255. "https://[ffff::127.0.0.4000]" Yes IPv4-in-IPv6-too-few-parts An IPv6 address with IPv4 address syntax: an IPv4 address contains too few parts. "https://[ffff::127.0.0]" Yes URL parsing invalid-URL-unit A code point is found that is not a URL unit. "https://example.org/>" " https://example.org " "ht tps://example.org" "https://example.org/%s" · special-scheme-missing-following-solidus The input’s scheme is not followed by "//". "file:c:/my-secret-folder" "https:example.org" const url = new URL("https:foo.html", "https://example.org/"); · missing-scheme-non-relative-URL The input is missing a scheme, because it does not begin with an ASCII alpha, and either no base URL was provided or the base URL cannot be used as a base URL because it has an opaque path. Input’s scheme is missing and no base URL is given: const url = new URL("💩"); Input’s scheme is missing, but the base URL has an opaque path. const url = new URL("💩", "mailto:[email protected]"); Yes invalid-reverse-solidus The URL has a special scheme and it uses U+005C (\) instead of U+002F (/). "https://example.org\path\to\file" · invalid-credentials The input includes credentials. "https://[email protected]" "ssh://[email protected]" · host-missing The input has a special scheme, but does not contain a host. "https://#fragment" "https://:443" "https://user:pass@" Yes port-out-of-range The input’s port is too big. "https://example.org:70000" Yes port-invalid The input’s port is invalid. "https://example.org:7z" Yes file-invalid-Windows-drive-letter The input is a relative-URL string that starts with a Windows drive letter and the base URL’s scheme is "file". const url = new URL("/c:/path/to/file", "file:///c:/"); · file-invalid-Windows-drive-letter-host A file: URL’s host is a Windows drive letter. "file://c:" · 1.2. Parsers The EOF code point is a conceptual code point that signifies the end of a string or code point stream. A pointer for a string input is an integer that points to a code point within input. Initially it points to the start of input. If it is −1 it points nowhere. If it is greater than or equal to input’s code point length, it points to the EOF code point. When a pointer is used, c references the code point the pointer points to as long as it does not point nowhere. When the pointer points to nowhere c cannot be used. When a pointer is used, remaining references the code point substring from the pointer + 1 to the end of the string, as long as c is not the EOF code point. When c is the EOF code point remaining cannot be used. If "mailto:username@example" is a string being processed and a pointer points to @, c is U+0040 (@) and remaining is "example". If the empty string is being processed and a pointer points to the start and is then decreased by 1, using c or remaining would be an error. 1.3. Percent-encoded bytes A percent-encoded byte is a string consisting of U+0025 (%) followed by two ASCII hex digits. It is generally a good idea for sequences of percent-encoded bytes to be such that, when percent-decoded and then passed to UTF-8 decode without BOM or fail, they do not end up as failure. How important this is depends on where the percent-encoded bytes are used. E.g., for the host parser not following this advice is fatal, whereas for URL rendering the percent-encoded bytes would not be rendered percent-decoded. To percent-encode a byte byte, return a string consisting of U+0025 (%), followed by two ASCII upper hex digits representing byte. To percent-decode a byte sequence input, run these steps: Using anything but UTF-8 decode without BOM when input contains bytes that are not ASCII bytes might be insecure and is not recommended. Let output be an empty byte sequence. For each byte byte in input: If byte is not 0x25 (%), then append byte to output. Otherwise, if byte is 0x25 (%) and the next two bytes after byte in input are not in the ranges 0x30 (0) to 0x39 (9), 0x41 (A) to 0x46 (F), and 0x61 (a) to 0x66 (f), all inclusive, append byte to output. Otherwise: Let bytePoint be the two bytes after byte in input, decoded, and then interpreted as a hexadecimal number. Append a byte whose value is bytePoint to output. Skip the next two bytes in input. Return output. To percent-decode a scalar value string input: Let bytes be the UTF-8 encoding of input. Return the percent-decoding of bytes. In general, percent-encoding results in a string with more U+0025 (%) code points than the input, and percent-decoding results in a byte sequence with less 0x25 (%) bytes than the input. A percent-encode set is a set of code points. The C0 control percent-encode set is a percent-encode set consisting of C0 controls and all code points greater than U+007E (~). The fragment percent-encode set is a percent-encode set consisting of the C0 control percent-encode set and U+0020 SPACE, U+0022 ("), U+003C (<), U+003E (>), and U+0060 (`). The query percent-encode set is a percent-encode set consisting of the C0 control percent-encode set and U+0020 SPACE, U+0022 ("), U+0023 (#), U+003C (<), and U+003E (>). The query percent-encode set cannot be defined in terms of the fragment percent-encode set due to the omission of U+0060 (`). The special-query percent-encode set is a percent-encode set consisting of the query percent-encode set and U+0027 ('). The path percent-encode set is a percent-encode set consisting of the query percent-encode set and U+003F (?), U+005E (^), U+0060 (`), U+007B ({), and U+007D (}). The userinfo percent-encode set is a percent-encode set consisting of the path percent-encode set and U+002F (/), U+003A (:), U+003B (;), U+003D (=), U+0040 (@), U+005B ([) to U+005D (]), inclusive, and U+007C (|). The component percent-encode set is a percent-encode set consisting of the userinfo percent-encode set and U+0024 ($) to U+0026 (&), inclusive, U+002B (+), and U+002C (,). This is used by HTML for registerProtocolHandler(), and could also be used by other standards to percent-encode data that can then be embedded in a URL’s path, query, or fragment; or in an opaque host. Using it with UTF-8 percent-encode gives identical results to JavaScript’s encodeURIComponent() [sic]. [HTML] [ECMA-262] The application/x-www-form-urlencoded percent-encode set is a percent-encode set consisting of the component percent-encode set and U+0021 (!), U+0027 (') to U+0029 RIGHT PARENTHESIS,…