Re: [xri] Preview of new LRDD draft

On Mon, Oct 26, 2009 at 5:12 PM, Eran Hammer-Lahav <eran@hueniverse.com> wrote:

Network Working Group E. Hammer-Lahav
Internet-Draft Yahoo!
Intended status: Informational October 27, 2009
Expires: April 30, 2010

Link-based Resource Descriptor Discovery (LRDD)
draft-hammer-discovery-04

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.

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."

The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

This Internet-Draft will expire on April 30, 2010.

Copyright Notice

Copyright (c) 2009 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 in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.

Abstract

This memo describes a process for obtaining information about a
resource identified by a URI using Web linking. The 'information
about a resource', a resource descriptor, provides machine-readable
information that aims to increase interoperability and enhance
interactions with the resource. This memo describe methods for
locating and obtaining descriptors, but leaves the descriptor format
and its interpretation out of scope.

Table of Contents

1. Introduction
2. Notational Conventions
3. Process Template
4. Identifying Descriptor Location
4.1. The 'LINK' Element
4.2. The HTTP Link Header
4.3. The Host Metadata Document
4.4. Method Selection Profiles
5. Obtaining Resource Descriptor
6. Security Considerations
7. IANA Considerations
Appendix A. Acknowledgments
Appendix B. Document History
8. References
8.1. Normative References
8.2. Informative References
Author's Address

1. Introduction

[[ This revision is a rough edit submitted early to share the
document progress and new direction, using a process template
approach. Feedback should ignore editorial changes. ]]

This memo describes a simple process for locating descriptors for
URI-identified resources using the Web Linking framework described by
[I-D.nottingham-http-link-header]. Resource descriptors are machine-
readable documents (usually based on well known serialization
languages such as XML, RDF, and JSON), which provide information
about resources (resource metadata) for the purpose of promoting
interoperability and assist with interacting with unknown resources
that support known interfaces.

Given the wide range of metadata needs, no single descriptor format
or retrieval method can adequately accommodate every use case. While
there are many methods for obtaining resource descriptors (e.g., HTTP
headers, WebDAV's PROPFIND [RFC4918], HTTP OPTIONS, URIQA's MGET
[URIQA]), and multiple ways in which Web Linking can be used to
associate a resource to its descriptor, LRDD provides a reusable
process template to accomodate the common discovery needs of many Web
protocols.

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.

This memo describes the first step in the discovery process in which
the resource descriptor document is located and retrieved. Other
steps, which are outside the scope of this memo, include parsing the
descriptor document based on its format (such as
[W3C.PR-powder-dr-20090604] and [OASIS.XRD-1.0]) and utilizing it
based on the application.

Please discuss this draft on the apps-discuss@ietf.org [1] mailing
list.

2. 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].

3. Process Template

This memo define a process template for associating and obtaining
resource descriptors. While the process is identical in any LRDD
implementation, some of the parameters are protocol-specific and MUST
be defined when LRDD is referenced:

o Relation Type - LRDD uses typed link relations as defined by
[I-D.nottingham-http-link-header] to associate a resource with its
descriptor document. Protocols SHOULD choose a relation type
carefully to ensure it does not conflict with existing or future
deployments using the same relation type. The relation type MAY
be a registered short name or an extension URI.

o Method Selection Profile - LRDD defines three profiles for
selecting links across the three linking methods: resource-
priority, host-priority, and equal-priority as described in
Section 4.4.

For example, a protocol utilizing LRDD can reference it by
instructing its clients to "use LRDD to obtain a resource description
using relation type 'http://example.com/rel/description' and the
'resource-priority' selection profile".

4. Identifying Descriptor Location

The descriptor location (URI) is a function of the resource URI.
Each of the following three methods is performed by using the
resource URI to identify its descriptor URI.

The methods described in this memo express the location of the
resource descriptor as a link relation, utilizing the link framework
defined by [I-D.nottingham-http-link-header]. The association of a
descriptor document with the resource it describes is declared using
the selected link relation type as described in Section 3.

In many cases, a request for one URI leads to requesting other URIs,
as is the case with HTTP redirections. Because the decision whether
to use such URIs is application-specific, LRDD is constrained to a
single URI identifying the resource. Any other resource URIs
received while performing discovery MUST be considered as a separate
and discrete input into the discovery function. If a resource URI
obtained during the performance of these methods is found to be more
relevant to the application, the discovery process MUST be restarted
with the new resource URI as its input.

For example, an HTTP HEAD request for URI A returns a redirection
(307) response with a set of links, and identifies the temporary
location of the representation at URI B. An HTTP HEAD request for URI
B returns a successful (200) response with its own set of links. An
application MAY choose to define a process in which the two sets of
links are obtained, prioritized, and utilized, however, it MUST do so
by explicitly instructing the client to perform LRDD multiple times,
as each is considered separate and distinct process.

Each method presents a different set of requirements. The criteria
used to determine which methods a server SHOULD support and client
SHOULD attempt are based on a combination of factors (the order in
which applicable methods are attempted is described in Section 4.4):

o The ability to offer and obtain a representation of the resource
by dereferencing its URI.

o The availability of a representation supporting 'LINK' markup
compatible with [I-D.nottingham-http-link-header].

o The availability of an HTTP representation of the resource and the
ability to provide and access link information in its response
header.

4.1. The 'LINK' Element

The 'LINK' element method is limited to resources with an available
markup representation that supports typed-relations using the 'LINK'
element, such as HTML [W3C.REC-html401-19991224], XHTML
[W3C.REC-xhtml1-20020801], and Atom [RFC4287]. Other markup formats
are permitted as long as the semantics of their 'LINK' elements are
fully compatible with the link framework defined in
[I-D.nottingham-http-link-header]. This method requires the
retrieval of a resource representation. While HTTP is the most
common transport for such documents, this method is transport
independent.

For example:

<LINK href=""http://example.com/resource;about"
rel="http://example.com/rel/description"
type="application/xrd+xml">

A client trying to obtain the location of the resource's descriptor
using this method SHALL:

1. Retrieve a representation of the resource using the applicable
transport for that resource URI. If the markup document is
obtained using HTTP, it MUST only be used by the client if the
document is a valid representation of the resource identified by
the HTTP request URI, typically in a response with a successful
(2xx) or redirection (3xx) status code. If no such valid
representation of the request URI is found, the method fails.

2. Parse the document as defined by its format specification and
look for 'LINK' elements with a "rel" attribute value containing
the chosen relation type. The client MUST obey the document
markup schema and ignore any invalid elements (such as 'LINK'
elements outside the 'HEAD' section of an HTML document). This
is done to avoid unintentional markup from other parts of the
document to be used for discovery purposes, which can have vast
impact on usability and security.

3. The descriptor location is obtained from the value of the "href"
attribute in the selected 'LINK' element. If more than one
matching link is found, process them in document order until a
descriptor document is successfully obtained as described in
Section 5.

Some 'LINK' elements can allow multiple relation types in a single
"rel" attribute (for example 'rel="http://example.com/rel/description
copyright"'). Clients MUST properly process such multiple relation
"rel" attributes as defined by the format specification.

4.2. The HTTP Link Header

The HTTP Link header method is limited to resources for which an HTTP
GET or HEAD request returns a 2xx, 3xx, or 4xx HTTP response
[RFC2616]. This method uses the Link header defined in
[I-D.nottingham-http-link-header] and requires the retrieval of a
resource representation header.

For example:

Link: <http://example.com/resource;about>;
rel="http://example.com/rel/description";
type="application/xrd+xml"

A client trying to obtain the location of the resource's descriptor
using this method SHALL:

1. Make an HTTP (or HTTPS as required) GET or HEAD request to the
resource URI to obtain a valid response header. If the HTTP
response carries a status code other than successful (2xx),
redirection (3xx), or client error (4xx), the method fails.

2. Parse the HTTP response header and look for Link headers with a
"rel" parameter value containing the chosen relation type.

3. The descriptor location is obtained from the "<>" enclosed URI-
reference in the selected Link header. If more than one matching
link is found, process them in any order until a descriptor
document is successfully obtained as described in Section 5.

Link headers can include multiple relation types in a single "rel"
parameter (for example 'rel="http://example.com/rel/description
copyright"'). Clients MUST properly process such multiple relation
"rel" attributes as defined by [I-D.nottingham-http-link-header].

4.3. The Host Metadata Document

The host metadata document method is available for any resource
identified by a URI whose authority supports the host-meta document
defined in [I-D.hammer-hostmeta]. This method does not require
obtaining any representation of the resource, and operates solely
using the resource URI.

The link relation between the resource URI and the descriptor URI is
obtained by using a template contained in the host-meta document. By
applying the host-wide template to an individual resource URI, a
resource-specific link is produced which can be used to indicate the
location of the descriptor document for that resource, bypassing the
need to access or provide a representation for it.

For example (line breaks are for formatting only, and are not allowed
in the document):

<Link>
<Rel>http://example.com/rel/description</Rel>
<URITemplate>{+uri};about</URITemplate>
<MediaType>application/xrd+xml"</MediaType>
</Link>

A client trying to obtain the location of the resource's descriptor
using this method SHALL:

1. Retrieve the host-meta document for URI's authority as defined by
[I-D.hammer-hostmeta] section 4. If the request fails to
retrieve a valid host-meta document, the method fails.

2. Parse host-meta document and look for 'Link' elements with a
"rel" attribute value containing the chosen relation type and a
'URITemplate' child element.

3. The descriptor location is constructed by applying the template
obtained from the selected Link element to the resource URI as
described by [I-D.hammer-hostmeta] section 3.2.1. If more than
one matching link is found, process them in document order until
a descriptor document is successfully obtained as described in
Section 5.

4.4. Method Selection Profiles

LRDD defines three method selection profiles for deciding the order
in which each of the three methods (when applicable) MUST be
attempted until a descriptor document is obtained successfully:

o Resource-Priority - Priority is given to the individual resource
over the linking policies of the host. The order in which the
methods SHALL be attempted is: 'LINK' element, 'Link' header, and
host-meta.

o Host-Priority - Priority is given to the linking policies of the
host over those defined by individual resources. The order in
which the methods SHALL be attempted is: host-meta, 'Link' header,
and 'LINK' element.

o Equal-Priority - The protocol-specific links from each method must
produce the same resource descriptor document and MAY be attempted
in any order, as long as the method is applicable to the resource
type and URI.

5. Obtaining Resource Descriptor

Once the desired descriptor URI has been obtained, the descriptor
document is retrieved. If the descriptor URI scheme is "http" or
"https", the document is obtained via an HTTP GET request to the
identified URI. The client MUST obey HTTP redirections (3xx), and
the descriptor document is considered valid only if retrieved with a
successful HTTP response status (2xx).

If the descriptor format or media type do not match those supported
by the protocol, the client SHOULD ignore the descriptor document and
treat it as if it was linked using a different relation type than the
selected protocol relation type as described in Section 3.

6. Security Considerations

The methods used to perform discovery are not secure, private or
integrity-guaranteed, and due caution should be exercised when using
them. Applications that perform LRDD SHOULD consider the attack
vectors opened by automatically following, trusting, or otherwise
using links gathered from 'LINK' elements, HTTP Link headers, or
host-meta documents.

7. IANA Considerations

No IANA actions are required by this document.

Appendix A. Acknowledgments

Inspiration for this memo derived from previous work on a descriptor
format called XRDS-Simple, which in turn derived from another
descriptor format, XRDS. Previous discovery workflows include Yadis
which is currently used by the OpenID community. While suffering
from significant shortcomings, Yadis was a breakthrough approach to
performing discovery using extremely restricted hosting environments,
and this memo has strived to preserve as much of that spirit as
possible.

The author wishes to thanks the OASIS XRI TC and WebFinger
communities for their support, encouragement, and enthusiasm for this
work. Special thanks go to Phil Archer, Lisa Dusseault, Joseph
Holsten, Mark Nottingham, John Panzer, Drummond Reed, and Jonathan
Rees for their invaluable feedback.

Appendix B. Document History

[[ to be removed by the RFC editor before publication as an RFC ]]

-04

o Focused memo on Web-linking-based discovery only instead of
positioning it as better or more appropriate than other methods.
Removed analysis appendix and discussion of discovery types and
removed many informative references. Rewrote as a process
template with protocol-specific parameters.

o Moved the Link-Pattern field and template syntax to new host-meta
draft.

-03

o Added protocol name LRDD (pronounced 'lard').

o Fixed Link-Pattern examples to include missing semicolons.

-02

o Changed focus from an HTTP-based process to Link-based process.

o Completely revised and restructured document for better clarity.

o Realigned the methods to produce consistent results and changed
the way redirections and client-errors are handled.

o Updated to use newer version of site-meta, now called host-meta,
including a new plaintext-based format to replace the previous XML
format.

o Renamed Link-Template to Link-Pattern to avoid future conflict
with a previously proposed Link-Template HTTP header.

o Removed support for the "scheme" Link-Template parameter.

o Replaced restrictions with interoperability recommendations.

o Added IANA considerations per new host-meta registry requirements.

-01

o Rename 'resource discovery' to 'descriptor discovery'.

o Added informative reference to Metalink.

o Clarified that the resource descriptor URI can use any URI scheme,
not just "http" or "https".

o Removed comment regarding redirects when using 'LINK' Elements.

o Clarified that HTTPS must be used with "https" URIs for both Link
headers and host-meta retrieval.

o Removed DNS verification step for host-meta with schemes other
then "http" and "https". Replaced with a general discussion of
authority and a security consideration comment.

o Organized host-meta section into another sub-section level.

o Enlarged the template vocabulary from a single "uri" variable to
include smaller URI components.

o Added informative reference to RFC 2295 in analysis appendix.

-00

o Initial draft.

8. References

8.1. Normative References

[I-D.hammer-hostmeta]
Hammer-Lahav, E., "Host-Meta: Web Host Metadata",
draft-hammer-hostmeta-01 (work in progress), October 2009.

[I-D.nottingham-http-link-header]
Nottingham, M., "Web Linking",
draft-nottingham-http-link-header-06 (work in progress),
July 2009.

[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.

[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
Syndication Format", RFC 4287, December 2005.

[W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>.

[W3C.REC-xhtml1-20020801]
Pemberton, S., "XHTML[TM] 1.0 The Extensible HyperText
Markup Language (Second Edition)", World Wide Web
Consortium Recommendation REC-xhtml1-20020801,
August 2002,
<http://www.w3.org/TR/2002/REC-xhtml1-20020801>.

8.2. Informative References

[OASIS.XRD-1.0]
Hammer-Lahav, E. and W. Norris, "Extensible Resource
Descriptor (XRD) Version 1.0 (work in progress)", <http://
www.oasis-open.org/committees/download.php/34815/
xrd-1.0-cd01.html>.

[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.

[URIQA] Nokia, "The URI Query Agent Model",
<http://sw.nokia.com/uriqa/URIQA.html>.

[W3C.PR-powder-dr-20090604]
Smith, K., Perego, A., and P. Archer, "Protocol for Web
Description Resources (POWDER): Description Resources",
World Wide Web Consortium PR PR-powder-dr-20090604,
June 2009,
<http://www.w3.org/TR/2009/PR-powder-dr-20090604>.

URIs

[1] <https://www.ietf.org/mailman/listinfo/apps-discuss>

Author's Address

Eran Hammer-Lahav
Yahoo!

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

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

xri message