Visual RFC.
ALL RFCs / RFC 8615
Read the RFC ↗

RFC 8615 / START HERE

Well-known URIs, before the details

Well-known URIs: Uniform Resource Identifiers

A URI identifies a resource. This RFC reserves /.well-known/ at the start of a supporting scheme’s path so an application can define a predictable location for discovery information. “Well-known” describes a location convention, not a trusted or universally available resource.

Start the guide See the 4 chapters ↓

The idea in one picture

  1. Read application rules

  2. Use a registered root path

  3. Check format and scope

A simplified picture of the idea; the chapters explain the actual mechanisms.

Why it exists

Applications need predictable discovery paths without taking over unrelated paths on every site. Registered names reduce collisions. This publication replaces RFC 5785, extends support beyond Web schemes and revises the registry procedures; each application still defines its own format, discovery rules and scope.

A familiar example

A fictional picnic app already knows from its application rules to look at https://api.example/.well-known/picnic-info. It uses the specified response format. It does not assume /foo/.well-known/picnic-info is equivalent, that /.well-known/ lists everything, or that the result controls another origin.

Helpful background

You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.

URI syntaxRFC 3986 · beginner overview ↗HTTPRFC 9110 · beginner overview ↗

What you’ll learn next

Begin with chapter one, or choose a topic.

  1. Start at the root of a supporting schemeA URI is a resource identifier. A well-known URI starts its path with /.well-known/ and uses a scheme explicitly defined to support it.
  2. Register a precise name and a specificationAn application name is one nonempty URI path segment. Registration connects that name to stable rules and avoids collisions.
  3. Follow application rules, not a directory indexThe shared prefix locates application-defined resources. It does not supply a common metadata format, a hostname discovery algorithm or an index.
  4. Protect the origin and constrain discovered policyA predictable path is visible to browsers and can affect an origin. Shared hosting, injected scripts and guessed cross-origin scope create risks.
Start with chapter one →

This introduction explains RFC 8615 (2019). Read the original RFC ↗