Representing metadata annotations in YANG-CBOR

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 20 October 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

This specification defines the representation of metadata annotations [RFC7952] in YANG-CBOR [RFC9254].¶

2. 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:¶

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!)?¶

3. 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:¶

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

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

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

{
   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
       ...: ...
     }
   ]
}

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

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

{
  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,
  ]
}

4. Security Considerations

The security considerations of [RFC7952] and [RFC9254] apply.¶

5. IANA Considerations

Acknowledgments

Andy Bierman brought up the need for this document.¶

Author's Address