draft-ietf-core-resource-directory-15.txt   draft-ietf-core-resource-directory-16.txt 
CoRE Z. Shelby CoRE Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Standards Track M. Koster Intended status: Standards Track M. Koster
Expires: April 6, 2019 SmartThings Expires: April 26, 2019 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
C. Amsuess, Ed. C. Amsuess, Ed.
October 03, 2018 October 23, 2018
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-15 draft-ietf-core-resource-directory-16
Abstract Abstract
In many M2M applications, direct discovery of resources is not In many M2M applications, direct discovery of resources is not
practical due to sleeping nodes, disperse networks, or networks where practical due to sleeping nodes, disperse networks, or networks where
multicast traffic is inefficient. These problems can be solved by multicast traffic is inefficient. These problems can be solved by
employing an entity called a Resource Directory (RD), which hosts employing an entity called a Resource Directory (RD), which hosts
registrations of resources held on other servers, allowing lookups to registrations of resources held on other servers, allowing lookups to
be performed for those resources. This document specifies the web be performed for those resources. This document specifies the web
interfaces that a Resource Directory supports for web servers to interfaces that a Resource Directory supports for web servers to
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 https://datatracker.ietf.org/drafts/current/. Drafts is at https://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 6, 2019. This Internet-Draft will expire on April 26, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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
(https://trustee.ietf.org/license-info) in effect on the date of (https://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 3, line 20 skipping to change at page 3, line 20
Parameter . . . . . . . . . . . . . . . . . . . . . 46 Parameter . . . . . . . . . . . . . . . . . . . . . 46
10.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . 46 10.4. "Endpoint Type" (et=) RD Parameter values . . . . . . . 46
10.5. Multicast Address Registration . . . . . . . . . . . . . 47 10.5. Multicast Address Registration . . . . . . . . . . . . . 47
11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47
11.1. Lighting Installation . . . . . . . . . . . . . . . . . 47 11.1. Lighting Installation . . . . . . . . . . . . . . . . . 47
11.1.1. Installation Characteristics . . . . . . . . . . . . 47 11.1.1. Installation Characteristics . . . . . . . . . . . . 47
11.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 48 11.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 48
11.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 51 11.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 51
11.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52 11.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 52
11.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 53 11.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 53
11.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 54 11.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 55
11.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 55 11.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 55
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55
13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 55 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 55
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 62
14.1. Normative References . . . . . . . . . . . . . . . . . . 62 14.1. Normative References . . . . . . . . . . . . . . . . . . 62
14.2. Informative References . . . . . . . . . . . . . . . . . 62 14.2. Informative References . . . . . . . . . . . . . . . . . 63
Appendix A. Registration Management . . . . . . . . . . . . . . 64 Appendix A. Registration Management . . . . . . . . . . . . . . 65
A.1. Registration Update . . . . . . . . . . . . . . . . . . . 65 A.1. Registration Update . . . . . . . . . . . . . . . . . . . 65
A.2. Registration Removal . . . . . . . . . . . . . . . . . . 68 A.2. Registration Removal . . . . . . . . . . . . . . . . . . 68
A.3. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 69 A.3. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 69
A.4. Update Endpoint Links . . . . . . . . . . . . . . . . . . 70 A.4. Update Endpoint Links . . . . . . . . . . . . . . . . . . 70
A.5. Endpoint and group lookup . . . . . . . . . . . . . . . . 70 A.5. Endpoint and group lookup . . . . . . . . . . . . . . . . 71
Appendix B. Web links and the Resource Directory . . . . . . . . 72 Appendix B. Web links and the Resource Directory . . . . . . . . 72
B.1. A simple example . . . . . . . . . . . . . . . . . . . . 72 B.1. A simple example . . . . . . . . . . . . . . . . . . . . 72
B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 72 B.1.1. Resolving the URIs . . . . . . . . . . . . . . . . . 73
B.1.2. Interpreting attributes and relations . . . . . . . . 73 B.1.2. Interpreting attributes and relations . . . . . . . . 73
B.2. A slightly more complex example . . . . . . . . . . . . . 73 B.2. A slightly more complex example . . . . . . . . . . . . . 74
B.3. Enter the Resource Directory . . . . . . . . . . . . . . 74 B.3. Enter the Resource Directory . . . . . . . . . . . . . . 74
B.4. A note on differences between link-format and Link B.4. A note on differences between link-format and Link
headers . . . . . . . . . . . . . . . . . . . . . . . . . 75 headers . . . . . . . . . . . . . . . . . . . . . . . . . 76
Appendix C. Syntax examples for Protocol Negotiation . . . . . . 76 Appendix C. Syntax examples for Protocol Negotiation . . . . . . 77
Appendix D. Modernized Link Format parsing . . . . . . . . . . . 77 Appendix D. Modernized Link Format parsing . . . . . . . . . . . 78
D.1. For endpoint developers . . . . . . . . . . . . . . . . . 78 D.1. For endpoint developers . . . . . . . . . . . . . . . . . 79
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 D.2. Examples of links with differing interpretations . . . . 79
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 80
1. Introduction 1. Introduction
The work on Constrained RESTful Environments (CoRE) aims at realizing The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained the REST architecture in a suitable form for the most constrained
nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M) networks (e.g. 6LoWPAN). CoRE is aimed at machine-to-machine (M2M)
applications such as smart energy and building automation. applications such as smart energy and building automation.
The discovery of resources offered by a constrained server is very The discovery of resources offered by a constrained server is very
skipping to change at page 9, line 5 skipping to change at page 9, line 5
| Endpoint | <-- Name, Scheme, IP, Port | Endpoint | <-- Name, Scheme, IP, Port
+------------+ +------------+
| |
| |
+------------+ +------------+
| Resource | <-- Target, Parameters | Resource | <-- Target, Parameters
+------------+ +------------+
Figure 2: The resource directory information hierarchy. Figure 2: The resource directory information hierarchy.
A Registrant-EP MAY keep concurrent registrations to more than one RD
at the same time if explicitly configured to do so, but that is not
expected to be supported by typical EP implementations. Any such
registrations are independent of each other. The usual expectation
when multiple discovery mechanisms or addresses are configured is
that they constitute a fallback path for a single registration.
3.3. RD Content Model 3.3. RD Content Model
The Entity-Relationship (ER) models shown in Figure 3 and Figure 4 The Entity-Relationship (ER) models shown in Figure 3 and Figure 4
model the contents of /.well-known/core and the resource directory model the contents of /.well-known/core and the resource directory
respectively, with entity-relationship diagrams [ER]. Entities respectively, with entity-relationship diagrams [ER]. Entities
(rectangles) are used for concepts that exist independently. (rectangles) are used for concepts that exist independently.
Attributes (ovals) are used for concepts that exist only in Attributes (ovals) are used for concepts that exist only in
connection with a related entity. Relations (diamonds) give a connection with a related entity. Relations (diamonds) give a
semantic meaning to the relation between entities. Numbers specify semantic meaning to the relation between entities. Numbers specify
the cardinality of the relations. the cardinality of the relations.
skipping to change at page 21, line 43 skipping to change at page 21, line 43
"ct" MAY include a space-separated sequence of Content-Format codes "ct" MAY include a space-separated sequence of Content-Format codes
as specified in Section 7.2.1 of [RFC7252], indicating that multiple as specified in Section 7.2.1 of [RFC7252], indicating that multiple
content-formats are available. The example below shows the required content-formats are available. The example below shows the required
Content-Format 40 (application/link-format) indicated as well as the Content-Format 40 (application/link-format) indicated as well as the
CBOR and JSON representation of link format. The RD resource CBOR and JSON representation of link format. The RD resource
locations /rd, /rd-lookup, and /rd-group are example values. The locations /rd, /rd-lookup, and /rd-group are example values. The
server in this example also indicates that it is capable of providing server in this example also indicates that it is capable of providing
observation on resource lookups. observation on resource lookups.
[ The RFC editor is asked to replace these and later occurrences of [ The RFC editor is asked to replace these and later occurrences of
MCD1, TBD64 and TBD504 with the numeric ID values assigned by IANA to MCD1, TBD64 and TBD504 with the assigned IPv6 site-local address for
application/link-format+cbor and application/link-format+json, "all CoRE Resource Directories" and the numeric ID values assigned by
respectively, as they are defined in I-D.ietf-core-links-json. ] IANA to application/link-format+cbor and application/link-
format+json, respectively, as they are defined in I-D.ietf-core-
links-json. ]
Req: GET coap://[MCD1]/.well-known/core?rt=core.rd* Req: GET coap://[MCD1]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
</rd>;rt="core.rd";ct="40 65225", </rd>;rt="core.rd";ct="40 65225",
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs, </rd-lookup/res>;rt="core.rd-lookup-res";ct="40 TBD64 TBD504";obs,
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504", </rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 TBD64 TBD504",
</rd-lookup/gp>;rt="core.rd-lookup-gp";ct=40 TBD64 TBD504", </rd-lookup/gp>;rt="core.rd-lookup-gp";ct=40 TBD64 TBD504",
</rd-group>;rt="core.rd-group";ct="40 TBD64 TBD504" </rd-group>;rt="core.rd-group";ct="40 TBD64 TBD504"
From a management and maintenance perspective, it is necessary to From a management and maintenance perspective, it is necessary to
skipping to change at page 30, line 13 skipping to change at page 30, line 13
value of the individual links as exemplified in Appendix B. An value of the individual links as exemplified in Appendix B. An
eventual (currently non-existing) "base" attribute of the link is not eventual (currently non-existing) "base" attribute of the link is not
affected by the value of "base" parameter in the registration. affected by the value of "base" parameter in the registration.
6. RD Groups 6. RD Groups
This section defines the REST API for the creation, management, and This section defines the REST API for the creation, management, and
lookup of endpoints for group operations. Similar to endpoint lookup of endpoints for group operations. Similar to endpoint
registration entries in the RD, groups may be created or removed. registration entries in the RD, groups may be created or removed.
However unlike an endpoint entry, a group entry consists of a list of However unlike an endpoint entry, a group entry consists of a list of
endpoints and does not have a lifetime associated with it. In order endpoints and does not have a lifetime associated with it. To make
to make use of multicast requests with CoAP, a group MAY have a use of multicast requests with CoAP, a group MAY have a multicast
multicast address associated with it. address associated with it, and should share a common set of
resources.
6.1. Register a Group 6.1. Register a Group
In order to create a group, a commissioning tool (CT) used to To create a group, a commissioning tool (CT) used to configure
configure groups, makes a request to the RD indicating the name of groups, makes a request to the RD indicating the name of the group to
the group to create (or update), optionally the sector the group create (or update), optionally the sector the group belongs to, and
belongs to, and optionally the multicast address of the group. This optionally the multicast address of the group. This specification
specification does not require that the endpoints belong to the same does not require that the endpoints belong to the same sector as the
sector as the group, but a Resource Directory implementation can group, but a Resource Directory implementation can impose
impose requirements on the sectors of groups and endpoints depending requirements on the sectors of groups and endpoints depending on its
on its configuration. configuration.
The registration message is a list of links to registration resources The registration message is a list of links to registration resources
of the endpoints that belong to that group. The CT can use any URI of the endpoints that belong to that group. The CT can use any URI
reference discovered using endpoint lookup from the same server or reference discovered using endpoint lookup from the same server or
obtained by registering an endpoint using third party registration obtained by registering an endpoint using third party registration
and enter it into a group. and enter it into a group.
The commissioning tool SHOULD not send any target attributes with the The commissioning tool SHOULD not send any target attributes with the
links to the registration resources, and the resource directory links to the registration resources, and the resource directory
SHOULD reject registrations that contain links with unprocessable SHOULD reject registrations that contain links with unprocessable
skipping to change at page 32, line 10 skipping to change at page 32, line 10
The following example shows an EP registering a group with the name The following example shows an EP registering a group with the name
"lights" which has two endpoints. The RD group path /rd-group is an "lights" which has two endpoints. The RD group path /rd-group is an
example RD location discovered in a request similar to Figure 6. example RD location discovered in a request similar to Figure 6.
Req: POST coap://rd.example.com/rd-group?gp=lights Req: POST coap://rd.example.com/rd-group?gp=lights
&base=coap://[ff35:30:2001:db8::1] &base=coap://[ff35:30:2001:db8::1]
Content-Format: 40 Content-Format: 40
Payload: Payload:
</rd/4521>, </rd/4521>,
</rd/4522> </rd/4520>
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd-group/12 Location-Path: /rd-group/12
A relative href value denotes the path to the registration resource A relative href value denotes the path to the registration resource
of the Endpoint. When pointing to a registration resource on a of the Endpoint. When pointing to a registration resource on a
different RD, the href value is a URI. different RD, the href value is a URI.
6.2. Group Removal 6.2. Group Removal
skipping to change at page 39, line 43 skipping to change at page 39, line 43
accessing the RD. accessing the RD.
The contents of the RD are inserted in two ways: The contents of the RD are inserted in two ways:
1. The node hosting the discoverable endpoint fills the RD with the 1. The node hosting the discoverable endpoint fills the RD with the
contents of /.well-known/core by: contents of /.well-known/core by:
* Storing the contents directly into RD (see Section 5.3) * Storing the contents directly into RD (see Section 5.3)
* Requesting the RD to load the contents from /.well-known/core * Requesting the RD to load the contents from /.well-known/core
see (section {{simple}) (see Section 5.3.1)
2. A Commissioning Tool (CT) fills the RD with endpoint information 2. A Commissioning Tool (CT) fills the RD with endpoint information
for a set of discoverable nodes. (see Section 5.3 with for a set of discoverable nodes. (see Section 5.3 with
base=authority parameter value) base=authority parameter value)
In both cases, the nodes filling the RD should be authenticated and In both cases, the nodes filling the RD should be authenticated and
authorized to change the contents of the RD. An Authorization Server authorized to change the contents of the RD. An Authorization Server
(AS) is responsible to assign a token to the registering node to (AS) is responsible to assign a token to the registering node to
authorize the node to discover or register endpoints in a given RD authorize the node to discover or register endpoints in a given RD
[I-D.ietf-ace-oauth-authz]. [I-D.ietf-ace-oauth-authz].
skipping to change at page 50, line 29 skipping to change at page 50, line 29
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd/4523 Location-Path: /rd/4523
The sector name d=R2-4-015 has been added for an efficient lookup The sector name d=R2-4-015 has been added for an efficient lookup
because filtering on "ep" name is more awkward. The same sector name because filtering on "ep" name is more awkward. The same sector name
is communicated to the two luminaries and the presence sensor by the is communicated to the two luminaries and the presence sensor by the
CT. CT.
The group is specified in the RD. The base parameter is set to the The group is specified in the RD. The base parameter is set to the
site-local multicast address allocated to the group. In the POST in site-local multicast address allocated to the group. In the POST in
the example below, these two endpoints and the endpoint of the the example below, two luminary endpoints are registered as members
presence sensor are registered as members of the group. of the group. They share a common resource set to which a multicast
request can be sent and executed by all members of the group.
Req: POST coap://[2001:db8:4::ff]/rd-group Req: POST coap://[2001:db8:4::ff]/rd-group
?gp=grp_R2-4-015&base=coap://[ff05::1] ?gp=grp_R2-4-015&base=coap://[ff05::1]
Payload: Payload:
</rd/4521>, </rd/4521>,
</rd/4522>, </rd/4522>
</rd/4523>
Res: 2.01 Created Res: 2.01 Created
Location-Path: /rd-group/501 Location-Path: /rd-group/501
After the filling of the RD by the CT, the application in the After the filling of the RD by the CT, the application in the
luminaries can learn to which groups they belong, and enable their luminaries can learn to which groups they belong, and enable their
interface for the multicast address. interface for the multicast address.
The luminary, knowing its sector and own IPv6 address, looks up the The luminary, knowing its sector and own IPv6 address, looks up the
groups containing light resources it is assigned to: groups containing light resources it is assigned to:
skipping to change at page 51, line 29 skipping to change at page 51, line 29
Content-Format: application/coap-group+json Content-Format: application/coap-group+json
Payload: Payload:
{ "a": "[ff05::1]", "n": "grp_R2-4-015"} { "a": "[ff05::1]", "n": "grp_R2-4-015"}
Res: 2.01 Created Res: 2.01 Created
Location-Path: /coap-group/1 Location-Path: /coap-group/1
Dependent on the situation, only the address, "a", or the name, "n", Dependent on the situation, only the address, "a", or the name, "n",
is specified in the coap-group resource. is specified in the coap-group resource.
The presence sensor can learn the presence of groups that support
resources with rt=light in its own sector by sending the request:
Req: GET coap://[2001:db8:4::ff]/rd-lookup/gp?d=R2-4-015&rt=light
Res: 2.05 Content
</rd-group/501>;gp="grp_R2-4-015";base="coap://[ff05::1]"
The presence sensor learns the multicast address to use for sending
messages to the luminaries.
11.2. OMA Lightweight M2M (LWM2M) Example 11.2. OMA Lightweight M2M (LWM2M) Example
This example shows how the OMA LWM2M specification makes use of This example shows how the OMA LWM2M specification makes use of
Resource Directory (RD). Resource Directory (RD).
OMA LWM2M is a profile for device services based on CoAP(OMA Name OMA LWM2M is a profile for device services based on CoAP(OMA Name
Authority). LWM2M defines a simple object model and a number of Authority). LWM2M defines a simple object model and a number of
abstract interfaces and operations for device management and device abstract interfaces and operations for device management and device
service enablement. service enablement.
skipping to change at page 55, line 32 skipping to change at page 55, line 42
Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders Oscar Novo, Srdjan Krco, Szymon Sasin, Kerry Lynn, Esko Dijk, Anders
Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen, Brandt, Matthieu Vial, Jim Schaad, Mohit Sethi, Hauke Petersen,
Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have Hannes Tschofenig, Sampo Ukkola, Linyi Tian, and Jan Newmarch have
provided helpful comments, discussions and ideas to improve and shape provided helpful comments, discussions and ideas to improve and shape
this document. Zach would also like to thank his colleagues from the this document. Zach would also like to thank his colleagues from the
EU FP7 SENSEI project, where many of the resource directory concepts EU FP7 SENSEI project, where many of the resource directory concepts
were originally developed. were originally developed.
13. Changelog 13. Changelog
changes from -15 to -16
o Recommend a common set of resources for members of a group
o Clarified use of multicast group in lighting example
o Add note on concurrent registrations from one EP being possible
but not expected
o Refresh web examples appendix to reflect current use of Modernized
Link Format
o Add examples of URIs where Modernized Link Format matters
o Editorial changes
changes from -14 to -15 changes from -14 to -15
o Rewrite of section "Security policies" o Rewrite of section "Security policies"
o Clarify that the "base" parameter text applies both to relative o Clarify that the "base" parameter text applies both to relative
references both in anchor and href references both in anchor and href
o Renamed "Registree-EP" to Registrant-EP" o Renamed "Registree-EP" to Registrant-EP"
o Talk of "relative references" and "URIs" rather than "relative" o Talk of "relative references" and "URIs" rather than "relative"
skipping to change at page 72, line 18 skipping to change at page 72, line 36
references is a journey through different documents ([RFC3986] references is a journey through different documents ([RFC3986]
defining URIs, [RFC6690] defining link-format documents based on defining URIs, [RFC6690] defining link-format documents based on
[RFC8288] which defines link headers, and [RFC7252] providing the [RFC8288] which defines link headers, and [RFC7252] providing the
transport). This appendix summarizes the mechanisms and semantics at transport). This appendix summarizes the mechanisms and semantics at
play from an entry in ".well-known/core" to a resource lookup. play from an entry in ".well-known/core" to a resource lookup.
This text is primarily aimed at people entering the field of This text is primarily aimed at people entering the field of
Constrained Restful Environments from applications that previously Constrained Restful Environments from applications that previously
did not use web mechanisms. did not use web mechanisms.
At all examples in this section give compatible results for both
Modernized and RFC6690 Link Format; the explanation of the steps
follow Modernized Link Format.
B.1. A simple example B.1. A simple example
Let's start this example with a very simple host, "2001:db8:f0::1". Let's start this example with a very simple host, "2001:db8:f0::1".
A client that follows classical CoAP Discovery ([RFC7252] Section 7), A client that follows classical CoAP Discovery ([RFC7252] Section 7),
sends the following multicast request to learn about neighbours sends the following multicast request to learn about neighbours
supporting resources with resource-type "temperature". supporting resources with resource-type "temperature".
The client sends a link-local multicast: The client sends a link-local multicast:
GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature GET coap://[ff02::fd]:5683/.well-known/core?rt=temperature
skipping to change at page 72, line 43 skipping to change at page 73, line 21
While the client - on the practical or implementation side - can just While the client - on the practical or implementation side - can just
go ahead and create a new request to "[2001:db8:f0::1]:5683" with go ahead and create a new request to "[2001:db8:f0::1]:5683" with
Uri-Path: "temp", the full resolution steps for insertion into and Uri-Path: "temp", the full resolution steps for insertion into and
retrieval from the RD without any shortcuts are: retrieval from the RD without any shortcuts are:
B.1.1. Resolving the URIs B.1.1. Resolving the URIs
The client parses the single returned record. The link's target The client parses the single returned record. The link's target
(sometimes called "href") is ""/temp"", which is a relative URI that (sometimes called "href") is ""/temp"", which is a relative URI that
needs resolving. As long as all involved links follow the needs resolving. The base URI <coap://[ff02::fd]:5683/.well-known/
restrictions set forth for this document (see Appendix B.4), the base core> is used to resolve the reference /temp against.
URI <coap://[ff02::fd]:5683/.well-known/core> is used to resolve the
reference /temp against.
The Base URI of the requested resource can be composed from the The Base URI of the requested resource can be composed from the
header options of the CoAP GET request by following the steps of header options of the CoAP GET request by following the steps of
[RFC7252] section 6.5 (with an addition at the end of 8.2) into [RFC7252] section 6.5 (with an addition at the end of 8.2) into
""coap://[2001:db8:f0::1]/.well-known/core"". ""coap://[2001:db8:f0::1]/.well-known/core"".
The record's target is resolved by replacing the path ""/.well-known/ Because ""/temp"" starts with a single slash, the record's target is
core"" from the Base URI (section 5.2 [RFC3986]) with the relative resolved by replacing the path ""/.well-known/core"" from the Base
target URI ""/temp"" into ""coap://[2001:db8:f0::1]/temp"". URI (section 5.2 [RFC3986]) with the relative target URI ""/temp""
into ""coap://[2001:db8:f0::1]/temp"".
B.1.2. Interpreting attributes and relations B.1.2. Interpreting attributes and relations
Some more information but the record's target can be obtained from Some more information but the record's target can be obtained from
the payload: the resource type of the target is "temperature", and the payload: the resource type of the target is "temperature", and
its content type is text/plain (ct=0). its content type is text/plain (ct=0).
A relation in a web link is a three-part statement that specifies a A relation in a web link is a three-part statement that specifies a
named relation between the so-called "context resource" and the named relation between the so-called "context resource" and the
target resource, like "_This page_ has _its table of contents_ at _/ target resource, like "_This page_ has _its table of contents_ at _/
toc.html_". In [RFC6690] link-format documents, there is an implicit toc.html_". In [RFC6690] and modernized link-format documents, there
"host relation" specified with default parameter: rel="hosts". is an implicit "host relation" specified with default parameter:
rel="hosts".
In our example, the context resource of the link is the URI specified In our example, the context resource of the link is the URI specified
in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A in the GET request "coap:://[2001:db8:f0::1]/.well-known/core". A
full English expression of the "host relation" is: full English expression of the "host relation" is:
'"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource '"coap://[2001:db8:f0::1]/.well-known/core" is hosting the resource
"coap://[2001:db8:f0::1]/temp", which is of the resource type "coap://[2001:db8:f0::1]/temp", which is of the resource type
"temperature" and can be accessed using the text/plain content "temperature" and can be accessed using the text/plain content
format.' format.'
skipping to change at page 74, line 26 skipping to change at page 74, line 51
used Simple Registration to register at the resource directory that used Simple Registration to register at the resource directory that
was announced to it, sending this request from its UDP port was announced to it, sending this request from its UDP port
"[2001:db8:f0::1]:6553": "[2001:db8:f0::1]:6553":
POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1 POST coap://[2001:db8:f01::ff]/.well-known/core?ep=simple-host1
The resource directory would have accepted the registration, and The resource directory would have accepted the registration, and
queried the simple host's ".well-known/core" by itself. As a result, queried the simple host's ".well-known/core" by itself. As a result,
the host is registered as an endpoint in the RD with the name the host is registered as an endpoint in the RD with the name
"simple-host1". The registration is active for 90000 seconds, and "simple-host1". The registration is active for 90000 seconds, and
the endpoint registration Base URI is ""coap://[2001:db8:f0::1]/"" the endpoint registration Base URI is ""coap://[2001:db8:f0::1]""
following the resolution steps described in Appendix B.1.1. It following the resolution steps described in Appendix B.1.1. It
should be remarked that the Base URI constructed that way always should be remarked that the Base URI constructed that way always
yields a URI of the form: scheme://authority without path suffix. yields a URI of the form: scheme://authority without path suffix.
If the client now queries the RD as it would previously have issued a If the client now queries the RD as it would previously have issued a
multicast request, it would go through the RD discovery steps by multicast request, it would go through the RD discovery steps by
fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd- fetching "coap://[2001:db8:f0::ff]/.well-known/core?rt=core.rd-
lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the lookup-res", obtain "coap://[2001:db8:f0::ff]/rd-lookup/res" as the
resource lookup endpoint, and issue a request to resource lookup endpoint, and issue a request to
"coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive "coap://[2001:db8:f0::ff]/rd-lookup/res?rt=temperature" to receive
skipping to change at page 74, line 51 skipping to change at page 75, line 28
This is not _literally_ the same response that it would have received This is not _literally_ the same response that it would have received
from a multicast request, but it contains the equivalent statement: from a multicast request, but it contains the equivalent statement:
'"coap://[2001:db8:f0::1]" is hosting the resource '"coap://[2001:db8:f0::1]" is hosting the resource
"coap://[2001:db8:f0::1]/temp", which is of the resource type "coap://[2001:db8:f0::1]/temp", which is of the resource type
"temperature" and can be accessed using the text/plain content "temperature" and can be accessed using the text/plain content
format.' format.'
(The difference is whether "/" or "/.well-known/core" hosts the (The difference is whether "/" or "/.well-known/core" hosts the
resources, which is subject of ongoing discussion about RFC6690). resources, which is one of the often misunderstood subtleties
Modernized Link Format addresses. Actually, /.well-known/core does
Actually, /.well-known/core does NOT host the resource but stores a NOT host the resource but stores a URI reference to the resource.)
URI reference to the resource.
To complete the examples, the client could also query all resources To complete the examples, the client could also query all resources
hosted at the endpoint with the known endpoint name "simple-host1". hosted at the endpoint with the known endpoint name "simple-host1".
A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1" A request to "coap://[2001:db8:f0::ff]/rd-lookup/res?ep=simple-host1"
would return would return
<coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0; <coap://[2001:db8:f0::1]/temp>;rt=temperature;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0; <coap://[2001:db8:f0::1]/light>;rt=light-lux;ct=0;
anchor="coap://[2001:db8:f0::1]", anchor="coap://[2001:db8:f0::1]",
<coap://[2001:db8:f0::1]/t>; <coap://[2001:db8:f0::1]/t>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate, anchor="coap://[2001:db8:f0::1]/sensors/temp";rel=alternate,
<http://www.example.com/sensors/t123>; <http://www.example.com/sensors/t123>;
anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby" anchor="coap://[2001:db8:f0::1]/sensors/temp";rel="describedby"
All the target and anchor references are already in absolute form All the target and anchor references are already in absolute form
there, which don't need to be resolved any further. there, which don't need to be resolved any further.
Had the simple host registered with a base= parameter (e.g. Had the simple host done an equivalent full registration with a base=
"?ep=simple-host1&base=coap+tcp://simple-host1.example.com"), that parameter (e.g. "?ep=simple-host1&base=coap+tcp://simple-
context would have been used to resolve the relative anchor values host1.example.com"), that context would have been used to resolve the
instead, giving relative anchor values instead, giving
<coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0; <coap+tcp://simple-host1.example.com/temp>;rt=temperature;ct=0;
anchor="coap+tcp://simple-host1.example.com" anchor="coap+tcp://simple-host1.example.com"
and analogous records. and analogous records.
B.4. A note on differences between link-format and Link headers B.4. A note on differences between link-format and Link headers
While link-format and Link headers look very similar and are based on While link-format and Link headers look very similar and are based on
the same model of typed links, there are some differences between the same model of typed links, there are some differences between
skipping to change at page 78, line 29 skipping to change at page 79, line 9
interpretation only affect links where the absent anchor attribute interpretation only affect links where the absent anchor attribute
means "coap://host/" according to RFC6690 and "coap://host/.well- means "coap://host/" according to RFC6690 and "coap://host/.well-
known/core" according to Modernized Link format; those typically only known/core" according to Modernized Link format; those typically only
occur in conjunction with the vaguely defined implicit "hosts" occur in conjunction with the vaguely defined implicit "hosts"
relationship. relationship.
D.1. For endpoint developers D.1. For endpoint developers
When developing endpoints, i.e. when generating documents that will When developing endpoints, i.e. when generating documents that will
be submitted to a Resource Directory, the differences between be submitted to a Resource Directory, the differences between
Modernized Link Format and RFC6690 can be ignored as long as all Modernized Link Format and RFC6690 can be ignored as long as
relative references start with a slash, and any of the following
applies: o all relative references start with a slash,
and any of the following applies:
o There is no anchor attribute, and the context of the link does not o There is no anchor attribute, and the context of the link does not
matter to the application. matter to the application.
Example: "</sensors>;ct=40" Example: "</sensors>;ct=40"
o The anchor is a relative reference. o The anchor is a relative reference.
Example: "</t>;anchor="/sensors/temp";rel="alternate" Example: "</t>;anchor="/sensors/temp";rel="alternate""
o The target is an absolute reference. o The target is an absolute reference.
Example: "<http://www.example.com/sensors/t123>;anchor="/sensors/ Example: "<http://www.example.com/sensors/t123>;anchor="/sensors/
temp";rel="describedby"" temp";rel="describedby""
D.2. Examples of links with differing interpretations
Examples of links with different interpretations from either applying
RFC6690 or Modernized Link Format are shown here. The example is
assumed to be obtained from a </device/index> document.
o "<sensors>": The target is "/sensors" in RFC6690 and "/device/
sensors" in Modernized Link Format (whereas "</sensors>" would be
unambiguous).
o "<?which=these>": The target is "/?which=these" in RFC6690 and
"/device/index?which=these" in Modernized Link Format.
o "<sensors>;anchor="http://example.com/calib-
proto/1234";rel="topic"" is about "http://example.com/sensors" in
RFC6690 and about "/device/sensors" in Modernized Link Format.
This link can not be expressed in RFC6690 link format without the
server explicitly expressing most of its own URI (which is
problematic in reverse proxy scenarios or when the Uri-Host option
is not sent).
o "</i>;rel="alternate";anchor=""": According to RFC6690, this
states that the "/" resource has an alternative representation at
"/i", whereas Modernized Link Format says that "/devices/index"
has an alternative representation at "/i".
The "anchor" attribute is usually left out; the link
"</i>;rel="alternate"" is equivalent to the above and results in
the same interpretations.
Authors' Addresses Authors' Addresses
Zach Shelby Zach Shelby
ARM ARM
150 Rose Orchard 150 Rose Orchard
San Jose 95134 San Jose 95134
USA USA
Phone: +1-408-203-9434 Phone: +1-408-203-9434
Email: zach.shelby@arm.com Email: zach.shelby@arm.com
Michael Koster Michael Koster
 End of changes. 31 change blocks. 
57 lines changed or deleted 132 lines changed or added

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