YANG Data Structure ExtensionsYumaWorksandy@yumaworks.comCiscombj@tail-f.comWatsen Networkskent+ietf@watsen.net
This document describes YANG mechanisms for
defining abstract data structures with YANG.
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
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" , 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 . 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, similarly 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 when, and only when, they appear in all
capitals, as shown here.
The following terms are used within this document:
YANG data structure: A data structure defined with the "structure"
statement.
The following terms are defined in the
Network Management Datastore Architecture
(NMDA) ,
and are not redefined here:
configuration
operational state
The following terms are defined in :
absolute-schema-nodeid
container
data definition statement
data node
leaf
leaf-list
list
A YANG data structure is defined with the "structure" extension
statement, defined in the YANG module "ietf‑yang‑structure‑ext". The
argument to the "structure" extension statement is the name of the
data structure. The data structures are considered to be in the same
identifier namespace as defined in section 6.2.1 of . In
particular, bullet 7:
This means that data structures defined with the "structure" statement
cannot have the same name as sibling nodes from regular YANG data
definition statements or other "structure" statements in the same YANG
module.
This does not mean a YANG data structure, once defined, has to be used
as a top-level protocol message or other top-level data structure.
A YANG data structure is encoded in the same way as an "anydata" node.
This means that the name of the structure is encoded as a "container",
with the instantiated children encoded as child nodes to this
node. For example, this structure:
can be encoded in JSON as:
A YANG data structure can be printed in a YANG Tree Diagram .
This document updates RFC 8340 by defining two new sections in the
tree diagram for a module:
YANG data structures, offset by two spaces and identified by the keyword
"structure" followed by the name
of the YANG data structure and a colon (":") character.
YANG data structure augmentations, offset by 2 spaces and identified
by the keyword "augment‑structure" followed by the augment target
structure name and a colon (":") character.
The new sections, including spaces conventions is:
Nodes in YANG data structures are printed according to the rules
defined in section 2.6 in .
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-yang-structure-ext@2019-03-07.yang"<CODE ENDS>
This document registers one URI as a namespace in the
"IETF XML Registry" :
This document registers one YANG module in the "YANG Module Names"
registry :
This document defines YANG extensions that are used to define
conceptual YANG data structures. It does not introduce any new
vulnerabilities beyond those specified in YANG 1.1 .
Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.The YANG 1.1 Data Modeling LanguageYANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF).RESTCONF ProtocolThis document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.YANG Tree DiagramsThis document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language.Network Management Datastore Architecture (NMDA)Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950.The IETF XML RegistryThis document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas.YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]
This example shows a simple address book that could be stored as an
artifact.
Below is the tree diagram of this module.
This example adds "county" and "zipcode" leafs to the address book:
Below is the tree diagram of this module.
This example shows how an address book can be encoded in XML:
This example shows how an address book can be encoded in JSON:
The following example defines a data structure with error information,
that can be included in an <error‑info> element in an <rpc‑error>.
The example below shows how this structure can be used in an
<rpc‑error>.