draft-ietf-core-link-format-13.txt   draft-ietf-core-link-format-14.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft Sensinode Internet-Draft Sensinode
Intended status: Standards Track May 23, 2012 Intended status: Standards Track June 1, 2012
Expires: November 24, 2012 Expires: December 3, 2012
CoRE Link Format CoRE Link Format
draft-ietf-core-link-format-13 draft-ietf-core-link-format-14
Abstract Abstract
This specification defines Web Linking using a link format for use by This specification defines Web Linking using a link format for use by
constrained web servers to describe hosted resources, their constrained web servers to describe hosted resources, their
attributes and other relationships between links. Based on the HTTP attributes and other relationships between links. Based on the HTTP
Link Header field defined in RFC5988, the CoRE Link Format is carried Link Header field defined in RFC5988, the CoRE Link Format is carried
as a payload and is assigned an Internet media type. A well-known as a payload and is assigned an Internet media type. A well-known
URI is defined as a default entry-point for requesting the links URI is defined as a default entry-point for requesting the links
hosted by a server. hosted by a server.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 24, 2012. This Internet-Draft will expire on December 3, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 31 skipping to change at page 2, line 31
3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10
3.2. Interface description 'if' attribute . . . . . . . . . . . 10 3.2. Interface description 'if' attribute . . . . . . . . . . . 10
3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 11 3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 11
4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11
4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16
7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16
7.3. New link-format Internet media type . . . . . . . . . . . 16 7.3. New link-format Internet media type . . . . . . . . . . . 17
7.4. Constrained RESTful Environments (CORE) Parameters 7.4. Constrained RESTful Environments (CORE) Parameters
Registry . . . . . . . . . . . . . . . . . . . . . . . . . 17 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 18
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19
9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 19 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 20
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
10.1. Normative References . . . . . . . . . . . . . . . . . . . 23 10.1. Normative References . . . . . . . . . . . . . . . . . . . 24
10.2. Informative References . . . . . . . . . . . . . . . . . . 24 10.2. Informative References . . . . . . . . . . . . . . . . . . 24
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
The Constrained RESTful Environments (CoRE) working group aims at The Constrained RESTful Environments (CoRE) realizes the
realizing the Representational State Transfer (REST) architecture Representational State Transfer (REST) architecture [REST] in a
[REST] in a suitable form for the most constrained nodes (e.g. 8-bit suitable form for the most constrained nodes (e.g. 8-bit
microcontrollers with limited memory) and networks (e.g. 6LoWPAN microcontrollers with limited memory) and networks (e.g. 6LoWPAN
[RFC4919]). CoRE is aimed at Machine-to-Machine (M2M) applications [RFC4919]). CoRE is aimed at Machine-to-Machine (M2M) applications
such as smart energy and building automation. such as smart energy and building automation.
The discovery of resources hosted by a constrained server is very The discovery of resources hosted by a constrained server is very
important in machine-to-machine applications where there are no important in machine-to-machine applications where there are no
humans in the loop and static interfaces result in fragility. The humans in the loop and static interfaces result in fragility. The
discovery of resources provided by an HTTP [RFC2616] Web Server is discovery of resources provided by an HTTP [RFC2616] Web Server is
typically called Web Discovery and the description of relations typically called Web Discovery and the description of relations
between resources is called Web Linking [RFC5988]. In the present between resources is called Web Linking [RFC5988]. In the present
skipping to change at page 3, line 37 skipping to change at page 3, line 37
resources and possible further link relations. In CoRE this resources and possible further link relations. In CoRE this
collection of links is carried as a resource of its own (as opposed collection of links is carried as a resource of its own (as opposed
to HTTP headers delivered with a specific resource). This document to HTTP headers delivered with a specific resource). This document
specifies a link format for use in CoRE Resource Discovery by specifies a link format for use in CoRE Resource Discovery by
extending the HTTP Link Header format [RFC5988] to describe these extending the HTTP Link Header format [RFC5988] to describe these
link descriptions. The CoRE Link Format is carried as a payload and link descriptions. The CoRE Link Format is carried as a payload and
is assigned an Internet media type. A well-known relative URI is assigned an Internet media type. A well-known relative URI
"/.well-known/core" is defined as a default entry-point for "/.well-known/core" is defined as a default entry-point for
requesting the list of links about resources hosted by a server, and requesting the list of links about resources hosted by a server, and
thus performing CoRE Resource Discovery. This specification is thus performing CoRE Resource Discovery. This specification is
applicable for use with CoAP [I-D.ietf-core-coap], HTTP or any other applicable for use with Constrained Application Protocol (CoAP)
suitable web transfer protocol. The link format can also be saved in [I-D.ietf-core-coap], HTTP or any other suitable web transfer
file format. protocol. The link format can also be saved in file format.
1.1. Web Linking in CoRE 1.1. Web Linking in CoRE
Technically the CoRE Link Format is a serialization of a typed link Technically the CoRE Link Format is a serialization of a typed link
as specified in [RFC5988], used to describe relationships between as specified in [RFC5988], used to describe relationships between
resources, so-called "Web Linking". In this specification Web resources, so-called "Web Linking". In this specification Web
Linking is extended with specific constrained M2M attributes, links Linking is extended with specific constrained M2M attributes, links
are carried as a message payload rather than in an HTTP Link Header are carried as a message payload rather than in an HTTP Link Header
field, and a default interface is defined to discover resources field, and a default interface is defined to discover resources
hosted by a server. This specification also defines a new relation hosted by a server. This specification also defines a new relation
skipping to change at page 9, line 17 skipping to change at page 9, line 17
Each link conveys one target URI as a URI-reference inside angle Each link conveys one target URI as a URI-reference inside angle
brackets ("<>"). The context URI of a link (also called base URI in brackets ("<>"). The context URI of a link (also called base URI in
[RFC3986]) is determined by the following rules in this [RFC3986]) is determined by the following rules in this
specification: specification:
(a) The context URI is set to the anchor parameter, when specified, (a) The context URI is set to the anchor parameter, when specified,
or or
(b) Origin of the target URI, when specified (b) Origin of the target URI, when specified
(c) Origin of the link format document's base URI. (c) Origin of the link format resource's base URI.
2.2. Link relations 2.2. Link relations
Since links in the CoRE Link Format are typically used to describe Since links in the CoRE Link Format are typically used to describe
resources hosted by a server, and thus in the absence of the relation resources hosted by a server, and thus in the absence of the relation
parameter the new relation type "hosts" is assumed (see Section 7.2). parameter the new relation type "hosts" is assumed (see Section 7.2).
The "hosts" relation type (from the verb "to host") indicates that The "hosts" relation type (from the verb "to host") indicates that
the target URI is a resource hosted by the server (i.e. server hosts the target URI is a resource hosted by the server (i.e. server hosts
resource) indicated by the context URI. The target URI MUST be a resource) indicated by the context URI. The target URI MUST be a
relative URI of the context URI for this relation type. relative URI of the context URI for this relation type.
skipping to change at page 12, line 46 skipping to change at page 12, line 46
The search name "href" refers to the URI-reference between the "<" The search name "href" refers to the URI-reference between the "<"
and ">" characters of a link. Both Value Strings match a target and ">" characters of a link. Both Value Strings match a target
attribute only if it exists. Value Strings are percent-decoded attribute only if it exists. Value Strings are percent-decoded
([RFC3986] section 2.1) before matching; similarly, any target ([RFC3986] section 2.1) before matching; similarly, any target
attributes notated as quoted-string are interpreted as defined in attributes notated as quoted-string are interpreted as defined in
section 2.2 of [RFC2616]. After these steps, a Complete Value String section 2.2 of [RFC2616]. After these steps, a Complete Value String
matches a target attribute if it is bitwise identical. A Prefix matches a target attribute if it is bitwise identical. A Prefix
Value String matches a target attribute if is is a bitwise prefix of Value String matches a target attribute if is is a bitwise prefix of
the target attribute (where any string is a prefix of itself). Empty the target attribute (where any string is a prefix of itself). Empty
prefix value strings are allowed, by the definition above they match prefix value strings are allowed, by the definition above they match
any target attribute that does exist. any target attribute that does exist. Note that relation-type target
attributes can contain multiple values, and each value MUST be
treated as a separate target attribute when matching.
It is not expected that very constrained nodes support filtering. It is not expected that very constrained nodes support filtering.
Implementations not supporting filtering MUST simply ignore the query Implementations not supporting filtering MUST simply ignore the query
string and return the whole resource for unicast requests. string and return the whole resource for unicast requests.
When using a transfer protocol like the Constrained Application When using a transfer protocol like the Constrained Application
Protocol (CoAP) that supports multicast requests, special care needs Protocol (CoAP) that supports multicast requests, special care needs
to be taken. A multicast request with a query string SHOULD NOT be to be taken. A multicast request with a query string SHOULD NOT be
responded to if filtering is not supported or if the filter does not responded to if filtering is not supported or if the filter does not
match (to avoid a needless response storm). The exception is in match (to avoid a needless response storm). The exception is in
cases where the IP stack interface is not able to indicate that the cases where the IP stack interface is not able to indicate that the
destination address was multicast. destination address was multicast.
skipping to change at page 13, line 38 skipping to change at page 13, line 41
5. Examples 5. Examples
A few examples of typical link descriptions in this format follows. A few examples of typical link descriptions in this format follows.
Multiple resource descriptions in a representation are separated by Multiple resource descriptions in a representation are separated by
commas. Linefeeds are also included in these examples for commas. Linefeeds are also included in these examples for
readability. Although the following examples use CoAP response readability. Although the following examples use CoAP response
codes, the examples are applicable to HTTP as well (the corresponding codes, the examples are applicable to HTTP as well (the corresponding
response code would be 200 OK). response code would be 200 OK).
This example includes links to two different sensors sharing the same This example includes links to two different sensors sharing the same
Interface Description. Interface Description. Note that the default relation type for this
link format is "hosts" in links with no rel= target attribute. Thus
the links in this example tell that the Origin server /.well-known/
core was requested from (the context) hosts the resources /sensors/
temp and /sensors/light (each a target).
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 Content RES: 2.05 Content
</sensors/temp>;if="sensor", </sensors/temp>;if="sensor",
</sensors/light>;if="sensor" </sensors/light>;if="sensor"
Without the linefeeds inserted here for readability, the format Without the linefeeds inserted here for readability, the format
actually looks as follows. actually looks as follows.
</sensors/temp>;if="sensor",</sensors/light>;if="sensor" </sensors/temp>;if="sensor",</sensors/light>;if="sensor"
This example arranges link descriptions hierarchically, with the This example arranges link descriptions hierarchically, with the
entry point including a link to a sub-resource containing links about entry point including a link to a sub-resource containing links about
the sensors. the sensors.
REQ: GET /.well-known/core REQ: GET /.well-known/core
skipping to change at page 14, line 14 skipping to change at page 14, line 20
entry point including a link to a sub-resource containing links about entry point including a link to a sub-resource containing links about
the sensors. the sensors.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 Content RES: 2.05 Content
</sensors>;ct=40 </sensors>;ct=40
REQ: GET /sensors REQ: GET /sensors
RES: 2.05 "Content" RES: 2.05 Content
</sensors/temp>;rt="temperature-c";if="sensor", </sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="light-lux";if="sensor" </sensors/light>;rt="light-lux";if="sensor"
An example query filter may look like: An example query filter may look like:
REQ: GET /.well-known/core?rt=light-lux REQ: GET /.well-known/core?rt=light-lux
RES: 2.05 "Content" RES: 2.05 Content
</sensors/light>;rt="light-lux";if="sensor" </sensors/light>;rt="light-lux";if="sensor"
Note that relation-type attributes like rt=, if= and rel= can have
multiple values separated by spaces. A query filter parameter can
match any one of those values, as in this example:
REQ: GET /.well-known/core?rt=light-lux
RES: 2.05 Content
</sensors/light>;rt="light-lux core.sen-light";if="sensor"
This example shows the use of an anchor attribute to relate the This example shows the use of an anchor attribute to relate the
temperature sensor resource to an external description and to an temperature sensor resource to an external description and to an
alternative URI. alternative URI.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 "Content" RES: 2.05 Content
</sensors>;ct=40;title="Sensor Index", </sensors>;ct=40;title="Sensor Index",
</sensors/temp>;rt="temperature-c";if="sensor", </sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="light-lux";if="sensor", </sensors/light>;rt="light-lux";if="sensor",
<http://www.example.com/sensors/t123>;anchor="/sensors/temp" <http://www.example.com/sensors/t123>;anchor="/sensors/temp"
;rel="describedby", ;rel="describedby",
</t>;anchor="/sensors/temp";rel="alternate" </t>;anchor="/sensors/temp";rel="alternate"
If a client is interested to find relations about a particular If a client is interested to find relations about a particular
resource, it can perform a query on the anchor parameter: resource, it can perform a query on the anchor parameter:
REQ: GET /.well-known/core?anchor=/sensors/temp REQ: GET /.well-known/core?anchor=/sensors/temp
RES: 2.05 "Content" RES: 2.05 Content
<http://www.example.com/sensors/temp123>;anchor="/sensors/temp" <http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
;rel="describedby", ;rel="describedby",
</t>;anchor="/sensors/temp";rel="alternate" </t>;anchor="/sensors/temp";rel="alternate"
The following example shows a large firmware resource with a size The following example shows a large firmware resource with a size
attribute. The consumer of this link would use the sz attribute to attribute. The consumer of this link would use the sz attribute to
determine if the resource representation is too large and if block determine if the resource representation is too large and if block
transfer would be required to request it. In this case a client with transfer would be required to request it. In this case a client with
only a 64 KiB flash might only support a 16-bit integer for storing only a 64 KiB flash might only support a 16-bit integer for storing
the sz attribute. Thus a special flag or value should be used to the sz attribute. Thus a special flag or value should be used to
indicate "Big" (larger than 64 KiB). indicate "Big" (larger than 64 KiB).
REQ: GET /.well-known/core?rt=firmware REQ: GET /.well-known/core?rt=firmware
skipping to change at page 15, line 14 skipping to change at page 15, line 35
The following example shows a large firmware resource with a size The following example shows a large firmware resource with a size
attribute. The consumer of this link would use the sz attribute to attribute. The consumer of this link would use the sz attribute to
determine if the resource representation is too large and if block determine if the resource representation is too large and if block
transfer would be required to request it. In this case a client with transfer would be required to request it. In this case a client with
only a 64 KiB flash might only support a 16-bit integer for storing only a 64 KiB flash might only support a 16-bit integer for storing
the sz attribute. Thus a special flag or value should be used to the sz attribute. Thus a special flag or value should be used to
indicate "Big" (larger than 64 KiB). indicate "Big" (larger than 64 KiB).
REQ: GET /.well-known/core?rt=firmware REQ: GET /.well-known/core?rt=firmware
RES: 2.05 "Content" RES: 2.05 Content
</firmware/v2.1>;rt="firmware";sz=262144 </firmware/v2.1>;rt="firmware";sz=262144
6. Security Considerations 6. Security Considerations
This specification has the same security considerations as described This specification has the same security considerations as described
in Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be in Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be
protected e.g. using DTLS when hosted on a CoAP server as per protected e.g. using DTLS when hosted on a CoAP server as per
[I-D.ietf-core-coap] Section 10.2. [I-D.ietf-core-coap] Section 10.2.
Some servers might provide resource discovery services to a mix of Some servers might provide resource discovery services to a mix of
skipping to change at page 16, line 33 skipping to change at page 17, line 8
[RFC5988]. [RFC5988].
Relation Name: hosts Relation Name: hosts
Description: Refers to a resource hosted by the server indicated by Description: Refers to a resource hosted by the server indicated by
the link context. the link context.
Reference: [[ this document ]] Reference: [[ this document ]]
Notes: This relation is used in CoRE where links are retrieved as a Notes: This relation is used in CoRE where links are retrieved as a
"/.well-known/core" resource representation. "/.well-known/core" resource representation, and is the default
relation type in the CoRE Link Format.
Application Data: None Application Data: None
7.3. New link-format Internet media type 7.3. New link-format Internet media type
This memo registers the a new Internet media type for the CoRE link This memo registers the a new Internet media type for the CoRE link
format, application/link-format. format, application/link-format.
Type name: application Type name: application
skipping to change at page 19, line 40 skipping to change at page 20, line 17
Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido
Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey
Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin,
Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed
Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan
for helpful comments and discussions that have shaped the document. for helpful comments and discussions that have shaped the document.
9. Changelog 9. Changelog
Changes from ietf-13 to ietf-14:
o Editorial clarifications.
o Examples and explanation for filtering when a target attribute
of relation-type contains multiple values.
Changes from ietf-12 to ietf-13: Changes from ietf-12 to ietf-13:
o Improvements to the new CoRE Parameters registry o Improvements to the new CoRE Parameters registry
o Replaced the Section 4.1 ABNF Query Filter definition with a URI o Replaced the Section 4.1 ABNF Query Filter definition with a URI
Template (#240) Template (#240)
o Aligned examples with rt= and if= value rules o Aligned examples with rt= and if= value rules
o Clarified that "href" can not be a link parameter o Clarified that "href" can not be a link parameter
 End of changes. 22 change blocks. 
25 lines changed or deleted 49 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/