CoRE                                                           Z. Shelby
Internet-Draft                                                 Sensinode
Intended status: Standards Track                        October 25, 2010
Expires: April 28, 2011

                            CoRE Link Format


   This document defines a link format for use by constrained CoAP web
   servers to describe URIs of resources offered along with other
   attributes.  Based on the HTTP Link Header format, the CoRE link
   format is carried as a payload and is assigned an Internet media
   type.  A well-known URI is defined as a default entry-point for
   requesting the list of links to resources hosted by a server.

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

   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 April 28, 2011.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   ( in effect on the date of
   publication of this document.  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

Shelby                   Expires April 28, 2011                 [Page 1]

Internet-Draft              CoRE Link Format                October 2010

   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Link Format  . . . . . . . . . . . . . . . . . . . . . . . . .  3
     2.1.  Target and context URIs  . . . . . . . . . . . . . . . . .  4
     2.2.  Link relation 'rel' usage  . . . . . . . . . . . . . . . .  5
     2.3.  Description 'd' usage  . . . . . . . . . . . . . . . . . .  5
     2.4.  Alternative URI 'sh' usage . . . . . . . . . . . . . . . .  5
     2.5.  Resource name 'n' usage  . . . . . . . . . . . . . . . . .  5
     2.6.  Content-type code 'ct' usage . . . . . . . . . . . . . . .  5
     2.7.  Resource identifier 'id' usage . . . . . . . . . . . . . .  6
     2.8.  Examples . . . . . . . . . . . . . . . . . . . . . . . . .  6
   3.  Well-known Interface . . . . . . . . . . . . . . . . . . . . .  6
     3.1.  Query Filtering  . . . . . . . . . . . . . . . . . . . . .  7
   4.  Security Considerations  . . . . . . . . . . . . . . . . . . .  8
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  9
     5.1.  Well-known 'core' URI  . . . . . . . . . . . . . . . . . .  9
     5.2.  New link-format Internet media type  . . . . . . . . . . .  9
   6.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 10
   7.  Changelog  . . . . . . . . . . . . . . . . . . . . . . . . . . 10
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 11
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 11
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11

Shelby                   Expires April 28, 2011                 [Page 2]

Internet-Draft              CoRE Link Format                October 2010

1.  Introduction

   The Constrained RESTful Environments (CoRE) working group aims at
   realizing the REST architecture in a suitable form for the most
   constrained nodes (e.g. 8-bit microcontrollers with limited RAM and
   ROM) and networks (e.g. 6LoWPAN).  CoRE is aimed at machine-to-
   machine (M2M) applications such as smart energy and building
   automation [I-D.shelby-core-coap-req].

   The discovery of resources offered by a constrained server is very
   important in machine-to-machine applications where there are no
   humans in the loop and static interfaces result in fragility.  The
   discovery of resources provided by an HTTP Web Server is typically
   called Web Discovery.  In this document we refer to the discovery of
   resources offered by a CoAP server as resource discovery.

   The core function of such a discovery mechanism is to provide URIs
   ("links") for the resources offered, complemented by information
   describing the relationship between the resource description and each
   resource as well as other attributes.  When such a collection of
   attributed resource references (links) is offered as a resource of
   its own (as opposed to as HTTP headers delivered with a different
   resource), we speak of its representation as a link-format.

   This document specifies a link-format for use in CoRE resource
   discovery by extending the HTTP Link Header Format
   [I-D.nottingham-http-link-header] to describe resources hosted by a
   constrained server.  The CoRE link-format is carried as a payload and
   is assigned an Internet media type.  A well-known URI "/.well-known/
   core" is defined as a default entry-point for requesting the list of
   links to resources hosted by a server.

2.  Link Format

   CoRE resource discovery extends the HTTP Link Header format specified
   in [I-D.nottingham-http-link-header] which is specified in Augmented
   Backus-Naur Form (ABNF) notation [RFC2616].  The format does not
   require special XML or binary parsing, and is extensible.

   This link format is used for a similar purpose to that described in
   [I-D.nottingham-http-link-header], to describe one or more
   relationships between resources.  However in this specification the
   link format is extended with specific constrained M2M link
   parameters, links are carried as a payload rather than in a message
   header, and a default interface is defined to discover resources
   described by these links.

Shelby                   Expires April 28, 2011                 [Page 3]

Internet-Draft              CoRE Link Format                October 2010

   [I-D.nottingham-http-link-header] did not require an Internet media
   type for this link format, as it assumes to be carried in an HTTP
   header.  This specification thus requests a Internet media type for
   this format (see Section 5.2).

   The CoRE link format uses the ABNF description and associated rules
   in Section 5 of [I-D.nottingham-http-link-header].  In addition, the
   URI, URI-reference and pchar rules are taken from [RFC3986].  The
   "Link:" text is omitted as that is part of the HTTP Link Header.
   Multiple link descriptions are separated by commas.  The CoRE link
   format MUST use the US-ASCII character set (support for RFC2231
   encoding of non-ASCII content TBD).  The following CoRE specific
   link-extension parameters to the format are defined:

      link-extension    = ( "d" "=" <"> URI-reference <">)
      link-extension    = ( "sh" "=" <"> URI-reference <">)
      link-extension    = ( "n" "=" quoted-string )
      link-extension    = ( "ct" "=" integer )
      link-extension    = ( "id" "=" quoted-string )
      integer           = 1*DIGIT

2.1.  Target and context URIs

   Each link description conveys one target URI as a URI-reference
   inside angle brackets ("<>").  The context URI of a link (also called
   base URI in [RFC3986]) conveyed in the description is by default the
   URI of the resource that returned the link-format representation.
   Thus each link can be thought of as describing a target resource
   hosted by the server in the absence of further relation information.
   This is an important difference to the way the HTTP Link Header
   format is used, as it is included in the header of an HTTP response
   for some URI (this URI is by default the context).  Thus the HTTP
   Link Header is by default relating the target URI to the URI that was
   requested.  In comparison, the CoRE link format includes one or more
   link entries, each describing a resource hosted by a server.  See
   Section 5 of [RFC3986] for a description of how URIs are constructed
   from URI references.

   As per Section 5.2 of [I-D.nottingham-http-link-header] a link
   description MAY include an "anchor" attribute, in which case the
   context is the URI included in that attribute.  This can be used to
   describe a relationship between two resources.  A consuming
   implementation can however choose to ignore such links.  It is not
   expected that most implementations will be able to derive useful
   information from explicitly anchored links.

Shelby                   Expires April 28, 2011                 [Page 4]

Internet-Draft              CoRE Link Format                October 2010

2.2.  Link relation 'rel' usage

   Link descriptions in CoRE are typically used to describe entry points
   to services hosted by the server, and thus in the absence of the rel
   attribute the registered "service" relation type is assumed.  In the
   CoRE link format the service relation type indicates that the link is
   a service hosted by the server (in the absence of the anchor
   attribute).  A description can make use of any registered relation
   type or extension types in the form of a URI by including the rel

2.3.  Description 'd' usage

   The description "d" attribute can provide a URI to a specific
   interface definition used to access the target resource.  This could
   be for example a URI to the WADL definition of the target resource.
   Multiple description attributes MAY appear in a link description.

2.4.  Alternative URI 'sh' usage

   This attribute can be included to define an alternative short URI
   which can also be used to access the target resource.  Multiple
   alternative short URI attributes MAY appear in a link description.

2.5.  Resource name 'n' usage

   The resource name "n" attribute is used to assign either a human
   readable or a semantically important name to a resource.  In the case
   of a temperature sensor resource the name could be something like
   "Temperature in Centigrade", a URI to an ontology like
   "" or an
   application-specific semantic name like "TemperatureC".  Multiple
   name attributes MAY appear in a link description.

2.6.  Content-type code 'ct' usage

   The Content-type code "ct" attribute provides a hint about the
   Internet media type this resource returns.  The value is in the CoAP
   identifier code format as a decimal ASCII integer
   [I-D.ietf-core-coap].  For example application/xml would be indicated
   as "ct=41".  If no Content-type code attribute is present then
   nothing about the type can be assumed.  The Content-type code
   attribute MUST NOT appear more than once in a link description.

   Alternatively, the "type" attribute MAY be used to indicate an
   Internet media type as a quoted-string.  It is not however expected
   that constrained implementations are able to parse quoted-string
   Content-type values.

Shelby                   Expires April 28, 2011                 [Page 5]

Internet-Draft              CoRE Link Format                October 2010

2.7.  Resource identifier 'id' usage

   The resource identifier "id" field is a unique identifier (e.g.  UUID
   or XRI) for this resource for use in e.g. resource or search
   directories.  The resource identifier attribute MUST NOT appear more
   than once in a link description.

2.8.  Examples

   A few examples of typical link descriptions in this format follows.
   Multiple resource descriptions in a representation are separated by
   commas.  Commas can also occur in quoted strings and URIs but do not
   end a description.  Linefeeds never occur in the actual format, but
   are shown in the example for readability.

   This example includes link descriptions for an index to sensors
   hosted by a server, along with links two two different sensors.

   GET /.well-known/core

   </sensors>;rel="index";n="Sensor Index",

   This example arranges link descriptions hierarchically, with the
   entry point including a link description to a sub-resource containing
   link descriptions about the sensors.

   GET /.well-known/core


   GET /.well-known/core/sensors


3.  Well-known Interface

   Resource discovery in CoRE is accomplished through the use of a well-
   known resource URI which returns a list of links (resource
   descriptions) offered by that constrained server.  Well-known
   resources have a path component that begins with "/.well-known/" as
   specified in [RFC5785].  This document defines a new well-known path
   prefix for CoRE discovery "/.well-known/core" [Section 5.1].  A

Shelby                   Expires April 28, 2011                 [Page 6]

Internet-Draft              CoRE Link Format                October 2010

   server implementing this specification MUST support this path prefix
   on the default port appropriate for the protocol for the purpose of
   resource discovery.  It is however up to the application which link
   descriptions are included and how they are organized.  In the absense
   of any links, a zero-length payload is returned.  The resource
   representation of this resource is described in Section 2.

   The CoRE resource discovery interface supports the following

   o  Performing a GET on /.well-known/core to the default port returns
      a list of link descriptions available from a CoAP server (if any).

   o  Filtering may be performed on any of the link format attributes
      using a query string as specified in Section 3.1.  For example
      [GET /.well-known/core?n=TemperatureC] would request resources
      with the name TemperatureC.  A server is not however required to
      support filtering.

   o  More capable servers such as proxies could support a resource
      directory by requesting the resource descriptions of other end-
      points or accepting [POST /.well-known/core messages] from other
      servers.  This adds the resources of other end-points as a sub-
      resource in which absolute URIs are included for the link-values.
      The details of such resource directory functionality is however
      out of scope for this document.

   End-points with a large number of resources SHOULD include resource
   descriptions only for important services or collections and organize
   their resource descriptions into a hierarchy of link resources.  This
   is done by including links in the /.well-known/core list which point
   to other resource lists, e.g. </.well-known/core/sensors>.  Such a
   hierarchy SHOULD be under the /.well-known/core path but could be
   located elsewhere.

3.1.  Query Filtering

   A server implementing this document MAY recognize the query part of a
   resource-discovery URI as a filter on the resources to be returned.
   The query part should conform to the following syntax:

     filter-query = resource-param "=" query-pattern
     resource-param = "uri" | "d" | "sh" | "n" | "id"
     query-pattern = 1*pchar [ "*" ]

   The resource-param "uri" refers to the URI-reference between the "<"

Shelby                   Expires April 28, 2011                 [Page 7]

Internet-Draft              CoRE Link Format                October 2010

   and ">" characters of a link-value.  Other resource-param values
   refer to the link attribute they name.  (TBD: Do we want to add the
   resource description attributes that I excluded, or the standard
   link-param attributes from I-D.nottingham-http-link-header?)
   Filtering is performed by comparing the query-pattern against the
   value of the attribute identified by the resource-param for each
   link-value in the collection of resources identified by the URI path.

   If the decoded query-pattern does not end with "*", a link value
   matches the query only if the value of the attribute or URI-reference
   denoted by the resource-param is bytewise identical to the query-
   pattern.  If the decoded query-pattern ends with "*", it is
   sufficient that the remainder of the query-pattern be a prefix of the
   value denoted by the resource-param.

   It is not expected that very constrained nodes support filtering.
   Implementations not supporting filtering MUST simply ignore the query
   string and return the whole resource for unicast requests.  An exact
   match is performed on the query string, and a 200 OK response is
   returned with link descriptions that contains the matching entries
   (if any).  In contrast, a multicast request with a query string MUST
   not be responded to if filtering is not supported (to avoid a
   needless response storm).  If resource descriptions are organized
   hierarchically, a query on the root resource /.well-known/core SHOULD
   return all matching resource descriptions from the entire hierarchy.
   An example query on the link descriptions from Section 2 may look

   GET /.well-known/core?n=LightLux


4.  Security Considerations

   This document needs the same security considerations as described in
   Section 7 of [I-D.nottingham-http-link-header].  The /.well-known/
   core resource may be protected e.g. using DTLS when hosted on a CoAP
   server as per [I-D.ietf-core-coap] Section 10.2.

   Great care must be taken when processing multicast requests using
   CoAP for the well-known link-format resources, as this could be used
   to perform denial of service on a constrained network.  A multicast
   request SHOULD only be accepted if the request is sufficiently
   authenticated and secured.

Shelby                   Expires April 28, 2011                 [Page 8]

Internet-Draft              CoRE Link Format                October 2010

5.  IANA Considerations

5.1.  Well-known 'core' URI

   This memo registers the "core" well-known URI in the Well-Known URI
   Registry as defined by [RFC5785].

   URI suffix: core

   Change controller: IETF

   Specification document(s): [[ this document ]]

   Related information: None

5.2.  New link-format Internet media type

   This memo registers the a new Internet media type for the CoRE link
   format, application/link-format.

   Type name: application

   Subtype name: link-format

   Required parameters: None

   Optional parameters: The query string may contain uri= to match the
   URI, or any other attribute defined for the link format to match that

   Encoding considerations: US-ASCII

   Security considerations: None

   Interoperability considerations:

   Published specification: [[ this document ]]

   Applications that use this media type: CoAP server and client

   Additional information:

   Magic number(s):

   File extension(s):

   Macintosh file type code(s):

Shelby                   Expires April 28, 2011                 [Page 9]

Internet-Draft              CoRE Link Format                October 2010

   Intended usage: COMMON

   Restrictions on usage: None

   Author: CoRE WG

   Change controller: IETF

6.  Acknowledgments

   Special thanks to Mark Nottingham and Eran Hammer-Lahav for
   discussions and ideas that led to this draft, and to Carsten Bormann
   and Peter Bigot for extensive comments and contributions that
   improved the text.

   Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido
   Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey
   Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin,
   Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed
   Beroset, Gilman Tolle, Robby Simpson, Peter Bigot, Colin O'Flynn and
   David Ryan for helpful comments and discussions that have shaped the

7.  Changelog

   Changes from ietf-00 to ietf-01:

      o Editorial changes to correct references.

      o Formal definition for filter query string.

      o Removed URI-reference option from "n" and "id".

      o Added security text about multicast requests.

   Changes from shelby-00 to ietf-00:

      o Fixed the ABNF link-extension definitions (quotes around URIs,
      integer definition).

      o Clarified that filtering is optional, and the query string is to
      be ignored if not supported (and the URL path processed as

      o Required support of wildcard * processing if filtering is

Shelby                   Expires April 28, 2011                [Page 10]

Internet-Draft              CoRE Link Format                October 2010

      o Removed the aussumption of a default content-type assumption.

8.  References

8.1.  Normative References

              Shelby, Z., Frank, B., and D. Sturek, "Constrained
              Application Protocol (CoAP)", draft-ietf-core-coap-02
              (work in progress), September 2010.

              Nottingham, M., "Web Linking",
              draft-nottingham-http-link-header-10 (work in progress),
              May 2010.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

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

8.2.  Informative References

              Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R.
              Kelsey, "CoAP Requirements and Features",
              draft-shelby-core-coap-req-02 (work in progress),
              October 2010.

Author's Address

   Zach Shelby
   Kidekuja 2
   Vuokatti  88600

   Phone: +358407796297

Shelby                   Expires April 28, 2011                [Page 11]