RFC 7595
Guidelines and Registration Procedures for URI Schemes
RFC 7595: Guidelines and Registration Procedures for URI Schemes 🎀
okay bestie, this one is the BCP (Best Current Practice) for URI schemes 💅 Here's the title block tea ☕
- Number: RFC 7595, BCP 35
- Category: Best Current Practice
- Authors: D. Thaler, Ed. (Microsoft), T. Hansen (AT&T Laboratories), and T. Hardie (Google) 👯
- Published: June 2015 by the Internet Engineering Task Force (IETF) 🌸
- ISSN: 2070-1721
- Obsoletes: RFC 4395 🙈 (it replaces that one!)
- Updates: nothing listed in the title block, though the abstract says it updates the guidelines
Abstract
okay so this doc refreshes the rules for URI schemes (the bit at the front of a URI, like http:) 🦋 It also updates how things get registered with IANA, the official keeper of the registries. And yes, it officially replaces RFC 4395 💜
Status of This Memo
This one is a formal Internet Best Current Practice 🎀
It's a product of the Internet Engineering Task Force (IETF), so it represents what the whole IETF community agrees on. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) ✨ If you want more on BCPs, check out Section 2 of RFC 5741.
For the current status, errata, and a place to send feedback, head to http://www.rfc-editor.org/info/rfc7595 🧚
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the publication date. Please actually read those, because they spell out your rights and restrictions for this document 🙏 If you pull Code Components out of this document, they must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. URIs and IRIs . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Requirements for Permanent Scheme Definitions . . . . . . . . 4
3.1. Demonstrable, New, Long-Lived Utility . . . . . . . . . . 4
3.2. Syntactic Compatibility . . . . . . . . . . . . . . . . . 4
3.3. Well Defined . . . . . . . . . . . . . . . . . . . . . . 5
3.4. Definition of Operations . . . . . . . . . . . . . . . . 6
3.5. Context of Use . . . . . . . . . . . . . . . . . . . . . 6
3.6. Internationalization and Character Encoding . . . . . . . 7
3.7. Clear Security and Privacy Considerations . . . . . . . . 7
3.8. Scheme Name Considerations . . . . . . . . . . . . . . . 8
3.9. Interoperability Considerations . . . . . . . . . . . . . 9
4. Guidelines for Provisional URI Scheme Registration . . . . . 9
5. Guidelines for Historical URI Scheme Registration . . . . . . 10
6. Guidelines for Private URI Scheme Use . . . . . . . . . . . . 10
7. URI Scheme Registration Procedure . . . . . . . . . . . . . . 10
7.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.2. Registration Procedures . . . . . . . . . . . . . . . . . 11
7.3. Change Control . . . . . . . . . . . . . . . . . . . . . 13
7.4. URI Scheme Registration Template . . . . . . . . . . . . 13
8. The "example" URI Scheme . . . . . . . . . . . . . . . . . . 14
8.1. "example" URI Scheme Registration Request . . . . . . . . 15
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
10. Security Considerations . . . . . . . . . . . . . . . . . . . 16
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
11.1. Normative References . . . . . . . . . . . . . . . . . . 16
11.2. Informative References . . . . . . . . . . . . . . . . . 17
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18
Contributor . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 191. Introduction ✨
okay so the URI protocol element and its generic syntax are defined by [RFC3986] 🎀 Every URI starts with a scheme name, as defined by Section 3.1 of RFC 3986, and that name points you to a spec for identifiers in that scheme. The URI syntax is a federated, extensible naming system, so each scheme's spec can narrow the syntax further and define what its identifiers actually mean 🧚
This document obsoletes [RFC4395], which had already obsoleted [RFC2717] and [RFC2718] 📚 Lately, people have been saying "URI" for every resource identifier, skipping "URL", and saving "URN" just for URIs that use the "urn" scheme name [RFC2141]. URN "namespaces" [RFC3406] are specific to the "urn" scheme, and this spec doesn't cover them directly.
This doc gives updated guidance for defining new schemes, for anyone defining, registering, or evaluating them. It also updates the process and mechanism for registering schemes in the IANA URI Schemes registry 💅 There's a single namespace for registered schemes, and the registry is meant to:
- provide a central point of discovery for established URI scheme names and easy location of defining documents for schemes;
- discourage multiple separate uses of the same scheme name;
- help those proposing new scheme names to discern established trends and conventions and to avoid names that might be confused with existing ones; and
- encourage registration by setting a low barrier for registration.
1.1. URIs and IRIs 🌈
Originally, URIs only allowed a limited set of characters from US-ASCII. An Internationalized Resource Identifier (IRI), as defined by [RFC3987], extends the URI syntax so it can use a much bigger set of characters and fit identifiers from languages all over the world 🌍 RFC 3987 [RFC3987] also defines a mapping between URIs and IRIs. IRIs use the same scheme names as URIs, so there's no separate registry or registration process for IRI schemes. The URI Schemes registry covers both URIs and IRIs, iykyk 🫶 If you want to describe identifiers that work as IRIs, define the matching URI syntax and note that IRI usage follows the rules and transformations in [RFC3987].
2. Terminology 📖
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] 💜
This doc separates a "scheme specification", which is the document that defines a scheme's syntax and semantics, from a "scheme registration request", which is the filled-in template sent to IANA 🎀 The term "scheme definition" is the generic way to say a scheme's syntax and semantics, and it's usually written down in a scheme specification.
3. Requirements for Permanent Scheme Definitions 👑
This section gives considerations for new schemes. Meeting these guidelines is REQUIRED for 'permanent' scheme registration. 'Permanent' status fits, but isn't limited to, use in standards. For URI schemes defined or normatively referenced by IETF Standards Track documents, 'permanent' registration status is REQUIRED 🔥
[RFC3986] defines the overall syntax for URIs like this:
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]A scheme definition cannot override the overall URI syntax 🙅 For example, fragment identifiers can't be reused outside the generic syntax restrictions, and fragment identifiers aren't scheme specific. A scheme definition must specify the scheme name and the syntax of the scheme-specific part, which is clarified as follows:
URI = scheme ":" scheme-specific-part [ "#" fragment ]
scheme-specific-part = hier-part [ "?" query ]3.1. Demonstrable, New, Long-Lived Utility 💖
Okay, so deploying a new scheme across Internet infrastructure can get expensive, because a lot of URI processing depends on the scheme 😭 A new scheme might need extra software, not just in clients and user agents, but also in parts of the network like gateways, proxies, and caches [W3CWebArch]. Scheme names share one global namespace, so it's smart to avoid fighting over short, catchy names. New schemes ought to be useful to the Internet community beyond what already-registered schemes offer. The scheme specification SHOULD discuss the utility of the scheme being registered ✨
3.2. Syntactic Compatibility 🧚♀️
[RFC3986] defines the generic syntax for all URI schemes, plus the syntax of common URI components that lots of schemes use for hierarchical identifiers. [RFC3987] extended that generic syntax to cover IRIs. All scheme specifications MUST define their own URI <scheme-specific-part> syntax 🫶 Be careful that every string matching your scheme-specific syntax also matches the <absolute-URI> grammar described in [RFC3986].
New schemes SHOULD reuse the common URI components of [RFC3986] when defining hierarchical naming schemes. If there's a strong reason a scheme shouldn't use hierarchical syntax, then the new scheme definition SHOULD follow the syntax of similar previously registered schemes 🦋
Schemes that aren't meant for use with relative URIs SHOULD avoid the forward slash "/" character, so you don't get unintended processing, like resolving "." and ".." (dot segments) 🙈
Schemes SHOULD avoid improper use of "//" 💀 Double slashes aren't a style choice that says "this is a URI." They're intended ONLY when the <scheme-specific-part> syntax has a hierarchical structure. In URIs from such schemes, double slashes mean what follows is the top hierarchical element for a naming authority (Section 3.2 of RFC 3986 has more details). Schemes that don't have a conformant hierarchical structure in their <scheme-specific-part> SHOULD NOT use double slashes after the "<scheme>:" string 🍓
New schemes SHOULD clearly define the role of reserved characters (see Section 2.2 of [RFC3986]) in URIs of the scheme being defined. The syntax should be clear about which characters from the "reserved" set act as delimiters within the new scheme's URIs, and when those characters must be escaped versus when they can be used without escaping 🎀
3.3. Well Defined ✨
okay so URIs might or might not get used as locators in practice, but a scheme definition MUST be crystal clear about how it's supposed to function 🧚 Schemes that aren't meant to be locators SHOULD describe how software that gets a URI of that scheme can figure out or access the resource it identifies 💖
For schemes that do work as locators, the way they locate things needs to be clearly defined 🎀 What that looks like depends on what kind of scheme it is, bestie.
Lots of new schemes are basically translators between some other namespace or protocol and the general URI world ✨ Like, ftp translates into the FTP protocol, and mid translates into a Message-ID for an email message 📧 For these, the description of the mapping SHOULD be complete and detailed enough that it works in both directions 🔄 You need to know how to go from a URI to an identifier, protocol actions, or name in the target namespace, AND how legal values in the base namespace (or legal protocol interactions) get represented in a valid URI. See Section 3.6 for guidelines on encoding strings or sequences of bytes within valid character sequences in a URI 🫶
If not every legal value or protocol interaction of the base standard can be represented with the scheme, the definition SHOULD be clear about which subset is allowed and why 🧐 No mystery subsets allowed, periodt 💅
3.4. Definition of Operations ✨
So part of defining how a URI identifies a resource is listing the operations you can perform on that resource using the URI as its identifier 👑 A scheme definition SHOULD define the applicable set of operations. The model everyone knows is HTTP methods: an HTTP resource can be operated on by GET, POST, PUT, and a bunch of other methods available through the HTTP protocol 🌈 The scheme definition SHOULD describe all well-defined operations on the resource identifier and what each one is supposed to do 📝
Some schemes don't fit the "information access" vibe of URIs at all 🙈 Like, telnet gives you location info for starting a bidirectional data stream to a remote host, and the only operation defined is to initiate the connection 🔌 Either way, the operations appropriate for a scheme SHOULD be documented ✨
Note: It is perfectly valid to say that "no operation apart from GET is defined for this URI." It is also valid to say that "there's only one operation defined for this URI, and it's not very GET-like." The important point is that what is defined on this scheme is described. 💜
Scheme definitions SHOULD define a "default" operation for when a URI is invoked (or "dereferenced") by an application 🚀 A common "default" operation today is to launch an application associated with the scheme name and let it use the other URI components as inputs to do something. The default invocation, or dereferencing, of a URI SHOULD be "safe" in the sense described by Section 3.4 of [W3CWebArch], i.e., performing such an invocation should not incur any additional obligations by doing so 🛡️ No surprise bills, no surprise commitments, just vibes 🌸
3.5. Context of Use ✨
In general, URIs get used across a really broad range of protocols and applications 🌍 For example, they're commonly used inside hypertext documents as references to other resources 📄 Sometimes, though, a scheme is meant for a different, specific set of protocols or applications 🎯 If so, the scheme definition SHOULD describe the intended use and include references to the documentation that defines the applications and/or protocols cited 📚 This doesn't get the applications and protocols off the hook, either. They still need documentation that discusses the URI schemes relevant to them 🦋
3.6. Internationalization and Character Encoding ✨
When you describe schemes where (some of) the elements of the URI are actually representations of human-readable text, care should be taken not to introduce unnecessary variety in the ways characters get encoded into octets and then into URI characters 🌏 Check out [RFC3987] and Section 2.5 (especially the last paragraph) of [RFC3986] for guidelines 🤓 If URIs of a scheme contain any text fields, the scheme definition MUST describe the ways in which characters are encoded and any compatibility issues with IRIs of the scheme 💅
The scheme specification SHOULD be as restrictive as possible about which characters are allowed in the URI 🔒 Some characters can create several different security issues (see, for example, [RFC4690]), so lock it down, bestie 🫶
Percent-encoded character sequences are automatically included by definition for characters given in IRI productions 🧩 This means that if you want to restrict the URI percent-encoded forms in some way, you must restrict the Unicode forms that would lead to them. In most cases, it's advisable to define the actual characters allowed in an IRI production so that the 'pct-encoded' definition from Section 2.1 of [RFC3986] is allowed at the same places, and to add prose that limits percent escapes to those that can be created by converting valid UTF-8 character sequences to percent-encoding 🎀
3.7. Clear Security and Privacy Considerations ✨
Definitions of schemes MUST be accompanied by a clear analysis of the security and privacy implications for systems that use the scheme 🔐 This follows the practice of Security Consideration sections within IANA registrations [RFC5226], so it's not a new vibe, just a consistent one 💖
In particular, Section 7 of RFC 3986 [RFC3986] describes general security considerations for URIs, while [RFC3987] gives those for IRIs 🧠 The definition of an individual scheme should note which of these apply to the specified scheme, plus any more scheme-specific concerns. For example, if the scheme-specific part is privacy sensitive, then that should be documented 🙈 Spill nothing, bestie 🤫
3.8. Scheme Name Considerations ✨
Section 3.1 of RFC 3986 defines the syntax of a URI scheme name, and this syntax stays the same for IRIs 🏷️ New scheme registrations MUST follow this syntax, which only allows a limited repertoire of characters (taken from US-ASCII) 🔤 Although the syntax for the scheme name in URIs is case insensitive, the scheme name itself MUST be registered using lowercase letters 🔡
Scheme names SHOULD be short but also sufficiently descriptive and distinguished so they don't cause problems 🍓
Schemes SHOULD NOT use names or other symbols that might cause problems with rights to use the name in IETF specifications and Internet protocols 🙅♀️ For example, be careful with trademark and service mark names (see Section 3.4 of [RFC5378]). Not your brand, not your name, babe 💅
Schemes SHOULD NOT use names that are either very general purpose or associated in the community with some other application or protocol 🫠 Schemes also SHOULD NOT use names that are overly general or grandiose in scope (e.g., names that allude to their "universal" or "standard" nature). Main character energy is great, but not THAT much 😭
A scheme name is not a "protocol" 🦋 However, like a service name as defined in Section 5 of [RFC6335], it often identifies a particular protocol or application. If a scheme name has a one-to-one correspondence with a service name, then the names SHOULD be the same 👑
Some organizations want their own namespace for URI scheme names for private use (see Section 6) 🔐 When they do that, it's important to prevent collisions and to make it possible to identify the owner of a private-use scheme. To get both of those, such organizations SHOULD use a prefix based on their domain name, expressed in reverse order. For example, a URI scheme name of com.example.mything might be used by the organization that owns the example.com domain name 🎀 Care must be taken, though, if the organization later loses the domain name embedded in their scheme names, since domain name registrations are not permanent 😬 To associate the private-use scheme name with the original organization, the private-use scheme can be registered using the registration procedure in Section 7 🧚
Furthermore, to prevent collisions with private-use scheme names, new scheme names registered MUST NOT contain a "." unless they're actually constructed from a reversed domain name 🚫 Dots are for domains, not for vibes 🌈
3.9. Interoperability Considerations ✨
If the person or group registering the scheme is aware of any details that might impact interoperability, identify them 🤝 For example, that could be proprietary or uncommon encoding methods, or incompatibility with types or versions of any underlying protocol 🧩 Spill the tea early, so everyone can get along 🫶
4. Guidelines for Provisional URI Scheme Registration ✨
'Provisional' registration can be used for schemes that aren't part of any standard but that are intended for use (or observed to be in use) beyond a private environment within a single organization 🌸 It can also be used as an intermediate step on the way to 'permanent' registration, e.g., before the scheme specification is finalized as a standard 🦋
For a 'provisional' registration, the following apply:
- The scheme name must meet the syntactic requirements of Section 3.8. 🏷️
- There must not already be an entry with the same scheme name. In the unfortunate case that there are multiple, different uses of the same scheme name, the Designated Expert can approve a request to modify an existing entry to note the separate use 🙃
- Contact information identifying the person supplying the registration must be included. Previously unregistered schemes discovered in use can be registered by third parties (even if not on behalf of those who created the scheme). In this case, both the registering party and the scheme creator SHOULD be identified 🫶
- If no permanent, citable specification for the scheme definition is included, credible reasons for not providing it SHOULD be given 📚
- The scheme definition SHOULD include clear security considerations (Section 3.7) or explain why a full security analysis is not available (e.g., in a third-party scheme registration) 🔐
- If the scheme definition does not meet the guidelines laid out in Section 3, the differences and reasons SHOULD be noted 📝
5. Guidelines for Historical URI Scheme Registration ✨
Sometimes it's appropriate to note a scheme that was once in use or registered but, for whatever reason, is no longer in common use or whose use is not recommended 🕰️ In this case, an individual can request that the URI scheme be registered (newly, or as an update to an existing registration) as 'historical' 📜 Any scheme that is no longer in common use MAY be designated as 'historical', and the registration SHOULD contain some indication of where the scheme was previously defined or documented 🦕 Receipts, bestie 🧾
6. Guidelines for Private URI Scheme Use ✨
Unregistered schemes can cause problems if their use isn't limited to a private environment within a single organization, since the use could leak out beyond the closed environment 🫣 Even within a closed environment, other colliding uses of the same scheme name could happen 😬 So a unique namespace MUST be used, and 'provisional' registration is strongly encouraged (unless the scheme name is constructed from a domain name), as discussed in Section 3.8 🎀
7. URI Scheme Registration Procedure ✨
7.1. General 💅
Okay so the IANA policy (using terms defined in [RFC5226]) for 'provisional' registrations used to be Expert Review, but this doc flips it to First Come First Served 🎀. 'permanent' and 'historical' registrations stay on Expert Review.
The registration procedure is supposed to be super lightweight for the noncontentious stuff 🫶. We're mostly trusting submitters and reviewers to have good sense, guided by these steps, so the community can land on something useful and acceptable.
If the negotiating parties genuinely can't reach consensus in an exceptional case, the IESG is the final arbiter of any contested registration 👑.
If standardization is on the horizon, the working group or individuals involved are advised to submit an early 'permanent' registration request, instead of waiting until standardization has finished its whole run ✨. IANA passes it to the Designated Expert, who may recommend 'provisional' registration until the specification is approved as a standard. That gives everyone a chance to give feedback while the spec is still being developed and reviewed, and while the submitters can still respond to issues 🧚. Once the specification is approved as a standard, the submitters should submit a request to change the registration status to 'permanent' 🦋.
The Designated Expert's job for 'permanent' registrations is to make sure the normal open review process was properly followed, and to raise possible concerns about the wider implications of proposals for how URIs get used and deployed 🔍. Nothing in the procedure lets the Designated Expert override properly arrived-at IETF or working group consensus, so no drama there 🙅♀️.
7.2. Registration Procedures 📝
Someone wishing to register a new scheme MUST:
- Check the IANA "Uniform Resource Identifier (URI) Schemes" registry to see whether there's already an entry for the name you want. If there is, pick a different scheme name or update the existing scheme specification, no cap 🙅♀️.
- Prepare a scheme registration request using the template specified in Section 7.4. The request can live in an Internet-Draft, be submitted alone, or be part of some other permanently available, stable protocol specification 💖. It can also be submitted in some other form (as part of another document or as a stand-alone document), but it'll be treated as an "IETF Contribution" under the guidelines of [RFC5378] 📜.
- If the registration request is for a 'permanent' registration (or, optionally, for any other registration if you want):
- Review the requirements in Section 3.
- Send a copy of the scheme registration request, or a pointer to the document containing it (with a specific reference to the section that requests the scheme registration), to the mailing list
uri-review@ietf.organd request review 📬. You can also request review on other relevant mailing lists as appropriate. For example, general discussion of URI syntax can happen onuri@w3.org, and schemes for a network protocol can be discussed on a mailing list for that protocol 🌈. Allow a reasonable time for discussion and comments. Four weeks is reasonable for a 'permanent' registration request ⏳. - Respond to review comments and make revisions to the proposal as needed to bring it into line with the guidelines in this document 🎀.
- Submit the (possibly updated) scheme registration request, or the pointer to the document containing it, to IANA at
iana@iana.org🚀.
Upon receipt of a scheme registration request, the following steps MUST be followed:
- IANA checks the submission for completeness. If required sections of the request are missing or any citations are not correct, IANA will reject it 🥲. You can resubmit a corrected request if you want.
- If the request is for 'provisional' registration and no entry already exists in the current registry for the same name, IANA adds it to the registry under the First Come First Served policy 🌸.
- Otherwise, IANA enters the request in the IANA registry with the status marked as "Pending Review", and the rest of this section applies 👀.
- IANA requests Expert Review of the request against the corresponding guidelines from this document 🔎.
- The Designated Expert evaluates the request against the criteria of the requested status 🧐.
- For a 'permanent' registration request, the Designated Expert may:
- Accept the specification of the scheme for 'permanent' registration.
- Suggest 'provisional' registration instead.
- Request IETF review and IESG approval; in the meantime, suggest 'provisional' registration.
- Request additional review or discussion as necessary.
- If an entry already exists for the same name, the Designated Expert decides whether the request should be rejected or whether the existing entry should be modified to note the separate use. This conflict process applies regardless of the requested status or the status of the existing entry ⚔️.
- Once the Designated Expert approves registration for a given status, IANA updates the registration to show the approved status ✅. If the Designated Expert rejects the registration instead, the "Pending Review" request is removed from the registry 💀.
Either based on an explicit request or independently initiated, the Designated Expert or the IESG can request the upgrade of a 'provisional' registration to a 'permanent' one 🦋. In those cases, IANA updates the status of the corresponding entry. Typically this would only happen if the use is considered a standard (not necessarily an IETF standard) 🌟.
7.3. Change Control 🛠️
Registrations can be updated in the registry through the same mechanism that's required for an initial registration 🔄. If the original definition of the scheme is in an IESG-approved document, updating the specification also requires IESG approval 👑.
'Provisional' registrations can be updated by the original registrant or by anyone the original registrant designates 🫶. The IESG can also reassign responsibility for a 'provisional' registration scheme, or request specific changes to a scheme registration. This makes it possible to change schemes where the original registrant is out of contact, or unwilling or unable to make changes 🧚.
Transition from 'provisional' to 'permanent' status can be requested and approved in the same way as a new 'permanent' registration ✨. Transition from 'permanent' to 'historical' status requires IESG approval. Transition from 'provisional' to 'historical' can be requested by anyone authorized to update the 'provisional' registration 🌸.
7.4. URI Scheme Registration Template 📋
This template describes the fields that MUST be supplied in a scheme registration request suitable for adding to the registry 💖:
Scheme name:
See Section 3.8 for guidelines.
Status:
This reflects the status requested and must be one of 'Permanent',
'Provisional', or 'Historical'.
Applications/protocols that use this scheme name:
See Section 3.5.
Contact:
Person (including contact information) to contact for further
information.
Change controller:
Organization or person (often the author), including contact
information, authorized to change this.
References:
Include full citations for all referenced documents. Scheme
registration requests for 'provisional' registration can be
included in an Internet-Draft; when the documents expire or are
approved for publication as an RFC, the registration will be
updated. A scheme specification is only required for 'permanent'
registration.The previous version of this specification required the following additional fields in a scheme registration request. Those fields are no longer part of the template, and the answers now belong in the scheme specification instead 🙈.
Scheme syntax:
See Section 3.2 for guidelines.
Scheme semantics:
See Section 3.3 and Section 3.4 for guidelines.
Encoding considerations:
See Section 3.3 and Section 3.6 for guidelines.
Interoperability considerations:
See Section 3.9 for guidelines.
Security considerations:
See Section 3.7 for guidelines.8. The "example" URI Scheme ✨
There's a real need for a scheme name that can be used in documentation examples without fear of clashing with current or future actual schemes 🧸. So the scheme "example" is hereby registered as a 'permanent' scheme for exactly that purpose 🎀.
Here's how the "example" scheme works:
Scheme syntax: The entire range of allowable syntax specified in [RFC3986] is allowed for "example" URIs. Similarly, the entire range of allowable syntax specified in [RFC3987] is allowed for "example" IRIs. For example, <example:foo>, <example:/foo>, and <example://foo> are all valid 🌈.
Scheme semantics: URIs in the "example" scheme are for documentation purposes only 📚. The use of "example" URIs must not be used as locators, identify any resources, or specify any particular set of operations 🙅♀️.
Encoding considerations: See Section 2.5 of [RFC3986] for guidelines 🔤.
Interoperability considerations: None.
Security considerations: None.
8.1. "example" URI Scheme Registration Request 🦋
Here's the registration request for the "example" scheme, which is the registry entry you'd expect to see 💅:
Scheme name: example
Status: permanent
Applications/protocols that use this scheme name: An "example" URI
is to be used for documentation purposes only. It MUST NOT be used
for any protocol.
Contact: N/A
Change controller: IETF
References: Section 8 of this document (RFC 7595).9. IANA Considerations 🏷️
Previously, the former "URL Scheme" registry was replaced by the "Uniform Resource Identifier (URI) Schemes" registry 🔁. That process was based on "Expert Review" [RFC5226], with an initial (optional) mailing list review.
The updated template has an additional field for the status of the scheme, and the procedures for entering new scheme names have been beefed up 💪. Section 7 is where the process for new scheme registration now lives.
IANA has done the following:
- Updated the URI Schemes registry to point to this document 📌.
- Combined the "Permanent URI Schemes", "Provisional URI Schemes", and "Historical URI Schemes" subregistries into a single common registry. It has an additional "Status" column containing the status ('Permanent', 'Provisional', 'Historical', or 'Pending Review'), and an additional "Notes" column that is normally empty but may contain notes approved by the Designated Expert 🗂️.
- Added the "example" URI scheme to the registry (see the template in Section 8.1 for registration) 🧚.
10. Security Considerations 🔐
okay bestie, this part is serious, so we're keeping the drama and the facts 💅 Every registered value is expected to come with clear security considerations, as covered in Section 3.7. But here's the tea: a protocol's security holes can be discovered later, so a scheme's security claims can change too 😭 When a new vulnerability shows up, that info might need to be attached to the existing docs so people don't get misled about how safe a registered scheme really is. Nobody wants to be lied to about their own security 🙈
Acknowledgements 🫶
Thanks to Mark Nottingham and Graham Klyne, and the other lovely people on the apps-discuss@ietf.org mailing list, for their comments on this document 💜
Huge thanks to Patrik Faltstrom, Paul Hoffmann, Ira McDonald, Roy Fielding, Stu Weibel, Tony Hammond, Charles Lindsey, Mark Baker, and everyone else on the uri@w3.org mailing list for their feedback on the earlier drafts 🌸 You all are literally the reason this doc is so solid ✨
Parts of this document are based on [RFC2717], [RFC2718] and [RFC3864]. Some of the ideas about using URIs came from the "Architecture of the World Wide Web" [W3CWebArch], which is giving foundational energy 🧚
Contributor 🎀
Larry Masinter was an author of the document this work is derived from, and he stayed on as author of this version all the way through the working group and IESG evaluation period. His many contributions are gratefully acknowledged, and he is an absolute icon 👑
Authors' Addresses 💌
Dave Thaler (editor)
Microsoft
One Microsoft Way
Redmond, WA 98052
United States
Phone: +1 425 703 8835
EMail: dthaler@microsoft.com
Tony Hansen
AT&T Laboratories
200 Laurel Ave.
Middletown, NJ 07748
United States
EMail: tony+urireg@maillennium.att.com
Ted Hardie
Google
Phone: +1 408 628 5864
EMail: ted.ietf@gmail.com11. References 📚
11.1. Normative References
These are the must-read references, the ones this document depends on to work 🦋
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC2141] Moats, R., "URN Syntax", RFC 2141, DOI 10.17487/RFC2141,
May 1997, <http://www.rfc-editor.org/info/rfc2141>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5378] Bradner, S., Ed. and J. Contreras, Ed., "Rights
Contributors Provide to the IETF Trust", BCP 78, RFC 5378,
DOI 10.17487/RFC5378, November 2008,
<http://www.rfc-editor.org/info/rfc5378>.
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
Cheshire, "Internet Assigned Numbers Authority (IANA)
Procedures for the Management of the Service Name and
Transport Protocol Port Number Registry", BCP 165,
RFC 6335, DOI 10.17487/RFC6335, August 2011,
<http://www.rfc-editor.org/info/rfc6335>.11.2. Informative References
These are the bonus reads for the curious, not required to get the spec 🌈
[RFC2717] Petke, R. and I. King, "Registration Procedures for URL
Scheme Names", RFC 2717, DOI 10.17487/RFC2717, November
1999, <http://www.rfc-editor.org/info/rfc2717>.
[RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke,
"Guidelines for new URL Schemes", RFC 2718,
DOI 10.17487/RFC2718, November 1999,
<http://www.rfc-editor.org/info/rfc2718>.
[RFC3406] Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom,
"Uniform Resource Names (URN) Namespace Definition
Mechanisms", BCP 66, RFC 3406, DOI 10.17487/RFC3406,
October 2002, <http://www.rfc-editor.org/info/rfc3406>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864,
DOI 10.17487/RFC3864, September 2004,
<http://www.rfc-editor.org/info/rfc3864>.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
January 2005, <http://www.rfc-editor.org/info/rfc3987>.
[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
Registration Procedures for New URI Schemes", RFC 4395,
DOI 10.17487/RFC4395, February 2006,
<http://www.rfc-editor.org/info/rfc4395>.
[RFC4690] Klensin, J., Faltstrom, P., Karp, C., and IAB, "Review and
Recommendations for Internationalized Domain Names
(IDNs)", RFC 4690, DOI 10.17487/RFC4690, September 2006,
<http://www.rfc-editor.org/info/rfc4690>.
[W3CWebArch]
W3C Technical Architecture Group, "Architecture of the
World Wide Web, Volume One", W3C Recommendation, December
2004, <http://www.w3.org/TR/webarch/>.📦 where this page comes from
- ietf: rfc7595 2015-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms