Web Host Metadata
Extracted elements (28)
host-meta was introduced to avoid overloading the root HTTP resource (e.g., 'http://example.com/') with host metadata that is not specific to that resource. A dedicated well-known URI provides a standard location for host-level policy without polluting the root resource.
Link ordering in the combined resource descriptor is intentional and defines priority: links appearing before the 'lrdd' link in host-meta have higher priority than links from the LRDD document, while links after the 'lrdd' link in host-meta have lower priority than the LRDD document's links.
The JRD format is recommended as an alternative to XRD XML to accommodate JSON-native clients. It is intentionally limited in extensibility compared to XRD, as extensibility is considered out of scope for this specification.
Two mechanisms for resource-specific information (link templates and LRDD documents) are provided because link templates handle generic rules efficiently while LRDD documents accommodate richer, per-resource information that cannot be expressed in a template.
The host-meta and host-meta.json documents obtained from the same host using HTTP and HTTPS (on default ports) MUST be identical, ensuring consistent metadata regardless of transport protocol.
Applications where the authenticity of host-meta information is necessary MUST require the use of HTTPS and MUST NOT produce a host-meta document via other means. Such applications MUST also require that any redirection leading to host-meta retrieval also uses HTTPS.
Before substituting template variables, values MUST be encoded using UTF-8, and any character other than unreserved (per RFC 3986) MUST be percent-encoded. Protocols MUST NOT change the meaning of the 'uri' variable.
If a client is unable to successfully process a template (e.g., unknown variable names or incompatible syntax), the parent 'Link' element SHOULD be ignored.
If the server response indicates the host-meta resource is located elsewhere (301, 302, or 307), the client SHOULD try to obtain the resource from the redirect location. If the resource is not available (404 or 410), the client SHOULD infer that metadata is not available via this mechanism.
Since the host-meta document is authoritative for the entire host, applications MUST ensure that using a host-meta document for another URI authority does not represent a potential security exploit.
The client obtains the host-meta document by sending an HTTP or HTTPS GET request to '/.well-known/host-meta' using default ports (80 for HTTP, 443 for HTTPS). The scope and meaning of host-meta documents obtained via other protocols or ports is undefined.
The host-meta document root MUST be an 'XRD' element. The document SHOULD NOT include a 'Subject' element, as no URI is available to identify hosts. The use of the 'Alias' element is undefined and NOT RECOMMENDED.
The host-meta document SHOULD be served with the 'application/xrd+xml' media type. If the client requests this representation or sends no Accept header, the server MUST respond using the XRD 1.0 XML representation.
The server MUST support at least one protocol (HTTP or HTTPS) for serving host-meta documents, but MAY support both. If both protocols are supported, they MUST produce the same document.
When following an 'lrdd' link, if the HTTP response status code is 301, 302, or 307, the client MUST follow the redirection and repeat the request. Processing is limited to a single level of LRDD inclusion (no recursive lrdd links).
When looking for host-wide information, the client MUST ignore any 'Link' elements with a 'template' attribute, as well as any link using the 'lrdd' relation type. All other elements are scoped as host-wide.
A 'Link' element with an 'href' attribute conveys a host-wide link relation between the host and a fixed target URI. A 'Link' element with a 'template' attribute conveys a resource-specific relation whose target is constructed by applying the context resource URI to the template.
Link-based Resource Descriptor Documents (LRDD, pronounced 'lard') are per-resource descriptor documents linked via 'lrdd' relation type link templates. They provide resource-specific information not expressible via link templates and MUST have an 'application/xrd+xml' representation.
Resource-specific information is assembled by iterating host-meta link templates in order: non-lrdd links are added to the resource descriptor directly; lrdd links trigger fetching the LRDD document whose links (except nested lrdd) and properties are merged in order.
The host-meta document is an XRD 1.0 XML document served at '/.well-known/host-meta' that describes host-wide metadata and resource-specific link templates. It may include Property elements, Link elements with fixed href attributes (host-wide), and Link elements with template attributes (resource-specific).
RFC 6415 registers the 'host-meta.json' well-known URI suffix in the Well-Known URI Registry, pointing to the JRD (JSON) representation of the host metadata document at '/.well-known/host-meta.json'.
RFC 6415 registers the 'host-meta' well-known URI suffix in the Well-Known URI Registry (RFC 5785), pointing to the XRD 1.0 host metadata document at '/.well-known/host-meta'.
RFC 6415 registers the 'lrdd' link relation type in the Link Relation Type Registry (RFC 5988). It refers to a Link-based Resource Descriptor Document providing further information about the link's context. LRDD resources MUST have an 'application/xrd+xml' representation and MAY have others.
Protocols using host-meta templates must evaluate their template construction and any protocol-specific variables to ensure templates cannot be abused. A poorly constructed template can be exploited to trick clients into following malicious links via unexpected variable value characters.
The host-meta document is presumed authoritative for all resources on the host. If compromised, it may represent a risk to the security of the server and all data served by it. Applications must review specific security implications before opting in to this facility.
JRD Link child 'Title' elements are serialized as a 'titles' object keyed by xml:lang value (or 'default' if absent); only the last instance of duplicate xml:lang values is retained. Link child 'Property' elements follow the same serialization as XRD-level properties.
The JRD (JSON Resource Descriptor) format serializes XRD to JSON: 'Subject' → 'subject' string; 'Alias' elements → 'aliases' string array; 'Property' elements → 'properties' object keyed by type URI; 'Link' elements → 'links' array of objects with attributes as name/value pairs.
The template syntax uses brace-enclosed variable names ('{var-name}') within a URI string. The ABNF defines URI-Template as a sequence of uri-char or variable elements; 'uri' is the predefined variable representing the entire context resource URI, percent-encoded per RFC 3986.