RFC 5785

Defining Well-Known Uniform Resource Identifiers (URIs) 🎀

Okay bestie, this is RFC 5785 💖. It's an Internet Standards Track doc, so it's the real deal. M. Nottingham and E. Hammer-Lahav wrote it, and it's dated April 2010. It's part of the IETF stream with ISSN 2070-1721 🌸. It doesn't obsolete anything, but it does update RFC 2616 and RFC 2818 ✨.

Abstract

The big idea is that this memo gives "well-known locations" their own path prefix, "/.well-known/", in selected Uniform Resource Identifier (URI) schemes 🦋.

Status of This Memo

Okay so, this is an Internet Standards Track document 👑.

This document is a product of the Internet Engineering Task Force (IETF) 🌈. It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication. If you want more on Internet Standards, check out Section 2 of RFC 5741 📚.

For the latest status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc5785 🔗.

Copyright Notice

Copyright (c) 2010 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 in effect on the date this document was published. Please read these carefully, because they spell out your rights and restrictions for 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 they come without warranty as described in the Simplified BSD License 💅.

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
  1.1.  Appropriate Use of Well-Known URIs  . . . . . . . . . . . . 3
2.  Notational Conventions  . . . . . . . . . . . . . . . . . . . . 3
3.  Well-Known URIs . . . . . . . . . . . . . . . . . . . . . . . . 3
4.  Security Considerations . . . . . . . . . . . . . . . . . . . . 4
5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4
  5.1.  The Well-Known URI Registry . . . . . . . . . . . . . . . . 4
    5.1.1.  Registration Template . . . . . . . . . . . . . . . . . 5
6.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  6.1.  Normative References  . . . . . . . . . . . . . . . . . . . 5
  6.2.  Informative References  . . . . . . . . . . . . . . . . . . 5
Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . . . 7
Appendix B.  Frequently Asked Questions . . . . . . . . . . . . . . 7

---

1. Introduction ✨

It's getting super common for web protocols to need to find out policy or other info about a host ("site-wide metadata") before they make a request 🧚. For example, the Robots Exclusion Protocol <http://www.robotstxt.org/> gives automated processes a way to get permission to access resources. And the Platform for Privacy Preferences [W3C.REC-P3P-20020416] tells user-agents how to find a privacy policy ahead of time 🔥.

There are other ways to get per-resource metadata, like HTTP headers or WebDAV's PROPFIND [RFC4918]. But the perceived overhead (client-side latency, deployment headaches, or both) often means they just aren't practical for these situations 🙄.

So people often pick a "well-known location" to hold this data, so it's easy to find 🍓. The catch is that it risks collisions, both with other "well-known locations" and with resources that already exist 💀.

To fix that, this memo defines a path prefix in HTTP(S) URIs for these "well-known locations", "/.well-known/" 🌸. Future specs that need a resource for site-wide metadata can register their use, which avoids collisions and keeps them from taking over too much of a site's URI space 🫶.

1.1. Appropriate Use of Well-Known URIs

There are lots of ways applications could use well-known URIs 💖. Still, in line with the Architecture of the World-Wide Web [W3C.REC-webarch-20041215], well-known URIs are not meant for general information retrieval or for setting up big URI namespaces on the Web 🙅‍♀️. They're there to make it easy to discover site information when other mechanisms aren't practical. Think policy that has to be checked before a resource gets accessed, or cases where doing multiple round-trips would hurt performance ⚡.

So the well-known URI space was made for putting site-wide policy and other metadata right where you can grab it (if it's concise enough). It can also point to other URIs that hold that metadata 🦋.

2. Notational Conventions

Okay, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document get read the way RFC 2119 [RFC2119] describes 🎀.

3. Well-Known URIs 💅

A well-known URI is a URI [RFC3986] whose path component starts with the characters "/.well-known/". Its scheme is "HTTP", "HTTPS", or another scheme that's been explicitly specified to use well-known URIs 🌈.

Applications that want to mint new well-known URIs MUST register them, following the procedures in Section 5.1 🔥.

For example, if an application registers the name 'example', the matching well-known URI on 'http://www.example.com/' would be 'http://www.example.com/.well-known/example' 🧚.

Registered names MUST conform to the segment-nz production in [RFC3986] 💜.

Heads up: this spec doesn't say how to figure out which authority to use in a given context, and it doesn't say how far the metadata you find by dereferencing the well-known URI reaches. Both of those should be defined by the application itself 🙈.

Usually a registration points to a spec that defines the format and associated media type you get when you dereference the well-known URI 📚.

It MAY also include extra info, like the syntax of additional path components, query strings, and/or fragment identifiers to append to the well-known URI. It can also cover protocol-specific details, such as how HTTP [RFC2616] method handling works 🦋.

Last but not least, this spec doesn't define a format or media type for the resource at "/.well-known/", so clients should not expect a resource to exist at that location 👑.

---

Part 1 is done, babe 🫶 Part 2 is coming next with Section 4 (Security Considerations) through the References and Appendices 💖✨

Appendix B. Frequently Asked Questions 🎀

Okay so bestie, this is the FAQ section and it is SO good 🙈 Let's get into it.

1. Aren't well-known locations bad for the Web? 💀

Ngl, yes, they kinda are 😭 But for a bunch of reasons, both technical and social, people use them a LOT and that number keeps climbing. So this memo makes a "sandbox" for them 🧚 The whole point is to lower the chances of two things colliding and to keep the impact on URIs that already exist on sites as small as possible. Main character energy for the sandbox 💅

2. Why /.well-known? 🦋

Because it's short, it's descriptive, and according to search indices, nobody's really using it yet. Iconic choice honestly ✨

3. What impact does this have on existing mechanisms, such as P3P and robots.txt? 🌸

None! 🫶 Nothing changes for them until they decide they want to use this mechanism. Totally opt-in vibes.

4. Why aren't per-directory well-known locations defined? 🍓

So the reason is, if every URI path segment got its own well-known location (think "/images/.well-known/"), that would make it way more likely to collide with a URI that already exists on a site 😬 Also these kinds of solutions usually don't scale well, because they're too "chatty" 🙈 It's giving overcomplicated, and nobody wants that.

---

Authors' Addresses 🖊️

Mark Nottingham

EMail: mnot@mnot.net URI: http://www.mnot.net/

Eran Hammer-Lahav

EMail: eran@hueniverse.com URI: http://hueniverse.com/

That's the whole RFC, bestie! 🌈👑 Iconic work from Mark and Eran 💖