]> CZ.NIC

Milesovska 1136/5 Praha 13000 Czech Republic vojtech.vilimek@nic.cz

AREA CoRE YANG-CBOR YANG CBOR The YANG-CBOR document defines rules for representing YANG-modeled data in CBOR . The YANG-CBOR defines rules for all built-in types, such as int64, leafref, and instance-identifier data type. However it fails to address some cases of the instance-identifier, specifically those pointing to keyless list entries or leaf-list entries. This documents updates to make the rules complete. About This Document Status information for this document may be found at . Discussion of this document takes place on the Constrained RESTful Environments (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 : Encoding Rules of Data Modeled with YANG in the Concise Binary Object Representation (CBOR) defines rules for representing of YANG-modeled data in CBOR . The instance-identifier YANG data type is well-defined for instances that reference containers, lists with one or more keys, and leafs. The document fails to address cases when the instance-identifier instance points to entries in a list with no keys or a leaf-list. The YANG-CBOR refines encoding rules of two kinds. One variant, named as using names, is compatible with YANG-JSON encoding. The second variant uses SIDs to compress the information needed to encode the instance-identifier. Only the SID-based encoding rules are incomplete. This documents aims to define the missing rules and to clarify the terminology used.

Terminology and Notation 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. The following terms are defined in :

• list
• leaf-list
• leaf
• container
• instance-identifier

The following term is defined in :

• data item

The following terms are defined in :

• YANG Scheme Item iDentifier (YANG SID, or simply SID)
• delta (of YANG SIDs)
• absolute SID

The following terms are defined in :

• item

Keyless list:

Is config false YANG list without any keys.

Keyed list:

Is YANG list that is not a keyless list. It is either a config true list or a config false list with at least one key. Note that a config true list must have at least one key.

Representing SIDs as YANG instance-identifier in CBOR

Motivation example Definition example adapted from : The following example shows the encoding of the 'reporting-entity' value referencing "neighbor-sysid" (which is assumed to have SID 68000) of the second list entry of the keyless "/isis:adjacencies/adjacency" list. The example is adapted from and therefore uses the isis namespace: We want to represent reporting-entity so that the value is "/isis:adjacencies/adjacency[.=2]/neighbor-sysid" instance-identifier, but we want to use SIDs Becuase the YANG list does not specify any keys, we will use index-based identification. Becuase the YANG do not specify any keys, we will resort to index based identification. CBOR diagnostic notation: [ 68000, 2 ] CBOR encoding: Where 68000 is absolute SID and 2 is 1-based index of the list entry.

Rules The definitions of require that the list entries are encoded as CBOR array with SID as first element, followed by keys in order same as walk from schema root to the targeted child node. This formulation only applies to keyed lists. For keyless lists, the entry identification MUST be encoded using a CBOR unsigned integer data item (major type 0). The index MUST be 1-based to maintain the same indexing base as RESTCONF and NETCONF . If the target data node is a leaf-list entry, the last element of the CBOR array MUST be encoded according to the encoding rules for the given leaf-list's type. The YANG 1.1 allows a leaf-list of state data (config false) to have duplicates. In this case, it is not defined which element the instance-identifier identifies. Due to restriction set forth in it is not possible to point the instance-identifier to a list or a leaf-list schema node. Only instance data (i.e. nodes in the data tree) can be targeted. TODO: If these encoding rules are accepted by the working group consensus, changes to the draft I-D.core-comi (CORECONF) will be necessary. This will allow us to identify keyless list instances, which is impossible in RESTCONF.

Examples Unless stated otherwise, all examples are considered to live inside the example module namespace. An equivalent representation using the Names encoding may help readers who are already familiar with YANG JSON encoding , or similar XML encoding defined in YANG 1.1 .

Simple leaf-list instance-identifier The following example shows the encoding of the 'reporting-entity' value referencing leaf-list instance "/auth/foreign-user" (which is assumed to have SID 60000) entry "alice". The name-based representation is "/example:auth/foreigh-user[.="alice"]". CBOR diagnostic notation: [ 60000, "alice" ] CBOR encoding:

Leaf-list inside list The following example shows the encoding of the 'reporting-entity' value referencing leaf-list instance "/user-group/user" (which is assumed to have SID 61000) entry "eve" for group-name "restricted". The name-based representation is "/example:user-group[group-name="restricted"]/user[.="eve"]". CBOR diagnostic notation: [ 61000, "restricted", "eve" ] CBOR encoding:

List instance We reuse the YANG snippet from . The following example shows the encoding of 'reporting-entity' value referencing list instance "/user-group" for group name "restricted". The name-based representation is "/example:user-group[group-name="restricted"]". CBOR diagnostic notation: [ 61000, "restricted" ] CBOR encoding:

Instance-identifier chaining The following example shows the encoding of 'reporting-entity' value referencing leaf-list instance "/working-group/chair" entry. This entry references "/auth/foreign-user" leaf-list entry "Carsten Bormann". The "/working-group/chair" is assumed to have SID 62000. The name-based representation is "/example:working-group[name="core"]/chair=[.="/example:auth/foreign-user[.="John Smith"]"]. CBOR diagnostic notation: [ 62000, "core", [ 60000, "Carsten Bormann" ] ] CBOR encoding: TODO longer chains of leaf-list instance-identifier lead to high nesting of the CBOR array data items. Shoul a cap for the contrained nodes by put to simplify the implementations? I think cap around 8 should be suffient for most deployments. I think that using leaf-list instance-identifier chaining is not a good practise.

Complex example of mixed keyed and keyless lists The following example shows the encoding of 'reporting-entity' value referencing leaf 'token-data' of device with 'id' "id01", first 'security' list entry for user's 'bob' second 'access-token' list entry. The leaf 'token-data' is assumed to have SID 61500. The name-based representation is "/example:device[id="id01"]/security[.=1]/user[user="bob"]/access-token[.=2]/token-data". CBOR diagnostic notation: [ 61500, "id01", 1, "bob", 2 ] CBOR encoding:

Content-Types TODO Is it possible to reuse the Content-types define in the ? It would be wasteful to assign new MIME content-type to basically the same format.

Security Considerations The security considerations of , , and apply. The implementations should be aware of possibly very large recursive nesting that occurs when instance-identifiers are chained. TODO Security

IANA Considerations This document has no IANA actions. TODO Is it possible to keep the same IANA allocations of th ? This draft wants to be more of a bugfix document than new encoding scheme.

References Normative References 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 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. 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. 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. Informative References 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] This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text. 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 defines a YANG data model that can be used to configure and manage the IS-IS protocol on network elements.

Acknowledgments TODO acknowledge. thank Andy Bierman for his friendly responses on mailing list.