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



> -----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
> 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.,
>    [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",
>    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
>    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
>    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
>    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
>       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]