3. Well-Known URIs
3. Well-Known URIs
A well-known URI is a URI [RFC3986] whose path component begins with the characters /.well-known/, provided that the scheme is explicitly defined to support well-known URIs.
For example, if an application registers the name example, the corresponding well-known URI on http://www.example.com/ would be http://www.example.com/.well-known/example.
This specification updates the http [RFC7230] and https [RFC7230] schemes to support well-known URIs. Other existing schemes can use the appropriate process for updating their definitions; for example, [RFC8307] does so for the ws and wss schemes. The "Uniform Resource Identifier (URI) Schemes" registry tracks which schemes support well-known URIs; see Section 5.2.
Applications that wish to mint new well-known URIs MUST register them, following the procedures in Section 5.1, subject to the following requirements.
Registered names MUST conform to the segment-nz production in [RFC3986]. This means they cannot contain the / character.
Registered names for a specific application SHOULD be correspondingly precise; "squatting" on generic terms is not encouraged. For example, if the Example application wants a well-known location for metadata, an appropriate registered name might be example-metadata or even example.com-metadata, not metadata.
At a minimum, a registration will reference a specification that defines the format and associated media type(s) to be obtained by dereferencing the well-known URI, along with the URI scheme(s) that the well-known URI can be used with. If no URI schemes are explicitly specified, http and https are assumed.
Typically, applications will use the default port for the given scheme; if an alternative port is used, it MUST be explicitly specified by the application in question.
Registrations MAY also contain additional information, such as the syntax of additional path components, query strings, and/or fragment identifiers to be appended to the well-known URI, or protocol-specific details (e.g., HTTP [RFC7231] method handling).
Note that this specification defines neither how to determine the hostname to use to find the well-known URI for a particular application, nor the scope of the metadata discovered by dereferencing the well-known URI; both should be defined by the application itself.
Also, this specification does not define a format or media type for the resource located at /.well-known/, and clients should not expect a resource to exist at that location.
Well-known URIs are rooted in the top of the path's hierarchy; they are not well-known by definition in other parts of the path. For example, /.well-known/example is a well-known URI, whereas /foo/.well-known/example is not.
See also Section 4 for Security Considerations regarding well-known locations.
3.1. Registering Well-Known URIs
The "Well-Known URIs" registry is located at https://www.iana.org/assignments/well-known-uris/. Registration requests can be made by following the instructions located there or by sending an email to the [email protected] mailing list.
Registration requests consist of at least the following information:
URI suffix: The name requested for the well-known URI, relative to /.well-known/; e.g., example.
Change controller: For Standards Track RFCs, state "IETF". For others, give the name of the responsible party. Other details (e.g., email address, home page URI) may also be included.
Specification document(s): Reference to the document that specifies the field, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant sections may also be included, but is not required.
Status: One of permanent or provisional. See guidance below.
Related information: Optionally, citations to additional documents containing further relevant information.
General requirements for registered values are described in Section 3.
Values defined by Standards Track RFCs and other open standards (in the sense of [RFC2026], Section 7.1.1) have a status of permanent. Other values can also be registered as permanent, if the experts find that they are in use, in consultation with the community. Other values should be registered as provisional.
Provisional entries can be removed by the experts if -- in consultation with the community -- the experts find that they are not in use. The experts can change a provisional entry's status to permanent; in doing so, the experts should consider how widely used a value is and consult the community beforehand.
Note that "consult the community" above refers to those responsible for the URI scheme(s) in question. Generally, this would take place on the mailing list(s) of the appropriate Working Group(s) (possibly concluded), or on [email protected] if no such list exists.
Well-known URIs can be registered by third parties (including the expert(s)), if the expert(s) determine that an unregistered well-known URI is widely deployed and not likely to be registered in a timely manner otherwise. Such registrations still are subject to the requirements defined, including the need to reference a specification.