Extensible Resource Descriptor (XRD) Version 1.0

Working Draft 01, 09 May 2009

Document identifier:
xrd-1.0-wd-01 (XML, HTML, PDF)
Locations:
Persistent version: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html
Current version: http://docs.oasis-open.org/xri/xrd/v1.0/WD01/xrd-1.0-wd01.html
Previous version:
Technical committee:
OASIS eXtensible Resource Identifier (XRI) TC
Chair:
Drummond Reed, Cordance 
Editor:
Eran Hammer-Lahav, Yahoo! 
Authors:
{Other} {People} 
Will Norris 
Declared XML Namespace:
  • http://docs.oasis-open.org/ns/xri/xrd-1.0

  • http://docs.oasis-open.org/ns/xri/xrd-1.0-trust

Abstract:

This document defines a simple generic format for resource description (XRD documents) and a protocol for obtaining XRD documents from HTTP(S) URIs.

Related Work:

This specification replaces or supersedes:

  • Extensible Resource Identifier (XRI) Resolution Version 2.0, Committee Draft 03, February 2008

This specification is related to:

  • Extensible Resource Identifier (XRI) Version 3.0, Committee Draft 01, May 2009

Status:

This document was last revised or approved by the XRI Technical Committee on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

Technical Committee members should send comments on this specification to the Technical Committee's email list. Others should send comments to the Technical Committee by using the "Send A Comment" button on the Technical Committee's web page at http://www.oasis-open.org/committees/xri.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ( http://www.oasis-open.org/committees/xri/ipr.php).

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/xri.

Notices:

Copyright İ OASIS Open 2005. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.


Table of Contents

1. Introduction
1.1. Terminology
1.2. Definitions
2. XRD Document Structure
2.1. Namespace and Schema Location
2.2. XRD Property Elements
2.3. Resource Property Elements
2.4. Related Resource Elements
3. Processing XRD Documents
3.1. Priority Attribute
3.2. Related Resource Selection
4. XRD Trust
4.1.
4.2. XRD Signing
5. Conformance

Appendixes

A. Acknowledgments (Non-Normative)
References

1. Introduction

This document defines a simple generic format for resource descriptor documents (XRD documents) and a protocol for obtaining XRD documents from HTTP(S) URIs. Resource descriptor documents provide machine-readable information about resources (resource metadata) for the purpose of promoting interoperability and assist in interacting with unknown resources that support known interfaces.

For example, a web page about an upcoming meeting can provide in its descriptor document the location of the meeting organizer's free/busy information to potentially negotiate a different time. A social network profile page descriptor can identify the location of the user's address book as well as accounts on other sites. A web service implementing an API with optional components can advertise which of these are supported.

1.1. Terminology

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 [RFC 2119].

1.2. Definitions

2. XRD Document Structure

XRD provides resource description metadata in a simple, extensible XML format. An XRD document describes properties of the roesource itself, as well as the relationship it has with other resources. While this specification defines only the XRD elements necessary to support the most common use cases, XRD can easily be extended to publish any form of metadata about the resources they describe.

2.1. Namespace and Schema Location

The following RELAX NG schema fragment defines the XML namespaces and other header information for the XRD schema:

default namespace = "http://docs.oasis-open.org/ns/xri/xrd-1.0"
namespace xrd = "http://docs.oasis-open.org/ns/xri/xrd-1.0"
namespace trust = "http://docs.oasis-open.org/ns/xri/xrd-1.0-trust"
datatypes xs = "http://www.w3.org/2001/XMLSchema-datatypes"

start = XRD

anyelementbody =
    (attribute * {text}
    | text
    | element * { anyelementbody } )*

non.xrd.element = element * - xrd:* - trust:* {
    anyelementbody
}

other.attribute = attribute * - xrd:* - trust:* { text }

The location of the normative Relax NG schema file for an XRD document as defined by this specification is: http://docs.oasis-open.org/xri/xrd/v1.0/WD01/xrd-1.0-wd01.rnc

The following URI will always reference the latest versions of this file: http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.rnc

2.2. XRD Property Elements

The first set of elements describe the XRD document itself — what it is about and when it expires. These are used to manage XRDs, particularly from the perspective of trust and caching.

2.2.1. Root Element <XRD>

This is the root element of an XRD document, and is defined by the following schema fragment:

XRD = element XRD {
    other.attribute *,
    Expires ?,
    Subject ?,
    Alias *,
    Type *,
    Link *,
    non.xrd.element *
}

2.2.2. Element <Expires>

0 or 1 per XRD element with type xs:dateTime. To promote interoperability, this date/time value should use the UTC "Z" time zone and should not use fractional seconds. An XRD consuming application may discard the XRD before the time indicated, but must not use an XRD after the time indicated. If the Discovery Document was obtained via HTTP, and the HTTP headers specified an expiry time per section 13.2 of [RFC 2616], the XRD element must not be used after the earlier of the two times.

The following schema fragment defines the Expires element:

Expires = element Expires {
    other.attribute *,
    xs:dateTime
}

2.2.3. Element <Subject>

0 or 1 per XRD with type xs:anyURI. Subject must be an absolute URI, and asserts the canonical identifier for the resource described by the XRD.

The following schema fragment defines the Subject element:

Subject = element Subject {
    other.attribute *,
    xs:anyURI
}

2.3. Resource Property Elements

These elements provide information and attributes about the resource that the XRD document is describing.

2.3.1. Element <Alias>

0 or more per XRD with type xs:anyURI. This must be an absolute URI, and provides additional non-canonical identifiers for the resource described by the XRD.

The following schema fragment defines the Alias element:

Alias = element Alias {
    other.attribute *,
    xs:anyURI
}

2.3.2. Element <Type>

0 or more per XRD with type xs:anyURI.

The Type element declares an attribute associated with the resource described by the XRD. The value of the Type element is a URI-formatted attribute-identifier. The meaning of the Type value is application-specific, and is used by the XRD provider to describe the resource to consuming applications familiar with the attribute-identifier. The attribute-identifier is used in a similar manner to XML namespace-identifiers. Attributes:

  • required (type xs:boolean). OPTIONAL. If not present, the attribute default value is false. If the required attribute is omitted or explicitly set to false, a consuming application should ignore any Type with values it does not recognize, and interact with the resource based on the values it does recognize.

    However, if the required attribute is set to true, a consuming application must not interact with the resource if it does not recognize the element value. The required attribute is used to indicate to a consuming application that some pre-defined knowledge is required in order to interact with the resource, without which undefined or potentially harmful side-effects can occur. The required attribute should not be used unless such harmful side-effects are likely.

The following schema fragment defines the Type element:

Type = element Type {
    other.attribute *,
    attribute required { xs:boolean } ?,
    xs:anyURI
}

2.4. Related Resource Elements

One of the primary uses of XRD is to describe the relationship between different resources. These elements identify and describe the other resources which are related to the resource the XRD document is describing.

2.4.1. Element <Link>

0 or more per XRD. The Link element serves as a container for metadata about the related resource, and carries similar semantics as the HTML Link element, the ATOM Link element, and the HTTP Link Header. The one distinction is that link relationships described by the Link element are between the resource described by the XRD and the linked resources, and not between the XRD itself and the linked resource. Attributes:

The following schema fragment defines the Link element:

Link = element Link {
    other.attribute *,
    attribute priority { xs:nonNegativeInteger } ?,
    Rel *,
    MediaType *,
    URI *,
    URITemplate *,
    TargetSubject ?,
    TargetAuthority ?,
    non.xrd.element *
}

2.4.2. Element <Rel>

0 or more per Link with type xs:anyURI. This defines the semantics of the relationship between the resource described by the XRD and the linked resource. Rel is semantically equivalent to the Link Relationship Types defined in [HTTP Link Header]. It is important to note that they do not identify any property or attribute of the linked resource. Rather, they describe only how the resource described by the XRD is related to the linked resource.

The following schema fragment defines the Rel element:

Rel = element Rel {
    other.attribute *,
    xs:anyURI
}

2.4.3. Element <MediaType>

0 or more per Link with type xs:string. This provides a hint as to the media type of the content available at the linked resource. The value of this element must be of the form of a media type defined in [RFC 2046].

The following schema fragment defines the MediaType element:

MediaType = element MediaType {
    other.attribute *,
    xs:string
}

2.4.4. Element <URI>

0 or more per Link with type xs:anyURI. Provides the URI where the linked resource can be found and used or retrieved. If no URI element is defined, it is assumed the URI can be obtained by other means not specified in this specification. Attributes:

The following schema fragment defines the URI element:

URI = element URI {
    other.attribute *,
    attribute priority { xs:nonNegativeInteger } ?,
    xs:anyURI
}

2.4.5. Element <URITemplate>

0 or more per Link with type xs:string. The template syntax provides a simple format 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 variable values. The dictionary of allowed variable names is defined by one or more Rel values of the enclosing Link. A template is transformed into a URI by substituting the variables with their calculated value. If a variable name is prefixed by "%", any character in the variable value other than unreserved must be percent-encoded per [RFC 3986].

This specification does not define when or how template variables are interposed into link templates. Link relationship values that wish to allow templating should specify such details.

Attributes:

The following schema fragment defines the URITemplate element:

URITemplate = element URITemplate {
    other.attribute *,
    attribute priority { xs:nonNegativeInteger } ?,
    xs:string
}

2.4.6. Element <trust:TargetSubject>

0 or 1 per Link with type xs:anyURI. This element is used for synonym trust verification, and identifies the canoncial URI for the targetted resource. This may be different than the value of a URI or URITemplate element, because those elements may assert a URI for a linked resource that is non canonical. See Section 4, “XRD Trust”

The following schema fragment defines the TargetSubject element:

TargetSubject = element trust:TargetSubject {
    other.attribute *,
    xs:anyURI
}

2.4.7. Element <trust:TargetAuthority>

0 or 1 per Link with type xs:string. {TODO} See Section 4, “XRD Trust”

The following schema fragment defines the TargetSubject element:

TargetAuthority = element trust:TargetAuthority {
    other.attribute *,
    xs:string
}

3. Processing XRD Documents

{TODO: some general note about consuming XRDs}

3.1. Priority Attribute

XRD allows the Link, URI, URITemplate, and SourceAlias elements to appear multiple times within the same parent element to provide redundancy, flexibility, or other purposes. When these elements appear more than once within the same parent, XRD publishers should use the priority attribute to prioritize selection of these element instances.

The priority attribute type is xs:nonNegativeInteger - its value must be a non-negative integer value. The attribute works in a similar manner to DNS records priority, where the lowest value has the highest priority. This means zero has the highest priority and infinity - represented as the value null - carries the lowest priority. If omitted, the element's priority value defaults to null, however, instead of omitting the attribute, it is recommended to set the priority value to 10. When a publisher wishes to indicate a very low priority, it is recommended to use a large finite value (100 or higher) rather than explicitly use the value null.

Consuming applications should select the element with the highest priority - the lowest numeric value of the priority attribute. In the following example, the URIs decreasing order of priority is 0, 10, 11, 25, and last null and the element with the omitted attribute (equally low).

<Link>
    <URI priority="10">http://example.com/second</URI>
    <URI priority="25">http://example.com/fourth</URI>
    <URI priority="11">http://example.com/third</URI>
    <URI priority="0">http://example.com/highest</URI>
    <URI>http://example.com/lowest</URI>
</Link>

If two or more instances of the same element type have identical priority attribute values (including the null value), the consuming application should select one of the instances at random. The application should not choose the first instance that appears in XML document order. This is needed to support the publisher's redundancy or load balancing intentions.

The element selected according to these rules is referred to as the highest priority element. If this element is subsequently disqualified from the set of qualified elements, the consuming application should attempt to select the next highest priority element. This process should be continued for all other instances of the qualified elements until success is achieved or all instances are exhausted.

3.1.1. Priority of <URI> and <URITemplate> elements

The URI for a related resource can be expressed using two different elements, URI and URITemplate, which differ only in the fact that templates require addtional processing in order to obtain the final URI. Therefore, elements of both types should be combined and sorted together in order to obtain the URI of highest priority. In the following example, the highest priority URI would the resultant URI from processing the template "{uri};service".

<Link>
    <URI priority="20">http://example.com/</URI>
    <URITemplate priority="10">{uri};service</URI>
</Link>

3.2. Related Resource Selection

Based on the consuming application's needs, the application defines a selection criteria based on the presence (or lack of) certain resource relationship values and media-types. The selection criteria can be any combination of Rel and MediaType values desired by the application, as well as looking for specific resource URIs. For example, an application can look for all related resources with an image media-type, the URI of a related resource with a SAML authentication relationship, or the properties of a specific related resource given its URI.

If the selection criteria place higher preference on the presence of certain relationships or media-types over others, it is handled by performing multiple selections. Each selection is assigned preference order based on the consuming application's needs and the selection results are compared to determine the most desired set. For example, if an application is looking for all image resources, giving higher preference to the JPEG formats over PNG, it will perform two selection processes, one for each media-type, and assign the resources in the JPEG set a higher preference value.

The consuming application performs the following steps in order to select the desired related resource descriptions:

  • Each Link element is compared against the selection criteria by comparing the values of the Rel, MediaType, URI, and URITemplate elements to those defined by the selection criteria.

  • If more than one Link element is matched, the consuming application should use the priority attribute values to find the highest priority element as defined in Section 3.1, “Priority Attribute”.

  • Within the priority sorted list of matching Link elements, if more than one URI or URITemplate elements are present, the consuming application should use the priority attribute values to find the highest priority element as defined in Section 3.1.1, “Priority of <URI> and <URITemplate> elements”.

4. XRD Trust

{TODO}

4.1. 

4.2. XRD Signing

{TODO: how to sign XRD, how to verify signatures, and how signed XRDs may be returned to a consuming application (signature in HTTP Header, <SignatureLocation> element, or application/x-www-form-urlencoded encoded response containing 'signature' and 'xrd'. For the base64 encoded stuff, borrow language from SAML Simple Sign)}

{TODO: SignatureLocation element is required (cardinality: 1). Two special values will be defined which instruct consuming applicaiton to look for signature in response header or body.}

5. Conformance

{TODO}

A. Acknowledgments (Non-Normative)

The following individuals have participated in the creation of this specification and are gratefully acknowledged (note that the itemized list uses spacing="compact" to remove the space between list items in the printed result):

  • Mary Baker

  • Jane Doe, Example Corporation

  • John Able, Other Example Corporation

References

[RFC 2046] N. Freed, N. Borenstein Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. IETF (Internet Engineering Task Force). 1996.

[RFC 2119] S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF (Internet Engineering Task Force). 1997.

[RFC 2606] E. Eastlake, A. Panitz Reserved Top Level DNS Names. IETF (Internet Engineering Task Force). 1999.

[RFC 2616] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee Hypertext Transfer Protocol -- HTTP/1.1. IETF (Internet Engineering Task Force). 1999.

[RFC 3986] T. Berners-Lee, R. Fielding, L. Masinter Uniform Resource Identifiers (URI): Generic Syntax. IETF (Internet Engineering Task Force). 2005.

[RFC 4287] M. Nottingham The Atom Syndication Format. IETF (Internet Engineering Task Force). 2005.

[HTML 4.01] D. Raggett HTML 4.01 Specification. W3 Recommendation. 1999

[HTTP Link Header] M. Nottingham Link Relations and HTTP Header Linking. IETF (Internet Engineering Task Force) Draft. 2009.

[Site Meta] M. Nottingham, E. Hammer-Lahav Host Metadata for the Web. IETF (Internet Engineering Task Force) Draft. 2009.

[XRI Resolution 2.0] G. Wachob Extensible Resource Identifier (XRI) Resolution V2.0. February 2008.

[LRDD] E. Hammer-Lahav Link-based Resource Descriptor Discovery. IETF (Internet Engineering Task Force) Draft. 2009.