RFC 6415

Web Host Metadata

📅 published October 2011, from ietf

RFC 6415: Web Host Metadata 💖

okay bestie, this one is RFC 6415: Web Host Metadata 🎀 It's a Standards Track doc from the IETF, published in October 2011. The editors are E. Hammer-Lahav, Ed. and B. Cook. It's ISSN 2070-1721 and it has no Obsoletes or Updates line in the title block. Let's get into it 🧚

Abstract ✨

so this spec is about how you find a host's metadata, plus info about the individual resources that host controls 💅

Status of This Memo 📜

this is an Internet Standards Track document 🔥

it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community. it went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741 🌸

for the current status, errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6415 💜

Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. 🫶

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. please actually read those, because they lay out your rights and restrictions for this document 🙈

if you pull Code Components out of this doc, they have to include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License ⚠️

Table of Contents 📑

1. Introduction ....................................................2
   1.1. Example ....................................................3
        1.1.1. Processing Resource-Specific Information ............4
   1.2. Notational Conventions .....................................5
2. Obtaining host-meta Documents ...................................6
3. The host-meta Document ..........................................6
   3.1. XML Document Format ........................................7
        3.1.1. The "Link" Element ..................................7
4. Processing host-meta Documents ..................................8
   4.1. Host-Wide Information ......................................9
   4.2. Resource-Specific Information ..............................9
5. Security Considerations ........................................10
6. IANA Considerations ............................................11
   6.1. The "host-meta" Well-Known URI ............................11
   6.2. The "host-meta.json" Well-Known URI .......................11
   6.3. The "lrdd" Relation Type ..................................11
Appendix A. JRD Document Format ...................................12
Appendix B. Acknowledgments .......................................15
Normative References ..............................................15

1. Introduction 🦋

okay so web protocols often need to discover host policy or metadata. the "host" isn't one single resource. it's the entity running the whole collection of resources that share a URI host [RFC3986], and those resources can be served by one or more servers 🌸

web protocols have a wide range of metadata needs, but they usually want metadata that's concise and simple to parse, and it helps when they can keep it in a shared spot that other related protocols also use ✨

here's the tricky part: there's no URI or representation that describes a host. so the usual ways of attaching per-resource metadata (like HTTP headers) just aren't available. the result is that people end up cramming host metadata into the root HTTP resource (like http://example.com/), even though that stuff isn't really specific to the root resource itself 💀

this doc defines a lightweight metadata document format for describing hosts. that's why it's called "host-meta", and it's meant for web-based protocols. it also registers the well-known URI suffix "host-meta" in the Well-Known URI Registry set up by [RFC5785] 🎀

sometimes a host-wide scope is just too coarse, though. host-meta gives you two mechanisms for resource-specific info:

  • Link Templates - links that use a URI template instead of a fixed target URI. they give you a way to write generic rules for building resource-specific links by plugging the individual resource URI into the template.
  • Link-based Resource Descriptor Documents (LRDD, pronounced 'lard') - descriptor documents with resource-specific info, usually the kind of info that can't be expressed with link templates. LRDD documents get linked to resources or host-meta documents through link templates with the "lrdd" relation type 🍓

1.1. Example 🧁

here's a simple host-meta document with both host-wide and resource-specific info for the 'example.com' host:

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>

  <!-- Host-Wide Information -->

  <Property type='http://protocol.example.net/version'>1.0</Property>

  <Link rel='copyright'
   href='http://example.com/copyright' />

  <!-- Resource-specific Information -->

  <Link rel='hub'
   template='http://example.com/hub' />

  <Link rel='lrdd'
   type='application/xrd+xml'
   template='http://example.com/lrdd?uri={uri}' />

  <Link rel='author'
   template='http://example.com/author?q={uri}' />

</XRD>

the host-wide info in that doc (the stuff that applies to the whole host) includes:

the resource-specific info in the doc includes:

  • A link template for getting real-time updates ("hub") about individual resources. since the template has no template variable, the target URI is the same for every resource.
  • An LRDD document link template ("lrdd") for grabbing extra resource-specific info that lives in a separate document for each individual resource.
  • A link template for finding info about the author of individual resources ("author").

1.1.1. Processing Resource-Specific Information 🔍

when you look up info about an individual resource (say, the resource at http://example.com/xy), the resource URI gets applied to the templates you found. that produces these links:

 <Link rel='hub'
  href='http://example.com/hub' />

 <Link rel='lrdd'
  type='application/xrd+xml'
  href='http://example.com/lrdd?uri=http%3A%2F%2Fexample.com%2Fxy' />

 <Link rel='author'
  href='http://example.com/author?q=http%3A%2F%2Fexample.com%2Fxy' />

the LRDD document for http://example.com/xy (fetched with an HTTP "GET" request) looks like this:

  <?xml version='1.0' encoding='UTF-8'?>
  <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>

    <Subject>http://example.com/xy</Subject>

    <Property type='http://spec.example.net/color'>red</Property>
    <Link rel='hub'
     href='http://example.com/another/hub' />

    <Link rel='author'
     href='http://example.com/john' />
  </XRD>

put together, the info available about the individual resource (shown as an Extensible Resource Descriptor (XRD) document, just for illustration) is:

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>

 <Subject>http://example.com/xy</Subject>

 <Property type='http://spec.example.net/color'>red</Property>

 <Link rel='hub'
  href='http://example.com/hub' />

 <Link rel='hub'
  href='http://example.com/another/hub' />

 <Link rel='author'
  href='http://example.com/john' />

 <Link rel='author'
  href='http://example.com/author?q=http%3A%2F%2Fexample.com%2Fxy' />

</XRD>

the order of links matters, and it comes from where they originally appeared in the host-meta and LRDD documents. for example, the "hub" link from the host-meta link template outranks the one in the LRDD document, because the host-meta link shows up before the "lrdd" link 👑

on the flip side, the "author" link in the LRDD document outranks the one in the host-meta document, because it shows up after the "lrdd" link 💅

1.2. Notational Conventions 📝

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] 🔥

this doc uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234]. on top of that, the following rules come from [RFC3986]: reserved, unreserved, and pct-encoded 🧚

2. Obtaining host-meta Documents 🎀

so the client gets the host-meta document for a given host by sending an HTTP [RFC2616] or HTTPS [RFC2818] GET request to the host for the "/.well-known/host-meta" path. it uses the default ports for each protocol (port 80 for HTTP and port 443 for HTTPS). whatever scope and meaning host-meta docs have when you get them through 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.

which protocol you use to get the host-meta document has big security ramifications, and we go into that in Section 5 😭

for example, this request gets the host-meta document for the 'example.com' host:

  GET /.well-known/host-meta HTTP/1.1
  Host: example.com

if the server response says the host-meta resource is somewhere else (a 301, 302, or 307 response status code), the client SHOULD try to get the resource from the location in the response. that means the host-meta document for one host MAY be retrieved from another host 👀 and if the resource isn't available or doesn't exist (like a 404 or 410 response status code), the client SHOULD infer that metadata isn't available through this mechanism 💀

the host-meta document SHOULD be served with the "application/xrd+xml" media type ✨

3. The host-meta Document ✨

okay so the host-meta doc is written in the XRD 1.0 format, which is defined in [OASIS.XRD-1.0] 💖 It's a simple, extensible XML-based schema for describing resources. This spec adds extra processing rules that are specifically for describing hosts 🧚 Documents MAY include any elements from the XRD 1.0 schema that this spec doesn't explicitly exclude.

The server MAY offer alternative representations of any XRD document it serves (host-meta, LRDD, or other XRD-based documents) 🌈 The client MAY ask for a specific one using the HTTP "Accept" request header field. If there's no "Accept" request header field in the request, or if the client asks for "application/xrd+xml", the server MUST reply with the REQUIRED XRD 1.0 XML representation described in Section 3.1. no skipping this one bestie 💅

Applications using the host-meta document MAY require the server to give them a specific alternative representation, on top of the XRD 1.0 XML one, but only when the client explicitly asks for it 🎀

A JavaScript Object Notation (JSON) Resource Descriptor, called JRD, is described in Appendix A 🦋 It is RECOMMENDED that servers offer the JRD representation alongside the XRD representation. it's giving options, and options are iconic ✨

3.1. XML Document Format

The host-meta document root MUST be an "XRD" element 👑 The document SHOULD NOT include a "Subject" element, because at this time there's no URI available to identify hosts 🙈 Using the "Alias" element in host-meta is undefined and NOT RECOMMENDED, so maybe just don't 💀

The subject (or "context IRI", as defined by [RFC5988]) of the XRD "Property" and "Link" elements is the host that the host-meta document describes 🌸 However, the subject of "Link" elements with a "template" attribute is the individual resource whose URI gets applied to the link template, as described in Section 3.1.1. that distinction is literally the whole vibe 😭

The XRD "Link" element, when used with the "href" attribute, conveys a link relation between the host described by the document and a common target URI 🍓

For example, this link declares a common copyright license for the entire scope:

<Link rel='copyright' href='http://example.com/copyright' />

A "Link" element with a "template" attribute is different though 🦋 It conveys a relation whose context is an individual resource within the host-meta document scope, and whose target is built by applying the context resource URI to the template. The template string MAY contain a URI string without any variables, to represent a resource-level relation that is identical for every individual resource 🫶

For example, a blog with multiple authors can provide info about each article's author by giving an endpoint with a parameter set to the URI of each article. Each article has a unique author, but they all share the same pattern for where that info lives 📚

<Link rel='author'
 template='http://example.com/author?article={uri}' />

3.1.1.1. Template Syntax

This spec defines a simple template syntax for URI transformation ✨ A template is a string containing brace-enclosed ("{}") variable names that mark the parts of the string to be swapped out for the matching variable values 🧚

Before substituting template variables, values MUST be encoded using UTF-8, and any character other than unreserved characters (as defined by [RFC3986]) MUST be percent-encoded per [RFC3986]. no encoding shortcuts, periodt 💅

This spec defines a single variable, "uri", which is the entire context resource URI 🔥 Protocols MAY define additional relation-specific variables and syntax rules, but they SHOULD only do that for protocol-specific relation types, and they MUST NOT change the meaning of the "uri" variable. If a client can't successfully process a template (like unknown variable names, or unknown or incompatible syntax), the parent "Link" element SHOULD be ignored 🙅‍♀️

The template syntax ABNF goes like this:

URI-Template =  *( uri-char / variable )
variable     =  "{" var-name "}"
uri-char     =  ( reserved / unreserved / pct-encoded )
var-name     =  %x75.72.69 / ( 1*var-char ) ; "uri" or other names
var-char     =  ALPHA / DIGIT / "." / "_"

For example:

Input:    http://example.com/r?f=1
Template: http://example.org/?q={uri}
Output:   http://example.org/?q=http%3A%2F%2Fexample.com%2Fr%3Ff%3D1

4. Processing host-meta Documents 🎀

Once the host-meta document has been obtained, the client processes its content based on the kind of info it wants: host-wide or resource-specific 🌈

Clients usually look for a link with a specific relation type or other attributes. In those cases the client doesn't need to process the entire host-meta document and every linked LRDD document. Instead it processes the various documents in their prescribed order until it finds the info it wants 🧠

Protocols using host-meta must indicate whether the info they seek is host-wide or resource-specific. For example: "obtain the first host-meta resource-specific link using the 'author' relation type". If both types are used for the same purpose (say, first look for resource-specific, then look for host-wide), the protocol must specify the processing order 🗺️

4.1. Host-Wide Information

When looking for host-wide info, the client MUST ignore any "Link" elements with a "template" attribute, as well as any link using the "lrdd" relation type. Everything else is scoped as host-wide 🏠

4.2. Resource-Specific Information

Unlike host-wide info, which lives solely inside the host-meta document, resource-specific info comes from host-meta link templates, as well as from linked LRDD documents 💜

When looking for resource-specific info, the client builds a resource descriptor by collecting and processing all the host-meta link templates. For each link template:

  1. The client applies the URI of the desired resource to the template, which produces a resource-specific link.
  2. If the link's relation type is other than "lrdd", the client adds the link to the resource descriptor in order.
  3. If the link's relation type is "lrdd":
    • 3.1. The client gets the LRDD document by following the scheme-specific rules for the LRDD document URI. If the document URI scheme is "http" or "https", the document is obtained via an HTTP "GET" request to the identified URI. If the HTTP response status code is 301, 302, or 307, the client MUST follow the redirection response and repeat the request with the provided location 🔁
    • 3.2. The client adds any links found in the LRDD document to the resource descriptor in order, except for any link using the "lrdd" relation type (processing is limited to a single level of inclusion). When adding links, the client SHOULD keep any extension attributes and child elements if they're present (like <Property> or <Title> elements) 🫧
    • 3.3. The client adds any resource properties found in the LRDD document to the resource descriptor in order (like <Alias> or <Property> child elements of the LRDD document <XRD> root element) 💅

5. Security Considerations 🚨

⚠️ this section is serious, so read it slowly bestie

The host-meta document is designed to be used by other applications that explicitly "opt-in" to using the facility. Therefore, any such application MUST review the specific security implications of using host-meta documents. By itself, this specification does not provide any protections or guarantees that any given host-meta document is under the control of the appropriate entity that each application requires 😰

The metadata returned by the host-meta resource is presumed to be under the control of the appropriate authority, and representative of all the resources it describes. If this resource gets compromised or ends up under the control of another party, it may be a risk to the security of the server and the data it serves, depending on which applications are using it 💀

Applications that use the host-meta document where the authenticity of the info is necessary MUST require the use of the HTTPS protocol, and MUST NOT produce a host-meta document using other means. On top of that, these applications MUST require that any redirection leading to the retrieval of a host-meta document also uses the HTTPS protocol 🔐

Since the host-meta document is authoritative for the entire host, not just the authority (the combination of scheme, host, and port) of the host-meta document server, applications MUST ensure that using a host-meta document for another URI authority does not represent a potential security exploit 🕵️‍♀️

Protocols using host-meta templates must evaluate how they construct their templates, as well as any protocol-specific variables or syntax, to make sure attackers can't abuse them. For example, a client can be tricked into following a malicious link because of a poorly built template that produces unexpected results when its variable values contain unexpected characters 😱

6. IANA Considerations 📋

6.1. The "host-meta" Well-Known URI

This spec registers the "host-meta" well-known URI in the Well-Known URI Registry, as defined by [RFC5785] 🦋

URI suffix:  host-meta

Change controller:  IETF

Specification document(s):  RFC 6415

Related information:  The "host-meta" documents obtained from the
   same host using the HTTP and HTTPS protocols (using default ports)
   MUST be identical.

6.2. The "host-meta.json" Well-Known URI

This spec registers the "host-meta.json" well-known URI in the Well-Known URI Registry, as defined by [RFC5785] 🌸

URI suffix:  host-meta.json

Change controller:  IETF

Specification document(s):  RFC 6415

Related information:  The "host-meta.json" documents obtained from
   the same host using the HTTP and HTTPS protocols (using default
   ports) MUST be identical.

6.3. The "lrdd" Relation Type

This spec registers the "lrdd" relation type in the Link Relation Type Registry defined by [RFC5988] 🧚

Relation Name:  lrdd

Description:  Refers to further information about the link's context,
   expressed as a LRDD ("Link-based Resource Descriptor Document")
   resource.  See RFC 6415 for information about processing this
   relation type in host-meta documents.  When used elsewhere, it
   refers to additional links and other metadata.  Multiple instances
   indicate additional LRDD resources.  LRDD resources MUST have an
   "application/xrd+xml" representation, and MAY have others.

Reference:  RFC 6415

Appendix A. JRD Document Format ✨

okay so bestie, this is the JSON version of everything we just covered 🎀 the JRD document format is basically a general-purpose XRD 1.0 representation, and it uses the JavaScript Object Notation (JSON) format from [RFC4627] 💖 it uses the same elements and processing rules from Section 3.1, and it's built to carry the same base functionality as the XML format. the one thing it doesn't do is extensibility, because that's outside the scope of this spec 🙈

the client MAY ask for a JRD representation with the HTTP "Accept" request header field set to application/json ✨ and the server MUST send back the HTTP "Content-Type" response header field with the value application/json 💅 if the Content-Type is anything else (or missing completely), that means the server doesn't support JRD, periodt 💀

another way the client MAY get JRD is by requesting the "host-meta.json" well-known document, making a GET request to /.well-known/host-meta.json, using the same process as /.well-known/host-meta 🦋 and if the server can't serve JRD at that spot, the server MUST respond with an HTTP 404 (Not Found) status code 😭

now the conversion part, which is giving puzzle energy 🧩 XRD elements get serialized into a JSON object like this:

o The XML document declaration and "XRD" element are discarded. 🗑️

o The "Subject" element is included as a name/value pair with the name 'subject', and the value is a string 🌸

o The "Expires" element is included as a name/value pair with the name 'expires', and the value is a string 🌸

o "Alias" elements are included as a single name/value pair with the name 'aliases', and the value is a string array holding the values of each element, in order 🍓

o "Property" elements are included as a single name/value pair with the name 'properties', and the value is an object. each element becomes a name/value pair where the "type" attribute is the name and the element value is a string value 💜 properties with empty values (the ones using the REQUIRED "xsi:nil='true'" attribute) are included as null 🫶 and if more than one "Property" element has the same "type" attribute, only the last instance is included 👑

o "Link" elements are included as a single name/value pair with the name 'links', and the value is an array where each element is an object 🦋 each attribute is a name/value pair with the attribute name as the name and the value as a string ✨

o "Link" child "Property" elements get included the same way as XRD-level "Property" elements, as a name/value pair inside the link object 🧚

o "Link" child "Title" elements are included as a single object with the name 'titles', and the value is an object where each element is a name/value pair with the "xml:lang" attribute as the name and the element value as a string value 🌈 elements without an "xml:lang" attribute get the name 'default' 🎀 if more than one "Title" element has the same (or no) "xml:lang" attribute, only the last instance is included 💀

o the conversion of any other element is left undefined 🤷‍♀️

for example, here's an XRD document 💖

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'
     xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>

  <Subject>http://blog.example.com/article/id/314</Subject>
  <Expires>2010-01-30T09:30:00Z</Expires>

  <Alias>http://blog.example.com/cool_new_thing</Alias>
  <Alias>http://blog.example.com/steve/article/7</Alias>

  <Property type='http://blgx.example.net/ns/version'>1.2</Property>
  <Property type='http://blgx.example.net/ns/version'>1.3</Property>
  <Property type='http://blgx.example.net/ns/ext' xsi:nil='true' />

  <Link rel='author' type='text/html'
        href='http://blog.example.com/author/steve'>
    <Title>About the Author</Title>
    <Title xml:lang='en-us'>Author Information</Title>
    <Property type='http://example.com/role'>editor</Property>
  </Link>

  <Link rel='author' href='http://example.com/author/john'>
    <Title>The other guy</Title>
    <Title>The other author</Title>
  </Link>
  <Link rel='copyright'
        template='http://example.com/copyright?id={uri}' />
</XRD>

...and that gets represented by this JRD document 🧁

{
  "subject":"http://blog.example.com/article/id/314",
  "expires":"2010-01-30T09:30:00Z",

  "aliases":[
    "http://blog.example.com/cool_new_thing",
    "http://blog.example.com/steve/article/7"],

  "properties":{
    "http://blgx.example.net/ns/version":"1.3",
    "http://blgx.example.net/ext":null
  },

  "links":[
    {
      "rel":"author",
      "type":"text/html",
      "href":"http://blog.example.com/author/steve",
      "titles":{
        "default":"About the Author",
        "en-us":"Author Information"
      },
      "properties":{
        "http://example.com/role":"editor"
      }
    },
    {
      "rel":"author",
      "href":"http://example.com/author/john",
      "titles":{
        "default":"The other author"
      }
    },
    {
      "rel":"copyright",
      "template":"http://example.com/copyright?id={uri}"
    }
  ]
}

ngl the "Subject" and "Alias" elements are NOT RECOMMENDED in host-meta documents 😳 they're only in the example for completeness, so don't go copying them into your host-meta files, bestie 🙅‍♀️

Appendix B. Acknowledgments 🫶

the authors wanna give a huge shoutout to everyone who gave feedback and use cases for this spec 🌟 especially Dirk Balfanz, DeWitt Clinton, Eve Maler, Breno de Medeiros, Brad Fitzpatrick, James Manger, Will Norris, Mark Nottingham, John Panzer, Drummond Reed, and Peter Saint-Andre 💜 literally iconic squad 👑

Normative References 📚

[OASIS.XRD-1.0] Hammer-Lahav, E., Ed., and W. Norris, Ed., "Extensible Resource Descriptor (XRD) Version 1.0", November 2010, <http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html>.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.

[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.

[RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006.

[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.

[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010.

[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.

Authors' Addresses 📮

Eran Hammer-Lahav (editor)

EMail: eran@hueniverse.com URI: http://hueniverse.com

Blaine Cook

EMail: romeda@gmail.com URI: http://romeda.org

📦 where this page comes from