]> Trilliant Networks Inc.

610 Rue du Luxembourg Granby Quebec J2J 2V2 Canada michel.veillette@trilliant.com

consultant

+31625097806 stokcons@kpnmail.nl https://vanderstok.tech

IMT Atlantique

2 rue de la Châtaigneraie Cesson-Sevigne 35510 France alexander.pelov@imt-atlantique.fr

YumaWorks

685 Cochran St. Suite #160 Simi Valley CA 93065 USA andy@yumaworks.com

Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

Web and Internet Transport CoRE This document describes a network management interface for constrained devices and networks, called CoAP Management Interface (CORECONF). The Constrained Application Protocol (CoAP) is used to access datastore and data node resources specified in YANG, or SMIv2 converted to YANG. CORECONF uses the YANG to CBOR mapping and converts YANG identifier strings to numeric identifiers for payload size reduction. CORECONF extends the set of YANG based protocols, NETCONF and RESTCONF, with the capability to manage constrained devices and networks. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the core Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Constrained Application Protocol (CoAP) 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 specification describes the CoAP Management Interface (CORECONF) which uses CoAP methods to access structured data defined in YANG . This specification is complementary to 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. CORECONF 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 messages, CORECONF uses a YANG to CBOR mapping and numeric identifiers to minimize CBOR payloads and URI length.

Terminology The following terms are defined in the YANG data modeling language : 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 : configuration data, datastore, state data. The following term is defined in : YANG schema item identifier (YANG SID, often shortened to simply SID). The following terms are defined in the CoAP protocol : 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 resource.

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 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 data node instance. Instance-values are serialized into the payload according to the rules defined in . In a yang-instances data item, the reference SID applying to the instance-value is provided by the SID in the corresponding instance-identifier.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Example syntax CBOR is used to encode CORECONF request and response payloads. The CBOR syntax of the YANG payloads is specified in , based on and . The payload examples are notated in Diagnostic notation (defined in and ), which can be automatically converted to CBOR. The examples in this document use the YANG modules defined in and where these contain the necessary nodes, and purpose-written modules where they do not. The SIDs appearing in the examples are illustrative; the SIDs actually assigned to the module defined by this document are given in .

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

CoAP request(3) -->| Indication | | Confirm |<-- CoAP response(3)<--+ Response (4) | | | | | | |<==== Security (7) ===>| +---------------------+ | +--------------+ | | Datastore(s) (5) | | | +---------------------+ | | | | +---------------------+ | | | Event stream(s) (6) | | | +---------------------+ | +-------------------------+ ]]>

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

(1) YANG specification:

contains a set of named and versioned modules.

(2) SMIv2 specification:

Optional part that consists of a named module which, 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 CORECONF client sends request messages to and receives response messages from the CORECONF server.

(4) Request, Indication, Response, Confirm:

Processes performed by the CORECONF clients and servers.

(5) Datastore:

A resource used to access configuration data, state data, RPCs, and actions. A CORECONF server supports a single unified datastore. Multiple datastores, for instance as those defined by Network Management Datastore Architecture (NMDA) , are out of scope of this specification.

(6) Event stream:

A resource used to get real-time notifications. A CORECONF 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 CORECONF resources. CORECONF relies on security protocols such as DTLS or OSCORE to secure CoAP communications.

Major differences between RESTCONF and CORECONF CORECONF is a RESTful protocol for small devices where saving bytes to transport a message is very important. Contrary to RESTCONF, many design decisions are motivated by the saving of bytes. Consequently, CORECONF is not a RESTCONF over CoAP protocol, but differs more significantly from RESTCONF.

Differences due to CoAP and its efficient usage CORECONF uses CoAP/UDP as transport protocol and CBOR as payload format . RESTCONF uses HTTP/TCP as transport protocol and JSON or XML as payload formats. CORECONF uses the methods FETCH and iPATCH to access data nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP method GET with the "fields" Query parameter. RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not supported by CoAP. CORECONF does not support "insert" query parameter (first, last, before, after) and the "point" query parameter which are supported by RESTCONF. CORECONF does not support the "start-time" and "stop-time" query parameters to retrieve past notifications. Other CoAP transports (such as CoAP over TCP or WebSockets ) are out of scope for this document.

Differences due to the use of CBOR CORECONF encodes YANG identifier strings as numbers, where RESTCONF does not. CORECONF also differs in the handling of default values, only 'report-all' and 'trim' options are supported.

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 CORECONF, numeric identifiers called YANG Schema Item iDentifier (YANG SID or simply SID) are used instead.

Instance-identifiers Instance-identifiers are used to uniquely identify data node instances within a datastore. This YANG built-in type is defined in . 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). In CORECONF, instance-identifiers are carried in the payload of FETCH and PATCH requests. They are encoded in CBOR based on the rules defined in .

Media-Types CORECONF uses Media-Types based on the YANG to CBOR mapping specified in . The following new Media-Types based on CBOR sequences are defined in this document:

application/yang-identifiers+cbor-seq:

This Media-Type represents a CBOR YANG document containing a list of instance-identifiers used to target specific data node instances within a datastore.

FORMAT: CBOR sequence of instance-identifiers

The message payload of Media-Type 'application/yang-identifiers+cbor-seq' is encoded using a CBOR sequence. Each item of this CBOR sequence contains an instance-identifier encoded as defined in .

application/yang-instances+cbor-seq:

This Media-Type 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 sequence of CBOR maps of instance-identifier, instance-value

The message payload of Media-Type 'application/yang-instances+cbor-seq' is encoded using a CBOR sequence. Each item within this CBOR sequence contains a CBOR map carrying an instance-identifier and associated instance-value. Instance-identifiers are encoded using the rules defined in , instance-values are encoded using the rules defined in . The reference SID applying to the instance-value is provided by the SID in the instance-identifier.

In the position of an instance-value, the CBOR undefined value (0xf7) indicates the absence of a value. Its precise meaning depends on the method, as specified in and . The CBOR null value (0xf6) is a valid instance-value for a leaf of type 'empty' (see ).

When present in an iPATCH request payload, this Media-Type 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 undefined, 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 (unless the value of D is undefined).

The following examples show the payload of each of the three Media-Types in diagnostic notation, using data from the examples in . A part of a datastore, in application/yang-data+cbor; id=sid, which is defined in and is used for the datastore as a whole ():

A leaf and a list entry identified in application/yang-identifiers+cbor-seq. The two items of the CBOR sequence are separated by a comma:

Two data node instances in application/yang-instances+cbor-seq. Each item of the CBOR sequence is a map of one instance-identifier and its instance-value:

The different Media-Type usages are summarized in the table below: Method Resource Media-Type FETCH request datastore application/yang-identifiers+cbor-seq FETCH response datastore application/yang-instances+cbor-seq iPATCH request datastore application/yang-instances+cbor-seq iPATCH response datastore N/A GET request datastore N/A GET response datastore application/yang-data+cbor; id=sid PUT request datastore application/yang-data+cbor; id=sid PUT response datastore N/A POST request datastore application/yang-data+cbor; id=sid POST response datastore N/A DELETE request datastore N/A DELETE response datastore N/A GET request event stream N/A GET response event stream application/yang-instances+cbor-seq FETCH request event stream application/yang-identifiers+cbor-seq FETCH response event stream application/yang-instances+cbor-seq POST request rpc, action application/yang-instances+cbor-seq POST response rpc, action application/yang-instances+cbor-seq any error
response any application/yang-data+cbor; id=sid No Media-Type (N/A) is used if the method request or response does not carry a payload.

Unified datastore CORECONF supports a simple datastore model consisting of a single unified datastore. This datastore 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. More complex datastore models such as the Network Management Datastore Architecture (NMDA) as defined by are out of scope of the present specification. Characteristics of the unified datastore are summarized in the table below: Name Value Name unified YANG modules all 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 CORECONF Defined in "ietf-coreconf"

CoAP Interface This document specifies a Management Interface. CoAP endpoints that implement the CORECONF management protocol, support at least one discoverable management resource of resource type (rt): core.c.ds. The path of the discoverable management resource is left to implementers to select (see ). YANG data node instances are accessible by performing FETCH and iPATCH operations on the datastore resource. CORECONF also supports event stream resources used to observe notification instances. Event stream resources can be discovered using resource type (rt): core.c.es. The description of the CORECONF management interface is shown in the table below: CoAP resource Example path rt Datastore resource /c core.c.ds Default event stream resource /s core.c.es The path values in the table are example ones. On discovery, the server makes the actual path values known for these resources. The methods used by CORECONF are: Operation Description FETCH Retrieve specific data nodes within a datastore resource or event stream resource iPATCH Idempotently create, replace, and delete data node(s) within a datastore resource POST Invoke an RPC or action GET Retrieve the datastore resource or event stream resource PUT Create or replace a datastore resource DELETE Delete a datastore resource

Data Retrieval One or more data nodes can be retrieved by the client. The operation is mapped to the FETCH method defined in . There are two additional query parameters for the FETCH method: query parameters Description c Control selection of configuration and non-configuration data nodes (GET and FETCH) d Control retrieval of default values.

Using the 'c' query parameter The 'c' (content) option 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 option 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 query parameter is not present, the default value is "a" (the quotes are added for readability, but they are not part of the payload).

Using the 'd' query parameter The 'd' (with-defaults) option controls how the default values of the descendant nodes of the requested data nodes will be processed. The allowed values are: Value Description a All data nodes are reported. Defined as 'report-all' in . t Data nodes set to the YANG default are not reported. Defined as 'trim' in . 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 or FETCH method is a data node that represents a container or list that has child resources with default values, and these have not been given a value yet, the server MUST NOT return the child resource if d=t, and MUST return the child resource if d=a. If this query parameter is not present, the default value is "t" (the quotes are added for readability, but they are not part of the payload).

FETCH The FETCH method is used to retrieve one or more instance-values. The FETCH request payload contains the list of instance-identifiers 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 undefined value (0xf7) 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. That means that the client is responsible for remembering the full instance-identifiers in its request since no key values will be in the response. This approach may also help reduce implementation complexity since the format of each entry within the CBOR sequence of the FETCH response is identical to the format of the corresponding GET response.

/ Request / Content-Format: TBD2 (application/yang-identifiers+cbor-seq) / CBOR sequence of instance-identifiers / 2.05 Content / Response / Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of SID, instance-value / ]]>

FETCH examples This example uses the current-datetime leaf from module ietf-system and the interface list from module ietf-interfaces . In this example the value of current-datetime (SID 1723) and the interface list (SID 1533) instance identified with name="eth0" are queried.

Data Editing CORECONF allows datastore contents to be created, modified and deleted using CoAP methods.

Data Ordering A CORECONF server MUST preserve the relative order of all user-ordered list and leaf-list entries that are received in a single edit request. As per , these YANG data node types are encoded as CBOR arrays, so messages will preserve their order.

POST The CoAP POST operation is used in CORECONF for the invocation of "ACTION" and "RPC" resources. Refer to for details on "ACTION" and "RPC" resources.

iPATCH One or multiple data node instances are replaced with the idempotent CoAP iPATCH method . There are no query parameters for the iPATCH method. The processing of one iPATCH request is atomic, as required by : the server applies the whole set of operations carried in the request, or none of them. If the request cannot be applied in full, the datastore is left unmodified and an error response is returned, as specified in . The server is free to choose how it achieves atomicity; one way is to validate the datastore that would result from the edit and to apply the change only if that validation succeeds, as described in . This needs only a transient buffer holding the datastore that would result from the edit. Atomicity is a property of a single request. A client that needs the operations of an edit to be independent of each other sends them as separate iPATCH requests; a client that needs them to succeed or fail together sends them in one request. The result of an iPATCH request is the same as if its operations were applied one after another, in the order in which they appear in the payload. For example, an operation can set a leaf of a list entry that an earlier operation of the same request has created. Constraints between data nodes, such as a leafref, are validated on the datastore that results from the whole request, so they can also refer to a data node instance that a later operation creates. The server is free to apply the operations internally in any other way, as long as that result is obtained. A successful iPATCH request is answered with 2.04 (Changed), including when the request creates or deletes data node instances: the target of the request is the datastore resource, which already exists. The processing of the iPATCH command is specified by Media-Type application/yang-instances+cbor-seq. 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 CBOR undefined value (0xf7) indicates the removal of an existing data node instance.

/ Request / Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of instance-identifier, instance-value / 2.04 Changed / Response / ]]>

iPATCH example In this example, a CORECONF client requests the following operations: Set "/ietf-system:system/ntp/enabled" (SID 1755) to true. Remove the server "tac.nrc.ca" from the "/ietf-system:system/ntp/server" (SID 1756) list. Add/set the server "tic.nrc.ca" in the list "/ietf-system:system/ntp/server" (SID 1756).

A data node instance is deleted using an iPATCH with an undefined value, as seen in this example.

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

2.05 Content Content-Format: 140 (application/yang-data+cbor; id=sid) / CBOR map of SID, instance-value / ]]>

Content-Format: 140 (application/yang-data+cbor; id=sid) / CBOR map of SID, instance-value / 2.04 Changed ]]>

Content-Format: 140 (application/yang-data+cbor; id=sid) / CBOR map of SID, instance-value / 2.01 Created ]]>

2.02 Deleted ]]>

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

Full datastore examples The example uses the interface list from module ietf-interfaces and the clock container from module ietf-system . We 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:

Event stream Event notification is an essential function for the management of servers. CORECONF allows notifications specified in YANG to be reported to a list of clients. The path for the default event stream can be discovered as described in . The server MAY support additional event stream resources to address different notification needs. Reception of notification instances is enabled with the CoAP Observe function. Clients subscribe to the notifications by sending a GET request with an "Observe" option to the stream resource. Each response payload carries zero or more notifications. A message without any notification is useful as the response that establishes a subscription (a GET with an Observe option of 0), for example when the server has nothing to report yet. Sending such a message otherwise is discouraged. When multiple notifications are reported, they MUST be ordered starting from the newest notification at index zero. Note that this could lead to notifications being sent multiple times, which increases the probability for the client to receive them, but it might potentially lead to messages that exceed the MTU of a single CoAP packet. If such cases could arise, implementers should make sure appropriate fragmentation is available - for example the one described in . The format of notifications is a CBOR sequence, where each item in the sequence is a single notification as described in . (Accordingly, a message without any notification is an empty CBOR sequence, i.e., zero bytes.)

Observe: 0 2.05 Content Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of instance-identifier, instance-value / ]]>

The sequence of data node instances may contain identical items which have been generated at different times. A CORECONF server that can no longer provide the notifications of a stream resource sends a notification with an appropriate error response code (4.xx or 5.xx) and removes the client from the list of observers, as specified in . An error that affects a single notification instance does not by itself terminate the stream. A client that observes the termination reports the failure to its user agent; whether it re-observes the stream is outside the scope of this document. 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 limited by the maximum number of notifications supported, the content of the instance is sent to all clients observing the modified stream.

Filtering Notifications If only a subset of all possible notifications is of interest, a FETCH operation can be performed with a request payload of type application/yang-identifiers+cbor-seq that indicates which subset.

Observe: 0 Content-Format: TBD2 (application/yang-identifiers+cbor-seq) / CBOR sequence of instance-identifiers / 2.05 Content Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of instance-identifier, instance-value / ]]>

When filtering is not supported by a CORECONF server, the request payload can be ignored: all event notifications are then reported independently of the presence and content of the request payload.

Notify Examples Let suppose the server generates the example-port-fault event as defined below.

In this example the default event stream resource path /s is an example location discovered with a request similar to . By executing a GET with Observe 0 on the default event stream resource the client receives the following response:

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. A client that wants to filter notifications can use a FETCH payload:

Note that the notifications in this example are identical to the unfiltered example as they are all using identifier SID 60010 and this is included in the filter.

RPC and Action 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 . The returned success response code is 2.04 Changed.

Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of instance-identifier, instance-value / 2.04 Changed Content-Format: TBD3 (application/yang-instances+cbor-seq) / CBOR sequence of CBOR maps of instance-identifier, instance-value / ]]>

RPC Example This example is based on , abbreviated and annotated with SIDs as follows:

This example invokes the 'reboot' RPC (SID 61000).

The 'reboot' RPC has no output, so the instance-value is an empty CBOR map. The output of an RPC or action is an internal node and is always encoded as a CBOR map (). The absence marker of is not used here: it only marks the absence or removal of a data node instance, and an RPC or action output is neither. A yang-instances payload is still returned, because its key (the SID of the RPC, or the instance-identifier of the action) identifies which invocation the response belongs to.

Action Example The example is based on the YANG action "reset" as defined in and annotated below with SIDs.

This example invokes the 'reset' action (SID 60002), of the server instance with name equal to "myserver".

Invocation without input An RPC or an action is invoked without input in two cases: its input has no mandatory data node and the client leaves the input out, or its YANG definition has no input at all. In both cases the request is still a payload of application/yang-instances+cbor-seq: the instance-identifier identifies the RPC or the action, and the instance-value is an empty map. The input of an RPC or an action is encoded as a CBOR map (), and an empty one has no data nodes in it. The 'reboot' RPC of can be invoked without input, because its 'delay' leaf has a default value:

(Content-Format: application/yang-instances+cbor-seq) { 61000: {} } RES: 2.04 Changed (Content-Format: application/yang-instances+cbor-seq) { 61000: {} } ]]>

In the module of , a second action 'restart' is added to the 'server' list. It has neither input nor output:

It is invoked on the server instance with name equal to "myserver":

(Content-Format: application/yang-instances+cbor-seq) { [60005, "myserver"]: {} } RES: 2.04 Changed (Content-Format: application/yang-instances+cbor-seq) { [60005, "myserver"]: {} } ]]>

Use of Block-wise Transfers 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 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, assembly of multiple blocks may be required to process complete data fields. Beware of race conditions. In case blocks are filled one at a time, care should be taken that the whole and consistent data representation is sent in multiple blocks sequentially without interruption. On the server, values might change, lists might get 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. (Note that the outer structure of yang-identifiers and yang-instances is a CBOR sequence, which already behaves similar to an indefinite-length encoded array.)

Application Discovery Two application discovery mechanisms are supported by CORECONF, the YANG library data model as defined by and the CORE resource discovery . Implementers may choose to implement one or the other or both.

YANG library The YANG library data model provides a high-level description of the resources available. The YANG library contains the list of modules, features, and deviations supported by the CORECONF server. From this information, CORECONF 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. As described in , 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. The following example assumes that the SID of the YANG library is 2351 (kv after encoding as specified in ) and that the server uses /c as datastore resource path.

;rt="core.c.yl" ]]>

Resource Discovery As some CoAP interfaces and services might not support the YANG library interface and still be interested to discover resources that are available, implementations MAY choose to support discovery of all available resources using "/.well-known/core" as defined by .

Datastore Resource Discovery The presence and location of (path to) each datastore implemented by the CORECONF 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 as specified in . For other examples of datastores, see the Network Management Datastore Architecture (NMDA) .

The following example assumes that the server uses /c as datastore resource path.

; rt="core.c.ds";ds=1029 ]]>

Data node Resource Discovery If implemented, the presence and location of (path to) each data node implemented by the CORECONF 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. The example assumes that the server uses /c as datastore resource path.

;rt="core.c.dn", ;rt="core.c.dn" ]]>

Without additional filtering, the list of data nodes may become prohibitively long. If this is the case implementations SHOULD support a way to obtain all links using multiple GET requests (for example through some form of pagination).

Event stream Resource Discovery The presence and location of (path to) each event stream implemented by the CORECONF 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. The following example assumes that the server uses /s as the default event stream resource.

;rt="core.c.es" ]]>

Error Handling In case a request is received which cannot be processed properly, the CORECONF server MUST return an error response. This error response MUST contain a CoAP 4.xx or 5.xx response code. Requests that result in an error response MUST NOT have an effect on the datastore. Errors returned by a CORECONF server can be broken into two categories, those associated with the CoAP protocol itself and those generated during the validation of the YANG data model constraints as described in . The following list of common CoAP errors should be implemented by CORECONF servers. This list is not exhaustive, other errors defined by CoAP and associated RFCs may be applicable. Error 4.01 (Unauthorized) is returned by the CORECONF server when the CORECONF client is not authorized to perform the requested action on the targeted resource (i.e., data node, datastore, rpc, action or event stream). Error 4.02 (Bad Option) is returned by the CORECONF server when one or more CoAP options are unknown or malformed. Error 4.04 (Not Found) is returned by the CORECONF server when the CORECONF client is requesting a non-instantiated resource (i.e., data node, datastore, rpc, action or event stream). Error 4.05 (Method Not Allowed) is returned by the CORECONF server when the CORECONF 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). Error 4.08 (Request Entity Incomplete) is returned by the CORECONF server if one or multiple blocks of a block transfer request is missing, see for more details. Error 4.13 (Request Entity Too Large) may be returned by the CORECONF server during a block transfer request, see for more details. Error 4.15 (Unsupported Content-Format) is returned by the CORECONF server when the Content-Format used in the request does not match those specified in . The CORECONF server MUST also enforce the different constraints associated with the YANG data models implemented. These constraints are described in . These errors are reported using the CoAP error code 4.00 (Bad Request) and may have the following error container, defined as a YANG data structure , as payload. The YANG definition and associated .sid file are available in and . The error container is encoded using the encoding rules of a YANG data template as defined in .

The following 'error-tag' and 'error-app-tag' are defined by the ietf-coreconf YANG module, these tags are implemented as YANG identity and can be extended as needed. error-tag 'operation-failed' is returned by the CORECONF server when the operation request cannot be processed successfully. error-app-tag 'malformed-message' is returned by the CORECONF server when the payload received from the CORECONF client does not contain a well-formed CBOR content as defined in or does not comply with the CBOR structure defined within this document. error-app-tag 'data-not-unique' is returned by the CORECONF server when the validation of the 'unique' constraint of a list or leaf-list fails. error-app-tag 'too-many-elements' is returned by the CORECONF 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 CORECONF 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 CORECONF server when the restrictions imposed by a 'must' statement are violated. error-app-tag 'duplicate' is returned by the CORECONF server when a client tries to create a duplicate list or leaf-list entry. error-tag 'invalid-value' is returned by the CORECONF server when the CORECONF 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' constraint is not fulfilled. error-app-tag 'invalid-datatype' is returned by the CORECONF server when CBOR encoding does not follow the rules set by the YANG Build-In type or when the value is incompatible with it (e.g., a value greater than 127 for an int8, undefined enumeration). error-app-tag 'not-in-range' is returned by the CORECONF server when the validation of the 'range' property fails. error-app-tag 'invalid-length' is returned by the CORECONF server when the validation of the 'length' property fails. error-app-tag 'pattern-test-failed' is returned by the CORECONF server when the validation of the 'pattern' property fails. error-tag 'missing-element' is returned by the CORECONF server when the operation requested by a CORECONF 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'. error-app-tag 'missing-key' is returned by the CORECONF server to further qualify a missing-element error. This error is returned when the CORECONF client tries to create or list instance, without all the 'key' specified or when the CORECONF client tries to delete a leaf listed as a 'key'. error-app-tag 'missing-input-parameter' is returned by the CORECONF server when the input parameters of an RPC or action are incomplete. error-tag 'unknown-element' is returned by the CORECONF server when the CORECONF 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'. error-tag 'bad-element' is returned by the CORECONF server when the CORECONF client tries to create data nodes for more than one case in a choice. error-tag 'data-missing' is returned by the CORECONF server when a data node required to accept the request is not present. error-app-tag 'instance-required' is returned by the CORECONF 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 CORECONF server when no nodes exist in a mandatory choice. error-tag 'error' is returned by the CORECONF server when an unspecified error has occurred. For example, the CORECONF server might return the following error.

Security Considerations For secure network management, it is important to restrict access to configuration variables only to authorized parties. CORECONF re-uses the security mechanisms already available to CoAP, this includes DTLS and OSCORE for protected access to resources, as well as suitable authentication and authorization mechanisms, for example those defined in ACE OAuth . All the security considerations of , , and apply to this document as well. The use of NoSec (), when OSCORE is not used, is NOT RECOMMENDED. In addition, mechanisms for authentication and authorization may need to be selected if not provided with the CoAP security mode. As and are used for payload and SID encoding, the security considerations of those documents also need to be well-understood. The YANG module specified in this document defines a schema for data that is designed to be accessed via CORECONF itself. Which secure transports are mandatory to implement is an open issue (see ). The module does not define any configuration or state data nodes and the usual analysis of which subtrees and data nodes are sensitive or vulnerable to write or read operations does not apply to it. What does deserve attention is the content a server places in the error structure (). The 'error-data-node' leaf carries an instance-identifier, and 'error-message' carries free text. A server that returns either to a client that is not authorized to see the corresponding part of the datastore discloses the shape of its data model, and possibly the existence of specific instances, through the error path. A server SHOULD limit the detail it reports in an error response to what the requesting client is authorized to read.

IANA Considerations

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.

CoAP Content-Formats Registry This document adds the following Content-Formats from the Expert Review range (0-255) to the "CoAP Content-Formats", within the "Constrained RESTful Environments (CoRE) Parameters" registry. Media Type Content Coding ID Reference application/yang-identifiers+cbor-seq   TBD2 RFC XXXX application/yang-instances+cbor-seq   TBD3 RFC XXXX // RFC Ed.: replace TBD2 (suggested: 141) and TBD3 (suggested: 142) with assigned IDs and remove this note. (There is no TBD1, that was already defined in RFC 9254.) // RFC Ed.: replace RFC XXXX with this RFC number and remove this note.

Media Types Registry This document adds the following media types to the "Media Types" registry. Name Template Reference yang-identifiers+cbor-seq application/yang-identifiers+cbor-seq RFC XXXX yang-instances+cbor-seq application/yang-instances+cbor-seq RFC XXXX Each of these media types share the following information: Subtype name: <as listed in table> Required parameters: N/A Optional parameters: N/A Encoding considerations: binary Security considerations: See the Security Considerations section of RFC XXXX Interoperability considerations: N/A Published specification: RFC XXXX Applications that use this media type: CORECONF Fragment identifier considerations: N/A Additional information:

Person & email address to contact for further information: iesg&ietf.org Intended usage: COMMON Restrictions on usage: N/A Author: Michel Veillette Change Controller: IETF Provisional registration? No // RFC Ed.: replace RFC XXXX with this RFC number and remove this note.

YANG Namespace and Module Name Registration This document registers the following XML namespace URN in the "IETF XML Registry", following the format defined in : URI: please assign urn:ietf:params:xml:ns:yang:ietf-coreconf Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. Reference: RFC XXXX IANA is requested to register the following YANG module in the "YANG Module Names" registry : Name: ietf-coreconf Namespace: urn:ietf:params:xml:ns:yang:ietf-coreconf Prefix: coreconf Reference: RFC XXXX // RFC Ed.: please replace XXXX with RFC number and remove this note The YANG module and SID file are in and , respectively.

YANG SID Range Assignment IANA has assigned the following SID range to the "ietf-coreconf" YANG module in the "IETF YANG-SID Ranges" registry, following the procedure of . IANA is requested to update the reference of this entry to this document: Entry Point: 1000 Size: 100 Module Name: ietf-coreconf Reference: RFC XXXX The SID file in assigns SIDs from this range, and this document depends on those values: uses the SID of the "unified" datastore identity.

This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK] This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] The Network Configuration Protocol (NETCONF) defines ways to read and edit configuration data from a NETCONF server. In some cases, part of this data may not be set by the NETCONF client, but rather a default value known to the server is used instead. In many situations the NETCONF client has a priori knowledge about default data, so the NETCONF server does not need to save it in a NETCONF configuration datastore or send it to the client in a retrieval operation reply. In other situations the NETCONF client will need this data from the server. Not all server implementations treat this default data the same way. This document defines a capability-based extension to the NETCONF protocol that allows the NETCONF client to identify how defaults are processed by the server, and also defines new mechanisms for client control of server processing of default data. [STANDARDS-TRACK] The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. This document describes the Concise Binary Object Representation (CBOR) Sequence format and associated media type "application/cbor-seq". A CBOR Sequence consists of any number of encoded CBOR data items, simply concatenated in sequence. Structured syntax suffixes for media types allow other media types to build on them and make it explicit that they are built on an existing media type as their foundation. This specification defines and registers "+cbor-seq" as a structured syntax suffix for CBOR Sequences. The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). The Constrained Application Protocol (CoAP) is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for small payloads from sensors and actuators; however, applications will need to transfer larger payloads occasionally -- for instance, for firmware updates. In contrast to HTTP, where TCP does the grunt work of segmenting and resequencing, CoAP is based on datagram transports such as UDP or Datagram Transport Layer Security (DTLS). These transports only offer fragmentation, which is even more problematic in constrained nodes and networks, limiting the maximum size of resource representations that can practically be transferred. Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. Essentially, the Block options provide a minimal way to transfer larger representations in a block-wise fashion. A CoAP implementation that does not support these options generally is limited in the size of the representations that can be exchanged, so there is an expectation that the Block options will be widely used in CoAP implementations. Therefore, this specification updates RFC 7252. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources. This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource. This document describes YANG mechanisms for defining abstract data structures with YANG. YANG (RFC 7950) is a data modeling language used to model configuration data, state data, parameters and results of Remote Procedure Call (RPC) operations or actions, and notifications. This document defines encoding rules for YANG in the Concise Binary Object Representation (CBOR) (RFC 8949). YANG Schema Item iDentifiers (YANG SIDs) are globally unique 63-bit unsigned integers used to identify YANG items. SIDs provide a more compact method for identifying those YANG items that can be used efficiently, notably in constrained environments (RFC 7228). This document defines the semantics, registration processes, and assignment processes for YANG SIDs for IETF-managed YANG modules. To enable the implementation of these processes, this document also defines a file format used to persist and publish assigned YANG SIDs. Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. Trilliant Networks Inc. Acklio This document describes a constrained version of the YANG library that provides information about the YANG modules, datastores, and datastore schemas used by a constrained network management server (e.g., a CORECONF server). In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). This document specifies version 1.2 of the Datagram Transport Layer Security (DTLS) protocol. The DTLS protocol provides communications privacy for datagram protocols. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. The DTLS protocol is based on the Transport Layer Security (TLS) protocol and provides equivalent security guarantees. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document updates DTLS 1.0 to work with TLS version 1.2. [STANDARDS-TRACK] 
This specification is obsoleted by . This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] This document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes definitions for configuration and system state (status information and counters for the collection of statistics). The YANG data model in this document conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342. This document obsoletes RFC 7223. This document defines a YANG data model for the configuration and identification of some common system properties within a device containing a Network Configuration Protocol (NETCONF) server. This document also includes data node definitions for system identification, time-of-day management, user management, DNS resolver configuration, and some protocol operations for system management. This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. This document specifies version 1.3 of the Datagram Transport Layer Security (DTLS) protocol. DTLS 1.3 allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection / non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol. This document obsoletes RFC 6347. This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE-OAuth. The framework is based on a set of building blocks including OAuth 2.0 and the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to better serve the IoT use cases. The Constrained Application Protocol (CoAP), although inspired by HTTP, was designed to use UDP instead of TCP. The message layer of CoAP over UDP includes support for reliable delivery, simple congestion control, and flow control. Some environments benefit from the availability of CoAP carried over reliable transports such as TCP or Transport Layer Security (TLS). This document outlines the changes required to use CoAP over TCP, TLS, and WebSockets transports. It also formally updates RFC 7641 for use with these transports and RFC 7959 to enable the use of larger messages over a reliable transport.

ietf-coreconf YANG module This appendix is normative.

WG List: Michel Veillette Alexander Pelov Peter van der Stok Andy Bierman Carsten Bormann "; description "This module contains the different definitions required by the CORECONF protocol. Copyright (c) 2026 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; revision 2026-03-02 { description "Initial revision."; reference "RFC XXXX: CoAP Management Interface (CORECONF)"; } identity unified { base ds:datastore; description "Identifier of 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 CORECONF server when the operation request can't be processed successfully."; } identity invalid-value { base error-tag; description "Returned by the CORECONF server when the CORECONF 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' constraint is not fulfilled."; } identity missing-element { base error-tag; description "Returned by the CORECONF server when the operation requested by a CORECONF 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 CORECONF server when the CORECONF 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 CORECONF server when the CORECONF client tries to create data nodes for more than one case in a choice."; } identity data-missing { base error-tag; description "Returned by the CORECONF server when a data node required to accept the request is not present."; } identity error { base error-tag; description "Returned by the CORECONF server when an unspecified error has occurred."; } identity error-app-tag { description "Base identity for error-app-tag."; } identity malformed-message { base error-app-tag; description "Returned by the CORECONF server when the payload received from the CORECONF client don't contain a well-formed CBOR content as defined in [RFC8949] or don't comply with the CBOR structure defined within this document."; } identity data-not-unique { base error-app-tag; description "Returned by the CORECONF 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 CORECONF 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 CORECONF 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 CORECONF server when the restrictions imposed by a 'must' statement are violated."; } identity duplicate { base error-app-tag; description "Returned by the CORECONF server when a client tries to create a duplicate list or leaf-list entry."; } identity invalid-datatype { base error-app-tag; description "Returned by the CORECONF server when CBOR encoding is incorrect 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 CORECONF server when the validation of the 'range' property fails."; } identity invalid-length { base error-app-tag; description "Returned by the CORECONF server when the validation of the 'length' property fails."; } identity pattern-test-failed { base error-app-tag; description "Returned by the CORECONF server when the validation of the 'pattern' property fails."; } identity missing-key { base error-app-tag; description "Returned by the CORECONF server to further qualify a missing-element error. This error is returned when the CORECONF client tries to create a list instance, without all the 'key' specified or when the CORECONF client tries to delete a leaf listed as a 'key'."; } identity missing-input-parameter { base error-app-tag; description "Returned by the CORECONF server when the input parameters of a RPC or action are incomplete."; } identity instance-required { base error-app-tag; description "Returned by the CORECONF 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 CORECONF server when no nodes exist in a mandatory choice."; } sx:structure 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."; } } } ]]>

ietf-coreconf .sid file This appendix is normative.

SIDs used in the examples The SIDs in the examples of this document are illustrative. This annex lists them by module, so that an example can be followed from one section to the next. A node has the same SID in every example in which it appears. The data examples use the modules ietf-interfaces and ietf-system . The examples of an RPC, an action and notifications use three small modules written for this document, because the two standard modules define no action and no notification. ietf-interfaces, and the identity ethernetCsmacd of iana-if-type: Node SID Used in module ietf-interfaces 1500 interface (list) 1533 , description 1534 , enabled 1535 , name 1537 , type 1538 , oper-status 1544 , ethernetCsmacd 1880 , ietf-system: Node SID Used in module ietf-system 1700 timezone-utc-offset 1740 clock (container) 1721 boot-datetime 1722 , current-datetime 1723 , , ntp/enabled 1755 ntp/server (list) 1756 name (of a server) 1759 prefer (of a server) 1760 udp (of a server) 1761 address (of udp) 1762 The YANG library, as assumed in : Node SID Used in YANG library 2351 ietf-coreconf, defined in : Node SID Used in error 1024 error-app-tag 1025 error-data-node 1026 error-message 1027 error-tag 1028 invalid-value 1011 not-in-range 1018 The module example-ops, used for the RPC: Node SID Used in reboot (RPC) 61000 delay 61001 input 61009 The module example-server-farm, used for the action: Node SID Used in server (list) 60000 name 60001 reset (action) 60002 reset-at 60003 reset-finished-at 60004 restart (action) 60005 input 60008 output 60009 The module example-port, used for notifications: Node SID Used in example-port-fault 60010 port-name 60011 port-fault 60012

Open Issues The following issues are not resolved in this revision and are planned for discussion at IETF 127 (see https://github.com/core-wg/comi/issues): How a SID is encoded in a URI path segment, and whether CORECONF supports discovery of individual data nodes through such URIs, or only through FETCH and the YANG library (issue #19, pull request #26). Whether the Content-Format Option is required on a POST to the datastore resource, where the same method is used both to create the datastore and to invoke an RPC or action (issue #29). Which security mechanisms a CORECONF implementation is required to support.

List of Figures

:

:

:

:

:

:

List of Tables

:

:

:

:

:

:

:

:

:

:

Acknowledgments We are very grateful to who was one of the original authors of the CORECONF specification. and explained the encoding aspects of PDUs transported under SNMP. 's implementation input motivated massively simplifying (and fixing) the URI construction for GET/PUT/POST requests. The specification has further benefited from comments (alphabetical order) by , , , , , , , , , , , , and .

Contributors Google

ivaylopetrov@google.com