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