[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Preview of new LRDD draft
That's an editing mistake. It was there from the previous example and now with host-meta using XML should no longer be there.
Thanks,
EHL
> -----Original Message-----
> From: Barnhill, William [USA] [mailto:barnhill_william@bah.com]
> Sent: Tuesday, October 27, 2009 3:47 AM
> To: Eran Hammer-Lahav; xri@lists.oasis-open.org
> Subject: RE: Preview of new LRDD draft
>
> Hi Eran,
>
> Congrats as well. Back in version 2 you introduced a phrasing within
> section 4.4 that I see is here in v 4 as well: "For example (line
> breaks are for formatting only, and are not allowed
> in the document)". I can see where restricting to no line breaks
> would make parser construction easier but I'd worry that it makes it
> harder to read/edit for a human.
>
> Also this seems to mean that valid and well-formed XML produced by some
> generator still might not work as a host meta doc as there's no way to
> express the line break constraint in XML schema language or RelaxNG
> AFAIK.
>
> Could stating that it must be canonical XML (line break sequences each
> optimized to a single #xA) work instead?
>
> Kind regards,
> Bill
>
> ________________________________________
> From: Eran Hammer-Lahav [eran@hueniverse.com]
> Sent: Monday, October 26, 2009 8:12 PM
> To: xri@lists.oasis-open.org
> Subject: [xri] Preview of new LRDD draft
>
> 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]