When a /.well-known/ URI Is the Wrong Tool — Advice from the Spec's Author

Mark Nottingham, co-author of the Well-Known URI specification and the registry’s Designated Expert, lays out his working guidance for protocol designers eyeing a /.well-known/ slot. The pattern fits one narrow shape: a client already knows a site (technically an origin — the scheme/host/port tuple) and needs to discover or act on something site-wide in a single, efficient lookup. robots.txt is the canonical case, since a crawler can read one central policy file instead of inspecting headers on every response. The change-password location is another good fit. If a protocol doesn’t have that specific ‘client knows the site, needs something site-wide’ problem, a registration won’t solve anything — and it certainly won’t confer the legitimacy or adoption some proposers imagine it brings.

Nottingham flags two common misuses. One is treating the registry as a credential or growth hack; a slot is not endorsement. The other is using a well-known location as a de facto URL shortener, conveying only a hostname and letting the fixed path fill in the rest. That hardcodes a 1:1 relationship between service and site, so any deployment needing multiple services is forced to spin up additional sites. His rule of thumb: if your protocol can carry a real URL, use the URL and skip the well-known location entirely.

Even when the tool fits, the assumptions behind ‘sites’ often break down. Discovery gets ambiguous when the user starts at login.example.com but the lookup belongs at example.com — designers must spell out hostname resolution, redirect behavior, and apex-domain expectations rather than assuming a clean architecture. Content-metadata use cases collide with multi-publisher hosts (the old /~username/ convention), frequently forcing a parallel metadata channel in headers or content. He closes with practical reminders: legacy root paths like /robots.txt need a real transition plan, schemes beyond http/https should be enumerated explicitly, and proposals must actually be registered following the registry’s naming guidance.