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

Versions: 00 01

Network Working Group                                           E. Wilde
Internet-Draft                                           EMC Corporation
Intended status: Informational                        September 16, 2013
Expires: March 20, 2014


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

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 used, media types being sent in the
   request, or URI parameters being used in a certain way).  While these
   expectations are essential to define the possible framework for
   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.

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 March 20, 2014.



Wilde                    Expires March 20, 2014                 [Page 1]


Internet-Draft           HTTP Link Descriptions           September 2013


Copyright Notice

   Copyright (c) 2013 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  . . . . . . . . . . . . . . . . . . . . . . . .  6
     1.2.  URI Templates  . . . . . . . . . . . . . . . . . . . . . .  7
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  8
   3.  Description Concepts . . . . . . . . . . . . . . . . . . . . .  8
     3.1.  Link Hints . . . . . . . . . . . . . . . . . . . . . . . .  8
     3.2.  Describing Variables . . . . . . . . . . . . . . . . . . .  9
   4.  Link Descriptions  . . . . . . . . . . . . . . . . . . . . . . 10
     4.1.  General Concepts . . . . . . . . . . . . . . . . . . . . . 10
     4.2.  Link Description Structure . . . . . . . . . . . . . . . . 11
     4.3.  Variable Description Structure . . . . . . . . . . . . . . 11
   5.  Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     5.1.  Editable Entry . . . . . . . . . . . . . . . . . . . . . . 11
     5.2.  Pageable Collection  . . . . . . . . . . . . . . . . . . . 12
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 12
     6.1.  Media Type . . . . . . . . . . . . . . . . . . . . . . . . 12
     6.2.  Link Relation  . . . . . . . . . . . . . . . . . . . . . . 14
   7.  Implementation Status  . . . . . . . . . . . . . . . . . . . . 14
   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 15
   9.  Open Issues  . . . . . . . . . . . . . . . . . . . . . . . . . 15
   10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     10.1. Prior to -00 . . . . . . . . . . . . . . . . . . . . . . . 15
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 16
     11.2. Non-Normative References . . . . . . . . . . . . . . . . . 16
   Appendix A.  Acknowledgements  . . . . . . . . . . . . . . . . . . 17
   Appendix B.  Link Description Schema . . . . . . . . . . . . . . . 17
   Appendix C.  XSLT for Generating Link Description HTML . . . . . . 21
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 26




Wilde                    Expires March 20, 2014                 [Page 2]


Internet-Draft           HTTP Link Descriptions           September 2013


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 essentially 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 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 very 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 values)
      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



Wilde                    Expires March 20, 2014                 [Page 3]


Internet-Draft           HTTP Link Descriptions           September 2013


      information in the link description has become outdated.  But this
      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 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 about a different resource.





























Wilde                    Expires March 20, 2014                 [Page 4]


Internet-Draft           HTTP Link Descriptions           September 2013


<?xml version="1.0" encoding="utf-8"?>
<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" default="1">
            <ld:restriction base="positiveInteger">
                <ld:minInclusive value="1"/>
                <ld:maxInclusive value="42"/>
            </ld:restriction>
        </ld:var>
    </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:hint name="allow" value=' [ "PUT" ] '/>
            <ld:hint name="formats" value=' { "image/png" : {} , "image/jpeg" : {} } '/>
        </link>
        <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
        <updated>2003-12-13T18:30:02Z</updated>
        <summary>Some text.</summary>
    </entry>
</feed>

   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 decription 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 link description being correct, because for example the
   "edit" link description shown above might start allowing DELETE
   requests again at any point in time.



Wilde                    Expires March 20, 2014                 [Page 5]


Internet-Draft           HTTP Link Descriptions           September 2013


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) by definition 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] provide a framework of
   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
   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 to design a
   service that served 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's helpful to illustrate the fact that link hints
   are nothing but optimizations of at which point during interactions
   certain information is provided.

   Currently, there is an overlap in what "Link Hints"
   [I-D.nottingham-link-hint] define, and what is proposed in this memo.
   Removing this overlap is captured in the "Open Issues" Section 9 and



Wilde                    Expires March 20, 2014                 [Page 6]


Internet-Draft           HTTP Link Descriptions           September 2013


   should be addressed during the development of both drafts.

1.2.  URI Templates

   While following links is the basic principle of interacting with
   resources on the web, 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, 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
   values, 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
   request.  URI Templates make no assumptions or statements about the
   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 simple 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 looks at 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,



Wilde                    Expires March 20, 2014                 [Page 7]


Internet-Draft           HTTP Link Descriptions           September 2013


   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, by binding them to the local variable names.  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.


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 echo 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 that link hints by not just providing



Wilde                    Expires March 20, 2014                 [Page 8]


Internet-Draft           HTTP Link Descriptions           September 2013


   hints for URIs, but for URI Templates as well.  Based on the current
   link hint model, 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 hint may also contain application
   specific information or documentation, in an model of application
   information and documentation that has been inspired by XML Schema
   Part 1 [XSD-1].

   A link may have any number of link hints, but only one link with a
   given name.

3.2.  Describing Variables

   When a link uses a URI Template, then this template will very likely
   contain variables.  Variables can be described in a variety of ways
   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.

      Datatype: Variables can be described in terms of using certain
      datatypes.  The datatype vocabulary is that of XML Schema Part 2
      [XSD-2], plus all of the applicable facets of those datatypes.
      This allows Link Descriptions to constrain the set of allowed
      values.  (This model does not cover any "co-constraints", i.e.
      dependencies across variables, or between variables and an
      external context.)

      Documentation: Documentation constructs can be associated with
      variables, which allows Link Descriptions to attach human-readable
      information to individual variables.  The documentation constructs
      use the documentation design of XML Schema Part 1 [XSD-1].  XML
      Schema's documentation model has the ability to support multi-
      lingual human-oriented documentation.

      Application Information: Application information constructs can be
      associated with variables, which allows Link Descriptions to
      attach machine-readable information to individual variables.  The
      application information constructs use the application information
      design of XML Schema Part 1 [XSD-1].



Wilde                    Expires March 20, 2014                 [Page 9]


Internet-Draft           HTTP Link Descriptions           September 2013


   For the purpose of this specification, the term "description" should
   be interpreted loosely.  Some aspects of descriptions can be formal,
   such as the datatypes of variables.  Thus, such a description can be
   used to drive general-purpose logic that knows no additional
   framework other than this specification.  However, for most other
   description aspects (concepts, documentation, and application
   information), this specification does not prescribe a description
   framework; it simply provides a structure how to deliver these
   descriptions.

   The descriptions of "concepts" and "datatypes" are not mutually
   exclusive.  On the contrary, a concept often will have associated
   constraints that essentially define a datatype.  The difference is
   that while concepts are only described by identifier (allowing a
   consumer to identify a concept that they know about), datatypes are
   described with a built-in vocabulary (XSD datatypes and their
   facets), allowing clients to interpret the datatype description.  As
   a consequence, when a consumer encounters an unknown concept, it adds
   little to the knowledge of the consumer, whereas a datatype
   description can always be interpreted and thus allows the consumer to
   learn about constraints of the associated variable in a declarative
   way.  It may therefore make sense to combine concepts and datatypes,
   if the goal is to be as self-describing as possible.


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



Wilde                    Expires March 20, 2014                [Page 10]


Internet-Draft           HTTP Link Descriptions           September 2013


   descriptions to both the template as a whole, and individual
   variables, this specification reuses the "appinfo" and
   "documentation" elements from XML Schema Part 1 [XSD-1].  These
   elements carry a "source" attribute, which is used (quoting from
   [XSD-1]) "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.

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



Wilde                    Expires March 20, 2014                [Page 11]


Internet-Draft           HTTP Link Descriptions           September 2013


   optional, but can help to improve the usefulness of link descriptions
   for developers.
<link xmlns="urn:ietf:rfc:XXXX" href="http://example.org/item42">
   <hint name="allow" value=' [ "PUT" ] '>
      <documentation xml:lang="en">For this particular resource, only PUT is supported. Specifically, this resource does not accept DELETE requests.</documentation>
   </hint>
   <hint name="formats" value=' { "image/png" : {} , "image/jpeg" : {} } '>
      <documentation xml:lang="en">Updates are accepted as PNG or JPEG representations.</documentation>
   </hint>
   <documentation xml:lang="en">Template for accessing an AtomPub media resource http://www.example.com/feed/item42, with the "edit-media" link by default allowing PUT/DELETE as per RFC 5023.</documentation>
</link>

5.2.  Pageable Collection

   ...
<link xmlns="urn:ietf:rfc:XXXX" hreft="http://example.org/{?pagesize,page}">
   <var name="pagesize" concept="http://example.com/feedpaging/pagesize" default="10">
      <restriction base="positiveInteger">
         <minInclusive value="1"/>
         <maxInclusive value="100"/>
      </restriction>
      <documentation xml:lang="en">Number of returned items per page.</documentation>
   </var>
   <var name="page" concept="http://example.com/feedpaging/page" default="1">
      <restriction base="positiveInteger"/>
      <documentation xml:lang="en">Page number of the returned page (based on the requested pagesize or a service-defined default).</documentation>
   </var>
   <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>
</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

      Required parameters: none

      Optional parameters: profile





Wilde                    Expires March 20, 2014                [Page 12]


Internet-Draft           HTTP Link Descriptions           September 2013


         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

      Restrictions on usage: none

      Author: Erik Wilde <dret@berkeley.edu>

      Change controller: IETF




Wilde                    Expires March 20, 2014                [Page 13]


Internet-Draft           HTTP Link Descriptions           September 2013


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
   they see fit".








Wilde                    Expires March 20, 2014                [Page 14]


Internet-Draft           HTTP Link Descriptions           September 2013


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.


10.  Change Log

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

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



Wilde                    Expires March 20, 2014                [Page 15]


Internet-Draft           HTTP Link Descriptions           September 2013


   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.

   [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-1]    Thompson, H., Beech, D., Mendelsohn, N., and M. Maloney,
              "XML Schema Part 1: Structures Second Edition", World Wide
              Web Consortium Recommendation REC-xmlschema-1-20041028,
              October 2004,
              <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.

   [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.  Non-Normative References

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




Wilde                    Expires March 20, 2014                [Page 16]


Internet-Draft           HTTP Link Descriptions           September 2013


   [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

   [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
<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"/>



Wilde                    Expires March 20, 2014                [Page 17]


Internet-Draft           HTTP Link Descriptions           September 2013


    </xs:simpleType>
    <xs:group name="descriptions">
        <xs:choice>
            <xs:element name="appinfo" id="appinfo">
                <xs:complexType mixed="true">
                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
                        <xs:any processContents="lax"/>
                    </xs:sequence>
                    <xs:attribute name="source" type="xs:anyURI"/>
                    <xs:anyAttribute namespace="##other" processContents="lax"/>
                </xs:complexType>
            </xs:element>
            <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:choice>
    </xs:group>
    <!-- these are simplified versions of the types for facet elements as defined in the schema for schemas at http://www.w3.org/2001/XMLSchema.xsd -->
    <xs:complexType name="facet">
        <xs:complexContent>
            <xs:restriction base="xs:anyType">
                <xs:attribute name="value" use="required"/>
            </xs:restriction>
        </xs:complexContent>
    </xs:complexType>
    <xs:complexType name="numFacet">
        <xs:complexContent>
            <xs:restriction base="ld:facet">
                <xs:attribute name="value" type="xs:nonNegativeInteger" use="required"/>
            </xs:restriction>
        </xs:complexContent>
    </xs:complexType>
    <xs:complexType name="link-type">
        <xs:choice maxOccurs="unbounded">
            <xs:element name="var">
                <xs:complexType>
                    <xs:sequence maxOccurs="unbounded" minOccurs="1">
                        <xs:element name="restriction" minOccurs="0">
                            <xs:complexType>
                                <xs:choice maxOccurs="unbounded" minOccurs="0">
                                    <xs:element name="minExclusive" type="ld:facet"/>



Wilde                    Expires March 20, 2014                [Page 18]


Internet-Draft           HTTP Link Descriptions           September 2013


                                    <xs:element name="minInclusive" type="ld:facet"/>
                                    <xs:element name="maxExclusive" type="ld:facet"/>
                                    <xs:element name="maxInclusive" type="ld:facet"/>
                                    <xs:element name="totalDigits">
                                        <xs:complexType>
                                            <xs:complexContent>
                                                <xs:restriction base="ld:numFacet">
                                                    <xs:attribute name="value" type="xs:positiveInteger" use="required"/>
                                                </xs:restriction>
                                            </xs:complexContent>
                                        </xs:complexType>
                                    </xs:element>
                                    <xs:element name="fractionDigits" type="ld:numFacet"/>
                                    <xs:element name="length" type="ld:numFacet"/>
                                    <xs:element name="minLength" type="ld:numFacet"/>
                                    <xs:element name="maxLength" type="ld:numFacet"/>
                                    <xs:element name="enumeration" type="ld:facet"/>
                                    <xs:element name="whiteSpace">
                                        <xs:complexType>
                                            <xs:complexContent>
                                                <xs:restriction base="ld:facet">
                                                    <xs:attribute name="value" use="required">
                                                        <xs:simpleType>
                                                            <xs:restriction base="xs:NMTOKEN">
                                                                <xs:enumeration value="preserve"/>
                                                                <xs:enumeration value="replace"/>
                                                                <xs:enumeration value="collapse"/>
                                                            </xs:restriction>
                                                        </xs:simpleType>
                                                    </xs:attribute>
                                                </xs:restriction>
                                            </xs:complexContent>
                                        </xs:complexType>
                                    </xs:element>
                                    <xs:element name="pattern" type="ld:facet"/>
                                </xs:choice>
                                <xs:attribute name="base" use="required" type="xs:QName"> </xs:attribute>
                            </xs:complexType>
                        </xs:element>
                        <xs:group ref="ld:descriptions" 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">



Wilde                    Expires March 20, 2014                [Page 19]


Internet-Draft           HTTP Link Descriptions           September 2013


                        <xs:annotation>
                            <xs:documentation>Identifies the variable by referring to a concept URI.</xs:documentation>
                        </xs:annotation>
                    </xs:attribute>
                    <xs:attribute name="default" type="xs:anySimpleType" use="optional">
                        <xs:annotation>
                            <xs:documentation>Defines the default value for the variable (used by the service if no value is provided). The value must match the type defined for the variable.</xs:documentation>
                        </xs:annotation>
                    </xs:attribute>
                </xs:complexType>
            </xs:element>
            <xs:group ref="ld:descriptions" maxOccurs="unbounded" minOccurs="0"/>
            <xs:element name="hint">
                <xs:complexType>
                    <xs:sequence>
                        <xs:group maxOccurs="unbounded" minOccurs="0" ref="ld:descriptions"/>
                    </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:assert test="count(../ld:hint[@name = current()/@name]) &lt;= 1">
                        <xs:annotation>
                            <xs:documentation>It is not allowed to have more than one hint with the same @name on the same link.</xs:documentation>
                        </xs:annotation>



Wilde                    Expires March 20, 2014                [Page 20]


Internet-Draft           HTTP Link Descriptions           September 2013


                    </xs:assert>
                </xs:complexType>
            </xs:element>
        </xs:choice>
        <xs:attribute name="hreft" type="ld:uriTemplate" use="optional"/>
        <xs:attribute name="href" type="xs:anyURI" use="optional"/>
        <xs:assert test="count(@href | @hreft) = 1">
            <xs:annotation>
                <xs:documentation>A link must either specify a URI (@href) or a URI Template (@hreft), but it cannot specify both at the same time.</xs:documentation>
            </xs:annotation>
        </xs:assert>
    </xs:complexType>
</xs:schema>


Appendix C.  XSLT for Generating Link Description HTML
<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>
                <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"/>



Wilde                    Expires March 20, 2014                [Page 21]


Internet-Draft           HTTP Link Descriptions           September 2013


                                <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>
                        <tr>
                            <th align="right">Appinfo:</th>
                            <td>
                                <xsl:call-template name="appinfo"/>
                            </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>
                                    <th>Appinfo</th>
                                </tr>
                            </thead>
                            <xsl:for-each select="ld:var">
                                <xsl:sort select="@name"/>
                                <tr>
                                    <td>
                                        <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>



Wilde                    Expires March 20, 2014                [Page 22]


Internet-Draft           HTTP Link Descriptions           September 2013


                                    </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>
                                                        <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>



Wilde                    Expires March 20, 2014                [Page 23]


Internet-Draft           HTTP Link Descriptions           September 2013


                                                    </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>
                                    <td>
                                        <xsl:call-template name="appinfo"/>
                                    </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>
                                    <th>Appinfo</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>
                                    </td>
                                    <td>
                                        <xsl:call-template name="documentation"/>
                                    </td>
                                    <td>
                                        <xsl:call-template name="appinfo"/>
                                    </td>
                                </tr>
                            </xsl:for-each>



Wilde                    Expires March 20, 2014                [Page 24]


Internet-Draft           HTTP Link Descriptions           September 2013


                        </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:template name="appinfo">
        <xsl:choose>
            <xsl:when test="ld:appinfo">
                <ul>
                    <xsl:for-each select="ld:appinfo">
                        <li>
                            <xsl:text>Source: </xsl:text>
                            <xsl:value-of select="@source"/>
                        </li>
                    </xsl:for-each>
                </ul>
            </xsl:when>
            <xsl:otherwise>
                <span class="msg">n/a</span>



Wilde                    Expires March 20, 2014                [Page 25]


Internet-Draft           HTTP Link Descriptions           September 2013


            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
</xsl:stylesheet>


Author's Address

   Erik Wilde
   EMC Corporation
   6801 Koll Center Parkway
   Pleasanton, CA 94566
   U.S.A.

   Phone: +1-925-6006244
   Email: erik.wilde@emc.com
   URI:   http://dret.net/netdret/


































Wilde                    Expires March 20, 2014                [Page 26]


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