YANG Data Structure Extensions
Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8791 YumaWorks
Updates: 8340 M. Bjorklund
Category: Standards Track Cisco
ISSN: 2070-1721 K. Watsen
YANG Data Structure Extensions
This document describes YANG mechanisms for defining abstract data
structures with YANG.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
Copyright (c) 2020 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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
3. YANG Data Structures in YANG Tree Diagrams
4. YANG Data Structure Extensions Module
5. IANA Considerations
5.1. YANG Module Registry
6. Security Considerations
7.1. Normative References
7.2. Informative References
Appendix A. Examples
A.1. "structure" Example
A.2. "augment-structure" Example
A.3. XML Encoding Example
A.4. JSON Encoding Example
A.5. "structure" Example That Defines a Non-top-level Structure
There is a need for standard mechanisms to allow the definition of
abstract data that is not intended to be implemented as configuration
or operational state. The "yang-data" extension statement from RFC
8040 [RFC8040] was defined for this purpose, but it is limited in its
The intended use of the "yang-data" extension was to model all or
part of a protocol message, such as the "errors" definition in the
YANG module "ietf-restconf" [RFC8040], or the contents of a file.
However, protocols are often layered such that the header or payload
portions of the message can be extended by external documents. The
YANG statements that model a protocol need to support this
extensibility that is already found in that protocol.
This document defines a new YANG extension statement called
"structure", which is similar to but more flexible than the "yang-
data" extension from [RFC8040]. There is no assumption that a YANG
data structure can only be used as a top-level abstraction, and it
may also be nested within some other data structure.
This document also defines a new YANG extension statement called
"augment-structure", which allows abstract data structures to be
augmented from external modules and is similar to the existing YANG
"augment" statement. Note that "augment" cannot be used to augment a
YANG data structure since a YANG compiler or other tool is not
required to understand the "structure" extension.
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.
The following term is used within this document:
YANG data structure: A data structure defined with the "structure"
The following terms are defined in the Network Management Datastore
Architecture (NMDA) [RFC8342] and are not redefined here:
* operational state
The following terms are defined in [RFC7950] and are not redefined
* data definition statement
* data node
Show full document text