RFC 6020
YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
Internet Engineering Task Force (IETF) M. Bjorklund, Ed. Request for Comments: 6020 Tail-f Systems Category: Standards Track October 2010 ISSN: 2070-1721 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)Abstract
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. 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 5741. 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/rfc6020. Copyright Notice Copyright (c) 2010 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 ....................................................8 2. Keywords ........................................................8 3. Terminology .....................................................8 3.1. Mandatory Nodes ...........................................10 4. YANG Overview ..................................................11 4.1. Functional Overview .......................................11 4.2. Language Overview .........................................13 4.2.1. Modules and Submodules .............................13 4.2.2. Data Modeling Basics ...............................13 4.2.3. State Data .........................................18 4.2.4. Built-In Types .....................................18 4.2.5. Derived Types (typedef) ............................19 4.2.6. Reusable Node Groups (grouping) ....................20 4.2.7. Choices ............................................21 4.2.8. Extending Data Models (augment) ....................22 4.2.9. RPC Definitions ....................................23 4.2.10. Notification Definitions ..........................24 5. Language Concepts ..............................................25 5.1. Modules and Submodules ....................................25 5.1.1. Import and Include by Revision .....................26 5.1.2. Module Hierarchies .................................27 5.2. File Layout ...............................................28 5.3. XML Namespaces ............................................29 5.3.1. YANG XML Namespace .................................29 5.4. Resolving Grouping, Type, and Identity Names ..............29 5.5. Nested Typedefs and Groupings .............................29 5.6. Conformance ...............................................30 5.6.1. Basic Behavior .....................................31 5.6.2. Optional Features ..................................31 5.6.3. Deviations .........................................31 5.6.4. Announcing Conformance Information in the <hello> Message ....................................32 5.7. Data Store Modification ...................................34 6. YANG Syntax ....................................................34
6.1. Lexical Tokenization ......................................34
6.1.1. Comments ...........................................34
6.1.2. Tokens .............................................34
6.1.3. Quoting ............................................35
6.2. Identifiers ...............................................36
6.2.1. Identifiers and Their Namespaces ...................36
6.3. Statements ................................................37
6.3.1. Language Extensions ................................37
6.4. XPath Evaluations .........................................38
6.4.1. XPath Context ......................................38
6.5. Schema Node Identifier ....................................39
7. YANG Statements ................................................39
7.1. The module Statement ......................................39
7.1.1. The module's Substatements .........................41
7.1.2. The yang-version Statement .........................41
7.1.3. The namespace Statement ............................42
7.1.4. The prefix Statement ...............................42
7.1.5. The import Statement ...............................42
7.1.6. The include Statement ..............................43
7.1.7. The organization Statement .........................44
7.1.8. The contact Statement ..............................44
7.1.9. The revision Statement .............................44
7.1.10. Usage Example .....................................45
7.2. The submodule Statement ...................................46
7.2.1. The submodule's Substatements ......................48
7.2.2. The belongs-to Statement ...........................48
7.2.3. Usage Example ......................................49
7.3. The typedef Statement .....................................49
7.3.1. The typedef's Substatements ........................50
7.3.2. The typedef's type Statement .......................50
7.3.3. The units Statement ................................50
7.3.4. The typedef's default Statement ....................50
7.3.5. Usage Example ......................................51
7.4. The type Statement ........................................51
7.4.1. The type's Substatements ...........................51
7.5. The container Statement ...................................51
7.5.1. Containers with Presence ...........................52
7.5.2. The container's Substatements ......................53
7.5.3. The must Statement .................................53
7.5.4. The must's Substatements ...........................55
7.5.5. The presence Statement .............................56
7.5.6. The container's Child Node Statements ..............56
7.5.7. XML Mapping Rules ..................................56
7.5.8. NETCONF <edit-config> Operations ...................56
7.5.9. Usage Example ......................................57
7.6. The leaf Statement ........................................58
7.6.1. The leaf's default value ...........................58
7.6.2. The leaf's Substatements ...........................59
7.6.3. The leaf's type Statement ..........................59
7.6.4. The leaf's default Statement .......................59
7.6.5. The leaf's mandatory Statement .....................60
7.6.6. XML Mapping Rules ..................................60
7.6.7. NETCONF <edit-config> Operations ...................60
7.6.8. Usage Example ......................................61
7.7. The leaf-list Statement ...................................62
7.7.1. Ordering ...........................................62
7.7.2. The leaf-list's Substatements ......................63
7.7.3. The min-elements Statement .........................63
7.7.4. The max-elements Statement .........................63
7.7.5. The ordered-by Statement ...........................64
7.7.6. XML Mapping Rules ..................................64
7.7.7. NETCONF <edit-config> Operations ...................65
7.7.8. Usage Example ......................................66
7.8. The list Statement ........................................67
7.8.1. The list's Substatements ...........................68
7.8.2. The list's key Statement ...........................68
7.8.3. The list's unique Statement ........................69
7.8.4. The list's Child Node Statements ...................70
7.8.5. XML Mapping Rules ..................................70
7.8.6. NETCONF <edit-config> Operations ...................71
7.8.7. Usage Example ......................................72
7.9. The choice Statement ......................................75
7.9.1. The choice's Substatements .........................76
7.9.2. The choice's case Statement ........................76
7.9.3. The choice's default Statement .....................77
7.9.4. The choice's mandatory Statement ...................79
7.9.5. XML Mapping Rules ..................................79
7.9.6. NETCONF <edit-config> Operations ...................79
7.9.7. Usage Example ......................................79
7.10. The anyxml Statement .....................................80
7.10.1. The anyxml's Substatements ........................81
7.10.2. XML Mapping Rules .................................81
7.10.3. NETCONF <edit-config> Operations ..................81
7.10.4. Usage Example .....................................82
7.11. The grouping Statement ...................................82
7.11.1. The grouping's Substatements ......................83
7.11.2. Usage Example .....................................84
7.12. The uses Statement .......................................84
7.12.1. The uses's Substatements ..........................85
7.12.2. The refine Statement ..............................85
7.12.3. XML Mapping Rules .................................86
7.12.4. Usage Example .....................................86
7.13. The rpc Statement ........................................87
7.13.1. The rpc's Substatements ...........................88
7.13.2. The input Statement ...............................88
7.13.3. The output Statement ..............................89
7.13.4. XML Mapping Rules .................................90
7.13.5. Usage Example .....................................91
7.14. The notification Statement ...............................91
7.14.1. The notification's Substatements ..................92
7.14.2. XML Mapping Rules .................................92
7.14.3. Usage Example .....................................93
7.15. The augment Statement ....................................93
7.15.1. The augment's Substatements .......................94
7.15.2. XML Mapping Rules .................................94
7.15.3. Usage Example .....................................95
7.16. The identity Statement ...................................97
7.16.1. The identity's Substatements ......................97
7.16.2. The base Statement ................................97
7.16.3. Usage Example .....................................98
7.17. The extension Statement ..................................98
7.17.1. The extension's Substatements .....................99
7.17.2. The argument Statement ............................99
7.17.3. Usage Example ....................................100
7.18. Conformance-Related Statements ..........................100
7.18.1. The feature Statement ............................100
7.18.2. The if-feature Statement .........................102
7.18.3. The deviation Statement ..........................102
7.19. Common Statements .......................................105
7.19.1. The config Statement .............................105
7.19.2. The status Statement .............................105
7.19.3. The description Statement ........................106
7.19.4. The reference Statement ..........................106
7.19.5. The when Statement ...............................107
8. Constraints ...................................................108
8.1. Constraints on Data ......................................108
8.2. Hierarchy of Constraints .................................109
8.3. Constraint Enforcement Model .............................109
8.3.1. Payload Parsing ...................................109
8.3.2. NETCONF <edit-config> Processing ..................110
8.3.3. Validation ........................................111
9. Built-In Types ................................................111
9.1. Canonical Representation .................................112
9.2. The Integer Built-In Types ...............................112
9.2.1. Lexical Representation ............................113
9.2.2. Canonical Form ....................................114
9.2.3. Restrictions ......................................114
9.2.4. The range Statement ...............................114
9.2.5. Usage Example .....................................115
9.3. The decimal64 Built-In Type ..............................115
9.3.1. Lexical Representation ............................115
9.3.2. Canonical Form ....................................115
9.3.3. Restrictions ......................................116
9.3.4. The fraction-digits Statement .....................116
9.3.5. Usage Example .....................................117
9.4. The string Built-In Type .................................117
9.4.1. Lexical Representation ............................117
9.4.2. Canonical Form ....................................117
9.4.3. Restrictions ......................................117
9.4.4. The length Statement ..............................117
9.4.5. Usage Example .....................................118
9.4.6. The pattern Statement .............................119
9.4.7. Usage Example .....................................119
9.5. The boolean Built-In Type ................................120
9.5.1. Lexical Representation ............................120
9.5.2. Canonical Form ....................................120
9.5.3. Restrictions ......................................120
9.6. The enumeration Built-In Type ............................120
9.6.1. Lexical Representation ............................120
9.6.2. Canonical Form ....................................120
9.6.3. Restrictions ......................................120
9.6.4. The enum Statement ................................120
9.6.5. Usage Example .....................................121
9.7. The bits Built-In Type ...................................122
9.7.1. Restrictions ......................................122
9.7.2. Lexical Representation ............................122
9.7.3. Canonical Form ....................................122
9.7.4. The bit Statement .................................122
9.7.5. Usage Example .....................................123
9.8. The binary Built-In Type .................................123
9.8.1. Restrictions ......................................124
9.8.2. Lexical Representation ............................124
9.8.3. Canonical Form ....................................124
9.9. The leafref Built-In Type ................................124
9.9.1. Restrictions ......................................124
9.9.2. The path Statement ................................124
9.9.3. Lexical Representation ............................125
9.9.4. Canonical Form ....................................125
9.9.5. Usage Example .....................................126
9.10. The identityref Built-In Type ...........................129
9.10.1. Restrictions .....................................129
9.10.2. The identityref's base Statement .................129
9.10.3. Lexical Representation ...........................130
9.10.4. Canonical Form ...................................130
9.10.5. Usage Example ....................................130
9.11. The empty Built-In Type .................................131
9.11.1. Restrictions .....................................131
9.11.2. Lexical Representation ...........................131
9.11.3. Canonical Form ...................................131
9.11.4. Usage Example ....................................131
9.12. The union Built-In Type .................................132
9.12.1. Restrictions .....................................132
9.12.2. Lexical Representation ...........................132
9.12.3. Canonical Form ...................................133
9.13. The instance-identifier Built-In Type ...................133
9.13.1. Restrictions .....................................134
9.13.2. The require-instance Statement ...................134
9.13.3. Lexical Representation ...........................134
9.13.4. Canonical Form ...................................134
9.13.5. Usage Example ....................................134
10. Updating a Module ............................................135
11. YIN ..........................................................137
11.1. Formal YIN Definition ...................................137
11.1.1. Usage Example ....................................141
12. YANG ABNF Grammar ............................................143
13. Error Responses for YANG Related Errors ......................165
13.1. Error Message for Data That Violates a unique
Statement ...............................................165
13.2. Error Message for Data That Violates a
max-elements Statement ..................................165
13.3. Error Message for Data That Violates a
min-elements Statement ..................................165
13.4. Error Message for Data That Violates a must Statement ...166
13.5. Error Message for Data That Violates a
require-instance Statement ..............................166
13.6. Error Message for Data That Does Not Match a
leafref Type ............................................166
13.7. Error Message for Data That Violates a mandatory
choice Statement ........................................166
13.8. Error Message for the "insert" Operation ................167
14. IANA Considerations ..........................................167
14.1. Media type application/yang .............................168
14.2. Media type application/yin+xml ..........................169
15. Security Considerations ......................................170
16. Contributors .................................................171
17. Acknowledgements .............................................171
18. References ...................................................171
18.1. Normative References ....................................171
18.2. Informative References ..................................172
1. Introduction
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. YANG is used to model the operations and content layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], Section 1.1). This document describes the syntax and semantics of the YANG language, how the data model defined in a YANG module is represented in the Extensible Markup Language (XML), and how NETCONF operations are used to manipulate the data.2. Keywords
The keywords "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
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 configuration data: The set of writable data that is required to transform a system from its initial default state into its current state [RFC4741]. o conformance: A measure of how accurately a device 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, 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, and anyxml.
o data tree: The instantiated tree of configuration and state data
on a device.
o derived type: A type that is derived from a built-in type (such as
uint32), or another derived type.
o device deviation: A failure of the device to implement the module
faithfully.
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 devices that support that feature.
o grouping: A reusable set of schema nodes, which may be used
locally in the module, in modules that include it, 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: Used to identify different kinds of YANG items by
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 module: A YANG module defines a hierarchy of nodes that can be
used for NETCONF-based operations. With its definitions and the
definitions it imports or includes from elsewhere, a module is
self-contained and "compilable".
o RPC: A Remote Procedure Call, as used within the NETCONF protocol.
o RPC operation: A specific Remote Procedure Call, as used within
the NETCONF protocol. It is also called a protocol operation.
o schema node: A node in the schema tree. One of container, leaf,
leaf-list, list, choice, case, rpc, input, output, notification,
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 state data: The additional data on a system that is not
configuration data such as read-only status information and
collected statistics [RFC4741].
o submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, 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.
3.1. Mandatory Nodes
A mandatory node is one of:
o A leaf, choice, or anyxml node with a "mandatory" statement with
the value "true".
o A list or leaf-list node with a "min-elements" statement with a
value greater than zero.
o A container node without a "presence" statement, which has at
least one mandatory node as a child.
(page 11 continued on part 2)
