HN Debrief

So You Want to Define a Well-Known URI

  • Web Standards
  • Infrastructure
  • Security
  • AI

The post is a guide to defining a so-called well-known URI, meaning a standardized path under `/.well-known/` that software can probe for metadata or a capability. It argues that these endpoints are useful when clients need a predictable place to discover something on a domain, but they are costly because they occupy shared global names, interact badly with some hosting models, and tend to live forever once shipped. The author’s practical advice is to register them only when the use case is common enough, specific enough, and hard to solve better with existing web or DNS mechanisms.

If you are designing service discovery or verification for your product, treat `/.well-known/` as a scarce shared namespace and register only narrow, broadly reusable endpoints. For company-specific verification and agent metadata, compare DNS, HTML link relations, and content negotiation before minting another web-root convention that others will have to support forever.

Discussion mood

Mostly favorable toward the post’s core warning against casually minting new shared paths, with a pragmatic view that `/.well-known/` is ugly but useful. Frustration centered on poor examples in the post, unregistered company conventions like `llms.txt`, and the broader web habit of piling overlapping discovery mechanisms on top of each other.

Key insights

  1. 01

    Content negotiation can replace new discovery files

    Serving the same resource as HTML, Markdown, or JSON from one canonical URL avoids inventing yet another discovery endpoint. Comments pointed to live patterns like Claude Code docs exposing `.md` versions and described using `Accept` headers or explicit extensions so humans, API clients, and agents all hit the same address and get the representation they need. That is a cleaner fit with HTTP than creating a site-wide marker file for every new consumer.

    Before adding a new `/.well-known/` or root file, ask whether the client really just needs another representation of pages you already serve. If yes, add link relations and content negotiation first, because that keeps the integration local to the resource instead of adding permanent global surface area.

      Attribution:
    • 9dev #1
    • vidarh #1 #2
    • mceachen #1
  2. 02

    Domain verification fits DNS badly at the apex

    Using apex TXT records for every vendor verification looks simple until the zone turns into a pile of unrelated strings. Comments noted that this bloats ordinary TXT lookups such as SPF checks, can make domains more attractive for DNS amplification abuse, and creates long-lived garbage records. The stronger pattern is still DNS-based, but under vendor-specific underscored names like `_service.example.com`, which keeps semantics out of the apex and avoids new record types while reducing collateral damage.

    If you need domain proof, do not default to stuffing one more TXT string onto the zone apex. Put the token on a scoped underscored label or use another existing DNS mechanism so you do not degrade unrelated lookups and operations.

      Attribution:
    • teddyh #1 #2
    • Bender #1
    • inigyou #1
  3. 03

    Some well-known endpoints deliver real product value

    The practical success case people kept returning to was not abstract metadata but narrow user workflows. `/.well-known/change-password` is useful because a password manager can probe once, cache the result, and send the user straight to the right page after a breach alert. OIDC discovery works for the same reason. It removes hard-coded provider configuration and gives software a single place to fetch live settings. The pattern works when the endpoint is specific, high-frequency, and shared across many products.

    Reserve well-known paths for cases where a generic client can immediately do something valuable for the user without bespoke integration. If your proposal still needs custom logic, custom docs, or vendor-specific interpretation after discovery, it is probably not a good candidate.

      Attribution:
    • masklinn #1
    • asdfasdfadsfs #1
    • ameliaquining #1
    • notpushkin #1
  4. 04

    Agent discovery is recreating web metadata fragmentation

    Comments about agentic browsing and service metadata captured a familiar failure mode. Every new wave of tooling wants its own discovery file, whether that is `llms.txt`, `auth.md`, or an agent card, even though the web already has DNS, link relations, and content negotiation. One commenter expects demand for domain-anchored machine discovery to rise with autonomous agents. The stronger implication is not that more files are inevitable, but that the ecosystem is about to repeat the same fragmentation unless one mechanism wins.

    Expect AI and agent tooling to pressure your site into exposing more machine-readable metadata. Push vendors toward existing mechanisms where possible, because supporting five overlapping conventions will become an operational tax very quickly.

      Attribution:
    • quotemstr #1
    • devdoshi #1
    • networked #1

Against the grain

  1. 01

    The post felt too abstract to be useful

    Several readers bounced off the article because it spends more time stating cautions than showing concrete design decisions. The complaint was not that the topic is trivial. It was that without worked examples, readers who are actually deciding between `/.well-known/`, DNS, or something else get very little help. A reply defended the post as a guardrail and pointer to the registration process rather than a tutorial.

    If you share standards guidance internally, do not stop at principles. Pair the rules with a short decision tree and example alternatives so product teams can apply them without already knowing the standards landscape.

      Attribution:
    • sandblast #1
    • thefifthsetpin #1
    • wseqyrku #1
  2. 02

    Dot-prefixed paths are a footgun

    The naming of `.well-known` itself drew pushback because dot paths are easy for operators and tooling to mishandle. Comments called out hidden-directory behavior, backup omissions, and developer confusion from an era when dotfiles implied local invisibility. Others replied that the dot was mainly a collision-avoidance hack and that modern tooling should already cope with dots in paths. Even so, the operational complaint is real.

    When you adopt `/.well-known/`, test it through your whole delivery chain, including static hosting, deploy filters, CDN rules, backups, and repo ignores. The standard path may be correct on paper and still fail in production for boring tooling reasons.

      Attribution:
    • russellbeattie #1
    • zamadatix #1
    • 9dev #1

In plain english

.well-known ↩
A standardized path prefix on websites used for machine-readable resources that software can reliably look up at fixed locations.
Content negotiation ↩
An HTTP mechanism where one URL can return different representations of the same resource based on client preferences.
DNS ↩
Domain Name System, the Internet service that maps domain names to records like IP addresses and text metadata.
HTML ↩
Hypertext Markup Language, the standard format for web pages shown in browsers.
HTTP ↩
Hypertext Transfer Protocol, the core protocol used by browsers and servers to request and deliver web content.
JSON ↩
JavaScript Object Notation, a widely used text format for structured data exchanged between systems.
Markdown ↩
A plain-text markup format that is easy for humans to write and often easier for software to parse than HTML.
OIDC ↩
OpenID Connect, an identity layer built on OAuth that lets applications authenticate users through an identity provider.
SPF ↩
Sender Policy Framework, a DNS-based email authentication system that declares which servers are allowed to send mail for a domain.
URI ↩
Uniform Resource Identifier, a general identifier for a resource such as a web address or name.
URL ↩
Uniform Resource Locator, a type of URI that tells you where a resource is and how to access it.

Reference links

Well-known URI references

AI and agent metadata proposals

Alternate representations and implementation examples

Identity and token discovery