Constrained Objects Language
draft-veillette-core-cool-00
The information below is for an old version of the document.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Michel Veillette , Alexander Pelov | ||
| Last updated | 2015-11-01 | ||
| Stream | (None) | ||
| Formats | plain text pdf htmlized pdfized bibtex | ||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-veillette-core-cool-00
Internet Engineering Task Force M. Veillette, Ed.
Internet-Draft Trilliant Networks Inc.
Intended status: Informational A. Pelov, Ed.
Expires: May 4, 2016 Acklio
S. Somaraju
Tridonic GmbH & Co KG
R. Somaraju
Landis+Gyr
November 1, 2015
Constrained Objects Language
draft-veillette-core-cool-00
Abstract
This document describes a management interface adapted to constrained
devices and constrained (e.g., low-power, lossy) networks. CoOL
resources (datastores, protocol operations and notifications) are
defined using the YANG modelling language [RFC6020]. Interactions
with these resources are performed using the CoAP web transfer
protocol [RFC7252]. Payloads and specific CoAP options are encoded
using the CBOR data format [RFC7049].
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 4, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
Veillette, et al. Expires May 4, 2016 [Page 1]
Internet-Draft Constrained Objects Language November 2015
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 5
3. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 5
4. Textual representation of CBOR contents . . . . . . . . . . . 6
5. YANG to CBOR mapping . . . . . . . . . . . . . . . . . . . . 7
5.1. YANG leaf . . . . . . . . . . . . . . . . . . . . . . . . 8
5.1.1. YANG type: binary . . . . . . . . . . . . . . . . . . 8
5.1.2. YANG type: bits . . . . . . . . . . . . . . . . . . . 8
5.1.3. YANG type: boolean . . . . . . . . . . . . . . . . . 9
5.1.4. YANG type: decimal64 . . . . . . . . . . . . . . . . 9
5.1.5. YANG type: empty . . . . . . . . . . . . . . . . . . 9
5.1.6. YANG type: enumeration . . . . . . . . . . . . . . . 10
5.1.7. YANG type: identityref . . . . . . . . . . . . . . . 10
5.1.8. YANG type: instance-identifier . . . . . . . . . . . 11
5.1.9. YANG type: int8, int16, int32, int64 . . . . . . . . 13
5.1.10. YANG type: leafref . . . . . . . . . . . . . . . . . 13
5.1.11. YANG type: string . . . . . . . . . . . . . . . . . . 14
5.1.12. YANG type: uint8, uint16, uint32, uint64 . . . . . . 14
5.1.13. YANG type: union . . . . . . . . . . . . . . . . . . 14
5.1.14. YANG type: anyxml . . . . . . . . . . . . . . . . . . 15
5.1.15. YANG type: container . . . . . . . . . . . . . . . . 16
5.1.16. YANG type: leaf-list . . . . . . . . . . . . . . . . 17
5.1.17. YANG type: list . . . . . . . . . . . . . . . . . . . 18
5.1.18. YANG type: choice . . . . . . . . . . . . . . . . . . 20
6. Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . 20
6.1. Module ID . . . . . . . . . . . . . . . . . . . . . . . . 21
6.2. Data node ID (DNID) . . . . . . . . . . . . . . . . . . . 21
6.3. Fully-qualified data node ID (FQDNID) . . . . . . . . . . 22
6.4. Notification ID . . . . . . . . . . . . . . . . . . . . . 23
6.5. Notification parameter ID . . . . . . . . . . . . . . . . 23
6.6. Protocol operation ID . . . . . . . . . . . . . . . . . . 24
6.7. Input parameter ID . . . . . . . . . . . . . . . . . . . 24
6.8. Output parameter ID . . . . . . . . . . . . . . . . . . . 25
6.9. Identifier examples . . . . . . . . . . . . . . . . . . . 26
7. Protocol details . . . . . . . . . . . . . . . . . . . . . . 30
7.1. Retrieving data node(s) . . . . . . . . . . . . . . . . . 30
7.2. The Fields CoAP option . . . . . . . . . . . . . . . . . 32
Veillette, et al. Expires May 4, 2016 [Page 2]
Internet-Draft Constrained Objects Language November 2015
7.3. Retrieving all data nodes . . . . . . . . . . . . . . . . 32
7.4. Updating data node(s) . . . . . . . . . . . . . . . . . . 34
7.5. Retrieving data node(s) from a list . . . . . . . . . . . 35
7.6. Retrieving multiple entries from a list . . . . . . . . . 37
7.7. Retrieving multiple entries of a single data node from a
list . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.8. Updating a list entry . . . . . . . . . . . . . . . . . . 39
7.9. Adding a list entry . . . . . . . . . . . . . . . . . . . 41
7.10. Deleting list entries . . . . . . . . . . . . . . . . . . 42
7.11. Patch . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.12. Protocol operation . . . . . . . . . . . . . . . . . . . 45
7.13. Event stream . . . . . . . . . . . . . . . . . . . . . . 46
7.14. Observe . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.15. Resource discovery . . . . . . . . . . . . . . . . . . . 50
7.16. Modules, sub-modules, and objects discovery . . . . . . . 51
8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 53
9. Security Considerations . . . . . . . . . . . . . . . . . . . 54
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54
10.1. Module ID . . . . . . . . . . . . . . . . . . . . . . . 54
10.2. "Fields" CoAP Option Number . . . . . . . . . . . . . . 55
10.3. "PATCH" CoAP Method Code . . . . . . . . . . . . . . . . 55
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 55
11.1. Normative References . . . . . . . . . . . . . . . . . . 56
11.2. Informative References . . . . . . . . . . . . . . . . . 56
Appendix A. ietf-cool YANG module . . . . . . . . . . . . . . . 57
Appendix B. ietf-cool-library YANG module . . . . . . . . . . . 64
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68
1. Introduction
CoOL is based on the current [I-D.vanderstok-core-comi] draft but
instead of using YANG hashes to identify objects, CoOL uses
structured identifiers. This approach reduces both message size and
implementation footprints. This approach facilitates its use in both
centralized (e.g. Network Management System, Path Computation
Element), and decentralized scenarios.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This specification makes use of the following terminology:
o CoOL client: The originating endpoint of a request, and the
destination endpoint of a response.
Veillette, et al. Expires May 4, 2016 [Page 3]
Internet-Draft Constrained Objects Language November 2015
o CoOL server: The destination endpoint of a request, and the
originating endpoint of a response.
o Data node: A node in the YANG schema that can be instantiated in a
Datastore. One of container, leaf, leaf-list, list, or anyxml.
o Data node ID (DNID): Identifier automatically or manually assigned
to a data node. This identifier is unique within the scope of a
YANG module.
o Data tree: Hierarchy of instantiated data nodes.
o Child data node: A data node defined within a container or a list
is a child of this container or list. The container or list is
the parent of the data node.
o Datastore resource: Resource used to store and access information.
o Endpoint: An entity participating in the CoOL protocol. Multiple
CoOL endpoints may be accessible using a single CoAP endpoint. In
this case, each CoOL enpoint is accessed using a distinct URI.
o Event stream resource: Resource used to access event notifications
generated by a CoOL server. Events are defined using the YANG
notification statement.
o Fully qualified data node ID (FQDNID): Concatenation of the Module
ID and the Data node ID. This identifier uniquely identifies a
data node.
o Identifier: An identifier embodies the information required to
distinguish what is being identified from all other things within
its scope of identification.
o Instance selector: A CBOR array containing the information
required to identify one or multiple entries within a YANG list.
o Module ID: Registered identifier assigned to a YANG module.
o Notification ID: Identifier automatically or manually assigned to
a YANG notification. This identifier is unique within the scope
of a YANG module.
o Object: Within CoOL, objects are a data node within a datastore
resource, an RPC within a protocol operation resource, or a
notification within an event stream resource.
o Parent data node: See Child data node.
Veillette, et al. Expires May 4, 2016 [Page 4]
Internet-Draft Constrained Objects Language November 2015
o Protocol operation resource: Resource used to invoke remote
procedure calls as defined by the YANG "rpc" statement.
o Protocol operation ID: Identifier automatically or manually
assigned to a YANG "rpc". This identifier is unique within the
scope of a YANG module.
o Resource: Content identified by a URI.
o Schema tree: Hierarchy of data nodes specified within a module.
2. Architecture
The CoOL protocol is based on the client-server model. The CoOL
server is the provider of the datastore resource, the protocol
operation resource, and the notification resource. The CoOL client
is the requester of these resources.
CoOL objects are defined using the YANG modeling language [RFC6020].
Interactions with these objects are performed using the Constrained
Application Protocol (CoAP) [RFC7252]. Payloads are encoded using
the Concise Binary Object Representation (CBOR) [RFC7049].
This specification is applicable to any transport or security
protocols supported by CoAP. Implementers are free to select the
most appropriate transport for the targeted applications.
+--------------+ +----------------------------------+
| CoOL client | | CoOL Server |
| | | - Datastore resource(s) |
| | | - Event stream resource(s) |
| | | - Protocol operation resource(s) |
+--------------+ +----------------------------------+
| CoAP client | <-------> | CoAP Server |
+--------------+ +----------------------------------+
| | | |
| Lower layers | | Lower layers |
| | | |
+--------------+ +----------------------------------+
3. CoAP Interface
This section lists the URIs recommended for the different CoOL
resources. A CoOL server MAY implement a different set of URIs.
(See the Resource discovery section (Section 7.15) for more details
on how a CoOL client can discover the list of URIs supported by a
CoOL server using the "/.well-known/core" resource.)
Veillette, et al. Expires May 4, 2016 [Page 5]
Internet-Draft Constrained Objects Language November 2015
o /cool - URI used to access the datastore resource of the default
endpoint.
o /cool/rpc - URI used to access the protocol operation resource of
the default endpoint.
o /cool/ep0, /cool/ep1, ... - URI used to access the datastore
resource of a specific endpoint.
o /cool/ep0/rpc, /cool/ep1/rpc, ... - URI used to access the
protocol operation resource of a specific endpoint.
o /cool/stream - URI used to access the default event stream for
this device.
o /cool/ep0/stream, /cool/ep1/stream, ... - URI used to access the
default event stream of a specific endpoint.
o /cool/stream/0, /cool/stream/1, ... - URI used to access alternate
event streams.
Support of endpoints and event streams are optional. The CoAP
response code 4.04 (Not Found) MUST be returned when a CoOL client
tries to access a resource that is unavailable.
4. Textual representation of CBOR contents
CoOL encodes payloads and the "Fields" CoAP option using the Concise
Binary Object Representation (CBOR) as defined by [RFC7049]. Within
this document, this binary encoding is represented using an
equivalent textual form. This textual form is used strictly for
documentation purposes and is never transmitted as such.
Veillette, et al. Expires May 4, 2016 [Page 6]
Internet-Draft Constrained Objects Language November 2015
The following table summarizes this representation. To facilitate
its understanding, this representation follows the JSON syntax (when
possible).
+----------+------+--------------------------+-----------+----------+
| CBOR | CBOR | Text representation | Example | CBOR |
| content | type | | | encoding |
+----------+------+--------------------------+-----------+----------+
| Unsigned | 0 | Decimal digits | 123 | 18 7b |
| integer | | | | |
| | | | | |
| Negative | 1 | Decimal digits prefixed | -123 | 38 7a |
| integer | | by a minus sign. | | |
| | | | | |
| Byte | 2 | Hexadecimal value | h' f15c' | 42 f15c |
| string | | enclosed between single | | |
| | | quotes and prefixed by | | |
| | | an 'h'. | | |
| | | | | |
| Text | 3 | String of Unicode | "txt" | 63 |
| string | | characters enclosed | | 747874 |
| | | between double quotes | | |
| | | | | |
| Array | 4 | Comma separated list | [ 1, 2 ] | 82 01 02 |
| | | of values within | | |
| | | square brackets. | | |
| | | | | |
| Map | 5 | Comma separated list | { | a2 |
| | | of name/value pair | 1: 123, | 01187b |
| | | within curly braces. | 2: 456 | 021901c8|
| | | | } | |
| | | | | |
| Boolean | 7/20 | false | false | f4 |
| | 7/21 | true | true | f5 |
| | | | | |
| Null | 7/22 | null | null | f6 |
| | | | | |
| Not | 7/23 | undefined | undefined | f7 |
| assigned | | | | |
+----------+------+--------------------------+-----------+----------+
5. YANG to CBOR mapping
Objects defined using the YANG modeling language are encoded using
CBOR [RFC7049] based on the rules defined in this section. We assume
that the reader is already familiar with both YANG [RFC6020] and CBOR
[RFC7049].
Veillette, et al. Expires May 4, 2016 [Page 7]
Internet-Draft Constrained Objects Language November 2015
5.1. YANG leaf
The leaf statement defines a data node associated with a value. The
following subsections describe the encoding of different leaf types.
5.1.1. YANG type: binary
Leafs of type binary MUST be encoded using a CBOR byte string data
item (major type 0).
Definition example:
leaf aes128-key {
type binary {
length 16;
}
}
Textual form: h'1f1ce6a3f42660d888d92a4d8030476e'
CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e
5.1.2. YANG type: bits
Leafs of type bits MUST be encoded using a CBOR byte string data item
(major type 0). Bits position 0 to 7 are assigned to the first byte
within the byte string, bits 8 to 15 to the second byte, and
subsequent bytes are assigned similarly. Within each byte, bits are
assigned from least to most significant.
Definition example [RFC6020]:
leaf mybits {
type bits {
bit disable-nagle {
position 0;
}
bit auto-sense-speed {
position 1;
}
bit 10-Mb-only {
position 2;
}
}
}
Textual form: h'05' (Represents bits disable-nagle and 10-Mb-only
set)
Veillette, et al. Expires May 4, 2016 [Page 8]
Internet-Draft Constrained Objects Language November 2015
CBOR encoding: 41 05
5.1.3. YANG type: boolean
Leafs of type boolean MUST be encoded using a CBOR true (major type
7, additional information 21) or false data item (major type 7,
additional information 20).
Definition example [RFC7317]:
leaf enabled {
type boolean;
}
Textual form: true
CBOR encoding: f5
5.1.4. YANG type: decimal64
Leafs of type decimal64 MUST be encoded using a CBOR unsigned integer
data item (major type 0).
Definition example [RFC7317]:
leaf my-decimal {
type decimal64 {
fraction-digits 2;
range "1 .. 3.14 | 10 | 20..max";
}
}
Textual form: 257 (Represents decimal value 2.57)
CBOR encoding: 19 0101
5.1.5. YANG type: empty
Leafs of type empty MUST be encoded using the CBOR null value (major
type 7, additional information 22).
Definition example [RFC7277]:
leaf is-router {
type empty;
}
Textual form: null
Veillette, et al. Expires May 4, 2016 [Page 9]
Internet-Draft Constrained Objects Language November 2015
CBOR encoding: f6
5.1.6. YANG type: enumeration
Leafs of type enumeration MUST be encoded using a CBOR unsigned
integer data item (major type 0).
Definition example [RFC7317]:
leaf oper-status {
type enumeration {
enum up { value 1; }
enum down { value 2; }
enum testing { value 3; }
enum unknown { value 4; }
enum dormant { value 5; }
enum not-present { value 6; }
enum lower-layer-down { value 7; }
}
}
Textual form: 3 (Represents enumeration value "testing")
CBOR encoding: 03
5.1.7. YANG type: identityref
Leafs of type identityref MUST be encoded using a CBOR text string
data item (major type 3). Unlike XML, CBOR does not support
namespaces. To overcome this limitation, identities are encoded
using a concatenation of the identity name(s) of the referenced
identities, excluding the base identity and separated by dot(s).
Veillette, et al. Expires May 4, 2016 [Page 10]
Internet-Draft Constrained Objects Language November 2015
Definition example [RFC7223]:
identity interface-type {
}
identity iana-interface-type {
base interface-type;
}
identity ethernetCsmacd {
base iana-interface-type;
}
leaf type {
type identityref {
base interface-type;
}
}
Textual form: "iana-interface-type.ethernetCsmacd"
CBOR encoding: 78 22
69616e612d696e746572666163652d747970652e65746865726e657443736d616364
5.1.8. YANG type: instance-identifier
When a leaf node of type instance-identifier identifies a single
instance data node (data node not part of a list), its value MUST be
encoded using a CBOR unsigned integer data item (major type 0)
containing the targeted data node ID.
Definition example [RFC7317]:
container system {
leaf contact {
type string;
}
leaf hostname {
type inet:domain-name;
}
}
Textual form: 69635
CBOR encoding: 1a 00011003
Veillette, et al. Expires May 4, 2016 [Page 11]
Internet-Draft Constrained Objects Language November 2015
In this example, the value 69635 identifies the instance of the data
node "hostname" within the ietf-system module. Assuming module ID =
68 and data node ID = 3.
When a leaf node of type instance-identifier identifies a data node
supporting multiple instances (data node part of a list), its value
MUST be encoded using a CBOR array data item (major type 4)
containing the following entries:
o a CBOR unsigned integer data item (major type 0) containing the
fully-qualified data node ID of the targeted data node.
o a CBOR array data item (major type 4) containing the value of each
key required to identify the instance of the targeted data node.
These keys MUST be ordered as defined in the "key" YANG statement,
starting from top level list, and follow by each of the
subordinate list(s).
Definition example [RFC7317]:
list user {
key name;
leaf name {
type string;
}
leaf password {
type ianach:crypt-hash;
}
list authorized-key {
key name;
leaf name {
type string;
}
leaf algorithm {
type string;
}
leaf key-data {
type binary;
}
}
Textual form: [69679, ["bob", "admin"]]
CBOR encoding: 82 1a 0001102f 82 63 626f62 65 61646d696e
Veillette, et al. Expires May 4, 2016 [Page 12]
Internet-Draft Constrained Objects Language November 2015
This example identifies the instance of the data node "key-data"
within the ietf-system module, associated with user name "bob" and
authorized-key name "admin". Assuming module ID = 68 and data node
ID = 47.
5.1.9. YANG type: int8, int16, int32, int64
Leafs of type int8, int16, int32 and int64 MUST be encoded using
either CBOR unsigned integer (major type 0) or CBOR signed integer
(major type 0), depending on the actual value.
Definition example [RFC7317]:
leaf timezone-utc-offset {
type int16 {
range "-1500 .. 1500";
}
}
Textual form: -300
CBOR encoding: 39 012b
5.1.10. YANG type: leafref
Leafs of type leafref MUST be encoded using the rules of the data
node referenced by the "path" YANG statement.
Definition example [RFC7223]:
typedef interface-state-ref {
type leafref {
path "/interfaces-state/interface/name";
}
}
container interfaces-state {
list interface {
key "name";
leaf name {
type string;
}
leaf-list higher-layer-if {
type interface-state-ref;
}
}
}
Veillette, et al. Expires May 4, 2016 [Page 13]
Internet-Draft Constrained Objects Language November 2015
Textual form: "eth1.10"
CBOR encoding: 67 657468312e3130
5.1.11. YANG type: string
Leafs of type string MUST be encoded using a CBOR text string data
item (major type 3).
Definition example [RFC7223]:
leaf name {
type string;
}
Textual form: "eth0"
CBOR encoding: 64 65746830
5.1.12. YANG type: uint8, uint16, uint32, uint64
Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using
a CBOR unsigned integer data item (major type 0).
Definition example [RFC7277]:
leaf mtu {
type uint16 {
range "68..max";
}
}
Textual form: 1280
CBOR encoding: 19 0500
5.1.13. YANG type: union
Leafs of type union MUST be encoded using the rules associated with
one of the type listed.
Veillette, et al. Expires May 4, 2016 [Page 14]
Internet-Draft Constrained Objects Language November 2015
Definition example [RFC7317]:
typedef ipv4-address {
type string {
pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}
([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N}
\p{L}]+)?';
}
}
typedef ipv6-address {
type string {
pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a
-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0
-9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0
-9]?[0-9])))(%[\p{N}\p{L}]+)?';
pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+)
?::(([^:]+:)*[^:]+)?)(%.+)?';
}
}
typedef ip-address {
type union {
type ipv4-address;
type ipv6-address;
}
}
leaf address {
type inet:ip-address;
}
Textual form: "[2001:db8:0:1]:80"
CBOR encoding: 71 5b323030313a6462383a303a315d3a3830
5.1.14. YANG type: anyxml
The "anyxml" statement represents an unknown data node. The encoding
of this data node MUST follow the rules of one of the YANG statements
listed in Section 5.
Definition example [RFC6020]:
anyxml data;
Textual form: 123
Veillette, et al. Expires May 4, 2016 [Page 15]
Internet-Draft Constrained Objects Language November 2015
CBOR encoding: 18 7b
Alternate value:
{
1 : 2,
2 : 55
}
CBOR encoding: a2 01 02 02 18 37
5.1.15. YANG type: container
A container MUST be encoded using a CBOR map data item (major type
5). A map is comprised of pairs of data items, with each data item
consisting of a key and a value. CBOR map keys MUST be encoded using
a CBOR unsigned integer (major type 0) and set to a data node ID or a
fully-qualified data node ID. Data node IDs MUST be used when a
parent node exists and this parent shares the same module ID as the
current data node. CBOR map values MUST be encoded using the rules
associated with the data node type.
Definition example [RFC7317]:
typedef date-and-time {
type string {
pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-]
\d{2}:\d{2})';
}
}
container clock {
leaf current-datetime {
type date-and-time;
}
leaf boot-datetime {
type date-and-time;
}
}
Veillette, et al. Expires May 4, 2016 [Page 16]
Internet-Draft Constrained Objects Language November 2015
Textual form:
{
69667 : {
36 : "2015-10-02T14:47:24Z-05:00",
37 : "2015-09-15T09:12:58Z-05:00"
}
}
CBOR encoding:
a1
1a 00011023
a2
18 24
78 1a 323031352d31302d30325431343a34373a32345a2d30353a3030
18 25
78 1a 323031352d30392d31355430393a31323a35385a2d30353a3030
In this example, we assume that the module ID = 68, data node IDs
clock = 35, current-datetime = 36 and boot-datetime 37.
5.1.16. YANG type: leaf-list
A leaf-list MUST be encoded using a CBOR array data item (major type
4). Each entry MUST be encoded using the rules defined by the type
specified.
Definition example [RFC7317]:
typedef domain-name {
type string {
length "1..253";
pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].)
*([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?
)|\.';
}
}
leaf-list search {
type domain-name;
ordered-by user;
}
Textual form: [ "ietf.org", "ieee.org" ]
CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267
Veillette, et al. Expires May 4, 2016 [Page 17]
Internet-Draft Constrained Objects Language November 2015
5.1.17. YANG type: list
A list MUST be encoded using a CBOR array data item (major type 4).
Each entry of this array is encoded using a CBOR map data item (major
type 5) following the same rules as a YANG container.
Definition example [RFC7317]:
list server {
key name;
leaf name {
type string;
}
choice transport {
case udp {
container udp {
leaf address {
type host;
mandatory true;
}
leaf port {
type port-number;
}
}
}
}
leaf association-type {
type enumeration {
enum server;
enum peer;
enum pool;
}
default server;
}
leaf iburst {
type boolean;
default false;
}
leaf prefer {
type boolean;
default false;
}
}
Veillette, et al. Expires May 4, 2016 [Page 18]
Internet-Draft Constrained Objects Language November 2015
Textual form:
{
69642 : [
{
11: "NRC TIC server",
12 : {
13: "tic.nrc.ca",
14: 123
},
15 : 0,
16 : false,
17 : true
},
{
11: "NRC TAC server",
12 : {
13: "tac.nrc.ca"
}
}
]
}
CBOR encoding:
a1
1a 0001100a
82
a5
0b 6e 4e52432054494320736572766572
0c a2
0d 6a 7469632e6e72632e6361
0e 18 7b
0f 00
10 f4
11 f5
a2
0b 6f 4e5243205441432073657276657220
0c a1
0d 6a 7461632e6e72632e6361
In this example, we assume that the module ID = 68, data node IDs
server = 10, name = 11, udp = 12, address = 13, port = 14,
association-type = 15, iburst = 16, prefer = 17.
Veillette, et al. Expires May 4, 2016 [Page 19]
Internet-Draft Constrained Objects Language November 2015
5.1.18. YANG type: choice
YANG allows the data model to segregate incompatible nodes into
distinct choices using the "choice" and "case" statements. Encoded
payload MUST carry data nodes defined in only one of the possible
cases.
Definition example [RFC7317]:
typedef timezone-name {
type string;
}
choice timezone {
case timezone-name {
leaf timezone-name {
type timezone-name;
}
}
case timezone-utc-offset {
leaf timezone-utc-offset {
type int16 {
range "-1500 .. 1500";
}
units "minutes";
}
}
}
Textual form:
{
69638 : "Europe/Stockholm"
}
CBOR encoding:
a1
1a 00011006
70
4575726f70652f53746f636b686f6c6d
6. Identifiers
All CoOL objects are associated with a unique identifier. The
uniqueness of these identifiers is guaranteed by the registration of
a module ID used as a prefix for the different manually or
automatically assigned identifiers.
Veillette, et al. Expires May 4, 2016 [Page 20]
Internet-Draft Constrained Objects Language November 2015
6.1. Module ID
A module ID is shared by all objects defined by a module. This
includes data nodes, protocol operations, and notifications defined
by a YANG module and included YANG sub-modules. Module IDs SHALL be
registered; see Section 10.1 for more details.
A registered module ID can be added to a YANG definition file using
the YANG extension module-id. Refer to Appendix A for the definition
of this extension.
Example:
module example {
import ietf-cool {
prefix "cool";
}
cool:module-id "123";
...
}
6.2. Data node ID (DNID)
Each data node defined within a YANG module and included YANG sub-
module(s) MUST be associated with a unique identifier within the
scope of this module.
Data node IDs can be assigned automatically or manually. Data node
IDs are assigned manually using the YANG extension "id". The
argument of this extension contains the path of the assigned data
node followed by the associated identifier; these two parts are
separated by a space.
Example:
cool:id "/container-name/leaf-name 5";
When assigned automatically, data nodes are numbered based on their
location in the schema tree.
o Top level data nodes are listed in the same order as defined in
the YANG module or sub-module.
Veillette, et al. Expires May 4, 2016 [Page 21]
Internet-Draft Constrained Objects Language November 2015
o Top level data nodes defined in sub-modules are listed after those
defined in the module. Sub-modules are ordered based on the order
of the include statements in the associated module.
o Data nodes within containers or lists are listed following their
parent node and in the same order as defined.
o Data nodes defined within an augment YANG statement are considered
top-level nodes and numbered accordingly.
o The "first-assigned-node-id" YANG extension can be used to control
the data node ID of the first data node automatically assigned.
When this extension is absent, the first data node ID is one.
Subsequent data nodes are assigned sequentially.
o Data node that are manually assigned are skipped.
o It is the responsibility of the module author to avoid any
conflicts between the manually and automatically assigned data
node IDs. Manually assigned identifiers MUST be either lower than
the value of "first-assigned-node-id" extension or higher than any
identifiers assigned automatically.
o When a module is updated, old Data node IDs can be preserved by
adding top level data nodes to the end of the module or by
manually assigning new data nodes within the schema tree.
o Data node ID zero is reserved for a virtual root containing all
top level objects for a module.
6.3. Fully-qualified data node ID (FQDNID)
The fully-qualified data node ID is the concatenation of the module
ID and the data node ID. A fully-qualified data node ID is globally
unique.
The fully-qualified data node ID is constructed as follows:
o Bits 0 to 9 (least significant bits) are set to the data node ID
assigned to the data node.
o Bits 10 to 29 are set to the module ID registered to the YANG
module containing the data node.
o Bits 30 to 31 are reserved and set to zero.
Data node IDs MUST be used when the module ID can be inferred from
the parent data node in a YANG container or YANG list, or from the
Veillette, et al. Expires May 4, 2016 [Page 22]
Internet-Draft Constrained Objects Language November 2015
previous ID in the array of the "Fields" CoAP option. Otherwise, the
fully qualified ID MUST be used.
6.4. Notification ID
Each notification defined MUST be associated with a unique identifier
within the scope of its associated YANG module and YANG sub-
module(s). Notification IDs can be assigned automatically or
manually.
Notification IDs can be assigned manually using the YANG extension
"id". The argument of this extension contains the path of the
assigned notification followed by the associated identifier.
Example:
cool:id "/system-status-update 1";
When assigned automatically, Notification IDs are assigned as
follows:
o Notifications are ordered based on their location in the YANG
definition file.
o Notifications defined in the sub-module are listed after those
defined in the module. Sub-modules are ordered based on the order
of the include statements in the associated module.
o The "first-assigned-notification-id" YANG extension can be used to
control the notification ID of the first notification
automatically assigned. When this extension is absent, the first
notification ID is one. Subsequent notifications are assigned
sequentially.
6.5. Notification parameter ID
Each notification parameter MUST be associated with a unique
identifier within the scope of this notification.
Notification parameter IDs can be assigned automatically or manually.
Notification parameter IDs are assigned manually using the YANG
extension "id". The argument of this extension contains the path of
the assigned notification parameter followed by the associated
identifier.
Example:
cool:id "/system-status-update/current-time 2";
Veillette, et al. Expires May 4, 2016 [Page 23]
Internet-Draft Constrained Objects Language November 2015
When assigned automatically, Notification parameter IDs are assigned
as follows:
o Top level parameters are listed in the same order as defined.
o Parameters defined within a container or a list are listed
following their parent node and in the same order as defined.
o The first parameter is assigned to ID one, subsequent parameters
are assigned sequentially.
o Manually assigned parameters are skipped.
6.6. Protocol operation ID
Each protocol operation defined MUST be associated with a unique
identifier within the scope of its associated YANG module and YANG
sub-module(s).
Protocol operation IDs can be assigned automatically or manually.
Protocol operation IDs are assigned manually using the YANG extension
"id". The argument of this extension contains the path of the
assigned protocol operation followed by the associated identifier.
Example:
cool:id "/system-shutdown 3";
When assigned automatically, Protocol operation IDs are assigned as
follows:
o RPCs are ordered based on their location in the YANG definition
file.
o RPCs defined in the sub-module are listed after those defined in
the module. Sub-modules are ordered based on the order of the
include statements in the associated module.
o The "first-assigned-rpc-id" YANG extension can be used to control
the protocol operation ID of the first RPC automatically assigned.
When this extension is absent, the first protocol operation ID is
one. Subsequent RPCs are assigned sequentially.
6.7. Input parameter ID
Each input parameter MUST be associated with a unique identifier
within the scope of the RPC input.
Veillette, et al. Expires May 4, 2016 [Page 24]
Internet-Draft Constrained Objects Language November 2015
Input parameter IDs can be assigned automatically or manually. Input
parameter IDs are assigned manually using the YANG extension "id".
The argument of this extension contains the path of the assigned
input parameter followed by the associated identifier.
Example:
cool:id "/is-supported/input/module-id 1";
When assigned automatically, Input parameter IDs are assigned as
follows:
o Top level input parameters are listed in the same order as
defined.
o Input parameters defined within a container or a list are listed
following their parent nodes and in the same order as defined.
o The first input parameter is assigned to ID one, subsequent input
parameters are assigned sequentially.
o Manually assigned input parameters are skipped.
6.8. Output parameter ID
Each output parameter MUST be associated with a unique identifier
within the scope of the RPC output.
Output parameter IDs can be assigned automatically or manually.
Output parameter IDs are assigned manually using the YANG extension
"id". The argument of this extension contains the path of the
assigned output parameter followed by the associated identifier.
Example:
cool:id " /is-supported/output/supported 1";
When assigned automatically, Output parameter IDs are assigned as
follows:
o Top level output parameters are listed in the same order as
defined.
o Output parameters defined within a container or a list are listed
following their parent node and in the same order as defined.
o The first output parameter is assigned to ID one, subsequent
output parameters are assigned sequentially.
Veillette, et al. Expires May 4, 2016 [Page 25]
Internet-Draft Constrained Objects Language November 2015
o Manually assigned output parameters are skipped.
6.9. Identifier examples
YANG modules do not need to be updated to be implemented using CoOL.
Identifiers can be automatically assigned without the presence of any
YANG extensions. Following is the outcome of this process applied to
the ietf-system YANG module [RFC7317].
+------+--------+--------------------------------------------------+
| DNID | FQDNID | Data node |
+------+--------+--------------------------------------------------+
| 0 | 69632 | / |
| 1 | 69633 | /system |
| 2 | 69634 | /system/contact |
| 3 | 69635 | /system/hostname |
| 4 | 69636 | /system/location |
| 5 | 69637 | /system/clock |
| 6 | 69638 | /system/clock/timezone/timezone-name/ |
| | | timezone-name |
| 7 | 69639 | /system/clock/timezone/timezone-utc-offset |
| | | /timezone-utc-offset |
| 8 | 69640 | /system/ntp |
| 9 | 69641 | /system/ntp/enabled |
| 10 | 69642 | /system/ntp/server |
| 11 | 69643 | /system/ntp/server/name |
| 12 | 69644 | /system/ntp/server/transport/udp/udp |
| 13 | 69645 | /system/ntp/server/transport/udp/udp/address |
| 14 | 69646 | /system/ntp/server/transport/udp/udp/port |
| 15 | 69647 | /system/ntp/server/association-type |
| 16 | 69648 | /system/ntp/server/iburst |
| 17 | 69649 | /system/ntp/server/prefer |
| 18 | 69650 | /system/dns-resolver |
| 19 | 69651 | /system/dns-resolver/search |
| 20 | 69652 | /system/dns-resolver/server |
| 21 | 69653 | /system/dns-resolver/server/name |
| 22 | 69654 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp |
| 23 | 69655 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp/address |
| 24 | 69656 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp/port |
| 25 | 69657 | /system/dns-resolver/options |
| 26 | 69658 | /system/dns-resolver/options/timeout |
| 27 | 69659 | /system/dns-resolver/options/attempts |
| 28 | 69660 | /system/radius |
| 29 | 69661 | /system/radius/server |
| 30 | 69662 | /system/radius/server/name |
Veillette, et al. Expires May 4, 2016 [Page 26]
Internet-Draft Constrained Objects Language November 2015
| 31 | 69663 | /system/radius/server/transport/udp/udp |
| 32 | 69664 | /system/radius/server/transport/udp/udp/address |
| 33 | 69665 | /system/radius/server/transport/udp/udp/ |
| | | authentication-port |
| 34 | 69666 | /system/radius/server/transport/udp/udp/ |
| | | shared-secret |
| 35 | 69667 | /system/radius/server/authentication-type |
| 36 | 69668 | /system/radius/options |
| 37 | 69669 | /system/radius/options/timeout |
| 38 | 69670 | /system/radius/options/attempts |
| 39 | 69671 | /system/authentication |
| 40 | 69672 | /system/authentication/user-authentication-order |
| 41 | 69673 | /system/authentication/user |
| 42 | 69674 | /system/authentication/user/name |
| 43 | 69675 | /system/authentication/user/password |
| 44 | 69676 | /system/authentication/user/authorized-key |
| 45 | 69677 | /system/authentication/user/authorized-key/name |
| 46 | 69678 | /system/authentication/user/authorized-key/ |
| | | algorithm |
| 47 | 69679 | /system/authentication/user/authorized-key/ |
| | | key-data |
| 48 | 69680 | /system-state |
| 49 | 69681 | /system-state/platform |
| 50 | 69682 | /system-state/platform/os-name |
| 51 | 69683 | /system-state/platform/os-release |
| 52 | 69684 | /system-state/platform/os-version |
| 53 | 69685 | /system-state/platform/machine |
| 54 | 69686 | /system-state/clock |
| 55 | 69687 | /system-state/clock/current-datetime |
| 56 | 69688 | /system-state/clock/boot-datetime |
+------+--------+--------------------------------------------------+
+----------------------+--------------------------------------------+
| Protocol operation | Protocol operation |
| IDs | |
+----------------------+--------------------------------------------+
| 1 | /set-current-datetime |
| | +--------------------+-------------------+ |
| | | Input parameter ID | Input parameter | |
| | +--------------------+-------------------+ |
| | | 1 | /current-datetime | |
| | +--------------------+-------------------+ |
| | |
| 2 | /system-restart |
| 3 | /system-shutdown |
+----------------------+--------------------------------------------+
Veillette, et al. Expires May 4, 2016 [Page 27]
Internet-Draft Constrained Objects Language November 2015
If we assume that the extensions shown below have been added to this
module:
Example:
module ietf-system {
import ietf-cool {
prefix "cool";
}
cool:module-id "68";
cool:first-assigned-node-id "20"
cool:first-assigned-rpc-id "10"
cool:id "/system/location 1"
cool:id "/system/dns-resolver/server/name 2"
cool:id "/system-restart 1"
...
}
The generated identifiers will be affected as follows:
+------+--------+--------------------------------------------------+
| DNID | FQDNID | Data node |
+------+--------+--------------------------------------------------+
| 0 | 69632 | / |
| 20 | 69652 | /system |
| 21 | 69653 | /system/contact |
| 22 | 69654 | /system/hostname |
| 1 | 69633 | /system/location |
| 23 | 69655 | /system/clock |
| 24 | 69656 | /system/clock/timezone/timezone-name/ |
| | | timezone-name |
| 25 | 69657 | /system/clock/timezone/timezone-utc-offset |
| | | /timezone-utc-offset |
| 26 | 69658 | /system/ntp |
| 27 | 69659 | /system/ntp/enabled |
| 28 | 69660 | /system/ntp/server |
| 29 | 69661 | /system/ntp/server/name |
| 30 | 69662 | /system/ntp/server/transport/udp/udp |
| 31 | 69663 | /system/ntp/server/transport/udp/udp/address |
| 32 | 69664 | /system/ntp/server/transport/udp/udp/port |
| 33 | 69665 | /system/ntp/server/association-type |
| 34 | 69666 | /system/ntp/server/iburst |
| 35 | 69667 | /system/ntp/server/prefer |
| 36 | 69668 | /system/dns-resolver |
| 37 | 69669 | /system/dns-resolver/search |
Veillette, et al. Expires May 4, 2016 [Page 28]
Internet-Draft Constrained Objects Language November 2015
| 38 | 69670 | /system/dns-resolver/server |
| 2 | 69634 | /system/dns-resolver/server/name |
| 39 | 69671 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp |
| 40 | 69672 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp/address |
| 41 | 69673 | /system/dns-resolver/server/transport/ |
| | | udp-and-tcp/udp-and-tcp/port |
| 42 | 69674 | /system/dns-resolver/options |
| 43 | 69675 | /system/dns-resolver/options/timeout |
| 44 | 69676 | /system/dns-resolver/options/attempts |
| 45 | 69677 | /system/radius |
| 46 | 69678 | /system/radius/server |
| 47 | 69679 | /system/radius/server/name |
| 48 | 69680 | /system/radius/server/transport/udp/udp |
| 49 | 69681 | /system/radius/server/transport/udp/udp/address |
| 50 | 69682 | /system/radius/server/transport/udp/udp/ |
| | | authentication-port |
| 51 | 69683 | /system/radius/server/transport/udp/udp/ |
| | | shared-secret |
| 52 | 69684 | /system/radius/server/authentication-type |
| 53 | 69685 | /system/radius/options |
| 54 | 69686 | /system/radius/options/timeout |
| 55 | 69687 | /system/radius/options/attempts |
| 56 | 69688 | /system/authentication |
| 57 | 69689 | /system/authentication/user-authentication-order |
| 58 | 69690 | /system/authentication/user |
| 59 | 69691 | /system/authentication/user/name |
| 60 | 69692 | /system/authentication/user/password |
| 61 | 69693 | /system/authentication/user/authorized-key |
| 62 | 69694 | /system/authentication/user/authorized-key/name |
| 63 | 69695 | /system/authentication/user/authorized-key/ |
| | | algorithm |
| 64 | 69696 | /system/authentication/user/authorized-key/ |
| | | key-data |
| 65 | 69697 | /system-state |
| 66 | 69698 | /system-state/platform |
| 67 | 69699 | /system-state/platform/os-name |
| 68 | 69700 | /system-state/platform/os-release |
| 69 | 69701 | /system-state/platform/os-version |
| 70 | 69702 | /system-state/platform/machine |
| 71 | 69703 | /system-state/clock |
| 72 | 69704 | /system-state/clock/current-datetime |
| 73 | 69705 | /system-state/clock/boot-datetime |
+------+--------+--------------------------------------------------+
Veillette, et al. Expires May 4, 2016 [Page 29]
Internet-Draft Constrained Objects Language November 2015
+----------------------+--------------------------------------------+
| Protocol operation | Protocol operation |
| IDs | |
+----------------------+--------------------------------------------+
| 10 | /set-current-datetime |
| | +--------------------+-------------------+ |
| | | Input parameter ID | Input parameter | |
| | +--------------------+-------------------+ |
| | | 1 | /current-datetime | |
| | +--------------------+-------------------+ |
| | |
| 1 | /system-restart |
| 11 | /system-shutdown |
+----------------------+--------------------------------------------+
7. Protocol details
This section defines the different interactions supported between a
CoOL client and a CoOL server.
7.1. Retrieving data node(s)
The CoAP GET method is used by a CoOL client to retrieve the value of
one or multiple data nodes.
The URI of the GET request MUST be set to the URI of the targeted
datastore.
The data node(s) to be retrieved MUST be specified within the
"Fields" CoAP option. This CoAP option contains a list of data node
IDs encoded using a CBOR array. The first data node ID MUST be
fully-qualified. Subsequence IDs MUST be elided if the module ID is
shared with the previous array entry.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.05 (Content). The
payload of the GET response MUST carry a CBOR map containing the data
node(s) requested. The subsection "YANG container" of the "YANG to
CBOR mapping" section defines the rules used to construct this CBOR
map. The CBOR value undefined (0xf7) must be returned for each data
node requested but not currently available.
Veillette, et al. Expires May 4, 2016 [Page 30]
Internet-Draft Constrained Objects Language November 2015
Example:
CoAP request:
GET /cool Fields([69637, 55])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
69637 : {
7 : 540
},
69687 : "2015-10-08T14:10:08Z09:00"
}
In this example, a CoOL client retrieves the data nodes "/system/
clock" and "/system-state/clock/current-datetime" defined in the
ietf-system module.
This example makes use of the following IDs:
o module ietf-system: module ID 68
o leaf clock: data node ID 5, fully-qualified ID 69637
o leaf timezone-utc-offset: data node ID 7
o leaf current-datetime: data node ID 55, fully-qualified ID 69687
These CoAP requests and responses MUST be encoded in accordance with
[RFC7252]. An encoding example is shown below:
CoAP request:
+-----------------------------------------+---------+---------------+
| CoAP field | Size | Value |
| | (bytes) | |
+-----------------------------------------+---------+---------------+
| Version, Type, Token Length, Code | 2 | |
| Message ID | 2 | |
| Token ID | 0 to 8 | |
| option Uri-Path (Delta and Length) | 1 | |
| option Uri-Path (Value) | 5 | "/cool" |
| option Fields (Delta and Length) | 1 | |
| option Fields (Value) | 8 | 82 |
| | | 1a 00011005 |
| | | 18 37 |
+-----------------------------------------+---------+---------------+
Veillette, et al. Expires May 4, 2016 [Page 31]
Internet-Draft Constrained Objects Language November 2015
CoAP response:
+-----------------------------------------+---------+---------------+
| CoAP field | Size | Value |
| | (bytes) | |
+-----------------------------------------+---------+---------------+
| Version, Type, Token Length, Code | 2 | |
| Message ID | 2 | |
| Token ID | 0 to 8 | |
| Option Content-Format (Delta and Length)| 1 | |
| Option Content-Format (Value) | 1 | 60 |
| Payload | 43 | a2 |
| | | 1a 00011005 |
| | | a1 |
| | | 07 |
| | | 19 021c |
| | | 1a 00011037|
| | | 78 19 |
| | | 32303135 |
| | | 2d31302d |
| | | 30385431 |
| | | 343a3130 |
| | | 2d30385a |
| | | 30393a30 |
| | | 30 |
+-----------------------------------------+---------+---------------+
7.2. The Fields CoAP option
The "Fields" CoAP option is used to specify the list of data node(s)
accessed. This option contains a CBOR array. Each entry of this
array can be an unsigned integer representing a data node ID or a
CBOR array representing an instance selector.
Example:
+-----+---+---+---+---+---------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+-----+---+---+---+---+---------+--------+--------+---------+
| 6 | x | x | - | x | Fields | opaque | 0-3 B | (none) |
+-----+---+---+---+---+---------+--------+--------+---------+
7.3. Retrieving all data nodes
To retrieve all data nodes associated with a YANG module, the Fields
CoAP option MUST be present and the CBOR array MUST contain the data
node ID zero for this module. Data nodes added to the specified
module by other modules using the augment YANG statement are returned
Veillette, et al. Expires May 4, 2016 [Page 32]
Internet-Draft Constrained Objects Language November 2015
but data nodes added by the specified module to other modules are not
returned.
To retrieve all data nodes of all YANG modules, the Fields CoAP
option MUST be absent.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.05 (Content). The
payload of the GET response MUST carry a CBOR map containing a
container for each module reported and identified using the data node
ID zero.
Example:
CoAP Request:
GET /cool Fields([66560])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
66560 : {
1 : {
2 : [
{
3 : "eth0",
4 : "Ethernet adapter Local Area Connection",
5 : "iana-interface-type.ethernetCsmacd",
6 : true,
68620 : {
13 : true,
14 : true,
15 : 1280,
16 : [
{
17 : "fe80::200:f8ff:fe21:67cf",
18 : 10
}
]
}
}
]
}
}
}
In this example, a CoOL client retrieves all data nodes of the YANG
module "ietf-interfaces". Data nodes defined using the augment YANG
statement in the "ietf-ip" module are also returned.
Veillette, et al. Expires May 4, 2016 [Page 33]
Internet-Draft Constrained Objects Language November 2015
If we assume that the CoOL server implements only the "ietf-
interfaces" and the "ietf-ip" modules, then the following request
returns the same response as above.
GET /cool
This example makes use of the following IDs:
o module ietf-interfaces: module ID 65
o module root : data node ID 0, fully-qualified 66560
o container interfaces: data node ID 1
o list interface: data node ID 2
o leaf name: data node ID 3
o leaf description: data node ID 4
o leaf type: data node ID 5
o leaf enabled: data node ID 6
o module ietf-ip: module ID 67
o container ipv6: data node ID 12, fully-qualified 68620
o leaf enabled: data node ID 13
o leaf forwarding: data node ID 14
o leaf mtu: data node ID 15
o list address: data node ID 16
o leaf ip: data node ID 17
o leaf prefix-length: data node ID 18
7.4. Updating data node(s)
The CoAP PUT method is used by CoOL clients to change the value of
one or multiple data nodes.
The URI of the PUT request MUST be set to the URI of the targeted
datastore.
Veillette, et al. Expires May 4, 2016 [Page 34]
Internet-Draft Constrained Objects Language November 2015
The payload of the PUT request carry a CBOR map containing the list
of data node(s) to be updated. The subsection "YANG container" of
the "YANG to CBOR mapping" section defines the rules used to
construct this CBOR map. It is important to note that the CBOR map
itself does not represent a data node; rather, each tag-value pair in
that map represents a data node to be updated.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.04 (Changed). If at
least one of the targeted data nodes doesn't exist, the CoOL server
MUST return a response code 4.00 (Bad Request) carrying a payload
with the data node "/error-info/error-code" set to 4 (doesNotExist).
PUT methods SHOULD be processed as atomic transactions, if any errors
occur, then the target datastore SHOULD NOT be changed by the PUT
operation.
Example:
CoAP request:
PUT /cool Content-Format(application/cbor)
{
69639 : 540,
69687 : "2015-10-08T14:10:08Z09:00"
}
CoAP response:
2.04 Changed
In this example, a CoOL client updates data nodes
/system/clock/timezone/timezone-utc-offset/timezone-utc-offset" and
"/system-state/clock/current-datetime".
This example makes use of the following IDs:
o module ietf-interfaces: module ID 65
o leaf timezone-utc-offset: data node ID 7, fully-qualified 69639
o leaf current-datetime: data node ID 55, fully-qualified 69687
7.5. Retrieving data node(s) from a list
The CoAP GET method is used by CoOL clients to retrieve the value of
one or multiple data nodes within a list.
To retrieve data node(s) within a list, the Fields option MUST carry
an instance selector. An instance selector is a CBOR array
containing these elements:
Veillette, et al. Expires May 4, 2016 [Page 35]
Internet-Draft Constrained Objects Language November 2015
o The first element of the CBOR array MUST be set to the data node
ID of the list containing the requested data nodes.
o The second element of the array MUST be set to a CBOR array
containing the value of the different keys required to select the
requested data nodes. Key values MUST be provided in the same
order as defined in the YANG key sub-statement. When a list is
defined within list(s), the key values are ordered starting with
the top level list and ending with the list containing the
requested data nodes.
o The third element is optional. When present, this element MUST be
set to a CBOR array containing the data node IDs of the data nodes
requested. When absent, all data nodes within the targeted list
entry MUST be returned.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.05 (Content). The
payload of the GET response MUST carry a CBOR map containing the
requested data nodes. The subsection "YANG container" of the "YANG
to CBOR mapping" section defines the rules used to construct this
CBOR map.
When the list entry specified in the request does not exist, the
returned payload MUST contain a map entry set to the CBOR value
undefined (0xf7).
Example:
CoAP request:
GET /cool Fields([69635, [66562, ["eth0"], [5, 6]])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
69635 : "datatracker.ietf.org",
66562 : {
5 : "iana-interface-type.ethernetCsmacd",
6 : true
}
}
In this example, a CoOL client retrieves the data node "/system/
hostname" defined in the ietf-system module and the data nodes
"/interfaces/interface/type" and "/interfaces/interface/enabled"
member of the "/interfaces/interface" list defined in the ietf-
interfaces module.
Veillette, et al. Expires May 4, 2016 [Page 36]
Internet-Draft Constrained Objects Language November 2015
Altername CoAP response:
2.05 Content Content-Format(application/cbor)
{
69635 : "datatracker.ietf.org",
66562 : undefined
}
This alternate CoAP response represents the case where the interface
name "eth0" doesn't exist within the "/interfaces/interface" list.
This example makes use of the following IDs:
o module ietf-interfaces: module ID 65
o module ietf-system: module ID 68
o leaf hostname: data node ID 3, fully-qualified 69635
o list interface: data node ID 2, fully-qualified 66562
o leaf type: data node ID 5
o leaf enabled: data node ID 6
7.6. Retrieving multiple entries from a list
Two approaches are supported to retrieve multiple list entries.
The first approach consists of providing a list of key sets. Each
key set selects one entry within the YANG list. In this case, the
second element of the instance selector MUST be encoded as a CBOR
array for which each entry is itself a CBOR array containing the
key(s).
The second approach consists of setting one or multiple keys to null
(0xf6). In this case, all possible values for this key are returned.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.05 (Content). The
payload of the GET response MUST carry a CBOR map containing the
different data nodes requested. The subsection "YANG container" of
the "YANG to CBOR mapping" section defines the rules used to
construct this CBOR map.
When the list entry specified in the request does not exist, the
returned payload MUST contain a map entry set to the CBOR value
undefined (0xf7).
Veillette, et al. Expires May 4, 2016 [Page 37]
Internet-Draft Constrained Objects Language November 2015
Example:
CoAP request:
GET /cool Fields([ [66569,[["eth0"], ["eth1"]], [10, 22, 27]] ])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
66569 : [
{
10 : "eth0",
22 : 1572864,
27 : 0
},
{
10 : "eth1",
22 : 1572864,
27 : 0
}
]
}
In this example, a CoOL client retrieves data nodes "/interfaces-
state/interface/statistics/in-octets" and "/interfaces-
state/interface/statistics/in-errors" for the interface name "eth0"
and "eth1".
Assuming that only two interfaces exist for this host, the following
request returns the same response as above.
CoAP request:
GET /cool Fields([ [66569,[ null ], [10, 22, 27]] ])
This example makes use of the following IDs:
o module ietf-interfaces: module ID 65
o list interface: data node ID 9, fully-qualified 66569
o leaf name: data node ID 10
o leaf in-octets: data node ID 22
o leaf in-errors: data node ID 27
Veillette, et al. Expires May 4, 2016 [Page 38]
Internet-Draft Constrained Objects Language November 2015
7.7. Retrieving multiple entries of a single data node from a list
Retrieval of a single data node within a list MUST be optimized as
follows:
In the request, the third element of the instance selector MUST be
encoded as a CBOR unsigned integer instead of a CBOR ARRAY.
In the response, the instances of the selected data node MUST be
encoded as a CBOR ARRAY associated directly with the ID of this data
node.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.05 (Content). When the
list entry specified in the request does not exist, the returned
payload MUST contain a map entry set to the CBOR value undefined
(0xf7).
Example:
CoAP request:
GET /cool Fields([ [66569,[ null ], 10] ])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
66570 : [ "eth0", "eth1", "wlan0" ]
}
In this example, a CoOL client retrieves all instances of data node
"/interfaces-state/interface/name" within the "/interfaces-state/
interface" list.
This example makes use of the following IDs:
o module ietf-interfaces: module ID 65
o list interface: data node ID 9, fully-qualified 66569
o leaf name: data node ID 10, fully-qualified 66570
7.8. Updating a list entry
The CoAP PUT method is used by a CoOL client to update the value of
one or multiple data nodes within a list.
The URI of the PUT request MUST be set to the URI of the targeted
datastore.
Veillette, et al. Expires May 4, 2016 [Page 39]
Internet-Draft Constrained Objects Language November 2015
The Fields CoAP option MUST be set to an instance selector composed
of the following elements:
o The first element MUST be set to the data node ID of the list.
o The second element MUST be set to a CBOR array containing the
value of the different keys required to select the targeted entry
within the specified list.
The payload of the PUT request MUST carry a CBOR map containing the
list entry to be updated. The subsection "YANG container" of the
"YANG to CBOR mapping" section defines the rules used to construct
this CBOR map.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.04 (Changed). If the
list specified doesn't exist, the CoOL server MUST return a response
code 4.00 (Bad Request) carrying a payload with data node "/error-
info/error-code" set to 4 (doesNotExist). PUT methods SHOULD be
processed as atomic transactions, if any errors occur, then the
target datastore SHOULD NOT be changed by the PUT operation.
Example:
CoAP request:
PUT /cool Fields([69642,[ "NTP Pool server 2" ]])
{
69642 : {
12 : {
13: "2620:10a:800f::11",
14: 123
}
}
}
CoAP response:
2.04 Changed
In this example, a CoOL client update data nodes
"/system/ntp/server/transport/udp/udp/address" and
"/system/ntp/server/transport/udp/udp/port" within the "/system/ntp/
server" list.
This example makes use of the following IDs:
o module ietf-system: module ID 68
o list server: data node ID 10, fully-qualified 69642
Veillette, et al. Expires May 4, 2016 [Page 40]
Internet-Draft Constrained Objects Language November 2015
o container udp: data node ID 12
o leaf address: data node ID 13
o leaf port: data node ID 14
7.9. Adding a list entry
The CoAP POST method is used by a CoOL client to insert an entry into
a list.
The URI of the POST request MUST be set to the URI of the targeted
datastore.
The payload of the POST request MUST carry a CBOR map containing the
data node ID of the list targeted. The subsection "YANG container"
of the "YANG to CBOR mapping" section defines the rules used to
construct this CBOR map.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.01 (Created). If the
entry provided already exists in the targeted list (duplicate key),
the CoOL server MUST return a response code 4.00 (Bad Request)
carrying a payload with data node "/error-info/error-code" set to 5
(alreadyExist).
Example:
CoAP request:
POST /cool
{
69642 : {
12 : {
13: "132.246.11.231",
14: 123
}
}
}
CoAP response:
2.01 Created
In this example, a CoOL client adds an entry in the "/system/ntp/
server" list. The entry added contains data nodes
"/system/ntp/server/transport/udp/udp/address" and
"/system/ntp/server/transport/udp/udp/port".
This example makes use of the following IDs:
Veillette, et al. Expires May 4, 2016 [Page 41]
Internet-Draft Constrained Objects Language November 2015
o module ietf-system: module ID 68
o list server: data node ID 10, fully-qualified 69642
o container udp: data node ID 12
o leaf address: data node ID 13
o leaf port: data node ID 14
7.10. Deleting list entries
The CoAP DELETE method is used by a CoOL client to delete an entry
within a list.
The URI of the PUT request MUST be set to the URI of the targeted
datastore.
The Field CoAP option MUST contain an instance selector composed of
the following elements:
o The first element MUST be set to the data node ID of the list.
o The second element MUST be set to a CBOR array containing the
value of the different keys required to identify the entry to be
deleted.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.02 (Deleted). If the
targeted entry doesn't exist, the CoOL server MUST return a response
code 4.00 (Bad Request) carrying a payload with data node "/error-
info/error-code" set to 4 (doesNotExist).
Example:
CoAP request:
DELETE /cool Fields([69642,[ "NTP Pool server 2" ]])
CoAP response:
2.02 Deleted
In this example, a CoOL client deletes the entry within the
"/system/ntp/server" list for the key "/system/ntp/server/name" =
"NTP Pool server 2".
This example makes use of the following IDs:
o module ietf-system: module ID 68
Veillette, et al. Expires May 4, 2016 [Page 42]
Internet-Draft Constrained Objects Language November 2015
o list server: data node ID 10, fully-qualified 69642
7.11. Patch
The CoAP PATCH method is used by CoOL clients to perform complex
atomic transactions on a datastore.
To perform a patch, the CoAP method MUST be set to PATCH.
The payload of the CoAP request MUST carry a "patch-request" list as
defined by the ietf-cool module. This list carries a sequence of
edits on a datastore. Each edit MUST be applied in ascending order,
and all edits MUST be applied. If any errors occur, then the target
datastore SHOULD NOT be changed by the patch operation.
On successful processing of the CoAP request, the CoOL server MUST
return a CoAP response with a response code 2.04 (Changed).
If at least one of the edit is rejected, the CoOL server MUST return
a CoAP response with a response code 4.00 (Bad Request) and the
payload MUST carry a "patch-response" list as defined by the ietf-
cool module.
In the following example, a CoOL client performs the following
operations using the patch method:
o Remove all entries present in the"/system/ntp/server" list.
o Create an entry in the "/system/ntp/server" list with the server
name set to "NTP Pool server 2" and the server address set to
"2.pool.ntp.org".
o Set the data node "/system/ntp/enabled" to true.
Veillette, et al. Expires May 4, 2016 [Page 43]
Internet-Draft Constrained Objects Language November 2015
Example:
CoAP request:
PATCH /cool Content-Format(application/cbor)
{
1028 : [
{
5 : 0,
6 : 4,
7 : [69642, [null]]
},
{
5 : 1,
6 : 0,
8 : {
69642 : {
11 : "NTP Pool server 2",
12 : {
13 : "2.pool.ntp.org"
}
}
}
},
{
5 : 2,
6 : 3,
8 : {
69641 : true
}
}
]
}
CoAP response:
2.04 Changed
Alternate CoAP response:
4.00 Bad Request (Content-Format: application/cbor)
{
1033 : [
{
10 : 1,
11 : 3
}
]
}
Veillette, et al. Expires May 4, 2016 [Page 44]
Internet-Draft Constrained Objects Language November 2015
This alternate response represents the case where the second edit
have been rejected because of an invalid value.
This example makes use of the following IDs:
o module ietf-cool: module ID 1
o list patch-request: data node ID 4, fully-qualified 1028
o leaf operation: data node ID 5
o leaf list-entry: data node ID 6
o anyxml value: data node ID 8
o list patch-response
o leaf edit-id
o leaf edit-status
o module ietf-system: module ID 68
o leaf enabled : data node ID 9, fully-qualified 69641
o list server: data node ID 10, fully-qualified 69642
o leaf name: data node ID 11
o container udp: data node ID 12
o leaf address: data node ID 13
7.12. Protocol operation
Protocol operations are defined using the YANG "rpc" statement.
Protocol operations are invoked by CoOL clients using a CoAP POST
method on the protocol operation resource.
When input parameter(s) are defined for the invoked protocol
operation and are needed by the CoOL client, they are carried in the
CoAP request payload. These parameter(s) are encoded using a CBOR
map. The subsection "YANG container" of the "YANG to CBOR mapping"
section defines the rules used to construct this CBOR map.
The response code of the CoAP response MUST be set to 2.05 (Content).
When output parameters are returned by the CoOL server, these
parameter(s) are carried in the CoAP response payload. These
Veillette, et al. Expires May 4, 2016 [Page 45]
Internet-Draft Constrained Objects Language November 2015
parameter(s) are encoded using a CBOR map. The subsection "YANG
container" of the "YANG to CBOR mapping" section defines the rules
used to construct this CBOR map.
Example:
CoAP request:
POST /cool/rpc/68/1 Content-Format(application/cbor)
{
1 : "2015-10-08T14:10:08Z09:00"
}
CoAP response:
2.05 Content
In this example, a CoOL client invokes the protocol operation "/set-
current-datetime". The "current-datetime" value is provided as input
parameter.
This example makes use of the following IDs:
o module ietf-system: module ID 68
o rpc set-current-datetime: protocol operation ID 1
o input parameter current-datetime: input parameter ID 1
7.13. Event stream
Notifications are defined using the YANG "notification" statement.
Subscriptions to an event stream and notification reporting are
performed using an event stream resource. When multiple event stream
resources are supported, the list of notifications associated with
each stream is either pre-defined or configured in the CoOL server.
CoOL clients MAY subscribe to one or more event stream resources.
To subscribe to an event stream resource, a CoOL client MUST send a
CoAP GET with the Observe CoAP option set to 0. To unsubscribe, a
CoOL client MAY send a CoAP reset or a CoAP GET with the Observe
option set to 1. For more information on the observe mechanism, see
[RFC7641].
Each notification transferred by a CoOL server to each of the
registered CoOL client is carried in a CoAP response with a response
code set to 2.05 (Content). Each CoAP response MUST carry in its
payload at least one notification but MAY carry multiple. Each
notification MUST be encoded as a CBOR map. The subsection "YANG
container" of the "YANG to CBOR mapping" section defines the rules
Veillette, et al. Expires May 4, 2016 [Page 46]
Internet-Draft Constrained Objects Language November 2015
used to construct this CBOR map. When multiple notifications are
reported, the CoAP response payload carries a CBOR array, with each
entry containing a notification encoded using a CBOR map.
For this example, we assume that the following notifications have
been added to the ietf-system module.
Example:
notification system-status-update {
leaf status-update {
type enumeration {
enum system-down { value 0; }
enum system-up { value 1; }
}
}
leaf current-time {
type yang:date-and-time;
}
}
notification ntp-time-updated {
leaf new-time {
type yang:date-and-time;
}
leaf time-drift {
type uint64;
units "milliseconds";
}
}
In this example, a CoOL client starts by registering to the default
event stream resource "/cool/streams".
CoAP request:
GET /cool/streams Observe(0) Token(0x9372)
The CoOL server confirms this registration by returning a first CoAP
response. The payload of this CoAP response may be empty or may
carry the last notification reported by this server.
CoAP response:
2.05 Content Observe(52) Token(0xD937)
After detecting an event, the CoOL server sends its first
notification to the registered CoOL client.
Veillette, et al. Expires May 4, 2016 [Page 47]
Internet-Draft Constrained Objects Language November 2015
CoAP response:
2.05 Content Observe(53) Token(0xD937)
Content-Format(application/cbor)
{
69634 : {
1 : "2015-10-08T14:10:08Z09:00",
2 : 271
}
}
To optimize communications or because of other constrains, the CoOL
server might transfer multiple notifications in a single CoAP
response.
CoAP response:
2.05 Content Observe(52) Token(0xD937)
Content-Format(application/cbor)
[
{
69633 : {
1 : 0,
2 : "2015-10-08T15:23:51Z09:00"
}
},
{
69633 : {
1 : 1,
2 : "2015-10-08T15:25:36Z09:00"
}
}
]
This example makes use of the following IDs:
o module ietf-system: module ID 68
o notification system-status-update: notification ID 69633
o leaf status-update: notification parameter ID 1
o leaf current-time: notification parameter ID 2
o notification ntp-time-updated : notification ID 69634
o leaf updated-time: notification parameter ID 1
o leaf time-drift: notification parameter ID 2
Veillette, et al. Expires May 4, 2016 [Page 48]
Internet-Draft Constrained Objects Language November 2015
7.14. Observe
A CoOL server MAY support state change notifications to some or all
its leaf data nodes. When supported the CoOL server MUST implement
the Server-Side requirements defined in [RFC7641] section 3 and the
CoOL client MUST implement the Client-Side requirements defined in
[RFC7641] section 4.
To start observing a leaf data node, a CoOL client MUST send a CoAP
GET with the Observe CoAP option set to 0. The Fields CoAP option
may be set to any content previously defined within this section.
The first data node selected represents the resource observed as
described in [RFC7641]. Subsequent data nodes selected represent
coincidental values. These data nodes are included in each
notification, but changes to these extra data nodes MUST not trigger
notification messages.
A subscription can be terminated by the CoOL client by returning a
CoAP Reset message or by sending a GET request with an Observe CoAP
option set to deregister (1). More details are available in
[RFC7641].
Example:
CoAP request:
GET /cool Fields([ [66594, ["eth0"]], [34, 29]]) Observe(0)
CoAP response:
2.05 Content Content-Format(application/cbor) Observe(2631)
{
66594: {
29 : 605873,
34 : 42
}
}
...
CoAP response:
2.05 Content Content-Format(application/cbor) Observe(2632)
{
66594: {
29 : 6493721,
34 : 43
}
}
Veillette, et al. Expires May 4, 2016 [Page 49]
Internet-Draft Constrained Objects Language November 2015
In this example, a CoOL client subscribes to state changes of the
data node "/interfaces-state/interface/statistics/out-errors" and
requests that data node "/interfaces-state/interface/statistics/out-
octets" is reported as coincidental value.
A first response is immediately returned by the CoOL server to
confirm the subscription and to report the current values of the
requested data nodes.
Subsequent responses are returned by the CoOL server each time the
data node "/interfaces-state/interface/statistics/out-errors"
changes.
7.15. Resource discovery
The "/.well-known/core" resource is used by CoOL clients to discover
resources implemented by CoOL servers. Each CoOL server MUST have an
entry in the "/.well-known/core" resource for each datastore
resource, protocol operation resource, and event stream resource
supported.
Resource discovery MUST be performed using a CoAP GET request. The
CoAP response MUST have a response code set to 2.05 (Content), a
Content-Format set to "application/link-format", and a payload
containing a list of web links.
To enable discovery of specific resource types, the CoAP server MUST
support the query string "rt".
Link format and the "/.well-known/core" resource are defined in
[RFC6690].
Example:
CoAP request:
GET /.well-known/core
CoAP response:
2.05 Content Content-Format(application/link-format)
</cool>;rt="cool.datastore",
</cool/rpc>;rt="cool.protocol-operation",
</cool/stream>;rt="cool.event-stream",
In this example, a CoOL client retrieves the list of all resources
available on a CoOL server.
Veillette, et al. Expires May 4, 2016 [Page 50]
Internet-Draft Constrained Objects Language November 2015
Alternatively, the CoOL client may query for a specific resource
type. In this example, the CoOL client queries for resource type
(rt) "cool.datastore".
CoAP request:
GET /.well-known/core?rt=cool.datastore
CoAP response:
2.05 Content Content-Format(application/link-format)
</cool>;rt="cool.datastore",
7.16. Modules, sub-modules, and objects discovery
CoOL clients can discover the list of modules, sub-modules, data
nodes, protocol operations, and event streams implemented by CoOL
servers by requesting this information from the "ietf-cool-library"
YANG module.
CoOL servers MUST implement the "ietf-cool-library" YANG module.
This module MUST contain information about all modules supported by
this CoOL server.
The "ietf-cool-library" YANG module also reports detailed information
about each module, such as "name", "features", "deviations",
"submodule", "data-nodes", "protocol-operation" and "notifications".
CoOL servers SHOULD support this detail information if the amount of
resources available allow their implementation.
Veillette, et al. Expires May 4, 2016 [Page 51]
Internet-Draft Constrained Objects Language November 2015
Example:
CoAP request:
GET /cool Fields([2049])
CoAP response:
2.05 Content Content-Format(application/cbor)
{
2049 : [
{
2 : 65,
3 : "ietf-interfaces",
4 : "2014-05-08",
5 : ["arbitrary-names", "pre-provisioning"],
10 : [1, 2, 3, 5, 6, 8, 9, 10, 11, 12, 13, 14, 16, 20, 21,
22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34]
},
{
2 : 68,
3 : "ietf-system",
4 : "2014-08-06",
5 : ["ntp", "ntp-udp-port"],
10 : [1, 2, 3, 5, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17],
11 : [1, 2, 3]
}
]
}
In this example, a CoOL client retrieves the entire content of the
"module" list. The CoOL protocol can be used by a CoOL client to
retrieve specific information within this list.
Second example:
CoAP request:
POST /cool/rpc/2/1 Content-Format(application/cbor)
{
1 : 68,
2 : 5
}
CoAP response:
2.05 Content Content-Format(application/cbor)
{
1 : true
}
Veillette, et al. Expires May 4, 2016 [Page 52]
Internet-Draft Constrained Objects Language November 2015
In this second example, a CoOL client uses the is-supported protocol
operation to verify support of data node "/system/clock".
These examples make use of the following IDs:
o module ietf-cool-library: module ID 2
o module ietf-interfaces: module ID 65
o module ietf-system: module ID 68
o list modules: data node ID 1, fully-qualified 2049
o leaf module-id: data node ID 2
o leaf name: data node ID 3
o leaf revision: data node ID 4
o leaf-list features: data node ID 5
o leaf-list data-nodes: data node ID 10
o leaf-list protocol-operations: data node ID 11
o rpc is-supported: protocol operation ID 1
8. Error Handling
All CoAP response codes defined by [RFC7552] MUST be accepted and
processed accordingly by CoOL clients. Optionally, client errors
(CoAP response codes 4.xx) or server errors (CoAP response codes
5.xx) MAY have a payload providing further information about the
cause of the error. This payload contain the "error-info" container
defined in the ietf-cool YANG module.
Example:
CoAP response:
4.00 Bad Request (Content-Format: application/cbor)
{
1025 : 2,
1026 : "Data node 69687 is unknown"
}
Veillette, et al. Expires May 4, 2016 [Page 53]
Internet-Draft Constrained Objects Language November 2015
9. Security Considerations
This application protocol relies on the lower layers to provide
confidentiality, integrity, and availability. A typical approach to
archive these requirements is to implement CoAP using the DTLS
binding as defined in [RFC7252] section 9. Other approaches are
possible to fulfill these requirements, such as the use of a network
layer security mechanism as discussed in
[I-D.bormann-core-ipsec-for-coap] or a link layer security mechanism
for exchanges done within a single sub-network (e.g.
[I-D.wang-6tisch-6top-coapie].
In some applications, different access rights to CoOL resources and
objects need to be granted to different CoOL clients. Different
solutions are possible, such as the implementation of Access Control
Lists (ACL) using YANG module(s) or the use of an authorization
certificate as defined in [RFC5755]. These access control mechanisms
need to be addressed in complementary specifications.
The Security Considerations section of CoAP [RFC7252] is especially
relevant to this application protocol and should be reviewed
carefully by implementers.
10. IANA Considerations
10.1. Module ID
This document defines a registry for YANG module IDs. The name of
this registry is "CoOL module ID".
The registry shall record for each entry:
The assigned identifier.
The name of the YANG module.
A reference to the module and associated sub-module documentation
(e.g. RFC number).
Contact information of the owner of the module, such as name,
email, and phone number.
Veillette, et al. Expires May 4, 2016 [Page 54]
Internet-Draft Constrained Objects Language November 2015
+--------+-----------------+------------------------------+---------+
| Module | Module name | Reference | Owner |
| ID | | | |
+--------+-----------------+------------------------------+---------+
| 0 | Reserved | | |
| 1 | cool | Defined in annex A | IETF |
| 2 | cool-library | Defined in annex B | IETF |
| 3 to | Reserved | Expert Review. Reserved for | |
| 63 | | standardized YANG modules | |
| | | targeting constrained | |
| | | networks and devices. These | |
| | | module IDs require less | |
| | | overhead when encoded using | |
| | | CBOR. | |
| 64 | ietf-inet-types | [RFC6021] | IETF |
| 65 | ietf-interfaces | [RFC7223] | IETF |
| 66 | iana-if-type | [RFC7224] | IETF |
| 67 | ietf-ip | [RFC7277] | IETF |
| 68 | ietf-system | [RFC7317] | IETF |
| 100 to | Reserved | Experimental use | |
| 127 | | | |
| 128 to | Reserved | Temporary registry | Authors |
| 1023 | | maintained by the authors to | |
| | | allow initial | |
| | | implementations. These | |
| | | identifiers should be | |
| | | transferred to the official | |
| | | registry when appropriate. | |
+--------+-----------------+------------------------------+---------+
10.2. "Fields" CoAP Option Number
The Fields CoAP option is used to specify a list of data nodes to be
retrieved by a CoAP GET. This option needs to be registered in the
CoAP Option Numbers registry as defined in [RFC7252] section 12.2.
10.3. "PATCH" CoAP Method Code
This draft makes use of the PATCH CoAP method as defined in
[I-D.vanderstok-core-patch]. This method needs to be registered in
the CoAP Method Codes sub-registry as defined in [RFC7252] section
12.1.1.
11. References
Veillette, et al. Expires May 4, 2016 [Page 55]
Internet-Draft Constrained Objects Language November 2015
11.1. Normative References
[I-D.vanderstok-core-patch]
Stok, P. and A. Sehgal, "Patch Method for Constrained
Application Protocol (CoAP)", draft-vanderstok-core-
patch-02 (work in progress), October 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<http://www.rfc-editor.org/info/rfc6020>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<http://www.rfc-editor.org/info/rfc6690>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for
System Management", RFC 7317, DOI 10.17487/RFC7317, August
2014, <http://www.rfc-editor.org/info/rfc7317>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<http://www.rfc-editor.org/info/rfc7641>.
11.2. Informative References
[I-D.bormann-core-ipsec-for-coap]
Bormann, C., "Using CoAP with IPsec", draft-bormann-core-
ipsec-for-coap-00 (work in progress), December 2012.
Veillette, et al. Expires May 4, 2016 [Page 56]
Internet-Draft Constrained Objects Language November 2015
[I-D.vanderstok-core-comi]
Stok, P., Bierman, A., Schoenwaelder, J., and A. Sehgal,
"CoAP Management Interface", draft-vanderstok-core-comi-08
(work in progress), October 2015.
[I-D.wang-6tisch-6top-coapie]
Wang, Q., Vilajosana, X., Watteyne, T., Sudhaakar, R., and
P. Zand, "Transporting CoAP Messages over IEEE802.15.4e
Information Elements", draft-wang-6tisch-6top-coapie-01
(work in progress), July 2015.
[RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet
Attribute Certificate Profile for Authorization",
RFC 5755, DOI 10.17487/RFC5755, January 2010,
<http://www.rfc-editor.org/info/rfc5755>.
[RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6021, DOI 10.17487/RFC6021, October 2010,
<http://www.rfc-editor.org/info/rfc6021>.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
<http://www.rfc-editor.org/info/rfc7223>.
[RFC7224] Bjorklund, M., "IANA Interface Type YANG Module",
RFC 7224, DOI 10.17487/RFC7224, May 2014,
<http://www.rfc-editor.org/info/rfc7224>.
[RFC7277] Bjorklund, M., "A YANG Data Model for IP Management",
RFC 7277, DOI 10.17487/RFC7277, June 2014,
<http://www.rfc-editor.org/info/rfc7277>.
[RFC7552] Asati, R., Pignataro, C., Raza, K., Manral, V., and R.
Papneja, "Updates to LDP for IPv6", RFC 7552,
DOI 10.17487/RFC7552, June 2015,
<http://www.rfc-editor.org/info/rfc7552>.
Appendix A. ietf-cool YANG module
Module containing YANG extensions for the CoOL protocol.
module ietf-cool {
namespace "urn:ietf:ns:cool";
prefix cool;
organization
"IETF Core Working Group";
Veillette, et al. Expires May 4, 2016 [Page 57]
Internet-Draft Constrained Objects Language November 2015
contact
"Michel Veillette
<mailto:michel.veillette@trilliantinc.com>
Randy Turner
<mailto:Randy.Turner@landisgyr.com>
Alexander Pelov
<mailto:a@ackl.io>
Abhinav Somaraju
<mailto:abhinav.somaraju@tridonic.com>";
description
"This module contains the different definitions required
by the CoOL protocol.";
revision 2015-09-30 {
description
"Initial revision.";
reference
"draft-veillette-core-cool";
}
// YANG modeling language extensions
extension module-id {
description "YANG statement used to assign a module ID.";
argument "module-identifier";
}
extension first-assigned-node-id {
description "YANG statement used to specify the first identifier
automatically assigned to a data node within a
YANG module. Subsequent data nodes are assigned
sequentially. Values lower than the
first-assigned-node-id are reserved for
manual assignment.";
argument "first-data-node-identifier";
}
extension first-assigned-rpc-id {
description "YANG statement used to specify the first identifier
automatically assigned to a protocol operation
within a YANG module. Subsequent protocol
operations are assigned sequentially. Values lower
than the first-assigned-rpc-id are reserved for
manual assignment.";
Veillette, et al. Expires May 4, 2016 [Page 58]
Internet-Draft Constrained Objects Language November 2015
argument "first-rpc-identifier";
}
extension first-assigned-notification-id {
description "YANG statement used to specify the first identifier
automatically assigned to a notification within
a Yang module. Subsequent notifications are
assigned sequentially. Values lower than the
first-assigned-notification-id are reserved for
manual assignment.";
argument "first-notification-identifier";
}
extension id {
description "YANG statement used to assign a specific identifier
to a data node, a protocol operation, a input
parameter, a output parameter, a notification
or a notification parameter. The argument of this
extension contain two information, the path of the
specified object and the associated identifier.
These two parts are separated by a space.";
argument "path-vs-id";
}
typedef status-code {
type enumeration {
enum ok {
value 0;
description "The requested edit have been performed
successfully.";
}
enum error {
value 1;
description "Unspecified error.";
}
enum malformed {
value 2;
description "Malformed CBOR payload.";
}
enum invalid {
value 3;
description "The value specified in the request can't be
apply to the target data node.";
}
Veillette, et al. Expires May 4, 2016 [Page 59]
Internet-Draft Constrained Objects Language November 2015
enum doesNotExist {
value 4;
description "The target data node specified in the request
don't exist.";
}
enum alreadyExist {
value 5;
description "The target data node specified in the request
already exist.";
}
enum readOnly {
value 6;
description "Attempt to update a read-only data node.";
}
}
}
container error-info {
description "Optional payload of a client error (CoAP response
4.xx) or server error (CoAP response 5.xx).";
leaf error-code {
mandatory true;
type status-code;
}
leaf error-text {
mandatory false;
type string;
description "Textual descriptions of the error.";
}
}
list patch-request {
key "edit-id";
description
"This list represents the payload of a patch request message.
It carry a sequence of edits on a datastore. Each edit MUST
be applied in ascending order, and all edits MUST be applied.
If any errors occur, then the target datastore SOULD NOT be
changed by the patch operation.";
leaf edit-id {
mandatory true;
type uint8;
Veillette, et al. Expires May 4, 2016 [Page 60]
Internet-Draft Constrained Objects Language November 2015
description
"Error messages returned by the server pertaining to
a specific edit will be identified by this value.";
}
leaf operation {
mandatory true;
type enumeration {
enum "create" {
value 0;
description
"The target data node is created using the supplied
value, only if it does not already exist.";
}
enum "delete" {
value 1;
description
"Delete the target node, only if the data resource
currently exists, otherwise return an error.";
}
enum "merge" {
value 2;
description
"The supplied value is merged with the target
data node.";
}
enum "replace" {
value 3;
description
"The supplied value is used to replace the target
data node.";
}
enum "remove" {
value 4;
description
"Delete the target node if it currently exists.";
}
enum insert-first {
value 5;
description
"Insert the supplied value at the beginning of an
user-ordered-list.";
}
enum insert-last {
value 6;
description
"Insert the supplied value at the end of an
user-ordered-list.";
Veillette, et al. Expires May 4, 2016 [Page 61]
Internet-Draft Constrained Objects Language November 2015
}
enum insert-before {
value 7;
description
"Insert the supplied value in a user-ordered-list
just before the entry identified by 'list-entry'
parameter.";
}
enum insert-after {
value 8;
description
"Insert the supplied value in a user-ordered-list
just after the entry identified by 'list-entry'
parameter.";
}
}
}
leaf list-entry {
when
"(../operation = 'delete' or ../operation = 'remove' or" +
" ../operation = 'insert-before' or" +
" ../operation = 'insert-after' )";
type binary;
mandatory true;
description
"CBOR array containing an instance identifier used to
identify an entry within a list.";
}
anyxml value {
when
"(../operation = 'create' or ../operation = 'merge' or" +
" ../operation = 'replace' or " +
" ../operation = 'insert-first' or" +
" ../operation = 'insert-last' or" +
" ../operation = 'insert-before' or" +
" ../operation = 'insert-after')";
description
"CBOR map containing the tag and value used for this
edit operation.";
}
}
list patch-response {
key "edit-id";
description
"This list represents the payload of a patch request response.
Veillette, et al. Expires May 4, 2016 [Page 62]
Internet-Draft Constrained Objects Language November 2015
Each entry contain the status of an operation included in
the corresponding request message.";
leaf edit-id {
mandatory true;
type uint8;
description
"This value is used to match this entry with the
corresponding entry in the patch-request list";
}
leaf edit-status {
mandatory true;
type status-code;
}
leaf error-text {
mandatory false;
type string;
description "Textual descriptions of the error.";
}
}
}
The following identifiers are assigned to the different objects of
the ietf-cool module.
+------+--------+---------------------------------------------------+
| DNID | FQDNID | Data node |
+------+--------+---------------------------------------------------+
| 0 | 1024 | / |
| 1 | 1025 | container /error-info |
| 2 | 1026 | leaf /error-info/error-code |
| 3 | 1027 | leaf /error-info/error-text |
| 4 | 1028 | list /patch-request |
| 5 | 1029 | leaf /patch-request/edit-id |
| 6 | 1030 | leaf /patch-request/operation |
| 7 | 1031 | leaf /patch-request/list-entry |
| 8 | 1032 | anyxml /patch-request/value |
| 9 | 1033 | list /patch-response |
| 10 | 1034 | leaf /patch-response/edit-id |
| 11 | 1035 | leaf /patch-response/edit-status |
| 12 | 1036 | leaf /patch-response/error-text |
+------+--------+---------------------------------------------------+
Veillette, et al. Expires May 4, 2016 [Page 63]
Internet-Draft Constrained Objects Language November 2015
Appendix B. ietf-cool-library YANG module
This YANG module provides Meta information about modules and sub-
modules implemented by the CoOL server.
module ietf-cool-library {
namespace "urn:ietf:ns:cool:library";
prefix cool;
description
"This YANG module provides Meta information about modules and
sub-modules implemented by the CoOL server";
revision "2015-09-30" {
description "Initial revision.";
}
typedef module-id {
description "Registered identifier of a YANG module.";
type uint32 {
range "1..1048575";
}
}
list modules {
key "module-id revision";
description
"Each entry represents one module currently
supported by the server.";
leaf module-id {
mandatory true;
type module-id;
description
"Registered module ID for this YANG module.";
}
leaf name {
type string;
description
"Name of this YANG module.";
}
leaf revision {
mandatory true;
type string {
Veillette, et al. Expires May 4, 2016 [Page 64]
Internet-Draft Constrained Objects Language November 2015
pattern '\d{4}-\d{2}-\d{2}';
}
description
"Revision of this YANG module. An empty string is used if
no revision statement is present in the YANG module.";
}
leaf-list features {
type string;
description
"List of YANG feature names from this module that are
supported by the server.";
}
leaf-list deviations {
type string;
description
"List of YANG deviation module names used by this server to
modify the conformance of the module associated with this
entry.";
}
list submodules {
key "name revision";
description
"Each entry represents one submodule within the parent
module.";
leaf name {
type string;
description
"Name of this YANG submodule.";
}
leaf revision {
mandatory true;
type string {
pattern '\d{4}-\d{2}-\d{2}';
}
description
"The YANG submodule revision. An empty string is used if
no revision statement is present in the YANG submodule.";
}
}
leaf-list data-nodes {
type uint32;
Veillette, et al. Expires May 4, 2016 [Page 65]
Internet-Draft Constrained Objects Language November 2015
description
"ID of each data node supported by this module, including
those defined in sub-modules.";
}
leaf-list protocol-operations {
type uint32;
description
"ID of each rpc supported by this module, including those
defined in sub-modules.";
}
leaf-list notifications {
type uint32;
description
"ID of each notification supported by this module,
including those defined in sub-modules.";
}
}
rpc is-supported {
description
"Used to verify if an object is supported by a CoOL server";
input {
leaf module-id {
type module-id;
mandatory true;
description "Module ID.";
}
choice object {
case data-node {
leaf data-node-id {
type uint16 {
range "1..1023";
}
mandatory true;
description "Data node ID.";
}
}
case protocol-operation {
leaf protocol-operation-id {
type uint16;
mandatory true;
Veillette, et al. Expires May 4, 2016 [Page 66]
Internet-Draft Constrained Objects Language November 2015
description "Protocol operation ID.";
}
}
case notification {
leaf notification-id {
type uint16;
mandatory true;
description "Notification ID.";
}
}
}
}
output {
leaf supported {
type boolean;
mandatory true;
description
"Return true is the specified object is supported.";
}
}
}
}
The following identifiers are assigned to the different objects of
the cool-library module.
+------+--------+---------------------------------------------------+
| DNID | FQDNID | Data node |
+------+--------+---------------------------------------------------+
| 0 | 2048 | / |
| 1 | 2049 | list /modules |
| 2 | 2050 | leaf /modules/module-id |
| 3 | 2051 | leaf /modules/name |
| 4 | 2052 | leaf /modules/revision |
| 5 | 2053 | leaf-list /modules/features |
| 6 | 2054 | leaf-list /modules/deviations |
| 7 | 2055 | list /modules/submodules |
| 8 | 2056 | leaf /modules/submodules/name |
| 9 | 2057 | leaf /modules/submodules/revision |
| 10 | 2058 | leaf-list /modules/data-nodes |
| 11 | 2059 | leaf-list /modules/protocol-operations |
| 12 | 2060 | leaf-list /modules/notifications |
+------+--------+---------------------------------------------------+
Veillette, et al. Expires May 4, 2016 [Page 67]
Internet-Draft Constrained Objects Language November 2015
+---------------+---------------------------------------------------+
| Protocol | Protocol operation |
| operation IDs | |
+---------------+---------------------------------------------------+
| 1 | /is-supported |
| | +---------------------+-----------------------+ |
| | | Input parameter ID | Input parameter | |
| | +---------------------+-----------------------+ |
| | | 1 | module-id | |
| | | 2 | data-node-id | |
| | | 3 | protocol-operation-id | |
| | | 4 | notification-id | |
| | +---------------------+-----------------------+ |
| | |
| | +---------------------+-----------------------+ |
| | | Output parameter ID | Output parameter | |
| | +---------------------+-----------------------+ |
| | | 1 | supported | |
| | +---------------------+-----------------------+ |
+---------------+---------------------------------------------------+
Authors' Addresses
Michel Veillette (editor)
Trilliant Networks Inc.
610 Rue du Luxembourg
Granby, Quebec J2J 2V2
Canada
Phone: +14503750556
Email: michel.veillette@trilliantinc.com
Alexander Pelov (editor)
Acklio
2 Rue de la Chataigneraie
Cesson-Sevigne, Bretagne 35510
France
Phone: +33299127004
Email: a@ackl.io
Veillette, et al. Expires May 4, 2016 [Page 68]
Internet-Draft Constrained Objects Language November 2015
Somaraju Abhinav
Tridonic GmbH & Co KG
Farbergasse 15
Dornbirn, Vorarlberg 6850
Austria
Phone: +43664808926169
Email: abhinav.somaraju@tridonic.com
Randy Turner
Landis+Gyr
30000 Mill Creek Ave
Suite 100
Alpharetta, GA 30022
US
Phone: ++16782581292
Email: randy.turner@landisgyr.com
URI: http://www.landisgyr.com/
Veillette, et al. Expires May 4, 2016 [Page 69]