[Docs] [txt|pdf|xml|html] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-vanderstok-core-comi) 00 01 02 03 04 05 06

CoRE                                                   M. Veillette, Ed.
Internet-Draft                                   Trilliant Networks Inc.
Intended status: Standards Track                    P. van der Stok, Ed.
Expires: May 16, 2019                                         consultant
                                                                A. Pelov
                                                                  Acklio
                                                              A. Bierman
                                                               YumaWorks
                                                       November 12, 2018


                       CoAP Management Interface
                        draft-ietf-core-comi-04

Abstract

   This document describes a network management interface for
   constrained devices and networks, called CoAP Management Interface
   (CoMI).  The Constrained Application Protocol (CoAP) is used to
   access datastore and data node resources specified in YANG, or SMIv2
   converted to YANG.  CoMI uses the YANG to CBOR mapping and converts
   YANG identifier strings to numeric identifiers for payload size
   reduction.  CoMI extends the set of YANG based protocols, NETCONF and
   RESTCONF, with the capability to manage constrained devices and
   networks.

Note

   Discussion and suggestions for improvement are requested, and should
   be sent to yot@ietf.org.

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 https://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 16, 2019.




Veillette, et al.         Expires May 16, 2019                  [Page 1]


Internet-Draft                    CoMI                     November 2018


Copyright Notice

   Copyright (c) 2018 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
   (https://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 . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  CoMI Architecture . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Major differences between RESTCONF and CoMI . . . . . . .   6
     2.2.  Compression of YANG identifiers . . . . . . . . . . . . .   7
     2.3.  Instance identifier . . . . . . . . . . . . . . . . . . .   8
     2.4.  Content-Formats . . . . . . . . . . . . . . . . . . . . .   8
     2.5.  Unified datastore . . . . . . . . . . . . . . . . . . . .  10
   3.  Example syntax  . . . . . . . . . . . . . . . . . . . . . . .  11
   4.  CoAP Interface  . . . . . . . . . . . . . . . . . . . . . . .  11
     4.1.  Using the 'k' Uri-Query option  . . . . . . . . . . . . .  13
     4.2.  Data Retrieval  . . . . . . . . . . . . . . . . . . . . .  14
       4.2.1.  Using the 'c' Uri-Query option  . . . . . . . . . . .  15
       4.2.2.  Using the 'd' Uri-Query option  . . . . . . . . . . .  15
       4.2.3.  GET . . . . . . . . . . . . . . . . . . . . . . . . .  16
       4.2.4.  FETCH . . . . . . . . . . . . . . . . . . . . . . . .  19
     4.3.  Data Editing  . . . . . . . . . . . . . . . . . . . . . .  20
       4.3.1.  Data Ordering . . . . . . . . . . . . . . . . . . . .  20
       4.3.2.  POST  . . . . . . . . . . . . . . . . . . . . . . . .  20
       4.3.3.  PUT . . . . . . . . . . . . . . . . . . . . . . . . .  21
       4.3.4.  iPATCH  . . . . . . . . . . . . . . . . . . . . . . .  22
       4.3.5.  DELETE  . . . . . . . . . . . . . . . . . . . . . . .  23
     4.4.  Full datastore access . . . . . . . . . . . . . . . . . .  23
       4.4.1.  Full datastore examples . . . . . . . . . . . . . . .  24
     4.5.  Event stream  . . . . . . . . . . . . . . . . . . . . . .  25
       4.5.1.  Notify Examples . . . . . . . . . . . . . . . . . . .  26
     4.6.  RPC statements  . . . . . . . . . . . . . . . . . . . . .  27
       4.6.1.  RPC Example . . . . . . . . . . . . . . . . . . . . .  27
   5.  Access to MIB Data  . . . . . . . . . . . . . . . . . . . . .  28
   6.  Use of Block  . . . . . . . . . . . . . . . . . . . . . . . .  28
   7.  Application Discovery . . . . . . . . . . . . . . . . . . . .  29



Veillette, et al.         Expires May 16, 2019                  [Page 2]


Internet-Draft                    CoMI                     November 2018


     7.1.  YANG library  . . . . . . . . . . . . . . . . . . . . . .  29
     7.2.  Resource Discovery  . . . . . . . . . . . . . . . . . . .  29
       7.2.1.  Datastore Resource Discovery  . . . . . . . . . . . .  30
       7.2.2.  Data node Resource Discovery  . . . . . . . . . . . .  30
       7.2.3.  Event stream Resource Discovery . . . . . . . . . . .  31
   8.  Error Handling  . . . . . . . . . . . . . . . . . . . . . . .  31
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  34
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  35
     10.1.  Resource Type (rt=) Link Target Attribute Values
            Registry . . . . . . . . . . . . . . . . . . . . . . . .  35
     10.2.  CoAP Content-Formats Registry  . . . . . . . . . . . . .  35
     10.3.  Media Types Registry . . . . . . . . . . . . . . . . . .  36
   11. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  37
   12. References  . . . . . . . . . . . . . . . . . . . . . . . . .  38
     12.1.  Normative References . . . . . . . . . . . . . . . . . .  38
     12.2.  Informative References . . . . . . . . . . . . . . . . .  39
   Appendix A.  ietf-comi YANG module  . . . . . . . . . . . . . . .  40
   Appendix B.  ietf-comi .sid file  . . . . . . . . . . . . . . . .  46
   Appendix C.  YANG example specifications  . . . . . . . . . . . .  49
     C.1.  ietf-system . . . . . . . . . . . . . . . . . . . . . . .  49
     C.2.  server list . . . . . . . . . . . . . . . . . . . . . . .  51
     C.3.  interfaces  . . . . . . . . . . . . . . . . . . . . . . .  52
     C.4.  Example-port  . . . . . . . . . . . . . . . . . . . . . .  52
     C.5.  IP-MIB  . . . . . . . . . . . . . . . . . . . . . . . . .  53
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  55

1.  Introduction

   The Constrained Application Protocol (CoAP) [RFC7252] is designed for
   Machine to Machine (M2M) applications such as smart energy, smart
   city and building control.  Constrained devices need to be managed in
   an automatic fashion to handle the large quantities of devices that
   are expected in future installations.  Messages between devices need
   to be as small and infrequent as possible.  The implementation
   complexity and runtime resources need to be as small as possible.

   This draft describes the CoAP Management Interface which uses CoAP
   methods to access structured data defined in YANG [RFC7950].  This
   draft is complementary to [RFC8040] which describes a REST-like
   interface called RESTCONF, which uses HTTP methods to access
   structured data defined in YANG.

   The use of standardized data models specified in a standardized
   language, such as YANG, promotes interoperability between devices and
   applications from different manufacturers.






Veillette, et al.         Expires May 16, 2019                  [Page 3]


Internet-Draft                    CoMI                     November 2018


   CoMI and RESTCONF are intended to work in a stateless client-server
   fashion.  They use a single round-trip to complete a single editing
   transaction, where NETCONF needs multiple round trips.

   To promote small messges, CoMI uses a YANG to CBOR mapping
   [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid]
   to minimize CBOR payloads and URI length.

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].

   The following terms are defined in the YANG data modelling language
   [RFC7950]: action, anydata, anyxml, client, container, data model,
   data node, identity, instance identifier, leaf, leaf-list, list,
   module, RPC, schema node, server, submodule.

   The following terms are defined in [RFC6241]: configuration data,
   datastore, state data

   The following term is defined in [I-D.ietf-core-yang-cbor]: YANG
   schema item identifier (SID).

   The following terms are defined in the CoAP protocol [RFC7252]:
   Confirmable Message, Content-Format, Endpoint.

   The following terms are defined in this document:

   data node resource:  a CoAP resource that models a YANG data node.

   datastore resource:  a CoAP resource that models a YANG datastore.

   event stream resource:  a CoAP resource used by clients to observe
      YANG notifications.

   notification instance:  An instance of a schema node of type
      notification, specified in a YANG module implemented by the
      server.  The instance is generated in the server at the occurrence
      of the corresponding event and reported by an event stream.

   list instance identifier:  Handle used to identify a YANG data node
      that is an instance of a YANG "list" specified with the values of
      the key leaves of the list.

   single instance identifier:  Handle used to identify a specific data
      node which can be instantiated only once.  This includes data



Veillette, et al.         Expires May 16, 2019                  [Page 4]


Internet-Draft                    CoMI                     November 2018


      nodes defined at the root of a YANG module and data nodes defined
      within a container.  This excludes data nodes defined within a
      list or any children of these data nodes.

   instance-identifier:  List instance identifier or single instance
      identifier.

   instance-value:  The value assigned to a schema node instance.
      Schema node values are serialized into the payload according to
      the rules defined in section 4 of [I-D.ietf-core-yang-cbor].

2.  CoMI Architecture

   This section describes the CoMI architecture to use CoAP for reading
   and modifying the content of datastore(s) used for the management of
   the instrumented node.

   +----------------------------------------------------------------+
   |                     SMIv2 specification (2)                    |
   +----------------------------------------------------------------+
                                  |
                                  V
   +----------------------------------------------------------------+
   |                     YANG specification  (1)                    |
   +----------------------------------------------------------------+
            |                                            |
   Client   V                               Server       V
   +----------------+                       +-----------------------+
   | Request        |--> CoAP request(3) -->| Indication            |
   | Confirm        |<-- CoAP response(3)<--| Response          (4) |
   |                |                       |                       |
   |                |<==== Security (7) ===>|+---------------------+|
   +----------------+                       || Datastore(s)    (5) ||
                                            |+---------------------+|
                                            |+---------------------+|
                                            || Event stream(s) (6) ||
                                            |+---------------------+|
                                            +-----------------------+

                   Figure 1: Abstract CoMI architecture

   Figure 1 is a high-level representation of the main elements of the
   CoMI management architecture.  The different numbered components of
   Figure 1 are discussed according to component number.

   (1) YANG specification:  contains a set of named and versioned
      modules.




Veillette, et al.         Expires May 16, 2019                  [Page 5]


Internet-Draft                    CoMI                     November 2018


   (2) SMIv2 specification:  A named module specifies a set of variables
      and "conceptual tables".  There is an algorithm to translate SMIv2
      specifications to YANG specifications.

   (3) CoAP request/response messages:  The CoMI client sends request
      messages to and receives response messages from the CoMI server.

   (4) Request, Indication, Response, Confirm:  Processes performed by
      the CoMI clients and servers.

   (5) Datastore:  A resource used to access configuration data, state
      data, RPCs and actions.  A CoMI server may support a single
      unified datastore or multiple datastores as those defined by
      Network Management Datastore Architecture (NMDA) [RFC8342].

   (6) Event stream:  A resource used to get real time notifications.  A
      CoMI server may support multiple Event streams serving different
      purposes such as normal monitoring, diagnostic, syslog, security
      monitoring.

   (7) Security:  The server MUST prevent unauthorized users from
      reading or writing any CoMI resources.  CoMI relies on security
      protocols such as DTLS [RFC6347] to secure CoAP communication.

2.1.  Major differences between RESTCONF and CoMI

   CoMI is a RESTful protocol for small devices where saving bytes to
   transport counts.  Contrary to RESTCONF, many design decisions are
   motivated by the saving of bytes.  Consequently, CoMI is not a
   RESTCONF over CoAP protocol, but differs more significantly from
   RESTCONF.  Some major differences are cited below:

   o  CoMI uses CoAP/UDP as transport protocol and CBOR as payload
      format [I-D.ietf-core-yang-cbor].  RESTCONF uses HTTP/TCP as
      transport protocol and JSON or XML as payload formats.

   o  CoMI encodes YANG identifier strings as numbers, where RESTCONF
      does not.

   o  CoMI uses the methods FETCH and iPATCH to access multiple data
      nodes.  RESTCONF uses instead the HTTP method PATCH and the HTTP
      method GET with the "fields" Query parameter.

   o  RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not
      used by CoAP.






Veillette, et al.         Expires May 16, 2019                  [Page 6]


Internet-Draft                    CoMI                     November 2018


   o  CoMI does not support "insert" query parameter (first, last,
      before, after) and the "point" query parameter which are supported
      by RESTCONF.

   o  CoMI does not support the "start-time" and "stop-time" query
      parameters to retrieve past notifications.

   o  CoMI does not support the "filter" query parameters to observe a
      specific set of notifications.

   o  CoMI also differ in the handling of default values, only 'report-
      all' and 'trip' options are supported.

2.2.  Compression of YANG identifiers

   In the YANG specification, items are identified with a name string.
   In order to significantly reduce the size of identifiers used in
   CoMI, numeric identifiers are used instead of these strings.  YANG
   Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor]
   section 2.1.

   When used in a URI, SIDs are encoded in based64 using the URL and
   Filename safe alphabet as defined by [RFC4648] section 5.  The last 6
   bits encoded is always aligned with the least significant 6 bits of
   the SID represented using an unsigned integer.  'A' characters (value
   0) at the start of the resulting string are removed.

   SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] |
                    URLsafeChar[SID >> 54 & 0x3F] |
                    URLsafeChar[SID >> 48 & 0x3F] |
                    URLsafeChar[SID >> 42 & 0x3F] |
                    URLsafeChar[SID >> 36 & 0x3F] |
                    URLsafeChar[SID >> 30 & 0x3F] |
                    URLsafeChar[SID >> 24 & 0x3F] |
                    URLsafeChar[SID >> 18 & 0x3F] |
                    URLsafeChar[SID >> 12 & 0x3F] |
                    URLsafeChar[SID >> 6 & 0x3F] |
                    URLsafeChar[SID & 0x3F]

   For example, SID 1721 is encoded as follow.











Veillette, et al.         Expires May 16, 2019                  [Page 7]


Internet-Draft                    CoMI                     November 2018


   URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A'
   URLsafeChar[1721 >> 6 & 0x3F]  = URLsafeChar[26] = 'a'
   URLsafeChar[1721 & 0x3F]       = URLsafeChar[57] = '5'

   The resulting base64 representation of SID 1721 is "a5"

2.3.  Instance identifier

   Instance identifiers are used to uniquely identify data node
   instances within a datastore.  This YANG built-in type is defined in
   [RFC7950] section 9.13.  An instance identifier is composed of the
   data node identifier (i.e. a SID) and for data nodes within list(s)
   the keys used to index within these list(s).

   When part of a payload, instance identifiers are encoded in CBOR
   based on the rules defined in [I-D.ietf-core-yang-cbor] section
   6.13.1.  When part of a URI, the SID is appended to the URI of the
   targeted datastore, the keys are specified using the 'k' URI-Query as
   defined in Section 4.1.

2.4.  Content-Formats

   ComI uses Content-Formats based on the YANG to CBOR mapping specified
   in [I-D.ietf-core-yang-cbor].

   The following Content-formats are defined:

   application/yang-data+cbor:  This Content-Format represents a CBOR
      YANG document containing one or multiple data node values.  Each
      data node is identified by its associated SID.

      FORMAT: CBOR map of SID, instance-value

      The message payload of Content-Format 'application/yang-data+cbor'
      is encoded using a CBOR map.  Each entry of this CBOR map is
      composed of a key and a value.  CBOR map keys are set to the SID
      assigned to the data nodes, CBOR map values are set to the
      instance value as defined in [I-D.ietf-core-yang-cbor] section 4.





Veillette, et al.         Expires May 16, 2019                  [Page 8]


Internet-Draft                    CoMI                     November 2018


   application/yang-identifiers+cbor:  This Content-Format represents a
      CBOR YANG document containing a list of instance identifier used
      to target specific data node instances within a datastore.

      FORMAT: CBOR array of instance-identifier

      The message payload of Content-Format 'application/yang-
      identifiers+cbor' is encoded using a CBOR array.  Each entry of
      this CBOR array contain an instance identifier encoded as defined
      in [I-D.ietf-core-yang-cbor] section 6.13.1.

   application/yang-instances+cbor:  This Content-Format represents a
      CBOR YANG document containing a list of data node instances.  Each
      data node instance is identified by its associated instance
      identifier.

      FORMAT: CBOR array of CBOR map of instance-identifier, instance-
      value

      The message payload of Content-Format 'application/yang-
      instances+cbor' is encoded using a CBOR array.  Each entry within
      this CBOR array contains a CBOR map carrying a single instance
      identifier and associated value.  Instance identifiers are encoded
      using the rules defined in [I-D.ietf-core-yang-cbor] section
      6.13.1, values are encoded using the rules defined in
      [I-D.ietf-core-yang-cbor] section 4.

      When present in an iPATCH request payload, this Content-Format
      carry a list of data node instances to be replaced, created, or
      deleted.  For each data node instance D, for which the instance
      identifier is the same as a data node instance I, in the targeted
      datastore resource: the value of D replaces the value of I.  When
      the value of D is null, the data node instance I is removed.  When
      the targeted datastore resource does not contain a data node
      instance with the same instance identifier as D, a new instance is
      created with the same instance identifier and value as D.

   The different Content-formats usage are summarized in the table
   below:












Veillette, et al.         Expires May 16, 2019                  [Page 9]


Internet-Draft                    CoMI                     November 2018


   +---------------+--------------+------------------------------------+
   | Method        | Resource     | Content-Format                     |
   +---------------+--------------+------------------------------------+
   | GET response  | data node    | /application/yang-data+cbor        |
   |               |              |                                    |
   | PUT request   | data node    | /application/yang-data+cbor        |
   |               |              |                                    |
   | POST request  | data node    | /application/yang-data+cbor        |
   |               |              |                                    |
   | DELETE        | data node    | n/a                                |
   |               |              |                                    |
   | GET response  | datastore    | /application/yang-data+cbor        |
   |               |              |                                    |
   | PUT request   | datastore    | /application/yang-data+cbor        |
   |               |              |                                    |
   | POST request  | datastore    | /application/yang-data+cbor        |
   |               |              |                                    |
   | FETCH request | datastore    | /application/yang-identifiers+cbor |
   |               |              |                                    |
   | FETCH         | datastore    | /application/yang-instances+cbor   |
   | response      |              |                                    |
   |               |              |                                    |
   | iPATCH        | datastore    | /application/yang-instances+cbor   |
   | request       |              |                                    |
   |               |              |                                    |
   | GET response  | event stream | /application/yang-instances+cbor   |
   |               |              |                                    |
   | POST request  | rpc, action  | /application/yang-data+cbor        |
   |               |              |                                    |
   | POST response | rpc, action  | /application/yang-data+cbor        |
   +---------------+--------------+------------------------------------+

2.5.  Unified datastore

   CoMI supports a simple datastore model consisting of on a single
   unified datastore.  This datasore provides access to both
   configuration and operational data.  Configuration updates performed
   on this datastore are reflected immediately or with a minimal delay
   as operational data.

   Alternatively, CoMI servers MAY implement a more complex datastore
   model such as the Network Management Datastore Architecture (NMDA) as
   defined by [RFC8342].  Each datastore supported is implemented as a
   datastore resource.

   Characteristics of the unified datastore are summarized in the table
   below:




Veillette, et al.         Expires May 16, 2019                 [Page 10]


Internet-Draft                    CoMI                     November 2018


   +-------------+-----------------------------------------------------+
   | Name        | Value                                               |
   +-------------+-----------------------------------------------------+
   | Name        | unified                                             |
   |             |                                                     |
   | YANG        | all modules                                         |
   | modules     |                                                     |
   |             |                                                     |
   | YANG nodes  | all data nodes ("config true" and "config false")   |
   |             |                                                     |
   | Access      | read-write                                          |
   |             |                                                     |
   | How applied | changes applied in place immediately or with a      |
   |             | minimal delay                                       |
   |             |                                                     |
   | Protocols   | CoMI                                                |
   |             |                                                     |
   | Defined in  | "ietf-comi"                                         |
   +-------------+-----------------------------------------------------+

3.  Example syntax

   This section presents the notation used for the examples.  The YANG
   modules that are used throughout this document are shown in
   Appendix C.  The example modules are copied from existing modules and
   annotated with SIDs.

   CBOR is used to encode CoMI request and response payloads.  The CBOR
   syntax of the YANG payloads is specified in [RFC7049].  The payload
   examples are notated in Diagnostic notation (defined in section 6 of
   [RFC7049]) that can be automatically converted to CBOR.

   SIDs in URIs are represented as a base64 number, SIDs in the payload
   are represented as decimal numbers.

4.  CoAP Interface

   This note specifies a Management Interface.  CoAP endpoints that
   implement the CoMI management protocol, support at least one
   discoverable management resource of resource type (rt): core.c.ds,
   with example path: /c, where c is short-hand for CoMI.  The path /c
   is recommended, but not compulsory (see Section 7).

   The mapping of YANG data node instances to CoMI resources is as
   follows.  Every data node of the YANG modules loaded in the CoMI
   server represents a sub-resource of the datastore resource (e.g. /c/
   sid).  When multiple instances of a list exist, instance selection is




Veillette, et al.         Expires May 16, 2019                 [Page 11]


Internet-Draft                    CoMI                     November 2018


   possible as described in Section 4.1, Section 4.2.3.1, and
   Section 4.2.4.

   CoMI also supports event stream resourced used to observe
   notification instances.  Event stream resources can be discovered
   using resource type (rt): core.c.ev.

   The description of the CoMI management interface is shown in the
   table below:

   +-------------+------------------+-----------+
   | Function    | Recommended path | rt        |
   +-------------+------------------+-----------+
   | Datastore   | /c               | core.c.ds |
   |             |                  |           |
   | Data node   | /c/SID           | core.c.dn |
   |             |                  |           |
   | Event steam | /s               | core.c.ev |
   +-------------+------------------+-----------+

   The path values are example values.  On discovery, the server makes
   the actual path values known for these resources.

   The methods used by CoMI are:

   +-----------+-------------------------------------------------------+
   | Operation | Description                                           |
   +-----------+-------------------------------------------------------+
   | GET       | Retrieve the datastore resource or a data node        |
   |           | resource                                              |
   |           |                                                       |
   | FETCH     | Retrieve specific data nodes within a datastore       |
   |           | resource                                              |
   |           |                                                       |
   | POST      | Create a datastore resource or a data node resource,  |
   |           | invoke an RPC or action                               |
   |           |                                                       |
   | PUT       | Create or replace a datastore resource or a data node |
   |           | resource                                              |
   |           |                                                       |
   | iPATCH    | Idem-potently create, replace, and delete data node   |
   |           | resource(s) within a datastore resource               |
   |           |                                                       |
   | DELETE    | Delete a datastore resource or a data node resource   |
   +-----------+-------------------------------------------------------+

   There is one Uri-Query option for the GET, PUT, POST, and DELETE
   methods.



Veillette, et al.         Expires May 16, 2019                 [Page 12]


Internet-Draft                    CoMI                     November 2018


   +------------------+----------------------------------------+
   | Uri-Query option | Description                            |
   +------------------+----------------------------------------+
   | k                | Select an instance within YANG list(s) |
   +------------------+----------------------------------------+

   This parameter is not used for FETCH and iPATCH, because their
   request payloads support list instance selection.

4.1.  Using the 'k' Uri-Query option

   The "k" (key) parameter specifies a specific instance of a data node.
   The SID in the URI is followed by the (?k=key1, key2,..).  Where SID
   identifies a data node, and key1, key2 are the values of the key
   leaves that specify an instance.  Lists can have multiple keys, and
   lists can be part of lists.  The order of key value generation is
   given recursively by:

   o  For a given list, if a parent data node is a list, generate the
      keys for the parent list first.

   o  For a given list, generate key values in the order specified in
      the YANG module.

   Key values are encoded using the rules defined in the following
   table.

























Veillette, et al.         Expires May 16, 2019                 [Page 13]


Internet-Draft                    CoMI                     November 2018


   +-----------------------------+--------------------------------+
   | YANG datatype               | Uri-Query text content         |
   +-----------------------------+--------------------------------+
   | uint8,uint16,unit32, uint64 | int2str(key)                   |
   |                             |                                |
   | int8, int16,int32, int64    | urlSafeBase64(CBORencode(key)) |
   |                             |                                |
   | decimal64                   | urlSafeBase64(CBOR key)        |
   |                             |                                |
   | string                      | key                            |
   |                             |                                |
   | boolean                     | "0" or "1"                     |
   |                             |                                |
   | enumeration                 | int2str(key)                   |
   |                             |                                |
   | bits                        | urlSafeBase64(CBORencode(key)) |
   |                             |                                |
   | binary                      | urlSafeBase64(key)             |
   |                             |                                |
   | identityref                 | int2str(key)                   |
   |                             |                                |
   | union                       | urlSafeBase64(CBORencode(key)) |
   |                             |                                |
   | instance-identifier         | urlSafeBase64(CBORencode(key)) |
   +-----------------------------+--------------------------------+

   In this table:

   o  The method int2str() is used to convert an integer value to a
      string.  For example, int2str(0x0123) return the string "291".

   o  The method urlSafeBase64() is used to convert a binary string to
      base64 using the URL and Filename safe alphabet as defined by
      [RFC4648] section 5.  For example, urlSafeBase64(\xF9\x56\xA1\x3C)
      return the string "-VahPA".

   o  The method CBORencode() is used to convert a YANG value to CBOR as
      specified in [I-D.ietf-core-yang-cbor] section 6.

   The resulting key string is encoded in a Uri-Query as specified in
   [RFC7252] section 6.5.

4.2.  Data Retrieval

   One or more data nodes can be retrieved by the client.  The operation
   is mapped to the GET method defined in section 5.8.1 of [RFC7252] and
   to the FETCH method defined in section 2 of [RFC8132].




Veillette, et al.         Expires May 16, 2019                 [Page 14]


Internet-Draft                    CoMI                     November 2018


   It is possible that the size of the payload is too large to fit in a
   single message.  In the case that management data is bigger than the
   maximum supported payload size, the Block mechanism from [RFC7959]
   may be used, as explained in more detail in Section 6.

   There are two additional Uri-Query options for the GET and FETCH
   methods.

   +-------------+-----------------------------------------------------+
   | Uri-Query   | Description                                         |
   | option      |                                                     |
   +-------------+-----------------------------------------------------+
   | c           | Control selection of configuration and non-         |
   |             | configuration data nodes (GET and FETCH)            |
   |             |                                                     |
   | d           | Control retrieval of default values.                |
   +-------------+-----------------------------------------------------+

4.2.1.  Using the 'c' Uri-Query option

   The 'c' (content) parameter controls how descendant nodes of the
   requested data nodes will be processed in the reply.

   The allowed values are:

   +-------+-----------------------------------------------------+
   | Value | Description                                         |
   +-------+-----------------------------------------------------+
   | c     | Return only configuration descendant data nodes     |
   |       |                                                     |
   | n     | Return only non-configuration descendant data nodes |
   |       |                                                     |
   | a     | Return all descendant data nodes                    |
   +-------+-----------------------------------------------------+

   This parameter is only allowed for GET and FETCH methods on datastore
   and data node resources.  A 4.02 (Bad Option) error is returned if
   used for other methods or resource types.

   If this Uri-Query option is not present, the default value is "a".

4.2.2.  Using the 'd' Uri-Query option

   The "d" (with-defaults) parameter controls how the default values of
   the descendant nodes of the requested data nodes will be processed.

   The allowed values are:




Veillette, et al.         Expires May 16, 2019                 [Page 15]


Internet-Draft                    CoMI                     November 2018


   +-------+-----------------------------------------------------------+
   | Value | Description                                               |
   +-------+-----------------------------------------------------------+
   | a     | All data nodes are reported. Defined as 'report-all' in   |
   |       | section 3.1 of [RFC6243].                                 |
   |       |                                                           |
   | t     | Data nodes set to the YANG default are not reported.      |
   |       | Defined as 'trim' in section 3.2 of [RFC6243].            |
   +-------+-----------------------------------------------------------+

   If the target of a GET or FETCH method is a data node that represents
   a leaf that has a default value, and the leaf has not been given a
   value by any client yet, the server MUST return the default value of
   the leaf.

   If the target of a GET method is a data node that represents a
   container or list that has child resources with default values, and
   these have not been given value yet,

      The server MUST not return the child resource if d= 't'

      The server MUST return the child resource if d= 'a'.

   If this Uri-Query option is not present, the default value is 't'.

4.2.3.  GET

   A request to read the values of a data node instance is sent with a
   CoAP GET message.  An instance identifier is specified in the URI
   path prefixed with the example path /c.

   FORMAT:
     GET /c/instance-identifier

     2.05 Content (Content-Format: application/yang-data+cbor)
     CBOR map of SID, instance-value

   The returned payload contains the CBOR encoding of the specified data
   node instance value.

4.2.3.1.  GET Examples

   Using for example the current-datetime leaf from Appendix C.1, a
   request is sent to retrieve the value of 'system-state/clock/current-
   datetime' specified in container system-state.  The SID of 'system-
   state/clock/current-datetime' is 1723, encoded in base64 according to
   Section 2.2, yields a7.  The response to the request returns the CBOR
   map with the key set to the SID of the requested data node (i.e.



Veillette, et al.         Expires May 16, 2019                 [Page 16]


Internet-Draft                    CoMI                     November 2018


   1723) and the value encoded using a 'text string' as defined in
   [I-D.ietf-core-yang-cbor] section 6.4.

   REQ: GET example.com/c/a7

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1723 : "2014-10-26T12:16:31Z"
   }

   The next example represents the retrieval of a YANG container.  In
   this case, the CoMI client performs a GET request on the clock
   container (SID = 1721; base64: a5).  The container returned is
   encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor]
   section 4.2.

   REQ: GET example.com/c/a5

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1721 : {
       +2 : "2014-10-26T12:16:51Z",   / current-datetime SID 1723 /
       +1 : "2014-10-21T03:00:00Z"    / boot-datetime SID 1722 /
     }
   }

   This example shows the retrieval of the /interfaces/interface YANG
   list accessed using SID 1533 (base64: X9).  The return payload is
   encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor]
   section 4.4.1 containing 2 instances.





















Veillette, et al.         Expires May 16, 2019                 [Page 17]


Internet-Draft                    CoMI                     November 2018


   REQ: GET example.com/c/X9

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1533 : [
       {
         +4 : "eth0",                / name  (SID 1537) /
         +1 : "Ethernet adaptor",    / description (SID 1534) /
         +5 : 1880,                  / type, (SID 1538) identity /
                                     / ethernetCsmacd (SID 1880) /
         +2 : true                   / enabled ( SID 1535) /
       },
       {
         +4 : "eth1",                / name (SID 1537) /
         +1 : "Ethernet adaptor",    / description (SID 1534) /
         +5 : 1880,                  / type, (SID 1538) identity /
                                     / ethernetCsmacd (SID 1880) /
         +2 : false                  / enabled ( SID 1535) /
       }
     ]
   }

   To retrieve a specific instance within the /interfaces/interface YANG
   list, the CoMI client adds the key of the targeted instance in its
   CoAP request using the 'k' URI-Query.  The return payload containing
   the instance requested is encoded using a CBOR array as specified by
   [I-D.ietf-core-yang-cbor] section 4.4.1.

   REQ: GET example.com/c/X9?k="eth0"

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1533 : [
       {
         +4 : "eth0",                / name  (SID 1537) /
         +1 : "Ethernet adaptor",    / description (SID 1534) /
         +5 : 1880,                  / type, (SID 1538) identity /
                                     / ethernetCsmacd (SID 1880) /
         +2 : true                   / enabled ( SID 1535) /
       }
     ]
   }

   It is equally possible to select a leaf of a specific instance of a
   list.  The example below requests the description leaf (SID=1534,
   base64: X-) within the interface list corresponding to the interface
   name "eth0".  The returned value is encoded in CBOR based on the
   rules specified by [I-D.ietf-core-yang-cbor] section 5.4.



Veillette, et al.         Expires May 16, 2019                 [Page 18]


Internet-Draft                    CoMI                     November 2018


   REQ: GET example.com/c/X-?k="eth0"

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1534 : "Ethernet adaptor"
   }

4.2.4.  FETCH

   The FETCH is used to retrieve multiple data node instance values.
   The FETCH request payload contains the list of instance identifier of
   the data node instances requested.

   The return response payload contains a list of data node instance
   values in the same order as requested.  A CBOR null is returned for
   each data node requested by the client, not supported by the server
   or not currently instantiated.

   For compactness, indexes of the list instance identifiers returned by
   the FETCH response SHOULD be elided, only the SID is provided.  In
   this case, the format of each entry within the CBOR array of the
   FETCH response is identical to the format as a GET response.

   FORMAT:
     FETCH /c (Content-Format: application/yang-identifiers+cbor)
     CBOR array of instance-identifier

     2.05 Content (Content-Format: application/yang-instances+cbor)
     CBOR array of CBOR map of instance-identifier, instance-value

4.2.4.1.  FETCH examples

   This example uses the current-datetime leaf and the interface list
   from Appendix C.1.  In this example the value of current-datetime
   (SID 1723) and the interface list (SID 1533) instance identified with
   name="eth0" are queried.















Veillette, et al.         Expires May 16, 2019                 [Page 19]


Internet-Draft                    CoMI                     November 2018


   REQ:  FETCH /c (Content-Format: application/yang-identifiers+cbor)
   [
     1723,            / current-datetime (SID 1723) /
     [1533, "eth0"]   / interface (SID 1533) with name = "eth0" /
   ]

   RES:  2.05 Content (Content-Format: application/yang-instances+cbor)
   [
     {
       1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) /
     },
     {
       1533 : {
         +4 : "eth0",                / name (SID 1537) /
         +1 : "Ethernet adaptor",    / description (SID 1534) /
         +5 : 1880,                  / type (SID 1538), identity /
                                     / ethernetCsmacd (SID 1880) /
         +2 : true                   / enabled (SID 1535) /
       }
     }
   ]

4.3.  Data Editing

   CoMI allows datastore contents to be created, modified and deleted
   using CoAP methods.

4.3.1.  Data Ordering

   A CoMI server SHOULD preserve the relative order of all user-ordered
   list and leaf-list entries that are received in a single edit
   request.  These YANG data node types are encoded as CBOR arrays so
   messages will preserve their order.

4.3.2.  POST

   The CoAP POST operation is used in CoMI for creation of data node
   resources and the invocation of "ACTION" and "RPC" resources.  Refer
   to Section 4.6 for details on "ACTION" and "RPC" resources.

   A request to create a data node resource is sent with a CoAP POST
   message.  The URI specifies the data node to be instantiated at the
   exception of list instances.  In this case, for compactness, the URI
   specifies the list for which an instance is created.







Veillette, et al.         Expires May 16, 2019                 [Page 20]


Internet-Draft                    CoMI                     November 2018


   FORMAT:
     POST /c/<instance identifier>
     (Content-Format :application/yang-data+cbor)
     CBOR map of SID, instance-value

     2.01 Created

   If the data node resource already exists, then the POST request MUST
   fail and a "4.09 Conflict" response code MUST be returned

4.3.2.1.  Post example

   The example uses the interface list from Appendix C.1.  Example is
   creating a new list instance within the interface list (SID = 1533):

   REQ: POST /c/X9 (Content-Format: application/yang-data+cbor)
   {
     1533 : [
       {
         +4 : "eth5",             / name (SID 1537) /
         +1 : "Ethernet adaptor", / description (SID 1534) /
         +5 : 1880,               / type (SID 1538), identity /
                                  / ethernetCsmacd (SID 1880) /
         +2 : true                / enabled (SID 1535) /
       }
     ]
   }

   RES: 2.01 Created

4.3.3.  PUT

   A data node resource instance is created or replaced with the PUT
   method.  A request to set the value of a data node instance is sent
   with a CoAP PUT message.

   FORMAT:
     PUT /c/<instanceidentifier>
              (Content-Format :application/yang-data+cbor)
     CBOR map of SID, instance-value

     2.01 Created

4.3.3.1.  PUT example

   The example uses the interface list from Appendix C.1.  Example is
   renewing an instance of the list interface (SID = 1533) with key
   name="eth0":



Veillette, et al.         Expires May 16, 2019                 [Page 21]


Internet-Draft                    CoMI                     November 2018


   REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor)
   {
     1533 : [
       {
         +4 : "eth0",             / name (SID 1537) /
         +1 : "Ethernet adaptor", / description (SID 1534) /
         +5 : 1880,               / type (SID 1538), identity /
                                  / ethernetCsmacd (SID 1880) /
         +2 : true                / enabled (SID 1535) /
       }
     ]
   }

   RES:  2.04 Changed

4.3.4.  iPATCH

   One or multiple data node instances are replaced with the idempotent
   iPATCH method [RFC8132].  A request is sent with a CoAP iPATCH
   message.

   There are no Uri-Query options for the iPATCH method.

   The processing of the iPATCH command is specified by Content-Format
   'application/yang-instances+cbor'.  In summary, if the CBOR patch
   payload contains a data node instance that is not present in the
   target, this instance is added.  If the target contains the specified
   instance, the content of this instance is replaced with the value of
   the payload.  A null value indicates the removal of an existing data
   node instance.

   FORMAT:
     iPATCH /c (Content-Format:  application/yang-instances+cbor)
     CBOR array of CBOR map of instance-identifier, instance-value

     2.04 Changed

4.3.4.1.  iPATCH example

   In this example, a CoMI client requests the following operations:

   o  Set "/system/ntp/enabled" (SID 1755) to true.

   o  Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID
      1756) list.

   o  Add/set the server "NTP Pool server 2" to the list "/system/ntp/
      server" (SID 1756).



Veillette, et al.         Expires May 16, 2019                 [Page 22]


Internet-Draft                    CoMI                     November 2018


   REQ: iPATCH /c (Content-Format: application/yang-instances+cbor)
   [
     {
       1755 : true                   / enabled (SID 1755) /
     },
     {
       [1756, "tac.nrc.ca"] : null   / server (SID 1756) /
     },
     {
       1756 : {                      / server (SID 1756) /
         +3 : "tic.nrc.ca",          / name (SID 1759) /
         +4 : true,                  / prefer (SID 1760) /
         +5 : {                      / udp (SID 1761) /
           +1 : "132.246.11.231"     / address (SID 1762) /
         }
       }
     }
   ]

   RES: 2.04 Changed

4.3.5.  DELETE

   A data node resource is deleted with the DELETE method.

   FORMAT:
     Delete /c/<instance identifier>

     2.02 Deleted

4.3.5.1.  DELETE example

   This example uses the interface list from Appendix C.3.  This example
   is deleting an instance of the interface list (SID = 1533):

   REQ:   DELETE /c/X9?k="eth0"

   RES:   2.02 Deleted

4.4.  Full datastore access

   The methods GET, PUT, POST, and DELETE can be used to request,
   replace, create, and delete a whole datastore respectively.








Veillette, et al.         Expires May 16, 2019                 [Page 23]


Internet-Draft                    CoMI                     November 2018


   FORMAT:
     GET /c

     2.05 Content (Content-Format: application/yang-data+cbor)
     CBOR map of SID, instance-value

   FORMAT:
     PUT /c (Content-Format: application/yang-data+cbor)
     CBOR map of SID, instance-value

     2.04 Changed

   FORMAT:
     POST /c (Content-Format: application/yang-data+cbor)
     CBOR map of SID, instance-value

     2.01 Created

   FORMAT:
      DELETE /c

     2.02 Deleted

   The content of the CBOR map represents the complete datastore of the
   server at the GET indication of after a successful processing of a
   PUT or POST request.

4.4.1.  Full datastore examples

   The example uses the interface list and the clock container from
   Appendix C.3.  Assume that the datastore contains two modules ietf-
   system (SID 1700) and ietf-interfaces (SID 1500); they contain the
   'interface' list (SID 1533) with one instance and the 'clock'
   container (SID 1721).  After invocation of GET, a CBOR map with data
   nodes from these two modules is returned:
















Veillette, et al.         Expires May 16, 2019                 [Page 24]


Internet-Draft                    CoMI                     November 2018


   REQ:  GET /c

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     1721 : {                       / Clock (SID 1721) /
       +2: "2016-10-26T12:16:31Z",  / current-datetime (SID 1723) /
       +1: "2014-10-05T09:00:00Z"   / boot-datetime (SID 1722) /
     },
     1533 : [
       {                       / interface (SID 1533) /
         +4 : "eth0",                 / name (SID 1537) /
         +1 : "Ethernet adaptor",     / description (SID 1534) /
         +5 : 1880,                   / type (SID 1538), identity: /
                                      / ethernetCsmacd (SID 1880) /
         +2 : true                    / enabled (SID 1535) /
       }
     ]
   }

4.5.  Event stream

   Event notification is an essential function for the management of
   servers.  CoMI allows notifications specified in YANG [RFC5277] to be
   reported to a list of clients.  The recommended path of the default
   event stream is /s.  The server MAY support additional event stream
   resources to address different notification needs.

   Reception of notification instances is enabled with the CoAP Observe
   [RFC7641] function.  Clients subscribe to the notifications by
   sending a GET request with an "Observe" option, specifying the /s
   resource when the default stream is selected.

   Each response payload carries one or multiple notifications.  The
   number of notification reported and the conditions used to remove
   notifications from the reported list is left to implementers.  When
   multiple notifications are reported, they MUST be ordered starting
   from the newest notification at index zero.

   The format of notification contents is defined in
   [I-D.ietf-core-yang-cbor] section 4.2.1.  For notification without
   any content, a null value is returned.

   An example implementation is:

      Every time an event is generated, the generated notification
      instance is appended to the chosen stream(s).  After an
      aggregation period, which may be adjusted using an exclusion delay
      and limited by the maximum number of notifications supported, the



Veillette, et al.         Expires May 16, 2019                 [Page 25]


Internet-Draft                    CoMI                     November 2018


      content of the instance is sent to all clients observing the
      modified stream.

   FORMAT:
     GET /<stream-resource> Observe(0)

     2.05 Content (Content-Format :application/yang-instances+cbor)
     CBOR array of CBOR map of instance-identifier, instance-value

   The array of data node instances may contain identical entries which
   have been generated at different times.

4.5.1.  Notify Examples

   Suppose the server generates the event specified in Appendix C.4.  By
   executing a GET on the /s resource the client receives the following
   response:

   REQ:  GET /s Observe(0) Token(0x93)

   RES:  2.05 Content (Content-Format :application/yang-tree+cbor)
                           Observe(12) Token(0x93)
   [
     {
       60010 : {             / example-port-fault (SID 60010) /
         +1 : "0/4/21",      / port-name (SID 60011) /
         +2 : "Open pin 2"   / port-fault (SID 60012) /
       }
     },
     {
       60010 : {             / example-port-fault (SID 60010) /
         +1 : "1/4/21",      / port-name (SID 60011) /
         +2 : "Open pin 5"   / port-fault (SID 60012) /
       }
     }
   ]

   In the example, the request returns a success response with the
   contents of the last two generated events.  Consecutively the server
   will regularly notify the client when a new event is generated.

   To check that the client is still alive, the server MUST send
   Confirmable Message periodically.  When the client does not confirm
   the notification from the server, the server will remove the client
   from the list of observers [RFC7641].






Veillette, et al.         Expires May 16, 2019                 [Page 26]


Internet-Draft                    CoMI                     November 2018


4.6.  RPC statements

   The YANG "action" and "RPC" statements specify the execution of a
   Remote procedure Call (RPC) in the server.  It is invoked using a
   POST method to an "Action" or "RPC" resource instance.

   The request payload contains the values assigned to the input
   container when specified.  The response payload contains the values
   of the output container when specified.  Both the input and output
   containers are encoded in CBOR using the rules defined in
   [I-D.ietf-core-yang-cbor] section 4.2.1.

   The returned success response code is 2.05 Content.

   FORMAT:
     POST /c/<instance identifier>
              (Content-Format :application/yang-data+cbor)
     CBOR map of SID, instance-value

     2.05 Content (Content-Format :application/yang-data+cbor)
     CBOR map of SID, instance-value


4.6.1.  RPC Example

   The example is based on the YANG action specification of
   Appendix C.2.  A server list is specified and the action "reset" (SID
   60002, base64: Opq), that is part of a "server instance" with key
   value "myserver", is invoked.

   REQ:  POST /c/Opq?k="myserver"
                 (Content-Format :application/yang-data+cbor)
   {
     60002 : {
       +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) /
     }
   }

   RES:  2.05 Content (Content-Format :application/yang-data+cbor)
   {
     60002 : {
       +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/
     }
   }







Veillette, et al.         Expires May 16, 2019                 [Page 27]


Internet-Draft                    CoMI                     November 2018


5.  Access to MIB Data

   Appendix C.5 shows a YANG module mapped from the SMI specification
   "IP-MIB" [RFC4293].  The following example shows the
   "ipNetToPhysicalEntry" list with 2 instances.

   REQ: GET example.com/c/Oz1

   RES: 2.05 Content (Content-Format: application/yang-data+cbor)
   {
     60021 : [             / ipNetToPhysicalEntry /
       {
         +1 : 1,           / ipNetToPhysicalIfIndex (SID 60022) /
         +2 : 1,           / ipNetToPhysicalNetAddressType (SID 60023) /
         +3 : h'0A000033', / ipNetToPhysicalNetAddress (SID 60024) /
         +4 : h'00000A01172D',/ ipNetToPhysicalPhysAddress (SID 60025) /
         +5 : 2333943,     / ipNetToPhysicalLastUpdated (SID 60026) /
         +6 : 4,           / ipNetToPhysicalType (SID 60027) /
         +7 : 1,           / ipNetToPhysicalState (SID 60028) /
         +8 : 1            / ipNetToPhysicalRowStatus (SID 60029) /
       },
       {
         +1 : 1,           / ipNetToPhysicalIfIndex (SID 60022) /
         +2 : 1,           / ipNetToPhysicalNetAddressType (SID 60023) /
         +3 : h'09020304', / ipNetToPhysicalNetAddress  (SID 60024) /
         +4 : h'00000A36200A',/ ipNetToPhysicalPhysAddress (SID 60025) /
         +5 : 2329836,     / ipNetToPhysicalLastUpdated (SID 60026) /
         +6 : 3,           / ipNetToPhysicalType (SID 60027) /
         +7 : 6,           / ipNetToPhysicalState (SID 60028) /
         +8 : 1            / ipNetToPhysicalRowStatus (SID 60029) /
       }
     ]
   }

6.  Use of Block

   The CoAP protocol provides reliability by acknowledging the UDP
   datagrams.  However, when large pieces of data need to be
   transported, datagrams get fragmented, thus creating constraints on
   the resources in the client, server and intermediate routers.  The
   block option [RFC7959] allows the transport of the total payload in
   individual blocks of which the size can be adapted to the underlying
   transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280,
   IEEE 802.15.4 payload of 60-80 bytes).  Each block is individually
   acknowledged to guarantee reliability.

   Notice that the Block mechanism splits the data at fixed positions,
   such that individual data fields may become fragmented.  Therefore,



Veillette, et al.         Expires May 16, 2019                 [Page 28]


Internet-Draft                    CoMI                     November 2018


   assembly of multiple blocks may be required to process the complete
   data field.

   Beware of race conditions.  Blocks are filled one at a time and care
   should be taken that the whole data representation is sent in
   multiple blocks sequentially without interruption.  On the server,
   values are changed, lists are re-ordered, extended or reduced.  When
   these actions happen during the serialization of the contents of the
   resource, the transported results do not correspond with a state
   having occurred in the server; or worse the returned values are
   inconsistent.  For example: array length does not correspond with the
   actual number of items.  It may be advisable to use Indefinite-length
   CBOR arrays and maps, which are foreseen for data streaming purposes.

7.  Application Discovery

   Two application discovery mechanisms are supported by CoMI, the YANG
   library data model as defined by [I-D.veillette-core-yang-library]
   and the CORE resource discovery [RFC6690].  Implementers may choose
   to implement one or the other or both.

7.1.  YANG library

   The YANG library data model [I-D.veillette-core-yang-library]
   provides a high level description of the resources available.  The
   YANG library contains the list of modules, features and deviations
   supported by the CoMI server.  From this information, CoMI clients
   can infer the list of data nodes supported and the interaction model
   to be used to access them.  This module also contains the list of
   datastores implemented.

   The location of the YANG library can be found by sending a GET
   request to "/.well-known/core" including a resource type (RT)
   parameter with the value "core.c.yl".  Upon success, the return
   payload will contain the root resource of the YANG library module.

   REQ: GET /.well-known/core?rt=core.c.yl

   RES: 2.05 Content (Content-Format: application/link-format)
   </c/kv >;rt="core.c.yl"

7.2.  Resource Discovery

   Even if the YANG library provides all the information needed for
   application discovery, the implementation of Resource discovery as
   defined by [RFC6690] can be desirable for a seamless integration with
   other CoAP interfaces and services.




Veillette, et al.         Expires May 16, 2019                 [Page 29]


Internet-Draft                    CoMI                     November 2018


7.2.1.  Datastore Resource Discovery

   The presence and location of (path to) each datastore implemented by
   the CoMI server can be discovered by sending a GET request to
   "/.well-known/core" including a resource type (RT) parameter with the
   value "core.c.ds".

   Upon success, the return payload contains the list of datastore
   resources.

   Each datastore returned is further qualified using the "ds" Link-
   Format attribute.  This attribute is set to the SID assigned to the
   datastore identity.  When a unified datastore is implemented, the ds
   attribute is set to 1029.  For other examples of datastores, see the
   Network Management Datastore Architecture (NMDA) [RFC7950].

   link-extension    = ( "ds" "=" sid ) )
                       ; SID assigned to the datastore identity
   sid               = 1*DIGIT

   For example:

   REQ: GET /.well-known/core?rt=core.c.ds

   RES: 2.05 Content (Content-Format: application/link-format)
   </c>; rt="core.c.ds";ds= 1029

7.2.2.  Data node Resource Discovery

   The presence and location of (path to) each data node implemented by
   the CoMI server are discovered by sending a GET request to "/.well-
   known/core" including a resource type (RT) parameter with the value
   "core.c.dn".

   Upon success, the return payload contains the SID assigned to each
   data node and their location.

   The example below shows the discovery of the presence and location of
   data nodes.  Data nodes '/ietf-system:system-state/clock/boot-
   datetime' (SID 1722) and '/ietf-system:system-state/clock/current-
   datetime' (SID 1723) are returned.

   REQ: GET /.well-known/core?rt=core.c.dn

   RES: 2.05 Content (Content-Format: application/link-format)
   </c/a6>;rt="core.c.dn",
   </c/a7>;rt="core.c.dn"




Veillette, et al.         Expires May 16, 2019                 [Page 30]


Internet-Draft                    CoMI                     November 2018


   The list of data nodes may become prohibitively long.
   Implementations MAY return a subset of this list or can rely solely
   on the YANG library.

7.2.3.  Event stream Resource Discovery

   The presence and location of (path to) each event stream implemented
   by the CoMI server are discovered by sending a GET request to
   "/.well-known/core" including a resource type (RT) parameter with the
   value "core.c.es".

   Upon success, the return payload contains the list of event stream
   resources.

   For example:

   REQ: GET /.well-known/core?rt=core.c.es

   RES: 2.05 Content (Content-Format: application/link-format)
   </s>;rt="core.c.es"

8.  Error Handling

   In case a request is received which cannot be processed properly, the
   CoMI server MUST return an error message.  This error message MUST
   contain a CoAP 4.xx or 5.xx response code.

   Errors returned by a CoMI server can be broken into two categories,
   those associated to the CoAP protocol itself and those generated
   during the validation of the YANG data model constrains as described
   in [RFC7950] section 8.

   The following list of common CoAP errors should be implemented by
   CoMI servers.  This list is not exhaustive, other errors defined by
   CoAP and associated RFCs may be applicable.

   o  Error 4.01 (Unauthorized) is returned by the CoMI server when the
      CoMI client is not authorized to perform the requested action on
      the targeted resource (i.e. data node, datastore, rpc, action or
      event stream).

   o  Error 4.02 (Bad Option) is returned by the CoMI server when one or
      more CoAP options are unknown or malformed.

   o  Error 4.04 (Not Found) is returned by the CoMI server when the
      CoMI client is requesting a non-instantiated resource (i.e. data
      node, datastore, rpc, action or event stream).




Veillette, et al.         Expires May 16, 2019                 [Page 31]


Internet-Draft                    CoMI                     November 2018


   o  Error 4.05 (Method Not Allowed) is returned by the CoMI server
      when the CoMI client is requesting a method not supported on the
      targeted resource. (e.g.  GET on an rpc, PUT or POST on a data
      node with "config" set to false).

   o  Error 4.08 (Request Entity Incomplete) is returned by the CoMI
      server if one or multiple blocks of a block transfer request is
      missing, see [RFC7959] for more details.

   o  Error 4.13 (Request Entity Too Large) may be returned by the CoMI
      server during a block transfer request, see [RFC7959] for more
      details.

   o  Error 4.15 (Unsupported Content-Format) is returned by the CoMI
      server when the Content-Format used in the request don't match
      those specified in section Section 2.4.

   CoMI server MUST also enforce the different constraints associated to
   the YANG data models implemented.  These constraints are described in
   [RFC7950] section 8.  These errors are reported using the CoAP error
   code 4.00 (Bad Request) and may have the following error container as
   payload.  The YANG definition and associated .sid file are available
   in Appendix A and Appendix B.  The error container is encoded using
   the encoding rules of a YANG data template as defined in
   [I-D.ietf-core-yang-cbor] section 5.

   +--rw error!
      +--rw error-tag             identityref
      +--rw error-app-tag?        identityref
      +--rw error-data-node?      instance-identifier
      +--rw error-message?        string

   The following 'error-tag' and 'error-app-tag' are defined by the
   ietf-comi YANG module, these tags are implemented as YANG identity
   and can be extended as needed.

   o  error-tag 'operation-failed' is returned by the CoMI server when
      the operation request cannot be processed successfully.

      *  error-app-tag 'malformed-message' is returned by the CoMI
         server when the payload received from the CoMI client don't
         contain a well-formed CBOR content as defined in [RFC7049]
         section 3.3 or don't comply with the CBOR structure defined
         within this document.

      *  error-app-tag 'data-not-unique' is returned by the CoMI server
         when the validation of the 'unique' constraint of a list or
         leaf-list fails.



Veillette, et al.         Expires May 16, 2019                 [Page 32]


Internet-Draft                    CoMI                     November 2018


      *  error-app-tag 'too-many-elements' is returned by the CoMI
         server when the validation of the 'max-elements' constraint of
         a list or leaf-list fails.

      *  error-app-tag 'too-few-elements' is returned by the CoMI server
         when the validation of the 'min-elements' constraint of a list
         or leaf-list fails.

      *  error-app-tag 'must-violation' is returned by the CoMI server
         when the restrictions imposed by a 'must' statement are
         violated.

      *  error-app-tag 'duplicate' is returned by the CoMI server when a
         client tries to create a duplicate list or leaf-list entry.

   o  error-tag 'invalid-value' is returned by the CoMI server when the
      CoMI client tries to update or create a leaf with a value encoded
      using an invalid CBOR datatype or if the 'range', 'length',
      'pattern' or 'require-instance' constrain is not fulfilled.

      *  error-app-tag 'invalid-datatype' is returned by the CoMI server
         when CBOR encoding don't follow the rules set by or when the
         value is incompatible with the YANG Built-In type. (e.g. a
         value greater than 127 for an int8, undefined enumeration)

      *  error-app-tag 'not-in-range' is returned by the CoMI server
         when the validation of the 'range' property fails.

      *  error-app-tag 'invalid-length' is returned by the CoMI server
         when the validation of the 'length' property fails.

      *  error-app-tag 'pattern-test-failed' is returned by the CoMI
         server when the validation of the 'pattern' property fails.

   o  error-tag 'missing-element' is returned by the CoMI server when
      the operation requested by a CoMI client fail to comply with the
      'mandatory' constraint defined.  The 'mandatory' constraint is
      enforced for leafs and choices, unless the node or any of its
      ancestors have a 'when' condition or 'if-feature' expression that
      evaluates to 'false'.

      *  error-app-tag 'missing-key' is returned by the CoMI server to
         further qualify an missing-element error.  This error is
         returned when the CoMI client tries to create or list instance,
         without all the 'key' specified or when the CoMI client tries
         to delete a leaf listed as a 'key'.





Veillette, et al.         Expires May 16, 2019                 [Page 33]


Internet-Draft                    CoMI                     November 2018


      *  error-app-tag 'missing-input-parameter' is returned by the CoMI
         server when the input parameters of an RPC or action are
         incomplete.

   o  error-tag 'unknown-element' is returned by the CoMI server when
      the CoMI client tries to access a data node of a YANG module not
      supported, of a data node associated to an 'if-feature' expression
      evaluated to 'false' or to a 'when' condition evaluated to
      'false'.

   o  error-tag 'bad-element' is returned by the CoMI server when the
      CoMI client tries to create data nodes for more than one case in a
      choice.

   o  error-tag 'data-missing' is returned by the CoMI server when a
      data node required to accept the request is not present.

      *  error-app-tag 'instance-required' is returned by the CoMI
         server when a leaf of type 'instance-identifier' or 'leafref'
         marked with require-instance set to 'true' refers to an
         instance that does not exist.

      *  error-app-tag 'missing-choice' is returned by the CoMI server
         when no nodes exist in a mandatory choice.

   o  error-tag 'error' is returned by the CoMI server when an
      unspecified error has occurred.

   For example, the CoMI server might return the following error.

   RES:  4.00 Bad Request (Content-Format :application/yang-data+cbor)
   {
     1024 : {
       +4 : 1011,       / error-tag (SID 1028) /
                        /   = invalid-value (SID 1011) /
       +1 : 1018,       / error-app-tag (SID 1025) /
                        /   = not-in-range (SID 1018) /
       +2 : 1740,       / error-data-node (SID 1026) /
                        /   = timezone-utc-offset (SID 1740) /
       +3 : "maximum value exceeded" / error-message (SID 1027) /
     }
   }

9.  Security Considerations

   For secure network management, it is important to restrict access to
   configuration variables only to authorized parties.  CoMI re-uses the
   security mechanisms already available to CoAP, this includes DTLS



Veillette, et al.         Expires May 16, 2019                 [Page 34]


Internet-Draft                    CoMI                     November 2018


   [RFC6347] for protected access to resources, as well suitable
   authentication and authorization mechanisms.

   Among the security decisions that need to be made are selecting
   security modes and encryption mechanisms (see [RFC7252]).  This
   requires a trade-off, as the NoKey mode gives no protection at all,
   but is easy to implement, whereas the X.509 mode is quite secure, but
   may be too complex for constrained devices.

   In addition, mechanisms for authentication and authorization may need
   to be selected.

   CoMI avoids defining new security mechanisms as much as possible.
   However, some adaptations may still be required, to cater for CoMI's
   specific requirements.

10.  IANA Considerations

10.1.  Resource Type (rt=) Link Target Attribute Values Registry

   This document adds the following resource type to the "Resource Type
   (rt=) Link Target Attribute Values", within the "Constrained RESTful
   Environments (CoRE) Parameters" registry.

   +-----------+---------------------+-----------+
   | Value     | Description         | Reference |
   +-----------+---------------------+-----------+
   | core.c.ds | YANG datastore      | RFC XXXX  |
   |           |                     |           |
   | core.c.dn | YANG data node      | RFC XXXX  |
   |           |                     |           |
   | core.c.yl | YANG module library | RFC XXXX  |
   |           |                     |           |
   | core.c.es | YANG event stream   | RFC XXXX  |
   +-----------+---------------------+-----------+

   // RFC Ed.: replace RFC XXXX with this RFC number and remove this
   note.

10.2.  CoAP Content-Formats Registry

   This document adds the following Content-Format to the "CoAP Content-
   Formats", within the "Constrained RESTful Environments (CoRE)
   Parameters" registry.







Veillette, et al.         Expires May 16, 2019                 [Page 35]


Internet-Draft                    CoMI                     November 2018


   +-----------------------------------+-------------+-----------+
   | Media Type                        | Encoding ID | Reference |
   +-----------------------------------+-------------+-----------+
   | application/yang-data+cbor        | XXX         | RFC XXXX  |
   |                                   |             |           |
   | application/yang-identifiers+cbor | XXX         | RFC XXXX  |
   |                                   |             |           |
   | application/yang-instances+cbor   | XXX         | RFC XXXX  |
   +-----------------------------------+-------------+-----------+

   // RFC Ed.: replace XXX with assigned IDs and remove this note.  //
   RFC Ed.: replace RFC XXXX with this RFC number and remove this note.

10.3.  Media Types Registry

   This document adds the following media types to the "Media Types"
   registry.

   +-----------------------+----------------------------+-----------+
   | Name                  | Template                   | Reference |
   +-----------------------+----------------------------+-----------+
   | yang-data+cbor        | application/yang-data+cbor | RFC XXXX  |
   |                       |                            |           |
   | yang-identifiers+cbor | application/               | RFC XXXX  |
   |                       |                            |           |
   |                       | yang-identifiers+cbor      |           |
   |                       |                            |           |
   | yang-instances+cbor   | application/               | RFC XXXX  |
   |                       |                            |           |
   |                       | yang-instances+cbor        |           |
   +-----------------------+----------------------------+-----------+

   Each of these media types share the following information:

   o  Subtype name: <as listed in table>

   o  Required parameters: N/A

   o  Optional parameters: N/A

   o  Encoding considerations: binary

   o  Security considerations: See the Security Considerations section
      of RFC XXXX

   o  Interoperability considerations: N/A

   o  Published specification: RFC XXXX



Veillette, et al.         Expires May 16, 2019                 [Page 36]


Internet-Draft                    CoMI                     November 2018


   o  Applications that use this media type: CoMI

   o  Fragment identifier considerations: N/A

   o  Additional information:

   *  Deprecated alias names for this type: N/A

   *  Magic number(s): N/A

   *  File extension(s): N/A

   *  Macintosh file type code(s): N/A

   o  Person & email address to contact for further information:
      iesg&ietf.org

   o  Intended usage: COMMON

   o  Restrictions on usage: N/A

   o  Author: Michel Veillette, ietf&augustcellars.com

   o  Change Controller: IESG

   o  Provisional registration?  No

   // RFC Ed.: replace RFC XXXX with this RFC number and remove this
   note.

11.  Acknowledgements

   We are very grateful to Bert Greevenbosch who was one of the original
   authors of the CoMI specification and specified CBOR encoding and use
   of hashes.

   Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs
   transported under SNMP.  Carsten Bormann has given feedback on the
   use of CBOR.

   The draft has benefited from comments (alphabetical order) by Rodney
   Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy
   Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes
   Tschofenig, Michael Verschoor, and Thomas Watteyne.







Veillette, et al.         Expires May 16, 2019                 [Page 37]


Internet-Draft                    CoMI                     November 2018


12.  References

12.1.  Normative References

   [I-D.ietf-core-sid]
              Veillette, M. and A. Pelov, "YANG Schema Item iDentifier
              (SID)", draft-ietf-core-sid-04 (work in progress), June
              2018.

   [I-D.ietf-core-yang-cbor]
              Veillette, M., Pelov, A., Turner, R., and A. Minaburo,
              "CBOR Encoding of Data Modeled with YANG", draft-ietf-
              core-yang-cbor-07 (work in progress), September 2018.

   [I-D.veillette-core-yang-library]
              Veillette, M., "Constrained YANG Module Library", draft-
              veillette-core-yang-library-03 (work in progress),
              September 2018.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
              Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
              <https://www.rfc-editor.org/info/rfc5277>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC6243]  Bierman, A. and B. Lengyel, "With-defaults Capability for
              NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
              <https://www.rfc-editor.org/info/rfc6243>.

   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
              October 2013, <https://www.rfc-editor.org/info/rfc7049>.







Veillette, et al.         Expires May 16, 2019                 [Page 38]


Internet-Draft                    CoMI                     November 2018


   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <https://www.rfc-editor.org/info/rfc7252>.

   [RFC7641]  Hartke, K., "Observing Resources in the Constrained
              Application Protocol (CoAP)", RFC 7641,
              DOI 10.17487/RFC7641, September 2015,
              <https://www.rfc-editor.org/info/rfc7641>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC7959]  Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
              the Constrained Application Protocol (CoAP)", RFC 7959,
              DOI 10.17487/RFC7959, August 2016,
              <https://www.rfc-editor.org/info/rfc7959>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8132]  van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
              FETCH Methods for the Constrained Application Protocol
              (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
              <https://www.rfc-editor.org/info/rfc8132>.

12.2.  Informative References

   [RFC4293]  Routhier, S., Ed., "Management Information Base for the
              Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293,
              April 2006, <https://www.rfc-editor.org/info/rfc4293>.

   [RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
              Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
              January 2012, <https://www.rfc-editor.org/info/rfc6347>.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
              <https://www.rfc-editor.org/info/rfc6690>.

   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
              <https://www.rfc-editor.org/info/rfc7223>.






Veillette, et al.         Expires May 16, 2019                 [Page 39]


Internet-Draft                    CoMI                     November 2018


   [RFC7317]  Bierman, A. and M. Bjorklund, "A YANG Data Model for
              System Management", RFC 7317, DOI 10.17487/RFC7317, August
              2014, <https://www.rfc-editor.org/info/rfc7317>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

Appendix A.  ietf-comi YANG module

   <CODE BEGINS> file "ietf-comi@2018-09-26.yang"
   module ietf-comi {
     yang-version 1.1;

     namespace "urn:ietf:params:xml:ns:yang:ietf-comi";
     prefix comi;

     import ietf-datastores {
       prefix ds;
     }

     import ietf-restconf {
       prefix rc;
       description
         "This import statement is only present to access
          the yang-data extension defined in RFC 8040.";
       reference "RFC 8040: RESTCONF Protocol";
     }

     organization
       "IETF Core Working Group";

     contact
       "Michel Veillette
        <mailto:michel.veillette@trilliantinc.com>

        Alexander Pelov
        <mailto:alexander@ackl.io>

        Peter van der Stok
        <mailto:consultancy@vanderstok.org>

        Andy Bierman
        <mailto:andy@yumaworks.com>";

     description
       "This module contains the different definitions required



Veillette, et al.         Expires May 16, 2019                 [Page 40]


Internet-Draft                    CoMI                     November 2018


        by the CoMI protocol.";

     revision 2018-09-26 {
       description
         "Use of YANG data template for the error payload.
          Definition of the unified datastore.";
       reference
         "[I-D.ietf-core-comi] CoAP Management Interface";
     }
     revision 2017-07-01 {
        description
         "Initial revision.";
       reference
         "[I-D.ietf-core-comi] CoAP Management Interface";
     }

     typedef sid {
       type uint64;
       description
         "YANG Schema Item iDentifier";
       reference
         "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)";
     }

     identity unified {
       base ds:datastore;
       description
         "The unified configuration and operational state datastore.";
     }

     identity error-tag {
       description
         "Base identity for error-tag.";
     }

     identity operation-failed {
       base error-tag;
       description
         "Returned by the CoMI server when the operation request
          can't be processed successfully.";
     }

     identity invalid-value {
       base error-tag;
       description
         "Returned by the CoMI server when the CoMI client tries to
          update or create a leaf with a value encoded using an
          invalid CBOR datatype or if the 'range', 'length',



Veillette, et al.         Expires May 16, 2019                 [Page 41]


Internet-Draft                    CoMI                     November 2018


          'pattern' or 'require-instance' constrain is not
          fulfilled.";
     }

     identity missing-element {
       base error-tag;
       description
         "Returned by the CoMI server when the operation requested
          by a CoMI client fails to comply with the 'mandatory'
          constraint defined. The 'mandatory' constraint is
          enforced for leafs and choices, unless the node or any of
          its ancestors have a 'when' condition or 'if-feature'
          expression that evaluates to 'false'.";
     }

     identity unknown-element {
       base error-tag;
       description
         "Returned by the CoMI server when the CoMI client tries to
          access a data node of a YANG module not supported, of a
          data node associated with an 'if-feature' expression
          evaluated to 'false' or to a 'when' condition evaluated
          to 'false'.";
     }

     identity bad-element {
       base error-tag;
       description
         "Returned by the CoMI server when the CoMI client tries to
          create data nodes for more than one case in a choice.";
     }

     identity data-missing {
       base error-tag;
       description
         "Returned by the CoMI server when a data node required to
          accept the request is not present.";
     }

     identity error {
       base error-tag;
       description
         "Returned by the CoMI server when an unspecified error has
         occurred.";
     }

     identity error-app-tag {
       description



Veillette, et al.         Expires May 16, 2019                 [Page 42]


Internet-Draft                    CoMI                     November 2018


         "Base identity for error-app-tag.";
     }

     identity malformed-message {
       base error-app-tag;
       description
         "Returned by the CoMI server when the payload received
          from the CoMI client don't contain a well-formed CBOR
          content as defined in [RFC7049] section 3.3 or don't
          comply with the CBOR structure defined within this
          document.";
     }

     identity data-not-unique {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'unique' constraint of a list or leaf-list fails.";
     }

     identity too-many-elements {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'max-elements' constraint of a list or leaf-list fails.";
     }

     identity too-few-elements {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'min-elements' constraint of a list or leaf-list fails.";
     }

     identity must-violation {
       base error-app-tag;
       description
         "Returned by the CoMI server when the restrictions
          imposed by a 'must' statement are violated.";
     }

     identity duplicate {
       base error-app-tag;
       description
         "Returned by the CoMI server when a client tries to create
          a duplicate list or leaf-list entry.";
     }




Veillette, et al.         Expires May 16, 2019                 [Page 43]


Internet-Draft                    CoMI                     November 2018


     identity invalid-datatype {
       base error-app-tag;
       description
         "Returned by the CoMI server when CBOR encoding is
          incorect or when the value encoded is incompatible with
          the YANG Built-In type. (e.g. value greater than 127
          for an int8, undefined enumeration).";
     }

     identity not-in-range {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'range' property fails.";
     }

     identity invalid-length {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'length' property fails.";
     }

     identity pattern-test-failed {
       base error-app-tag;
       description
         "Returned by the CoMI server when the validation of the
          'pattern' property fails.";
     }

     identity missing-key {
       base error-app-tag;
       description
         "Returned by the CoMI server to further qualify a
          missing-element error. This error is returned when the
          CoMI client tries to create or list instance, without all
          the 'key' specified or when the CoMI client tries to
          delete a leaf listed as a 'key'.";
     }

     identity missing-input-parameter {
       base error-app-tag;
       description
         "Returned by the CoMI server when the input parameters
          of a RPC or action are incomplete.";
     }

     identity instance-required {



Veillette, et al.         Expires May 16, 2019                 [Page 44]


Internet-Draft                    CoMI                     November 2018


       base error-app-tag;
       description
         "Returned by the CoMI server when a leaf of type
          'instance-identifier' or 'leafref' marked with
          require-instance set to 'true' refers to an instance
          that does not exist.";
     }

     identity missing-choice {
       base error-app-tag;
       description
         "Returned by the CoMI server when no nodes exist in a
          mandatory choice.";
     }

     rc:yang-data comi-error {
       container error {
         description
           "Optional payload of a 4.00 Bad Request CoAP error.";

         leaf error-tag {
           type identityref {
             base error-tag;
           }
           mandatory true;
           description
             "The enumerated error-tag.";
         }

         leaf error-app-tag {
           type identityref {
             base error-app-tag;
           }
           description
             "The application-specific error-tag.";
         }

         leaf error-data-node {
           type instance-identifier;
           description
             "When the error reported is caused by a specific data node,
              this leaf identifies the data node in error.";
         }

         leaf error-message {
           type string;
           description
             "A message describing the error.";



Veillette, et al.         Expires May 16, 2019                 [Page 45]


Internet-Draft                    CoMI                     November 2018


         }
       }
     }
   }
   <CODE ENDS>

Appendix B.  ietf-comi .sid file

   {
     "assignment-ranges": [
       {
         "entry-point": 1000,
         "size": 100
       }
     ],
     "module-name": "ietf-comi",
     "module-revision": "2018-09-26",
     "items": [
       {
         "namespace": "module",
         "identifier": "ietf-comi",
         "sid": 1000
       },
       {
         "namespace": "identity",
         "identifier": "bad-element",
         "sid": 1001
       },
       {
         "namespace": "identity",
         "identifier": "data-missing",
         "sid": 1002
       },
       {
         "namespace": "identity",
         "identifier": "data-not-unique",
         "sid": 1003
       },
       {
         "namespace": "identity",
         "identifier": "duplicate",
         "sid": 1004
       },
       {
         "namespace": "identity",
         "identifier": "error",
         "sid": 1005
       },



Veillette, et al.         Expires May 16, 2019                 [Page 46]


Internet-Draft                    CoMI                     November 2018


       {
         "namespace": "identity",
         "identifier": "error-app-tag",
         "sid": 1006
       },
       {
         "namespace": "identity",
         "identifier": "error-tag",
         "sid": 1007
       },
       {
         "namespace": "identity",
         "identifier": "instance-required",
         "sid": 1008
       },
       {
         "namespace": "identity",
         "identifier": "invalid-datatype",
         "sid": 1009
       },
       {
         "namespace": "identity",
         "identifier": "invalid-length",
         "sid": 1010
       },
       {
         "namespace": "identity",
         "identifier": "invalid-value",
         "sid": 1011
       },
       {
         "namespace": "identity",
         "identifier": "malformed-message",
         "sid": 1012
       },
       {
         "namespace": "identity",
         "identifier": "missing-choice",
         "sid": 1013
       },
       {
         "namespace": "identity",
         "identifier": "missing-element",
         "sid": 1014
       },
       {
         "namespace": "identity",
         "identifier": "missing-input-parameter",



Veillette, et al.         Expires May 16, 2019                 [Page 47]


Internet-Draft                    CoMI                     November 2018


         "sid": 1015
       },
       {
         "namespace": "identity",
         "identifier": "missing-key",
         "sid": 1016
       },
       {
         "namespace": "identity",
         "identifier": "must-violation",
         "sid": 1017
       },
       {
         "namespace": "identity",
         "identifier": "not-in-range",
         "sid": 1018
       },
       {
         "namespace": "identity",
         "identifier": "operation-failed",
         "sid": 1019
       },
       {
         "namespace": "identity",
         "identifier": "pattern-test-failed",
         "sid": 1020
       },
       {
         "namespace": "identity",
         "identifier": "too-few-elements",
         "sid": 1021
       },
       {
         "namespace": "identity",
         "identifier": "too-many-elements",
         "sid": 1022
       },
       {
         "namespace": "identity",
         "identifier": "unified",
         "sid": 1029
       },
       {
         "namespace": "identity",
         "identifier": "unknown-element",
         "sid": 1023
       },
       {



Veillette, et al.         Expires May 16, 2019                 [Page 48]


Internet-Draft                    CoMI                     November 2018


         "namespace": "data",
         "identifier": "/ietf-comi:error",
         "sid": 1024
       },
       {
         "namespace": "data",
         "identifier": "/ietf-comi:error/error-app-tag",
         "sid": 1025
       },
       {
         "namespace": "data",
         "identifier": "/ietf-comi:error/error-data-node",
         "sid": 1026
       },
       {
         "namespace": "data",
         "identifier": "/ietf-comi:error/error-message",
         "sid": 1027
       },
       {
         "namespace": "data",
         "identifier": "/ietf-comi:error/error-tag",
         "sid": 1028
       }
     ]
   }

Appendix C.  YANG example specifications

   This appendix shows five YANG example specifications taken over from
   as many existing YANG modules.  Each YANG item identifier is
   accompanied by its SID shown after the "//" comment sign.

C.1.  ietf-system

   Excerpt of the YANG module ietf-system [RFC7317].

   module ietf-system {                   // SID 1700
     container system {                   // SID 1717
       container clock {                  // SID 1738
         choice timezone {
           case timezone-name {
             leaf timezone-name {         // SID 1739
               type timezone-name;
             }
           }
           case timezone-utc-offset {
             leaf timezone-utc-offset {   // SID 1740



Veillette, et al.         Expires May 16, 2019                 [Page 49]


Internet-Draft                    CoMI                     November 2018


               type int16 {
               }
             }
           }
         }
       }
       container ntp {                    // SID 1754
         leaf enabled {                   // SID 1755
           type boolean;
           default true;
         }
         list server {                    // SID 1756
           key name;
           leaf name {                    // SID 1759
             type string;
           }
           choice transport {
             case udp {
               container udp {            // SID 1761
                 leaf address {           // SID 1762
                   type inet:host;
                 }
                 leaf port {              // SID 1763
                   type inet:port-number;
                 }
               }
             }
           }
           leaf association-type {        // SID 1757
             type enumeration {
               enum server {
               }
               enum peer {
               }
               enum pool {
               }
             }
           }
           leaf iburst {                  // SID 1758
             type boolean;
           }
           leaf prefer {                  // SID 1760
             type boolean;
             default false;
           }
         }
       }
     container system-state {             // SID 1720



Veillette, et al.         Expires May 16, 2019                 [Page 50]


Internet-Draft                    CoMI                     November 2018


       container clock {                  // SID 1721
         leaf current-datetime {          // SID 1723
           type yang:date-and-time;
         }
         leaf boot-datetime {             // SID 1722
           type yang:date-and-time;
         }
       }
     }
   }

C.2.  server list

   Taken over from [RFC7950] section 7.15.3.

   module example-server-farm {
     yang-version 1.1;
     namespace "urn:example:server-farm";
     prefix "sfarm";

     import ietf-yang-types {
       prefix "yang";
     }

     list server {                        // SID 60000
       key name;
       leaf name {                        // SID 60001
         type string;
       }
       action reset {                     // SID 60002
         input {
           leaf reset-at {                // SID 60003
             type yang:date-and-time;
             mandatory true;
            }
          }
          output {
            leaf reset-finished-at {      // SID 60004
              type yang:date-and-time;
              mandatory true;
            }
          }
        }
      }
   }






Veillette, et al.         Expires May 16, 2019                 [Page 51]


Internet-Draft                    CoMI                     November 2018


C.3.  interfaces

   Excerpt of the YANG module ietf-interfaces [RFC7223].

   module ietf-interfaces {               // SID 1500
     container interfaces {               // SID 1505
       list interface {                   // SID 1533
         key "name";
         leaf name {                      // SID 1537
           type string;
         }
         leaf description {               // SID 1534
           type string;
         }
         leaf type {                      // SID 1538
           type identityref {
             base interface-type;
           }
           mandatory true;
         }

         leaf enabled {                   // SID 1535
           type boolean;
           default "true";
         }

         leaf link-up-down-trap-enable {  // SID 1536
           if-feature if-mib;
           type enumeration {
             enum enabled {
               value 1;
             }
             enum disabled {
               value 2;
             }
           }
         }
       }
     }
   }

C.4.  Example-port

   Notification example defined within this document.







Veillette, et al.         Expires May 16, 2019                 [Page 52]


Internet-Draft                    CoMI                     November 2018


   module example-port {
           ...
           notification example-port-fault {   // SID 60010
             description
               "Event generated if a hardware fault on a
                line card port is detected";
             leaf port-name {                  // SID 60011
               type string;
               description "Port name";
             }
             leaf port-fault {                 // SID 60012
               type string;
               description "Error condition detected";
             }
           }
         }

C.5.  IP-MIB

   The YANG translation of the SMI specifying the IP-MIB [RFC4293],
   extended with example SID numbers, yields:

   module IP-MIB {
     import IF-MIB {
       prefix if-mib;
     }
     import INET-ADDRESS-MIB {
       prefix inet-address;
     }
     import SNMPv2-TC {
       prefix smiv2;
     }
     import ietf-inet-types {
       prefix inet;
     }
     import yang-smi {
       prefix smi;
     }
     import ietf-yang-types {
       prefix yang;
     }

     container ip {                            // SID 60020
       list ipNetToPhysicalEntry {             // SID 60021
         key "ipNetToPhysicalIfIndex
              ipNetToPhysicalNetAddressType
              ipNetToPhysicalNetAddress";
         leaf ipNetToPhysicalIfIndex {         // SID 60022



Veillette, et al.         Expires May 16, 2019                 [Page 53]


Internet-Draft                    CoMI                     November 2018


           type if-mib:InterfaceIndex;
         }
         leaf ipNetToPhysicalNetAddressType {  // SID 60023
           type inet-address:InetAddressType;
         }
         leaf ipNetToPhysicalNetAddress {      // SID 60024
           type inet-address:InetAddress;
         }
         leaf ipNetToPhysicalPhysAddress {     // SID 60025
           type yang:phys-address {
             length "0..65535";
           }
         }
         leaf ipNetToPhysicalLastUpdated {     // SID 60026
           type yang:timestamp;
         }
         leaf ipNetToPhysicalType {            // SID 60027
           type enumeration {
             enum "other" {
               value 1;
             }
             enum "invalid" {
               value 2;
             }
             enum "dynamic" {
               value 3;
             }
             enum "static" {
               value 4;
             }
             enum "local" {
               value 5;
             }
           }
         }
         leaf ipNetToPhysicalState {           // SID 60028
           type enumeration {
             enum "reachable" {
               value 1;
             }
             enum "stale" {
               value 2;
             }
             enum "delay" {
               value 3;
             }
             enum "probe" {
               value 4;



Veillette, et al.         Expires May 16, 2019                 [Page 54]


Internet-Draft                    CoMI                     November 2018


             }
             enum "invalid" {
               value 5;
             }
             enum "unknown" {
               value 6;
             }
             enum "incomplete" {
               value 7;
             }
           }
         }
         leaf ipNetToPhysicalRowStatus {       // SID 60029
           type smiv2:RowStatus;
       }  // list ipNetToPhysicalEntry
     }  // container ip
   }  // module IP-MIB

Authors' Addresses

   Michel Veillette (editor)
   Trilliant Networks Inc.
   610 Rue du Luxembourg
   Granby, Quebec  J2J 2V2
   Canada

   Email: michel.veillette@trilliant.com


   Peter van der Stok (editor)
   consultant

   Phone: +31-492474673 (Netherlands), +33-966015248 (France)
   Email: consultancy@vanderstok.org
   URI:   www.vanderstok.org


   Alexander Pelov
   Acklio
   2bis rue de la Chataigneraie
   Cesson-Sevigne, Bretagne  35510
   France

   Email: a@ackl.io







Veillette, et al.         Expires May 16, 2019                 [Page 55]


Internet-Draft                    CoMI                     November 2018


   Andy Bierman
   YumaWorks
   685 Cochran St.
   Suite #160
   Simi Valley, CA  93065
   USA

   Email: andy@yumaworks.com











































Veillette, et al.         Expires May 16, 2019                 [Page 56]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/