draft-ietf-core-link-format-01.txt   draft-ietf-core-link-format-02.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft Sensinode Internet-Draft Sensinode
Intended status: Standards Track October 25, 2010 Intended status: Standards Track December 10, 2010
Expires: April 28, 2011 Expires: June 13, 2011
CoRE Link Format CoRE Link Format
draft-ietf-core-link-format-01 draft-ietf-core-link-format-02
Abstract Abstract
This document defines a link format for use by constrained CoAP web This document defines Web Linking using a link format for use by
servers to describe URIs of resources offered along with other constrained web servers to describe hosted resources, their
attributes. Based on the HTTP Link Header format, the CoRE link attributes and other relationships between links. Based on the HTTP
format is carried as a payload and is assigned an Internet media Link Header format defined in RFC5988, the CoRE Link Format is
type. A well-known URI is defined as a default entry-point for carried as a payload and is assigned an Internet media type. A well-
requesting the list of links to resources hosted by a server. known URI is defined as a default entry-point for requesting the
links hosted by a server.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 April 28, 2011. This Internet-Draft will expire on June 13, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Target and context URIs . . . . . . . . . . . . . . . . . 4 2.1. Web Linking in CoRE . . . . . . . . . . . . . . . . . . . 4
2.2. Link relation 'rel' usage . . . . . . . . . . . . . . . . 5 2.1.1. Target and context URIs . . . . . . . . . . . . . . . 4
2.3. Description 'd' usage . . . . . . . . . . . . . . . . . . 5 2.1.2. Link relations . . . . . . . . . . . . . . . . . . . . 5
2.4. Alternative URI 'sh' usage . . . . . . . . . . . . . . . . 5 2.1.3. Use of anchors . . . . . . . . . . . . . . . . . . . . 5
2.5. Resource name 'n' usage . . . . . . . . . . . . . . . . . 5 2.2. CoRE link extensions . . . . . . . . . . . . . . . . . . . 5
2.6. Content-type code 'ct' usage . . . . . . . . . . . . . . . 5 2.2.1. Resource name 'n' attribute . . . . . . . . . . . . . 6
2.7. Resource identifier 'id' usage . . . . . . . . . . . . . . 6 2.2.2. Interface description 'd' attribute . . . . . . . . . 6
2.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.3. Content-type code 'ct' attribute . . . . . . . . . . . 6
3. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 6 2.2.4. Maximum size estimate 'sz' attribute . . . . . . . . . 6
3.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 7 2.2.5. Observable 'obs' attribute . . . . . . . . . . . . . . 7
4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 3. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 3.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 8
5.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 9 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.2. New link-format Internet media type . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 6.3. New link-format Internet media type . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . . 11 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.1. Normative References . . . . . . . . . . . . . . . . . . . 14
9.2. Informative References . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
The Constrained RESTful Environments (CoRE) working group aims at The Constrained RESTful Environments (CoRE) working group aims at
realizing the REST architecture in a suitable form for the most realizing the REST architecture in a suitable form for the most
constrained nodes (e.g. 8-bit microcontrollers with limited RAM and constrained nodes (e.g. 8-bit microcontrollers with limited RAM and
ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to- ROM) and networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-
machine (M2M) applications such as smart energy and building machine (M2M) applications such as smart energy and building
automation [I-D.shelby-core-coap-req]. automation.
The discovery of resources offered 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 Web Server is typically discovery of resources provided by an HTTP Web Server is typically
called Web Discovery. In this document we refer to the discovery of called Web Discovery and the description of relations between
resources offered by a CoAP server as resource discovery. resources is called Web Linking [RFC5988]. In this document we refer
to the discovery of resources hosted by a constrained web server,
The core function of such a discovery mechanism is to provide URIs their attributes and other resource relations as CoRE Resource
("links") for the resources offered, complemented by information Discovery.
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 The main function of such a discovery mechanism is to provide URIs
discovery by extending the HTTP Link Header Format (called links) for the resources hosted by the server, complemented
[I-D.nottingham-http-link-header] to describe resources hosted by a by attributes about those resources and possible further link
constrained server. The CoRE link-format is carried as a payload and relations. In CoRE this collection of links is carried as a resource
is assigned an Internet media type. A well-known URI "/.well-known/ of its own (as opposed to as HTTP headers delivered with a specific
core" is defined as a default entry-point for requesting the list of resource). This document specifies a link format for use in CoRE
links to resources hosted by a server. Resource Discovery by extending the HTTP Link Header Format [RFC5988]
to describe these link descriptions. 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 about resources hosted by a server, and
thus performing CoRE Resource Discovery.
2. Link Format 2. Link Format
CoRE resource discovery extends the HTTP Link Header format specified The CoRE Link Format extends the HTTP Link Header format specified in
in [I-D.nottingham-http-link-header] which is specified in Augmented [RFC5988], which is specified in Augmented Backus-Naur Form (ABNF)
Backus-Naur Form (ABNF) notation [RFC2616]. The format does not notation. The format does not require special XML or binary parsing,
require special XML or binary parsing, and is extensible. is fairly compact, and is extensible - all important characteristics
for CoRE. It should be noted that this link format is just one
serialization of typed links defined in [RFC5988], others include
Atom or HTTP links. It is expected that resources discovered in the
CoRE Link Format may also be made available in alternative formats on
the greater Internet.
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
header. This specification thus defines a Internet media type for
the CoRE Link Format (see Section 6.3).
The CoRE link format uses the ABNF description and associated rules
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
Link Header. As in [RFC5988], multiple link descriptions are
separated by commas. Note that commas can also occur in quoted
strings and URIs but do not end a description. The CoRE link format
MUST use UTF-8 encoding, which SHOULD be in NFC (Unicode
Normalization Form C). See Section 3 of [RFC5198], which explains
why it useful to represent Unicode in a single unique form.
2.1. Web Linking in CoRE
This link format is used for a similar purpose to that described in This link format is used for a similar purpose to that described in
[I-D.nottingham-http-link-header], to describe one or more [RFC5988], to describe relationships between resources via typed
relationships between resources. However in this specification the links, so-called "Web Linking". However in this specification Web
link format is extended with specific constrained M2M link Linking is extended with specific constrained M2M attributes, links
parameters, links are carried as a payload rather than in a message are carried as a message payload rather than in an HTTP Link Header,
header, and a default interface is defined to discover resources and a default interface is defined to discover resources hosted by a
described by these links. server. This specification defines a new relation type "hosts",
which indicates that the resource is hosted by the server from which
the link document was requested.
[I-D.nottingham-http-link-header] did not require an Internet media 2.1.1. Target and context URIs
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 Each link conveys one target URI as a URI-reference inside angle
in Section 5 of [I-D.nottingham-http-link-header]. In addition, the brackets ("<>"). The context URI of a link (also called base URI in
URI, URI-reference and pchar rules are taken from [RFC3986]. The [RFC3986]) conveyed in the CoRE Link Format is by default built from
"Link:" text is omitted as that is part of the HTTP Link Header. the scheme and authority parts of the target URI. In the absence of
Multiple link descriptions are separated by commas. The CoRE link this information in the target URI, the context URI is built from the
format MUST use the US-ASCII character set (support for RFC2231 scheme and authority that was used for referencing the resource
encoding of non-ASCII content TBD). The following CoRE specific returning the set of links, replacing the path with an empty path.
link-extension parameters to the format are defined: Thus by default links can be thought of as describing a target
resource hosted by the server. Other relations can be expressed by
including an anchor parameter (which defines the context URI) along
with an explicit relation parameter. 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 URI). 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 links, each describing a
resource hosted by a server by default. Other relations can be
expressed by using the anchor parameter. See Section 5 of [RFC3986]
for a description of how URIs are constructed from URI references.
link-extension = ( "d" "=" <"> URI-reference <">) 2.1.2. Link relations
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 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
parameter the new relation type "hosts" is assumed (see Section 6.2).
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
anchor parameter.
Each link description conveys one target URI as a URI-reference To express other relations a links can make use of any registered
inside angle brackets ("<>"). The context URI of a link (also called relation parameter or target attributes by including the relation
base URI in [RFC3986]) conveyed in the description is by default the parameter. The context of a relation can be defined using the anchor
URI of the resource that returned the link-format representation. parameter. In this way, relations between resources hosted on a
Thus each link can be thought of as describing a target resource server, or between hosted resources and external resources can be
hosted by the server in the absence of further relation information. expressed.
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 2.1.3. Use of anchors
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.
2.2. Link relation 'rel' usage 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
that attribute. This is used to describe a relationship between two
resources. A consuming implementation can however choose to ignore
such links. It is not expected that all implementations will be able
to derive useful information from explicitly anchored links.
Link descriptions in CoRE are typically used to describe entry points 2.2. CoRE link extensions
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
attribute.
2.3. Description 'd' usage The following CoRE specific target attributes are defined. These
attributes describe information useful in accessing the target link
of the relation, and in some cases may be URIs. These URIs MUST be
treated as indicators, and are not meant to be actually retrieved
like a URL. When attributes are compared, they MUST be compared as
strings. Relationships to resources that are meant to be retrieved
should be expressed as separate links using the anchor attribute and
the appropriate relation type.
The description "d" attribute can provide a URI to a specific link-extension = ( "n" "=" quoted-string )
interface definition used to access the target resource. This could link-extension = ( "d" "=" <"> URI-reference <">)
be for example a URI to the WADL definition of the target resource. link-extension = ( "ct" "=" integer )
Multiple description attributes MAY appear in a link description. link-extension = ( "sz" "=" integer )
link-extension = ( "obs" )
integer = 1*DIGIT
2.4. Alternative URI 'sh' usage 2.2.1. Resource name 'n' attribute
This attribute can be included to define an alternative short URI The resource name "n" attribute is used to assign a semantically
which can also be used to access the target resource. Multiple important name to a resource. In the case of a temperature sensor
alternative short URI attributes MAY appear in a link description. resource this could be an application-specific semantic name like
"TemperatureC", a URN like "urn:temperature:centigrade" or a URI
referencing a specific concept in an ontology like
"http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature". Multiple name
attributes MAY appear in a link.
2.5. Resource name 'n' usage The name attribute is not meant to used to assign a human readable
name to a resource. The "title" attribute defined in [RFC5988] is
meant for that purpose.
The resource name "n" attribute is used to assign either a human 2.2.2. Interface description 'd' attribute
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
"http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature" 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 interface description "d" attribute is used to provide a URI or
URN indicating a specific interface definition used to interact with
the target resource. This could be for example the URI of a WADL
definition of the target resource
"http://www.example.org/sensor.wadl", or a URN indicating the type of
interface to the resource "urn:sensor". Multiple description
attributes MAY appear in a link.
2.2.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. The value is in the CoAP Internet media type this resource returns. Note that this is only a
identifier code format as a decimal ASCII integer hint, and does not override the Content-type Option of a CoAP
response obtained by actually following the link. 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 [I-D.ietf-core-coap]. For example application/xml would be indicated
as "ct=41". If no Content-type code attribute is present then as "ct=41". If no Content-type code attribute is present then
nothing about the type can be assumed. The Content-type code nothing about the type can be assumed. The Content-type code
attribute MUST NOT appear more than once in a link description. 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. It is not however expected Internet media type as a quoted-string [RFC5988]. It is not however
that constrained implementations are able to parse quoted-string expected that constrained implementations are able to parse quoted-
Content-type values. string Content-type values. A link MAY include either a ct attribute
or a type attribute, but MUST NOT include both.
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",
</sensors/temp>;sh="/t";n="TemperatureC",
</sensors/light>;sh="/l";ct=41;n="LightLux"
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 2.2.4. Maximum size estimate 'sz' attribute
</.well-known/core/sensors>;rel="section" The maximum size estimate attribute "sz" gives an indication of the
;type="application/link-format" maximum size of the link indicated by the target URI. This attribute
is not expected to be included for small resources that can
comfortably by carried in a single MTU, but SHOULD be included for
resources larger than that. The maximum size estimate attribute MUST
NOT appear more than once in a link.
GET /.well-known/core/sensors 2.2.5. Observable 'obs' attribute
</sensors/temp>;sh="/t";n="TemperatureC", The observable attribute "obs" is used to indicate that this resource
</sensors/light>;sh="/l";ct=41;n="LightLux" supports the observation feature defined in [I-D.ietf-core-observe].
This attribute is used as a flag, and thus it has no value component.
The observable attribute MUST NOT appear more than once in a link.
3. Well-known Interface 3. 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 (resource known resource URI which returns a list of links about resources
descriptions) offered by that constrained server. Well-known hosted by that server and other link relations. Well-known resources
resources have a path component that begins with "/.well-known/" as have a path component that begins with "/.well-known/" as specified
specified in [RFC5785]. This document defines a new well-known path in [RFC5785]. This document defines a new well-known resource for
prefix for CoRE discovery "/.well-known/core" [Section 5.1]. A CoRE Resource Discovery "/.well-known/core". A server implementing
server implementing this specification MUST support this path prefix this specification MUST support this resource on the default port
on the default port appropriate for the protocol for the purpose of appropriate for the protocol for the purpose of resource discovery.
resource discovery. It is however up to the application which link It is however up to the application which links are included and how
descriptions are included and how they are organized. In the absense they are organized. In the absence of any links, a zero-length
of any links, a zero-length payload is returned. The resource payload is returned. The resource representation of this resource
representation of this resource is described in Section 2. uses the CoRE Link Format described in Section 2. URIs under the
path /.well-known/core are reserved by this specification for use by
servers in organizing links into multiple resources, each with their
own URI.
The CoRE resource discovery interface supports the following The CoRE resource discovery interface supports the following
interactions: interactions:
o Performing a GET on /.well-known/core to the default port returns 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). a set of links available from the CoAP server (if any) in the CoRE
Link Format. These links might describe resources hosted on that
server, on other servers, or express other kinds of link relations
as described in Section 2.
o Filtering may be performed on any of the link format attributes o Filtering may be performed on any of the link format attributes
using a query string as specified in Section 3.1. For example using a query string as specified in Section 3.1. For example
[GET /.well-known/core?n=TemperatureC] would request resources [GET /.well-known/core?n=TemperatureC] would request resources
with the name TemperatureC. A server is not however required to with the name TemperatureC. A server is not however required to
support filtering. support filtering.
o More capable servers such as proxies could support a resource o More capable servers such as proxies could support a resource
directory by requesting the resource descriptions of other end- directory by requesting the resource descriptions of other end-
points or accepting [POST /.well-known/core messages] from other points or allowing servers to POST requests to /.well-known/core.
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 The details of such resource directory functionality is however
out of scope for this document. out of scope for this document, and is expected to be specified
separately.
End-points with a large number of resources SHOULD include resource End-points with a large number of resources SHOULD include resource
descriptions only for important services or collections and organize descriptions only for important links and MAY organize their resource
their resource descriptions into a hierarchy of link resources. This descriptions into a hierarchy of link resources. This is done by
is done by including links in the /.well-known/core list which point including links in the /.well-known/core list which point to other
to other resource lists, e.g. </.well-known/core/sensors>. Such a resource lists using the "section" relation type, e.g. </.well-known/
hierarchy SHOULD be under the /.well-known/core path but could be core/sensors>. Such a hierarchy MUST be under the /.well-known/core
located elsewhere. path.
3.1. Query Filtering 3.1. Query Filtering
A server implementing this document MAY recognize the query part of a A server implementing this document MAY recognize the query part of a
resource-discovery URI as a filter on the resources to be returned. resource-discovery URI as a filter on the resources to be returned.
The query part should conform to the following syntax: The query part should conform to the following syntax. Note that
this only defines querying for a single parameter at a time.
filter-query = resource-param "=" query-pattern filter-query = resource-param "=" query-pattern
resource-param = "uri" | "d" | "sh" | "n" | "id" resource-param = "uri" | parmname
query-pattern = 1*pchar [ "*" ] query-pattern = 1*pchar [ "*" ]
The resource-param "uri" refers to the URI-reference between the "<" The resource-param "uri" refers to the URI-reference between the "<"
and ">" characters of a link-value. Other resource-param values and ">" characters of a link. Other resource-param values refer to
refer to the link attribute they name. (TBD: Do we want to add the the link attribute they name. Filtering is performed by comparing
resource description attributes that I excluded, or the standard the query-pattern against the value of the attribute identified by
link-param attributes from I-D.nottingham-http-link-header?) the resource-param for each link-value in the collection of resources
Filtering is performed by comparing the query-pattern against the identified by the URI path.
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 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. value denoted by the resource-param.
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. An exact string and return the whole resource for unicast requests. An
match is performed on the query string, and a 200 OK response is implementation supporting filtering MUST return only those entries
returned with link descriptions that contains the matching entries for which the value of the link attribute identified by the resource-
(if any). In contrast, a multicast request with a query string MUST param contains the query-pattern as a substring. If resource
not be responded to if filtering is not supported (to avoid a descriptions are organized hierarchically, a query on the root
needless response storm). If resource descriptions are organized resource /.well-known/core MUST return all matching resource
hierarchically, a query on the root resource /.well-known/core SHOULD descriptions from the entire hierarchy.
return all matching resource descriptions from the entire hierarchy.
An example query on the link descriptions from Section 2 may look
like:
GET /.well-known/core?n=LightLux When using a transfer protocol like CoAP that supports multicast
requests, special care is taken. A multicast request with a query
string MUST not be responded to if filtering is not supported (to
avoid a needless response storm).
</sensors/light>;sh="/l";ct=41;n="LightLux" 4. Examples
4. Security Considerations A few examples of typical link descriptions in this format follows.
Multiple resource descriptions in a representation are separated by
commas. Linefeeds never occur in the actual format, but are shown in
the example for readability.
This example includes links to two different sensors.
REQ: GET /.well-known/core
RES: 200 OK
</sensors/temp>;ct=41;n="TemperatureC",
</sensors/light>;ct=41;n="LightLux"
This example arranges link descriptions hierarchically, with the
entry point including a link to a sub-resource containing links about
the sensors.
REQ: GET /.well-known/core
RES: 200 OK
</.well-known/core/sensors>;rel="section";ct=40
REQ: GET /.well-known/core/sensors
RES: 200 OK
</sensors/temp>;n="TemperatureC",
</sensors/light>;ct=41;n="LightLux"
An example query filter may look like:
REQ: GET /.well-known/core?n=LightLux
RES: 200 OK
</sensors/light>;ct=41;n="LightLux"
This example shows the use of an anchor attribute to relate the
temperature sensor resource to an external description and to an
alternative URL.
REQ: GET /.well-known/core
RES: 200 OK
</sensors>;rel="index";n="Sensor Index",
</sensors/temp>;n="TemperatureC",
</sensors/light>;ct=41;n="LightLux",
<http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
;rel=describedby,
</t>;anchor="/sensors/temp";rel=alternate
If a client is interested to find relations about a particular
resource, it can perform a query on the anchor parameter:
REQ: GET /.well-known/core?anchor=/sensors/temp
RES: 200 OK
<http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
;rel=describedby,
</t>;anchor="/sensors/temp";rel=alternate
5. 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 [I-D.nottingham-http-link-header]. The /.well-known/ Section 7 of [RFC5988]. The /.well-known/core resource may be
core resource may be protected e.g. using DTLS when hosted on a CoAP protected e.g. using DTLS when hosted on a CoAP server as per
server as per [I-D.ietf-core-coap] Section 10.2. [I-D.ietf-core-coap] Section 10.2.
Great care must be taken when processing multicast requests using Multicast requests using CoAP for the well-known link-format
CoAP for the well-known link-format resources, as this could be used resources could be used to perform denial of service on a constrained
to perform denial of service on a constrained network. A multicast network. A multicast request SHOULD only be accepted if the request
request SHOULD only be accepted if the request is sufficiently is sufficiently authenticated and secured.
authenticated and secured.
5. IANA Considerations 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.
5.1. Well-known 'core' URI 6. IANA Considerations
6.1. 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
5.2. New link-format Internet media type 6.2. New 'hosts' relation type
This memo registers the new "hosts" Web Linking relation type as per
[RFC5988].
Relation Name: hosts
Description: Refers to a resource hosted by the server indicated by
the link context.
Reference: [[ this document ]]
Notes: This relation is used in CoRE where links are retrieved as a
/.well-known/core resource representation, and by default the context
of the links is the server at coap://authority from which /.well-
known/core was requested.
Application Data: None
6.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: The query string may contain uri= to match the
URI, or any other attribute defined for the link format to match that URI, or any other attribute defined for the link format to match that
attribute. attribute.
Encoding considerations: US-ASCII Encoding considerations: UTF-8 (NFC)
Security considerations: None Security considerations: None
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. implementations for resource discovery and HTTP applications that use
the link-format as a payload.
Additional information: Additional information:
Magic number(s): Magic number(s):
File extension(s): File extension(s):
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
6. Acknowledgments 7. Acknowledgments
Special thanks to Mark Nottingham and Eran Hammer-Lahav for Special thanks to Peter Bigot, who has made a considerable number
discussions and ideas that led to this draft, and to Carsten Bormann reviews and text contributions that greatly improved the document.
and Peter Bigot for extensive comments and contributions that In particular, Peter is responsible for the ABNF descriptions and the
improved the text. idea for a new "hosts" relation type.
Thanks to Mark Nottingham and Eran Hammer-Lahav for discussions and
ideas that led to this draft, and to Carsten Bormann and Martin
Thomson for extensive comments 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, Peter Bigot, Colin O'Flynn and Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn and David Ryan
David Ryan for helpful comments and discussions that have shaped the for helpful comments and discussions that have shaped the document.
document.
7. Changelog 8. Changelog
Changes from ietf-01 to ietf-02:
o Added references to RFC5988 (#41).
o Removed sh and id link-extensions (#42).
o Defined the use of UTF-8 (#84).
o Changed query filter definition for any parameter (#70).
o Added more example, now as a separate section (#43).
o Mentioned cyclical links in the security section (#57).
o Removed the sh and id attributes, added obs and sz attributes
(#42).
o Improved the context and relation description wrt RFC5988 and
requested a new "hosts" default relation type (#85).
Changes from ietf-00 to ietf-01: Changes from ietf-00 to ietf-01:
o Editorial changes to correct references. o Editorial changes to correct references.
o Formal definition for filter query string. o Formal definition for filter query string.
o Removed URI-reference option from "n" and "id". o Removed URI-reference option from "n" and "id".
o Added security text about multicast requests. o Added security text about multicast requests.
skipping to change at page 11, line 7 skipping to change at page 13, line 47
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.
8. References 9. References
9.1. Normative References
8.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Frank, B., and D. Sturek, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-02
(work in progress), September 2010.
[I-D.nottingham-http-link-header]
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 [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.
8.2. Informative References [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[I-D.shelby-core-coap-req] 9.2. Informative References
Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R.
Kelsey, "CoAP Requirements and Features", [I-D.ietf-core-coap]
draft-shelby-core-coap-req-02 (work in progress), Shelby, Z., Frank, B., and D. Sturek, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-03
(work in progress), October 2010.
[I-D.ietf-core-observe]
Hartke, K. and Z. Shelby, "Observing Resources in CoAP",
draft-ietf-core-observe-00 (work in progress),
October 2010. October 2010.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, March 2008.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785,
April 2010.
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. 60 change blocks. 
254 lines changed or deleted 383 lines changed or added

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