[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

Network Working Group                                           E. Wilde
Internet-Draft                                               UC Berkeley
Intended status: Informational                         February 12, 2014
Expires: August 16, 2014


                         HTTP Link Descriptions
                        draft-wilde-link-desc-01

Abstract

   Interactions with many resources on the Web are driven by links, and
   these links often define certain expectations about the interactions
   (such as HTTP methods being allowed, media types being accepted in
   the request, or URI templates being supported).  While these
   expectations are essential to define the possible interactions, it
   may be useful to further narrow them down by providing link
   descriptions, which can help clients to gain more runtime knowledge
   about the resource they are about to interact with.  This memo
   defines Link Descriptions, a model and associated media type that can
   be used to describe links by supporting descriptive markup for
   representing interaction information with links.  Link Descriptions
   can be used by media types (by inclusion or by reference) that seek
   to make Link Descriptions runtime-capable, without having to create
   their own representation for them.

Note to Readers

   Please discuss this draft on the apps-discuss mailing list [1].

   Online access to all versions and files is available on github [2].

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

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

   This Internet-Draft will expire on August 16, 2014.



Wilde                    Expires August 16, 2014                [Page 1]


Internet-Draft           HTTP Link Descriptions            February 2014


Copyright Notice

   Copyright (c) 2014 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
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Web Links  . . . . . . . . . . . . . . . . . . . . . . . .  5
     1.2.  URI Templates  . . . . . . . . . . . . . . . . . . . . . .  6
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  8
   3.  Description Concepts . . . . . . . . . . . . . . . . . . . . .  8
     3.1.  Link Hints . . . . . . . . . . . . . . . . . . . . . . . .  8
     3.2.  Describing Variables . . . . . . . . . . . . . . . . . . .  8
   4.  Link Descriptions  . . . . . . . . . . . . . . . . . . . . . .  9
     4.1.  General Concepts . . . . . . . . . . . . . . . . . . . . .  9
     4.2.  Link Description Structure . . . . . . . . . . . . . . . . 10
     4.3.  Variable Description Structure . . . . . . . . . . . . . . 10
   5.  Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
     5.1.  Editable Entry . . . . . . . . . . . . . . . . . . . . . . 10
     5.2.  Pageable Collection  . . . . . . . . . . . . . . . . . . . 11
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
     6.1.  Media Type . . . . . . . . . . . . . . . . . . . . . . . . 11
     6.2.  Link Relation  . . . . . . . . . . . . . . . . . . . . . . 13
   7.  Implementation Status  . . . . . . . . . . . . . . . . . . . . 13
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 14
   9.  Open Issues  . . . . . . . . . . . . . . . . . . . . . . . . . 14
   10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     10.1. From -00 to -01  . . . . . . . . . . . . . . . . . . . . . 15
     10.2. Prior to -00 . . . . . . . . . . . . . . . . . . . . . . . 15
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 15
     11.2. Informative References . . . . . . . . . . . . . . . . . . 16
   Appendix A.  Acknowledgements  . . . . . . . . . . . . . . . . . . 17
   Appendix B.  Link Description Schema . . . . . . . . . . . . . . . 17
   Appendix C.  XSLT for Generating Link Description HTML . . . . . . 19
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 23



Wilde                    Expires August 16, 2014                [Page 2]


Internet-Draft           HTTP Link Descriptions            February 2014


1.  Introduction

   Interactions with resources found on the Web often are driven by
   following links (targeted at URIs [RFC3986]), which can be either
   fixed links (described in Section 1.1), or can be templated links
   (using URI Templates [RFC6570]) containing variables (described in
   Section 1.2).  In both cases, the context of the link in most cases
   provides information that can be essential or helpful when it comes
   to following a link, which means interacting with the link target:
   For fixed links, the context may provide (in most cases implicitly,
   through the use of typed links) allowed interaction methods (such as
   HTTP verbs) or expectations around the expected media type(s) in
   requests; for templated links, the context additionally may provide
   information about how to instantiate the variables provided in the
   URI Template.  This memo defines a schema and a media type that can
   be used to (partially) represent this information, so that it becomes
   possible to represent a change in interaction affordances at runtime.

   Possible use cases for both scenarios (fixed and templated links) are
   as follows:

      Fixed Links: AtomPub [RFC5023] defines an "edit" link relation,
      that informs clients that such a link can be followed to read,
      update, or delete a resource.  This means that a client
      encountering such a link would conclude that it can try to read,
      update, or delete the target resource.  However, if the resource
      is not deletable, then an "edit" link could be annotated to
      indicate that the linked resource cannot be deleted.  A client
      could ignore the annotation and still attempt to delete the
      resource, but the request would be likely to fail (unless the
      state of the resource changed in the meantime).  This kind of
      information can be useful for UIs, where it can be used to drive
      usability features such as disabling certain UI elements.

      Templated Links: URI Templates [RFC6570] define a framework for
      how to represent and instantiate (with concrete variable
      assignments) templated URIs, but they don't describe how variables
      themselves are described, or can be constrained.  If a collection
      resource for example supports paged access to the set of
      collection members, then it might be useful for a client to know
      the number of available pages.  With this additional knowledge, it
      is possible to build applications and UIs that specifically take
      this knowledge into account to drive further interactions with the
      resource.  For a paged collection, it may be a UI that provides
      direct links to all available pages (if that number is reasonably
      small).  Again, if the collection changes in size between the link
      being generated, and the link interaction taking place, the
      information in the link description has become outdated.  But this



Wilde                    Expires August 16, 2014                [Page 3]


Internet-Draft           HTTP Link Descriptions            February 2014


      just means that either a client may request a page that doesn't
      exist anymore, or will not expect a page to exist that now exists.
      Both of these conditions can be handled well at the time when the
      client starts interacting with the linked resource.

   As described in both cases, it is possible for the link description
   to become outdated, leading to cases where the assumptions made by
   the client (based on the link description) and the link target itself
   do not match anymore.  For this reason, ideally a resource should
   provide a link description for itself, allowing a client to update
   its expectations.  However, since the service generating the link and
   the service providing the link target often are loosely coupled, link
   descriptions can be used in links, in descriptions where services
   expose more runtime information about resources by providing link
   descriptions for themselves, or in both places.

   The following example shows hows both of these mechanisms can be used
   in one representation, which is based on Atom [RFC4287] and AtomPub
   [RFC5023].  It also shows the two cases just described, with the
   first link description being one to "self", while the second link
   description is describing a different resource.
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="ld.xslt"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ld="urn:ietf:rfc:XXXX">
    <title>Example Feed</title>
    <link rel="self" href="http://example.org/?page=3" ld:hreft="http://example.org/{?page}">
        <ld:var name="page" concept="http://example.com/feedpaging/page"/>
    </link>
    <link rel="next" href="http://example.org/?page=4"/>
    <link rel="previous" href="http://example.org/?page=2"/>
    <updated>2003-12-13T18:30:02Z</updated>
    <author>
        <name>John Doe</name>
    </author>
    <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
    <entry>
        <title>Atom-Powered Robots Run Amok</title>
        <link href="http://example.org/2003/12/13/atom03"/>
        <link rel="edit" href="http://example.org/item42">
            <ld:allow method="PUT">
                <ld:hint name="formats" value="image/png, image/jpeg"/>
            </ld:allow>
        </link>
        <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
        <updated>2003-12-13T18:30:02Z</updated>
        <summary>Some text.</summary>
    </entry>
</feed>



Wilde                    Expires August 16, 2014                [Page 4]


Internet-Draft           HTTP Link Descriptions            February 2014


   The link to the feed itself is augmented with a URI Template
   described in Section 1.2, which allows a client to understand that
   individual feed pages can be requested (assuming the consumer
   understands the "concept" identifiers for the described variables).
   The link to the entry is an augmented typed Web Link described in
   Section 1.1, which allows a consumer to understand that even though
   "edit" links typically can be followed via GET, PUT, and DELETE, this
   particular link should only be followed using a PUT request.

   It is worth noting that link descriptions of course can become
   outdated between the time such a link description has been received
   by a client, and the time a client actually sends a request when
   following such a link (this is the case both for "self" links and
   links to other resources).  This means that clients should never
   depend on a link description being correct, because for example the
   "edit" link description shown above might start allowing DELETE
   requests again at any point in time.

1.1.  Web Links

   One of the defining principles of many services provided on the Web
   is that they expose linked resources, so that clients can follow the
   links in order to accomplish application goals.  "Web Linking"
   [RFC5988] establishes a framework of typed links, allowing resources
   to expose typed links, which then can be followed by clients.  While
   this framework allows clients to select links based on their "types",
   it does not provide any support for additional runtime information
   about possible interactions with such a link.  As outlined in the
   AtomPub example above, a link typed as "edit" (as defined and
   registered by AtomPub) can be followed by using HTTP GET, PUT, or
   DELETE, and the typed link by itself cannot provide the additional
   information that some resource may allow updates, but disallows
   deletion.

   "Link Hints" [I-D.nottingham-link-hint] (a draft currently under
   development) provide a framework for runtime hints that can be used
   to indicate information that might be made available by the link
   target resource itself, but ahead of time.  For example, a link hint
   would be able to indicate on an "edit" link that the resource only
   allows PUT requests, which is something that could also be discovered
   by sending an HTTP request and getting an HTTP Allow header in the
   response.  However, link hints can save overhead by avoiding round
   trips, and they also allow to minimize the chances of sending
   requests that will not succeed.

   While link hints can help to avoid overhead and drive client
   behavior, they are strictly optional.  There should be no functional
   difference of what a client can achieve by using or ignoring link



Wilde                    Expires August 16, 2014                [Page 5]


Internet-Draft           HTTP Link Descriptions            February 2014


   hints; they simply expose information that otherwise would be more
   costly to acquire.

   Since it is potentially expensive to provide link hints in
   representations (because they may involve interpreting access control
   data), it is perfectly possible that services provide link hints only
   on some requests.  For example, it would be possible for a service to
   serve http://example.com/collection as a collection of items with
   embedded "edit" links, whereas
   http://example.com/collection?hints=true would result in a
   representation that would contain additional link hints for each
   individual "edit" link.  This kind of design is outside of the scope
   of this memo, but it is helpful to illustrate the fact that link
   hints are nothing but optimizations.

   Currently, there is an overlap in what "Link Hints"
   [I-D.nottingham-link-hint] define, and what is proposed in this memo.
   While both drafts propose a way how to represent link hints/
   descriptions, the "Link Hints" draft does not address URI Templates.
   Removing this overlap is captured in the "Open Issues" Section 9 and
   should be addressed during the further development and/or alignment
   of both drafts.

1.2.  URI Templates

   Following links is the basic principle of interacting with resources
   on the web, but in many cases, interactions with resources require
   clients to provide information in addition to just using a fixed URI
   in a request.  In these cases, information can be provided in any way
   supported by the interaction protocol, and in case of HTTP, this
   often means that information is either embedded in the URI, in HTTP
   headers, and/or in the body of the request.  For the first case, "URI
   Template" [RFC6570] provides a standard that allows servers and
   clients to exchange information about the URIs that a service
   accepts.  The standard specifies "a compact sequence of characters
   for describing a range of Uniform Resource Identifiers through
   variable expansion."  It allows servers to publish their expectation
   how a URI should be created by substituting variables with values.
   Consider the following URI Template:
   http://www.example.com/collection{?pagesize,page}

   This URI Template allows clients to expand it with two variables
   assignments, to end up with a concrete URI such as the following:
   http://www.example.com/collection?pagesize=10&page=42

   URI Templates cover the aspect of starting with a template with
   variables in it, assigning values to these variables, and then
   expanding the template into a URI that can be used for sending a



Wilde                    Expires August 16, 2014                [Page 6]


Internet-Draft           HTTP Link Descriptions            February 2014


   request.  URI Templates make no assumptions or statements about the
   meaning or value range of the variables, except for those aspects
   which are required to cover the process of expanding the template.
   In particular, for the example given above, there is no indication
   that the values are supposed to be positive integers (the data type),
   nor is there any indication that the service may apply certain limits
   such as a maximum page size (which may change depending on which
   paged resource is being accessed).  As a side note, even if this
   basic type information was known, URI template expansion could still
   result in URIs that would not yield successful requests, such as when
   asking for a page that is beyond the number of pages that a
   collection has (in a given page size).

   The goal of Link Descriptions as defined in this memo is to allow
   servers to expose a description that provides support both at
   development time (when a developer uses a media type that uses URI
   Templates) and at runtime (when a client wants to use a URI template
   as part of its application flow).  Link Descriptions are intended to
   provide additional information that is not communicated by publishing
   URI Templates alone.  The additional information is both targeted at
   machines, and at humans.  On the human-oriented Web, a Template
   Description can be seen as the equivalent of a help or documentation
   page that is linked to from a form, where users can learn more about
   the values they are supposed to submit within the form.

   As a concrete example, a link to a collection like the one above may
   be exposed in a link description as follows:
<link rel="items" href="http://www.example.com/collection" hreft="http://www.example.com/collection{?pagesize,page}">
  <var name="pagesize" concept="http://example.com/feedpaging/pagesize"/>
  <var name="page" concept="http://example.com/feedpaging/page"/>
</link>

   This link description allows a URI Template's variables to be
   described in terms of URI-identified concepts.  By using such a
   model, it is possible to use global names for URI Template
   parameters, and bind them to URI Template variable names.  The
   template and the variables int the example above are not specific for
   any HTTP method, i.e. this link description does not define any
   constraints in terms of how to use URI Templates differently for
   different HTTP methods.  But this is possible, and is covered in the
   detailed description below.

   The concept URIs are pure identifiers for the purpose of link
   descriptions; i.e. they should not be considered dereferenceable, and
   the assumption is that consumers of link descriptions will only use
   them to match discovered concepts against known concepts.  This
   design does not prohibit to make concept URIs dereferenceable, but
   this is outside of the scope of link descriptions.



Wilde                    Expires August 16, 2014                [Page 7]


Internet-Draft           HTTP Link Descriptions            February 2014


2.  Terminology

   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 RFC 2119 [RFC2119].


3.  Description Concepts

   The general idea of link descriptions is that they allow to annotate
   links (URIs or URI Templates) with context that clients can use when
   they choose to follow those links.  In the XML syntax, descriptions
   are deliberately designed to follow the design of Atom's popular
   <link> element, which serves as a blueprint for links in many media
   types.  The main idea of link descriptions is to provide a framework
   which provides services that want to serve this kind of description
   with a starting point.  If these services want, they can reuse the
   representations for this framework, in whole or in part.

3.1.  Link Hints

   As mentioned already, "Link Hints" [I-D.nottingham-link-hint] as
   currently defined overlap with the concepts proposed in this memo.
   However, this memo goes further than link hints by not just providing
   hints for URIs, but for URI Templates as well.  Based on the current
   link hint model defined in that draft, a link hint is a name/value
   pair, where the name is either a registered link hint, or a URI.  The
   allowed value space depends on the link hint, and in the current
   model, structured values must be encoded in JSON.  A link may have
   any number of link hints, but only one link hint with a given name.

3.2.  Describing Variables

   When a link description uses a URI Template, then this template will
   very likely contain variables.  Variables can be described when using
   Link Descriptions.  For each variable contained in the URI Template,
   it is possible to use the following description methods:

      Concept: It is possible to associate a variable with a concept, so
      that media types and applications can make an association between
      the concepts they are defining/exposing, and how they are exposed
      in URI Templates.  Concepts can be identified by using a URI as an
      identifier.  This specification defines no interactions with this
      URI identifier and makes no assumption about possible
      representations, should this URI be dereferenceable and yield some
      representation.





Wilde                    Expires August 16, 2014                [Page 8]


Internet-Draft           HTTP Link Descriptions            February 2014


      Documentation: Documentation constructs can be associated with
      variables, which allows Link Descriptions to attach human-readable
      information to individual variables.  The documentation model has
      the ability to support multi-lingual human-oriented documentation.

   For the purpose of this specification, the term "description" should
   be interpreted loosely.  Description aspects such as concepts and
   documentation do not prescribe a description framework; they simply
   provides a structure how to deliver these descriptions, so that
   clients can use them when making decisions about which links to
   follow, and how to follow them.


4.  Link Descriptions

   Link Descriptions are based on a URI Template, and add descriptive
   elements that allow publishers of URI Templates to describe the URI
   Template as a whole, and to add individual descriptions of all
   variables in the template.  The idea of Link Descriptions is that
   they are made available at design time and/or at runtime, so that
   clients encountering URI Templates as part of HTTP services can find
   more information about the template itself.

   Ideally, every URI template exposed in an HTTP service should be
   accompanied by a link to a Link Description.  In those XML-based HTTP
   services where URI Templates are exposed in XML attributes named
   "hreft", the suggestion is to add a link to the corresponding Link
   Description in an "hrefd" XML attribute.

4.1.  General Concepts

   As mentioned in Section 1.2, most of the descriptions in this spec do
   not prescribe a specific description framework.  While variables
   (Section 4.3) can be described with a built-in vocabulary of
   datatypes, most other descriptions are either for human consumption,
   or do rely on some external description framework.  To attach these
   descriptions to both the template as a whole, and individual
   variables, this specification reuses the "appinfo" and
   "documentation" elements from XML Schema Part 1.  These elements
   carry a "source" attribute, which is used "to supplement the local
   information."  For example, when a description of a variable is done
   formally using a specific description framework, this would best
   translate to use appinfo elements, and to add an identifier to them
   which would identify the description framework in question.  As a
   result, any client knowing this particular description framework
   would be able to interpret the variable description in the Link
   Description.




Wilde                    Expires August 16, 2014                [Page 9]


Internet-Draft           HTTP Link Descriptions            February 2014


4.2.  Link Description Structure

   An interaction is described by including the URI Template itself, and
   optionally adding documentation and/or appinfo elements to add human-
   or machine-readable descriptions.

4.3.  Variable Description Structure

   A variable is described by specifying the variable name.  Variables
   can refer to a "concept" associated with a variable, which can by
   identified by URI.  This specification makes no provision how such a
   concept is defined and/or described/documented, but it allows
   consumers of a Link Description to match their understanding of
   certain concepts to those identifiers, which then establishes a
   binding between the concept, and the variable it has been bound to.

   A variable can have a default value, in which case the assumption is
   that excluding this variable from a request has the same effect as
   including it with the default value.  Since Link Descriptions are
   runtime concepts, however, there is no guarantee that a service might
   not use a different value between the time when the Link Description
   was retrieved, and the time when a request based on it is being sent.

   Variable descriptions can optionally add documentation and/or appinfo
   elements to add human- or machine-readable descriptions.


5.  Examples

   ...

5.1.  Editable Entry

   ...

   All the example use "documentation" elements which are entirely
   optional, but can help to improve the usefulness of link descriptions
   for developers.













Wilde                    Expires August 16, 2014               [Page 10]


Internet-Draft           HTTP Link Descriptions            February 2014


<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="ld.xslt"?>
<link xmlns="urn:ietf:rfc:XXXX" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ietf:rfc:XXXX ld.xsd" href="http://example.org/item42">
   <documentation xml:lang="en">Link Description for accessing the AtomPub media resource http://www.example.com/feed/item42, with the "edit-media" link allowing PUT/DELETE as per RFC 5023, but the specific resource not currently allowing DELETE (constraining AtomPub semantics), but allowing PATCH.</documentation>
   <allow method="PUT">
      <documentation xml:lang="en">For this particular resource, PUT is supported.</documentation>
      <hint name="formats" value="image/png, image/jpeg">
         <documentation xml:lang="en">Updates are accepted as PNG or JPEG representations.</documentation>
      </hint>
   </allow>
   <allow method="PATCH">
      <documentation xml:lang="en">Extending AtomPub's capabilities, images can also be PATCHed, with two patch media types being supported.</documentation>
      <hint name="formats" value="application/png-patch, application/jpeg-patch">
         <documentation xml:lang="en">Patches are accepted as (hypothetical) PNG or JPEG patch document representations.</documentation>
      </hint>
   </allow>
</link>

5.2.  Pageable Collection

   ...
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="ld.xslt"?>
<link xmlns="urn:ietf:rfc:XXXX" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ietf:rfc:XXXX ld.xsd" hreft="http://example.org/{?pagesize,page}">
   <documentation xml:lang="en">Template for accessing a paged feed of entries at http://www.example.com/feed, with client controls for the page size, and the returned page.</documentation>
   <var name="pagesize" concept="http://example.com/feedpaging/pagesize">
      <documentation xml:lang="en">Number of returned items per page.</documentation>
   </var>
   <var name="page" concept="http://example.com/feedpaging/page">
      <documentation xml:lang="en">Page number of the returned page (based on the requested pagesize or a service-defined default).</documentation>
   </var>
</link>


6.  IANA Considerations

6.1.  Media Type

   The Internet media type [RFC6838] for a Link Description document is
   application/ldesc+xml (using the "+xml" suffix as defined and
   registered by RFC 6839 [RFC6839]).

   Type name:  application

   Subtype name:  ldesc+xml






Wilde                    Expires August 16, 2014               [Page 11]


Internet-Draft           HTTP Link Descriptions            February 2014


   Required parameters:  none

   Optional parameters:  profile

         The "profile" link relation [RFC6906] allows "resource
         representations to indicate that they are following one or more
         profiles.  A profile is defined not to alter the semantics of
         the resource representation itself, but to allow clients to
         learn about additional semantics (constraints, conventions,
         extensions) that are associated with the resource
         representation, in addition to those defined by the media type
         and possibly other mechanisms."  If the application/ldesc+xml
         media type is use with a profile parameter, this refers to a
         profile as defined by [RFC6906], making it easier for
         extensions of the link description media type to identify
         themselves.

   Encoding considerations:  Same as encoding considerations of
      application/xml as specified in [RFC3023].

   Security considerations:  This media type has all of the security
      considerations described in [RFC3023], plus those listed in
      Section 8.

   Interoperability considerations:  N/A

   Published specification:  RFC XXXX

   Applications that use this media type:  Applications that publish
      descriptions of URI Interactions.

   Additional information:

      Magic number(s):  none

      File extension(s):  No specific file extension proposed, but as a
         general rule, XML data often uses ".xml" as the file extension.

      Macintosh file type code(s):  TEXT

   Person & email address to contact for further information:  Erik
      Wilde <dret@berkeley.edu>

   Intended usage:  COMMON







Wilde                    Expires August 16, 2014               [Page 12]


Internet-Draft           HTTP Link Descriptions            February 2014


   Restrictions on usage:  none

   Author:  Erik Wilde <dret@berkeley.edu>

   Change controller:  IESG

6.2.  Link Relation

   The link relation type below will be registered by IANA per Section
   6.2.1 of RFC 5988 [RFC5988]:

      Relation Name: ldesc

      Description: Linking to a resource that can be used as a link
      description for requesting runtime information about a particular
      context's interaction affordances.

      Reference: RFC XXXX

      Notes: Link Descriptions can be used in all scenarios where
      clients want to create requests that represent a query into the
      context resource.  The media type of the context resource and the
      media type of the link description resource are not constrained by
      this specification.


7.  Implementation Status

   Note to RFC Editor: Please remove this section before publication.

   This section records the status of known implementations of the
   protocol defined by this specification at the time of posting of this
   Internet-Draft, and is based on a proposal described in RFC 6982
   [RFC6982].  The description of implementations in this section is
   intended to assist the IETF in its decision processes in progressing
   drafts to RFCs.  Please note that the listing of any individual
   implementation here does not imply endorsement by the IETF.
   Furthermore, no effort has been spent to verify the information
   presented here that was supplied by IETF contributors.  This is not
   intended as, and must not be construed to be, a catalog of available
   implementations or their features.  Readers are advised to note that
   other implementations may exist.

   According to RFC 6982, "this will allow reviewers and working groups
   to assign due consideration to documents that have the benefit of
   running code, which may serve as evidence of valuable experimentation
   and feedback that have made the implemented protocols more mature.
   It is up to the individual working groups to use this information as



Wilde                    Expires August 16, 2014               [Page 13]


Internet-Draft           HTTP Link Descriptions            February 2014


   they see fit".


8.  Security Considerations

   ...


9.  Open Issues

      If and how to use profiles (example in Section 5); if profile use
      is recommended, define a suggested profile URI for other specs to
      use?

      How to handle variables in Level 4 templates that are supposed to
      have composite values?

      If a template is refined in an incremental process (such as for
      example faceted search services), does it make sense to be able to
      add a "back" link and/or "home" link, so that clients can find the
      "most general" version easily?

      How does this interact with "faceted search" scenarios?  Does
      incremental refinement of URI Template Descriptions somehow nicely
      and naturally map into faceted search scenarios?

      Is there a concept of how Template Descriptions (and thus URI
      Templates) can be reused?  Should there be an inclusion facility
      or something along those lines?  If so, what's the model for that?
      Initial thoughts on possibilities can be found on this page [3]

      Should there be some recommended link relation to use when linking
      to a Template Description from within the context of a URI
      Template?

      While currently everything is defined in XML, providing
      alternative serializations (JSON and RDF) might be an interesting
      thing to consider.

      Should there be a "Template" HTTP header field, listing a
      resource's URI Template and, optionally, containing a link to a
      description resource for it (basically, a rel="ldesc" link)?

      What about using CURIE for the variable names, thus eliminating
      the need for separate concept URIs?  This would need prefix
      bindings, which in XML would just up as regular namespace
      declarations.  It might quite be a bit more problematic in non-XML
      contexts, such as serving a URI Template in an HTTP header.



Wilde                    Expires August 16, 2014               [Page 14]


Internet-Draft           HTTP Link Descriptions            February 2014


      Support for "HTTP Prefer" [I-D.snell-http-prefer] might need
      another link hint, so that clients know which preferences they
      might use.


10.  Change Log

   Note to RFC Editor: Please remove this section before publication.

10.1.  From -00 to -01

   o  Adding "Template" HTTP header field as an open issue.

   o  Adding CURIEs as one possible convention to use for variable
      names, so that "Concept URIs" are embedded in the template itself,
      and not external.

   o  Adding "HTTP Prefer" [I-D.snell-http-prefer] as an open issue.

   o  Updated author address.

10.2.  Prior to -00

   An earlier variation of a similar idea was published as "Template
   Descriptions" [I-D.wilde-template-desc].  However, since this earlier
   draft was exclusively focusing on interactions with links driven by
   URI Templates [RFC6570], instead of looking at links in general, it
   was sufficiently distinct to start a new draft, instead of evolving
   the existing one.


11.  References

11.1.  Normative References

   [I-D.nottingham-link-hint]
              Nottingham, M., "HTTP Link Hints",
              draft-nottingham-link-hint-00 (work in progress),
              June 2013.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", RFC 2119, March 1997.

   [RFC3023]  Murata, M., St. Laurent, S., and D. Kohn, "XML Media
              Types", RFC 3023, January 2001.

   [RFC4287]  Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
              Syndication Format", RFC 4287, December 2005.



Wilde                    Expires August 16, 2014               [Page 15]


Internet-Draft           HTTP Link Descriptions            February 2014


   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570, March 2012.

   [XSD-2]    Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
              Second Edition", World Wide Web Consortium
              Recommendation REC-xmlschema-2-20041028, October 2004,
              <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

11.2.  Informative References

   [I-D.snell-http-prefer]
              Snell, J., "Prefer Header for HTTP",
              draft-snell-http-prefer-18 (work in progress),
              January 2013.

   [I-D.wilde-template-desc]
              Wilde, E., Davis, C., and Y. Liu, "URI Template
              Descriptions", draft-wilde-template-desc-00 (work in
              progress), December 2012.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC5005]  Nottingham, M., "Feed Paging and Archiving", RFC 5005,
              September 2007.

   [RFC5023]  Gregorio, J. and B. de hOra, "The Atom Publishing
              Protocol", RFC 5023, October 2007.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, January 2013.

   [RFC6839]  Hansen, T. and A. Melnikov, "Additional Media Type
              Structured Syntax Suffixes", RFC 6839, January 2013.

   [RFC6906]  Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
              March 2013.

   [RFC6982]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", RFC 6982,
              July 2013.

URIs




Wilde                    Expires August 16, 2014               [Page 16]


Internet-Draft           HTTP Link Descriptions            February 2014


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

   [2]  <https://github.com/dret/I-D/tree/master/link-desc>

   [3]  <http://dret.typepad.com/dretblog/2012/12/
        structuring-uri-templates.html>


Appendix A.  Acknowledgements

   Thanks for comments and suggestions provided by Dmitry Limonov.


Appendix B.  Link Description Schema
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="urn:ietf:rfc:XXXX" xmlns:ld="urn:ietf:rfc:XXXX">
    <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd">
        <xs:annotation>
            <xs:documentation>Get access to the xml: attribute groups for xml:lang as declared on 'documentation' below.</xs:documentation>
        </xs:annotation>
    </xs:import>
    <xs:element name="link" type="ld:link-type"> </xs:element>
    <xs:simpleType name="uriTemplate">
        <xs:annotation>
            <xs:documentation>Representing the type for URI template values according to RFC 6570. This is probably too complicated to cover with a regular expression in any reasonable way, so type enforcement is not done by the schema.</xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:element name="documentation" id="documentation">
        <xs:complexType mixed="true">
            <xs:sequence minOccurs="0" maxOccurs="unbounded">
                <xs:any processContents="lax"/>
            </xs:sequence>
            <xs:attribute name="source" type="xs:anyURI"/>
            <xs:attribute ref="xml:lang"/>
            <xs:anyAttribute namespace="##other" processContents="lax"/>
        </xs:complexType>
    </xs:element>
    <xs:complexType name="link-type">
        <xs:sequence>
            <xs:element ref="ld:documentation" maxOccurs="unbounded" minOccurs="0"/>
            <xs:choice maxOccurs="unbounded" minOccurs="0">
                <xs:element ref="ld:var"/>
                <xs:element ref="ld:hint"/>
                <xs:element name="allow">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element maxOccurs="unbounded" minOccurs="0" ref="ld:documentation"/>



Wilde                    Expires August 16, 2014               [Page 17]


Internet-Draft           HTTP Link Descriptions            February 2014


                            <xs:choice maxOccurs="unbounded" minOccurs="0">
                                <xs:element ref="ld:var"/>
                                <xs:element ref="ld:hint"/>
                            </xs:choice>
                        </xs:sequence>
                        <xs:attribute name="method">
                            <xs:simpleType>
                                <xs:restriction base="xs:token">
                                    <xs:enumeration value="GET"/>
                                    <xs:enumeration value="PUT"/>
                                    <xs:enumeration value="POST"/>
                                    <xs:enumeration value="DELETE"/>
                                    <xs:pattern value="[!#$%&amp;&apos;\*\+\-\.\^_`\|~0-9A-Za-z]+">
                                        <xs:annotation>
                                            <xs:documentation>As defined by http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-24#section-3.2.6, and only allowing one method token to be specified.</xs:documentation>
                                        </xs:annotation>
                                    </xs:pattern>
                                </xs:restriction>
                            </xs:simpleType>
                        </xs:attribute>
                    </xs:complexType>
                </xs:element>
            </xs:choice>
        </xs:sequence>
        <xs:attribute name="hreft" type="ld:uriTemplate" use="optional"/>
        <xs:attribute name="href" type="xs:anyURI" use="optional"/>
    </xs:complexType>
    <xs:element name="var">
        <xs:complexType>
            <xs:sequence maxOccurs="unbounded" minOccurs="1">
                <xs:element ref="ld:documentation" maxOccurs="unbounded" minOccurs="0"/>
                <xs:any namespace="##other" minOccurs="0">
                    <xs:annotation>
                        <xs:documentation>If variables are restricted in ways other than the simple type restrictions that are built into link descriptions, then these restrictions can be embedded in a variable description as well, as long as they are represented using a different namespace.</xs:documentation>
                    </xs:annotation>
                </xs:any>
            </xs:sequence>
            <xs:attribute name="name" use="required"/>
            <xs:attribute name="concept" type="xs:anyURI" use="optional">
                <xs:annotation>
                    <xs:documentation>Identifies the variable by referring to a concept URI.</xs:documentation>
                </xs:annotation>
            </xs:attribute>
        </xs:complexType>
    </xs:element>
    <xs:element name="hint">
        <xs:complexType>
            <xs:sequence>



Wilde                    Expires August 16, 2014               [Page 18]


Internet-Draft           HTTP Link Descriptions            February 2014


                <xs:element maxOccurs="unbounded" minOccurs="0" ref="ld:documentation"/>
            </xs:sequence>
            <xs:attribute name="name" use="required">
                <xs:annotation>
                    <xs:documentation>A hint is either a registered hint with a simple name (defined by a regular expression), or an unregistered hint which is identified by URI.</xs:documentation>
                </xs:annotation>
                <xs:simpleType>
                    <xs:union memberTypes="xs:anyURI">
                        <xs:simpleType>
                            <xs:restriction base="xs:token">
                                <xs:annotation>
                                    <xs:documentation>The list of "registered link hints" is taken from http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3 and will probably change.</xs:documentation>
                                </xs:annotation>
                                <xs:enumeration value="allow"/>
                                <xs:enumeration value="formats"/>
                                <xs:enumeration value="links"/>
                                <xs:enumeration value="accept-post"/>
                                <xs:enumeration value="accept-patch"/>
                                <xs:enumeration value="accept-ranges"/>
                                <xs:enumeration value="accept-prefer"/>
                                <xs:enumeration value="precondition-req"/>
                                <xs:enumeration value="auth-scheme"/>
                                <xs:enumeration value="status"/>
                            </xs:restriction>
                        </xs:simpleType>
                    </xs:union>
                </xs:simpleType>
            </xs:attribute>
            <xs:attribute name="value"/>
        </xs:complexType>
    </xs:element>
</xs:schema>


Appendix C.  XSLT for Generating Link Description HTML
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:ld="urn:ietf:rfc:XXXX" exclude-result-prefixes="ld">
    <xsl:output method="html"/>
    <xsl:template match="/">
        <html>
            <head>
                <title>Link Descriptions</title>
                <style type="text/css">
                    ul { margin : 0 }
                    .msg { color : #C0C0C0 }
                </style>
            </head>
            <body>



Wilde                    Expires August 16, 2014               [Page 19]


Internet-Draft           HTTP Link Descriptions            February 2014


                <h1>Link Descriptions</h1>
                <xsl:for-each select="//*[ ld:var | ld:hint ]">
                    <hr/>
                    <xsl:for-each select=" @href | @hreft | @ld:href | @ld:hreft ">
                        <h2>
                            <code>
                                <xsl:value-of select="name()"/>
                                <xsl:text>="</xsl:text>
                                <a href="{.}">
                                    <xsl:value-of select="."/>
                                </a>
                                <xsl:text>"</xsl:text>
                            </code>
                        </h2>
                    </xsl:for-each>
                    <xsl:if test="@rel">
                        <h3>
                            <code>
                                <xsl:text>rel="</xsl:text>
                                <xsl:value-of select="@rel"/>
                                <xsl:text>"</xsl:text>
                            </code>
                        </h3>
                    </xsl:if>
                    <table rules="none" style="margin : 15px">
                        <tr>
                            <th align="right">Documentation:</th>
                            <td>
                                <xsl:call-template name="documentation"/>
                            </td>
                        </tr>
                    </table>
                    <xsl:if test="ld:var">
                        <h4>Variables:</h4>
                        <table rules="all" border="1" cellpadding="5">
                            <thead>
                                <tr>
                                    <th>Variable</th>
                                    <th>Concept</th>
                                    <th>Default</th>
                                    <th>Value Range</th>
                                    <th>Documentation</th>
                                </tr>
                            </thead>
                            <xsl:for-each select="ld:var">
                                <xsl:sort select="@name"/>
                                <tr>
                                    <td>



Wilde                    Expires August 16, 2014               [Page 20]


Internet-Draft           HTTP Link Descriptions            February 2014


                                        <xsl:value-of select="@name"/>
                                    </td>
                                    <td>
                                        <xsl:choose>
                                            <xsl:when test="@concept">
                                                <q>
                                                    <xsl:value-of select="@concept"/>
                                                </q>
                                            </xsl:when>
                                            <xsl:otherwise>
                                                <span class="msg">n/a</span>
                                            </xsl:otherwise>
                                        </xsl:choose>
                                    </td>
                                    <td>
                                        <xsl:choose>
                                            <xsl:when test="@default">
                                                <q>
                                                    <code>
                                                        <xsl:value-of select="@default"/>
                                                    </code>
                                                </q>
                                            </xsl:when>
                                            <xsl:otherwise>
                                                <span class="msg">n/a</span>
                                            </xsl:otherwise>
                                        </xsl:choose>
                                    </td>
                                    <td>
                                        <xsl:choose>
                                            <xsl:when test="ld:restriction">
                                                <div>
                                                    <xsl:text>Base: </xsl:text>
                                                    <code>
                                                        <xsl:choose>
                                                            <xsl:when test="contains(ld:restriction/@base, ':')">
                                                                <xsl:value-of select="ld:restriction/@base"/>
                                                            </xsl:when>
                                                            <xsl:otherwise>
                                                                <a href="http://www.w3.org/TR/xmlschema-2/#{ld:restriction/@base}">
                                                                    <xsl:value-of select="concat('xs:', ld:restriction/@base)"/>
                                                                </a>
                                                            </xsl:otherwise>
                                                        </xsl:choose>
                                                    </code>
                                                </div>
                                                <xsl:if test="ld:restriction/ld:*">
                                                    <ul>



Wilde                    Expires August 16, 2014               [Page 21]


Internet-Draft           HTTP Link Descriptions            February 2014


                                                        <xsl:for-each select="ld:restriction/ld:*">
                                                            <xsl:sort select="local-name()"/>
                                                            <li>
                                                                <code>
                                                                    <a href="http://www.w3.org/TR/xmlschema-2/#rf-{local-name()}">
                                                                        <xsl:value-of select="concat('xs:',local-name())"/>
                                                                    </a>
                                                                    <xsl:text>="</xsl:text>
                                                                    <xsl:value-of select="@value"/>
                                                                    <xsl:text>"</xsl:text>
                                                                </code>
                                                            </li>
                                                        </xsl:for-each>
                                                    </ul>
                                                </xsl:if>
                                            </xsl:when>
                                            <xsl:otherwise>
                                                <span class="msg">n/a</span>
                                            </xsl:otherwise>
                                        </xsl:choose>
                                    </td>
                                    <td>
                                        <xsl:call-template name="documentation"/>
                                    </td>
                                </tr>
                            </xsl:for-each>
                        </table>
                    </xsl:if>
                    <xsl:if test="ld:hint">
                        <h4>Hints:</h4>
                        <table rules="all" border="1" cellpadding="5">
                            <thead>
                                <tr>
                                    <th>Name</th>
                                    <th>Value</th>
                                    <th>Documentation</th>
                                </tr>
                            </thead>
                            <xsl:for-each select="ld:hint">
                                <xsl:sort select="@name"/>
                                <tr>
                                    <td>
                                        <xsl:value-of select="@name"/>
                                    </td>
                                    <td>
                                        <code>
                                            <xsl:value-of select="@value"/>
                                        </code>



Wilde                    Expires August 16, 2014               [Page 22]


Internet-Draft           HTTP Link Descriptions            February 2014


                                    </td>
                                    <td>
                                        <xsl:call-template name="documentation"/>
                                    </td>
                                </tr>
                            </xsl:for-each>
                        </table>
                    </xsl:if>
                </xsl:for-each>
            </body>
        </html>
    </xsl:template>
    <xsl:template name="documentation">
        <xsl:choose>
            <xsl:when test="ld:documentation">
                <ul>
                    <xsl:for-each select="ld:documentation">
                        <li>
                            <xsl:value-of select="node()"/>
                            <xsl:if test="@xml:lang">
                                <xsl:text> </xsl:text>
                                <span class="msg">
                                    <xsl:text>(</xsl:text>
                                        <code>
                                            <xsl:text>xml:lang="</xsl:text>
                                            <xsl:value-of select="@xml:lang"/>
                                            <xsl:text>"</xsl:text>
                                        </code>
                                    <xsl:text>)</xsl:text>
                                </span>
                            </xsl:if>
                        </li>
                    </xsl:for-each>
                </ul>
            </xsl:when>
            <xsl:otherwise>
                <span class="msg">n/a</span>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
</xsl:stylesheet>










Wilde                    Expires August 16, 2014               [Page 23]


Internet-Draft           HTTP Link Descriptions            February 2014


Author's Address

   Erik Wilde
   UC Berkeley

   Email: dret@berkeley.edu
   URI:   http://dret.net/netdret/












































Wilde                    Expires August 16, 2014               [Page 24]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/