OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

xri message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [xri] Preview of new LRDD draft


Congrats on this new draft. I find it very readable and clear. Right now I don't have any comments except to mention that the Security Considerations section seems a little light - it doesn't mention any options for providing security around a descriptor document or the descriptor discovery process (not that anything more than general principles might be appropriate, but at least they might be mentioned).

Now I need to read the new draft of host-meta. Is it out yet (it may be and I just haven't been paying enough attention).


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)

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-

  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

  The list of Internet-Draft Shadow Directories can be accessed at

  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.


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

  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

2.  Notational Conventions

  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  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

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

  For example:

    <LINK href=""http://example.com/resource;about"

  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>;

  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):


  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

  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

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


  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


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

  o  Fixed Link-Pattern examples to include missing semicolons.


  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

  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.


  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.


  o  Initial draft.

8.  References

8.1.  Normative References

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

             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.

             Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
             Specification", World Wide Web Consortium
             Recommendation REC-html401-19991224, December 1999,

             Pemberton, S., "XHTML[TM] 1.0 The Extensible HyperText
             Markup Language (Second Edition)", World Wide Web
             Consortium Recommendation REC-xhtml1-20020801,
             August 2002,

8.2.  Informative References

             Hammer-Lahav, E. and W. Norris, "Extensible Resource
             Descriptor (XRD) Version 1.0 (work in progress)", <http://

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

  [URIQA]    Nokia, "The URI Query Agent Model",

             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,


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

Author's Address

  Eran Hammer-Lahav

  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:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]