One document matched: draft-hammer-discovery-04.xml
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<rfc category="info" ipr="trust200902" docName="draft-hammer-discovery-04">
<?rfc strict="yes" ?>
<?rfc toc="yes" ?>
<?rfc tocdepth="2" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<front>
<title abbrev="LRDD">LRDD: Link-based Resource Descriptor Discovery</title>
<author initials="E" surname="Hammer-Lahav" fullname="Eran Hammer-Lahav">
<organization>
Yahoo!
</organization>
<address>
<email>eran@hueniverse.com</email>
<uri>http://hueniverse.com</uri>
</address>
</author>
<date year="2010"/>
<abstract>
<t>
LRDD (pronounced 'lard') provides a process for obtaining information about a resource
identified by a URI. The 'information about a resource' - a resource descriptor - provides
machine-readable information that aims to increase interoperability and enhance
interactions with the resource. LRDD provides a narrow and well-defined set of rules for
obtaining and processing link-based descriptors (found in multiple places such as HTTP
headers, document markup, and resource descriptors) which are often required for security
and consistent client behavior.
</t>
</abstract>
<note title="Editorial Note (to be removed by RFC Editor)">
<t>
Please discuss this draft on the
<eref target="https://www.ietf.org/mailman/listinfo/apps-discuss">apps-discuss@ietf.org</eref>
mailing list.
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
LRDD defines a simple process for locating resource descriptors for URI-identified
resources. Resource descriptors are machine-readable documents which provide information
about resources (resource metadata) for the purpose of promoting interoperability and
assist in interacting with unknown resources that support known interfaces.
</t>
<t>
For example, a web page about an upcoming meeting can provide in its descriptor 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.
</t>
<t>
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., links, HTTP headers, WebDAV's PROPFIND <xref target="RFC4918" />,
HTTP OPTIONS, URIQA's MGET <xref target="URIQA" />), LRDD utilizes the Web Linking
framework defined in <xref target="I-D.nottingham-http-link-header"/>. LRDD defines a
narrow profile of Web Linking for obtaining and processing link-based descriptors to
accommodate the common discovery needs of many Web protocols.
</t>
<t>
In LRDD, the resource descriptor is constructed by obtaining and aggregating links and
descriptor documents from multiple sources (e.g. HTTP headers, document markup, site-meta).
In most cases, clients do not need to construct a complete resource descriptor, but instead
process the information in a specific order until the desired information is found.
</t>
<section title="Example">
<t>
An article published by a website allows readers to post comments and provide the web
address of their own blog. The article page includes an avatar (a photo of the reader)
when displaying comments, which is obtained by performing discovery on the web address
provided by the reader (if supported by the reader's blog).
</t>
<t>
After receiving a comment from Jane which has her own blog at
<spanx style="verb">http://jane.example.com/blog</spanx>, the website perform LRDD discovery
to try and obtain the Jane's photo.
</t>
<figure>
<preamble>
First, the website determines the source priority order for Jane's blog by fetching its
host-meta document from <spanx style="verb">http://jane.example.com/.well-known/host-meta</spanx>:
</preamble>
<artwork>
<![CDATA[
<?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>jane.example.com</hm:Host>
<Property type='http://lrdd.net/priority/resource' />
<Link rel='lrdd' template='http://jane.example.com?lrdd={uri}'>
</XRD>
]]>
</artwork>
<postamble>
which indicates the blog is using Resource-priority (giving higher priority to links
provided by the resource itself over those defined by the global policy). Since Jane's
blog uses Resource-priority, the website looks for <spanx style="verb">avatar</spanx>
links in this order: <Link> elements, HTTP Link headers, and then host-meta link
templates.
</postamble>
</figure>
<figure>
<preamble>
To obtain a markup representation of Jane's blog, the website makes an HTTP
<spanx style="verb">GET</spanx> request to <spanx style="verb">http://jane.example.com/blog</spanx>:
</preamble>
<artwork>
<![CDATA[
GET /blog HTTP/1.1
Host: jane.example.com
Accept: text/html
]]>
</artwork>
</figure>
<figure>
<preamble>
And receives back (HTML simplified for display purposes):
</preamble>
<artwork>
<![CDATA[
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Link: <http://jane.example.com/author>; rel="author"
<html>
<head>
<link href='http://jane.example.com/image' rel='avatar' />
</head>
<body>
<h1>Jane's Blog</h1>
</body>
</html>
]]>
</artwork>
</figure>
<t>
The HTML markup includes the desired link. The website can fetch Jane's photo from
<spanx style="verb">http://jane.example.com/image</spanx>.
</t>
<t>
Now that it has Jane's photo, the website is looking for a short description of Jane to
include with her comment. It performs another LRDD discovery, this time looking for an
<spanx style="verb">about</spanx> link. Repeating the same process, the website looks for
qualified <Link> elements in Jane's blog HTML markup and finds none. It then looks
for a LRDD document - a descriptor document containing additional information about the
resource - which uses the <spanx style="verb">lrdd</spanx> link relation. It finds none
in the HTML representation.
</t>
<t>
In Resource-priority, the next source is HTTP header. The HTTP header (shown above with
the HTML response) includes a qualified link to Jane's author page.
</t>
<t>
Before it can display Jane's photo and description, the website needs to find the copyright
license used by Jane's blog. It performs another LRDD discovery looking for a link with
a <spanx style="verb">copyright</spanx> relation type. It fails to find such link in the
HTML markup as well as a link to a LRDD document. It then tries and fails to find a
<spanx style="verb">copyright</spanx> link in the HTTP header or a LRDD document linked from
the header.
</t>
<t>
The website then proceeds to the host-meta source, looking for link templates. It fails
to find a link to a copyright statement, but it does find a link to a LRDD document.
It obtains the LRDD document for Jane's blog by applying the blog's URI to the template:
</t>
<figure>
<artwork>
<![CDATA[
http://jane.example.com?lrdd=http%3A%2F%2Fjane.example.com%2Fblog
]]>
</artwork>
</figure>
<figure>
<preamble>
and obtains the LRDD document for Jane's blog:
</preamble>
<artwork>
<![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Subject>http://jane.example.com/blog</Subject>
<Link rel='copyright' href='http://jane.example.com/copyright'>
</XRD>
]]>
</artwork>
</figure>
<t>
The LRDD document provided by the host-meta link template includes a link to the
copyright statement. The website now has all the information it needs to display Jane's
comment along with her photo and description on the article page.
</t>
</section>
<section title="Notational Conventions">
<t>
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
<xref target="RFC2119" />.
</t>
</section>
</section>
<section title="Resource Descriptor" anchor="descriptor">
<t>
The LRDD resource descriptor is the aggregation of links and descriptor documents obtained
from four sources (when applicable and available):
<list style="symbols">
<t>
host-meta - links generated by applying the resource URI to the link templates provided
by the host's host-meta document as defined in <xref target="I-D.hammer-hostmeta" />.
</t>
<t>
HTTP Link headers - links included in the HTTP response header to an <xref target="RFC2616">HTTP</xref>
<spanx style="verb">HEAD</spanx> or <spanx style="verb">GET</spanx> request for the resource.
</t>
<t>
<Link> elements - links included in the resource representation markup.
</t>
<t>
LRDD documents - links and other metadata contained in
<xref target="OASIS.XRD-1.0">XRD</xref> documents linked to from any of the previous
three link sources using the <spanx style="verb">lrdd</spanx> relation type.
</t>
</list>
</t>
<t>
LRDD clients usually look for a link with a specific relation type or other well-typed
metadata. In such cases, the client does not need to construct the entire resource
descriptor, but instead, process the various sources in their prescribed order until the
desired information is found.
</t>
</section>
<section title="Discovery Process">
<t>
The LRDD process begins with the URI of the resource being discovered and the type of
information being sought:
<list style="symbols">
<t>
Link of a given relation type - the client is looking for a link with a specific
relation type and other link attributes such as media type or relation-specific
attributes.
</t>
<t>
Metadata contained within a LRDD-linked XRD document - the client is seeking
information other than a link to another resource, such as resource properties or other
structured metadata.
</t>
</list>
</t>
<t>
The client MUST first determine the host source priority order as described in
<xref target="order" />. Once the order is determined, the client process each of the
sources listed in <xref target="sources" /> as follows:
<list style="numbers">
<t>
If the information being sought is a link: find a link matching the desired criteria by
processing the links in order. If a qualified link is found, the process ends successfully.
</t>
<t>
Find the first link with the <spanx style="verb">lrdd</spanx> relation type. The link's
media type attribute MUST be set to <spanx style="verb">application/xrd+xml</spanx>
if present. The link's target is the location of the LRDD document. Any
<spanx style="verb">lrdd</spanx> links other than the first MUST be ignored. If no
qualified link is found, continue with the next source.
</t>
<t>
Obtain the LRDD document by following the scheme-specific rules for the LRDD
document's URI. If the document's URI scheme is "http" or "https", the document is
obtained via an HTTP <spanx style="verb">GET</spanx> request to the identified URI.
The client MUST obey HTTP redirections (3xx). The document is considered valid
only if retrieved with a successful HTTP response status (2xx) and is a valid XRD
document per <xref target="OASIS.XRD-1.0" />. If no valid document is found,
continue with the next source.
</t>
<t>
If the information being sought is a link: find a link matching the desired criteria by
processing the LRDD document as defined by <xref target="OASIS.XRD-1.0" />
section 4. If a qualified link is found, the process ends successfully.
</t>
<t>
If the information being sought is something other than a link: parse the LRDD document
as defined by <xref target="OASIS.XRD-1.0" />, looking for the desired metadata. If
the desired information is found, the process ends successfully.
</t>
<t>
If the information being sought is not found, continue with the next source. If all the
sources have been exhausted, the process ends unsuccessfully.
</t>
</list>
</t>
<section title="Source Priority Order" anchor="order">
<t>
LRDD descriptors include information contained or linked to from three sources:
host-meta link templates, HTTP Link headers, and <Link> elements. To ensure
consistent client behavior and to enable hosts to set their own security policy with
regard to metadata authority, LRDD provides two processing profiles:
<list style="symbols">
<t>
Host-priority - Priority is given to links set by the host policy (via
host-meta and HTTP Link headers) over those set by each individual resources (via
<Link> elements). Clients MUST process the three sources in the following
order: host-meta link templates, HTTP Link headers, and <Link> elements.
</t>
<t>
Resource-priority - Priority is given to the individual resource over the policies of
the host. Clients MUST process the three sources in the following order: <Link>
elements, HTTP Link headers, and host-meta link templates.
</t>
</list>
</t>
<t>
Host-priority is the default source priority order. Hosts that wish to use
Resource-priority MUST declare it by setting the LRDD priority property in their
host-meta document: <spanx style="verb">http://lrdd.net/priority/resource</spanx>. The
priority property does not have a value.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
<![CDATA[
<?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>
<Property type='http://lrdd.net/priority/resource' />
</XRD>
]]>
</artwork>
</figure>
</section>
<section title="Information Sources" anchor="sources">
<t>
Each of the information sources supported by LRDD presents a different set of
requirements and benefits. The criteria used to determine which sources a server
MAY support are based on a combination of factors:
<list style="symbols">
<t>
The ability to offer and obtain a representation of the resource by dereferencing its
URI.
</t>
<t>
The availability of a representation supporting <Link> markup compatible with
<xref target="I-D.nottingham-http-link-header" />.
</t>
<t>
The availability of an HTTP representation of the resource and the ability to provide
and access link information in its response header.
</t>
</list>
</t>
<section title="host-meta Link Templates">
<t>
The host-meta document source is available for any resource identified by a URI
with an authority that supports the host-meta document as defined in
<xref target="I-D.hammer-hostmeta" />. This method does not require obtaining any
representation of the resource, and operates solely using the resource URI.
</t>
<t>
Links between the resource URI and other resources are expressed by link templates
as defined by <xref target="I-D.hammer-hostmeta" /> section 3.2. By applying the
host-wide templates to an individual resource URI, a resource-specific link is
constructed which can be used to express links without the need to access or provide a
representation for the resource.
</t>
<t>
Clients MUST process the host-meta document, looking for link templates and applying
the resource URI to produce a list of links to be used in the discovery process.
Clients MUST retain the order of the links as present in the host-meta document. Any
links contained in the host-meta document not using the
<spanx style="verb">template</spanx> attribute MUST be ignored and excluded from LRDD
processing, but are still valid for other purposes.
</t>
<figure>
<preamble>
For example, the resource URI <spanx style="verb">http://example.com/x</spanx> and the
following host-meta link template:
</preamble>
<artwork>
<![CDATA[
<Link rel='author' template="http://example.com?author={uri}' />
]]>
</artwork>
<postamble>
generates an <spanx style="verb">author</spanx> link between
<spanx style="verb">http://example.com/x</spanx> and
<spanx style="verb">http://example.com?author=http%3A%2F%2Fexample.com%2Fx</spanx>.
</postamble>
</figure>
</section>
<section title="HTTP Link Headers">
<t>
The HTTP Link header source is limited to resources for which an HTTP
<spanx style="verb">GET</spanx> or <spanx style="verb">HEAD</spanx> request returns a
2xx, 3xx, or 4xx HTTP response per <xref target="RFC2616" />. This method uses the
Link header defined in <xref target="I-D.nottingham-http-link-header" /> and requires the
retrieval of a resource representation header.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
<![CDATA[
Link: <http://example.com?author=http%3A%2F%2Fexample.com%2Fx>;
rel="author"
]]>
</artwork>
</figure>
<t>
Clients obtain HTTP Link header links by making an HTTP (or HTTPS as required)
<spanx style="verb">GET</spanx> or <spanx style="verb">HEAD</spanx> 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.
</t>
<t>
Link headers can include multiple relation types in a single <spanx style="verb">rel</spanx>
attribute (for example <spanx style="verb">rel="license copyright"</spanx>). Clients
MUST properly process such multiple relation <spanx style="verb">rel</spanx> attributes
as defined by <xref target="I-D.nottingham-http-link-header" />.
</t>
</section>
<section title="<Link> Elements">
<t>
The <Link> element source is limited to resources with an available markup
representation that supports typed-relations using the <Link> element, such as
HTML <xref target="W3C.REC-html401-19991224" />, XHTML
<xref target="W3C.REC-xhtml1-20020801" />, and Atom <xref target="RFC4287" />. Other
markup formats are permitted as long as the semantics of their <Link> elements are
fully compatible with the link framework defined in
<xref target="I-D.nottingham-http-link-header" />. This source requires the retrieval of
a resource representation. While HTTP is the most common transport for such documents,
this source is transport independent.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
<![CDATA[
<LINK href='http://example.com?author=http%3A%2F%2Fexample.com%2Fx'
rel='author'>
]]>
</artwork>
</figure>
<t>
Clients obtain <Link> element links by retrieving 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 received with a successful (2xx) response code. If no such valid
representation of the request URI is found, the source MUST NOT be used.
</t>
<t>
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.
</t>
<t>
Some <Link> elements allow multiple relation types in a single
<spanx style="verb">rel</spanx> attribute (for example
<spanx style="verb">rel='license copyright'</spanx>). Clients MUST properly process
such multiple relation <spanx style="verb">rel</spanx> attributes as defined by the
format specification.
</t>
</section>
</section>
</section>
<section anchor="Security" title="Security Considerations">
<t>
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.
</t>
</section>
<section title="IANA Considerations">
<section title="The 'lrdd' Relation Type">
<t>
This specification registers the <spanx style="verb">lrdd</spanx> relation type in the
Link Relation Type Registry defined by <xref target="I-D.nottingham-http-link-header" />:
<list style="hanging">
<t hangText="Relation Name:">
lrdd
</t>
<t hangText="Description:">
Identifies a resource descriptor for the link's context used by the LRDD protocol.
</t>
<t hangText="Reference:">
[[ This specification ]]
</t>
</list>
</t>
</section>
</section>
<appendix title="Acknowledgments">
<t>
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.
</t>
<t>
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.
</t>
</appendix>
<appendix title="Document History">
<t>
[[ to be removed by the RFC editor before publication as an RFC ]]
</t>
<t>
-04
<list style="symbols">
<t>
Changed focus to a narrow and well-defined discovery process.
</t>
<t>
Removed analysis appendix and discussion of discovery types and removed
informative references.
</t>
<t>
Expanded the descriptor definition to include links as well as LRDD documents, moving
away from the single-document approach.
</t>
<t>
Moved the Link-Pattern field and template syntax to new host-meta draft.
</t>
<t>
Updated references.
</t>
<t>
Added example.
</t>
</list>
</t>
<t>
-03
<list style="symbols">
<t>
Added protocol name LRDD (pronounced 'lard').
</t>
<t>
Fixed Link-Pattern examples to include missing semicolons.
</t>
</list>
</t>
<t>
-02
<list style="symbols">
<t>
Changed focus from an HTTP-based process to Link-based process.
</t>
<t>
Completely revised and restructured document for better clarity.
</t>
<t>
Realigned the methods to produce consistent results and changed the way
redirections and client-errors are handled.
</t>
<t>
Updated to use newer version of site-meta, now called host-meta, including
a new plaintext-based format to replace the previous XML format.
</t>
<t>
Renamed Link-Template to Link-Pattern to avoid future conflict with a previously
proposed Link-Template HTTP header.
</t>
<t>
Removed support for the "scheme" Link-Template parameter.
</t>
<t>
Replaced restrictions with interoperability recommendations.
</t>
<t>
Added IANA considerations per new host-meta registry requirements.
</t>
</list>
</t>
<t>
-01
<list style="symbols">
<t>
Rename 'resource discovery' to 'descriptor discovery'.
</t>
<t>
Added informative reference to Metalink.
</t>
<t>
Clarified that the resource descriptor URI can use any URI scheme, not just "http" or "https".
</t>
<t>
Removed comment regarding redirects when using <Link> Elements.
</t>
<t>
Clarified that HTTPS must be used with "https" URIs for both Link headers and host-meta retrieval.
</t>
<t>
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.
</t>
<t>
Organized host-meta section into another sub-section level.
</t>
<t>
Enlarged the template vocabulary from a single "uri" variable to include smaller URI components.
</t>
<t>
Added informative reference to RFC 2295 in analysis appendix.
</t>
</list>
</t>
<t>
-00
<list style="symbols">
<t>
Initial draft.
</t>
</list>
</t>
</appendix>
</middle>
<back>
<references title="Normative References">
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html401-19991224.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xhtml1-20020801.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-nottingham-http-link-header-08.xml"?>
<?rfc include="http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-hostmeta-05.xml"?>
</references>
<references title="Informative References">
<?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.4918.xml"?>
<reference anchor="OASIS.XRD-1.0" target="http://www.oasis-open.org/committees/download.php/36542/xrd-1.0-wd15.html">
<front>
<title>Extensible Resource Descriptor (XRD) Version 1.0 (work in progress)</title>
<author initials="E.H" surname="Hammer-Lahav" fullname="Eran">
<organization />
</author>
<author initials="W.N" surname="Norris" fullname="Will Norris">
<organization />
</author>
</front>
<format type="HTML" target="http://www.oasis-open.org/committees/download.php/36542/xrd-1.0-wd15.html" />
</reference>
<reference anchor="URIQA" target="http://sw.nokia.com/uriqa/URIQA.html">
<front>
<title>The URI Query Agent Model</title>
<author initials="" surname="" fullname="">
<organization>Nokia</organization>
</author>
</front>
<format type="HTML" target="http://sw.nokia.com/uriqa/URIQA.html" />
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 14:22:30 |