YANG Data Structure Extensions
RFC 8791

Document Type RFC - Proposed Standard (June 2020; No errata)
Updates RFC 8340
Last updated 2020-06-17
Replaces draft-bierman-netmod-yang-data-ext
Stream IETF
Formats plain text html xml pdf htmlized bibtex
Yang Validation 0 errors, 0 warnings.
Reviews
Additional URLs
- Yang catalog entry for ietf-yang-structure-ext@2019-03-07.yang
- Yang impact analysis for draft-ietf-netmod-yang-data-ext
- Mailing list discussion
Stream WG state Submitted to IESG for Publication
Document shepherd Joel Jaeggli
Shepherd write-up Show (last changed 2019-10-12)
IESG IESG state RFC 8791 (Proposed Standard)
Consensus Boilerplate Yes
Telechat date
Responsible AD Alissa Cooper
Send notices to Joel Jaeggli <joelja@gmail.com>
IANA IANA review state IANA OK - Actions Needed
IANA action state RFC-Ed-Ack
IANA expert review state Expert Reviews OK


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
                                                         Watsen Networks
                                                               June 2020

                     YANG Data Structure Extensions

Abstract

   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
   https://www.rfc-editor.org/info/rfc8791.

Copyright Notice

   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

   1.  Introduction
     1.1.  Terminology
       1.1.1.  NMDA
       1.1.2.  YANG
   2.  Definitions
   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.  References
     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
   Authors' Addresses

1.  Introduction

   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
   functionality.

   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.

1.1.  Terminology

   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"
      statement.

1.1.1.  NMDA

   The following terms are defined in the Network Management Datastore
   Architecture (NMDA) [RFC8342] and are not redefined here:

   *  configuration

   *  operational state

1.1.2.  YANG

   The following terms are defined in [RFC7950] and are not redefined
   here:

   *  absolute-schema-nodeid

   *  container

   *  data definition statement

   *  data node

   *  leaf

   *  leaf-list
Show full document text