RFC 8820

URI Design and Ownership

📅 published June 2020, from ietf

RFC 8820: URI Design and Ownership 🎀

Okay bestie, so this is RFC 8820, a Best Current Practice (it's BCP 190, ISSN 2070-1721), published by the IETF in June 2020. The author is M. Nottingham. It obsoletes RFC 7320 and updates RFC 3986 💅 It's all about who gets to decide what a URI looks like inside, and it's giving main character energy ✨

Abstract 🌸

Section 1.1.1 of RFC 3986 calls URI syntax "a federated and extensible naming system wherein each scheme's specification may further restrict the syntax and semantics of identifiers using that scheme." Basically, the scheme is what decides the shape of a URI. It's super common for schemes to hand off the substructure to whoever owns the URI, but publishing standalone standards that force particular substructure onto URIs is often a big problem 😬

This document gives guidance on how standards should specify URI substructure.

This document obsoletes RFC 7320 and updates RFC 3986.

Status of This Memo 📋

This memo documents an Internet Best Current Practice.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to give feedback on it can be found at https://www.rfc-editor.org/info/rfc8820.

Copyright (c) 2020 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents 🦋

1.  Introduction
  1.1.  Intended Audience
  1.2.  Notational Conventions
2.  Best Current Practices for Standardizing Structured URIs
  2.1.  URI Schemes
  2.2.  URI Authorities
  2.3.  URI Paths
  2.4.  URI Queries
  2.5.  URI Fragment Identifiers
3.  Alternatives to Specifying Structure in URIs
4.  Security Considerations
5.  IANA Considerations
6.  References
  6.1.  Normative References
  6.2.  Informative References
Appendix A.  Changes from RFC 7320
Acknowledgments
Author's Address

1. Introduction ✨

URIs [RFC3986] very often include structured application data. That can be artifacts from filesystems (often in the path component) and user information (often in the query component). Sometimes there's even application-specific data in the authority component (e.g., some applications are spread across several hostnames to enable a form of partitioning or dispatch) 🧚

Implementations can add further constraints on the structure of URIs. For example, lots of web servers look at the filename extension of the last path segment to figure out the media type of the response. Prepackaged applications are also often super structured, and their URIs can only be changed in limited ways (usually just the hostname and port they're deployed on) 💅

Because the owner of the URI (as defined in [webarch], Section 2.2.2.1) is choosing to use the server or the application, this can be seen as reasonable delegation of authority. However, when a party other than the owner mandates these conventions, it can have several potentially detrimental effects:

  • Collisions - As more ad hoc conventions for URI structure get standardized, it becomes more likely that they'll collide with each other (especially since servers, applications, and individual deployments will all have their own conventions) 💥
  • Dilution - When the information added to a URI is ephemeral, it waters down the URI's usefulness by reducing its stability (see [webarch], Section 3.5.1), and it can cause several alternate forms of the URI to exist (see [webarch], Section 2.3.1) 🫠
  • Rigidity - Fixed URI syntax often gets in the way of the deployment patterns people actually want. For example, if an authority wants to offer several applications on a single hostname, it becomes difficult to impossible if their URIs don't allow the flexibility that requires 🙅‍♀️
  • Operational Difficulty - Supporting some URI conventions can be hard in some implementations. For example, requiring a particular query parameter on "http" URIs can rule out web servers that serve responses straight from a filesystem. Likewise, an application that fixes a base path for its operation (e.g., "/v1") makes it impossible to deploy other applications with the same prefix on the same host 😩
  • Client Assumptions - When conventions are standardized, some clients will inevitably assume the standards are in use whenever those conventions show up. This can lead to interoperability problems. For example, if a specification says the "sig" URI query parameter indicates that its payload is a cryptographic signature for the URI, it can lead to undesirable behavior 👀

Publishing a standard that constrains an existing URI structure in ways that [RFC3986] doesn't explicitly allow (usually by updating the URI scheme definition) is therefore sometimes problematic. That's both for the reasons above and because the structure of a URI needs to stay firmly under its owner's control 🔒

This document explains some best current practices for establishing URI structures, conventions, and formats in standards. It also offers strategies for specifications in Section 3 🌈

1.1. Intended Audience 🎀

This document's guidelines and requirements are aimed at authors of specifications that constrain the syntax or structure of URIs, or parts of them. Two classes of these specifications are called out specifically:

  • Protocol Extensions ("Extensions") - specifications that offer new capabilities which could apply to any identifier or to a large subset of possible identifiers, e.g., a new signature mechanism for "http" URIs, metadata for any URI, or a new format.
  • Applications Using URIs ("Applications") - specifications that use URIs to meet specific needs, e.g., an HTTP interface to particular information on a host.

Requirements that target the generic class "Specifications" apply to all specifications, including both those listed above and others.

Note that this specification ought not be read as stopping parties that legitimately own URIs, or have been delegated that ownership, from controlling them. For example, a specification might legitimately define the semantics of a URI on IANA's web site as part of setting up a registry 💜

There may be existing IETF specifications that already deviate from the guidance in this document. In these cases, it's up to the relevant communities (i.e., those of the URI scheme as well as any relevant community that produced the specification in question) to decide on an appropriate outcome. For example, they could update the scheme definition or change the specification itself 🧠

1.2. Notational Conventions 📝

The key words are the important part here, so here's the official text, word for word:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Best Current Practices for Standardizing Structured URIs 💖

This section updates [RFC3986] by advising Specifications how they should define structure and semantics within URIs. Best practices differ depending on which URI component you're talking about, as described below 🫶

2.1. URI Schemes 🍓

Applications and Extensions can require one or more specific URI schemes. For example, it's perfectly fine to require that an Application support "http" and "https" URIs. However, Applications ought not block the use of other URI schemes in the future, unless those are clearly only usable with the nominated schemes.

A Specification that defines substructure for URI schemes overall (e.g., a prefix or suffix for URI scheme names) MUST do so by modifying [BCP35] (an exceptional circumstance). Only do this if you really have to, because it's a rare plot twist 😤

2.2. URI Authorities 👑

Scheme definitions set the presence, format, and semantics of an authority component in URIs. All other Specifications MUST NOT constrain or define the structure or the semantics for URI authorities, unless they update the scheme registration itself or the structures it relies on (e.g., DNS name syntax, as defined in Section 3.5 of [RFC1034]). Hands off the hostname, bestie 🙅‍♀️

For example, an Extension or Application cannot say that the "foo" prefix in https://foo_app.example.com is meaningful or triggers special handling in URIs, unless they update either the "http" URI scheme or the DNS hostname syntax 💅

Applications can nominate or constrain the port they use, when applicable. For example, BarApp could run over port nnnn (provided that it is properly registered) 🔌

2.3. URI Paths 🌷

Scheme definitions set the presence, format, and semantics of a path component in URIs, although these are often handed off to the Application(s) in a given deployment.

To avoid collisions, rigidity, and erroneous client assumptions, Specifications MUST NOT define a fixed prefix for their URI paths -- for example, /myapp -- unless the scheme definition allows it. Iconic behavior would be respecting that boundary 🙌

One such exception to this requirement is registered "well-known" URIs, as specified by [RFC8615]. See that document for a description of when that mechanism applies 🧚‍♀️

Note that this doesn't apply to Applications defining a structure for a URI's path "under" a resource controlled by the server. Because the prefix is controlled by the party deploying the Application, collisions and rigidity are avoided, and the risk of erroneous client assumptions goes down 🥰

For example, an Application might define "app_root" as a deployment-controlled URI prefix. Application-defined resources might then be assumed to be present at {app_root}/foo and {app_root}/bar ✨

Extensions MUST NOT define a structure within individual URI components (e.g., a prefix or suffix), again to avoid collisions and erroneous client assumptions. No cap, this one's a hard no 🚫

(Part 1 of 2 — part 2 picks up with Section 2.4 🦋)

2.4. URI Queries ✨

Okay so queries are giving "it depends" 💅. Whether a query exists, what format it takes, and what it means depend on lots of factors, and a scheme definition can constrain them. Usually the resource's own implementation decides 🧚.

Applications can spell out the query syntax for the resources they control 🎀. BUT that can cause operational headaches for deployments that don't support a certain kind of query. Like, a site might want to host an Application using "static" files that don't take query parameters at all 😭.

Extensions MUST NOT constrain the format or semantics of queries, to avoid collisions and wrong client assumptions 🙈. Example: an Extension saying every query parameter named sig means a cryptographic signature would collide with parameters that already exist on sites, and clients would assume any matching parameter is a signature. Absolutely not 💀.

Per the "Form submission" section of [HTML5], HTML constrains the syntax of query strings used in form submission. New form languages are encouraged to allow creating a broader variety of URIs (e.g., by letting the form create new path components, and so forth) 🌈.

2.5. URI Fragment Identifiers 🦋

Section 3.5 of [RFC3986] says fragment identifiers' syntax and semantics depend on the media type of a potentially retrieved resource. So other Specifications MUST NOT define structure within the fragment identifier, unless they're explicitly defining one for reuse by media types in their own definitions (like JSON Pointer [RFC6901] does) 🫶.

An Application that defines common fragment identifiers across media types it doesn't control would cause interoperability problems with handlers for those media types, because the new, non-standard syntax isn't expected there 😤.

3. Alternatives to Specifying Structure in URIs 🧚

Given the issues described in Section 1, the most successful strategy for Applications and Extensions that want to use URIs is to use them the way they were designed: as links exchanged as part of the protocol, rather than statically specified syntax. Several existing specifications can help with this 💖.

  • [RFC8288] specifies relation types for web links. It gives you a framework for linking on the Web, where every link has a relation type, context, and target, so Applications can define a link's semantics and connectivity 🔗.
  • [RFC6570] provides a standard syntax for URI Templates, which can dynamically insert Application-specific variables into a URI. That enables these Applications without impinging on URI owners' control of their URIs ✨.
  • [RFC8615] lets specific paths be "reserved" for standard use on URI schemes that opt into that mechanism ("http" and "https" by default). Heads up, though: this is not a general "escape valve" for Applications that need structured URIs. Check that specification for more info 🙈.

Specifying more elaborate structures to dodge collisions is not an acceptable solution, and it doesn't address the issues described in Section 1. For example, prefixing query parameters with "myapp_" doesn't help, because the prefix itself is subject to the risk of collision (since it isn't "reserved") 💀.

4. Security Considerations 🚨

This document does not introduce new protocol artifacts with security considerations 🫣. What it does is prohibit some practices that might lead to vulnerabilities. For example, if a security-sensitive mechanism is introduced by assuming that a URI path component or query string has a particular meaning, false positives might be encountered (due to sites that already use the chosen string). See also [RFC6943]. Please don't let this one slide, bestie 😭🔥.

5. IANA Considerations 💤

This document has no IANA actions.

6. References 📚

6.1. Normative References

6.2. Informative References

Appendix A. Changes from RFC 7320 🎀

Many of the requirements of RFC 7320 were removed, in the spirit of making this BCP guidance rather than rules. Less gatekeeping, more vibes 🌸.

Acknowledgments 🫶

Thanks to David Booth, Dave Crocker, Tim Bray, Anne van Kesteren, Martin Thomson, Erik Wilde, Dave Thaler, and Barry Leiba for their suggestions and feedback. Iconic squad 👑.

Author's Address 💌

Mark Nottingham

Email: mnot@mnot.net URI: https://www.mnot.net/

📦 where this page comes from