The Problem with "Just Register a Well-Known URI"

Mark Nottingham, co-author of RFC 8615 (Well-Known URIs) and current Designated Expert for the IANA registry, sees a recurring pattern: protocol designers treat the well-known location registry as a badge of legitimacy. It's not. As Nottingham puts it: "Some proposals register one expecting it to confer legitimacy, or boost adoption — as though a slot in the registry were a credential. It isn't."

A well-known location solves one specific problem: the client knows the site and needs to discover something about the whole site efficiently. robots.txt is the canonical example — it predates the RFC but perfectly illustrates the pattern. A crawler needs site-wide access policies without checking headers on every response.

When Well-Known Locations Work

Well-known locations shine when the client already knows the site's hostname and needs site-wide information or interaction. Examples: the change-password well-known location (allows clients to trigger password changes) or security.txt (provides security contact info). The key constraint: the protocol can only carry a hostname. If your protocol can convey a full URL, don't use a well-known location.

The URL Shortener Trap

Nottingham identifies a common anti-pattern: using well-known locations as a URL shortener. Instead of transmitting a full URL in a protocol, designers send only the hostname and rely on the well-known location to fill in the rest. This locks you into a 1:1 relationship between services and sites. If a deployment ever needs more than one service, they must create a different site and redirect users.

Example: Suppose your protocol defines /.well-known/my-service for a single API endpoint. Later, you need two endpoints — my-service-a and my-service-b. Now you either need two hostnames or a complex dispatching mechanism. Had you used a real URL from the start, you could have /api/v1/a and /api/v1/b under the same host.

Discovery Mismatches

Many protocols assume "the user already knows the site" — but the reality is fuzzy. If a client starts at login.example.com, should it look up the well-known location on that subdomain or on example.com? Should it follow redirects? This matters especially when the protocol isn't really about Web sites but just leverages HTTP.

Nottingham advises: "Consider both what's being discovered and what your users start with, then work out how they reliably find the right hostname without assuming too much about their architecture." For registrable domain names, locating at the apex (e.g., example.com) can be operationally difficult — many deployments don't serve traffic from the apex.

Content Metadata: More Work Than You Think

Some protocols use well-known locations for content metadata, inspired by robots.txt. But many sites have multiple publishers (e.g., the old /~username/ convention). Putting content metadata in a central location either excludes those users or forces administrators to build complex infrastructure to delegate control.

This creates a tradeoff between convenience and granularity. Nottingham warns: "That's not to say that Well-Known locations can't be used for content metadata; just that they're a lot more work than you might think." Often you'll need a parallel metadata mechanism — HTTP response headers or in-content metadata — plus rationalization between the two.

Transitioning from Root Locations

Some protocols already defined a fixed location at the root (like /.well-known/). If so, you need a transition plan for existing deployments. Nottingham notes that proponents "over-focus on their current deployed footprint" — with a good transition plan over a reasonable time, moving to a well-known location is manageable.

Explicit Scheme Handling

Many proposals implicitly assume http and https URLs. But well-known locations apply to other URL schemes too. The RFC doesn't restrict schemes, so you should enumerate relevant schemes explicitly.

Registration is Mandatory

Finally, register your well-known location. The IANA registry has guidance on when to register and how to choose a name. Unlike Nottingham's informal advice, the registration process affects your chances of successful registration.

Practical Checklist

Before proposing a well-known location, ask:

  1. Can your protocol carry a full URL? If yes, use a real URL, not a well-known location.
  2. Do clients already know the site hostname? If not, discovery will be fragile.
  3. Is the information truly site-wide? If it varies by user, path, or subdomain, a well-known location adds complexity.
  4. Are you expecting a registry slot to boost adoption? It won't. The spec must stand on its own.
  5. Have you enumerated all URL schemes you support? Don't assume HTTP(S) only.
  6. Do you have a transition plan if the protocol already uses a root path?

The Bottom Line

Well-known locations are a precision tool. Use them when the client knows the hostname and needs site-wide data. Avoid them for discovery, URL shortening, or as a credibility stamp. As Nottingham says, "a registration may only create new ones — and won't bring the adoption you're hoping for."