RFC 7320

URI Design and Ownership

📅 published July 2014, from ietf

RFC 7320: URI Design and Ownership 🎀 (Part 1 of 2)

okay bestie, this one is a Best Current Practice (BCP 190) from July 2014 💅 It's by M. Nottingham, and it comes from the IETF. It updates RFC 3986, the big URI syntax spec, and it's been published with ISSN 2070-1721. The whole vibe is about who gets to decide what a URI looks like ✨

Abstract ✨

okay so 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." 🦋 In other words, the scheme decides what a URI's structure looks like. It's super common for a scheme to hand some of that substructure off to the URI's owner, and that's totally fine. But publishing independent standards that force a specific URI substructure is a no-go, bc it basically steals ownership 😭 This doc explains why that's problematic and gives you some better options for standards. 💖

Status of This Memo

This memo is an Internet Best Current Practice 🌸

This doc is a product of the Internet Engineering Task Force (IETF). It reflects the consensus of the IETF community, got public review, and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on BCPs, check Section 2 of RFC 5741 🧚

For the current status of this doc, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7320 💜

Copyright (c) 2014 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're in effect on the date of publication. Please read these carefully, bc they spell out your rights and restrictions for this document. Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Simplified BSD License. ⭐

Table of Contents 🍓

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  1.1.  Intended Audience . . . . . . . . . . . . . . . . . . . .   4
  1.2.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
2.  Best Current Practices for Standardizing Structured URIs  . .   4
  2.1.  URI Schemes . . . . . . . . . . . . . . . . . . . . . . .   5
  2.2.  URI Authorities . . . . . . . . . . . . . . . . . . . . .   5
  2.3.  URI Paths . . . . . . . . . . . . . . . . . . . . . . . .   5
  2.4.  URI Queries . . . . . . . . . . . . . . . . . . . . . . .   6
  2.5.  URI Fragment Identifiers  . . . . . . . . . . . . . . . .   6
3.  Alternatives to Specifying Structure in URIs  . . . . . . . .   7
4.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
  5.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
  5.2.  Informative References  . . . . . . . . . . . . . . . . .   8
Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .   9

1. Introduction ✨

okay so URIs [RFC3986] super often carry structured application data 🧚 That can include stuff from filesystems (usually in the path component) and user info (often in the query component). Sometimes there's even application-specific data in the authority component. For example, some apps are split across several hostnames to get a form of partitioning or dispatch 🦋

Also, an implementation can put constraints on URI structure. Like, lots of Web servers look at the filename extension of the last path segment to figure out the media type of the response 💅 And prepackaged apps often have really structured URIs that can only be changed in limited ways. Usually you can only tweak the hostname and port where they're deployed 🙈

So the owner of the URI (as defined in [webarch] Section 2.2.2.1) picks to use the server or the application. That can be seen as reasonable delegation of authority. BUT when a party other than the owner mandates those conventions, it can cause a few potentially harmful effects:

  • Collisions - As more ad hoc conventions for URI structure get standardized, it gets more likely that they'll collide with each other (especially since servers, applications, and individual deployments will each have their own conventions) 💀
  • Dilution - When the info added to a URI is ephemeral, it dilutes the URI's usefulness by reducing its stability (see [webarch] Section 3.5.1). It can also 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 desired deployment patterns. For example, if an authority wants to offer several applications on a single hostname, it's hard, if not impossible, to do if their URIs don't allow the flexibility it needs 🌸
  • Operational Difficulty - Supporting some URI conventions can be tough in some implementations. For example, saying that a particular query parameter must be used with "HTTP" URIs rules out Web servers that serve the response 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 get standardized, some clients will inevitably assume the standards are in use whenever they see those conventions. This can lead to interoperability problems. For example, if a spec documents that the "sig" URI query parameter indicates 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 not it. The structure of a URI needs to stay firmly under its owner's control, and the IETF (as well as other organizations) shouldn't take that over 👑

This document explains some best current practices for setting up URI structures, conventions, and formats in standards. It also offers strategies for specs to avoid breaking these guidelines, which you'll find in Section 3 💖

1.1. Intended Audience

The requirements in this doc are aimed at authors of specs that constrain the syntax or structure of URIs, or parts of them. Two classes of these specs get called out specifically:

  • Protocol Extensions ("extensions") - specs that offer new capabilities that could apply to any identifier, or to a large subset of possible identifiers. For example, a new signature mechanism for 'http' URIs, or metadata for any URI 🦋
  • Applications Using URIs ("applications") - specs that use URIs to meet specific needs. For example, an HTTP interface to particular information on a host 🌈

Requirements that target the generic class "Specifications" apply to all specs, including both of the ones above and others 💅

Note that this spec shouldn't be read as blocking parties that legitimately own URIs, or have delegated that ownership, from allocating control of them. For example, a spec 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 specs that already go against the guidance in this doc. In those cases, it's up to the relevant communities (i.e., the community for the URI scheme and the one that produced the spec in question) to figure out a good outcome. For example, they might update the scheme definition, or change the spec itself 🧚

1.2. Notational Conventions

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]. ✨

2. Best Current Practices for Standardizing Structured URIs 🎀

This section updates [RFC3986] by setting limits on how other specs may define structure and semantics within URIs. Best practices differ depending on the URI component, as described below 💖

2.1. URI Schemes

Applications and extensions MAY require use of specific URI scheme(s). For example, it's perfectly fine to require that an application support 'http' and 'https' URIs. However, applications SHOULD NOT preclude the use of other URI schemes in the future, unless they're clearly only usable with the nominated schemes 🌸

A spec that defines substructure within a specific URI scheme MUST do so in the defining document for that URI scheme. A spec that defines substructure for URI schemes overall MUST do so by modifying [BCP115] (an exceptional circumstance) 👑

2.2. URI Authorities

Scheme definitions define whether an authority component exists in URIs, plus its format and semantics. All other specs MUST NOT constrain, or define the structure or the semantics for, URI authorities, unless they update the scheme registration itself 🦋

For example, an extension or application ought not say that the "foo" prefix in "foo_app.example.com" is meaningful or triggers special handling in URIs 🙈

However, applications MAY nominate or constrain the port they use, when applicable. For example, BarApp could run over port nnnn (provided that it's properly registered) 🍓

2.3. URI Paths

Scheme definitions define whether a path component exists in URIs, plus its format and semantics. All other specs MUST NOT constrain, or define the structure or the semantics for, any path component 💅

The only exception to this requirement is registered "well-known" URIs, as specified by [RFC5785]. See that doc for a description of when that mechanism applies 🧚

For example, an application ought not specify a fixed URI path "/myapp", since that takes over the host's control of that space 😭

Specifying a fixed path relative to another one (e.g., {whatever}/myapp) is also bad practice, even if "whatever" is discovered as suggested in Section 3. Sure, doing so might prevent collisions, but it doesn't avoid the potential for operational difficulties. For example, an implementation might prefer to use query processing instead, because of implementation constraints 🌈

2.4. URI Queries 🎀

okay so the query part of a URI (the bit after the ?) is giving complicated. Whether it's even there, what it looks like, and what it means depends on a bunch of stuff. A scheme definition MAY constrain it, and honestly it's usually decided by how the resource itself is built 🌸

Applications MUST NOT directly specify the syntax of queries, bestie, because that can cause real operational headaches for deployments that don't support a certain kind of query. Like, a site might want to run an app using "static" files that just don't do query parameters at all 🙈

Extensions MUST NOT constrain the format or semantics of queries. Period 💅

Here's why. Say an extension decides that every query parameter named "sig" means a cryptographic signature. That would crash straight into query parameters that already exist on sites, and clients would start assuming any matching parameter is a signature. Not it 💀

HTML [W3C.REC-html401-19991224] puts rules on the syntax of query strings used in form submission. New form languages SHOULD NOT copy that. Instead they should let people make a wider variety of URIs, for example by letting a form create new path components and whatever else 🍓

Also, "well-known" URIs (see [RFC5785]) MAY constrain their own query syntax, since those namespaces are basically delegated to whoever registered them ✨

2.5. URI Fragment Identifiers 🦋

Media type definitions (as per [RFC6838]) SHOULD specify the fragment identifier syntax or syntaxes to be used with them. Other specifications MUST NOT define structure within the fragment identifier, unless they're explicitly defining one for reuse by media type definitions. Main character rules 👑

For example, imagine an application that defines common fragment identifiers across media types it doesn't control. That would cause interoperability problems with handlers for those media types, because they aren't expecting this new non-standard syntax at all 😭

3. Alternatives to Specifying Structure in URIs 🧚

Given the issues from Section 1, the most successful move 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, not as statically specified syntax. There are a few existing specs that can help with this, and they're iconic 💖

[RFC5988] 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 what a link means and how it connects things 🔥

[RFC6570] gives a standard syntax for URI Templates. Apps can use it to drop application-specific variables into a URI dynamically, which keeps the app working without stepping on the URI owner's control of it 🫶

[RFC5785] lets specific paths be "reserved" for standard use on URI schemes that opt into the mechanism ('http' and 'https' by default). But real talk, this is NOT a general escape valve for apps that need structured URIs. Go read that spec for the details 🌈

Now, making elaborate structures just to dodge collisions is not an acceptable solution, and it doesn't fix the issues in Section 1. Like, prefixing query parameters with "myapp_" doesn't help at all, because the prefix itself can collide too (it isn't "reserved") 🙃

4. Security Considerations 🔥

This document doesn't introduce new protocol artifacts with security considerations. What it does is prohibit some practices that could lead to vulnerabilities. For example, if a security-sensitive mechanism gets introduced by assuming a URI path component or query string has a particular meaning, you could hit false positives, because sites that already use that string exist. Be careful out there 😭 See also [RFC6943].

5. References 📚

5.1. Normative References

  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
  • [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, January 2013.
  • [webarch] Jacobs, I. and N. Walsh, "Architecture of the World Wide Web, Volume One", December 2004, <http://www.w3.org/TR/2004/REC-webarch-20041215>.

5.2. Informative References

  • [BCP115] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and Registration Procedures for New URI Schemes", RFC 4395, BCP 115, February 2006.
  • [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010.
  • [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
  • [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
  • [RFC6943] Thaler, D., "Issues in Identifier Comparison for Security Purposes", RFC 6943, May 2013.
  • [W3C.REC-html401-19991224] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 Specification", World Wide Web Consortium Recommendation REC-html401-19991224, December 1999, <http://www.w3.org/TR/1999/REC-html401-19991224>.

Appendix A. Acknowledgments 🫶

Huge 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. Legends, all of you 🌟

Author's Address 💜

Mark Nottingham

EMail: mnot@mnot.net
URI:   http://www.mnot.net/
📦 where this page comes from