YANG Data Structure Extensions
updates
- rfc-8340 — YANG Tree Diagrams
Extracted elements (15)
The standard YANG 'augment' statement cannot be used to augment a YANG data structure defined with 'structure' because a YANG compiler or other tool is not required to understand the 'structure' extension. The new 'augment-structure' statement was introduced to handle this case explicitly.
The 'yang-data' extension from RFC 8040 was limited in functionality: it assumed top-level use only and did not support augmentation from external modules. RFC 8791 replaces it with the more flexible 'structure' and 'augment-structure' extensions to address these gaps.
YANG data structures share the same identifier namespace as defined in RFC 7950 Section 6.2.1, meaning a 'structure'-defined structure cannot share a name with sibling nodes from regular YANG data definition statements or other 'structure' statements in the same module.
Within a 'structure' or 'augment-structure' extension statement, the list-stmt is not required to have a key-stmt defined, and the config-stmt is ignored if present. These are constrained behaviors that differ from standard YANG list and config semantics.
A specification using the 'structure' extension MUST specify the message encoding rules, including the content media type if applicable, since the extension itself does not define a media type.
The substatements of the 'augment-structure' extension MUST follow the ABNF rules: [status-stmt], [description-stmt], [reference-stmt], 1*(data-def-stmt / case-stmt).
The substatements of the 'structure' extension MUST follow the ABNF rules: *must-stmt, [status-stmt], [description-stmt], [reference-stmt], *(typedef-stmt / grouping-stmt), *data-def-stmt.
The 'augment-structure' context node is derived in the same way as the standard 'augment' statement (RFC 7950 Section 6.4.1), and that conceptual node is the context for must-stmt, when-stmt, path-stmt, min/max-elements-stmt, mandatory-stmt, unique-stmt, ordered-by, and instance-identifier data type.
The 'augment-structure' extension statement allows augmentation of YANG data structures defined with 'structure' from external modules. Its mandatory 'path' argument is an absolute-schema-nodeid where the first node identifies the target structure and subsequent nodes identify the node within that structure.
The 'structure' extension statement defines a named YANG data structure representing conceptual data independent of protocol context or encoding format. It is only valid as a top-level statement (substatement to 'module' or 'submodule') and its argument is the name of the data structure.
The XPath document element for a 'structure' extension statement is the extension statement itself, such that child nodes of the document element are the data-def-stmt substatements. This conceptual document is the context for must-stmt, when-stmt, path-stmt, min/max-elements-stmt, mandatory-stmt, unique-stmt, ordered-by, and instance-identifier data type.
YANG tree diagrams are updated (RFC 8340) to include two new sections: 'structure <name>:' sections offset by two spaces for YANG data structures, and 'augment-structure <name>:' sections for data structure augmentations. Nodes in these sections have no flags.
IANA registered the URI 'urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext' in the 'ns' subregistry of the IETF XML Registry, and registered the module 'ietf-yang-structure-ext' (prefix: sx) in the YANG Module Names subregistry of the YANG Parameters registry.
This document defines YANG extensions for conceptual data structures and does not introduce any new vulnerabilities beyond those specified in YANG 1.1 (RFC 7950). No additional security considerations apply.
A YANG data structure is encoded in the same way as an 'anydata' node: the structure name is encoded as a 'container', with instantiated children encoded as child nodes. For example, a structure named 'my-error' encodes in JSON as 'example-errors:my-error': { ... }.