Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR)
Extracted elements (30)
CBOR tags are used sparingly — only for absolute SIDs (tag 47), anyxml data nodes, and union datatype disambiguation — to minimize encoded size and avoid unnecessary meta-information beyond the CBOR generic data model.
Enumeration and bits types defined within a union are encoded as CBOR text strings (rather than integers or byte strings) to maintain compatibility with the XML and JSON encodings of overlapping unions, which is required by the idiosyncrasy of YANG's data model for unions (RFC 7950 Section 9.12).
SIDs were introduced to allow YANG data models to be implemented on constrained devices and constrained networks (RFC 7228), where the text-string identifiers used by NETCONF and RESTCONF impose unacceptable overhead. The name-based encoding is retained for environments that wish to avoid SID management overhead at the cost of larger message size.
The anyxml node serializes arbitrary CBOR content, and its value MAY contain items tagged with the CBOR tags listed in Section 9.3. Those tags SHALL be supported. The 'xml' in the name is a misnomer inherited from YANG-XML and does not imply XML content.
This specification supports two CBOR key types — SIDs and names — which are distinguishable by their CBOR type (integer vs. text string). Protocols or mechanisms implementing this specification can mandate one key type or allow the generator to choose freely per key.
A leaf-list MUST be encoded using a CBOR array data item (major type 4); each entry MUST be encoded according to its datatype per Section 6.
A 'leaf' MUST be encoded according to its datatype using the encoding rules specified in Section 6.
A list or subset of a list MUST be encoded using a CBOR array data item (major type 4), even when it has a single entry. Each list entry within the array is encoded as a CBOR map using container-like encoding rules.
Container-like instances (containers, YANG data structures, notification contents, RPC inputs/outputs, action inputs/outputs, list entries, and anydata nodes) MUST be encoded using a CBOR map data item (major type 5), with each schema node encoded as a key-value pair.
In a union type, bits, enumeration, identityref, and instance-identifier MUST be enclosed by their respective CBOR tags (43, 44, 45, 46) to avoid ambiguity when different YANG datatypes share the same CBOR major type.
The bits type when defined within a union type MUST be encoded as a CBOR text string containing a space-separated sequence of names of the set bits, enclosed by CBOR tag 43.
The enumeration type MUST be encoded as a CBOR unsigned or negative integer based on the assigned or automatically computed value. However, when enumeration appears in a union type, it MUST be encoded as a CBOR text string enclosed by CBOR tag 44.
The yang-data extension container MUST be encoded using the same rules as YANG container-like instances (Section 4.2). When using SIDs, the outer CBOR map key is the SID of the yang-data extension container; when using names, the key is the namespace-qualified name.
Unless specified otherwise by the implementing protocol, indefinite length encoding (per RFC 8949 Section 3.2) SHALL be supported by CBOR decoders used with YANG-CBOR, enabling implementations to emit arrays or maps before the number of entries is known.
When identityref values are encoded using SIDs, they MUST use a CBOR unsigned integer (major type 0); no delta mechanism is employed for identityref SIDs. When encoded as names and the identity is in a different module than the leaf, the namespace-qualified form MUST be used.
YANG item identifiers encoded as names MUST use the namespace-qualified form (module:identifier) for all members of a top-level CBOR map and whenever the namespace of a representation node differs from its parent. In all other cases, the simple form MUST be used.
SIDs used as CBOR map keys are encoded as deltas: signed integers added to a reference SID. The reference SID for an outermost map is zero unless conferred by the environment; for inner maps it is the SID of the enclosing map entry. Absolute SIDs in key positions require CBOR tag 47.
This specification defines three content-types based on application/yang-data+cbor: with id=sid (compact SID-based, for constrained nodes), id=name (text-string-based, as a drop-in for JSON), and without the id parameter (mixed, for applications that need to handle YANG modules before SID mappings are defined).
YANG Schema Item iDentifier (YANG SID or SID) is a 63-bit unsigned integer (range 0..9223372036854775807) used to identify YANG items including identities, data nodes, RPCs, actions, YANG data structures, notifications, modules, and features. SID value 0 is reserved and never used in interchange.
IANA has allocated five CBOR tag numbers: tag 43 (YANG bits datatype, text string), tag 44 (YANG enumeration datatype, text string), tag 45 (YANG identityref, unsigned integer or text string), tag 46 (YANG instance-identifier, unsigned integer, text string, or array), and tag 47 (YANG SID absolute value, unsigned integer).
IANA has registered the media type 'application/yang-data+cbor' in the Media Types registry (RFC 9254). The optional 'id' parameter accepts values 'sid' or 'name' to indicate the key encoding type used in the CBOR representation.
IANA has registered three CoAP Content-Format IDs: 340 for application/yang-data+cbor, 341 for application/yang-data+cbor; id=name, and 140 for application/yang-data+cbor; id=sid in the CoRE Parameters registry.
Software on the receiving side SHOULD reject all messages that do not comply with the rules of this document and reply with an appropriate error message. In particular, when the id parameter is used, identifiers of the other type must be rejected to avoid divergent interpretation of content between implementations.
When SIDs are in use, interpretation of encoded data depends not only on having the correct YANG modules but also on the correct SID mapping information. Management and evolution of SID mappings therefore requires the same care as managing the YANG modules themselves.
Absolute SID values in map key positions (where bare integers imply deltas) MUST be tagged with CBOR tag number 47 wrapping a CBOR unsigned integer. This distinguishes absolute SIDs from delta-encoded SIDs during deserialization.
Instance-identifier for single-instance schema nodes MUST be encoded as a CBOR unsigned integer set to the target SID. For list entries, it MUST be a CBOR array whose first entry is the target SID and subsequent entries are the list key values in key-statement order.
The bits type MUST be encoded as a CBOR byte string (major type 2) when only one byte string suffices, or as a CBOR array alternating byte strings and positive unsigned integers (skip offsets multiplied by 8). An array with a single byte string MUST be encoded as just that byte string; trailing zero bytes at the end of a byte string MUST be omitted.
The decimal64 type MUST be encoded using a CBOR decimal fraction as defined in RFC 8949 Section 3.4.4 (CBOR tag 4 wrapping a two-element array of exponent and mantissa). For example, 2.57 with fraction-digits 2 encodes as 4([-2, 257]).
The empty type MUST be encoded using the CBOR null value (major type 7, additional information 22). The binary type MUST be encoded as a CBOR byte string (major type 2). The string type MUST be encoded as a CBOR text string (major type 3). The boolean type MUST be encoded as CBOR simple value true (major type 7, additional information 21) or false (major type 7, additional information 20).
Unsigned integer types (uint8, uint16, uint32, uint64) MUST be encoded as a CBOR unsigned integer data item (major type 0). Signed integer types (int8, int16, int32, int64) MUST be encoded as CBOR unsigned integer (major type 0) or CBOR negative integer (major type 1) depending on the actual value.