Internet-Draft | yang-extensions | September 2024 |
Richardson | Expires 31 March 2025 | [Page] |
This document describes a mechanism of signaling extensions to YANG modules that can be used when YANG is not used in an online fashion.¶
This note is to be removed before publishing as an RFC.¶
Status information for this document may be found at https://datatracker.ietf.org/doc/draft-richardson-netmod-atrest-extensions/.¶
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/mcr/yang-extensions-at-reset.¶
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 31 March 2025.¶
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.¶
In the process of revising [RFC8366] to accomodate needed extensions an effort was initially made to do this using augment (cite) and later augment-structure. [RFC8366] is a digitally signed voucher format used in onboarding of new devices. It is a file format that may be transmitted over CoAP, HTTP or via USB key, but it does not use RESTCONF. The contents of the file are not subject to negotiation as might be done with [RFC8528].¶
Rather than have each topic document define the relevant extensions needed, it turned out to be necessary to collect all the extensions necessary into a single revision to the YANG module, which is being produced as [I-D.ietf-anima-rfc8366bis].¶
[RFC8520] is like [RFC8366]: it is a file format. When [RFC8520] was defined, it anticipated that there would be future extensions, and defined a YANG leaf called "extensions" which is a list of subsequent YANG modules which are included. This is being used to define, for instance, [I-D.ietf-opsawg-ol].¶
When YANG is serialized to XML or JSON, the keys used in the attribute map are strings, and so it seems relatively straightforward for a human programmer to understand how to insert these new keys into the same attribute map. YANG however, is intended to be machine parseable, and [RFC9254] provides a way to serialize YANG to CBOR. While strings can be used if necessary, the preferred method is via YANG-SID values, allocated for instance, via [RFC9595]. It is not obvious how an extension mechanism as described by [RFC8520] can be efficiently encoded to CBOR, nor how YANG tooling should react to these ad-hoc extensions.¶
This document makes the [RFC8520] extension mechanism a generic mechanism that can be used by any YANG module, and explains how to efficiently encode this to CBOR using YANG-SID.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
XXX - Do we need more details about the motivation?¶
A YANG module that expects to have extensions establishes an attribute called "extensions" This attribute value is a list of extensions that are included in this object. This set of available values is established as an IANA registry by the document defining the module.¶
(XXX- this assumes per-module extensions, vs a global set of extensions that could be used by many modules)¶
When encoding YANG as CBOR, in order to encode the additional attributes defined by that extension, a new sub-map is created. The key for this sub-map, in the parent map, consists of the YANG module SID, encoded using the CBOR Tag 47, the tag for an absolute SID. Within the sub-map, the normal delta-encoding is used, using the SID values allocated for that module.¶
(XXX- the submap should allow to XML and JSON too?)¶
Hello.¶