draft-ietf-core-link-format-03.txt   draft-ietf-core-link-format-04.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft Sensinode Internet-Draft Sensinode
Intended status: Standards Track March 14, 2011 Intended status: Standards Track May 3, 2011
Expires: September 15, 2011 Expires: November 4, 2011
CoRE Link Format CoRE Link Format
draft-ietf-core-link-format-03 draft-ietf-core-link-format-04
Abstract Abstract
This document defines Web Linking using a link format for use by This document 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 format defined in RFC5988, the CoRE Link Format is Link Header format defined in RFC5988, the CoRE Link Format is
carried as a payload and is assigned an Internet media type. A well- 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 known URI is defined as a default entry-point for requesting the
links hosted by a server. links 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 September 15, 2011. This Internet-Draft will expire on November 4, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 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 26 skipping to change at page 2, line 26
2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Target and context URIs . . . . . . . . . . . . . . . . . 7 2.1. Target and context URIs . . . . . . . . . . . . . . . . . 7
2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 7 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 7
2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 8 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 8
3. CoRE link extensions . . . . . . . . . . . . . . . . . . . . . 8 3. CoRE link extensions . . . . . . . . . . . . . . . . . . . . . 8
3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 8 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 8
3.2. Interface description 'if' attribute . . . . . . . . . . . 9 3.2. Interface description 'if' attribute . . . . . . . . . . . 9
3.3. Content-type code 'ct' attribute . . . . . . . . . . . . . 9 3.3. Content-type code 'ct' attribute . . . . . . . . . . . . . 9
3.4. Maximum size estimate 'sz' attribute . . . . . . . . . . . 9 3.4. Maximum size estimate 'sz' attribute . . . . . . . . . . . 9
4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 10 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 10
4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 10 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 11
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7.1. Attribute Registry . . . . . . . . . . . . . . . . . . . . 13 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 14
7.2. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 14 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 14
7.3. New 'hosts' relation type . . . . . . . . . . . . . . . . 14 7.3. New link-format Internet media type . . . . . . . . . . . 14
7.4. New link-format Internet media type . . . . . . . . . . . 15 7.4. New CoAP Media Type registry entry . . . . . . . . . . . . 16
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16
9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18
10.2. Informative References . . . . . . . . . . . . . . . . . . 18 10.2. Informative References . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction 1. Introduction
The Constrained RESTful Environments (CoRE) working group aims at The Constrained RESTful Environments (CoRE) working group aims at
realizing the Representational State Transfer (REST) architecture realizing the Representational State Transfer (REST) architecture
skipping to change at page 3, line 25 skipping to change at page 3, line 25
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 this document between resources is called Web Linking [RFC5988]. In this document
we refer to the discovery of resources hosted by a constrained web we refer to the discovery of resources hosted by a constrained web
server, their attributes and other resource relations as CoRE server, their attributes and other resource relations as CoRE
Resource Discovery. Resource Discovery.
The main function of such a discovery mechanism is to provide The main function of such a discovery mechanism is to provide
Universal Resource Indicators (URIs, called links) for the resources Universal Resource Identifiers (URIs, called links) for the resources
hosted by the server, complemented by attributes about those hosted by the server, complemented by attributes about those
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 URI "/.well-known/ 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 core" is defined as a default entry-point for requesting the list of
links about resources hosted by a server, and thus performing CoRE links about resources hosted by a server, and thus performing CoRE
skipping to change at page 4, line 40 skipping to change at page 4, line 40
1.2.1. Discovery 1.2.1. Discovery
In M2M application, for example home or building automation, there is In M2M application, for example home or building automation, there is
a need for local clients and servers to find and interact with each a need for local clients and servers to find and interact with each
other without human intervention. The CoRE Link Format can be used other without human intervention. The CoRE Link Format can be used
by servers in such environments to enable Resource Discovery of the by servers in such environments to enable Resource Discovery of the
resources hosted by the server. resources hosted by the server.
Resource Discovery can be performed either unicast or multicast. Resource Discovery can be performed either unicast or multicast.
When a server's IP address is already known, either a priori or When a server's IP address is already known, either a priori or
resolved via the Domain Name System (DNS), unicast disovery is resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast
performed in order to locate the entry point to the resource of discovery is performed in order to locate the entry point to the
interest. This is performed using a GET to /.well-known/core on the resource of interest. This is performed using a GET to /.well-known/
server, which returns a payload in the CoRE Link Format. A client core on the server, which returns a payload in the CoRE Link Format.
would then match the appropriate Resource Type, Interface Description A client would then match the appropriate Resource Type, Interface
and possible Content-Type for its application. These attributes may Description and possible Content-Type [RFC2045] for its application.
also be included in the query string in order to filter the number of These attributes may also be included in the query string in order to
links returned in a response. filter the number of links returned in a response.
Multicast resource discovery is useful when a client needs to locate Multicast resource discovery is useful when a client needs to locate
a resource within a limited scope, and that scope supports IP a resource within a limited scope, and that scope supports IP
multicast. A GET request to the appropriate multicast address is multicast. A GET request to the appropriate multicast address is
made for /.well-known/core. In order to limit the number and size or made for /.well-known/core. In order to limit the number and size or
responses, a query string is recommended with the known attributes. responses, a query string is recommended with the known attributes.
Typically a resource would be discovered based on its Resource Type Typically a resource would be discovered based on its Resource Type
and/or Interface Description, along with possible application and/or Interface Description, along with possible application
specific attributes. specific attributes.
skipping to change at page 6, line 13 skipping to change at page 6, line 13
and concepts that are discussed in [RFC5988]. This specification and concepts that are discussed in [RFC5988]. This specification
makes use of the following terminology: makes use of the following terminology:
Web Linking Web Linking
A framework for indicating the relationships between web A framework for indicating the relationships between web
resources. resources.
Link Link
Also called "typed links" in RFC5988. A link is a typed Also called "typed links" in RFC5988. A link is a typed
connection between two resources identified by URIs. Made up of a connection between two resources identified by URIs. Made up of a
context URI, a link relation type, a tarfet URI, and optional context URI, a link relation type, a target URI, and optional
target attributes. target attributes.
Link Format Link Format
A particular serialisation of typed links. A particular serialisation of typed links.
CoRE Link Format CoRE Link Format
A particular serialization of typed links based the HTTP Link A particular serialization of typed links based the HTTP Link
Header serialization defined in Section 5 of RFC5988, but carried Header serialization defined in Section 5 of RFC5988, but carried
as a resource representation with a MIME type. as a resource representation with a MIME type.
skipping to change at page 6, line 50 skipping to change at page 6, line 50
is just one serialization of typed links defined in [RFC5988], others is just one serialization of typed links defined in [RFC5988], others
include HTML link, Atom feed links [RFC4287] or HTTP Link Headers. include HTML link, Atom feed links [RFC4287] or HTTP Link Headers.
It is expected that resources discovered in the CoRE Link Format may It is expected that resources discovered in the CoRE Link Format may
also be made available in alternative formats on the greater also be made available in alternative formats on the greater
Internet. The CoRE Link Format is only expected to be supported in Internet. The CoRE Link Format is only expected to be supported in
constrained networks and M2M systems. constrained networks and M2M systems.
Section 5 of [RFC5988] did not require an Internet media type for the Section 5 of [RFC5988] did not require an Internet media type for the
defined link format, as it was defined to be carried in an HTTP defined link format, as it was defined to be carried in an HTTP
header. This specification thus defines a Internet media type for header. This specification thus defines a Internet media type for
the CoRE Link Format (see Section 7.4). the CoRE Link Format (see Section 7.3).
The CoRE link format uses the ABNF description and associated rules The CoRE link format uses the ABNF description and associated rules
in Section 5 of [RFC5988]. In addition, the pchar rule is taken from in Section 5 of [RFC5988]. In addition, the pchar rule is taken from
[RFC3986]. The "Link:" text is omitted as that is part of the HTTP [RFC3986]. The "Link:" text is omitted as that is part of the HTTP
Link Header. As in [RFC5988], multiple link descriptions are Link Header. As in [RFC5988], multiple link descriptions are
separated by commas. Note that commas can also occur in quoted separated by commas. Note that commas can also occur in quoted
strings and URIs but do not end a description. The CoRE link format strings and URIs but do not end a description. The CoRE link format
MUST use UTF-8 encoding, which SHOULD be in NFC (Unicode MUST use UTF-8 encoding [RFC3629], which SHOULD be in NFC (Unicode
Normalization Form C). See Section 3 of [RFC5198], which explains Normalization Form C) as per Section 3 of [RFC5198].
why it useful to represent Unicode in a single unique form.
2.1. Target and context URIs 2.1. Target and context URIs
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]) conveyed in the CoRE Link Format is by default built from [RFC3986]) conveyed in the CoRE Link Format is by default built from
the scheme and authority parts of the target URI. In the absence of the scheme and authority parts of the target URI. In the absence of
this information in the target URI, the context URI is built from the this information in the target URI, the context URI is built from the
scheme and authority that was used for referencing the resource scheme and authority that was used for referencing the resource
returning the set of links, replacing the path with an empty path. returning the set of links, replacing the path with an empty path.
skipping to change at page 7, line 41 skipping to change at page 7, line 40
the target URI to the URI that was requested. In comparison, the the target URI to the URI that was requested. In comparison, the
CoRE link format includes one or more links, each describing a CoRE link format includes one or more links, each describing a
resource hosted by a server by default. Other relations can be resource hosted by a server by default. Other relations can be
expressed by using the anchor parameter. See Section 5 of [RFC3986] expressed by using the anchor parameter. See Section 5 of [RFC3986]
for a description of how URIs are constructed from URI references. for a description of how URIs are constructed from URI references.
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.3). parameter the new relation type "hosts" is assumed (see Section 7.2).
The "hosts" relation type indicates that the target URI is a resource The "hosts" relation type indicates that the target URI is a resource
hosted by the server given by the base URI, or, if present, the hosted by the server given by the base URI, or, if present, the
anchor parameter. anchor parameter.
To express other relations a links can make use of any registered To express other relations a links can make use of any registered
relation parameter or target attributes by including the relation relation parameter or target attributes by including the relation
parameter. The context of a relation can be defined using the anchor parameter. The context of a relation can be defined using the anchor
parameter. In this way, relations between resources hosted on a parameter. In this way, relations between resources hosted on a
server, or between hosted resources and external resources can be server, or between hosted resources and external resources can be
expressed. expressed.
skipping to change at page 8, line 16 skipping to change at page 8, line 16
As per Section 5.2 of [RFC5988] a link description MAY include an As per Section 5.2 of [RFC5988] a link description MAY include an
"anchor" attribute, in which case the context is the URI included in "anchor" attribute, in which case the context is the URI included in
that attribute. This is used to describe a relationship between two that attribute. This is used to describe a relationship between two
resources. A consuming implementation can however choose to ignore resources. A consuming implementation can however choose to ignore
such links. It is not expected that all implementations will be able such links. It is not expected that all implementations will be able
to derive useful information from explicitly anchored links. to derive useful information from explicitly anchored links.
3. CoRE link extensions 3. CoRE link extensions
The following CoRE specific target attributes are defined. These The following CoRE specific target attributes are defined in addition
attributes describe information useful in accessing the target link to the ABNF rules in Section 5 of [RFC5988]. These attributes
of the relation, and in some cases may be URIs. These URIs MUST be describe information useful in accessing the target link of the
treated as indicators, and are not meant to be actually retrieved relation, and in some cases may be URIs. These URIs MUST be treated
like a URL. When attributes are compared, they MUST be compared as as non resolvable identifiers (they are not meant to be retrieved).
strings. Relationships to resources that are meant to be retrieved When attributes are compared, they MUST be compared as strings.
should be expressed as separate links using the anchor attribute and Relationships to resources that are meant to be retrieved should be
the appropriate relation type. expressed as separate links using the anchor attribute and the
appropriate relation type.
; Import base format from Section 5 of RFC5988
link-extension = ( "rt" "=" quoted-string ) link-extension = ( "rt" "=" quoted-string )
link-extension = ( "if" "=" quoted-string ) link-extension = ( "if" "=" quoted-string )
link-extension = ( "ct" "=" integer ) link-extension = ( "ct" "=" integer ) ; Range of 0-65535
link-extension = ( "sz" "=" integer ) link-extension = ( "sz" "=" integer )
integer = 1*DIGIT integer = 1*DIGIT
3.1. Resource type 'rt' attribute 3.1. Resource type 'rt' attribute
The resource type "rt" attribute is used to assign a semantically The resource type "rt" attribute is an opaque string used to assign a
important type to a resource. One can think of this as a noun semantically important type to a resource. One can think of this as
describing the resource. In the case of a temperature resource this a noun describing the resource. In the case of a temperature
could be an application-specific semantic type like resource this could be e.g. an application-specific semantic type
"OutdoorTemperature", a Universal Resource Name (URN) like like "OutdoorTemperature", a Universal Resource Name (URN) like
"urn:temperature:outdoor" or a URI referencing a specific concept in "urn:temperature:outdoor" or a URI referencing a specific concept in
an ontology like an ontology like
"http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple
resource type attributes MAY appear in a link. resource type attributes MAY appear in a link.
The resource type attribute is not meant to used to assign a human The resource type attribute is not meant to used to assign a human
readable name to a resource. The "title" attribute defined in readable name to a resource. The "title" attribute defined in
[RFC5988] is meant for that purpose. [RFC5988] is meant for that purpose.
3.2. Interface description 'if' attribute 3.2. Interface description 'if' attribute
The interface description "if" attribute is used to provide a name, The interface description "if" attribute is an opaque string used to
URI or URN indicating a specific interface definition used to provide a name, URI or URN indicating a specific interface definition
interact with the target resource. One can think of this as used to interact with the target resource. One can think of this as
describing verbs usable on a resource. The interface description describing verbs usable on a resource. The interface description
attribute is meant to describe the generic REST interface to interact attribute is meant to describe the generic REST interface to interact
with a resource or a set of resources. It is expected that an with a resource or a set of resources. It is expected that an
interface description will be re-used by different resource types. interface description will be re-used by different resource types.
For example the resource types "OutdoorTemperature", "DewPoint" and For example the resource types "OutdoorTemperature", "DewPoint" and
"RelHumidity" could all be accessible using the interface description "RelHumidity" could all be accessible using the interface description
"http://www.example.org/myapp.wadl#sensor". "http://www.example.org/myapp.wadl#sensor".
The interface description could be for example the URI of a Web The interface description could be for example the URI of a Web
Application Description Language (WADL) definition of the target Application Description Language (WADL) [wadl] definition of the
resource "http://www.example.org/myapp.wadl#sensor", a URN indicating target resource "http://www.example.org/myapp.wadl#sensor", a URN
the type of interface to the resource "urn:myapp:sensor", or an indicating the type of interface to the resource "urn:myapp:sensor",
application-specific name "Sensor". Multiple interface description or an application-specific name "Sensor". Multiple interface
attributes MAY appear in a link. description attributes MAY appear in a link.
3.3. Content-type code 'ct' attribute 3.3. Content-type code 'ct' attribute
The Content-type code "ct" attribute provides a hint about the The Content-type code "ct" attribute provides a hint about the
Internet media type this resource returns. Note that this is only a Internet media type this resource returns. Note that this is only a
hint, and does not override the Content-type Option of a CoAP hint, and does not override the Content-type Option of a CoAP
response obtained by actually following the link. The value is in response obtained by actually following the link. The value is in
the CoAP identifier code format as a decimal ASCII integer the CoAP identifier code format as a decimal ASCII integer
[I-D.ietf-core-coap]. For example application/xml would be indicated [I-D.ietf-core-coap] and MUST be in the range of 0-65535 (16-bit
as "ct=41". If no Content-type code attribute is present then unsigned integer). For example application/xml would be indicated as
nothing about the type can be assumed. The Content-type code "ct=41". If no Content-type code attribute is present then nothing
attribute MUST NOT appear more than once in a link. about the type can be assumed. The Content-type code attribute MUST
NOT appear more than once in a link.
Alternatively, the "type" attribute MAY be used to indicate an Alternatively, the "type" attribute MAY be used to indicate an
Internet media type as a quoted-string [RFC5988]. It is not however Internet media type as a quoted-string [RFC5988]. It is not however
expected that constrained implementations are able to parse quoted- expected that constrained implementations are able to parse quoted-
string Content-type values. A link MAY include either a ct attribute string Content-type values. A link MAY include either a ct attribute
or a type attribute, but MUST NOT include both. or a type attribute, but MUST NOT include both.
3.4. Maximum size estimate 'sz' attribute 3.4. Maximum size estimate 'sz' attribute
The maximum size estimate attribute "sz" gives an indication of the The maximum size estimate attribute "sz" gives an indication of the
maximum size of the resource indicated by the target URI. This maximum size of the resource indicated by the target URI. This
attribute is not expected to be included for small resources that can attribute is not expected to be included for small resources that can
comfortably by carried in a single Maxiumum Transmission Unit (MTU), comfortably by carried in a single Maxiumum Transmission Unit (MTU),
but SHOULD be included for resources larger than that. The maximum but SHOULD be included for resources larger than that. The maximum
size estimate attribute MUST NOT appear more than once in a link. size estimate attribute MUST NOT appear more than once in a link.
Note that there is no defined upper limit to the value of the sz
attributes. Implementations MUST be prepared to accept large values.
One implementation strategy is to convert any value larger than a
reasonable size limit for this implementation to a special value
"Big", which in further processing would indicate that a size value
was given that was so big that it cannot be processed by this
implementation.
4. Well-known Interface 4. Well-known Interface
Resource discovery in CoRE is accomplished through the use of a well- Resource discovery in CoRE is accomplished through the use of a well-
known resource URI which returns a list of links about resources known resource URI which returns a list of links about resources
hosted by that server and other link relations. Well-known resources hosted by that server and other link relations. Well-known resources
have a path component that begins with "/.well-known/" as specified have a path component that begins with "/.well-known/" as specified
in [RFC5785]. This document defines a new well-known resource for in [RFC5785]. This document defines a new well-known resource for
CoRE Resource Discovery "/.well-known/core". CoRE Resource Discovery "/.well-known/core".
A server implementing this specification MUST support this resource A server implementing this specification MUST support this resource
skipping to change at page 11, line 22 skipping to change at page 11, line 32
the link attribute they name. Filtering is performed by comparing the link attribute they name. Filtering is performed by comparing
the query-pattern against the value of the attribute identified by the query-pattern against the value of the attribute identified by
the resource-param for each link-value in the collection of resources the resource-param for each link-value in the collection of resources
identified by the URI path. identified by the URI path.
If the decoded query-pattern does not end with "*", a link value 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 matches the query only if the value of the attribute or URI-reference
denoted by the resource-param is bytewise identical to the query- denoted by the resource-param is bytewise identical to the query-
pattern. If the decoded query-pattern ends with "*", it is pattern. If the decoded query-pattern ends with "*", it is
sufficient that the remainder of the query-pattern be a prefix of the 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 value denoted by the resource-param. A query-pattern of "*" will
constrained nodes support filtering. Implementations not supporting match that resource-param with an empty string value. It is not
filtering MUST simply ignore the query string and return the whole expected that very constrained nodes support filtering.
resource for unicast requests. Implementations not supporting filtering MUST simply ignore the query
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 is Protocol (CoAP) that supports multicast requests, special care is
taken. A multicast request with a query string MUST not be responded taken. A multicast request with a query string MUST not be responded
to if filtering is not supported (to avoid a needless response to if filtering is not supported (to avoid a needless response
storm). storm).
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.
skipping to change at page 12, line 4 skipping to change at page 12, line 13
the example for readability. the example for readability.
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.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 200 OK RES: 200 OK
</sensors/temp>;ct=41;rt="TemperatureC";if="sensor", </sensors/temp>;ct=41;rt="TemperatureC";if="sensor",
</sensors/light>;ct=41;rt="LightLux";if="sensor" </sensors/light>;ct=41;rt="LightLux";if="sensor"
Without the linefeeds included for readability, the format actually
looks as follows.
</sensors/temp>;ct=41;rt="TemperatureC";if="sensor",</sensors/light>;
ct=41;rt="LightLux";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
RES: 200 OK RES: 200 OK
</sensors>;rt="index";ct=40 </sensors>;rt="index";ct=40
REQ: GET /sensors REQ: GET /sensors
skipping to change at page 13, line 5 skipping to change at page 13, line 25
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: 200 OK RES: 200 OK
<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
attribute. The consumer of this link would use the sz attribute to
determine if the resource representation is too large and if block
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
the sz attibute. Thus a special flag or value should be used to
indicate "Big" (larger than 64 KiB).
REQ: GET /.well-known/core?rt=firmware
RES: 200 OK
</firmware/v2.1>;rt="firmware";sz=262144
6. Security Considerations 6. Security Considerations
This document needs the same security considerations as described in This document needs the same security considerations as described in
Section 7 of [RFC5988]. The /.well-known/core resource may be 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.
Multicast requests using CoAP for the well-known link-format Multicast requests using CoAP for the well-known link-format
resources could be used to perform denial of service on a constrained resources could be used to perform denial of service on a constrained
network. A multicast request SHOULD only be accepted if the request network. A multicast request SHOULD only be accepted if the request
is sufficiently authenticated and secured. is sufficiently authenticated and secured using e.g. IPsec or an
appropriate object security mechanism.
CoRE link format parsers should be aware that a link description may CoRE link format parsers should be aware that a link description may
be cyclical, i.e., contain a link to itself. These cyclical links be cyclical, i.e., contain a link to itself. These cyclical links
could be direct or indirect (i.e., through referenced link could be direct or indirect (i.e., through referenced link
resources). Care should be taken when parsing link descriptions and resources). Care should be taken when parsing link descriptions and
accessing cyclical links. accessing cyclical links.
7. IANA Considerations 7. IANA Considerations
7.1. Attribute Registry 7.1. Well-known 'core' URI
This document defines a registry for the link extension attributes
defined for use with the CoRE Link Format. The name of the registry
is "CoRE Link Format Attributes".
Each entry in the registry must include the attribute name, the
attribute, the format of the attribute and a reference to the
attribute's documentation.
Initial entries in this registry are as follows:
+-----------------------+-----------+---------------+-----------+
| Name | Attribute | Type | Reference |
+-----------------------+-----------+---------------+-----------+
| Resource Type | rt | Quoted String | &SELF; |
| Interface Description | if | Quoted String | &SELF; |
| Content-Type | ct | Integer | &SELF; |
| Maximum Size Estimate | sz | Integer | &SELF; |
+-----------------------+-----------+---------------+-----------+
Table 1: CoAP Option Numbers
New attributes defined for the CoRE Link Format MUST NOT collide with
existing attributes defined in [RFC5988].
The IANA policy for future additions to this registry is "IETF
Review" as described in [RFC5226].
The documentation of an attribute should specify the semantics of the
attribute, including the following properties:
o The meaning of the attribute.
o The format of the attribute's value.
o Whether the attribute can occur multiple times.
o The default value, if any.
7.2. Well-known 'core' URI
This memo registers the "core" well-known URI in the Well-Known URI This memo registers the "core" well-known URI in the Well-Known URI
Registry as defined by [RFC5785]. Registry as defined by [RFC5785].
URI suffix: core URI suffix: core
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
Related information: None Related information: None
7.3. New 'hosts' relation type 7.2. New 'hosts' relation type
This memo registers the new "hosts" Web Linking relation type as per This memo registers the new "hosts" Web Linking relation type as per
[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, and by default the context /.well-known/core resource representation, and by default the context
of the links is the server at coap://authority from which /.well- of the links is the server at coap://authority from which /.well-
known/core was requested. known/core was requested.
Application Data: None Application Data: None
7.4. 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
Subtype name: link-format Subtype name: link-format
Required parameters: None Required parameters: None
Optional parameters: The query string may contain uri= to match the Optional parameters: None
URI, or any other attribute defined for the link format to match that
attribute as defined in this document.
Encoding considerations: UTF-8 (NFC) Encoding considerations: 8bit (UTF-8 (NFC))
Security considerations: None Security considerations:
Multicast requests using CoAP for the well-known link-format
resources 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 using e.g. IPsec or an
appropriate object security mechanism.
CoRE link format parsers should be aware that a link description may
be cyclical, i.e., contain a link to itself. These cyclical links
could be direct or indirect (i.e., through referenced link
resources). Care should be taken when parsing link descriptions and
accessing cyclical links.
Interoperability considerations: Interoperability considerations:
Published specification: [[ this document ]] Published specification: [[ this document ]]
Applications that use this media type: CoAP server and client Applications that use this media type: CoAP server and client
implementations for resource discovery and HTTP applications that use implementations for resource discovery and HTTP applications that use
the link-format as a payload. the link-format as a payload.
Additional information: Additional information:
Magic number(s): Magic number(s):
File extension(s): File extension(s): *.wlnk
Macintosh file type code(s): Macintosh file type code(s):
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: None Restrictions on usage: None
Author: CoRE WG Author: CoRE WG
Change controller: IETF Change controller: IETF
7.4. New CoAP Media Type registry entry
This specification requests a value for application/link-format in
the CoAP Media Type Registry defined in [I-D.ietf-core-coap]. The
value "40" is requested as it has been in use by all existing
implementations of this specification.
8. Acknowledgments 8. Acknowledgments
Special thanks to Peter Bigot, who has made a considerable number Special thanks to Peter Bigot, who has made a considerable number
reviews and text contributions that greatly improved the document. reviews and text contributions that greatly improved the document.
In particular, Peter is responsible for the ABNF descriptions and the In particular, Peter is responsible for the ABNF descriptions and the
idea for a new "hosts" relation type. idea for a new "hosts" relation type.
Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions
and ideas that led to this draft, and to Carsten Bormann, Martin and ideas that led to this draft, and to Carsten Bormann, Martin
Thomson and Peter Saint-Andre for extensive comments and Thomson, Alexey Melnikov and Peter Saint-Andre for extensive comments
contributions that improved the text. and contributions that improved the text.
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-03 to ietf-04:
o Removed the attribute registry (#145).
o Requested a CoAP media type for application/link-format (#144).
o Editorial and reference improvements from AD review (#146).
o Added a range limitation for ct attribute.
o Added security considerations and file extension for
application/link-format registration.
Changes from ietf-02 to ietf-03: Changes from ietf-02 to ietf-03:
o Removed 'obs' attribute definition, now defined in the CoAP o Removed 'obs' attribute definition, now defined in the CoAP
Observation spec (#99). Observation spec (#99).
o Changed Resource name (n=) to Resource type (rt=) and d= to if= o Changed Resource name (n=) to Resource type (rt=) and d= to if=
(#121). (#121).
o Hierarchical organization of links under /.well-known/core o Hierarchical organization of links under /.well-known/core
removed (#95). removed (#95).
skipping to change at page 18, line 4 skipping to change at page 18, line 24
o Clarified that filtering is optional, and the query string is to o Clarified that filtering is optional, and the query string is to
be ignored if not supported (and the URL path processed as be ignored if not supported (and the URL path processed as
normally). normally).
o Required support of wildcard * processing if filtering is o Required support of wildcard * processing if filtering is
supported. supported.
o Removed the aussumption of a default content-type assumption. o Removed the aussumption of a default content-type assumption.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-04 (work in progress), January 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
10.2. Informative References 10.2. Informative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-04 (work in progress), January 2011.
[REST] Fielding, "Architectural Styles and the Design of Network- [REST] Fielding, "Architectural Styles and the Design of Network-
based Software Architectures", , 2000, <http:// based Software Architectures", , 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>. www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>.
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, November 1987.
[RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
Syndication Format", RFC 4287, December 2005. Syndication Format", RFC 4287, December 2005.
[RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
"Transmission of IPv6 Packets over IEEE 802.15.4 "Transmission of IPv6 Packets over IEEE 802.15.4
Networks", RFC 4944, September 2007. Networks", RFC 4944, September 2007.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, March 2008. Interchange", RFC 5198, March 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785, Uniform Resource Identifiers (URIs)", RFC 5785,
April 2010. April 2010.
[wadl] Hadley, M., "Web Application Description Language (WADL)",
2009, <http://java.net/projects/wadl/sources/svn/content/
trunk/www/wadl20090202.pdf>.
Author's Address Author's Address
Zach Shelby Zach Shelby
Sensinode Sensinode
Kidekuja 2 Kidekuja 2
Vuokatti 88600 Vuokatti 88600
FINLAND FINLAND
Phone: +358407796297 Phone: +358407796297
Email: zach@sensinode.com Email: zach@sensinode.com
 End of changes. 40 change blocks. 
118 lines changed or deleted 154 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/