]> Universität Bremen TZI

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

ART (Applications and Real-Time) CBOR This specification defines the representation of metadata annotations (RFC 7952) in YANG-CBOR (RFC 9254). About This Document Status information for this document may be found at . Discussion of this document takes place on the cbor Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This specification defines the representation of metadata annotations in YANG-CBOR .

Conventions and Definitions 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 term "CDDL" refers to the data definition language defined in and its registered extensions (such as those in ), as well as . Specific examples are notated in CBOR Extended Diagnostic Notation (EDN), as originally introduced in Section of RFC 8949 and extended in . ( more rigorously defines and further extends EDN.) RFC-Editor:
This document uses the CPA (code point allocation) convention described in [I-D.bormann-cbor-draft-numbers]. For each usage of the term "CPA", please remove the prefix "CPA" from the indicated value and replace the residue with the value assigned by IANA; perform an analogous substitution for all other occurrences of the prefix "CPA" in the document. Finally, please remove this note. The terms of and apply.

Specification This section defines the metadata encoding for YANG-CBOR , analogous to the Subsections for YANG-XML and YANG-JSON of . defines a "Metadata Object" for YANG-JSON. Analogously, the YANG-CBOR encoding of metadata annotations uses a Metadata Map, which is identical in structure to the other CBOR maps used in . Where YANG SIDs are used as the basis for the map keys for the metadata map, the map's reference SID is the reference SID of the enclosing data structure, as defined in . Where names () are used as the map keys for the metadata map, they MUST be fully qualified, analogous to . Metadata annotations are added to a data node instance by replacing the representation of the instance ("Instance-Representation") with the structure specified in CDDL in :

Metadata-Annotated Data Node = #6.109([ ; CPA109 metadata-map, Instance-Representation ]) ]]>

In essence, the annotated-data-node stands in for the Instance-Representation; a consuming implementation that wants to ignore all metadata received can simply replace each annotated-data-node by the Instance-Representation embedded in it. (Editor's note:) QUESTION: Do we need to represent metadata maps without the actual instance representation present? If yes, we could simply make the second element of the array in optional. (Editor's note:) QUESTION: This representation assumes that it is good that metadata always come before the actual data node, as would also be the case with XML attributes. Sections and of show examples with metadata last, though. Can we simply focus on one of these orders (always first, or always last), or do we really need to support both (avoid!)?

Examples This section provides a number of examples, based on the examples in ; please see the descriptions of these examples there. Note that the examples here always show an enclosing map if needed; this is generally elided in (which shows only map key and map value separated by colon). All but one example below use YANG SIDs (). For this, the examples assume the example SID assignments in , the relevant ones of which are also repeated at the start of each subsection: Example SID values

name	SID
cask	61600
seq	61601
name	61602
stuff	61603
example-last-modified:last-modified	61610
foo:flag	61620
bibliomod:folio	61630

For computing the outermost SID deltas, the examples assume the reference SID is 61000.

Examples from The examples here show that the map representing the instance representation is not extended by a new member as in , but is enclosed in an annotated-data-node structure like in the other examples. Example SID values for this section

name	SID
cask	61600
seq	61601
name	61602
example-last-modified:last-modified	61610

"cask" is a container or anydata node:

Cask example

The same "cask" example with name-based CBOR maps ():

Cask example with names

"seq" is a list whose key is "name"; annotation "last-modified" is added only to the first entry:

Seq example

Examples from Example SID values for this section

name	SID
stuff	61603
example-last-modified:last-modified	61610
foo:flag	61620

"flag" is a leaf node of the "boolean" type defined in module "foo". The SID 61620 for "foo:flag" expresses both the name "flag" and the namespace name "foo" in its CBOR encoding:

Foo:flag example

"stuff" is an anyxml node:

Stuff example

Examples from

name	SID
example-last-modified:last-modified	61610
bibliomod:folio	61630

Bibliomod:folio example SID: 61610 /CPA/ 109([{-20: "2015-06-18T17:01:14+02:00"}, 3]), /CPA/ 109([{-20: "2015-09-16T10:27:35+02:00"}, 7]), 8, ] } ]]>

Security Considerations The security considerations of and apply.

IANA Considerations

CBOR Tags Registry In the registry "CBOR Tags" , IANA is requested to allocate one tag:

• Tag: CPA109
• Data item: Array [metadata, ?data]
• Semantics: "YANG data node with metadata annotations"
• Reference: This document

References Normative References This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. 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). 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. IANA 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. The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed:,, and for the construction of constants; / for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and for indicating the use of a non-basic feature in an instance. Universität Bremen TZI The Concise Data Definition Language (CDDL), as defined in RFC 8610 and RFC 9165, provides an easy and unambiguous way to express structures for protocol messages and data formats that are represented in CBOR or JSON. The present document updates RFC 8610 by addressing errata and making other small fixes for the ABNF grammar defined for CDDL there. 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 Universität Bremen TZI The Concise Binary Object Representation, CBOR (STD 94, RFC 8949), defines a "diagnostic notation" in order to be able to converse about CBOR data items without having to resort to binary data. This document specifies how to add application-oriented extensions to the diagnostic notation. It then defines two such extensions for text representations of epoch-based date/times and of IP addresses and prefixes (RFC 9164). A few further additions close some gaps in usability. To facilitate tool interoperation, this document specifies a formal ABNF definition for extended diagnostic notation (EDN) that accommodates application- oriented literals.

Acknowledgments Andy Bierman brought up the need for this document.