url.spec.whatwg.orgURL Standard

URL Living Standard — Last Updated 25 March 2024 Participate: GitHub whatwg/url ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/url/commits Snapshot as of this commit @urlstandard Tests: web-platform-tests url/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract The defines URLs, domains, IP addresses, the application/x-www-form-urlencoded format, and their API. Table of Contents Goals 1 Infrastructure 1.1 Writing 1.2 Parsers 1.3 Percent-encoded bytes 2 Security considerations 3 Hosts (domains and IP addresses) 3.1 Host representation 3.2 Host miscellaneous 3.3 IDNA 3.4 Host writing 3.5 Host parsing 3.6 Host serializing 3.7 Host equivalence 4 URLs 4.1 URL representation 4.2 URL miscellaneous 4.3 URL writing 4.4 URL parsing 4.5 URL serializing 4.6 URL equivalence 4.7 Origin 4.8 URL rendering 4.8.1 Simplify non-human-readable or irrelevant components 4.8.2 Elision 4.8.3 Internationalization and special characters 5 application/x-www-form-urlencoded 5.1 application/x-www-form-urlencoded parsing 5.2 application/x-www-form-urlencoded serializing 5.3 Hooks 6 API 6.1 URL class 6.2 URLSearchParams class 6.3 URL APIs elsewhere Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References Informative References IDL Index 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 or returns the empty string. [UTS46] If details about Unicode ToASCII errors are recorded, user agents are encouraged to pass those along. Yes domain-to-Unicode Unicode ToUnicode records an error. [UTS46] The same considerations as with domain-to-ASCII apply. · Host parsing domain-invalid-code-point The input’s host contains a forbidden domain code point . 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 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-many-parts An IPv4 address does not consist of exactly 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) 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 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:user@example.org" ); 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://user@example.org " " ssh://user@example.org " · 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:...