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