draft-ietf-core-link-format-12.txt   draft-ietf-core-link-format-13.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft Sensinode Internet-Draft Sensinode
Intended status: Standards Track May 18, 2012 Intended status: Standards Track May 23, 2012
Expires: November 19, 2012 Expires: November 24, 2012
CoRE Link Format CoRE Link Format
draft-ietf-core-link-format-12 draft-ietf-core-link-format-13
Abstract Abstract
This document defines Web Linking using a link format for use by This specification defines Web Linking using a link format for use by
constrained web servers to describe hosted resources, their constrained web servers to describe hosted resources, their
attributes and other relationships between links. Based on the HTTP attributes and other relationships between links. Based on the HTTP
Link Header field defined in RFC5988, the CoRE Link Format is carried Link Header field defined in RFC5988, the CoRE Link Format is carried
as a payload and is assigned an Internet media type. A well-known as a payload and is assigned an Internet media type. A well-known
URI is defined as a default entry-point for requesting the links URI is defined as a default entry-point for requesting the links
hosted by a server. hosted by a server.
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
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 19, 2012. This Internet-Draft will expire on November 24, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 23 skipping to change at page 2, line 23
1.2.2. Resource Collections . . . . . . . . . . . . . . . . . 5 1.2.2. Resource Collections . . . . . . . . . . . . . . . . . 5
1.2.3. Resource Directory . . . . . . . . . . . . . . . . . . 5 1.2.3. Resource Directory . . . . . . . . . . . . . . . . . . 5
1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Link Format . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Target and context URIs . . . . . . . . . . . . . . . . . 9 2.1. Target and context URIs . . . . . . . . . . . . . . . . . 9
2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 9 2.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 9
2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 9 2.3. Use of anchors . . . . . . . . . . . . . . . . . . . . . . 9
3. CoRE link attributes . . . . . . . . . . . . . . . . . . . . . 9 3. CoRE link attributes . . . . . . . . . . . . . . . . . . . . . 9
3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10 3.1. Resource type 'rt' attribute . . . . . . . . . . . . . . . 10
3.2. Interface description 'if' attribute . . . . . . . . . . . 10 3.2. Interface description 'if' attribute . . . . . . . . . . . 10
3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 10 3.3. Maximum size estimate 'sz' attribute . . . . . . . . . . . 11
4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11 4. Well-known Interface . . . . . . . . . . . . . . . . . . . . . 11
4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12 4.1. Query Filtering . . . . . . . . . . . . . . . . . . . . . 12
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16 7.1. Well-known 'core' URI . . . . . . . . . . . . . . . . . . 16
7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16 7.2. New 'hosts' relation type . . . . . . . . . . . . . . . . 16
7.3. New link-format Internet media type . . . . . . . . . . . 16 7.3. New link-format Internet media type . . . . . . . . . . . 16
7.4. Registry for Resource Type and Interface Description 7.4. Constrained RESTful Environments (CORE) Parameters
Values . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 17
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19
9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 19 9. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 19
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.1. Normative References . . . . . . . . . . . . . . . . . . . 23 10.1. Normative References . . . . . . . . . . . . . . . . . . . 23
10.2. Informative References . . . . . . . . . . . . . . . . . . 23 10.2. Informative References . . . . . . . . . . . . . . . . . . 24
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25
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
[REST] in a suitable form for the most constrained nodes (e.g. 8-bit [REST] in a suitable form for the most constrained nodes (e.g. 8-bit
microcontrollers with limited memory) and networks (e.g. 6LoWPAN microcontrollers with limited memory) and networks (e.g. 6LoWPAN
[RFC4944]). CoRE is aimed at Machine-to-Machine (M2M) applications [RFC4919]). CoRE is aimed at Machine-to-Machine (M2M) applications
such as smart energy and building automation. such as smart energy and building automation.
The discovery of resources hosted by a constrained server is very The discovery of resources hosted by a constrained server is very
important in machine-to-machine applications where there are no important in machine-to-machine applications where there are no
humans in the loop and static interfaces result in fragility. The humans in the loop and static interfaces result in fragility. The
discovery of resources provided by an HTTP [RFC2616] Web Server is discovery of resources provided by an HTTP [RFC2616] Web Server is
typically called Web Discovery and the description of relations typically called Web Discovery and the description of relations
between resources is called Web Linking [RFC5988]. In the present between resources is called Web Linking [RFC5988]. In the present
document we refer to the discovery of resources hosted by a specification we refer to the discovery of resources hosted by a
constrained web server, their attributes and other resource relations constrained web server, their attributes and other resource relations
as CoRE Resource Discovery. as CoRE 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 Identifiers (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
skipping to change at page 4, line 28 skipping to change at page 4, line 28
Typical use cases for Web Linking on today's web include e.g. Typical use cases for Web Linking on today's web include e.g.
describing the author of a web page or describing relations between describing the author of a web page or describing relations between
web pages (next chapter, previous chapter etc.). Web Linking can web pages (next chapter, previous chapter etc.). Web Linking can
also be applied to M2M applications, where typed links are used to also be applied to M2M applications, where typed links are used to
assist a machine client in finding and understanding how to use assist a machine client in finding and understanding how to use
resources on a server. In this section a few use cases are described resources on a server. In this section a few use cases are described
for how the CoRE Link Format could be used in M2M applications. For for how the CoRE Link Format could be used in M2M applications. For
further technical examples see Section 5. As there are a large range further technical examples see Section 5. As there are a large range
of M2M applications, these use cases are purposely generic. This of M2M applications, these use cases are purposely generic. This
document assumes that different deployments or application domains specification assumes that different deployments or application
will define the appropriate REST Interface Descriptions along with domains will define the appropriate REST Interface Descriptions along
Resource Types to make discovery meaningful. with Resource Types to make discovery meaningful.
1.2.1. Discovery 1.2.1. Discovery
In M2M applications, for example home or building automation, there In M2M applications, for example home or building automation, there
is a need for local clients and servers to find and interact with is a need for local clients and servers to find and interact with
each other without human intervention. The CoRE Link Format can be each other without human intervention. The CoRE Link Format can be
used by servers in such environments to enable Resource Discovery of used by servers in such environments to enable Resource Discovery of
the resources hosted by the server. the resources hosted by the server.
Resource Discovery can be performed either unicast or multicast. Resource Discovery can be performed either unicast or multicast.
skipping to change at page 5, line 47 skipping to change at page 5, line 47
for resources. Resource registration can be achieved by having each for resources. Resource registration can be achieved by having each
server POST their resources to "/.well-known/core" on the resource server POST their resources to "/.well-known/core" on the resource
directory. This in turn adds links to the resource directory under directory. This in turn adds links to the resource directory under
an appropriate resource. These links can then be discovered by any an appropriate resource. These links can then be discovered by any
client by making a request to a resource directory lookup interface. client by making a request to a resource directory lookup interface.
1.3. Terminology 1.3. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. specification are to be interpreted as described in [RFC2119].
This specification makes use of the Augmented Backus-Naur Form (ABNF)
[RFC5234] notation, including the core rules defined in Appendix A of
that document.
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC5988] and [RFC6454]. In and concepts that are discussed in [RFC5988] and [RFC6454]. In
addition, this specification makes use of the following terminology: addition, this specification 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
skipping to change at page 7, line 10 skipping to change at page 7, line 14
"application/link-format" for the CoRE Link Format (see Section 7.3). "application/link-format" for the CoRE Link Format (see Section 7.3).
Whereas the HTTP Link Header field depends on [RFC2616] for its Whereas the HTTP Link Header field depends on [RFC2616] for its
encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629]. A
decoder of the format is not expected to (but not prohibited from) decoder of the format is not expected to (but not prohibited from)
validate UTF-8 encoding and doesn't need to perform any UTF-8 validate UTF-8 encoding and doesn't need to perform any UTF-8
normalization. UTF-8 data can be compared bit-wise, which allows normalization. UTF-8 data can be compared bit-wise, which allows
values to contain UTF-8 data without any added complexity for values to contain UTF-8 data without any added complexity for
constrained nodes. constrained nodes.
The CoRE link format is equivalent to the [RFC5988] link format, The CoRE link format is equivalent to the [RFC5988] link format,
however the ABNF in the present document is repeated with however the ABNF in the present specification is repeated with
improvements to be compliant with [RFC5234] and includes new link improvements to be compliant with [RFC5234] and includes new link
parameters. As in [RFC5988], multiple link descriptions are parameters. The link parameter "href" is reserved for use as a query
separated by commas. Note that commas can also occur in quoted parameter for filtering in this specification (see Section 4.1), and
strings and URIs but do not end a description. In order to convert MUST NOT be defined as a link parameter. As in [RFC5988], multiple
an HTTP Link Header field to this link format, first the "Link:" HTTP link descriptions are separated by commas. Note that commas can also
header is removed, any LWS is removed, the header value is converted occur in quoted strings and URIs but do not end a description. In
to UTF-8 and any percent-encodings decoded. order to convert an HTTP Link Header field to this link format, first
the "Link:" HTTP header is removed, any LWS is removed, the header
value is converted to UTF-8 and any percent-encodings decoded.
Link = link-value-list Link = link-value-list
link-value-list = [ link-value *[ "," link-value ]] link-value-list = [ link-value *[ "," link-value ]]
link-value = "<" URI-Reference ">" *( ";" link-param ) link-value = "<" URI-Reference ">" *( ";" link-param )
link-param = ( ( "rel" "=" relation-types ) link-param = ( ( "rel" "=" relation-types )
/ ( "anchor" "=" <"> URI-Reference <"> ) / ( "anchor" "=" DQUOTE URI-Reference DQUOTE )
/ ( "rev" "=" relation-types ) / ( "rev" "=" relation-types )
/ ( "hreflang" "=" Language-Tag ) / ( "hreflang" "=" Language-Tag )
/ ( "media" "=" ( MediaDesc / ( <"> MediaDesc <"> ) ) ) / ( "media" "=" ( MediaDesc
/ ( "title" "=" quoted-string ) / ( DQUOTE MediaDesc DQUOTE ) ) )
/ ( "title*" "=" ext-value ) / ( "title" "=" quoted-string )
/ ( "type" "=" ( media-type / quoted-mt ) ) / ( "title*" "=" ext-value )
/ ( "rt" "=" relation-types ) / ( "type" "=" ( media-type / quoted-mt ) )
/ ( "if" "=" relation-types ) / ( "rt" "=" relation-types )
/ ( "sz" "=" cardinal ) / ( "if" "=" relation-types )
/ ( link-extension ) ) / ( "sz" "=" cardinal )
link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] ) / ( link-extension ) )
/ ( ext-name-star "=" ext-value ) link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] )
ext-name-star = parmname "*" ; reserved for RFC2231-profiled / ( ext-name-star "=" ext-value )
; extensions. Whitespace NOT ext-name-star = parmname "*" ; reserved for RFC2231-profiled
; allowed in between. ; extensions. Whitespace NOT
ptoken = 1*ptokenchar ; allowed in between.
ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "(" ptoken = 1*ptokenchar
/ ")" / "*" / "+" / "-" / "." / "/" / DIGIT ptokenchar = "!" / "#" / "$" / "%" / "&" / "'" / "("
/ ":" / "<" / "=" / ">" / "?" / "@" / ALPHA / ")" / "*" / "+" / "-" / "." / "/" / DIGIT
/ "[" / "]" / "^" / "_" / "`" / "{" / "|" / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA
/ "}" / "~" / "[" / "]" / "^" / "_" / "`" / "{" / "|"
media-type = type-name "/" subtype-name / "}" / "~"
quoted-mt = <"> media-type <"> media-type = type-name "/" subtype-name
relation-types = relation-type quoted-mt = DQUOTE media-type DQUOTE
/ <"> relation-type *( 1*SP relation-type ) <"> relation-types = relation-type
relation-type = reg-rel-type / ext-rel-type / DQUOTE relation-type *( 1*SP relation-type ) DQUOTE
reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" ) relation-type = reg-rel-type / ext-rel-type
ext-rel-type = URI reg-rel-type = LOALPHA *( LOALPHA / DIGIT / "." / "-" )
cardinal = "0" / ( %x31-39 *DIGIT ) ext-rel-type = URI
LOALPHA = <defined in RFC2616> cardinal = "0" / ( %x31-39 *DIGIT )
quoted-string = <defined in RFC2616> LOALPHA = %x61-7A ; a-z
URI = <defined in RFC3986> quoted-string = <defined in RFC2616>
URI-Reference = <defined in RFC3986> URI = <defined in RFC3986>
type-name = <defined in RFC4288> URI-Reference = <defined in RFC3986>
subtype-name = <defined in RFC4288> type-name = <defined in RFC4288>
MediaDesc = <defined in W3C.REC-html401-19991224> subtype-name = <defined in RFC4288>
Language-Tag = <defined in RFC5646> MediaDesc = <defined in W3C.REC-html401-19991224>
ext-value = <defined in RFC5987> Language-Tag = <defined in RFC5646>
parmname = <defined in RFC5987> ext-value = <defined in RFC5987>
parmname = <defined in RFC5987>
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]) is determined by the following rules in this [RFC3986]) is determined by the following rules in this
specification: specification:
(a) The context URI is set to the anchor parameter, when specified, (a) The context URI is set to the anchor parameter, when specified,
or or
skipping to change at page 10, line 13 skipping to change at page 10, line 13
relation), but that this is not part of the protocol and MUST NOT be relation), but that this is not part of the protocol and MUST NOT be
done automatically on link evaluation. When attributes values are done automatically on link evaluation. When attributes values are
compared, they MUST be compared as strings. compared, they MUST be compared as strings.
3.1. Resource type 'rt' attribute 3.1. Resource type 'rt' attribute
The resource type "rt" attribute is an opaque string used to assign The resource type "rt" attribute is an opaque string used to assign
an application specific semantic type to a resource. One can think an application specific semantic type to a resource. One can think
of this as a noun describing the resource. In the case of a of this as a noun describing the resource. In the case of a
temperature resource this could be e.g. an application-specific temperature resource this could be e.g. an application-specific
semantic type like "OutdoorTemperature" or a URI referencing a semantic type like "outdoor-temperature" or a URI referencing a
specific concept in an ontology like specific concept in 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 types MAY be included in the value of this parameter, each resource types MAY be included in the value of this parameter, each
separated by a space, similar to the relation attribute. The separated by a space, similar to the relation attribute. The
registry for Resource Type values is defined in Section 7.4. registry for Resource Type values is defined in Section 7.4.
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. The resource type attribute [RFC5988] is meant for that purpose. The resource type attribute
MUST NOT appear more than once in a link. MUST NOT appear more than once in a link.
3.2. Interface description 'if' attribute 3.2. Interface description 'if' attribute
The Interface Description "if" attribute is an opaque string used to The Interface Description "if" attribute is an opaque string used to
provide a name or URI indicating a specific interface definition used provide a name or URI indicating a specific interface definition used
to interact with the target resource. One can think of this as 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 "outdoor-temperature", "dew-point" and
"RelHumidity" could all be accessible using the interface description "rel-humidity" could all be accessible using the interface
"http://www.example.org/myapp.wadl#sensor". Multiple interface description "http://www.example.org/myapp.wadl#sensor". Multiple
descriptions MAY be included in the value of this parameter, each interface descriptions MAY be included in the value of this
separated by a space, similar to the relation attribute. The parameter, each separated by a space, similar to the relation
registry for Interface Description values is defined in Section 7.4. attribute. The registry for Interface Description values is defined
in Section 7.4.
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) [WADL] definition of the Application Description Language (WADL) [WADL] definition of the
target resource "http://www.example.org/myapp.wadl#sensor", a URN target resource "http://www.example.org/myapp.wadl#sensor", a URN
indicating the type of interface to the resource "urn:myapp:sensor", indicating the type of interface to the resource "urn:myapp:sensor",
or an application-specific name "Sensor". The Interface Description or an application-specific name "Sensor". The Interface Description
attribute MUST NOT appear more than once in a link. attribute MUST NOT appear more than once in a link.
3.3. Maximum size estimate 'sz' attribute 3.3. Maximum size estimate 'sz' attribute
skipping to change at page 11, line 24 skipping to change at page 11, line 29
"Big", which in further processing would indicate that a size 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 was given that was so big that it cannot be processed by this
implementation. 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 specification defines a new well-known resource
CoRE Resource Discovery "/.well-known/core". for CoRE Resource Discovery "/.well-known/core".
A server implementing this specification MUST support this resource A server implementing this specification MUST support this resource
on the default port appropriate for the protocol for the purpose of on the default port appropriate for the protocol for the purpose of
resource discovery. It is however up to the application which links resource discovery. It is however up to the application which links
are included and how they are organized. The resource "/.well-known/ are included and how they are organized. The resource "/.well-known/
core" is meant to be used to return links to the entry points of core" is meant to be used to return links to the entry points of
resource interfaces on a server. More sophisticated link resource interfaces on a server. More sophisticated link
organization can be achieved by including links to CoRE Link Format organization can be achieved by including links to CoRE Link Format
resources located elsewhere on the server, for example to achieve an resources located elsewhere on the server, for example to achieve an
index. In the absence of any links, a zero-length payload is index. In the absence of any links, a zero-length payload is
skipping to change at page 11, line 50 skipping to change at page 12, line 7
interactions: interactions:
o Performing a GET on "/.well-known/core" to the default port o Performing a GET on "/.well-known/core" to the default port
returns a set of links available from the server (if any) in the returns a set of links available from the server (if any) in the
CoRE Link Format. These links might describe resources hosted on CoRE Link Format. These links might describe resources hosted on
that server, on other servers, or express other kinds of link that server, on other servers, or express other kinds of link
relations as described in Section 2. 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 4.1. For example using a query string as specified in Section 4.1. For example
[GET /.well-known/core?rt=TemperatureC] would request resources [GET /.well-known/core?rt=temperature-c] would request resources
with the resource type TemperatureC. A server is not however with the resource type TemperatureC. A server is not however
required to support filtering. required to 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 allowing servers to POST requests to "/.well-known/ points or allowing servers to POST requests to "/.well-known/
core". The details of such resource directory functionality is core". The details of such resource directory functionality is
however out of scope for this document, and is expected to be however out of scope for this specification, and is expected to be
specified separately. specified separately.
4.1. Query Filtering 4.1. Query Filtering
A server implementing this document MAY recognize the query part of a A server implementing this specification MAY recognize the query part
resource discovery URI as a filter on the resources to be returned. of a resource discovery URI as a filter on the resources to be
The query part should conform to the following syntax. Note that returned. The path and query components together should conform to
this only defines querying for a single parameter at a time. the following level-4 URI Template [RFC6570]
filter-query = resource-param "=" query-pattern /.well-known/core{?search*}
resource-param = "href" / parmname
query-pattern = search-token [ "*" ]
search-token = *search-char
search-char = unreserved / pct-encoded
/ ":" / "@" ; from pchar
/ "/" / "?" ; from query
/ "!" / "$" / "'" / "(" / ")"
/ "+" / "," / ";" / "=" ; from sub-delims
parmname = <defined in RFC5987>
pct-encoding = <defined in RFC3986>
unreserved = <defined in RFC3986>
The resource-param "href" refers to the URI-reference between the "<" where the variable "search" is a 1-element list that has a single
and ">" characters of a link. Other resource-param values refer to name/value pair, where
the link attribute they name. Filtering is performed by comparing
the normalized query-pattern (decode percent-encoding and convert to
UTF8) against the value of the attribute identified by the resource-
param for each link-value in the collection of resources identified
by the URI path.
If the decoded query-pattern does not end with "*", a link value o name is either "href", a link-param name defined in this
matches the query only if the value of the attribute or URI-reference specification, or any other link-extension name, and
denoted by the resource-param is byte-wise identical to the
normalized query-pattern. If the decoded query-pattern ends with o value is either a Complete Value String that does not end in a "*"
"*", it is sufficient that the remainder of the query-pattern be a (%2A), or a Prefix Value String followed by a "*" (%2A).
prefix of the value denoted by the resource-param. A query-pattern
of "*" matches to an empty string value as well as to any other non- The search name "href" refers to the URI-reference between the "<"
empty string. It is not expected that very constrained nodes support and ">" characters of a link. Both Value Strings match a target
filtering. Implementations not supporting filtering MUST simply attribute only if it exists. Value Strings are percent-decoded
ignore the query string and return the whole resource for unicast ([RFC3986] section 2.1) before matching; similarly, any target
requests. attributes notated as quoted-string are interpreted as defined in
section 2.2 of [RFC2616]. After these steps, a Complete Value String
matches a target attribute if it is bitwise identical. A Prefix
Value String matches a target attribute if is is a bitwise prefix of
the target attribute (where any string is a prefix of itself). Empty
prefix value strings are allowed, by the definition above they match
any target attribute that does exist.
It is not expected that very constrained nodes support filtering.
Implementations not supporting filtering MUST simply ignore the query
string and return the whole resource for unicast requests.
When using a transfer protocol like the Constrained Application When using a transfer protocol like the Constrained Application
Protocol (CoAP) that supports multicast requests, special care needs Protocol (CoAP) that supports multicast requests, special care needs
to be taken. A multicast request with a query string SHOULD NOT be to be taken. A multicast request with a query string SHOULD NOT be
responded to if filtering is not supported or if the filter does not responded to if filtering is not supported or if the filter does not
match (to avoid a needless response storm). The exception is in match (to avoid a needless response storm). The exception is in
cases where the IP stack interface is not able to indicate that the cases where the IP stack interface is not able to indicate that the
destination address was multicast. destination address was multicast.
The following are examples of valid query URIs:
o ?href=/foo matches a link-value that is anchored at /foo
o ?href=/foo* matches a link-value that is anchored at a URI that
starts with /foo
o ?foo=bar matches a link value that has a target attribute named
foo with the exact value bar
o ?foo=bar* matches a link value that has a target attribute named
foo the value of which starts with bar, e.g., bar or barley
o ?foo=* matches a link value that has a target attribute named foo
5. Examples 5. Examples
A few examples of typical link descriptions in this format follows. A few examples of typical link descriptions in this format follows.
Multiple resource descriptions in a representation are separated by Multiple resource descriptions in a representation are separated by
commas. Linefeeds are also included in these examples for commas. Linefeeds are also included in these examples for
readability. Although the following examples use CoAP response readability. Although the following examples use CoAP response
codes, the examples are applicable to HTTP as well (the corresponding codes, the examples are applicable to HTTP as well (the corresponding
response code would be 200 OK). response code would be 200 OK).
This example includes links to two different sensors sharing the same This example includes links to two different sensors sharing the same
skipping to change at page 14, line 13 skipping to change at page 14, line 15
the sensors. the sensors.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 Content RES: 2.05 Content
</sensors>;ct=40 </sensors>;ct=40
REQ: GET /sensors REQ: GET /sensors
RES: 2.05 "Content" RES: 2.05 "Content"
</sensors/temp>;rt="TemperatureC";if="sensor", </sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="LightLux";if="sensor" </sensors/light>;rt="light-lux";if="sensor"
An example query filter may look like: An example query filter may look like:
REQ: GET /.well-known/core?rt=LightLux REQ: GET /.well-known/core?rt=light-lux
RES: 2.05 "Content" RES: 2.05 "Content"
</sensors/light>;rt="LightLux";if="sensor" </sensors/light>;rt="light-lux";if="sensor"
This example shows the use of an anchor attribute to relate the This example shows the use of an anchor attribute to relate the
temperature sensor resource to an external description and to an temperature sensor resource to an external description and to an
alternative URI. alternative URI.
REQ: GET /.well-known/core REQ: GET /.well-known/core
RES: 2.05 "Content" RES: 2.05 "Content"
</sensors>;ct=40;title="Sensor Index", </sensors>;ct=40;title="Sensor Index",
</sensors/temp>;rt="TemperatureC";if="sensor", </sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="LightLux";if="sensor", </sensors/light>;rt="light-lux";if="sensor",
<http://www.example.com/sensors/t123>;anchor="/sensors/temp" <http://www.example.com/sensors/t123>;anchor="/sensors/temp"
;rel="describedby", ;rel="describedby",
</t>;anchor="/sensors/temp";rel="alternate" </t>;anchor="/sensors/temp";rel="alternate"
If a client is interested to find relations about a particular If a client is interested to find relations about a particular
resource, it can perform a query on the anchor parameter: resource, it can perform a query on the anchor parameter:
REQ: GET /.well-known/core?anchor=/sensors/temp REQ: GET /.well-known/core?anchor=/sensors/temp
RES: 2.05 "Content" RES: 2.05 "Content"
skipping to change at page 15, line 16 skipping to change at page 15, line 19
the sz attribute. Thus a special flag or value should be used to the sz attribute. Thus a special flag or value should be used to
indicate "Big" (larger than 64 KiB). indicate "Big" (larger than 64 KiB).
REQ: GET /.well-known/core?rt=firmware REQ: GET /.well-known/core?rt=firmware
RES: 2.05 "Content" RES: 2.05 "Content"
</firmware/v2.1>;rt="firmware";sz=262144 </firmware/v2.1>;rt="firmware";sz=262144
6. Security Considerations 6. Security Considerations
This document has the same security considerations as described in This specification has the same security considerations as described
Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be in Section 7 of [RFC5988]. The "/.well-known/core" resource MAY be
protected e.g. using DTLS when hosted on a CoAP server as per protected e.g. using DTLS when hosted on a CoAP server as per
[I-D.ietf-core-coap] Section 10.2. [I-D.ietf-core-coap] Section 10.2.
Some servers might provide resource discovery services to a mix of Some servers might provide resource discovery services to a mix of
clients that are trusted to different levels. For example, a clients that are trusted to different levels. For example, a
lighting control system might allow any client to read state lighting control system might allow any client to read state
variables, but only certain clients to write state (turn lights on or variables, but only certain clients to write state (turn lights on or
off). Servers that have authentication and authorization features off). Servers that have authentication and authorization features
SHOULD support authentication features of the underlying transport SHOULD support authentication features of the underlying transport
protocols (HTTP or DTLS/TLS) and allow servers to return different protocols (HTTP or DTLS/TLS) and allow servers to return different
skipping to change at page 17, line 41 skipping to change at page 17, line 41
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. Registry for Resource Type and Interface Description Values 7.4. Constrained RESTful Environments (CORE) Parameters Registry
This specification establishes two new registries, one for Resource This specification establishes a new Constrained RESTful Environments
Type (rt=) and the other for Interface Description (if=) link target (CORE) Parameters registry, which contains two new sub-registries of
attribute values. This registry is similar to the Link Relation Link Target Attribute values (defined in [RFC5988]), one for Resource
Registry defined in [RFC5988]. No initial entries are defined by Type (rt=) Link Target Attribute values and the other for Interface
this specification for either registry. Description (if=) Link Target Attribute values. No initial entries
are defined by this specification for either sub-registry.
These registries have the following requirements on values: For both sub-registries, values starting with the characters "core"
are registered using the IETF Review registration policy [RFC5226].
All other values are registered using the Specification Required
policy, which requires review by a designated expert appointed by the
IESG or their delegate.
The designated expert will enforce the following requirements:
o Registration values MUST be related to the intended purpose of o Registration values MUST be related to the intended purpose of
these attributes as described in Section 3. these attributes as described in Section 3.
o Registered values MUST conform to the ABNF reg-rel-type definition o Registered values MUST conform to the ABNF reg-rel-type definition
of Section 2, meaning the value MUST start with a lower case of Section 2, meaning that the value starts with a lower case
alphabet character, followed by a sequence of lower case alphabet, alphabetic character, followed by a sequence of lower case
numeric, "." or "-" characters. The value MUST NOT contain white alphabetic, numeric, "." or "-" characters, and contains no white
space. space.
o It is recommended that the period "." character is used for o It is recommended that the period "." character be used for
dividing name segments, and that the dash "-" character is used dividing name segments, and that the dash "-" character be used
for making a segment more readable. Example Interface Description for making a segment more readable. Example Interface Description
values might be "core.batch" and "core.link-batch". values might be "core.batch" and "core.link-batch".
o URIs are reserved for free use as extension values for these o URIs are reserved for free use as extension values for these
attributes, and MUST NOT be registered. attributes, and MUST NOT be registered.
Values starting with the characters "core" are reserved, and can only
be requested for registration when defined in an IETF working group
document.
Relation types are registered on the advice of a Designated Expert
(appointed by the IESG or their delegate), with a Specification
Required (using terminology from [RFC5226]).
Registration requests consist of the completed registration template Registration requests consist of the completed registration template
below, typically published in an RFC or Open Standard (in the sense below, with the reference pointing to the required specification. To
described by [RFC2026], Section 7). However, to allow for the allow for the allocation of values prior to publication, the
allocation of values prior to publication, the Designated Expert may designated expert may approve registration once they are satisfied
approve registration once they are satisfied that a specification that a specification will be published.
will be published.
Note that relation types can be registered by third parties, if the Note that link target attribute values can be registered by third
Designated Expert determines that an unregistered relation type is parties, if the Designated Expert determines that an unregistered
widely deployed and not likely to be registered in a timely manner. link target attribute values is widely deployed and not likely to be
registered in a timely manner.
The registration template for both registries is: The registration template for both sub-registries is:
o Attribute Value: o Attribute Value:
o Description: o Description:
o Reference: o Reference:
o Notes: [optional] o Notes: [optional]
Registration requests should be sent to the (TBD)@ietf.org mailing Registration requests should be sent to the core-parameters@ietf.org
list, marked clearly in the subject line (e.g., "NEW RESOURCE TYPE - mailing list, marked clearly in the subject line (e.g., "NEW RESOURCE
example" to register an "example" relation type, or "NEW INTERFACE TYPE - example" to register an "example" relation type, or "NEW
DESCRIPTION - example" to register an "example" interface INTERFACE DESCRIPTION - example" to register an "example" interface
description). description).
Within at most 14 days of the request, the Designated Expert(s) will Within at most 14 days of the request, the Designated Expert(s) will
either approve or deny the registration request, communicating this either approve or deny the registration request, communicating this
decision to the review list and IANA. Denials should include an decision to the review list and IANA. Denials should include an
explanation and, if applicable, suggestions as to how to make the explanation and, if applicable, suggestions as to how to make the
request successful. request successful.
Decisions (or lack thereof) made by the Designated Expert can be Decisions (or lack thereof) made by the Designated Expert can be
first appealed to Application Area Directors (contactable using first appealed to Application Area Directors (contactable using
app-ads@tools.ietf.org email address or directly by looking up their app-ads@tools.ietf.org email address or directly by looking up their
email addresses on http://www.iesg.org/ website) and, if the email addresses on http://www.iesg.org/ website) and, if the
appellant is not satisfied with the response, to the full IESG (using appellant is not satisfied with the response, to the full IESG (using
the iesg@iesg.org mailing list). the iesg@iesg.org mailing list).
IANA should only accept registry updates from the Designated
Expert(s), and should direct all requests for registration to the
review mailing list.
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 improving the ABNF In particular, Peter is responsible for early improvements to the
descriptions and the idea for a new "hosts" relation type. ABNF descriptions and the 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, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard
Barnes and Peter Saint-Andre for extensive comments and contributions Barnes, Barry Leiba and Peter Saint-Andre for extensive comments and
that improved the text. 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-12 to ietf-13:
o Improvements to the new CoRE Parameters registry
o Replaced the Section 4.1 ABNF Query Filter definition with a URI
Template (#240)
o Aligned examples with rt= and if= value rules
o Clarified that "href" can not be a link parameter
Changes from ietf-11 to ietf-12: Changes from ietf-11 to ietf-12:
o Changed "uri" to "href" in the filter query (#200) o Changed "uri" to "href" in the filter query (#200)
o Upgraded all ABNF to RFC5234 (#197) o Upgraded all ABNF to RFC5234 (#197)
o Put multiple rt= and if= values in a single attribute (as in o Put multiple rt= and if= values in a single attribute (as in
rel=) (#199) rel=) (#199)
o Use the Origin definition (#191) o Use the Origin definition (#191)
o Clarified URI fetching rules (#196) o Clarified URI fetching rules (#196)
o Added access control and other security consideration o Added access control and other security consideration
improvements (#189) improvements (#189)
skipping to change at page 23, line 21 skipping to change at page 23, line 28
o Removed the assumption of a default content-type. o Removed the assumption of a default content-type.
10. References 10. References
10.1. Normative References 10.1. Normative References
[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.
[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.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 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.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005. Registration Procedures", BCP 13, RFC 4288, December 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[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.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009. Languages", BCP 47, RFC 5646, September 2009.
[RFC5987] Reschke, J., "Character Set and Language Encoding for [RFC5987] Reschke, J., "Character Set and Language Encoding for
Hypertext Transfer Protocol (HTTP) Header Field Hypertext Transfer Protocol (HTTP) Header Field
Parameters", RFC 5987, August 2010. Parameters", RFC 5987, August 2010.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012.
10.2. Informative References 10.2. Informative References
[I-D.ietf-core-coap] [I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank, Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)", "Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-09 (work in progress), March 2012. draft-ietf-core-coap-09 (work in progress), March 2012.
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000, <http:// Network-based Software Architectures", 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>. www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>.
skipping to change at page 24, line 16 skipping to change at page 24, line 35
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities", [RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, November 1987. STD 13, RFC 1034, November 1987.
[RFC1035] Mockapetris, P., "Domain names - implementation and [RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987. specification", STD 13, RFC 1035, November 1987.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[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.
[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, [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
"Transmission of IPv6 Packets over IEEE 802.15.4 over Low-Power Wireless Personal Area Networks (6LoWPANs):
Networks", RFC 4944, September 2007. Overview, Assumptions, Problem Statement, and Goals",
RFC 4919, August 2007.
[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.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
December 2011. December 2011.
[WADL] Hadley, M., "Web Application Description Language (WADL)", [WADL] Hadley, M., "Web Application Description Language (WADL)",
2009, <http://java.net/projects/wadl/sources/svn/content/ 2009, <http://java.net/projects/wadl/sources/svn/content/
 End of changes. 49 change blocks. 
168 lines changed or deleted 200 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/