A Guide to Using Well-Known URIs Effectively

Mark Nottingham offers expert guidance on the effective use of Well-Known URIs, emphasizing their role in site-wide discovery. He cautions against using them for convenience or perceived legitimacy, as this can lead to deployment rigidity. The article outlines critical considerations for discovery scope and multi-tenant environments to ensure robust protocol design.

Key Points

• Well-known URIs are best suited for site-wide discovery where the client already knows the origin and needs efficient access to global policies or interactions.
• Avoid using well-known locations as URL shorteners or for 'official' status, as this causes unnecessary deployment rigidity and architectural lock-in.
• Designers must account for discovery scope issues, specifically how clients resolve the correct hostname when starting from a subdomain or a specific user path.
• Centralized metadata at a well-known location can be problematic for multi-publisher sites, requiring a balance between administrative convenience and user granularity.
• Proper registration requires explicit enumeration of supported URL schemes and a clear transition plan for any existing root-level locations.

Sentiment

The overall sentiment is cautiously supportive of the article's main point. Hacker News mostly agrees that well-known URIs are useful when they prevent root namespace sprawl and enable real client interoperability, but the discussion is full of engineering caveats about specificity, documentation, implementation burden, DNS alternatives, and whether voluntary discovery conventions are honored in practice.

In Agreement

• Root-level files and one-off discovery conventions should be avoided when a well-known URI can provide a standardized location for site-wide metadata.
• A centralized miscellaneous namespace is better than allowing every protocol or company to squat on its own path at the web root.
• Specific well-known endpoints are justified when interoperable clients need a stable, predictable place to probe, such as password managers, OIDC clients, ACME tooling, federation software, or key-discovery systems.
• The article usefully highlights overlooked deployment issues such as multi-service domains, subdomains, user-controlled paths, and the need to think about where discovery is scoped.
• Standards that reuse existing registries and common formats can reduce the repeated reinvention of subtly incompatible discovery mechanisms.

Opposed

• Some commenters felt the article was too abstract and obvious, offering too few concrete examples or actionable recommendations for implementers.
• Several people questioned whether .well-known endpoints are truly discoverable to humans, arguing that RFCs and registries often point to specifications rather than live examples.
• Some preferred alternative discovery mechanisms such as DNS records, underscore-prefixed names, HTML link tags, schema markup, content negotiation, or per-page Markdown and JSON representations.
• Commenters criticized overly narrow or company-branded identifiers, arguing that generic domain-verification or service-discovery mechanisms would age better than vendor-specific paths.
• Skeptics argued that compliance-oriented files such as robots.txt or llms.txt do not matter when crawlers or bots can simply ignore them.