Web host-meta data

Overview #

Web host-meta data is defined in RFC 6415 and describes a Discovery Mechanism for metadata as well as information about individual resources controlled by the host.

RFC 6415 document also registers the well-known URI suffix "host-meta" in the Well-known URI Registry established by RFC 5785.

Web host-meta data registers the "lrdd" relation type in the Link Relation Types Registry

Obtaining host-meta Documents#

The client obtains the host-meta document for a given host by sending an HTTP RFC 2616 or an HTTPS RFC 2818 GET request to the host for the "/.well-known/host-meta" path, using the default ports defined for each protocol (e.g., port 80 for HTTP and port 443 for HTTPS). The scope and meaning of host-meta documents obtained via other protocols or ports is undefined.

The server MUST support at least one protocol but MAY support both. If both protocols are supported, they MUST produce the same document.

Web host-meta data Example#

For example, the following request is used to obtain the host-meta document for the 'example.com' host:
GET /.well-known/host-meta HTTP/1.1
 Host: example.com
If the server response indicates that the host-meta resource is located elsewhere (a 301, 302, or 307 response status code), the client SHOULD try to obtain the resource from the location provided in the response. This means that the host-meta document for one host MAY be retrieved from another host. Likewise, if the resource is not available or does not exist (e.g., a 404 or 410 response status code), the client SHOULD infer that metadata is not available via this mechanism.

The host-meta document SHOULD be served with the "application/xrd+xml" media type and is in XRD.

The client MAY request a JRD representation using the HTTP "Accept" request header field with a value of "application/json". The server MUST include the HTTP Response Header "Content-Type" with a value of "application/json". Any other "Content-Type" value (or lack thereof) indicates that the server does not support the JRD format.

Alternatively, the client MAY request a JRD representation by requesting the "host-meta.json" well-known document, by making a

GET /.well-known/host-meta.json HTTP/1.1
 Host: example.com
following the same process used for "/.well-known/host-meta". If the server does not support serving a JRD representation at this location, the server MUST respond with an HTTP 404 (Not Found) status code.

Resource-specific Information#

In addition, there are times when a host-wide scope for policy or metadata is too coarse-grained. Web host-meta data provides two mechanisms for providing resource-specific information:
  • Link Templates - links using a URI template instead of a fixed target URI, providing a way to define generic rules for generating resource-specific links by applying the individual resource URI to the template.
  • Link-based Resource Descriptor Documents (LRDD), pronounced 'lard') - descriptor documents providing resource-specific information, typically information that cannot be expressed using link templates. LRDD documents are linked to resources or host-meta documents using link templates with the "lrdd" relation type.

Web host-meta data Example#

Using Google Gmail http://gmail.com/.well-known/host-meta obtains an XML eXtensible Resource Descriptor Sequence (XRDS) document:
<?xml version='1.0' encoding='UTF-8'?>
<!-- NOTE: this host-meta end-point is a pre-alpha work in progress.   Don't rely on it. -->
<!-- Please follow the list at http://groups.google.com/group/webfinger -->
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0' 
  <hm:Host xmlns='http://host-meta.net/xrd/1.0'>gmail.com</hm:Host>
  <Link rel='lrdd' 
    <Title>Resource Descriptor</Title>

OpenID Provider Issuer Discovery#

Using the provided "template URL" provided http://www.google.com/s2/webfinger/?q=jwilleke@gmail.com obtains an XML XRDS document:
<?xml version='1.0'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
	<Link rel='http://portablecontacts.net/spec/1.0' href='http://www-opensocial.googleusercontent.com/api/people/'/>
	<Link rel='http://portablecontacts.net/spec/1.0#me' href='http://www-opensocial.googleusercontent.com/api/people/110925871223838855670/'/>
	<Link rel='http://webfinger.net/rel/profile-page' href='http://www.google.com/profiles/jwilleke' type='text/plain'/>
	<Link rel='http://microformats.org/profile/hcard' href='http://www.google.com/profiles/jwilleke' type='text/plain'/>
	<Link rel='http://gmpg.org/xfn/11' href='http://www.google.com/profiles/jwilleke' type='text/plain'/>
	<Link rel='http://specs.openid.net/auth/2.0/provider' href='http://www.google.com/profiles/jwilleke'/>
	<Link rel='describedby' href='http://www.google.com/profiles/jwilleke' type='text/plain'/>
	<Link rel='describedby' href='https://www.google.com/s2/webfinger/?q=jwilleke@gmail.com&amp;fmt=foaf' type='application/rdf+xml'/>
Which shows the OpenID Connect Provider url (http://specs.openid.net/auth/2.0/provider).

More Information#

There might be more information for this subject on one of the following: