Representing metadata annotations in YANG-CBOR
Internet-Draft draft-bormann-cbor-yang-metadata-00
Carsten Bormann
Universität Bremen TZI
Postfach 330440
Bremen
D-28359
Germany
+49-421-218-63921
cabo@tzi.org
18 April 2024
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 https://datatracker.ietf.org/doc/draft-bormann-cbor-yang-metadata/.
Discussion of this document takes place on the cbor Working Group mailing list (mailto:cbor@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/cbor/. Subscribe at https://www.ietf.org/mailman/listinfo/cbor/.
Source for this draft and an issue tracker can be found at https://github.com/cabo/yang-metadata.
Introduction
This specification defines the representation of metadata annotations [RFC7952] in YANG-CBOR [RFC9254].
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 [BCP14] when, and only when, they appear in all capitals, as shown here.
The term "CDDL" refers to the data definition language defined in [RFC8610] and its registered extensions (such as those in [RFC9165]), as well as [I-D.ietf-cbor-update-8610-grammar].
Specific examples are notated in CBOR Extended Diagnostic Notation (EDN), as originally introduced in Section 8 of RFC 8949 [STD94] and extended in Appendix G of [RFC8610]. ([I-D.ietf-cbor-edn-literals] 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 [RFC7952] and [RFC9254] apply.
Specification
This section defines the metadata encoding for YANG-CBOR [RFC9254], analogous to the Subsections for YANG-XML and YANG-JSON of Section 5 of [RFC7952].
Section 5.2.1 of [RFC7952] 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 [RFC9254].
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 Section 3.2 of [RFC9254]. Where names (Section 3.3 of [RFC9254]) are used as the map keys for the metadata map, they MUST be fully qualified, analogous to Section 5.2.1 of [RFC7952].
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 Figure 1:
Metadata-Annotated Data Node

annotated-data-node<Instance-Representation> = #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 Figure 1 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 5.2.3 and 5.2.4 of [RFC7952] 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 Section 5.2 of [RFC7952]; 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 Section 5.2 of [RFC7952] (which shows only map key and map value separated by colon).
All but one example below use YANG SIDs (Section 3.2 of [RFC9254]). For this, the examples assume the example SID assignments in Table 1, 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 Section 5.2.2 of [RFC7952]
The examples here show that the map representing the instance representation is not extended by a new member as in Section 5.2.2 of [RFC7952], 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

{
   600: /CPA/ 109([                      # SID: 61600
     {
       10: "2015-09-16T10:27:35+02:00"   # SID: 61610
     },
     ... # instance representation in its own map
   ])
}

The same "cask" example with name-based CBOR maps (Section 3.3 of [RFC9254]):
Cask example with names

{
   "cask": /CPA/ 109([
     {
       "example-last-modified:last-modified":
         "2015-09-16T10:27:35+02:00"
     },
     ... # instance representation in its own map
   ])
}

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

{
   601: [                                # SID: 61601
     /CPA/ 109([
       {
          9: "2015-09-16T10:27:35+02:00" # SID: 61610
       },
       {
          1: "one",                      # SID: 61602
          ...: ...
       }
     ]),
     {                       # no metadata annotation
       1: "two",                         # SID: 61602
       ...: ...
     }
   ]
}

Examples from Section 5.2.3 of [RFC7952]
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

{
  620: 109([                             # SID: 61620
    {
      -10: "2015-09-16T10:27:35+02:00"   # SID: 61610
    },
    true
  ])
}

"stuff" is an anyxml node:
Stuff example

{
  603: 109([                             # SID: 61603
    {
      7: "2015-09-16T10:27:35+02:00"     # SID: 61610
    },
    [1, null, "three"]
  ])
}

Examples from Section 5.2.4 of [RFC7952]
name | SID
example-last-modified:last-modified | 61610
bibliomod:folio | 61630
Bibliomod:folio example

{
  630: [                                  # SID: 61630
    6,                 # SIDs below: -20 -> 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 [RFC7952] and [RFC9254] apply.
IANA Considerations
CBOR Tags Registry
In the registry "CBOR Tags" [IANA.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
[RFC7952]

Defining and Using Metadata with YANG
L. Lhotka
August 2016
RFC 7952
DOI 10.17487/RFC7952
[RFC9254]

Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR)
M. Veillette, Ed.
I. Petrov, Ed.
A. Pelov
C. Bormann
M. Richardson
July 2022
RFC 9254
DOI 10.17487/RFC9254
[RFC8949]

Concise Binary Object Representation (CBOR)
C. Bormann
P. Hoffman
December 2020
STD 94
RFC 8949
DOI 10.17487/RFC8949
[IANA.cbor-tags]

Concise Binary Object Representation (CBOR) Tags
IANA
[RFC8610]

Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures
H. Birkholz
C. Vigano
C. Bormann
June 2019
RFC 8610
DOI 10.17487/RFC8610
[RFC9165]

Additional Control Operators for the Concise Data Definition Language (CDDL)
C. Bormann
December 2021
RFC 9165
DOI 10.17487/RFC9165
[I-D.ietf-cbor-update-8610-grammar]

Updates to the CDDL grammar of RFC 8610
Carsten Bormann
Universität Bremen TZI
2 March 2024
Internet-Draft draft-ietf-cbor-update-8610-grammar-04
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
Informative References
[I-D.ietf-cbor-edn-literals]

CBOR Extended Diagnostic Notation (EDN): Application-Oriented Literals, ABNF, and Media Type
Carsten Bormann
Universität Bremen TZI
1 February 2024
Internet-Draft draft-ietf-cbor-edn-literals-08
Acknowledgments
Andy Bierman brought up the need for this document.