draft-ietf-core-resource-directory-09.txt   draft-ietf-core-resource-directory-10.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: May 4, 2017 SmartThings Expires: September 14, 2017 SmartThings
C. Bormann C. Bormann
Universitaet Bremen TZI Universitaet Bremen TZI
P. van der Stok P. van der Stok
consultant consultant
October 31, 2016 March 13, 2017
CoRE Resource Directory CoRE Resource Directory
draft-ietf-core-resource-directory-09 draft-ietf-core-resource-directory-10
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
descriptions of resources held on other servers, allowing lookups to descriptions 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 in order for web interfaces that a Resource Directory supports in order for web
skipping to change at page 1, line 44 skipping to change at page 1, line 44
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 May 4, 2017. This Internet-Draft will expire on September 14, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5 3. Architecture and Use Cases . . . . . . . . . . . . . . . . . 5
3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6 3.1. Use Case: Cellular M2M . . . . . . . . . . . . . . . . . 6
3.2. Use Case: Home and Building Automation . . . . . . . . . 7 3.2. Use Case: Home and Building Automation . . . . . . . . . 7
3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7 3.3. Use Case: Link Catalogues . . . . . . . . . . . . . . . . 7
4. Finding a Directory Server . . . . . . . . . . . . . . . . . 8 4. Finding a Resource Directory . . . . . . . . . . . . . . . . 8
4.1. Resource Directory Address Option (RDAO) . . . . . . . . 9 4.1. Resource Directory Address Option (RDAO) . . . . . . . . 9
5. Simple Registration . . . . . . . . . . . . . . . . . . . . . 10 5. Resource Directory . . . . . . . . . . . . . . . . . . . . . 10
5.1. Simple publishing to Resource Directory Server . . . . . 11 5.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 11
5.2. Third-party registration . . . . . . . . . . . . . . . . 12 5.2. Base URI Discovery . . . . . . . . . . . . . . . . . . . 11
6. Resource Directory Function Set . . . . . . . . . . . . . . . 12 5.3. Registration . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Content Formats . . . . . . . . . . . . . . . . . . . . . 13 5.3.1. Simple Registration . . . . . . . . . . . . . . . . . 16
6.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 13 5.3.2. Simple publishing to Resource Directory Server . . . 17
6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 15 5.3.3. Third-party registration . . . . . . . . . . . . . . 17
6.4. Registration Update . . . . . . . . . . . . . . . . . . . 18 5.3.4. Plurality of link references in a Registration . . . 18
6.5. Registration Removal . . . . . . . . . . . . . . . . . . 20 5.4. Operations on the Registration Resource . . . . . . . . . 18
6.6. Read Endpoint Links . . . . . . . . . . . . . . . . . . . 21 5.4.1. Registration Update . . . . . . . . . . . . . . . . . 19
6.7. Update Endpoint Links . . . . . . . . . . . . . . . . . . 22 5.4.2. Registration Removal . . . . . . . . . . . . . . . . 21
7. Group Function Set . . . . . . . . . . . . . . . . . . . . . 24 5.4.3. Read Endpoint Links . . . . . . . . . . . . . . . . . 22
7.1. Register a Group . . . . . . . . . . . . . . . . . . . . 24 5.4.4. Update Endpoint Links . . . . . . . . . . . . . . . . 23
7.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 26 6. RD Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8. RD Lookup Function Set . . . . . . . . . . . . . . . . . . . 27 6.1. Register a Group . . . . . . . . . . . . . . . . . . . . 27
9. New Link-Format Attributes . . . . . . . . . . . . . . . . . 32 6.2. Group Removal . . . . . . . . . . . . . . . . . . . . . . 29
9.1. Resource Instance attribute 'ins' . . . . . . . . . . . . 32 7. RD Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.2. Export attribute 'exp' . . . . . . . . . . . . . . . . . 33 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35
10. DNS-SD Mapping . . . . . . . . . . . . . . . . . . . . . . . 33 8.1. Endpoint Identification and Authentication . . . . . . . 35
10.1. DNS-based Service discovery . . . . . . . . . . . . . . 33 8.2. Access Control . . . . . . . . . . . . . . . . . . . . . 35
10.2. mapping ins to <Instance> . . . . . . . . . . . . . . . 34 8.3. Denial of Service Attacks . . . . . . . . . . . . . . . . 36
10.3. Mapping rt to <ServiceType> . . . . . . . . . . . . . . 35 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
10.4. Domain mapping . . . . . . . . . . . . . . . . . . . . . 35 9.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 36
10.5. TXT Record key=value strings . . . . . . . . . . . . . . 35 9.2. IPv6 ND Resource Directory Address Option . . . . . . . . 36
10.6. Importing resource links into DNS-SD . . . . . . . . . . 36 9.3. RD Parameter Registry . . . . . . . . . . . . . . . . . . 36
11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 37
11.1. Endpoint Identification and Authentication . . . . . . . 37 10.1. Lighting Installation . . . . . . . . . . . . . . . . . 37
11.2. Access Control . . . . . . . . . . . . . . . . . . . . . 37 10.1.1. Installation Characteristics . . . . . . . . . . . . 38
11.3. Denial of Service Attacks . . . . . . . . . . . . . . . 37 10.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 39
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 10.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 42
12.1. Resource Types . . . . . . . . . . . . . . . . . . . . . 38 10.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 42
12.2. Link Extension . . . . . . . . . . . . . . . . . . . . . 38 10.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 44
12.3. IPv6 ND Resource Directory Address Option . . . . . . . 38 10.2.3. LWM2M Update Endpoint Registration . . . . . . . . . 45
12.4. RD Parameter Registry . . . . . . . . . . . . . . . . . 38 10.2.4. LWM2M De-Register Endpoint . . . . . . . . . . . . . 46
13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 39 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
13.1. Lighting Installation . . . . . . . . . . . . . . . . . 39 12. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 46
13.1.1. Installation Characteristics . . . . . . . . . . . . 40 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
13.1.2. RD entries . . . . . . . . . . . . . . . . . . . . . 41 13.1. Normative References . . . . . . . . . . . . . . . . . . 50
13.1.3. DNS entries . . . . . . . . . . . . . . . . . . . . 44 13.2. Informative References . . . . . . . . . . . . . . . . . 51
13.2. OMA Lightweight M2M (LWM2M) Example . . . . . . . . . . 44 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51
13.2.1. The LWM2M Object Model . . . . . . . . . . . . . . . 45
13.2.2. LWM2M Register Endpoint . . . . . . . . . . . . . . 46
13.2.3. Alternate Base URI . . . . . . . . . . . . . . . . . 48
13.2.4. LWM2M Update Endpoint Registration . . . . . . . . . 48
13.2.5. LWM2M De-Register Endpoint . . . . . . . . . . . . . 48
14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
15. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 49
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 52
16.1. Normative References . . . . . . . . . . . . . . . . . . 52
16.2. Informative References . . . . . . . . . . . . . . . . . 53
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54
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 5, line 11 skipping to change at page 4, line 48
All groups within a domain are unique. All groups within a domain are unique.
Endpoint Endpoint
Endpoint (EP) is a term used to describe a web server or client in Endpoint (EP) is a term used to describe a web server or client in
[RFC7252]. In the context of this specification an endpoint is [RFC7252]. In the context of this specification an endpoint is
used to describe a web server that registers resources to the used to describe a web server that registers resources to the
Resource Directory. An endpoint is identified by its endpoint Resource Directory. An endpoint is identified by its endpoint
name, which is included during registration, and is unique within name, which is included during registration, and is unique within
the associated domain of the registration. the associated domain of the registration.
Context
When registering links to a Resource Directory, the Context refers
to the scheme, address, port, and base path for all the links
registered on behalf of an endpoint, of the general form
scheme://host:port/path/ where the client may explicitly set the
scheme and host, and may supply the port and path as optional
parameters. When the context of a registration is explicitly set,
the URI resolution rules in [RFC3986] MUST be applied.
Commissioning Tool Commissioning Tool
Commissioning Tool (CT) is a device that assists during the Commissioning Tool (CT) is a device that assists during the
installation of the network by assigning values to parameters, installation of the network by assigning values to parameters,
naming endpoints and groups, or adapting the installation to the naming endpoints and groups, or adapting the installation to the
needs of the applications. needs of the applications.
RDAO RDAO
Resource Directory Address Option. Resource Directory Address Option.
3. Architecture and Use Cases 3. Architecture and Use Cases
The resource directory architecture is illustrated in Figure 1. A The resource directory architecture is illustrated in Figure 1. A
Resource Directory (RD) is used as a repository for Web Links Resource Directory (RD) is used as a repository for Web Links
[RFC5988] about resources hosted on other web servers, which are [RFC5988] about resources hosted on other web servers, which are
called endpoints (EP). An endpoint is a web server associated with a called endpoints (EP). An endpoint is a web server associated with a
scheme, IP address and port (called Context), thus a physical node scheme, IP address and port (called Context), thus a physical node
may host one or more endpoints. The RD implements a set of REST may host one or more endpoints. The RD implements a set of REST
interfaces for endpoints to register and maintain sets of Web Links interfaces for endpoints to register and maintain sets of Web Links
(called resource directory entries), and for clients to lookup (called resource directory registration entries), and for clients to
resources from the RD or maintain groups. Endpoints themselves can lookup resources from the RD or maintain groups. Endpoints
also act as clients. An RD can be logically segmented by the use of themselves can also act as clients. An RD can be logically segmented
Domains. The domain an endpoint is associated with can be defined by by the use of Domains. The domain an endpoint is associated with can
the RD or configured by an outside entity. This information be defined by the RD or configured by an outside entity. This
hierarchy is shown in Figure 2. information hierarchy is shown in Figure 2.
Endpoints are assumed to proactively register and maintain resource A mechanism to discover an RD using CoRE Link Format [RFC6690] is
directory entries on the RD, which are soft state and need to be defined.
periodically refreshed. An endpoint is provided with interfaces to
register, update and remove a resource directory entry. Furthermore, Endpoints proactively register and maintain resource directory
a mechanism to discover an RD using the CoRE Link Format [RFC6690] is registration entries on the RD, which are soft state and need to be
defined. It is also possible for an RD to proactively discover Web periodically refreshed.
Links from endpoints and add them as resource directory entries. A
lookup interface for discovering any of the Web Links held in the RD An endpoint is provided with interfaces to register, update and
is provided using the CoRE Link Format. remove a resource directory registration entry. It is also possible
for an RD to fetch Web Links from endpoints and add them as resource
directory entries.
At the first registration of a set of entries, a "registration
resource" is created, the location of which is returned to the
registering endpoint. The registering endpoint uses this
registration resource to manage the contents of the registration
entry.
A lookup interface for discovering any of the Web Links held in the
RD is provided using the CoRE Link Format.
Registration Lookup, Group Registration Lookup, Group
Interface Interfaces Interface Interfaces
+----+ | | +----+ | |
| EP |---- | | | EP |---- | |
+----+ ---- | | +----+ ---- | |
--|- +------+ | --|- +------+ |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
| EP | ---------|-----| RD |----|-----| Client | | EP | ---------|-----| RD |----|-----| Client |
+----+ | ----| | | +--------+ +----+ | ----| | | +--------+
skipping to change at page 7, line 41 skipping to change at page 7, line 44
Home and commercial building automation systems can benefit from the Home and commercial building automation systems can benefit from the
use of M2M web services. The discovery requirements of these use of M2M web services. The discovery requirements of these
applications are demanding. Home automation usually relies on run- applications are demanding. Home automation usually relies on run-
time discovery to commission the system, whereas in building time discovery to commission the system, whereas in building
automation a combination of professional commissioning and run-time automation a combination of professional commissioning and run-time
discovery is used. Both home and building automation involve peer- discovery is used. Both home and building automation involve peer-
to-peer interactions between endpoints, and involve battery-powered to-peer interactions between endpoints, and involve battery-powered
sleeping devices. sleeping devices.
The exporting of resource information to other discovery systems is
also important in these automation applications. In home automation
there is a need to interact with other consumer electronics, which
may already support DNS-SD, and in building automation DNS-SD in
combination with resource directories can cover multiple buildings.
3.3. Use Case: Link Catalogues 3.3. Use Case: Link Catalogues
Resources may be shared through data brokers that have no knowledge Resources may be shared through data brokers that have no knowledge
beforehand of who is going to consume the data. Resource Directory beforehand of who is going to consume the data. Resource Directory
can be used to hold links about resources and services hosted can be used to hold links about resources and services hosted
anywhere to make them discoverable by a general class of anywhere to make them discoverable by a general class of
applications. applications.
For example, environmental and weather sensors that generate data for For example, environmental and weather sensors that generate data for
public consumption may provide the data to an intermediary server, or public consumption may provide the data to an intermediary server, or
broker. Sensor data are published to the intermediary upon changes broker. Sensor data are published to the intermediary upon changes
or at regular intervals. Descriptions of the sensors that resolve to or at regular intervals. Descriptions of the sensors that resolve to
links to sensor data may be published to a Resource Directory. links to sensor data may be published to a Resource Directory.
Applications wishing to consume the data can use the Resource Applications wishing to consume the data can use RD Lookup to
Directory lookup function set to discover and resolve links to the discover and resolve links to the desired resources and endpoints.
desired resources and endpoints. The Resource Directory service need The Resource Directory service need not be coupled with the data
not be coupled with the data intermediary service. Mapping of intermediary service. Mapping of Resource Directories to data
Resource Directories to data intermediaries may be many-to-many. intermediaries may be many-to-many.
Metadata in web-link compatible representations are supplied by Metadata in web link formats like [RFC6690] are supplied by Resource
Resource Directories, which may be internally stored as triples, or Directories, which may be internally stored as triples, or relation/
relation/attribute pairs providing metadata about resource links. attribute pairs providing metadata about resource links. External
External catalogs that are represented in other formats may be catalogs that are represented in other formats may be converted to
converted to common web linking formats for storage and access by common web linking formats for storage and access by Resource
Resource Directories. Since it is common practice for these to be Directories. Since it is common practice for these to be URN
URN encoded, simple and lossless structural transforms should encoded, simple and lossless structural transforms should generally
generally be sufficient to store external metadata in Resource be sufficient to store external metadata in Resource Directories.
Directories.
The additional features of Resource Directory allow domains to be The additional features of Resource Directory allow domains to be
defined to enable access to a particular set of resources from defined to enable access to a particular set of resources from
particular applications. This provides isolation and protection of particular applications. This provides isolation and protection of
sensitive data when needed. Resource groups may defined to allow sensitive data when needed. Resource groups may defined to allow
batched reads from multiple resources. batched reads from multiple resources.
4. Finding a Directory Server 4. Finding a Resource Directory
Endpoints that want to contact a directory server can obtain Several mechanisms can be employed for discovering the RD, including
candidate IP addresses for such servers in a number of ways. assuming a default location (e.g. on an Edge Router in a LoWPAN),
assigning an anycast address to the RD, using DHCP, or discovering
the RD using .well-known/core and hyperlinks as specified in CoRE
Link Format [RFC6690]. Endpoints that want to contact a Resource
Directory can obtain candidate IP addresses for such servers in a
number of ways.
In a 6LoWPAN, good candidates can be taken from: In a 6LoWPAN, good candidates can be taken from:
o specific static configuration (e.g., anycast addresses), if any, o specific static configuration (e.g., anycast addresses), if any,
o the ABRO option of 6LoWPAN-ND [RFC6775], o the ABRO option of 6LoWPAN-ND [RFC6775],
o other ND options that happen to point to servers (such as RDNSS), o other ND options that happen to point to servers (such as RDNSS),
o DHCPv6 options that might be defined later. o DHCPv6 options that might be defined later.
o The IPv6 Neighbor Discovery Resource Directory Address Option o The IPv6 Neighbor Discovery Resource Directory Address Option
described in Section 4.1 described in Section 4.1
In networks with more inexpensive use of multicast, the candidate IP In networks with more inexpensive use of multicast, the candidate IP
address may be a well-known multicast address, i.e. directory servers address may be a well-known multicast address, i.e. directory servers
are found by simply sending GET requests to that well-known multicast are found by simply sending GET requests to that well-known multicast
address (see Section 6.2). address (see Section 5.2).
Constrained nodes configured in large batches may be configured for
an anycast address for the RD. Each target network environment in
which some of these preconfigured nodes are to be brought up is then
configured with a route for this anycast address that leads to an RD
that is appropriate for the environment.
As some of these sources are just (more or less educated) guesses, As some of these sources are just (more or less educated) guesses,
endpoints MUST make use of any error messages to very strictly rate- endpoints MUST make use of any error messages to very strictly rate-
limit requests to candidate IP addresses that don't work out. For limit requests to candidate IP addresses that don't work out. For
example, an ICMP Destination Unreachable message (and, in particular, example, an ICMP Destination Unreachable message (and, in particular,
the port unreachable code for this message) may indicate the lack of the port unreachable code for this message) may indicate the lack of
a CoAP server on the candidate host, or a CoAP error response code a CoAP server on the candidate host, or a CoAP error response code
such as 4.05 "Method Not Allowed" may indicate unwillingness of a such as 4.05 "Method Not Allowed" may indicate unwillingness of a
CoAP server to act as a directory server. CoAP server to act as a directory server.
skipping to change at page 10, line 32 skipping to change at page 10, line 32
Type: 38 Type: 38
Length: 8-bit unsigned integer. The length of Length: 8-bit unsigned integer. The length of
the option in units of 8 bytes. the option in units of 8 bytes.
Always 3. Always 3.
Valid Lifetime: 16-bit unsigned integer. The length of Valid Lifetime: 16-bit unsigned integer. The length of
time in units of 60 seconds (relative to time in units of 60 seconds (relative to
the time the packet is received) that the time the packet is received) that
this set of border router information is this Resource Directory address is valid.
valid. A value of all zero bits (0x0) A value of all zero bits (0x0) indicates
assumes a default value of 10,000 that this Resource Directory address
(~one week). is not valid anymore.
Reserved: This field is unused. It MUST be Reserved: This field is unused. It MUST be
initialized to zero by the sender and initialized to zero by the sender and
MUST be ignored by the receiver. MUST be ignored by the receiver.
RD Address: IPv6 address of the RD. RD Address: IPv6 address of the RD.
Figure 3: Resource Directory Address Option Figure 3: Resource Directory Address Option
5. Simple Registration 5. Resource Directory
Not all endpoints hosting resources are expected to know how to
implement the Resource Directory Function Set (see Section 6) hence
cannot register with a Resource Directory. Instead, simple endpoints
can implement the generic Simple Directory Discovery approach
described in this section. An RD implementing this specification
MUST implement Simple Directory Discovery. However, there may be
security reasons why this form of directory discovery would be
disabled.
This approach requires that the endpoint makes available the hosted
resources that it wants to be discovered, as links on its "/.well-
known/core" interface as specified in [RFC6690].
The endpoint then finds one or more addresses of the directory server
as described in Section 4.
An endpoint can send (a selection of) hosted resources to a directory
server for publication as described in Section 5.1.
The directory server integrates the information it received this way
into its resource directory. It MAY make the information available
to further directories, if it can ensure that a loop does not form.
The protocol used between directories to ensure loop-free operation
is outside the scope of this document.
5.1. Simple publishing to Resource Directory Server
An endpoint that wants to make itself discoverable occasionally sends
a POST request to the "/.well-known/core" URI of any candidate
directory server that it finds. The body of the POST request is
empty, which triggers the resource directory server to perform GET
requests at the requesting server's default discovery URI to obtain
the link-format payload to register.
The endpoint MAY include registration parameters in the POST request
as per Section 6.3.
The following example shows an endpoint using simple publishing, by
simply sending an empty POST to a resource directory.
Req:(to RD server from [ff02::1])
POST coap://rd.example.com/.well-known/core?lt=6000
Content-Format: 40
payload:
(empty payload)
Res: 2.04 Changed
(later)
Req: (from RD server to [ff02::1])
GET coap://[ff02::1]/.well-known/core
Accept: 40
Res: 2.05 Content
payload:
</sen/temp>
5.2. Third-party registration
For some applications, even Simple Directory Discovery may be too
taxing for certain very constrained devices, in particular if the
security requirements become too onerous.
In a controlled environment (e.g. building control), the Resource
Directory can be filled by a third device, called a commissioning
tool. The commissioning tool can fill the Resource Directory from a
database or other means. For that purpose the scheme, IP address and
port of the registered device is indicated in the Context parameter
of the registration described in Section 6.3.
6. Resource Directory Function Set
This section defines the REST interfaces between an RD and endpoints, This section defines the required set of REST interfaces between a
which is called the Resource Directory Function Set. Although the Resource Directory (RD) and endpoints. Although the examples
examples throughout this section assume the use of CoAP [RFC7252], throughout this section assume the use of CoAP [RFC7252], these REST
these REST interfaces can also be realized using HTTP [RFC7230]. In interfaces can also be realized using HTTP [RFC7230]. In all
all definitions in this section, both CoAP response codes (with dot definitions in this section, both CoAP response codes (with dot
notation) and HTTP response codes (without dot notation) are shown. notation) and HTTP response codes (without dot notation) are shown.
An RD implementing this specification MUST support the discovery, An RD implementing this specification MUST support the discovery,
registration, update, lookup, and removal interfaces defined in this registration, update, lookup, and removal interfaces defined in this
section. section.
Resource directory entries are designed to be easily exported to 5.1. Content Formats
other discovery mechanisms such as DNS-SD. For that reason,
parameters that would meaningfully be mapped to DNS SHOULD be limited
to a maximum length of 63 bytes.
6.1. Content Formats
Resource Directory implementations using this specification MUST Resource Directory implementations using this specification MUST
support the application/link-format content format (ct=40). support the application/link-format content format (ct=40).
Resource Directories implementing this specification MAY support Resource Directories implementing this specification MAY support
additional content formats. additional content formats.
Any additional content format supported by a Resource Directory Any additional content format supported by a Resource Directory
implementing this specification MUST have an equivalent serialization implementing this specification MUST have an equivalent serialization
in the application/link-format content format. in the application/link-format content format.
6.2. Discovery 5.2. Base URI Discovery
Before an endpoint can make use of an RD, it must first know the RD's Before an endpoint can make use of an RD, it must first know the RD's
address and port, and the path of its RD Function Set. There can be address and port, and the base URI information for its REST API.
several mechanisms for discovering the RD including assuming a This section defines discovery of the RD and its base URI using the
default location (e.g. on an Edge Router in a LoWPAN), by assigning well-known interface of the CoRE Link Format [RFC6690]. It is
an anycast address to the RD, using DHCP, or by discovering the RD however expected that RDs will also be discoverable via other methods
using the CoRE Link Format (see also Section 4). This section
defines discovery of the RD using the well-known interface of the
CoRE Link Format [RFC6690] as the required mechanism. It is however
expected that RDs will also be discoverable via other methods
depending on the deployment. depending on the deployment.
Discovery of the RD function set is performed by sending either a Discovery of the RD base URI is performed by sending either a
multicast or unicast GET request to "/.well-known/core" and including multicast or unicast GET request to "/.well-known/core" and including
a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in a Resource Type (rt) parameter [RFC6690] with the value "core.rd" in
the query string. Likewise, a Resource Type parameter value of the query string. Likewise, a Resource Type parameter value of
"core.rd-lookup" is used to discover the RD Lookup Function Set. "core.rd-lookup*" is used to discover the base URI for RD Lookup
Upon success, the response will contain a payload with a link format operations, and "core.gp" is used to discover the base URI for RD
entry for each RD discovered, with the URL indicating the root Group operations. Upon success, the response will contain a payload
resource of the RD. When performing multicast discovery, the with a link format entry for each RD function discovered, indicating
multicast IP address used will depend on the scope required and the the base URI of the RD function returned and the corresponding
multicast capabilities of the network. Resource Type. When performing multicast discovery, the multicast IP
address used will depend on the scope required and the multicast
capabilities of the network.
A Resource Directory MAY provide hints about the content-formats it A Resource Directory MAY provide hints about the content-formats it
supports in the links it exposes or registers, using the "ct" link supports in the links it exposes or registers, using the "ct" link
attribute, as shown in the example below. Clients MAY use these attribute, as shown in the example below. Clients MAY use these
hints to select alternate content-formats for interaction with the hints to select alternate content-formats for interaction with the
Resource Directory. Resource Directory.
HTTP does not support multicast and consequently only unicast HTTP does not support multicast and consequently only unicast
discovery can be supported using HTTP. Links to Resource Directories discovery can be supported using HTTP. Links to Resource Directories
MAY be registered in other Resource Directories, and well-known entry MAY be registered in other Resource Directories, and well-known entry
skipping to change at page 14, line 24 skipping to change at page 12, line 20
The discovery request interface is specified as follows: The discovery request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: GET Method: GET
URI Template: /.well-known/core{?rt} URI Template: /.well-known/core{?rt}
URI Template Variables: URI Template Variables:
rt := Resource Type (optional). MAY contain one or more of the rt := Resource Type (optional). MAY contain one of the values
values "core.rd", "core.rd-lookup", "core.rd-group" or "core.rd", "core.rd-lookup*", "core.rd-lookup-d", "core.rd-
"core.rd*" lookup-res", "core.rd-lookup-ep", "core.rd-lookup-gp",
"core.rd-group" or "core.rd*"
Content-Format: application/link-format (if any) Content-Format: application/link-format (if any)
Content-Format: application/link-format+json (if any) Content-Format: application/link-format+json (if any)
Content-Format: application/link-format+cbor (if any) Content-Format: application/link-format+cbor (if any)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.05 "Content" with an application/link-format, Success: 2.05 "Content" with an application/link-format,
skipping to change at page 15, line 4 skipping to change at page 12, line 50
Failure: 4.00 "Bad Request" is returned in case of a malformed Failure: 4.00 "Bad Request" is returned in case of a malformed
request for a unicast request. request for a unicast request.
Failure: No error response to a multicast request. Failure: No error response to a multicast request.
HTTP support : YES (Unicast only) HTTP support : YES (Unicast only)
The following example shows an endpoint discovering an RD using this The following example shows an endpoint discovering an RD using this
interface, thus learning that the base RD resource is, in this interface, thus learning that the base RD resource is, in this
example, at /rd and that the content_format delivered by the server example, at /rd and that the content-format delivered by the server
hosting the resource is application.xml (ct=40). Note that it is up hosting the resource is application/link-format (ct=40). Note that
to the RD to choose its base RD resource, although diagnostics and it is up to the RD to choose its base RD resource, although
debugging is facilitated by using the base paths specified here where diagnostics and debugging is facilitated by using the base paths
possible. specified here where possible.
Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*
Res: 2.05 Content Res: 2.05 Content
</rd>;rt="core.rd";ct=40, </rd>;rt="core.rd";ct=40,
</rd-lookup>;rt="core.rd-lookup";ct=40, </rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40,
</rd-lookup/res>;rt="core.rd-lookup-res";ct="40",
</rd-group>;rt="core.rd-group";ct=40 </rd-group>;rt="core.rd-group";ct=40
The following example shows the way of indicating that a client may The following example shows the way of indicating that a client may
request alternate content-formats. The Content-Format code attribute request alternate content-formats. The Content-Format code attribute
"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 a Content-Format 40 (application/link-format) indicated as well as a
more application-specific content format (picked as 65225 in this more application-specific content format (picked as 65225 in this
example; this is in the experimental space, not an assigned value). example; this is in the experimental space, not an assigned value).
The base RD resource values /rd, /rd-lookup, and /rd-group are The base RD resource values /rd, /rd-lookup, and /rd-group are
example values. example values.
Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* Req: GET coap://[ff02::1]/.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>;rt="core.rd-lookup";ct="40 65225", </rd-lookup/res>;rt="core.rd-lookup-res";ct="40 65225",
</rd-lookup/ep>;rt="core.rd-lookup-ep";ct="40 65225",
</rd-group>;rt="core.rd-group";ct="40 65225" </rd-group>;rt="core.rd-group";ct="40 65225"
6.3. Registration 5.3. Registration
After discovering the location of an RD Function Set, an endpoint MAY After discovering the location of an RD, an endpoint MAY register its
register its resources using the registration interface. This resources using the registration interface. This interface accepts a
interface accepts a POST from an endpoint containing the list of POST from an endpoint containing the list of resources to be added to
resources to be added to the directory as the message payload in the the directory as the message payload in the CoRE Link Format
CoRE Link Format [RFC6690], JSON CoRE Link Format (application/link- [RFC6690], JSON CoRE Link Format (application/link-format+json), or
format+json), or CBOR CoRE Link Format (application/link-format+cbor) CBOR CoRE Link Format (application/link-format+cbor)
[I-D.ietf-core-links-json], along with query string parameters [I-D.ietf-core-links-json], along with query parameters indicating
indicating the name of the endpoint, its domain and the lifetime of the name of the endpoint, and optionally its domain and the lifetime
the registration. All parameters except the endpoint name are of the registration. It is expected that other specifications will
optional. It is expected that other specifications will define define further parameters (see Section 9.3). The RD then creates a
further parameters (see Section 12.4). The RD then creates a new new registration resource in the RD and returns its location. An
resource or updates an existing resource in the RD and returns its endpoint MUST use that location when refreshing registrations using
location. An endpoint MUST use that location when refreshing this interface. Endpoint resources in the RD are kept active for the
registrations using this interface. Endpoint resources in the RD are period indicated by the lifetime parameter. The endpoint is
kept active for the period indicated by the lifetime parameter. The responsible for refreshing the entry within this period using either
endpoint is responsible for refreshing the entry within this period the registration or update interface. The registration interface
using either the registration or update interface. The registration MUST be implemented to be idempotent, so that registering twice with
interface MUST be implemented to be idempotent, so that registering the same endpoint parameters ep and d does not create multiple RD
twice with the same endpoint parameter does not create multiple RD
entries. A new registration may be created at any time to supersede entries. A new registration may be created at any time to supersede
an existing registration, replacing the registration parameters and an existing registration, replacing the registration parameters and
links. links.
The registration request interface is specified as follows: The registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+rd}{?ep,d,et,lt,con} URI Template: /{+rd}{?ep,d,et,lt,con}
URI Template Variables: URI Template Variables:
rd := RD Function Set path (mandatory). This is the path of the rd := RD Base URI path (mandatory). This is the path of the RD,
RD Function Set, as obtained from discovery. The value "rd" is as obtained from discovery. The value "rd" is recommended for
recommended for this variable. this variable.
ep := Endpoint name (mandatory). The endpoint name is an ep := Endpoint name (mandatory). The endpoint name is an
identifier that MUST be unique within a domain. The maximum identifier that MUST be unique within a domain. The maximum
length of this parameter is 63 bytes. length of this parameter is 63 bytes.
d := Domain (optional). The domain to which this endpoint d := Domain (optional). The domain to which this endpoint
belongs. The maximum length of this parameter is 63 bytes. belongs. The maximum length of this parameter is 63 bytes.
When this parameter is elided, the RD MAY associate the When this parameter is elided, the RD MAY associate the
endpoint with a configured default domain. The domain value is endpoint with a configured default domain.
needed to export the endpoint to DNS-SD (see Section 10).
et := Endpoint Type (optional). The semantic type of the et := Endpoint Type (optional). The semantic type of the
endpoint. This parameter SHOULD be less than 63 bytes. endpoint. This parameter SHOULD be less than 63 bytes.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the registration in
seconds. Range of 60-4294967295. If no lifetime is included, seconds. Range of 60-4294967295. If no lifetime is included
a default value of 86400 (24 hours) SHOULD be assumed. in the initial registration, a default value of 86400 (24
hours) SHOULD be assumed. If the lt parameter is not included
in a registration refresh or update operation, the most
recently supplied value SHALL be re-used.
con := Context (optional). This parameter sets the scheme, con := Context (optional). This parameter sets the scheme,
address and port at which this server is available in the form address and port at which this server is available in the form
scheme://host:port. In the absence of this parameter the scheme://host:port/path. In the absence of this parameter the
scheme of the protocol, source IP address and source port of scheme of the protocol, source address and source port of the
the register request are assumed. This parameter is mandatory register request are assumed. This parameter is mandatory when
when the directory is filled by a third party such as an the directory is filled by a third party such as an
commissioning tool. commissioning tool. When con is used, scheme and host are
mandatory and port and path parameters are optional. If the
endpoint uses an ephemeral port to register with, it MUST
include the con: parameter in the registration to provide a
valid network path. If the endpoint which is located behind a
NAT gateway is registering with a Resource Directory which is
on the network service side of the NAT gateway, the endpoint
MUST use a persistent port for the outgoing registration in
order to provide the NAT gateway with a valid network address
for replies and incoming requests.
Content-Format: application/link-format Content-Format: application/link-format
Content-Format: application/link-format+json Content-Format: application/link-format+json
Content-Format: application/link-format+cbor Content-Format: application/link-format+cbor
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.01 "Created" or 201 "Created". The Location header MUST Success: 2.01 "Created" or 201 "Created". The Location header
be included with the new resource entry for the endpoint. This option MUST be included in the response when a new registration
Location MUST be a stable identifier generated by the RD as it is resource is created. This Location MUST be a stable identifier
used for all subsequent operations on this registration. The generated by the RD as it is used for all subsequent operations on
resource returned in the Location is for the purpose of updating this registration resource. The registration resource location
the lifetime of the registration and for maintaining the content thus returned is for the purpose of updating the lifetime of the
of the registered links, including updating and deleting links. registration and for maintaining the content of the registered
links, including updating and deleting links.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the
registration content with links resulting in plurality of
references; see Section 5.3.4.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following example shows an endpoint with the name "node1" The following example shows an endpoint with the name "node1"
registering two resources to an RD using this interface. The registering two resources to an RD using this interface. The
location "/rd" is an example value of an RD base location. location "/rd" is an example value of an RD base location.
Req: POST coap://rd.example.com/rd?ep=node1 Req: POST coap://rd.example.com/rd?ep=node1
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
Res: 2.01 Created Res: 2.01 Created
Location: /rd/4521 Location: /rd/4521
A Resource Directory may optionally support HTTP. Here is an example
of the same registration operation above, when done using HTTP.
Req: POST /rd?ep=node1 HTTP/1.1 Req: POST /rd?ep=node1 HTTP/1.1
Host : example.com Host : example.com
Content-Type: application/link-format Content-Type: application/link-format
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
Res: 201 Created Res: 201 Created
Location: /rd/4521 Location: /rd/4521
6.4. Registration Update 5.3.1. Simple Registration
Not all endpoints hosting resources are expected to know how to
upload links to a RD as described in Section 5.3. Instead, simple
endpoints can implement the Simple Registration approach described in
this section. An RD implementing this specification MUST implement
Simple Registration. However, there may be security reasons why this
form of directory discovery would be disabled.
This approach requires that the endpoint makes available the hosted
resources that it wants to be discovered, as links on its "/.well-
known/core" interface as specified in [RFC6690].
The endpoint then finds one or more addresses of the directory server
as described in Section 4.
An endpoint can send (a selection of) hosted resources to a directory
server for publication as described in Section 5.3.2.
The directory server integrates the information it received this way
into its resource directory. It MAY make the information available
to further directories, if it can ensure that a loop does not form.
The protocol used between directories to ensure loop-free operation
is outside the scope of this document.
5.3.2. Simple publishing to Resource Directory Server
An endpoint that wants to make itself discoverable occasionally sends
a POST request to the "/.well-known/core" URI of any candidate
directory server that it finds. The body of the POST request is
empty, which triggers the resource directory server to perform GET
requests at the requesting server's default discovery URI to obtain
the link-format payload to register.
The endpoint MUST include the endpoint name and MAY include the
registration parameters d, lt, and et, in the POST request as per
Section 5.3.
The following example shows an endpoint using simple publishing, by
simply sending an empty POST to a resource directory.
Req:(to RD server from [ff02::1])
POST coap://rd.example.com/.well-known/core?lt=6000;ep=node1
Content-Format: 40
payload:
(empty payload)
Res: 2.04 Changed
(later)
Req: (from RD server to [ff02::1])
GET coap://[ff02::1]/.well-known/core
Accept: 40
Res: 2.05 Content
payload:
</sen/temp>
5.3.3. Third-party registration
For some applications, even Simple Directory Discovery may be too
taxing for certain very constrained devices, in particular if the
security requirements become too onerous.
In a controlled environment (e.g. building control), the Resource
Directory can be filled by a third device, called a commissioning
tool. The commissioning tool can fill the Resource Directory from a
database or other means. For that purpose the scheme, IP address and
port of the registered device is indicated in the Context parameter
of the registration described in Section 5.3.
5.3.4. Plurality of link references in a Registration
Plurality of link references within a Registration (registration
resource) is an indication of some error condition and should not be
allowed.
Plurality of link references exists if, and only if, two or more
links in a Registration contain identical context, target, and
relation values. This condition would be likely to arise if there
were multiple co-ordinators or configuration tools, each with a
different set of configuration values for the same resource.
A Resource Directory SHOULD reject a registration, or an operation on
a registration, which would result in a plurality of link references
within the the context of the registration. There is no requirement
in this document for a resource directory to check for plurality of
reference between different registrations. Resource Directory
operations which are rejected due to reference plurality SHOULD be
returned the "Conflict" code, indicating that there is someting wrong
with the request.
5.4. Operations on the Registration Resource
After the initial registration, an endpoint should retain the
returned location of the Registration Resource for further
operations, including refreshing the registration in order to extend
the lifetie and "keep-alive" the registration. If the lifetime of
the registration expires, the RD SHOULD NOT respond to discovery
queries with information from the endpoint. The RD SHOULD continue
to provide access to the Registration Resource after a registration
time-out occurs in order to enable the registering endpoint to
eventually refresh the registration. The RD MAY eventually remove
the registration resource for the purpose of resource recovery and
garbage collection. If the Registration Resource is removed, the
endpoint will need to re-register.
The Registration Resource may also be used to inspect the
registration resource using GET, update the registration link
contents using PATCH, or cancel the registration using DELETE.
These operations are described in this section.
In accordance with Section 5.3.4, operations which would result in
plural link references within the context of a registration resource
SHOULD be rejected using the "Conflict" result code.
5.4.1. Registration Update
The update interface is used by an endpoint to refresh or update its The update interface is used by an endpoint to refresh or update its
registration with an RD. To use the interface, the endpoint sends a registration with an RD. To use the interface, the endpoint sends a
POST request to the resource returned in the Location option in the POST request to the registration resource returned in the Location
response to the first registration. header option in the response returned from the intial registration
operation.
An update MAY update the lifetime or context registration parameters An update MAY update the lifetime or context registration parameters
"lt", "con" as in Section 6.3 ) if they have changed since the last "lt", "con" as in Section 5.3 ) if the previous settings are to be
registration or update. Parameters that have not changed SHOULD NOT retained. Parameters that are not being changed changed SHOULD NOT
be included in an update. Adding parameters that have not changed be included in an update. Adding parameters that have not changed
increases the size of the message but does not have any other increases the size of the message but does not have any other
implications. Parameters MUST be included as query parameters in an implications. Parameters MUST be included as query parameters in an
update operation as in Section 6.3. update operation as in Section 5.3.
Upon receiving an update request, an RD MUST reset the timeout for Upon receiving an update request, an RD MUST reset the timeout for
that endpoint and update the scheme, IP address and port of the that endpoint and update the scheme, IP address and port of the
endpoint, using the source address of the update, or the context endpoint, using the source address of the update, or the context
("con") parameter if present. If the lifetime parameter "lt" is ("con") parameter if present. If the lifetime parameter "lt" is
included in the received update request, the RD MUST update the included in the received update request, the RD MUST update the
lifetime of the registration and set the timeout equal to the new lifetime of the registration and set the timeout equal to the new
lifetime. lifetime. If the lifetime parameter is not included in the
registration update, the most recent setting is re-used for the next
registration time-out period.
An update MAY optionally add or replace links for the endpoint by An update MAY optionally add or replace links for the endpoint by
including those links in the payload of the update as a CoRE Link including those links in the payload of the update as a CoRE Link
Format document. A link is replaced only if both the target URI and Format document. A link is replaced only if all of the target URI
relation type match. and relation type (if present) and anchor value (if present) match.
If the link payload is included, it SHOULD be checked for reference
plurality as described in Section 5.3.4 and rejected with a
"Conflict" result if there are plural link references detected.
In addition to the use of POST, as described in this section, there In addition to the use of POST, as described in this section, there
is an alternate way to add, replace, and delete links using PATCH as is an alternate way to add, replace, and delete links using PATCH as
described in Section 6.7. described in Section 5.4.4.
The update registration request interface is specified as follows: The update registration request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: POST Method: POST
URI Template: /{+location}{?lt,con} URI Template: /{+location}{?lt,con}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location path returned by the RD as a
result of a successful earlier registration. result of a successful earlier registration.
lt := Lifetime (optional). Lifetime of the registration in lt := Lifetime (optional). Lifetime of the registration in
seconds. Range of 60-4294967295. If no lifetime is included, seconds. Range of 60-4294967295. If no lifetime is included,
a default value of 86400 (24 hours) SHOULD be assumed. the previous last lifetime set on a previous update or the
original registration (falling back to 86400) SHOULD be used.
con := Context (optional). This parameter sets the scheme, con := Context (optional). This parameter sets the scheme,
address and port at which this server is available in the form address and port at which this server is available in the form
scheme://host:port. Optional. In the absence of this scheme://host:port/path. In the absence of this parameter the
parameter the scheme of the protocol, source IP address and scheme of the protocol, source address and source port of the
source port used to register are assumed. This parameter is register request are assumed. This parameter is mandatory when
compulsory when the directory is filled by a third party such the directory is filled by a third party such as an
as a commissioning tool. commissioning tool. When con is used, scheme and host are
mandatory and port and path parameters are optional.
Content-Format: application/link-format (mandatory) Content-Format: application/link-format (mandatory)
Content-Format: application/link-format+json (optional) Content-Format: application/link-format+json (optional)
Content-Format: application/link-format+cbor (optional) Content-Format: application/link-format+cbor (optional)
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.04 "Changed" or 204 "No Content" if the update was Success: 2.04 "Changed" or 204 "No Content" if the update was
successfully processed. successfully processed.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not Failure: 4.04 "Not Found" or 404 "Not Found". Registration does not
exist (e.g. may have expired). exist (e.g. may have expired).
Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the
registration content with links resulting in plurality of
references; see Section 5.3.4.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following example shows an endpoint updating its registration at The following example shows an endpoint updating its registration at
an RD using this interface with the example location value: /rd/4521. an RD using this interface with the example location value: /rd/4521.
Req: POST /rd/4521 Req: POST /rd/4521
Res: 2.04 Changed Res: 2.04 Changed
The following example shows an endpoint updating its registration The following example shows an endpoint updating its registration
with a new lifetime and context, changing an existing link, and with a new lifetime and context, changing an existing link, and
adding a new link using this interface with the example location adding a new link using this interface with the example location
skipping to change at page 20, line 4 skipping to change at page 21, line 22
with a new lifetime and context, changing an existing link, and with a new lifetime and context, changing an existing link, and
adding a new link using this interface with the example location adding a new link using this interface with the example location
value /rd/4521. With the initial registration the client set the value /rd/4521. With the initial registration the client set the
following values: following values:
o lifetime (lt)=500 o lifetime (lt)=500
o context (con)=coap://local-proxy-old.example.com:5683 o context (con)=coap://local-proxy-old.example.com:5683
o resource= </sensors/temp>;ct=41;rt="foobar";if="sensor" o resource= </sensors/temp>;ct=41;rt="foobar";if="sensor"
Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683" Req: POST /rd/4521?lt=600&con="coap://local-proxy.example.com:5683"
Content-Format: 40 Content-Format: 40
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-f";if="sensor", </sensors/temp>;ct=41;rt="temperature-f";if="sensor",
</sensors/door>;ct=41;rt="door";if="sensor" </sensors/door>;ct=41;rt="door";if="sensor"
Res: 2.04 Changed Res: 2.04 Changed
6.5. Registration Removal 5.4.2. Registration Removal
Although RD entries have soft state and will eventually timeout after Although RD entries have soft state and will eventually timeout after
their lifetime, an endpoint SHOULD explicitly remove its entry from their lifetime, an endpoint SHOULD explicitly remove its entry from
the RD if it knows it will no longer be available (for example on the RD if it knows it will no longer be available (for example on
shut-down). This is accomplished using a removal interface on the RD shut-down). This is accomplished using a removal interface on the RD
by performing a DELETE on the endpoint resource. by performing a DELETE on the endpoint resource.
The removal request interface is specified as follows: The removal request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
skipping to change at page 21, line 9 skipping to change at page 22, line 27
HTTP support: YES HTTP support: YES
The following examples shows successful removal of the endpoint from The following examples shows successful removal of the endpoint from
the RD with example location value /rd/4521. the RD with example location value /rd/4521.
Req: DELETE /rd/4521 Req: DELETE /rd/4521
Res: 2.02 Deleted Res: 2.02 Deleted
6.6. Read Endpoint Links 5.4.3. Read Endpoint Links
Some endpoints may wish to manage their links as a collection, and Some endpoints may wish to manage their links as a collection, and
may need to read the current set of links in order to determine link may need to read the current set of links stored in the registration
maintenance operations. resource, in order to determine link maintenance operations.
One or more links MAY be selected by using query filtering as One or more links MAY be selected by using query filtering as
specified in [RFC6690] Section 4.1 specified in [RFC6690] Section 4.1
If no links are selected, the Resource Directory SHOULD return an
empty payload.
The read request interface is specified as follows: The read request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: GET Method: GET
URI Template: /{+location}{?href,rel,rt,if,ct} URI Template: /{+location}{?href,rel,rt,if,ct}
URI Template Variables: URI Template Variables:
skipping to change at page 22, line 14 skipping to change at page 23, line 37
The following examples show successful read of the endpoint links The following examples show successful read of the endpoint links
from the RD, with example location value /rd/4521. from the RD, with example location value /rd/4521.
Req: GET /rd/4521 Req: GET /rd/4521
Res: 2.01 Content Res: 2.01 Content
Payload: Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor", </sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor" </sensors/light>;ct=41;rt="light-lux";if="sensor"
6.7. Update Endpoint Links 5.4.4. Update Endpoint Links
[This section will be removed before or as a result of a working-
group last-call if the PATCH methods do not achieve the same level of
consensus as the present document.]
A PATCH update adds, removes or changes links for the endpoint by A PATCH update adds, removes or changes links for the endpoint by
including link update information in the payload of the update as a including link update information in the payload of the update as a
merge-patch+json format [RFC7396] document. merge-patch+json format [RFC7396] document.
Other PATCH document formats may be used as appropriate for patching
the array of objects format of a Registration Resource. In
particular, a select-merge patch document format could combine the
function of link selection query and link attribute replacement
values.
One or more links are selected for update by using query filtering as One or more links are selected for update by using query filtering as
specified in [RFC6690] Section 4.1 specified in [RFC6690] Section 4.1
The query filter selects the links to be modified or deleted, by The query filter selects the links to be modified or deleted, by
matching the query parameter values to the values of the link matching the query parameter values to the values of the link
attributes. attributes.
When the query parameters are not present in the request, the payload When the query parameters are not present in the request, the payload
specifies links to be added to the target document. When the query specifies links to be added to the target document. When the query
parameters are present, the attribute names and values in the query parameters are present, the attribute names and values in the query
parameters select one or more links on which to apply the PATCH parameters select one or more links on which to apply the PATCH
operation. operation.
skipping to change at page 22, line 37 skipping to change at page 24, line 14
The query filter selects the links to be modified or deleted, by The query filter selects the links to be modified or deleted, by
matching the query parameter values to the values of the link matching the query parameter values to the values of the link
attributes. attributes.
When the query parameters are not present in the request, the payload When the query parameters are not present in the request, the payload
specifies links to be added to the target document. When the query specifies links to be added to the target document. When the query
parameters are present, the attribute names and values in the query parameters are present, the attribute names and values in the query
parameters select one or more links on which to apply the PATCH parameters select one or more links on which to apply the PATCH
operation. operation.
If no links are selected by the query parameters, the PATCH operation
SHOULD NOT update the state of any resource, and SHOULD return a
reply of "Changed".
If an attribute name specified in the PATCH document exists in any If an attribute name specified in the PATCH document exists in any
the set of selected links, all occurrences of the attribute value in the set of selected links, all occurrences of the attribute value in
the target document MUST be updated using the value from the PATCH the target document MUST be updated using the value from the PATCH
payload. If the attribute name is not present in any selected links, payload. If the attribute name is not present in any selected links,
the attribute MUST be added to the links. the attribute MUST be added to the links.
If the PATCH payload contains plural link references, or processing
the PATCH payload would result in plural link references, the request
SHOULD be rejected with a "Conflict" result.
If the PATCH payload results in the modification of link target,
context, or relation values, that is "href", "rel", or "anchor", the
request SHOULD be rejected with a "Conflict" result code.
The update request interface is specified as follows: The update request interface is specified as follows:
Interaction: EP -> RD Interaction: EP -> RD
Method: PATCH Method: PATCH
URI Template: /{+location}{?href,rel,rt,if,ct} URI Template: /{+location}{?href,rel,rt,if,ct}
URI Template Variables: URI Template Variables:
skipping to change at page 23, line 26 skipping to change at page 25, line 15
Success: 2.04 "Changed" 0r 204 "No Content" in the update was Success: 2.04 "Changed" 0r 204 "No Content" in the update was
successfully processed. successfully processed.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource Failure: 4.04 "Not Found" or 404 "Not Found". Registration resource
does not exist (e.g. may have expired). does not exist (e.g. may have expired).
Failure: 4.09 "Conflict" or 409 "Conflict". Attempt to update the
registration content with links resulting in plurality of
references; see Section 5.3.4.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples show an endpoint adding </sensors/humid>, The following examples show an endpoint adding </sensors/humid>,
modifying </sensors/temp>, and removing </sensors/light> links in RD modifying </sensors/temp>, and removing </sensors/light> links in RD
using the Update Endpoint Links function with the example location using the Update Endpoint Links function with the example location
value /rd/4521. value /rd/4521.
The Registration Resource initial state is:
Req: GET /rd/4521
Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature",
</sensors/light>;ct=41;rt="light-lux";if="sensor"
The following example shows an EP adding the link </sensors/ The following example shows an EP adding the link </sensors/
humid>;ct=41;rt="humid-s";if="sensor" to the collection of links at humid>;ct=41;rt="humid-s";if="sensor" to the collection of links at
the location /rd/4521. the location /rd/4521.
Req: PATCH /rd/4521 Req: PATCH /rd/4521
Payload: Payload:
[{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}] [{"href":"/sensors/humid","ct": 41, "rt": "humid-s", "if": "sensor"}]
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /rd/4521
Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature",
</sensors/light>;ct=41;rt="light-lux";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"
The following example shows an EP modifying all links at the example The following example shows an EP modifying all links at the example
location /rd/4521 which are identified by href="/sensors/temp", from location /rd/4521 which are identified by href="/sensors/temp", from
the initial link-value of </sensors/temp>;rt="temperature" to the new the initial link-value of </sensors/temp>;rt="temperature" to the new
link-value </sensors/temp>;rt="temperature-c";if="sensor" by changing link-value </sensors/temp>;rt="temperature-c";if="sensor" by changing
the value of the link attribute "rt" and adding the link attribute the value of the link attribute "rt" and adding the link attribute
if="sensor" using the PATCH operation with the supplied merge- if="sensor" using the PATCH operation with the supplied merge-
patch+json document payload. patch+json document payload.
Req: PATCH /rd/4521?href="/sensors/temp" Req: PATCH /rd/4521?href=/sensors/temp
Payload: Payload:
{"rt": "temperature-c", "if": "sensor"}, {"rt": "temperature-c", "if": "sensor"},
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /rd/4521
Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/light>;ct=41;rt="light-lux";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"
This example shows an EP removing all links at the example location This example shows an EP removing all links at the example location
/rd/4521 which are identified by href="/sensors/light". /rd/4521 which are identified by href="/sensors/light".
Req: PATCH /rd/4521?href="/sensors/light" Req: PATCH /rd/4521?href=/sensors/light
Payload: Payload:
{null} {}
Content-Format: Content-Format:
application/merge-patch+json application/merge-patch+json
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /rd/4521
7. Group Function Set Res: 2.01 Content
Payload:
</sensors/temp>;ct=41;rt="temperature-c";if="sensor",
</sensors/humid>;ct=41;rt="humid-s";if="sensor"
This section defines a function set for the creation of groups of 6. RD Groups
endpoints for the purpose of managing and looking up endpoints for
group operations. The group function set is similar to the resource This section defines the REST API for the creation, management, and
directory function set, in that a group may be created or removed. lookup of endpoints for group operations. Similar to endpoint
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. In order
to make use of multicast requests with CoAP, a group MAY have a to make use of multicast requests with CoAP, a group MAY have a
multicast address associated with it. multicast address associated with it.
7.1. Register a Group 6.1. Register a Group
In order to create a group, a commissioning tool (CT) used to In order to create a group, a commissioning tool (CT) used to
configure groups, makes a request to the RD indicating the name of configure groups, makes a request to the RD indicating the name of
the group to create (or update), optionally the domain the group the group to create (or update), optionally the domain the group
belongs to, and optionally the multicast address of the group. The belongs to, and optionally the multicast address of the group. The
registration message includes the list of endpoints that belong to registration message includes the list of endpoints that belong to
that group. that group.
All the endpoints in the group MUST be registered with the RD before All the endpoints in the group MUST be registered with the RD before
registering a group. If an endpoint is not yet registered to the RD registering a group. If an endpoint is not yet registered to the RD
skipping to change at page 25, line 25 skipping to change at page 28, line 5
The registration request interface is specified as follows: The registration request interface is specified as follows:
Interaction: CT -> RD Interaction: CT -> RD
Method: POST Method: POST
URI Template: /{+rd-group}{?gp,d,con} URI Template: /{+rd-group}{?gp,d,con}
URI Template Variables: URI Template Variables:
rd-group := RD Group Function Set path (mandatory). This is the rd-group := RD Group Base URI path (mandatory). This is the path
path of the RD Group Function Set. The value "rd-group" is of the RD Group REST API. The value "rd-group" is recommended
recommended for this variable. for this variable.
gp := Group Name (mandatory). The name of the group to be gp := Group Name (mandatory). The name of the group to be
created or replaced, unique within that domain. The maximum created or replaced, unique within that domain. The maximum
length of this parameter is 63 bytes. length of this parameter is 63 bytes.
d := Domain (optional). The domain to which this group belongs. d := Domain (optional). The domain to which this group belongs.
The maximum length of this parameter is 63 bytes. Optional. The maximum length of this parameter is 63 bytes. Optional.
When this parameter is elided, the RD MAY associate the When this parameter is elided, the RD MAY associate the
endpoint with a configured default domain. The domain value is endpoint with a configured default domain.
needed to export the endpoint to DNS-SD (see Section 10)
con := Context (optional). This parameter is used to set the IP con := Context (optional). This parameter sets the scheme,
multicast address at which this server is available in the form address and port at which this server is available in the form
scheme://multicast-address:port. Optional. In the absence of scheme://host:port/path. In the absence of this parameter the
this parameter no multicast address is configured. This scheme of the protocol, source address and source port of the
parameter is compulsory when the directory is filled by a register request are assumed. This parameter is mandatory when
commissioning tool. the directory is filled by a third party such as an
commissioning tool. When con is used, scheme and host are
mandatory and port and path parameters are optional.
Content-Format: application/link-format Content-Format: application/link-format
Content-Format: application/link-format+json Content-Format: application/link-format+json
Content-Format: application/link-format+cbor Content-Format: application/link-format+cbor
The following response codes are defined for this interface: The following response codes are defined for this interface:
Success: 2.01 "Created" or 201 "Created". The Location header MUST Success: 2.01 "Created" or 201 "Created". The Location header
be included with the new group entry. This Location MUST be a option MUST be returned in response to a successful group CREATE
stable identifier generated by the RD as it is used for delete operation. This Location MUST be a stable identifier generated by
operations on this registration. the RD as it is used for delete operations of the group
registration resource.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not Failure: 4.04 "Not Found" or 404 "Not Found". An Endpoint is not
registered in the RD (e.g. may have expired). registered in the RD (e.g. may have expired).
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
skipping to change at page 26, line 34 skipping to change at page 29, line 17
Req: POST coap://rd.example.com/rd-group?gp=lights Req: POST coap://rd.example.com/rd-group?gp=lights
Content-Format: 40 Content-Format: 40
Payload: Payload:
<>;ep="node1", <>;ep="node1",
<>;ep="node2" <>;ep="node2"
Res: 2.01 Created Res: 2.01 Created
Location: /rd-group/12 Location: /rd-group/12
Req: POST /rd-group?gp=lights HTTP/1.1 6.2. Group Removal
Host: example.com
Content-Type: application/link-format
Payload:
<>;ep="node1",
<>;ep="node2"
Res: 201 Created
Location: /rd-group/12
7.2. Group Removal
A group can be removed simply by sending a removal message to the A group can be removed simply by sending a removal message to the
location returned when registering the group. Removing a group MUST location of the group registration resource which was returned when
NOT remove the endpoints of the group from the RD. intially registering the group. Removing a group MUST NOT remove the
endpoints of the group from the RD.
The removal request interface is specified as follows: The removal request interface is specified as follows:
Interaction: CT -> RD Interaction: CT -> RD
Method: DELETE Method: DELETE
URI Template: /{+location} URI Template: /{+location}
URI Template Variables: URI Template Variables:
location := This is the Location path returned by the RD as a location := This is the Location path returned by the RD as a
result of a successful group registration. result of a successful group registration.
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
skipping to change at page 27, line 26 skipping to change at page 30, line 4
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist. Failure: 4.04 "Not Found" or 404 "Not Found". Group does not exist.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The following examples shows successful removal of the group from the The following examples shows successful removal of the group from the
RD with the example location value /rd-group/12. RD with the example location value /rd-group/12.
Req: DELETE /rd-group/12 Req: DELETE /rd-group/12
Res: 2.02 Deleted Res: 2.02 Deleted
8. RD Lookup Function Set 7. RD Lookup
In order for an RD to be used for discovering resources registered In order for an RD to be used for discovering resources registered
with it, a lookup interface can be provided using this function set. with it, an optional lookup interface may be provided. This lookup
This lookup interface is defined as a default, and it is assumed that interface is defined as a default, and it is assumed that RDs may
RDs may also support lookups to return resource descriptions in also support lookups to return resource descriptions in alternative
alternative formats (e.g. Atom or HTML Link) or using more advanced formats (e.g. Atom or HTML Link) or using more advanced interfaces
interfaces (e.g. supporting context or semantic based lookup). (e.g. supporting context or semantic based lookup).
This function set allows lookups for domains, groups, endpoints and RD Lookup allows lookups for domains, groups, endpoints and resources
resources using attributes defined in the RD Function Set and for use using attributes defined in this document and for use with the CoRE
with the CoRE Link Format. The result of a lookup request is the Link Format. The result of a lookup request is the list of links (if
list of links (if any) corresponding to the type of lookup. Thus, a any) corresponding to the type of lookup. Thus, a domain lookup MUST
domain lookup MUST return a list of domains, a group lookup MUST return a list of domains, a group lookup MUST return a list of
return a list of groups, an endpoint lookup MUST return a list of groups, an endpoint lookup MUST return a list of endpoints and a
endpoints and a resource lookup MUST return a list of links to resource lookup MUST return a list of links to resources.
resources.
RD Lookup does not expose registration resources directly, but
returns link content from registration resource entries which satisfy
RD Lookup queries.
The lookup type is selected by a URI endpoint, which is indicated by
a Resource Type as per Table 1 below:
+-------------+--------------------+-----------+
| Lookup Type | Resource Type | Mandatory |
+-------------+--------------------+-----------+
| Resource | core.rd-lookup-res | Mandatory |
| Endpoint | core.rd-lookup-ep | Mandatory |
| Domain | core.rd-lookup-d | Optional |
| Group | core.rd-lookup-gp | Optional |
+-------------+--------------------+-----------+
Table 1: Lookup Types
Each endpoint and resource lookup result returns respectively the Each endpoint and resource lookup result returns respectively the
scheme (IP address and port) followed by the path part of the URI of scheme (IP address and port) followed by the path part of the URI of
every endpoint and resource inside angle brackets ("<>") and followed every endpoint and resource inside angle brackets ("<>") and followed
by the other parameters. by the other parameters.
The target of these links SHOULD be the actual location of the The target of these links SHOULD be the actual location of the
domain, endpoint or resource, but MAY be an intermediate proxy e.g. domain, endpoint or resource, but MAY be an intermediate proxy e.g.
in the case of an HTTP lookup interface for CoAP endpoints. in the case of an HTTP lookup interface for CoAP endpoints.
skipping to change at page 28, line 42 skipping to change at page 31, line 37
zero and page zero. Thus, specifying count of 10 and page of 0 will zero and page zero. Thus, specifying count of 10 and page of 0 will
return the first 10 links in the result set (links 0-9). Count = 10 return the first 10 links in the result set (links 0-9). Count = 10
and page = 1 will return the next 'page' containing links 10-19, and and page = 1 will return the next 'page' containing links 10-19, and
so on. so on.
Multiple query parameters MAY be included in a lookup, all included Multiple query parameters MAY be included in a lookup, all included
parameters MUST match for a resource to be returned. The parameters MUST match for a resource to be returned. The
character'*' MAY be included at the end of a parameter value as a character'*' MAY be included at the end of a parameter value as a
wildcard operator. wildcard operator.
The rd-lookup interface MAY use any set of query parameters to match RD Lookup requests MAY use any set of query parameters to match the
the registered attributes and relations. In addition, this interface registered attributes and relations. In addition, this interface MAY
MAY be used with queries that specify domains, endpoints, and groups. be used with queries that specify domains, endpoints, and groups.
For example, a domain lookup filtering on groups would return a list For example, a domain lookup filtering on groups would return a list
of domains that contain the specified groups. An endpoint lookup of domains that contain the specified groups. An endpoint lookup
filtering on groups would return a list of endpoints that are in the filtering on groups would return a list of endpoints that are in the
specified groups. specified groups.
The lookup interface is specified as follows: The lookup interface is specified as follows:
Interaction: Client -> RD Interaction: Client -> RD
Method: GET Method: GET
URI Template: /{+rd-lookup-base}/{lookup- URI Template: /{+rd-lookup-base}/{lookup-
type}{?d,ep,gp,et,rt,page,count,resource-param} type}{?d,res,ep,gp,et,rt,page,count,resource-param}
URI Template Variables: URI Template Variables:
rd-lookup-base := RD Lookup Function Set path (mandatory). This rd-lookup-base := RD Lookup Base URI path (mandatory). This is
is the path of the RD Lookup Function Set. The recommended the base path for RD Lookup requests. The recommended value
value for this variable is: "rd-lookup". for this variable is: "rd-lookup".
lookup-type := ("d", "ep", "res", "gp") (mandatory) This variable lookup-type := ("ep", "res") (mandatory), ("d","gp") (optional)
is used to select the kind of lookup to perform (domain, This variable is used to select the type of lookup to perform
endpoint, resource, or group). (endpoint, resource, domain, or group). The values are
recommended defaults and MAY use other values as needed. The
supported lookup-types SHOULD be listed in .well-known/core
using the specified resource types.
ep := Endpoint name (optional). Used for endpoint, group and ep := Endpoint name (optional). Used for endpoint, group and
resource lookups. resource lookups.
d := Domain (optional). Used for domain, group, endpoint and d := Domain (optional). Used for domain, group, endpoint and
resource lookups. resource lookups.
res := resource (optional). Used for domain, group, endpoint and res := resource (optional). Used for domain, group, endpoint and
resource lookups. resource lookups.
skipping to change at page 30, line 6 skipping to change at page 32, line 50
all matching links in the result set. Link numbering starts all matching links in the result set. Link numbering starts
with zero. with zero.
rt := Resource type (optional). Used for group, endpoint and rt := Resource type (optional). Used for group, endpoint and
resource lookups. resource lookups.
et := Endpoint type (optional). Used for group, endpoint and et := Endpoint type (optional). Used for group, endpoint and
resource lookups. resource lookups.
resource-param := Link attribute parameters (optional). Any link resource-param := Link attribute parameters (optional). Any link
attribute as defined in Section 4.1 of [RFC6690], used for target attribute as defined in Section 4.1 of [RFC6690], used
resource lookups. for resource lookups.
Content-Format: application/link-format (optional) Content-Format: application/link-format (optional)
Content-Format: application/link-format+json (optional) Content-Format: application/link-format+json (optional)
Content-Format: application/link-format+cbor (optional) Content-Format: application/link-format+cbor (optional)
The following responses codes are defined for this interface: The following responses codes are defined for this interface:
Success: 2.05 "Content" or 200 "OK" with an "application/link- Success: 2.05 "Content" or 200 "OK" with an "application/link-
skipping to change at page 30, line 34 skipping to change at page 33, line 30
Failure: No error response to a multicast request. Failure: No error response to a multicast request.
Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed Failure: 4.00 "Bad Request" or 400 "Bad Request". Malformed
request. request.
Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable". Failure: 5.03 "Service Unavailable" or 503 "Service Unavailable".
Service could not perform the operation. Service could not perform the operation.
HTTP support: YES HTTP support: YES
The examples in this section assume a CoAP host with IP address The examples in this section assume CoAP hosts with a default CoAP
FDFD::123 and a default CoAP port 61616. HTTP hosts are possible and port 61616. HTTP hosts are possible and do not change the nature of
do not change the nature of the examples.\ the examples.
The following example shows a client performing a resource lookup The following example shows a client performing a resource lookup
with the example look-up location /rd-lookup/: with the example look-up location /rd-lookup/:
Req: GET /rd-lookup/res?rt=temperature Req: GET /rd-lookup/res?rt=temperature
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::123]:61616/temp>;rt="temperature" <coap://[FDFD::123]:61616/temp>;rt="temperature"
The following example shows a client performing an endpoint type The following example shows a client performing an endpoint type
lookup: lookup:
Req: GET /rd-lookup/ep?et=power-node Req: GET /rd-lookup/ep?et=power-node
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::123]:61616>;ep="node5", <coap://[FDFD::127]:61616>;ep="node5",
<coap://[FDFD::123]:61616>;ep="node7" <coap://[FDFD::129]:61616>;ep="node7"
The following example shows a client performing a domain lookup: The following example shows a client performing a domain lookup:
Req: GET /rd-lookup/d Req: GET /rd-lookup/d
Res: 2.05 Content Res: 2.05 Content
<>;d="domain1", <>;d="domain1",
<>;d="domain2" <>;d="domain2"
The following example shows a client performing a group lookup for The following example shows a client performing a group lookup for
skipping to change at page 31, line 35 skipping to change at page 34, line 27
<>;gp="lights1";d="example.com" <>;gp="lights1";d="example.com"
<>;gp="lights2";d="ecample.com" <>;gp="lights2";d="ecample.com"
The following example shows a client performing a lookup for all The following example shows a client performing a lookup for all
endpoints in a particular group: endpoints in a particular group:
Req: GET /rd-lookup/ep?gp=lights1 Req: GET /rd-lookup/ep?gp=lights1
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::123]:61616>;ep="node1", <coap://[FDFD::123]:61616>;ep="node1",
<coap://[FDFD::123]:61616>;ep="node2" <coap://[FDFD::124]:61616>;ep="node2"
The following example shows a client performing a lookup for all The following example shows a client performing a lookup for all
groups an endpoint belongs to: groups an endpoint belongs to:
Req: GET /rd-lookup/gp?ep=node1 Req: GET /rd-lookup/gp?ep=node1
Res: 2.05 Content Res: 2.05 Content
<>;gp="lights1" <>;gp="lights1"
The following example shows a client performing a paginated lookup The following example shows a client performing a paginated lookup
skipping to change at page 32, line 22 skipping to change at page 35, line 22
Req: GET /rd-lookup/res?page=1&count=5 Req: GET /rd-lookup/res?page=1&count=5
Res: 2.05 Content Res: 2.05 Content
<coap://[FDFD::123]:61616/res/5>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/5>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/6>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/6>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/7>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/7>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/8>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/8>;rt=sensor;ct=60
<coap://[FDFD::123]:61616/res/9>;rt=sensor;ct=60 <coap://[FDFD::123]:61616/res/9>;rt=sensor;ct=60
9. New Link-Format Attributes 8. Security Considerations
When using the CoRE Link Format to describe resources being
discovered by or posted to a resource directory service, additional
information about those resources is useful. This specification
defines the following new attributes for use in the CoRE Link Format
[RFC6690]:
link-extension = ( "ins" "=" (ptoken | quoted-string) )
; The token or string is max 63 bytes
link-extension = ( "exp" )
9.1. Resource Instance attribute 'ins'
The Resource Instance "ins" attribute is an identifier for this
resource, which makes it possible to distinguish it from other
similar resources. This attribute is similar in use to the
<Instance> portion of a DNS-SD record (see Section 10.1, and SHOULD
be unique across resources with the same Resource Type attribute in
the domain it is used. A Resource Instance might be a descriptive
string like "Ceiling Light, Room 3", a short ID like "AF39" or a
unique UUID or iNumber. This attribute is used by a Resource
Directory to distinguish between multiple instances of the same
resource type within the directory.
This attribute MUST be no more than 63 bytes in length. The resource
identifier attribute MUST NOT appear more than once in a link
description. This attribute MAY be used as a query parameter in the
RD Lookup Function Set defined in Section 7.
9.2. Export attribute 'exp'
The Export "exp" attribute is used as a flag to indicate that a link
description MAY be exported by a resource directory to external
directories.
The CoRE Link Format is used for many purposes between CoAP
endpoints. Some are useful mainly locally, for example checking the
observability of a resource before accessing it, determining the size
of a resource, or traversing dynamic resource structures. However,
other links are very useful to be exported to other directories, for
example the entry point resource to a functional service. This
attribute MAY be used as a query parameter in the RD Lookup Function
Set defined in Section 7.
10. DNS-SD Mapping
CoRE Resource Discovery is intended to support fine-grained discovery
of hosted resources, their attributes, and possibly other resource
relations [RFC6690]. In contrast, service discovery generally refers
to a coarse-grained resolution of an endpoint's IP address, port
number, and protocol.
Resource and service discovery are complementary in the case of large
networks, where the latter can facilitate scaling. This document
defines a mapping between CoRE Link Format attributes and DNS-Based
Service Discovery [RFC6763] fields that permits discovery of CoAP
services by either method.
10.1. DNS-based Service discovery
DNS-Based Service Discovery (DNS-SD) defines a conventional method of
configuring DNS PTR, SRV, and TXT resource records to facilitate
discovery of services (such as CoAP servers in a subdomain) using the
existing DNS infrastructure. This section gives a brief overview of
DNS-SD; see [RFC6763] for a detailed specification.
DNS-SD service names are limited to 255 octets and are of the form:
Service Name = <Instance>.<ServiceType>.<Domain>.
The service name is the label of SRV/TXT resource records. The SRV
RR specifies the host and the port of the endpoint. The TXT RR
provides additional information in the form of key/value pairs.
The <Domain> part of the service name is identical to the global (DNS
subdomain) part of the authority in URIs that identify servers or
groups of servers.
The <ServiceType> part is composed of at least two labels. The first
label of the pair is the application protocol name [RFC6335] preceded
by an underscore character. The second label indicates the transport
and is always "_udp" for UDP-based CoAP services. In cases where
narrowing the scope of the search may be useful, these labels may be
optionally preceded by a subtype name followed by the "_sub" label.
An example of this more specific <ServiceType> is
"light._sub._dali._udp".
A default <Instance> part of the service name may be set at the
factory or during the commissioning process. It SHOULD uniquely
identify an instance of <ServiceType> within a <Domain>. Taken
together, these three elements comprise a unique name for an SRV/ TXT
record pair within the DNS subdomain.
The granularity of a service name MAY be that of a host or group, or
it could represent a particular resource within a CoAP server. The
SRV record contains the host name (AAAA record name) and port of the
service while protocol is part of the service name. In the case
where a service name identifies a particular resource, the path part
of the URI must be carried in a corresponding TXT record.
A DNS TXT record is in practice limited to a few hundred octets in
length, which is indicated in the resource record header in the DNS
response message. The data consists of one or more strings
comprising a key=value pair. By convention, the first pair is
txtver=<number> (to support different versions of a service
description).
10.2. mapping ins to <Instance>
The Resource Instance "ins" attribute maps to the <Instance> part of
a DNS-SD service name. It is stored directly in the DNS as a single
DNS label of canonical precomposed UTF-8 [RFC3629] "Net-Unicode"
(Unicode Normalization Form C) [RFC5198] text. However, to the
extent that the "ins" attribute may be chosen to match the DNS host
name of a service, it SHOULD use the syntax defined in Section 3.5 of
[RFC1034] and Section 2.1 of [RFC1123].
The <Instance> part of the name of a service being offered on the
network SHOULD be configurable by the user setting up the service, so
that he or she may give it an informative name. However, the device
or service SHOULD NOT require the user to configure a name before it
can be used. A sensible choice of default name can allow the device
or service to be accessed in many cases without any manual
configuration at all. The default name should be short and
descriptive, and MAY include a collision-resistant substring such as
the lower bits of the device's MAC address, serial number,
fingerprint, or other identifier in an attempt to make the name
relatively unique.
DNS labels are currently limited to 63 octets in length and the
entire service name may not exceed 255 octets.
10.3. Mapping rt to <ServiceType>
The resource type "rt" attribute is mapped into the <ServiceType>
part of a DNS-SD service name and SHOULD conform to the reg-rel-type
production of the Link Format defined in Section 2 of [RFC6690]. The
"rt" attribute MUST be composed of at least a single Net-Unicode text
string, without underscore '_' or period '.' and limited to 15 octets
in length, which represents the application protocol name. This
string is mapped to the DNS-SD <ServiceType> by prepending an
underscore and appending a period followed by the "_udp" label. For
example, rt="dali" is mapped into "_dali._udp".
The application protocol name may be optionally followed by a period
and a service subtype name consisting of a Net-Unicode text string,
without underscore or period and limited to 63 octets. This string
is mapped to the DNS-SD <ServiceType> by appending a period followed
by the "_sub" label and then appending a period followed by the
service type label pair derived as in the previous paragraph. For
example, rt="dali.light" is mapped into "light._sub._dali._udp".
The resulting string is used to form labels for DNS-SD records which
are stored directly in the DNS.
10.4. Domain mapping
DNS domains may be derived from the "d" attribute. The domain
attribute may be suffixed with the zone name of the authoritative DNS
server to generate the domain name. The "ep" attribute is prefixed
to the domain name to generate the FQDN to be stored into DNS with an
AAAA RR.
10.5. TXT Record key=value strings
A number of [RFC6763] key/value pairs are derived from link-format
information, to be exported in the DNS-SD as key=value strings in a
TXT record ([RFC6763], Section 6.3).
The resource <URI> is exported as key/value pair "path=<URI>".
The Interface Description "if" attribute is exported as key/value
pair "if=<Interface Description>".
The DNS TXT record can be further populated by importing any other
resource description attributes as they share the same key=value
format specified in Section 6 of [RFC6763].
10.6. Importing resource links into DNS-SD
Assuming the ability to query a Resource Directory or multicast a GET
(?exp) over the local link, CoAP resource discovery may be used to
populate the DNS-SD database in an automated fashion. CoAP resource
descriptions (links) can be exported to DNS-SD for exposure to
service discovery by using the Resource Instance attribute as the
basis for a unique service name, composed with the Resource Type as
the <ServiceType>, and registered in the correct <Domain>. The agent
responsible for exporting records to the DNS zone file SHOULD be
authenticated to the DNS server. The following example, using the
example lookup location /rd-lookup, shows an agent discovering a
resource to be exported:
Req: GET /rd-lookup/res?exp
Res: 2.05 Content
<coap://[FDFD::1234]:5683/light/1>;
exp;rt="dali.light";ins="Spot";
d="office";ep="node1"
The agent subsequently registers the following DNS-SD RRs, assuming a
zone name "example.com" prefixed with "office":
node1.office.example.com. IN AAAA FDFD::1234
_dali._udp.office.example.com IN PTR
Spot._dali._udp.office.example.com
light._sub._dali._udp.example.com IN PTR
Spot._dali._udp.office.example.com
Spot._dali._udp.office.example.com IN SRV 0 0 5683
node1.office.example.com.
Spot._dali._udp.office.example.com IN TXT
txtver=1;path=/light/1
In the above figure the Service Name is chosen as
Spot._dali._udp.office.example.com without the light._sub service
prefix. An alternative Service Name would be:
Spot.light._sub._dali._udp.office.example.com.
11. Security Considerations
The security considerations as described in Section 7 of [RFC5988] The security considerations as described in Section 7 of [RFC5988]
and Section 6 of [RFC6690] apply. The "/.well-known/core" resource and Section 6 of [RFC6690] apply. The "/.well-known/core" resource
may be protected e.g. using DTLS when hosted on a CoAP server as may be protected e.g. using DTLS when hosted on a CoAP server as
described in [RFC7252]. DTLS or TLS based security SHOULD be used on described in [RFC7252]. DTLS or TLS based security SHOULD be used on
all resource directory interfaces defined in this document. all resource directory interfaces defined in this document.
11.1. Endpoint Identification and Authentication 8.1. Endpoint Identification and Authentication
An Endpoint is determined to be unique by an RD by the Endpoint An Endpoint is determined to be unique by an RD by the Endpoint
identifier parameter included during Registration, and any associated identifier parameter included during Registration, and any associated
TLS or DTLS security bindings. An Endpoint MUST NOT be identified by TLS or DTLS security bindings. An Endpoint MUST NOT be identified by
its protocol, port or IP address as these may change over the its protocol, port or IP address as these may change over the
lifetime of an Endpoint. lifetime of an Endpoint.
Every operation performed by an Endpoint or Client on a resource Every operation performed by an Endpoint or Client on a resource
directory SHOULD be mutually authenticated using Pre-Shared Key, Raw directory SHOULD be mutually authenticated using Pre-Shared Key, Raw
Public Key or Certificate based security. Endpoints using a Public Key or Certificate based security. Endpoints using a
Certificate MUST include the Endpoint identifier as the Subject of Certificate MUST include the Endpoint identifier as the Subject of
the Certificate, and this identifier MUST be checked by a resource the Certificate, and this identifier MUST be checked by a resource
directory to match the Endpoint identifier included in the directory to match the Endpoint identifier included in the
Registration message. Registration message.
11.2. Access Control 8.2. Access Control
Access control SHOULD be performed separately for the RD Function Set Access control SHOULD be performed separately for the RD
and the RD Lookup Function Set, as different endpoints may be registration, Lookup, and group API base paths, as different
authorized to register with an RD from those authorized to lookup endpoints may be authorized to register with an RD from those
endpoints from the RD. Such access control SHOULD be performed in as authorized to lookup endpoints from the RD. Such access control
fine-grained a level as possible. For example access control for SHOULD be performed in as fine-grained a level as possible. For
lookups could be performed either at the domain, endpoint or resource example access control for lookups could be performed either at the
level. domain, endpoint or resource level.
11.3. Denial of Service Attacks 8.3. Denial of Service Attacks
Services that run over UDP unprotected are vulnerable to unknowingly Services that run over UDP unprotected are vulnerable to unknowingly
become part of a DDoS attack as UDP does not require return become part of a DDoS attack as UDP does not require return
routability check. Therefore, an attacker can easily spoof the routability check. Therefore, an attacker can easily spoof the
source IP of the target entity and send requests to such a service source IP of the target entity and send requests to such a service
which would then respond to the target entity. This can be used for which would then respond to the target entity. This can be used for
large-scale DDoS attacks on the target. Especially, if the service large-scale DDoS attacks on the target. Especially, if the service
returns a response that is order of magnitudes larger than the returns a response that is order of magnitudes larger than the
request, the situation becomes even worse as now the attack can be request, the situation becomes even worse as now the attack can be
amplified. DNS servers have been widely used for DDoS amplification amplified. DNS servers have been widely used for DDoS amplification
attacks. There is also a danger that NTP Servers could become attacks. There is also a danger that NTP Servers could become
implicated in denial-of-service (DoS) attacks since they run on implicated in denial-of-service (DoS) attacks since they run on
unprotected UDP, there is no return routability check, and they can unprotected UDP, there is no return routability check, and they can
have a large amplification factor. The responses from the NTP server have a large amplification factor. The responses from the NTP server
were found to be 19 times larger than the request. A Resource were found to be 19 times larger than the request. A Resource
Directory (RD) which responds to wild-card lookups is potentially Directory (RD) which responds to wild-card lookups is potentially
vulnerable if run with CoAP over UDP. Since there is no return vulnerable if run with CoAP over UDP. Since there is no return
routability check and the responses can be significantly larger than routability check and the responses can be significantly larger than
requests, RDs can unknowingly become part of a DDoS amplification requests, RDs can unknowingly become part of a DDoS amplification
attack. Therefore, it is RECOMMENDED that implementations ensure attack.
return routability. This can be done, for example by responding to
wild card lookups only over DTLS or TLS or TCP.
12. IANA Considerations 9. IANA Considerations
12.1. Resource Types 9.1. Resource Types
"core.rd", "core.rd-group" and "core.rd-lookup" resource types need "core.rd", "core.rd-group", "core.rd-lookup-ep", "core.rd-lookup-
res", "core.rd-lookup-d", and "core.rd-lookup-gp" resource types need
to be registered with the resource type registry defined by to be registered with the resource type registry defined by
[RFC6690]. [RFC6690].
12.2. Link Extension 9.2. IPv6 ND Resource Directory Address Option
The "exp" and "ins" attributes need to be registered when a future
Web Linking link-extension registry is created (e.g. in RFC5988bis).
12.3. IPv6 ND Resource Directory Address Option
This document registers one new ND option type under the subregistry This document registers one new ND option type under the subregistry
"IPv6 Neighbor Discovery Option Formats": "IPv6 Neighbor Discovery Option Formats":
o Resource Directory address Option (38) o Resource Directory address Option (38)
12.4. RD Parameter Registry 9.3. RD Parameter Registry
This specification defines a new sub-registry for registration and This specification defines a new sub-registry for registration and
lookup parameters called "RD Parameters" under "CoRE Parameters". lookup parameters called "RD Parameters" under "CoRE Parameters".
Although this specification defines a basic set of parameters, it is Although this specification defines a basic set of parameters, it is
expected that other standards that make use of this interface will expected that other standards that make use of this interface will
define new ones. define new ones.
Each entry in the registry must include the human readable name of Each entry in the registry must include the human readable name of
the parameter, the query parameter, validity requirements if any and the parameter, the query parameter, validity requirements if any and
a description. The query parameter MUST be a valid URI query key a description. The query parameter MUST be a valid URI query key
[RFC3986]. [RFC3986].
Initial entries in this sub-registry are as follows: Initial entries in this sub-registry are as follows:
+-----------+-------+---------------+-------------------------------+ +----------+-------+---------------+--------------------------------+
| Name | Query | Validity | Description | | Name | Query | Validity | Description |
+-----------+-------+---------------+-------------------------------+ +----------+-------+---------------+--------------------------------+
| Endpoint | ep | | Name of the endpoint, max 63 | | Endpoint | ep | | Name of the endpoint, max 63 |
| Name | | | bytes | | Name | | | bytes |
| Lifetime | lt | 60-4294967295 | Lifetime of the registration | | Lifetime | lt | 60-4294967295 | Lifetime of the registration |
| | | | in seconds | | | | | in seconds |
| Domain | d | | Domain to which this endpoint | | Domain | d | | Domain to which this endpoint |
| | | | belongs | | | | | belongs |
| Endpoint | et | | Semantic name of the endpoint | | Endpoint | et | | Semantic name of the endpoint |
| Type | | | | | Type | | | |
| Context | con | URI | The scheme, address and port | | Context | con | URI | The scheme, address and port |
| | | | at which this server is | | | | | at which this server is |
| | | | available | | | | | available |
| Resource | res | | Name of the resource | | Resource | res | | Name of the resource |
| Name | | | | | Name | | | |
| Group | gp | | Name of a group in the RD | | Group | gp | | Name of a group in the RD |
| Name | | | | | Name | | | |
| Page | page | Integer | Used for pagination | | Page | page | Integer | Used for pagination |
| Count | count | Integer | Used for pagination | | Count | count | Integer | Used for pagination |
| Resource | ins | | Instance Identifier | +----------+-------+---------------+--------------------------------+
| Instance | | | |
| Export | exp | | A link MAY be exported to |
| | | | another Resource Directory |
+-----------+-------+---------------+-------------------------------+
Table 1: RD Parameters Table 2: RD Parameters
The IANA policy for future additions to the sub-registry is "Expert The IANA policy for future additions to the sub-registry is "Expert
Review" as described in [RFC5226]. Review" as described in [RFC5226].
13. Examples 10. Examples
13.1. Lighting Installation Two examples are presented: a Lighting Installation example in
Section 10.1 and a LWM2M example in Section 10.2.
10.1. Lighting Installation
This example shows a simplified lighting installation which makes use This example shows a simplified lighting installation which makes use
of the Resource Directory (RD) with a CoAP interface to facilitate of the Resource Directory (RD) with a CoAP interface to facilitate
the installation and start up of the application code in the lights the installation and start up of the application code in the lights
and sensors. In particular, the example leads to the definition of a and sensors. In particular, the example leads to the definition of a
group and the enabling of the corresponding multicast address. No group and the enabling of the corresponding multicast address. No
conclusions must be drawn on the realization of actual installation conclusions must be drawn on the realization of actual installation
or naming procedures, because the example only "emphasizes" some of or naming procedures, because the example only "emphasizes" some of
the issues that may influence the use of the RD and does not pretend the issues that may influence the use of the RD and does not pretend
to be normative. The example uses the recommended values for the to be normative. The example uses the recommended values for the
base resources: "/rd", "/rd-lookup", and "/rd-group". base resources: "/rd", "/rd-lookup", and "/rd-group".
13.1.1. Installation Characteristics 10.1.1. Installation Characteristics
The example assumes that the installation is managed. That means The example assumes that the installation is managed. That means
that a Commissioning Tool (CT) is used to authorize the addition of that a Commissioning Tool (CT) is used to authorize the addition of
nodes, name them, and name their services. The CT can be connected nodes, name them, and name their services. The CT can be connected
to the installation in many ways: the CT can be part of the to the installation in many ways: the CT can be part of the
installation network, connected by WiFi to the installation network, installation network, connected by WiFi to the installation network,
or connected via GPRS link, or other method. or connected via GPRS link, or other method.
It is assumed that there are two naming authorities for the It is assumed that there are two naming authorities for the
installation: (1) the network manager that is responsible for the installation: (1) the network manager that is responsible for the
skipping to change at page 40, line 39 skipping to change at page 38, line 45
group of lamps consists of: middle and left lamps of luminary1 and group of lamps consists of: middle and left lamps of luminary1 and
right lamp of luminary2. right lamp of luminary2.
Before commissioning by the lighting manager, the network is Before commissioning by the lighting manager, the network is
installed and access to the interfaces is proven to work by the installed and access to the interfaces is proven to work by the
network manager. network manager.
At the moment of installation, the network under installation is not At the moment of installation, the network under installation is not
necessarily connected to the DNS infra structure. Therefore, SLAAC necessarily connected to the DNS infra structure. Therefore, SLAAC
IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in IPv6 addresses are assigned to CT, RD, luminaries and sensor shown in
Table 2 below: Table 3 below:
+--------------------+--------------+ +--------------------+--------------+
| Name | IPv6 address | | Name | IPv6 address |
+--------------------+--------------+ +--------------------+--------------+
| luminary1 | FDFD::ABCD:1 | | luminary1 | FDFD::ABCD:1 |
| luminary2 | FDFD::ABCD:2 | | luminary2 | FDFD::ABCD:2 |
| Presence sensor | FDFD::ABCD:3 | | Presence sensor | FDFD::ABCD:3 |
| Resource directory | FDFD::ABCD:0 | | Resource directory | FDFD::ABCD:0 |
+--------------------+--------------+ +--------------------+--------------+
Table 2: interface SLAAC addresses Table 3: interface SLAAC addresses
In Section 13.1.2 the use of resource directory during installation In Section 10.1.2 the use of resource directory during installation
is presented. In Section 13.1.3 the connection to DNS is discussed. is presented.
13.1.2. RD entries 10.1.2. RD entries
It is assumed that access to the DNS infrastructure is not always It is assumed that access to the DNS infrastructure is not always
possible during installation. Therefore, the SLAAC addresses are possible during installation. Therefore, the SLAAC addresses are
used in this section. used in this section.
For discovery, the resource types (rt) of the devices are important. For discovery, the resource types (rt) of the devices are important.
The lamps in the luminaries have rt: light, and the presence sensor The lamps in the luminaries have rt: light, and the presence sensor
has rt: p-sensor. The endpoints have names which are relevant to the has rt: p-sensor. The endpoints have names which are relevant to the
light installation manager. In this case luminary1, luminary2, and light installation manager. In this case luminary1, luminary2, and
the presence sensor are located in room 2-4-015, where luminary1 is the presence sensor are located in room 2-4-015, where luminary1 is
located at the window and luminary2 and the presence sensor are located at the window and luminary2 and the presence sensor are
located at the door. The endpoint names reflect this physical located at the door. The endpoint names reflect this physical
location. The middle, left and right lamps are accessed via path location. The middle, left and right lamps are accessed via path
/light/middle, /light/left, and /light/right respectively. The /light/middle, /light/left, and /light/right respectively. The
identifiers relevant to the Resource Directory are shown in Table 3 identifiers relevant to the Resource Directory are shown in Table 4
below: below:
+----------------+------------------+---------------+---------------+ +----------------+------------------+---------------+---------------+
| Name | endpoint | resource path | resource type | | Name | endpoint | resource path | resource type |
+----------------+------------------+---------------+---------------+ +----------------+------------------+---------------+---------------+
| luminary1 | lm_R2-4-015_wndw | /light/left | light | | luminary1 | lm_R2-4-015_wndw | /light/left | light |
| luminary1 | lm_R2-4-015_wndw | /light/middle | light | | luminary1 | lm_R2-4-015_wndw | /light/middle | light |
| luminary1 | lm_R2-4-015_wndw | /light/right | light | | luminary1 | lm_R2-4-015_wndw | /light/right | light |
| luminary2 | lm_R2-4-015_door | /light/left | light | | luminary2 | lm_R2-4-015_door | /light/left | light |
| luminary2 | lm_R2-4-015_door | /light/middle | light | | luminary2 | lm_R2-4-015_door | /light/middle | light |
| luminary2 | lm_R2-4-015_door | /light/right | light | | luminary2 | lm_R2-4-015_door | /light/right | light |
| Presence | ps_R2-4-015_door | /ps | p-sensor | | Presence | ps_R2-4-015_door | /ps | p-sensor |
| sensor | | | | | sensor | | | |
+----------------+------------------+---------------+---------------+ +----------------+------------------+---------------+---------------+
Table 3: Resource Directory identifiers Table 4: Resource Directory identifiers
The CT inserts the endpoints of the luminaries and the sensor in the The CT inserts the endpoints of the luminaries and the sensor in the
RD using the Context parameter (con) to specify the interface RD using the Context parameter (con) to specify the interface
address: address:
Req: POST coap://[FDFD::ABCD:0]/rd Req: POST coap://[FDFD::ABCD:0]/rd
?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1] ?ep=lm_R2-4-015_wndw&con=coap://[FDFD::ABCD:1]
Payload: Payload:
</light/left>;rt="light"; d="R2-4-015", </light/left>;rt="light"; d="R2-4-015",
</light/middle>;rt="light"; d="R2-4-015", </light/middle>;rt="light"; d="R2-4-015",
skipping to change at page 42, line 44 skipping to change at page 41, line 6
because filtering on "ep" name is more awkward. The same domain name because filtering on "ep" name is more awkward. The same domain 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 Context parameter is set to The group is specified in the RD. The Context parameter is set to
the site-local multicast address allocated to the group. In the POST the site-local multicast address allocated to the group. In the POST
in the example below, these two endpoints and the endpoint of the in the example below, these two endpoints and the endpoint of the
presence sensor are registered as members of the group. presence sensor are registered as members of the group.
Req: POST coap://[FDFD::ABCD:0]/rd-group Req: POST coap://[FDFD::ABCD:0]/rd-group
?gp=grp_R2-4-015;con="coap//[FF05::1]";exp;ins="grp1234" ?gp=grp_R2-4-015;con="coap//[FF05::1]"
Payload: Payload:
<>ep=lm_R2-4-015_wndw, <>ep=lm_R2-4-015_wndw,
<>ep=lm_R2-4-015_door, <>ep=lm_R2-4-015_door,
<>ep=ps_R2-4-015_door <>ep=ps_R2-4-015_door
Res: 2.01 Created Res: 2.01 Created
Location: /rd-group/501 Location: /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 domain, queries the RD for the endpoint The luminary, knowing its domain, queries the RD for the endpoint
with rt=light and d=R2-4-015. The RD returns all endpoints in the with rt=light and d=R2-4-015. The RD returns all endpoints in the
domain. domain.
Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep Req: GET coap://[FDFD::ABCD:0]/rd-lookup/ep
?d=R2-4-015;rt=light ?d=R2-4-015;rt=light
skipping to change at page 44, line 5 skipping to change at page 42, line 16
Content-Format: application/coap-group+json Content-Format: application/coap-group+json
{ "a": "[FF05::1]", { "a": "[FF05::1]",
"n": "grp_R2-4-015"} "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.
13.1.3. DNS entries 10.2. OMA Lightweight M2M (LWM2M) Example
It may be profitable to discover the light groups for applications,
which are unaware ot the existence of the RD. An agent needs to
query the RD to return all groups which are exported to be inserted
into DNS.
Req: GET /rd-lookup/gp?exp
Res: 2.05 Content
<coap://[FF05::1]/>;exp;gp="grp_R2-4-015;ins="grp1234";
ep="lm_R2-4-015_wndw";
ep="lm_R2-4-015_door
The group with FQDN grp_R2-4-015.bc.example.com can be entered into
the DNS by the agent. The accompanying instance name is grp1234.
The <ServiceType> is chosen to be _group._udp. The agent enters the
following RRs into the DNS.
grp_R2-4-015.bc.example.com. IN AAAA FF05::1
_group._udp.bc.example.com IN PTR
grp1234._group._udp.bc.example.com
grp1234._group._udp.bc.example.com IN SRV 0 0 5683
grp_R2-4-015_door.bc.example.com.
grp1234._group._udp.bc.example.com IN TXT
txtver=1;path=/light/grp1
From then on applications, not familiar with the existence of the RD,
can use DNS to access the lighting group.
13.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.
An LWM2M server is an instance of an LWM2M middleware service layer, An LWM2M server is an instance of an LWM2M middleware service layer,
skipping to change at page 45, line 10 skipping to change at page 42, line 38
defined by the LWM2M specification. defined by the LWM2M specification.
CoRE Resource Directory (RD) is used to provide the LWM2M CoRE Resource Directory (RD) is used to provide the LWM2M
Registration interface. Registration interface.
LWM2M does not provide for registration domains and does not LWM2M does not provide for registration domains and does not
currently use the rd-group or rd-lookup interfaces. currently use the rd-group or rd-lookup interfaces.
The LWM2M specification describes a set of interfaces and a resource The LWM2M specification describes a set of interfaces and a resource
model used between a LWM2M device and an LWM2M server. Other model used between a LWM2M device and an LWM2M server. Other
interfaces, proxies, applications, and function sets are currently interfaces, proxies, and applications are currently out of scope for
out of scope for LWM2M. LWM2M.
The location of the LWM2M Server and RD Function Set is provided by The location of the LWM2M Server and RD base URI path is provided by
the LWM2M Bootstrap process, so no dynamic discovery of the RD the LWM2M Bootstrap process, so no dynamic discovery of the RD is
function set is used. LWM2M Servers and endpoints are not required used. LWM2M Servers and endpoints are not required to implement the
to implement the ./well-known/core resource. ./well-known/core resource.
13.2.1. The LWM2M Object Model 10.2.1. The LWM2M Object Model
The OMA LWM2M object model is based on a simple 2 level class The OMA LWM2M object model is based on a simple 2 level class
hierarchy consisting of Objects and Resources. hierarchy consisting of Objects and Resources.
An LWM2M Resource is a REST endpoint, allowed to be a single value or An LWM2M Resource is a REST endpoint, allowed to be a single value or
an array of values of the same data type. an array of values of the same data type.
An LWM2M Object is a resource template and container type that An LWM2M Object is a resource template and container type that
encapsulates a set of related resources. An LWM2M Object represents encapsulates a set of related resources. An LWM2M Object represents
a specific type of information source; for example, there is a LWM2M a specific type of information source; for example, there is a LWM2M
skipping to change at page 45, line 50 skipping to change at page 43, line 29
{/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource- {/base-uri}{/object-id}{/object-instance}{/resource-id}{/resource-
instance} instance}
The five variables given here are strings. base-uri can also have The five variables given here are strings. base-uri can also have
the special value "undefined" (sometimes called "null" in RFC 6570). the special value "undefined" (sometimes called "null" in RFC 6570).
Each of the variables object-instance, resource-id, and resource- Each of the variables object-instance, resource-id, and resource-
instance can be the special value "undefined" only if the values instance can be the special value "undefined" only if the values
behind it in this sequence also are "undefined". As a special case, behind it in this sequence also are "undefined". As a special case,
object-instance can be "empty" (which is different from "undefined") object-instance can be "empty" (which is different from "undefined")
if resource-id is not "undefined". [_TEMPLATE_TODO] if resource-id is not "undefined".
base-uri := Base URI for LWM2M resources or "undefined" for default base-uri := Base URI for LWM2M resources or "undefined" for default
(empty) base URI (empty) base URI
object-id := OMNA (OMA Name Authority) registered object ID (0-65535) object-id := OMNA (OMA Name Authority) registered object ID (0-65535)
object-instance := Object instance identifier (0-65535) or object-instance := Object instance identifier (0-65535) or
"undefined"/"empty" (see above)) to refer to all instances of an "undefined"/"empty" (see above)) to refer to all instances of an
object ID object ID
resource-id := OMNA (OMA Name Authority) registered resource ID resource-id := OMNA (OMA Name Authority) registered resource ID
skipping to change at page 46, line 24 skipping to change at page 44, line 4
(0-65535) or "undefined" to refer to all resources within an instance (0-65535) or "undefined" to refer to all resources within an instance
resource-instance := Resource instance identifier or "undefined" to resource-instance := Resource instance identifier or "undefined" to
refer to single instance of a resource refer to single instance of a resource
LWM2M IDs are 16 bit unsigned integers represented in decimal (no LWM2M IDs are 16 bit unsigned integers represented in decimal (no
leading zeroes except for the value 0) by URI format strings. For leading zeroes except for the value 0) by URI format strings. For
example, a LWM2M URI might be: example, a LWM2M URI might be:
/1/0/1 /1/0/1
The base uri is empty, the Object ID is 1, the instance ID is 0, the The base uri is empty, the Object ID is 1, the instance ID is 0, the
resource ID is 1, and the resource instance is "undefined". This resource ID is 1, and the resource instance is "undefined". This
example URI points to internal resource 1, which represents the example URI points to internal resource 1, which represents the
registration lifetime configured, in instance 0 of a type 1 object registration lifetime configured, in instance 0 of a type 1 object
(LWM2M Server Object). (LWM2M Server Object).
13.2.2. LWM2M Register Endpoint 10.2.2. LWM2M Register Endpoint
LWM2M defines a registration interface based on the Resource LWM2M defines a registration interface based on the REST API,
Directory Function Set, described in Section 6. The URI of the LWM2M described in Section 5. The base URI path of the LWM2M Resource
Resource Directory function set is specified to be "/rd" as Directory is specified to be "/rd" as recommended in Section 5.3.
recommended in Section 6.3.
LWM2M endpoints register object IDs, for example </1>, to indicate LWM2M endpoints register object IDs, for example </1>, to indicate
that a particular object type is supported, and register object that a particular object type is supported, and register object
instances, for example </1/0>, to indicate that a particular instance instances, for example </1/0>, to indicate that a particular instance
of that object type exists. of that object type exists.
Resources within the LWM2M object instance are not registered with Resources within the LWM2M object instance are not registered with
the RD, but may be discovered by reading the resource links from the the RD, but may be discovered by reading the resource links from the
object instance using GET with a CoAP Content-Format of application/ object instance using GET with a CoAP Content-Format of application/
link-format. Resources may also be read as a structured object by link-format. Resources may also be read as a structured object by
performing a GET to the object instance with a Content-Format of performing a GET to the object instance with a Content-Format of
senml+json. senml+json.
When an LWM2M object or instance is registered, this indicates to the When an LWM2M object or instance is registered, this indicates to the
LWM2M server that the object and its resources are available for LWM2M server that the object and its resources are available for
management and service enablement (REST API) operations. management and service enablement (REST API) operations.
LWM2M endpoints may use the following RD registration parameters as LWM2M endpoints may use the following RD registration parameters as
defined in Table 1 : defined in Table 2 :
ep - Endpoint Name ep - Endpoint Name
lt - registration lifetime lt - registration lifetime
Endpoint Name is mandatory, all other registration parameters are Endpoint Name is mandatory, all other registration parameters are
optional. optional.
Additional optional LWM2M registration parameters are defined: Additional optional LWM2M registration parameters are defined:
+------------+-------+-------------------------------+--------------+ +------------+-------+-------------------------------+--------------+
skipping to change at page 47, line 32 skipping to change at page 45, line 17
+------------+-------+-------------------------------+--------------+ +------------+-------+-------------------------------+--------------+
| Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available | | Protocol | b | {"U",UQ","S","SQ","US","UQS"} | Available |
| Binding | | | Protocols | | Binding | | | Protocols |
| | | | | | | | | |
| LWM2M | ver | 1.0 | Spec Version | | LWM2M | ver | 1.0 | Spec Version |
| Version | | | | | Version | | | |
| | | | | | | | | |
| SMS Number | sms | | MSISDN | | SMS Number | sms | | MSISDN |
+------------+-------+-------------------------------+--------------+ +------------+-------+-------------------------------+--------------+
Table 4: LWM2M Additional Registration Parameters Table 5: LWM2M Additional Registration Parameters
The following RD registration parameters are not currently specified The following RD registration parameters are not currently specified
for use in LWM2M: for use in LWM2M:
et - Endpoint Type et - Endpoint Type
con - Context con - Context
The endpoint registration must include a payload containing links to The endpoint registration must include a payload containing links to
all supported objects and existing object instances, optionally all supported objects and existing object instances, optionally
including the appropriate link-format relations. including the appropriate link-format relations.
skipping to change at page 48, line 5 skipping to change at page 45, line 39
Here is an example LWM2M registration payload: Here is an example LWM2M registration payload:
</1>,</1/0>,</3/0>,</5> </1>,</1/0>,</3/0>,</5>
This link format payload indicates that object ID 1 (LWM2M Server This link format payload indicates that object ID 1 (LWM2M Server
Object) is supported, with a single instance 0 existing, object ID 3 Object) is supported, with a single instance 0 existing, object ID 3
(LWM2M Device object) is supported, with a single instance 0 (LWM2M Device object) is supported, with a single instance 0
existing, and object 5 (LWM2M Firmware Object) is supported, with no existing, and object 5 (LWM2M Firmware Object) is supported, with no
existing instances. existing instances.
13.2.3. Alternate Base URI 10.2.3. LWM2M Update Endpoint Registration
If the LWM2M endpoint exposes objects at a base URI other than the
default empty base path, the endpoint must register the base URI
using rt="oma.lwm2m". An example link payload using alternate base
URI would be:
</my_lwm2m>;rt="oma.lwm2m",</my_lwm2m/1>,<my_lwm2m/1/0>,<my_lwm2m/5>
This link payload indicates that the lwm2m objects will be placed
under the base URI "/my_lwm2m" and that object ID 1 (server) is
supported, with a single instance 0 existing, and object 5 (firmware
update) is supported.
13.2.4. LWM2M Update Endpoint Registration
An LWM2M Registration update proceeds as described in Section 6.4, An LWM2M Registration update proceeds as described in Section 5.4.1,
and adds some optional parameter updates: and adds some optional parameter updates:
lt - Registration Lifetime lt - Registration Lifetime
b - Protocol Binding b - Protocol Binding
sms - MSISDN sms - MSISDN
link payload - new or modified links link payload - new or modified links
A Registration update is also specified to be used to update the A Registration update is also specified to be used to update the
LWM2M server whenever the endpoint's UDP port or IP address are LWM2M server whenever the endpoint's UDP port or IP address are
changed. changed.
13.2.5. LWM2M De-Register Endpoint 10.2.4. LWM2M De-Register Endpoint
LWM2M allows for de-registration using the delete method on the LWM2M allows for de-registration using the delete method on the
returned location from the initial registration operation. LWM2M de- returned location from the initial registration operation. LWM2M de-
registration proceeds as described in Section 6.5. registration proceeds as described in Section 5.4.2.
14. Acknowledgments 11. Acknowledgments
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, Mohit Sethi, Sampo Ukkola and Linyi Tian have Brandt, Matthieu Vial, Mohit Sethi, Sampo Ukkola, Linyi Tian,
provided helpful comments, discussions and ideas to improve and shape Chistian Amsuss, and Jan Newmarch have provided helpful comments,
this document. Section 9 is based on an earlier draft by Kerry Lynn. discussions and ideas to improve and shape this document. Zach would
Zach would also like to thank his colleagues from the EU FP7 SENSEI also like to thank his colleagues from the EU FP7 SENSEI project,
project, where many of the resource directory concepts were where many of the resource directory concepts were originally
originally developed. developed.
15. Changelog 12. Changelog
changes from -09 to -10
o removed "ins" and "exp" link-format extensions.
o removed all text concerning DNS-SD.
o removed inconsistency in RDAO text.
o suggestions taken over from various sources
o replaced "Function Set" with "REST API", "base URI", "base path"
o moved simple registration to registration section
changes from -08 to -09 changes from -08 to -09
o clarified the "example use" of the base RD resource values /rd, o clarified the "example use" of the base RD resource values /rd,
/rd-lookup, and /rd-group. /rd-lookup, and /rd-group.
o changed "ins" ABNF notation. o changed "ins" ABNF notation.
o various editorial improvements, including in examples o various editorial improvements, including in examples
skipping to change at page 52, line 35 skipping to change at page 50, line 18
o Added the concept of an RD Domain and a registration parameter for o Added the concept of an RD Domain and a registration parameter for
it. it.
o Recommended the Location returned from a registration to be o Recommended the Location returned from a registration to be
stable, allowing for endpoint and Domain information to be changed stable, allowing for endpoint and Domain information to be changed
during updates. during updates.
o Changed the lookup interface to accept endpoint and Domain as o Changed the lookup interface to accept endpoint and Domain as
query string parameters to control the scope of a lookup. query string parameters to control the scope of a lookup.
16. References 13. References
16.1. Normative References 13.1. Normative References
[I-D.ietf-core-links-json] [I-D.ietf-core-links-json]
Li, K., Rahman, A., and C. Bormann, "Representing CoRE Li, K., Rahman, A., and C. Bormann, "Representing CoRE
Formats in JSON and CBOR", draft-ietf-core-links-json-06 Formats in JSON and CBOR", draft-ietf-core-links-json-06
(work in progress), July 2016. (work in progress), July 2016.
[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, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 53, line 14 skipping to change at page 50, line 46
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008, DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. <http://www.rfc-editor.org/info/rfc5226>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>. <http://www.rfc-editor.org/info/rfc5988>.
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
Cheshire, "Internet Assigned Numbers Authority (IANA)
Procedures for the Management of the Service Name and
Transport Protocol Port Number Registry", BCP 165,
RFC 6335, DOI 10.17487/RFC6335, August 2011,
<http://www.rfc-editor.org/info/rfc6335>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012, DOI 10.17487/RFC6570, March 2012,
<http://www.rfc-editor.org/info/rfc6570>. <http://www.rfc-editor.org/info/rfc6570>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>. <http://www.rfc-editor.org/info/rfc6690>.
[RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013,
<http://www.rfc-editor.org/info/rfc6763>.
[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
DOI 10.17487/RFC7396, October 2014, DOI 10.17487/RFC7396, October 2014,
<http://www.rfc-editor.org/info/rfc7396>. <http://www.rfc-editor.org/info/rfc7396>.
16.2. Informative References 13.2. Informative References
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
<http://www.rfc-editor.org/info/rfc1034>.
[RFC1123] Braden, R., Ed., "Requirements for Internet Hosts -
Application and Support", STD 3, RFC 1123,
DOI 10.17487/RFC1123, October 1989,
<http://www.rfc-editor.org/info/rfc1123>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
<http://www.rfc-editor.org/info/rfc5198>.
[RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C. [RFC6775] Shelby, Z., Ed., Chakrabarti, S., Nordmark, E., and C.
Bormann, "Neighbor Discovery Optimization for IPv6 over Bormann, "Neighbor Discovery Optimization for IPv6 over
Low-Power Wireless Personal Area Networks (6LoWPANs)", Low-Power Wireless Personal Area Networks (6LoWPANs)",
RFC 6775, DOI 10.17487/RFC6775, November 2012, RFC 6775, DOI 10.17487/RFC6775, November 2012,
<http://www.rfc-editor.org/info/rfc6775>. <http://www.rfc-editor.org/info/rfc6775>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
skipping to change at page 54, line 30 skipping to change at page 51, line 36
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for [RFC7390] Rahman, A., Ed. and E. Dijk, Ed., "Group Communication for
the Constrained Application Protocol (CoAP)", RFC 7390, the Constrained Application Protocol (CoAP)", RFC 7390,
DOI 10.17487/RFC7390, October 2014, DOI 10.17487/RFC7390, October 2014,
<http://www.rfc-editor.org/info/rfc7390>. <http://www.rfc-editor.org/info/rfc7390>.
Editorial Comments
[_TEMPLATE_TODO] This text needs some help from an RFC 6570 expert.
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
 End of changes. 139 change blocks. 
741 lines changed or deleted 603 lines changed or added

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