Network Working Group E. Hammer-Lahav
Internet-Draft Yahoo!
Intended status: Informational April 30, 2010
Expires: November 1, 2010
host-meta: Web Host Metadata
draft-hammer-hostmeta-06
Abstract
This memo describes a method for locating host metadata for Web-based
protocols.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 1, 2010.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hammer-Lahav Expires November 1, 2010 [Page 1]
Internet-Draft host-meta April 2010
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Namespace and Version . . . . . . . . . . . . . . . . . . 4
1.3. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Metadata Scope . . . . . . . . . . . . . . . . . . . . . . . . 4
3. The host-meta Document Format . . . . . . . . . . . . . . . . 4
3.1. The 'hm:Host' Element . . . . . . . . . . . . . . . . . . 5
3.2. The 'Link' Element . . . . . . . . . . . . . . . . . . . . 5
3.2.1. Template Syntax . . . . . . . . . . . . . . . . . . . 6
4. Obtaining host-meta Documents . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6.1. The host-meta Well-Known URI . . . . . . . . . . . . . . . 8
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 8
Appendix B. Document History . . . . . . . . . . . . . . . . . . 8
7. Normative References . . . . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
Hammer-Lahav Expires November 1, 2010 [Page 2]
Internet-Draft host-meta April 2010
1. Introduction
Web-based protocols often require the discovery of host policy or
metadata, where host is not a single resource but the entity
controlling the collection of resources identified by URIs with a
common host as defined by [RFC3986]. While these protocols have a
wide range of metadata needs, they often define metadata that is
concise, has simple syntax requirements, and can benefit from storing
its metadata in a common location used by other related protocols.
Because there is no URI or resource available to describe a host,
many of the methods used for associating per-resource metadata (such
as HTTP headers) are not available. This often leads to the
overloading of the root HTTP resource (e.g. 'http://example.com/')
with host metadata that is not specific to the root resource, and
often has nothing to do it.
This memo registers the "well-known" URI suffix "host-meta" in the
Well-Known URI Registry established by [RFC5785], and specifies a
simple, general-purpose metadata document for hosts, to be used by
multiple Web-based protocols.
[[ Please discuss this draft on the apps-discuss@ietf.org [1] mailing
list. ]]
1.1. Example
A simple host-meta document for the 'example.com' and
'www.example.com' hosts with a link providing host-wide copyright
information and a link template providing a URI for obtaining
resource-specific author information for each resource within the
host-meta document scope:
<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'
xmlns:hm='http://host-meta.net/ns/1.0'>
<hm:Host>example.com</hm:Host>
<hm:Host>www.example.com</hm:Host>
<Link rel='license'
href='http://example.com/license'>
<Title xml:lang='en-us'>Site License Policy</Title>
</Link>
<Link rel='author'
template='http://meta.example.com?uri={uri}'>
<Title xml:lang='en-us'>Author Profile</Title>
</Link>
Hammer-Lahav Expires November 1, 2010 [Page 3]
Internet-Draft host-meta April 2010
</XRD>
1.2. Namespace and Version
The host-meta document uses the XRD 1.0 XML namespace URI
[W3C.REC-xml-names-19990114]:
http://docs.oasis-open.org/ns/xri/xrd-1.0
The XML namespace URI for the host-meta specific extension elements
defined in this specification is:
http://host-meta.net/ns/1.0
1.3. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This specification uses the namespace prefix "hm:" for the extension
Namespace URI identified in Section 1.2. Note that the choice of
namespace prefix is arbitrary and not semantically significant.
Element names without a namespace prefix belong to the XRD 1.0 XML
namespace identified in Section 1.2.
This document uses the Augmented Backus-Naur Form (ABNF) notation of
[RFC5234]. Additionally, the following rules are included from
[RFC3986]: reserved, unreserved, and host.
2. Metadata Scope
Each host-meta document describes one or more hosts. The scope MUST
be expressed explicitly within the document using the "hm:Host"
element as described in Section 3.1. The host-meta scope does not
apply to any other hostname (or sub-domain) not explicitly declared.
For example, 'example.net', 'example.com', and 'www.example.com' all
have different and non-overlapping scopes.
3. The host-meta Document Format
The host-meta document uses the XRD 1.0 document format as defined by
[OASIS.XRD-1.0], which provides a simple and extensible XML-based
schema for describing resources. This memo defines additional
elements and processing rules needed to describe hosts. Documents
MAY include any XRD element not explicitly excluded.
Hammer-Lahav Expires November 1, 2010 [Page 4]
Internet-Draft host-meta April 2010
The host-meta document root MUST be an "XRD" element. The document
SHOULD NOT include a "Subject" element, as at this time no URI is
available to identify hosts. The use of the "Alias" element in host-
meta is undefined and NOT RECOMMENDED.
This memo defines the "hm:Host" element for declaring document scope.
The subject (or "context resource" as defined by
[I-D.nottingham-http-link-header]) of the XRD "Property" and "Link"
elements are the hosts included in the document scope, with the
exception of "Link" elements with a "template" attribute for which
the subject are the individual resources included in the document
scope as described in Section 3.2.
3.1. The 'hm:Host' Element
The 'hm:Host" element is used to declare the scope of the host-meta
document and is defined as a child element of the root "XRD" element.
The parent "XRD" element MUST include one but MAY include more
"hm:Host" elements (order does not matter). If a host-meta document
includes more than one "hm:Host" element, it does not signify any
relationship between the individual hosts other than sharing the same
metadata included in the document.
The element value syntax ABNF:
Host-Element-Value = host
3.2. The 'Link' Element
The XRD "Link" element, when used with the "href" attribute, conveys
a link relation between the hosts described by the document and a
common target URI.
For example, the following link declares a common author for the
entire scope:
<Link rel='author' href='http://example.com/author' />
However, a "Link" element with a "template" attribute conveys
relations whose context are the individual resources within the host-
meta document scope, and whose target is constructed by applying each
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 information
about each article's author by providing an endpoint with a parameter
set to the URI of each article. Each article has a unique author,
Hammer-Lahav Expires November 1, 2010 [Page 5]
Internet-Draft host-meta April 2010
but all share the same pattern of where that information is located:
<Link rel='author' template='http://example.com?author={uri}' />
3.2.1. Template Syntax
This memo defines a simple template syntax for URI transformation. A
template is a string containing brace-enclosed ("{}") variable names
marking the parts of the string that are to be substituted by the
corresponding variable values.
Before substituting template variables, any value character other
than unreserved (as defined by [RFC3986]) MUST be percent-encoded per
[RFC3986].
This memo defines a single variable - "uri" - as the entire context
resource URI. Protocols MAY define additional relation-specific
variables and syntax rules, but SHOULD only do so for protocol-
specific relation types, and MUST NOT change the meaning of the "uri"
variable. If a client is unable to successfully process a template
(e.g. unknown variable names, unknown or incompatible syntax) the
parent "Link" element SHOULD be ignored.
The template syntax ABNF:
URI-Template = *( uri-char | variable )
variable = "{" var-name "}"
uri-char = ( reserved | unreserved )
var-name = "uri" | ( 1*var-char )
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