RFC 7950
The YANG 1.1 Data Modeling Language
Internet Engineering Task Force (IETF) M. Bjorklund, Ed. Request for Comments: 7950 Tail-f Systems Category: Standards Track August 2016 ISSN: 2070-1721 The YANG 1.1 Data Modeling LanguageAbstract
YANG 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). 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 http://www.rfc-editor.org/info/rfc7950.
Copyright Notice Copyright (c) 2016 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 (http://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. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
Table of Contents
1. Introduction ....................................................9 1.1. Summary of Changes from RFC 6020 ..........................10 2. Key Words ......................................................12 3. Terminology ....................................................12 3.1. A Note on Examples ........................................16 4. YANG Overview ..................................................16 4.1. Functional Overview .......................................16 4.2. Language Overview .........................................18 4.2.1. Modules and Submodules .............................18 4.2.2. Data Modeling Basics ...............................19 4.2.3. Configuration and State Data .......................23 4.2.4. Built-In Types .....................................24 4.2.5. Derived Types (typedef) ............................25 4.2.6. Reusable Node Groups (grouping) ....................25 4.2.7. Choices ............................................27 4.2.8. Extending Data Models (augment) ....................28 4.2.9. Operation Definitions ..............................29 4.2.10. Notification Definitions ..........................31 5. Language Concepts ..............................................32 5.1. Modules and Submodules ....................................32 5.1.1. Import and Include by Revision .....................33 5.1.2. Module Hierarchies .................................34 5.2. File Layout ...............................................36 5.3. XML Namespaces ............................................36 5.3.1. YANG XML Namespace .................................36 5.4. Resolving Grouping, Type, and Identity Names ..............37 5.5. Nested Typedefs and Groupings .............................37 5.6. Conformance ...............................................38 5.6.1. Basic Behavior .....................................38 5.6.2. Optional Features ..................................38 5.6.3. Deviations .........................................39 5.6.4. Announcing Conformance Information in NETCONF ......40 5.6.5. Implementing a Module ..............................40 5.7. Datastore Modification ....................................44 6. YANG Syntax ....................................................44 6.1. Lexical Tokenization ......................................45 6.1.1. Comments ...........................................45 6.1.2. Tokens .............................................45 6.1.3. Quoting ............................................45 6.2. Identifiers ...............................................47 6.2.1. Identifiers and Their Namespaces ...................47 6.3. Statements ................................................48 6.3.1. Language Extensions ................................48 6.4. XPath Evaluations .........................................49 6.4.1. XPath Context ......................................50 6.5. Schema Node Identifier ....................................54
7. YANG Statements ................................................55 7.1. The "module" Statement ....................................55 7.1.1. The module's Substatements .........................56 7.1.2. The "yang-version" Statement .......................57 7.1.3. The "namespace" Statement ..........................57 7.1.4. The "prefix" Statement .............................57 7.1.5. The "import" Statement .............................58 7.1.6. The "include" Statement ............................59 7.1.7. The "organization" Statement .......................60 7.1.8. The "contact" Statement ............................60 7.1.9. The "revision" Statement ...........................60 7.1.10. Usage Example .....................................61 7.2. The "submodule" Statement .................................62 7.2.1. The submodule's Substatements ......................63 7.2.2. The "belongs-to" Statement .........................63 7.2.3. Usage Example ......................................64 7.3. The "typedef" Statement ...................................65 7.3.1. The typedef's Substatements ........................65 7.3.2. The typedef's "type" Statement .....................65 7.3.3. The "units" Statement ..............................65 7.3.4. The typedef's "default" Statement ..................66 7.3.5. Usage Example ......................................66 7.4. The "type" Statement ......................................66 7.4.1. The type's Substatements ...........................67 7.5. The "container" Statement .................................67 7.5.1. Containers with Presence ...........................67 7.5.2. The container's Substatements ......................68 7.5.3. The "must" Statement ...............................69 7.5.4. The must's Substatements ...........................70 7.5.5. The "presence" Statement ...........................71 7.5.6. The container's Child Node Statements ..............71 7.5.7. XML Encoding Rules .................................71 7.5.8. NETCONF <edit-config> Operations ...................72 7.5.9. Usage Example ......................................72 7.6. The "leaf" Statement ......................................73 7.6.1. The leaf's Default Value ...........................74 7.6.2. The leaf's Substatements ...........................75 7.6.3. The leaf's "type" Statement ........................75 7.6.4. The leaf's "default" Statement .....................75 7.6.5. The leaf's "mandatory" Statement ...................76 7.6.6. XML Encoding Rules .................................76 7.6.7. NETCONF <edit-config> Operations ...................76 7.6.8. Usage Example ......................................77 7.7. The "leaf-list" Statement .................................77 7.7.1. Ordering ...........................................78 7.7.2. The leaf-list's Default Values .....................79 7.7.3. The leaf-list's Substatements ......................80 7.7.4. The leaf-list's "default" Statement ................80
7.7.5. The "min-elements" Statement .......................80
7.7.6. The "max-elements" Statement .......................81
7.7.7. The "ordered-by" Statement .........................81
7.7.8. XML Encoding Rules .................................82
7.7.9. NETCONF <edit-config> Operations ...................82
7.7.10. Usage Example .....................................83
7.8. The "list" Statement ......................................84
7.8.1. The list's Substatements ...........................85
7.8.2. The list's "key" Statement .........................85
7.8.3. The list's "unique" Statement ......................86
7.8.4. The list's Child Node Statements ...................87
7.8.5. XML Encoding Rules .................................88
7.8.6. NETCONF <edit-config> Operations ...................88
7.8.7. Usage Example ......................................90
7.9. The "choice" Statement ....................................93
7.9.1. The choice's Substatements .........................94
7.9.2. The choice's "case" Statement ......................94
7.9.3. The choice's "default" Statement ...................96
7.9.4. The choice's "mandatory" Statement .................98
7.9.5. XML Encoding Rules .................................98
7.9.6. Usage Example ......................................99
7.10. The "anydata" Statement .................................100
7.10.1. The anydata's Substatements ......................100
7.10.2. XML Encoding Rules ...............................101
7.10.3. NETCONF <edit-config> Operations .................101
7.10.4. Usage Example ....................................101
7.11. The "anyxml" Statement ..................................102
7.11.1. The anyxml's Substatements .......................103
7.11.2. XML Encoding Rules ...............................103
7.11.3. NETCONF <edit-config> Operations .................103
7.11.4. Usage Example ....................................104
7.12. The "grouping" Statement ................................104
7.12.1. The grouping's Substatements .....................105
7.12.2. Usage Example ....................................105
7.13. The "uses" Statement ....................................106
7.13.1. The uses's Substatements .........................106
7.13.2. The "refine" Statement ...........................106
7.13.3. XML Encoding Rules ...............................107
7.13.4. Usage Example ....................................107
7.14. The "rpc" Statement .....................................108
7.14.1. The rpc's Substatements ..........................109
7.14.2. The "input" Statement ............................109
7.14.3. The "output" Statement ...........................110
7.14.4. NETCONF XML Encoding Rules .......................111
7.14.5. Usage Example ....................................112
7.15. The "action" Statement ..................................113
7.15.1. The action's Substatements .......................114
7.15.2. NETCONF XML Encoding Rules .......................114
7.15.3. Usage Example ....................................115
7.16. The "notification" Statement ............................116
7.16.1. The notification's Substatements .................117
7.16.2. NETCONF XML Encoding Rules .......................117
7.16.3. Usage Example ....................................118
7.17. The "augment" Statement .................................119
7.17.1. The augment's Substatements ......................121
7.17.2. XML Encoding Rules ...............................121
7.17.3. Usage Example ....................................122
7.18. The "identity" Statement ................................124
7.18.1. The identity's Substatements .....................124
7.18.2. The "base" Statement .............................124
7.18.3. Usage Example ....................................125
7.19. The "extension" Statement ...............................126
7.19.1. The extension's Substatements ....................126
7.19.2. The "argument" Statement .........................127
7.19.3. Usage Example ....................................127
7.20. Conformance-Related Statements ..........................128
7.20.1. The "feature" Statement ..........................128
7.20.2. The "if-feature" Statement .......................130
7.20.3. The "deviation" Statement ........................131
7.21. Common Statements .......................................134
7.21.1. The "config" Statement ...........................134
7.21.2. The "status" Statement ...........................135
7.21.3. The "description" Statement ......................136
7.21.4. The "reference" Statement ........................136
7.21.5. The "when" Statement .............................136
8. Constraints ...................................................138
8.1. Constraints on Data ......................................138
8.2. Configuration Data Modifications .........................139
8.3. NETCONF Constraint Enforcement Model .....................139
8.3.1. Payload Parsing ...................................139
8.3.2. NETCONF <edit-config> Processing ..................140
8.3.3. Validation ........................................141
9. Built-In Types ................................................141
9.1. Canonical Representation .................................141
9.2. The Integer Built-In Types ...............................142
9.2.1. Lexical Representation ............................142
9.2.2. Canonical Form ....................................143
9.2.3. Restrictions ......................................143
9.2.4. The "range" Statement .............................143
9.2.5. Usage Example .....................................144
9.3. The decimal64 Built-In Type ..............................144
9.3.1. Lexical Representation ............................145
9.3.2. Canonical Form ....................................145
9.3.3. Restrictions ......................................145
9.3.4. The "fraction-digits" Statement ...................145
9.3.5. Usage Example .....................................146
9.4. The string Built-In Type .................................146
9.4.1. Lexical Representation ............................146
9.4.2. Canonical Form ....................................147
9.4.3. Restrictions ......................................147
9.4.4. The "length" Statement ............................147
9.4.5. The "pattern" Statement ...........................148
9.4.6. The "modifier" Statement ..........................148
9.4.7. Usage Example .....................................149
9.5. The boolean Built-In Type ................................150
9.5.1. Lexical Representation ............................150
9.5.2. Canonical Form ....................................150
9.5.3. Restrictions ......................................150
9.6. The enumeration Built-In Type ............................150
9.6.1. Lexical Representation ............................150
9.6.2. Canonical Form ....................................151
9.6.3. Restrictions ......................................151
9.6.4. The "enum" Statement ..............................151
9.6.5. Usage Example .....................................152
9.7. The bits Built-In Type ...................................154
9.7.1. Restrictions ......................................154
9.7.2. Lexical Representation ............................154
9.7.3. Canonical Form ....................................154
9.7.4. The "bit" Statement ...............................155
9.7.5. Usage Example .....................................156
9.8. The binary Built-In Type .................................157
9.8.1. Restrictions ......................................157
9.8.2. Lexical Representation ............................157
9.8.3. Canonical Form ....................................157
9.9. The leafref Built-In Type ................................157
9.9.1. Restrictions ......................................158
9.9.2. The "path" Statement ..............................158
9.9.3. The "require-instance" Statement ..................159
9.9.4. Lexical Representation ............................159
9.9.5. Canonical Form ....................................159
9.9.6. Usage Example .....................................159
9.10. The identityref Built-In Type ...........................163
9.10.1. Restrictions .....................................163
9.10.2. The identityref's "base" Statement ...............163
9.10.3. Lexical Representation ...........................163
9.10.4. Canonical Form ...................................164
9.10.5. Usage Example ....................................164
9.11. The empty Built-In Type .................................165
9.11.1. Restrictions .....................................165
9.11.2. Lexical Representation ...........................165
9.11.3. Canonical Form ...................................165
9.11.4. Usage Example ....................................166
9.12. The union Built-In Type .................................166
9.12.1. Restrictions .....................................166
9.12.2. Lexical Representation ...........................166
9.12.3. Canonical Form ...................................167
9.12.4. Usage Example ....................................167
9.13. The instance-identifier Built-In Type ...................168
9.13.1. Restrictions .....................................168
9.13.2. Lexical Representation ...........................169
9.13.3. Canonical Form ...................................169
9.13.4. Usage Example ....................................169
10. XPath Functions ..............................................170
10.1. Function for Node Sets ..................................170
10.1.1. current() ........................................170
10.2. Function for Strings ....................................170
10.2.1. re-match() .......................................170
10.3. Function for the YANG Types "leafref" and
"instance-identifier" ...................................171
10.3.1. deref() ..........................................171
10.4. Functions for the YANG Type "identityref" ...............172
10.4.1. derived-from() ...................................172
10.4.2. derived-from-or-self() ...........................174
10.5. Function for the YANG Type "enumeration" ................174
10.5.1. enum-value() .....................................174
10.6. Function for the YANG Type "bits" .......................175
10.6.1. bit-is-set() .....................................175
11. Updating a Module ............................................176
12. Coexistence with YANG Version 1 ..............................179
13. YIN ..........................................................179
13.1. Formal YIN Definition ...................................180
13.1.1. Usage Example ....................................182
14. YANG ABNF Grammar ............................................184
15. NETCONF Error Responses for YANG-Related Errors ..............211
15.1. Error Message for Data That Violates a "unique"
Statement ...............................................211
15.2. Error Message for Data That Violates a
"max-elements" Statement ................................211
15.3. Error Message for Data That Violates a
"min-elements" Statement ................................211
15.4. Error Message for Data That Violates a "must"
Statement ...............................................212
15.5. Error Message for Data That Violates a
"require-instance" Statement ............................212
15.6. Error Message for Data That Violates a Mandatory
"choice" Statement ......................................212
15.7. Error Message for the "insert" Operation ................212
16. IANA Considerations ..........................................213
17. Security Considerations ......................................213
18. References ...................................................214
18.1. Normative References ....................................214
18.2. Informative References ..................................215
Acknowledgements .................................................217
Contributors .....................................................217
Author's Address .................................................217
1. Introduction
YANG is a data modeling language originally designed to model
configuration and state data manipulated by the Network Configuration
Protocol (NETCONF), NETCONF Remote Procedure Calls, and NETCONF
notifications [RFC6241]. Since the publication of YANG version 1
[RFC6020], YANG has been used or proposed to be used for other
protocols (e.g., RESTCONF [RESTCONF] and the Constrained Application
Protocol (CoAP) Management Interface (CoMI) [CoMI]). Further,
encodings other than XML have been proposed (e.g., JSON [RFC7951]).
This document describes the syntax and semantics of version 1.1 of
the YANG language. It also describes how a data model defined in a
YANG module is encoded in the Extensible Markup Language (XML) [XML]
and how NETCONF operations are used to manipulate the data. Other
protocols and encodings are possible but are out of scope for this
specification.
In terms of developing YANG data models, [YANG-Guidelines] provides
some guidelines and recommendations.
Note that this document does not obsolete RFC 6020 [RFC6020].
1.1. Summary of Changes from RFC 6020
This document defines 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 [RFC6020]. The following changes are not backward compatible with YANG version 1: o Changed the rules for the interpretation of escaped characters in double-quoted strings. This is a backward-incompatible change from YANG version 1. When updating a YANG version 1 module to 1.1 and the module uses a character sequence that is now illegal, the string must be changed to match the new rules. See Section 6.1.3 for details. o An unquoted string cannot contain any single or double quote characters. This is a backward-incompatible change from YANG version 1. When updating a YANG version 1 module to 1.1 and the module uses such quote characters, the string must be changed to match the new rules. See Section 6.1.3 for details. o Made "when" and "if-feature" illegal on list keys. This is a backward-incompatible change from YANG version 1. When updating a YANG version 1 module to 1.1 and the module uses these constructs, they must be removed to match the new rules. o Defined the legal characters in YANG modules. When updating a YANG version 1 module to 1.1, any characters that are now illegal must be removed. See Section 6 for details. o Made noncharacters illegal in the built-in type "string". This change affects the runtime behavior of YANG-based protocols. The following additional changes have been done to YANG: o Changed the YANG version from "1" to "1.1". o Made the "yang-version" statement mandatory in YANG version "1.1". o Extended the "if-feature" syntax to be a boolean expression over feature names. o Allow "if-feature" in "bit", "enum", and "identity". o Allow "if-feature" in "refine".
o Allow "choice" as a shorthand "case" statement (see
Section 7.9.2).
o Added a new substatement "modifier" to the "pattern" statement
(see Section 9.4.6).
o Allow "must" in "input", "output", and "notification".
o Allow "require-instance" in leafref.
o Allow "description" and "reference" in "import" and "include".
o Allow imports of multiple revisions of a module.
o Allow "augment" to add conditionally mandatory nodes (see
Section 7.17).
o Added a set of new XML Path Language (XPath) functions in
Section 10.
o Clarified the XPath context's tree in Section 6.4.1.
o Defined the string value of an identityref in XPath expressions
(see Section 9.10).
o Clarified what unprefixed names mean in leafrefs in typedefs (see
Sections 6.4.1 and 9.9.2).
o Allow identities to be derived from multiple base identities (see
Sections 7.18 and 9.10).
o Allow enumerations and bits to be subtyped (see Sections 9.6
and 9.7).
o Allow leaf-lists to have default values (see Section 7.7.2).
o Allow non-unique values in non-configuration leaf-lists (see
Section 7.7).
o Use syntax for case-sensitive strings (as per [RFC7405]) in the
grammar.
o Changed the module advertisement mechanism (see Section 5.6.4).
o Changed the scoping rules for definitions in submodules. A
submodule can now reference all definitions in all submodules that
belong to the same module, without using the "include" statement.
o Added a new statement "action", which is used to define operations
tied to data nodes.
o Allow notifications to be tied to data nodes.
o Added a new data definition statement "anydata" (see
Section 7.10), which is RECOMMENDED to be used instead of "anyxml"
when the data can be modeled in YANG.
o Allow types "empty" and "leafref" in unions.
o Allow type "empty" in a key.
o Removed the restriction that identifiers could not start with the
characters "xml".
The following changes have been done to the NETCONF mapping:
o A server advertises support for YANG 1.1 modules by using
ietf-yang-library [RFC7895] instead of listing them as
capabilities in the <hello> message.
2. Key Words
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].
3. Terminology
The following terms are used within this document:
o action: An operation defined for a node in the data tree.
o anydata: A data node that can contain an unknown set of nodes that
can be modeled by YANG, except anyxml.
o anyxml: A data node that can contain an unknown chunk of XML data.
o augment: Adds new schema nodes to a previously defined schema
node.
o base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type.
o built-in type: A YANG data type defined in the YANG language, such
as uint32 or string.
o choice: A schema node where only one of a number of identified
alternatives is valid.
o client: An entity that can access YANG-defined data on a server,
over some network management protocol.
o conformance: A measure of how accurately a server follows a data
model.
o container: An interior data node that exists in at most one
instance in the data tree. A container has no value, but rather a
set of child nodes.
o data definition statement: A statement that defines new data
nodes. One of "container", "leaf", "leaf-list", "list", "choice",
"case", "augment", "uses", "anydata", and "anyxml".
o data model: A data model describes how data is represented and
accessed.
o data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, list, anydata, and
anyxml.
o data tree: An instantiated tree of any data modeled with YANG,
e.g., configuration data, state data, combined configuration and
state data, RPC or action input, RPC or action output, or
notification.
o derived type: A type that is derived from a built-in type (such as
uint32) or another derived type.
o extension: An extension attaches non-YANG semantics to statements.
The "extension" statement defines new statements to express these
semantics.
o feature: A mechanism for marking a portion of the model as
optional. Definitions can be tagged with a feature name and are
only valid on servers that support that feature.
o grouping: A reusable set of schema nodes, which may be used
locally in the module and by other modules that import from it.
The "grouping" statement is not a data definition statement and,
as such, does not define any nodes in the schema tree.
o identifier: A string used to identify different kinds of YANG
items by name.
o identity: A globally unique, abstract, and untyped name.
o instance identifier: A mechanism for identifying a particular node
in a data tree.
o interior node: Nodes within a hierarchy that are not leaf nodes.
o leaf: A data node that exists in at most one instance in the data
tree. A leaf has a value but no child nodes.
o leaf-list: Like the leaf node but defines a set of uniquely
identifiable nodes rather than a single node. Each node has a
value but no child nodes.
o list: An interior data node that may exist in multiple instances
in the data tree. A list has no value, but rather a set of child
nodes.
o mandatory node: A mandatory node is one of:
* A leaf, choice, anydata, or anyxml node with a "mandatory"
statement with the value "true".
* A list or leaf-list node with a "min-elements" statement with a
value greater than zero.
* A container node without a "presence" statement and that has at
least one mandatory node as a child.
o module: A YANG module defines hierarchies of schema nodes. With
its definitions and the definitions it imports or includes from
elsewhere, a module is self-contained and "compilable".
o non-presence container: A container that has no meaning of its
own, existing only to contain child nodes.
o presence container: A container where the presence of the
container itself carries some meaning.
o RPC: A Remote Procedure Call.
o RPC operation: A specific Remote Procedure Call.
o schema node: A node in the schema tree. One of action, container,
leaf, leaf-list, list, choice, case, rpc, input, output,
notification, anydata, and anyxml.
o schema node identifier: A mechanism for identifying a particular
node in the schema tree.
o schema tree: The definition hierarchy specified within a module.
o server: An entity that provides access to YANG-defined data to a
client, over some network management protocol.
o server deviation: A failure of the server to implement a module
faithfully.
o submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, actions, and notifications to
a module. A YANG module can be constructed from a number of
submodules.
o top-level data node: A data node where there is no other data node
between it and a "module" or "submodule" statement.
o uses: The "uses" statement is used to instantiate the set of
schema nodes defined in a "grouping" statement. The instantiated
nodes may be refined and augmented to tailor them to any specific
needs.
o value space: For a data type; the set of values permitted by the
data type. For a leaf or leaf-list instance; the value space of
its data type.
The following terms are defined in [RFC6241]:
o configuration data
o configuration datastore
o datastore
o state data
When modeled with YANG, a datastore is realized as an instantiated
data tree.
When modeled with YANG, a configuration datastore is realized as an
instantiated data tree with configuration data.
3.1. A Note on Examples
Throughout this document, there are many examples of YANG statements. These examples are supposed to illustrate certain features and are not supposed to be complete, valid YANG modules.
(page 16 continued on part 2)
