summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7950.txt
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
committerThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
commit4bfd864f10b68b71482b35c818559068ef8d5797 (patch)
treee3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc7950.txt
parentea76e11061bda059ae9f9ad130a9895cc85607db (diff)
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc7950.txt')
-rw-r--r--doc/rfc/rfc7950.txt12155
1 files changed, 12155 insertions, 0 deletions
diff --git a/doc/rfc/rfc7950.txt b/doc/rfc/rfc7950.txt
new file mode 100644
index 0000000..ac4af7f
--- /dev/null
+++ b/doc/rfc/rfc7950.txt
@@ -0,0 +1,12155 @@
+
+
+
+
+
+
+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 Language
+
+Abstract
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 1]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 2]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+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
+
+
+
+Bjorklund Standards Track [Page 3]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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
+
+
+
+Bjorklund Standards Track [Page 4]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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
+
+
+
+
+
+
+Bjorklund Standards Track [Page 5]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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
+
+
+
+
+
+
+Bjorklund Standards Track [Page 6]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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
+
+
+
+
+Bjorklund Standards Track [Page 7]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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
+
+
+
+
+Bjorklund Standards Track [Page 8]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 9]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+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".
+
+
+
+
+
+Bjorklund Standards Track [Page 10]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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.
+
+
+
+
+Bjorklund Standards Track [Page 11]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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.
+
+
+
+Bjorklund Standards Track [Page 12]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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.
+
+
+
+
+Bjorklund Standards Track [Page 13]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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.
+
+
+
+
+
+Bjorklund Standards Track [Page 14]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ 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.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 15]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+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.
+
+4. YANG Overview
+
+ This non-normative section is intended to give a high-level overview
+ of YANG to first-time readers.
+
+4.1. Functional Overview
+
+ YANG is a language originally designed to model data for the NETCONF
+ protocol. A YANG module defines hierarchies of data that can be used
+ for NETCONF-based operations, including configuration, state data,
+ RPCs, and notifications. This allows a complete description of all
+ data sent between a NETCONF client and server. Although out of scope
+ for this specification, YANG can also be used with protocols other
+ than NETCONF.
+
+ YANG models the hierarchical organization of data as a tree in which
+ each node has a name, and either a value or a set of child nodes.
+ YANG provides clear and concise descriptions of the nodes, as well as
+ the interaction between those nodes.
+
+ YANG structures data models into modules and submodules. A module
+ can import definitions from other external modules and can include
+ definitions from submodules. The hierarchy can be augmented,
+ allowing one module to add data nodes to the hierarchy defined in
+ another module. This augmentation can be conditional, with new nodes
+ appearing only if certain conditions are met.
+
+ YANG data models can describe constraints to be enforced on the data,
+ restricting the presence or value of nodes based on the presence or
+ value of other nodes in the hierarchy. These constraints are
+ enforceable by either the client or the server.
+
+ YANG defines a set of built-in types and has a type mechanism through
+ which additional types may be defined. Derived types can restrict
+ their base type's set of valid values using mechanisms like range or
+ pattern restrictions that can be enforced by clients or servers.
+ They can also define usage conventions for use of the derived type,
+ such as a string-based type that contains a hostname.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 16]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ YANG permits the definition of reusable groupings of nodes. The
+ usage of these groupings can refine or augment the nodes, allowing it
+ to tailor the nodes to its particular needs. Derived types and
+ groupings can be defined in one module and used in either the same
+ module or another module that imports it.
+
+ YANG data hierarchy constructs include defining lists where list
+ entries are identified by keys that distinguish them from each other.
+ Such lists may be defined as either sorted by user or automatically
+ sorted by the system. For user-sorted lists, operations are defined
+ for manipulating the order of the list entries.
+
+ YANG modules can be translated into an equivalent XML syntax called
+ YANG Independent Notation (YIN) (Section 13), allowing applications
+ using XML parsers and Extensible Stylesheet Language Transformations
+ (XSLT) scripts to operate on the models. The conversion from YANG to
+ YIN is semantically lossless, so content in YIN can be round-tripped
+ back into YANG.
+
+ YANG is an extensible language, allowing extensions to be defined by
+ standards bodies, vendors, and individuals. The statement syntax
+ allows these extensions to coexist with standard YANG statements in a
+ natural way, while extensions in a YANG module stand out sufficiently
+ for the reader to notice them.
+
+ YANG resists the tendency to solve all possible problems, limiting
+ the problem space to allow expression of data models for network
+ management protocols such as NETCONF, not arbitrary XML documents or
+ arbitrary data models.
+
+ To the extent possible, YANG maintains compatibility with the Simple
+ Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
+ Information version 2 [RFC2578] [RFC2579]). SMIv2-based MIB modules
+ can be automatically translated into YANG modules for read-only
+ access [RFC6643]. However, YANG is not concerned with reverse
+ translation from YANG to SMIv2.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 17]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2. Language Overview
+
+ This section introduces some important constructs used in YANG that
+ will aid in the understanding of the language specifics in later
+ sections.
+
+4.2.1. Modules and Submodules
+
+ YANG data models are defined in modules. A module contains a
+ collection of related definitions.
+
+ A module contains three types of statements: module header
+ statements, "revision" statements, and definition statements. The
+ module header statements describe the module and give information
+ about the module itself, the "revision" statements give information
+ about the history of the module, and the definition statements are
+ the body of the module where the data model is defined.
+
+ A server may implement a number of modules, allowing multiple views
+ of the same data or multiple views of disjoint subsections of the
+ server's data. Alternatively, the server may implement only one
+ module that defines all available data.
+
+ A module may have portions of its definitions separated into
+ submodules, based on the needs of the module designer. The external
+ view remains that of a single module, regardless of the presence or
+ size of its submodules.
+
+ The "import" statement allows a module or submodule to reference
+ definitions defined in other modules.
+
+ The "include" statement is used in a module to identify each
+ submodule that belongs to it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 18]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.2. Data Modeling Basics
+
+ YANG defines four main types of data nodes for data modeling. In
+ each of the following subsections, the examples show the YANG syntax
+ as well as a corresponding XML encoding. The syntax of YANG
+ statements is defined in Section 6.3.
+
+4.2.2.1. Leaf Nodes
+
+ A leaf instance contains simple data like an integer or a string. It
+ has exactly one value of a particular type and no child nodes.
+
+ YANG Example:
+
+ leaf host-name {
+ type string;
+ description
+ "Hostname for this system.";
+ }
+
+ XML Encoding Example:
+
+ <host-name>my.example.com</host-name>
+
+ The "leaf" statement is covered in Section 7.6.
+
+4.2.2.2. Leaf-List Nodes
+
+ A leaf-list defines a sequence of values of a particular type.
+
+ YANG Example:
+
+ leaf-list domain-search {
+ type string;
+ description
+ "List of domain names to search.";
+ }
+
+ XML Encoding Example:
+
+ <domain-search>high.example.com</domain-search>
+ <domain-search>low.example.com</domain-search>
+ <domain-search>everywhere.example.com</domain-search>
+
+ The "leaf-list" statement is covered in Section 7.7.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 19]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.2.3. Container Nodes
+
+ A container is used to group related nodes in a subtree. A container
+ has only child nodes and no value. A container may contain any
+ number of child nodes of any type (leafs, lists, containers,
+ leaf-lists, actions, and notifications).
+
+ YANG Example:
+
+ container system {
+ container login {
+ leaf message {
+ type string;
+ description
+ "Message given at start of login session.";
+ }
+ }
+ }
+
+ XML Encoding Example:
+
+ <system>
+ <login>
+ <message>Good morning</message>
+ </login>
+ </system>
+
+ The "container" statement is covered in Section 7.5.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 20]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.2.4. List Nodes
+
+ A list defines a sequence of list entries. Each entry is like a
+ container and is uniquely identified by the values of its key leafs
+ if it has any key leafs defined. A list can define multiple key
+ leafs and may contain any number of child nodes of any type
+ (including leafs, lists, containers, etc.).
+
+ YANG Example:
+
+ list user {
+ key "name";
+ leaf name {
+ type string;
+ }
+ leaf full-name {
+ type string;
+ }
+ leaf class {
+ type string;
+ }
+ }
+
+ XML Encoding Example:
+
+ <user>
+ <name>glocks</name>
+ <full-name>Goldie Locks</full-name>
+ <class>intruder</class>
+ </user>
+ <user>
+ <name>snowey</name>
+ <full-name>Snow White</full-name>
+ <class>free-loader</class>
+ </user>
+ <user>
+ <name>rzell</name>
+ <full-name>Rapun Zell</full-name>
+ <class>tower</class>
+ </user>
+
+ The "list" statement is covered in Section 7.8.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 21]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.2.5. Example Module
+
+ These statements are combined to define the module:
+
+ // Contents of "example-system.yang"
+ module example-system {
+ yang-version 1.1;
+ namespace "urn:example:system";
+ prefix "sys";
+
+ organization "Example Inc.";
+ contact "joe@example.com";
+ description
+ "The module for entities implementing the Example system.";
+
+ revision 2007-06-09 {
+ description "Initial revision.";
+ }
+
+ container system {
+ leaf host-name {
+ type string;
+ description
+ "Hostname for this system.";
+ }
+
+ leaf-list domain-search {
+ type string;
+ description
+ "List of domain names to search.";
+ }
+
+ container login {
+ leaf message {
+ type string;
+ description
+ "Message given at start of login session.";
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 22]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ list user {
+ key "name";
+ leaf name {
+ type string;
+ }
+ leaf full-name {
+ type string;
+ }
+ leaf class {
+ type string;
+ }
+ }
+ }
+ }
+ }
+
+4.2.3. Configuration and State Data
+
+ YANG can model state data, as well as configuration data, based on
+ the "config" statement. When a node is tagged with "config false",
+ its subhierarchy is flagged as state data. If it is tagged with
+ "config true", its subhierarchy is flagged as configuration data.
+ Parent containers, lists, and key leafs are reported also, giving the
+ context for the state data.
+
+ In this example, two leafs are defined for each interface, a
+ configured speed and an observed speed.
+
+ list interface {
+ key "name";
+ config true;
+
+ leaf name {
+ type string;
+ }
+ leaf speed {
+ type enumeration {
+ enum 10m;
+ enum 100m;
+ enum auto;
+ }
+ }
+ leaf observed-speed {
+ type uint32;
+ config false;
+ }
+ }
+
+
+
+
+Bjorklund Standards Track [Page 23]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The "config" statement is covered in Section 7.21.1.
+
+4.2.4. Built-In Types
+
+ YANG has a set of built-in types, similar to those of many
+ programming languages, but with some differences due to special
+ requirements of network management. The following table summarizes
+ the built-in types discussed in Section 9:
+
+ +---------------------+-------------------------------------+
+ | Name | Description |
+ +---------------------+-------------------------------------+
+ | binary | Any binary data |
+ | bits | A set of bits or flags |
+ | boolean | "true" or "false" |
+ | decimal64 | 64-bit signed decimal number |
+ | empty | A leaf that does not have any value |
+ | enumeration | One of an enumerated set of strings |
+ | identityref | A reference to an abstract identity |
+ | instance-identifier | A reference to a data tree node |
+ | int8 | 8-bit signed integer |
+ | int16 | 16-bit signed integer |
+ | int32 | 32-bit signed integer |
+ | int64 | 64-bit signed integer |
+ | leafref | A reference to a leaf instance |
+ | string | A character string |
+ | uint8 | 8-bit unsigned integer |
+ | uint16 | 16-bit unsigned integer |
+ | uint32 | 32-bit unsigned integer |
+ | uint64 | 64-bit unsigned integer |
+ | union | Choice of member types |
+ +---------------------+-------------------------------------+
+
+ The "type" statement is covered in Section 7.4.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 24]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.5. Derived Types (typedef)
+
+ YANG can define derived types from base types using the "typedef"
+ statement. A base type can be either a built-in type or a derived
+ type, allowing a hierarchy of derived types.
+
+ A derived type can be used as the argument for the "type" statement.
+
+ YANG Example:
+
+ typedef percent {
+ type uint8 {
+ range "0 .. 100";
+ }
+ }
+
+ leaf completed {
+ type percent;
+ }
+
+ XML Encoding Example:
+
+ <completed>20</completed>
+
+ The "typedef" statement is covered in Section 7.3.
+
+4.2.6. Reusable Node Groups (grouping)
+
+ Groups of nodes can be assembled into reusable collections using the
+ "grouping" statement. A grouping defines a set of nodes that are
+ instantiated with the "uses" statement.
+
+ YANG Example:
+
+ grouping target {
+ leaf address {
+ type inet:ip-address;
+ description "Target IP address.";
+ }
+ leaf port {
+ type inet:port-number;
+ description "Target port number.";
+ }
+ }
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 25]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ container peer {
+ container destination {
+ uses target;
+ }
+ }
+
+ XML Encoding Example:
+
+ <peer>
+ <destination>
+ <address>2001:db8::2</address>
+ <port>830</port>
+ </destination>
+ </peer>
+
+ The grouping can be refined as it is used, allowing certain
+ statements to be overridden. In this example, the description is
+ refined:
+
+ container connection {
+ container source {
+ uses target {
+ refine "address" {
+ description "Source IP address.";
+ }
+ refine "port" {
+ description "Source port number.";
+ }
+ }
+ }
+ container destination {
+ uses target {
+ refine "address" {
+ description "Destination IP address.";
+ }
+ refine "port" {
+ description "Destination port number.";
+ }
+ }
+ }
+ }
+
+ The "grouping" statement is covered in Section 7.12.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 26]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+4.2.7. Choices
+
+ YANG allows the data model to segregate incompatible nodes into
+ distinct choices using the "choice" and "case" statements. The
+ "choice" statement contains a set of "case" statements that define
+ sets of schema nodes that cannot appear together. Each "case" may
+ contain multiple nodes, but each node may appear in only one "case"
+ under a "choice".
+
+ The choice and case nodes appear only in the schema tree and not in
+ the data tree. The additional levels of hierarchy are not needed
+ beyond the conceptual schema. The presence of a case is indicated by
+ the presence of one or more of the nodes within it.
+
+ Since only one of the choice's cases can be valid at any time, when a
+ node from one case is created in the data tree, all nodes from all
+ other cases are implicitly deleted. The server handles the
+ enforcement of the constraint, preventing incompatibilities from
+ existing in the configuration.
+
+ YANG Example:
+
+ container food {
+ choice snack {
+ case sports-arena {
+ leaf pretzel {
+ type empty;
+ }
+ leaf beer {
+ type empty;
+ }
+ }
+ case late-night {
+ leaf chocolate {
+ type enumeration {
+ enum dark;
+ enum milk;
+ enum first-available;
+ }
+ }
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 27]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ XML Encoding Example:
+
+ <food>
+ <pretzel/>
+ <beer/>
+ </food>
+
+ The "choice" statement is covered in Section 7.9.
+
+4.2.8. Extending Data Models (augment)
+
+ YANG allows a module to insert additional nodes into data models,
+ including both the current module (and its submodules) and an
+ external module. This is useful, for example, for vendors to add
+ vendor-specific parameters to standard data models in an
+ interoperable way.
+
+ The "augment" statement defines the location in the data model
+ hierarchy where new nodes are inserted, and the "when" statement
+ defines the conditions when the new nodes are valid.
+
+ When a server implements a module containing an "augment" statement,
+ that implies that the server's implementation of the augmented module
+ contains the additional nodes.
+
+ YANG Example:
+
+ augment /system/login/user {
+ when "class != 'wheel'";
+ leaf uid {
+ type uint16 {
+ range "1000 .. 30000";
+ }
+ }
+ }
+
+ This example defines a "uid" node that is valid only when the user's
+ "class" is not "wheel".
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 28]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If a module augments another module, the XML elements that are added
+ to the encoding are in the namespace of the augmenting module. For
+ example, if the above augmentation were in a module with prefix
+ "other", the XML would look like:
+
+ XML Encoding Example:
+
+ <user>
+ <name>alicew</name>
+ <full-name>Alice N. Wonderland</full-name>
+ <class>drop-out</class>
+ <other:uid>1024</other:uid>
+ </user>
+
+ The "augment" statement is covered in Section 7.17.
+
+4.2.9. Operation Definitions
+
+ YANG allows the definition of operations. The operations' names,
+ input parameters, and output parameters are modeled using YANG data
+ definition statements. Operations on the top level in a module are
+ defined with the "rpc" statement. Operations can also be tied to a
+ container or list data node. Such operations are defined with the
+ "action" statement.
+
+ YANG Example for an operation at the top level:
+
+ rpc activate-software-image {
+ input {
+ leaf image-name {
+ type string;
+ }
+ }
+ output {
+ leaf status {
+ type string;
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 29]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ NETCONF XML Example:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <activate-software-image xmlns="http://example.com/system">
+ <image-name>example-fw-2.3</image-name>
+ </activate-software-image>
+ </rpc>
+
+ <rpc-reply message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <status xmlns="http://example.com/system">
+ The image example-fw-2.3 is being installed.
+ </status>
+ </rpc-reply>
+
+ YANG Example for an operation tied to a list data node:
+
+ list interface {
+ key "name";
+
+ leaf name {
+ type string;
+ }
+
+ action ping {
+ input {
+ leaf destination {
+ type inet:ip-address;
+ }
+ }
+ output {
+ leaf packet-loss {
+ type uint8;
+ }
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 30]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ NETCONF XML Example:
+
+ <rpc message-id="102"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <action xmlns="urn:ietf:params:xml:ns:yang:1">
+ <interface xmlns="http://example.com/system">
+ <name>eth1</name>
+ <ping>
+ <destination>192.0.2.1</destination>
+ </ping>
+ </interface>
+ </action>
+ </rpc>
+
+ <rpc-reply message-id="102"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:sys="http://example.com/system">
+ <sys:packet-loss>60</sys:packet-loss>
+ </rpc-reply>
+
+ The "rpc" statement is covered in Section 7.14, and the "action"
+ statement is covered in Section 7.15.
+
+4.2.10. Notification Definitions
+
+ YANG allows the definition of notifications. YANG data definition
+ statements are used to model the content of the notification.
+
+ YANG Example:
+
+ notification link-failure {
+ description
+ "A link failure has been detected.";
+ leaf if-name {
+ type leafref {
+ path "/interface/name";
+ }
+ }
+ leaf if-admin-status {
+ type admin-status;
+ }
+ leaf if-oper-status {
+ type oper-status;
+ }
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 31]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ NETCONF XML Example:
+
+ <notification
+ xmlns="urn:ietf:params:netconf:capability:notification:1.0">
+ <eventTime>2007-09-01T10:00:00Z</eventTime>
+ <link-failure xmlns="urn:example:system">
+ <if-name>so-1/2/3.0</if-name>
+ <if-admin-status>up</if-admin-status>
+ <if-oper-status>down</if-oper-status>
+ </link-failure>
+ </notification>
+
+ The "notification" statement is covered in Section 7.16.
+
+5. Language Concepts
+
+5.1. Modules and Submodules
+
+ The module is the base unit of definition in YANG. A module defines
+ a single data model. A module can also augment an existing data
+ model with additional nodes.
+
+ Submodules are partial modules that contribute definitions to a
+ module. A module may include any number of submodules, but each
+ submodule may belong to only one module.
+
+ Developers of YANG modules and submodules are RECOMMENDED to choose
+ names for their modules that will have a low probability of colliding
+ with standard or other enterprise modules, e.g., by using the
+ enterprise or organization name as a prefix for the module name.
+ Within a server, all module names MUST be unique.
+
+ A module uses the "include" statement to list all its submodules. A
+ module, or submodule belonging to that module, can reference
+ definitions in the module and all submodules included by the module.
+
+ A module or submodule uses the "import" statement to reference
+ external modules. Statements in the module or submodule can
+ reference definitions in the external module using the prefix
+ specified in the "import" statement.
+
+ For backward compatibility with YANG version 1, a submodule MAY use
+ the "include" statement to reference other submodules within its
+ module, but this is not necessary in YANG version 1.1. A submodule
+ can reference any definition in the module it belongs to and in all
+ submodules included by the module. A submodule MUST NOT include
+ different revisions of other submodules than the revisions that its
+ module includes.
+
+
+
+Bjorklund Standards Track [Page 32]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A module or submodule MUST NOT include submodules from other modules,
+ and a submodule MUST NOT import its own module.
+
+ The "import" and "include" statements are used to make definitions
+ available from other modules:
+
+ o For a module or submodule to reference definitions in an external
+ module, the external module MUST be imported.
+
+ o A module MUST include all its submodules.
+
+ o A module, or submodule belonging to that module, MAY reference
+ definitions in the module and all submodules included by the
+ module.
+
+ There MUST NOT be any circular chains of imports. For example, if
+ module "a" imports module "b", "b" cannot import "a".
+
+ When a definition in an external module is referenced, a locally
+ defined prefix MUST be used, followed by a colon (":") and then the
+ external identifier. References to definitions in the local module
+ MAY use the prefix notation. Since built-in data types do not belong
+ to any module and have no prefix, references to built-in data types
+ (e.g., int32) cannot use the prefix notation. The syntax for a
+ reference to a definition is formally defined by the rule
+ "identifier-ref" in Section 14.
+
+5.1.1. Import and Include by Revision
+
+ Published modules evolve independently over time. In order to allow
+ for this evolution, modules can be imported using specific revisions.
+ Initially, a module imports the revisions of other modules that are
+ current when the module is written. As future revisions of the
+ imported modules are published, the importing module is unaffected
+ and its contents are unchanged. When the author of the module is
+ prepared to move to the most recently published revision of an
+ imported module, the module is republished with an updated "import"
+ statement. By republishing with the new revision, the authors
+ explicitly indicate their acceptance of any changes in the imported
+ module.
+
+ For submodules, the issue is related but simpler. A module or
+ submodule that includes submodules may specify the revision of the
+ included submodules. If a submodule changes, any module or submodule
+ that includes it by revision needs to be updated to reference the new
+ revision.
+
+
+
+
+
+Bjorklund Standards Track [Page 33]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ For example, module "b" imports module "a".
+
+ module a {
+ yang-version 1.1;
+ namespace "urn:example:a";
+ prefix "a";
+
+ revision 2008-01-01 { ... }
+ grouping a {
+ leaf eh { .... }
+ }
+ }
+
+ module b {
+ yang-version 1.1;
+ namespace "urn:example:b";
+ prefix "b";
+
+ import a {
+ prefix "p";
+ revision-date 2008-01-01;
+ }
+
+ container bee {
+ uses p:a;
+ }
+ }
+
+ When the author of "a" publishes a new revision, the changes may not
+ be acceptable to the author of "b". If the new revision is
+ acceptable, the author of "b" can republish with an updated revision
+ in the "import" statement.
+
+ If a module is not imported with a specific revision, it is undefined
+ which revision is used.
+
+5.1.2. Module Hierarchies
+
+ YANG allows modeling of data in multiple hierarchies, where data may
+ have more than one top-level node. Each top-level data node in a
+ module defines a separate hierarchy. Models that have multiple
+ top-level nodes are sometimes convenient and are supported by YANG.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 34]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+5.1.2.1. NETCONF XML Encoding
+
+ NETCONF is capable of carrying any XML content as the payload in the
+ <config> and <data> elements. The top-level nodes of YANG modules
+ are encoded as child elements, in any order, within these elements.
+ This encapsulation guarantees that the corresponding NETCONF messages
+ are always well-formed XML documents.
+
+ For example, an instance of:
+
+ module example-config {
+ yang-version 1.1;
+ namespace "urn:example:config";
+ prefix "co";
+
+ container system { ... }
+ container routing { ... }
+ }
+
+ could be encoded in NETCONF as:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <!-- system data here -->
+ </system>
+ <routing xmlns="urn:example:config">
+ <!-- routing data here -->
+ </routing>
+ </config>
+ </edit-config>
+ </rpc>
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 35]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+5.2. File Layout
+
+ YANG modules and submodules are typically stored in files, one
+ "module" or "submodule" statement per file. The name of the file
+ SHOULD be of the form:
+
+ module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )
+
+ "module-or-submodule-name" is the name of the module or submodule,
+ and the optional "revision-date" is the latest revision of the module
+ or submodule, as defined by the "revision" statement (Section 7.1.9).
+
+ The file extension ".yang" denotes that the contents of the file are
+ written with YANG syntax (Section 6), and ".yin" denotes that the
+ contents of the file are written with YIN syntax (Section 13).
+
+ YANG parsers can find imported modules and included submodules via
+ this convention.
+
+5.3. XML Namespaces
+
+ All YANG definitions are specified within a module. Each module is
+ bound to a distinct XML namespace [XML-NAMES], which is a globally
+ unique URI [RFC3986]. A NETCONF client or server uses the namespace
+ during XML encoding of data.
+
+ XML namespaces for modules published in RFC streams [RFC4844] MUST be
+ assigned by IANA; see Section 14 in [RFC6020].
+
+ XML namespaces for private modules are assigned by the organization
+ owning the module without a central registry. Namespace URIs MUST be
+ chosen so they cannot collide with standard or other enterprise
+ namespaces -- for example, by using the enterprise or organization
+ name in the namespace.
+
+ The "namespace" statement is covered in Section 7.1.3.
+
+5.3.1. YANG XML Namespace
+
+ YANG defines an XML namespace for NETCONF <edit-config> operations,
+ <error-info> content, and the <action> element. The name of this
+ namespace is "urn:ietf:params:xml:ns:yang:1".
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 36]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+5.4. Resolving Grouping, Type, and Identity Names
+
+ Grouping, type, and identity names are resolved in the context in
+ which they are defined, rather than the context in which they are
+ used. Users of groupings, typedefs, and identities are not required
+ to import modules or include submodules to satisfy all references
+ made by the original definition. This behaves like static scoping in
+ a conventional programming language.
+
+ For example, if a module defines a grouping in which a type is
+ referenced, when the grouping is used in a second module, the type is
+ resolved in the context of the original module, not the second
+ module. There is no ambiguity if both modules define the type.
+
+5.5. Nested Typedefs and Groupings
+
+ Typedefs and groupings may appear nested under many YANG statements,
+ allowing these to be lexically scoped by the statement hierarchy
+ under which they appear. This allows types and groupings to be
+ defined near where they are used, rather than placing them at the
+ top level of the hierarchy. The close proximity increases
+ readability.
+
+ Scoping also allows types to be defined without concern for naming
+ conflicts between types in different submodules. Type names can be
+ specified without adding leading strings designed to prevent name
+ collisions within large modules.
+
+ Finally, scoping allows the module author to keep types and groupings
+ private to their module or submodule, preventing their reuse. Since
+ only top-level types and groupings (i.e., those appearing as
+ substatements to a "module" or "submodule" statement) can be used
+ outside the module or submodule, the developer has more control over
+ what pieces of their module are presented to the outside world,
+ supporting the need to hide internal information and maintaining a
+ boundary between what is shared with the outside world and what is
+ kept private.
+
+ Scoped definitions MUST NOT shadow definitions at a higher scope. A
+ type or grouping cannot be defined if a higher level in the statement
+ hierarchy has a definition with a matching identifier.
+
+ A reference to an unprefixed type or grouping, or one that uses the
+ prefix of the current module, is resolved by locating the matching
+ "typedef" or "grouping" statement among the immediate substatements
+ of each ancestor statement.
+
+
+
+
+
+Bjorklund Standards Track [Page 37]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+5.6. Conformance
+
+ Conformance to a model is a measure of how accurately a server
+ follows the model. Generally speaking, servers are responsible for
+ implementing the model faithfully, allowing applications to treat
+ servers that implement the model identically. Deviations from the
+ model can reduce the utility of the model and increase the fragility
+ of applications that use it.
+
+ YANG modelers have three mechanisms for conformance:
+
+ o the basic behavior of the model
+
+ o optional features that are part of the model
+
+ o deviations from the model
+
+ We will consider each of these in sequence.
+
+5.6.1. Basic Behavior
+
+ The model defines a contract between a YANG-based client and server;
+ this contract allows both parties to have faith that the other knows
+ the syntax and semantics behind the modeled data. The strength of
+ YANG lies in the strength of this contract.
+
+5.6.2. Optional Features
+
+ In many models, the modeler will allow sections of the model to be
+ conditional. The server controls whether these conditional portions
+ of the model are supported or valid for that particular server.
+
+ For example, a syslog data model may choose to include the ability to
+ save logs locally, but the modeler will realize that this is only
+ possible if the server has local storage. If there is no local
+ storage, an application should not tell the server to save logs.
+
+ YANG supports this conditional mechanism using a construct called
+ "feature". Features give the modeler a mechanism for making portions
+ of the module conditional in a manner that is controlled by the
+ server. The model can express constructs that are not universally
+ present in all servers. These features are included in the model
+ definition, allowing a consistent view and allowing applications to
+ learn which features are supported and tailor their behavior to the
+ server.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 38]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A module may declare any number of features, identified by simple
+ strings, and may make portions of the module optional based on those
+ features. If the server supports a feature, then the corresponding
+ portions of the module are valid for that server. If the server
+ doesn't support the feature, those parts of the module are not valid,
+ and applications should behave accordingly.
+
+ Features are defined using the "feature" statement. Definitions in
+ the module that are conditional to the feature are noted by the
+ "if-feature" statement.
+
+ Further details are available in Section 7.20.1.
+
+5.6.3. Deviations
+
+ In an ideal world, all servers would be required to implement the
+ model exactly as defined, and deviations from the model would not be
+ allowed. But in the real world, servers are often not able or
+ designed to implement the model as written. For YANG-based
+ automation to deal with these server deviations, a mechanism must
+ exist for servers to inform applications of the specifics of such
+ deviations.
+
+ For example, a BGP module may allow any number of BGP peers, but a
+ particular server may only support 16 BGP peers. Any application
+ configuring the 17th peer will receive an error. While an error may
+ suffice to let the application know it cannot add another peer, it
+ would be far better if the application had prior knowledge of this
+ limitation and could prevent the user from starting down the path
+ that could not succeed.
+
+ Server deviations are declared using the "deviation" statement, which
+ takes as its argument a string that identifies a node in the schema
+ tree. The contents of the statement detail the manner in which the
+ server implementation deviates from the contract as defined in the
+ module.
+
+ Further details are available in Section 7.20.3.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 39]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+5.6.4. Announcing Conformance Information in NETCONF
+
+ This document defines the following mechanism for announcing
+ conformance information. Other mechanisms may be defined by future
+ specifications.
+
+ A NETCONF server MUST announce the modules it implements (see
+ Section 5.6.5) by implementing the YANG module "ietf-yang-library"
+ defined in [RFC7895] and listing all implemented modules in the
+ "/modules-state/module" list.
+
+ The server also MUST advertise the following capability in the
+ <hello> message (line breaks and whitespaces are used for formatting
+ reasons only):
+
+ urn:ietf:params:netconf:capability:yang-library:1.0?
+ revision=<date>&module-set-id=<id>
+
+ The parameter "revision" has the same value as the revision date of
+ the "ietf-yang-library" module implemented by the server. This
+ parameter MUST be present.
+
+ The parameter "module-set-id" has the same value as the leaf
+ "/modules-state/module-set-id" from "ietf-yang-library". This
+ parameter MUST be present.
+
+ With this mechanism, a client can cache the supported modules for a
+ server and only update the cache if the "module-set-id" value in the
+ <hello> message changes.
+
+5.6.5. Implementing a Module
+
+ A server implements a module if it implements the module's data
+ nodes, RPCs, actions, notifications, and deviations.
+
+ A server MUST NOT implement more than one revision of a module.
+
+ If a server implements a module A that imports a module B, and A uses
+ any node from B in an "augment" or "path" statement that the server
+ supports, then the server MUST implement a revision of module B that
+ has these nodes defined. This is regardless of whether module B is
+ imported by revision or not.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 40]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If a server implements a module A that imports a module C without
+ specifying the revision date of module C and the server does not
+ implement C (e.g., if C only defines some typedefs), the server MUST
+ list module C in the "/modules-state/module" list from
+ "ietf-yang-library" [RFC7895], and it MUST set the leaf
+ "conformance-type" to "import" for this module.
+
+ If a server lists a module C in the "/modules-state/module" list from
+ "ietf-yang-library" and there are other modules Ms listed that import
+ C without specifying the revision date of module C, the server MUST
+ use the definitions from the most recent revision of C listed for
+ modules Ms.
+
+ The reason for these rules is that clients need to be able to know
+ the specific data model structure and types of all leafs and
+ leaf-lists implemented in a server.
+
+ For example, with these modules:
+
+ module a {
+ yang-version 1.1;
+ namespace "urn:example:a";
+ prefix "a";
+
+ import b {
+ revision-date 2015-01-01;
+ }
+ import c;
+
+ revision 2015-01-01;
+
+ feature foo;
+
+ augment "/b:x" {
+ if-feature foo;
+
+ leaf y {
+ type b:myenum;
+ }
+ }
+
+ container a {
+ leaf x {
+ type c:bar;
+ }
+ }
+ }
+
+
+
+
+Bjorklund Standards Track [Page 41]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ module b {
+ yang-version 1.1;
+ namespace "urn:example:b";
+ prefix "b";
+
+ revision 2015-01-01;
+
+ typedef myenum {
+ type enumeration {
+ enum zero;
+ }
+ }
+
+ container x {
+ }
+ }
+
+ module b {
+ yang-version 1.1;
+ namespace "urn:example:b";
+ prefix "b";
+
+ revision 2015-04-04;
+ revision 2015-01-01;
+
+ typedef myenum {
+ type enumeration {
+ enum zero; // added in 2015-01-01
+ enum one; // added in 2015-04-04
+ }
+ }
+
+ container x { // added in 2015-01-01
+ container y; // added in 2015-04-04
+ }
+ }
+
+ module c {
+ yang-version 1.1;
+ namespace "urn:example:c";
+ prefix "c";
+
+ revision 2015-02-02;
+
+ typedef bar {
+ ...
+ }
+ }
+
+
+
+Bjorklund Standards Track [Page 42]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ module c {
+ yang-version 1.1;
+ namespace "urn:example:c";
+ prefix "c";
+
+ revision 2015-03-03;
+ revision 2015-02-02;
+
+ typedef bar {
+ ...
+ }
+ }
+
+ A server that implements revision "2015-01-01" of module "a" and
+ supports feature "foo" can implement revision "2015-01-01" or
+ "2015-04-04" of module "b". Since "b" was imported by revision, the
+ type of leaf "/b:x/a:y" is the same, regardless of which revision of
+ "b" the server implements.
+
+ A server that implements module "a" but does not support feature
+ "foo" does not have to implement module "b".
+
+ A server that implements revision "2015-01-01" of module "a"
+ picks any revision of module "c" and lists it in the
+ "/modules-state/module" list from "ietf-yang-library".
+
+ The following XML encoding example shows valid data for the
+ "/modules-state/module" list for a server that implements module "a":
+
+ <modules-state
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
+ <module-set-id>ee1ecb017370cafd</module-set-id>
+ <module>
+ <name>a</name>
+ <revision>2015-01-01</revision>
+ <namespace>urn:example:a</namespace>
+ <feature>foo</feature>
+ <conformance-type>implement</conformance-type>
+ </module>
+ <module>
+ <name>b</name>
+ <revision>2015-04-04</revision>
+ <namespace>urn:example:b</namespace>
+ <conformance-type>implement</conformance-type>
+ </module>
+
+
+
+
+
+
+Bjorklund Standards Track [Page 43]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ <module>
+ <name>c</name>
+ <revision>2015-02-02</revision>
+ <namespace>urn:example:c</namespace>
+ <conformance-type>import</conformance-type>
+ </module>
+ </modules-state>
+
+5.7. Datastore Modification
+
+ Data models may allow the server to alter the configuration datastore
+ in ways not explicitly directed via network management protocol
+ messages. For example, a data model may define leafs that are
+ assigned system-generated values when the client does not provide
+ one. A formal mechanism for specifying the circumstances where these
+ changes are allowed is out of scope for this specification.
+
+6. YANG Syntax
+
+ The YANG syntax is similar to that of SMIng [RFC3780] and programming
+ languages like C and C++. This C-like syntax was chosen specifically
+ for its readability, since YANG values the time and effort of the
+ readers of models above those of modules writers and YANG tool-chain
+ developers. This section introduces the YANG syntax.
+
+ Legal characters in YANG modules are the Unicode and ISO/IEC 10646
+ [ISO.10646] characters, including tab, carriage return, and line feed
+ but excluding the other C0 control characters, the surrogate blocks,
+ and the noncharacters. The character syntax is formally defined by
+ the rule "yang-char" in Section 14.
+
+ YANG modules and submodules are stored in files using the UTF-8
+ [RFC3629] character encoding.
+
+ Lines in a YANG module end with a carriage return-line feed
+ combination or with a line feed alone. A carriage return that is not
+ followed by a line feed may only appear inside a quoted string
+ (Section 6.1.3). Note that carriage returns and line feeds that
+ appear inside quoted strings become part of the value of the string
+ without modification; the value of a multi-line quoted string
+ contains the same form of line ends as those lines of the YANG
+ module.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 44]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+6.1. Lexical Tokenization
+
+ YANG modules are parsed as a series of tokens. This section details
+ the rules for recognizing tokens from an input stream. YANG
+ tokenization rules are both simple and powerful. The simplicity is
+ driven by a need to keep the parsers easy to implement, while the
+ power is driven by the fact that modelers need to express their
+ models in readable formats.
+
+6.1.1. Comments
+
+ Comments are C++ style. A single line comment starts with "//" and
+ ends at the end of the line. A block comment starts with "/*" and
+ ends with the nearest following "*/".
+
+ Note that inside a quoted string (Section 6.1.3), these character
+ pairs are never interpreted as the start or end of a comment.
+
+6.1.2. Tokens
+
+ A token in YANG is either a keyword, a string, a semicolon (";"), or
+ braces ("{" or "}"). A string can be quoted or unquoted. A keyword
+ is either one of the YANG keywords defined in this document, or a
+ prefix identifier, followed by a colon (":"), followed by a language
+ extension keyword. Keywords are case sensitive. See Section 6.2 for
+ a formal definition of identifiers.
+
+6.1.3. Quoting
+
+ An unquoted string is any sequence of characters that does not
+ contain any space, tab, carriage return, or line feed characters, a
+ single or double quote character, a semicolon (";"), braces ("{" or
+ "}"), or comment sequences ("//", "/*", or "*/").
+
+ Note that any keyword can legally appear as an unquoted string.
+
+ Within an unquoted string, every character is preserved. Note that
+ this means that the backslash character does not have any special
+ meaning in an unquoted string.
+
+ If a double-quoted string contains a line break followed by space or
+ tab characters that are used to indent the text according to the
+ layout in the YANG file, this leading whitespace is stripped from the
+ string, up to and including the column of the starting double quote
+ character, or to the first non-whitespace character, whichever occurs
+ first. Any tab character in a succeeding line that must be examined
+ for stripping is first converted into 8 space characters.
+
+
+
+
+Bjorklund Standards Track [Page 45]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If a double-quoted string contains space or tab characters before a
+ line break, this trailing whitespace is stripped from the string.
+
+ A single-quoted string (enclosed within ' ') preserves each character
+ within the quotes. A single quote character cannot occur in a
+ single-quoted string, even when preceded by a backslash.
+
+ Within a double-quoted string (enclosed within " "), a backslash
+ character introduces a representation of a special character, which
+ depends on the character that immediately follows the backslash:
+
+ \n newline
+ \t a tab character
+ \" a double quote
+ \\ a single backslash
+
+ The backslash MUST NOT be followed by any other character.
+
+ If a quoted string is followed by a plus character ("+"), followed by
+ another quoted string, the two strings are concatenated into one
+ string, allowing multiple concatenations to build one string.
+ Whitespace, line breaks, and comments are allowed between the quoted
+ strings and the plus character.
+
+ In double-quoted strings, whitespace trimming is done before
+ substitution of backslash-escaped characters. Concatenation is
+ performed as the last step.
+
+6.1.3.1. Quoting Examples
+
+ The following strings are equivalent:
+
+ hello
+ "hello"
+ 'hello'
+ "hel" + "lo"
+ 'hel' + "lo"
+
+ The following examples show some special strings:
+
+ "\"" - string containing a double quote
+ '"' - string containing a double quote
+ "\n" - string containing a newline character
+ '\n' - string containing a backslash followed
+ by the character n
+
+
+
+
+
+
+Bjorklund Standards Track [Page 46]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following examples show some illegal strings:
+
+ '''' - a single-quoted string cannot contain single quotes
+ """ - a double quote must be escaped in a double-quoted string
+
+ The following strings are equivalent:
+
+ "first line
+ second line"
+
+ "first line\n" + " second line"
+
+6.2. Identifiers
+
+ Identifiers are used to identify different kinds of YANG items by
+ name. Each identifier starts with an uppercase or lowercase ASCII
+ letter or an underscore character, followed by zero or more ASCII
+ letters, digits, underscore characters, hyphens, and dots.
+ Implementations MUST support identifiers up to 64 characters in
+ length and MAY support longer identifiers. Identifiers are case
+ sensitive. The identifier syntax is formally defined by the rule
+ "identifier" in Section 14. Identifiers can be specified as quoted
+ or unquoted strings.
+
+6.2.1. Identifiers and Their Namespaces
+
+ Each identifier is valid in a namespace that depends on the type of
+ the YANG item being defined. All identifiers defined in a namespace
+ MUST be unique.
+
+ o All module and submodule names share the same global module
+ identifier namespace.
+
+ o All extension names defined in a module and its submodules share
+ the same extension identifier namespace.
+
+ o All feature names defined in a module and its submodules share the
+ same feature identifier namespace.
+
+ o All identity names defined in a module and its submodules share
+ the same identity identifier namespace.
+
+ o All derived type names defined within a parent node or at the top
+ level of the module or its submodules share the same type
+ identifier namespace. This namespace is scoped to all descendant
+ nodes of the parent node or module. This means that any
+ descendant node may use that typedef, and it MUST NOT define a
+ typedef with the same name.
+
+
+
+Bjorklund Standards Track [Page 47]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o All grouping names defined within a parent node or at the top
+ level of the module or its submodules share the same grouping
+ identifier namespace. This namespace is scoped to all descendant
+ nodes of the parent node or module. This means that any
+ descendant node may use that grouping, and it MUST NOT define a
+ grouping with the same name.
+
+ o All leafs, leaf-lists, lists, containers, choices, rpcs, actions,
+ notifications, anydatas, and anyxmls defined (directly or through
+ a "uses" statement) within a parent node or at the top level of
+ the module or its submodules share the same identifier namespace.
+ This namespace is scoped to the parent node or module, unless the
+ parent node is a case node. In that case, the namespace is scoped
+ to the closest ancestor node that is not a case or choice node.
+
+ o All cases within a choice share the same case identifier
+ namespace. This namespace is scoped to the parent choice node.
+
+ Forward references are allowed in YANG.
+
+6.3. Statements
+
+ A YANG module contains a sequence of statements. Each statement
+ starts with a keyword, followed by zero or one argument, followed by
+ either a semicolon (";") or a block of substatements enclosed within
+ braces ("{ }"):
+
+ statement = keyword [argument] (";" / "{" *statement "}")
+
+ The argument is a string, as defined in Section 6.1.2.
+
+6.3.1. Language Extensions
+
+ A module can introduce YANG extensions by using the "extension"
+ keyword (see Section 7.19). The extensions can be imported by other
+ modules with the "import" statement (see Section 7.1.5). When an
+ imported extension is used, the extension's keyword MUST be qualified
+ using the prefix with which the extension's module was imported. If
+ an extension is used in the module where it is defined, the
+ extension's keyword MUST be qualified with the prefix of this module.
+
+ The processing of extensions depends on whether support for those
+ extensions is claimed for a given YANG parser or the tool set in
+ which it is embedded. An unsupported extension appearing in a YANG
+ module as an unknown-statement (see Section 14) MAY be ignored in its
+ entirety. Any supported extension MUST be processed in accordance
+ with the specification governing that extension.
+
+
+
+
+Bjorklund Standards Track [Page 48]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Care must be taken when defining extensions so that modules that use
+ the extensions are meaningful also for applications that do not
+ support the extensions.
+
+6.4. XPath Evaluations
+
+ YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation
+ for specifying many inter-node references and dependencies. An
+ implementation is not required to implement an XPath interpreter but
+ MUST ensure that the requirements encoded in the data model are
+ enforced. The manner of enforcement is an implementation decision.
+ The XPath expressions MUST be syntactically correct, and all prefixes
+ used MUST be present in the XPath context (see Section 6.4.1). An
+ implementation may choose to implement them by hand, rather than
+ using the XPath expression directly.
+
+ The data model used in the XPath expressions is the same as that used
+ in XPath 1.0 [XPATH], with the same extension for root node children
+ as used by XSLT 1.0 (see Section 3.1 in [XSLT]). Specifically, it
+ means that the root node may have any number of element nodes as its
+ children.
+
+ The data tree has no concept of document order. An implementation
+ needs to choose some document order, but how it is done is an
+ implementation decision. This means that XPath expressions in YANG
+ modules SHOULD NOT rely on any specific document order.
+
+ Numbers in XPath 1.0 are IEEE 754 [IEEE754-2008] double-precision
+ floating-point values; see Section 3.5 in [XPATH]. This means that
+ some values of int64, uint64, and decimal64 types (see Sections 9.2
+ and 9.3) cannot be exactly represented in XPath expressions.
+ Therefore, due caution should be exercised when using nodes with
+ 64-bit numeric values in XPath expressions. In particular, numerical
+ comparisons involving equality may yield unexpected results.
+
+ For example, consider the following definition:
+
+ leaf lxiv {
+ type decimal64 {
+ fraction-digits 18;
+ }
+ must ". <= 10";
+ }
+
+ An instance of the "lxiv" leaf having the value of
+ 10.0000000000000001 will then successfully pass validation.
+
+
+
+
+
+Bjorklund Standards Track [Page 49]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+6.4.1. XPath Context
+
+ All YANG XPath expressions share the following XPath context
+ definition:
+
+ o The set of namespace declarations is the set of all "import"
+ statements' prefix and namespace pairs in the module where the
+ XPath expression is specified, and the "prefix" statement's prefix
+ for the "namespace" statement's URI.
+
+ o Names without a namespace prefix belong to the same namespace as
+ the identifier of the current node. Inside a grouping, that
+ namespace is affected by where the grouping is used (see
+ Section 7.13). Inside a typedef, that namespace is affected by
+ where the typedef is referenced. If a typedef is defined and
+ referenced within a grouping, the namespace is affected by where
+ the grouping is used (see Section 7.13).
+
+ o The function library is the core function library defined in
+ [XPATH] and the functions defined in Section 10.
+
+ o The set of variable bindings is empty.
+
+ The mechanism for handling unprefixed names is adopted from XPath 2.0
+ [XPATH2.0] and helps simplify XPath expressions in YANG. No
+ ambiguity may ever arise, because YANG node identifiers are always
+ qualified names with a non-null namespace URI.
+
+ The accessible tree depends on where the statement with the XPath
+ expression is defined:
+
+ o If the XPath expression is defined in a substatement to a data
+ node that represents configuration, the accessible tree is the
+ data in the datastore where the context node exists. The root
+ node has all top-level configuration data nodes in all modules as
+ children.
+
+ o If the XPath expression is defined in a substatement to a data
+ node that represents state data, the accessible tree is all state
+ data in the server, and the running configuration datastore. The
+ root node has all top-level data nodes in all modules as children.
+
+ o If the XPath expression is defined in a substatement to a
+ "notification" statement, the accessible tree is the notification
+ instance, all state data in the server, and the running
+ configuration datastore. If the notification is defined on the
+ top level in a module, then the root node has the node
+
+
+
+
+Bjorklund Standards Track [Page 50]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ representing the notification being defined and all top-level data
+ nodes in all modules as children. Otherwise, the root node has
+ all top-level data nodes in all modules as children.
+
+ o If the XPath expression is defined in a substatement to an "input"
+ statement in an "rpc" or "action" statement, the accessible tree
+ is the RPC or action operation instance, all state data in the
+ server, and the running configuration datastore. The root node
+ has top-level data nodes in all modules as children.
+ Additionally, for an RPC, the root node also has the node
+ representing the RPC operation being defined as a child. The node
+ representing the operation being defined has the operation's input
+ parameters as children.
+
+ o If the XPath expression is defined in a substatement to an
+ "output" statement in an "rpc" or "action" statement, the
+ accessible tree is the RPC or action operation instance, all state
+ data in the server, and the running configuration datastore. The
+ root node has top-level data nodes in all modules as children.
+ Additionally, for an RPC, the root node also has the node
+ representing the RPC operation being defined as a child. The node
+ representing the operation being defined has the operation's
+ output parameters as children.
+
+ In the accessible tree, all leafs and leaf-lists with default values
+ in use exist (see Sections 7.6.1 and 7.7.2).
+
+ If a node that exists in the accessible tree has a non-presence
+ container as a child, then the non-presence container also exists in
+ the accessible tree.
+
+ The context node varies with the YANG XPath expression and is
+ specified where the YANG statement with the XPath expression is
+ defined.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 51]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+6.4.1.1. Examples
+
+ Given the following module:
+
+ module example-a {
+ yang-version 1.1;
+ namespace urn:example:a;
+ prefix a;
+
+ container a {
+ list b {
+ key id;
+ leaf id {
+ type string;
+ }
+ notification down {
+ leaf reason {
+ type string;
+ }
+ }
+ action reset {
+ input {
+ leaf delay {
+ type uint32;
+ }
+ }
+ output {
+ leaf result {
+ type string;
+ }
+ }
+ }
+ }
+ }
+ notification failure {
+ leaf b-ref {
+ type leafref {
+ path "/a/b/id";
+ }
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 52]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ and given the following data tree, specified in XML:
+
+ <a xmlns="urn:example:a">
+ <b>
+ <id>1</id>
+ </b>
+ <b>
+ <id>2</id>
+ </b>
+ </a>
+
+ The accessible tree for a notification "down" on /a/b[id="2"] is:
+
+ <a xmlns="urn:example:a">
+ <b>
+ <id>1</id>
+ </b>
+ <b>
+ <id>2</id>
+ <down>
+ <reason>error</reason>
+ </down>
+ </b>
+ </a>
+ // possibly other top-level nodes here
+
+ The accessible tree for an action invocation of "reset" on
+ /a/b[id="1"] with the "when" parameter set to "10" would be:
+
+ <a xmlns="urn:example:a">
+ <b>
+ <id>1</id>
+ <reset>
+ <delay>10</delay>
+ </reset>
+ </b>
+ <b>
+ <id>2</id>
+ </b>
+ </a>
+ // possibly other top-level nodes here
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 53]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The accessible tree for the action output of this action is:
+
+ <a xmlns="urn:example:a">
+ <b>
+ <id>1</id>
+ <reset>
+ <result>ok</result>
+ </reset>
+ </b>
+ <b>
+ <id>2</id>
+ </b>
+ </a>
+ // possibly other top-level nodes here
+
+ The accessible tree for a notification "failure" could be:
+
+ <a xmlns="urn:example:a">
+ <b>
+ <id>1</id>
+ </b>
+ <b>
+ <id>2</id>
+ </b>
+ </a>
+ <failure>
+ <b-ref>2</b-ref>
+ </failure>
+ // possibly other top-level nodes here
+
+6.5. Schema Node Identifier
+
+ A schema node identifier is a string that identifies a node in the
+ schema tree. It has two forms, "absolute" and "descendant", defined
+ by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid"
+ in Section 14, respectively. A schema node identifier consists of a
+ path of identifiers, separated by slashes ("/"). In an absolute
+ schema node identifier, the first identifier after the leading slash
+ is any top-level schema node in the local module or in an imported
+ module.
+
+ References to identifiers defined in external modules MUST be
+ qualified with appropriate prefixes, and references to identifiers
+ defined in the current module and its submodules MAY use a prefix.
+
+ For example, to identify the child node "b" of top-level node "a",
+ the string "/a/b" can be used.
+
+
+
+
+Bjorklund Standards Track [Page 54]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7. YANG Statements
+
+ The following sections describe all of the YANG statements.
+
+ Note that even a statement that does not have any substatements
+ defined in YANG can have vendor-specific extensions as substatements.
+ For example, the "description" statement does not have any
+ substatements defined in YANG, but the following is legal:
+
+ description "Some text." {
+ ex:documentation-flag 5;
+ }
+
+7.1. The "module" Statement
+
+ The "module" statement defines the module's name and groups all
+ statements that belong to the module together. The "module"
+ statement's argument is the name of the module, followed by a block
+ of substatements that holds detailed module information. The module
+ name is an identifier (see Section 6.2).
+
+ Names of modules published in RFC streams [RFC4844] MUST be assigned
+ by IANA; see Section 14 in [RFC6020].
+
+ Private module names are assigned by the organization owning the
+ module without a central registry. See Section 5.1 for
+ recommendations on how to name modules.
+
+ A module typically has the following layout:
+
+ module <module-name> {
+
+ // header information
+ <yang-version statement>
+ <namespace statement>
+ <prefix statement>
+
+ // linkage statements
+ <import statements>
+ <include statements>
+
+ // meta-information
+ <organization statement>
+ <contact statement>
+ <description statement>
+ <reference statement>
+
+
+
+
+
+Bjorklund Standards Track [Page 55]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ // revision history
+ <revision statements>
+
+ // module definitions
+ <other statements>
+ }
+
+7.1.1. The module's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | augment | 7.17 | 0..n |
+ | choice | 7.9 | 0..n |
+ | contact | 7.1.8 | 0..1 |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | deviation | 7.20.3 | 0..n |
+ | extension | 7.19 | 0..n |
+ | feature | 7.20.1 | 0..n |
+ | grouping | 7.12 | 0..n |
+ | identity | 7.18 | 0..n |
+ | import | 7.1.5 | 0..n |
+ | include | 7.1.6 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | namespace | 7.1.3 | 1 |
+ | notification | 7.16 | 0..n |
+ | organization | 7.1.7 | 0..1 |
+ | prefix | 7.1.4 | 1 |
+ | reference | 7.21.4 | 0..1 |
+ | revision | 7.1.9 | 0..n |
+ | rpc | 7.14 | 0..n |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ | yang-version | 7.1.2 | 1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 56]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.1.2. The "yang-version" Statement
+
+ The "yang-version" statement specifies which version of the YANG
+ language was used in developing the module. The statement's argument
+ is a string. It MUST contain the value "1.1" for YANG modules
+ defined based on this specification.
+
+ A module or submodule that doesn't contain the "yang-version"
+ statement, or one that contains the value "1", is developed for YANG
+ version 1, defined in [RFC6020].
+
+ Handling of the "yang-version" statement for versions other than
+ "1.1" (the version defined here) is out of scope for this
+ specification. Any document that defines a higher version will need
+ to define the backward compatibility of such a higher version.
+
+ For compatibility between YANG versions 1 and 1.1, see Section 12.
+
+7.1.3. The "namespace" Statement
+
+ The "namespace" statement defines the XML namespace that all
+ identifiers defined by the module are qualified by in the XML
+ encoding, with the exception of identifiers for data nodes, action
+ nodes, and notification nodes defined inside a grouping (see
+ Section 7.13 for details). The argument to the "namespace" statement
+ is the URI of the namespace.
+
+ See also Section 5.3.
+
+7.1.4. The "prefix" Statement
+
+ The "prefix" statement is used to define the prefix associated with
+ the module and its namespace. The "prefix" statement's argument is
+ the prefix string that is used as a prefix to access a module. The
+ prefix string MAY be used with the module to refer to definitions
+ contained in the module, e.g., "if:ifName". A prefix is an
+ identifier (see Section 6.2).
+
+ When used inside the "module" statement, the "prefix" statement
+ defines the prefix suggested to be used when this module is imported.
+
+ To improve readability of the NETCONF XML, a NETCONF client or server
+ that generates XML or XPath that uses prefixes SHOULD use the prefix
+ defined by the module as the XML namespace prefix, unless there is a
+ conflict.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 57]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ When used inside the "import" statement, the "prefix" statement
+ defines the prefix to be used when accessing definitions inside the
+ imported module. When a reference to an identifier from the imported
+ module is used, the prefix string for the imported module followed by
+ a colon (":") and the identifier is used, e.g., "if:ifIndex". To
+ improve readability of YANG modules, the prefix defined by a module
+ SHOULD be used when the module is imported, unless there is a
+ conflict. If there is a conflict, i.e., two different modules that
+ both have defined the same prefix are imported, at least one of them
+ MUST be imported with a different prefix.
+
+ All prefixes, including the prefix for the module itself, MUST be
+ unique within the module or submodule.
+
+7.1.5. The "import" Statement
+
+ The "import" statement makes definitions from one module available
+ inside another module or submodule. The argument is the name of the
+ module to import, and the statement is followed by a block of
+ substatements that holds detailed import information. When a module
+ is imported, the importing module may:
+
+ o use any grouping and typedef defined at the top level in the
+ imported module or its submodules.
+
+ o use any extension, feature, and identity defined in the imported
+ module or its submodules.
+
+ o use any node in the imported module's schema tree in "must",
+ "path", and "when" statements, or as the target node in "augment"
+ and "deviation" statements.
+
+ The mandatory "prefix" substatement assigns a prefix for the imported
+ module that is scoped to the importing module or submodule. Multiple
+ "import" statements may be specified to import from different
+ modules.
+
+ When the optional "revision-date" substatement is present, any
+ typedef, grouping, extension, feature, and identity referenced by
+ definitions in the local module are taken from the specified revision
+ of the imported module. It is an error if the specified revision of
+ the imported module does not exist. If no "revision-date"
+ substatement is present, it is undefined from which revision of the
+ module they are taken.
+
+ Multiple revisions of the same module can be imported, provided that
+ different prefixes are used.
+
+
+
+
+Bjorklund Standards Track [Page 58]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | prefix | 7.1.4 | 1 |
+ | reference | 7.21.4 | 0..1 |
+ | revision-date | 7.1.5.1 | 0..1 |
+ +---------------+---------+-------------+
+
+ The import's Substatements
+
+7.1.5.1. The import's "revision-date" Statement
+
+ The import's "revision-date" statement is used to specify the version
+ of the module to import.
+
+7.1.6. The "include" Statement
+
+ The "include" statement is used to make content from a submodule
+ available to that submodule's parent module. The argument is an
+ identifier that is the name of the submodule to include. Modules are
+ only allowed to include submodules that belong to that module, as
+ defined by the "belongs-to" statement (see Section 7.2.2).
+
+ When a module includes a submodule, it incorporates the contents of
+ the submodule into the node hierarchy of the module.
+
+ For backward compatibility with YANG version 1, a submodule is
+ allowed to include another submodule belonging to the same module,
+ but this is not necessary in YANG version 1.1 (see Section 5.1).
+
+ When the optional "revision-date" substatement is present, the
+ specified revision of the submodule is included in the module. It is
+ an error if the specified revision of the submodule does not exist.
+ If no "revision-date" substatement is present, it is undefined which
+ revision of the submodule is included.
+
+ Multiple revisions of the same submodule MUST NOT be included.
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | revision-date | 7.1.5.1 | 0..1 |
+ +---------------+---------+-------------+
+
+ The includes's Substatements
+
+
+
+Bjorklund Standards Track [Page 59]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.1.7. The "organization" Statement
+
+ The "organization" statement defines the party responsible for this
+ module. The argument is a string that is used to specify a textual
+ description of the organization(s) under whose auspices this module
+ was developed.
+
+7.1.8. The "contact" Statement
+
+ The "contact" statement provides contact information for the module.
+ The argument is a string that is used to specify contact information
+ for the person or persons to whom technical queries concerning this
+ module should be sent, such as their name, postal address, telephone
+ number, and electronic mail address.
+
+7.1.9. The "revision" Statement
+
+ The "revision" statement specifies the editorial revision history of
+ the module, including the initial revision. A series of "revision"
+ statements detail the changes in the module's definition. The
+ argument is a date string in the format "YYYY-MM-DD", followed by a
+ block of substatements that holds detailed revision information. A
+ module SHOULD have at least one "revision" statement. For every
+ published editorial change, a new one SHOULD be added in front of the
+ revisions sequence so that all revisions are in reverse chronological
+ order.
+
+7.1.9.1. The revision's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 60]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.1.10. Usage Example
+
+ The following example relies on [RFC6991].
+
+ module example-system {
+ yang-version 1.1;
+ namespace "urn:example:system";
+ prefix "sys";
+
+ import ietf-yang-types {
+ prefix "yang";
+ reference "RFC 6991: Common YANG Data Types";
+ }
+
+ include example-types;
+
+ organization "Example Inc.";
+ contact
+ "Joe L. User
+
+ Example Inc.
+ 42 Anywhere Drive
+ Nowhere, CA 95134
+ USA
+
+ Phone: +1 800 555 0100
+ Email: joe@example.com";
+
+ description
+ "The module for entities implementing the Example system.";
+
+ revision 2007-06-09 {
+ description "Initial revision.";
+ }
+
+ // definitions follow...
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 61]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.2. The "submodule" Statement
+
+ While the primary unit in YANG is a module, a YANG module can itself
+ be constructed out of several submodules. Submodules allow a module
+ designer to split a complex model into several pieces where all the
+ submodules contribute to a single namespace, which is defined by the
+ module that includes the submodules.
+
+ The "submodule" statement defines the submodule's name, and it groups
+ all statements that belong to the submodule together. The
+ "submodule" statement's argument is the name of the submodule,
+ followed by a block of substatements that holds detailed submodule
+ information. The submodule name is an identifier (see Section 6.2).
+
+ Names of submodules published in RFC streams [RFC4844] MUST be
+ assigned by IANA; see Section 14 in [RFC6020].
+
+ Private submodule names are assigned by the organization owning the
+ submodule without a central registry. See Section 5.1 for
+ recommendations on how to name submodules.
+
+ A submodule typically has the following layout:
+
+ submodule <module-name> {
+
+ <yang-version statement>
+
+ // module identification
+ <belongs-to statement>
+
+ // linkage statements
+ <import statements>
+
+ // meta-information
+ <organization statement>
+ <contact statement>
+ <description statement>
+ <reference statement>
+
+ // revision history
+ <revision statements>
+
+ // module definitions
+ <other statements>
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 62]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.2.1. The submodule's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | augment | 7.17 | 0..n |
+ | belongs-to | 7.2.2 | 1 |
+ | choice | 7.9 | 0..n |
+ | contact | 7.1.8 | 0..1 |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | deviation | 7.20.3 | 0..n |
+ | extension | 7.19 | 0..n |
+ | feature | 7.20.1 | 0..n |
+ | grouping | 7.12 | 0..n |
+ | identity | 7.18 | 0..n |
+ | import | 7.1.5 | 0..n |
+ | include | 7.1.6 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | notification | 7.16 | 0..n |
+ | organization | 7.1.7 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | revision | 7.1.9 | 0..n |
+ | rpc | 7.14 | 0..n |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ | yang-version | 7.1.2 | 1 |
+ +--------------+---------+-------------+
+
+7.2.2. The "belongs-to" Statement
+
+ The "belongs-to" statement specifies the module to which the
+ submodule belongs. The argument is an identifier that is the name of
+ the module.
+
+ A submodule MUST only be included by either the module to which it
+ belongs or another submodule that belongs to that module.
+
+ The mandatory "prefix" substatement assigns a prefix for the module
+ to which the submodule belongs. All definitions in the module that
+ the submodule belongs to and all its submodules can be accessed by
+ using the prefix.
+
+
+
+
+
+Bjorklund Standards Track [Page 63]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | prefix | 7.1.4 | 1 |
+ +--------------+---------+-------------+
+
+ The belongs-to's Substatement
+
+7.2.3. Usage Example
+
+ submodule example-types {
+ yang-version 1.1;
+ belongs-to "example-system" {
+ prefix "sys";
+ }
+
+ import ietf-yang-types {
+ prefix "yang";
+ }
+
+ organization "Example Inc.";
+ contact
+ "Joe L. User
+
+ Example Inc.
+ 42 Anywhere Drive
+ Nowhere, CA 95134
+ USA
+
+ Phone: +1 800 555 0100
+ Email: joe@example.com";
+
+ description
+ "This submodule defines common Example types.";
+
+ revision "2007-06-09" {
+ description "Initial revision.";
+ }
+
+ // definitions follow...
+ }
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 64]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.3. The "typedef" Statement
+
+ The "typedef" statement defines a new type that may be used locally
+ in the module or submodule, and by other modules that import from it,
+ according to the rules in Section 5.5. The new type is called the
+ "derived type", and the type from which it was derived is called the
+ "base type". All derived types can be traced back to a YANG
+ built-in type.
+
+ The "typedef" statement's argument is an identifier that is the name
+ of the type to be defined and MUST be followed by a block of
+ substatements that holds detailed typedef information.
+
+ The name of the type MUST NOT be one of the YANG built-in types. If
+ the typedef is defined at the top level of a YANG module or
+ submodule, the name of the type to be defined MUST be unique within
+ the module.
+
+7.3.1. The typedef's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | default | 7.3.4 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | type | 7.3.2 | 1 |
+ | units | 7.3.3 | 0..1 |
+ +--------------+---------+-------------+
+
+7.3.2. The typedef's "type" Statement
+
+ The "type" statement, which MUST be present, defines the base type
+ from which this type is derived. See Section 7.4 for details.
+
+7.3.3. The "units" Statement
+
+ The "units" statement, which is optional, takes as an argument a
+ string that contains a textual definition of the units associated
+ with the type.
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 65]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.3.4. The typedef's "default" Statement
+
+ The "default" statement takes as an argument a string that contains a
+ default value for the new type.
+
+ The value of the "default" statement MUST be valid according to the
+ type specified in the "type" statement.
+
+ If the base type has a default value and the new derived type does
+ not specify a new default value, the base type's default value is
+ also the default value of the new derived type.
+
+ If the type's default value is not valid according to the new
+ restrictions specified in a derived type or leaf definition, the
+ derived type or leaf definition MUST specify a new default value
+ compatible with the restrictions.
+
+7.3.5. Usage Example
+
+ typedef listen-ipv4-address {
+ type inet:ipv4-address;
+ default "0.0.0.0";
+ }
+
+7.4. The "type" Statement
+
+ The "type" statement takes as an argument a string that is the name
+ of a YANG built-in type (see Section 9) or a derived type (see
+ Section 7.3), followed by an optional block of substatements that is
+ used to put further restrictions on the type.
+
+ The restrictions that can be applied depend on the type being
+ restricted. The restriction statements for all built-in types are
+ described in the subsections of Section 9.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 66]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.4.1. The type's Substatements
+
+ +------------------+---------+-------------+
+ | substatement | section | cardinality |
+ +------------------+---------+-------------+
+ | base | 7.18.2 | 0..n |
+ | bit | 9.7.4 | 0..n |
+ | enum | 9.6.4 | 0..n |
+ | fraction-digits | 9.3.4 | 0..1 |
+ | length | 9.4.4 | 0..1 |
+ | path | 9.9.2 | 0..1 |
+ | pattern | 9.4.5 | 0..n |
+ | range | 9.2.4 | 0..1 |
+ | require-instance | 9.9.3 | 0..1 |
+ | type | 7.4 | 0..n |
+ +------------------+---------+-------------+
+
+7.5. The "container" Statement
+
+ The "container" statement is used to define an interior data node in
+ the schema tree. It takes one argument, which is an identifier,
+ followed by a block of substatements that holds detailed container
+ information.
+
+ A container node does not have a value, but it has a list of child
+ nodes in the data tree. The child nodes are defined in the
+ container's substatements.
+
+7.5.1. Containers with Presence
+
+ YANG supports two styles of containers, those that exist only for
+ organizing the hierarchy of data nodes and those whose presence in
+ the data tree has an explicit meaning.
+
+ In the first style, the container has no meaning of its own, existing
+ only to contain child nodes. In particular, the presence of the
+ container node with no child nodes is semantically equivalent to the
+ absence of the container node. YANG calls this style a "non-presence
+ container". This is the default style.
+
+ For example, the set of scrambling options for Synchronous Optical
+ Network (SONET) interfaces may be placed inside a "scrambling"
+ container to enhance the organization of the configuration hierarchy
+ and to keep these nodes together. The "scrambling" node itself has
+ no meaning, so removing the node when it becomes empty relieves the
+ user from performing this task.
+
+
+
+
+
+Bjorklund Standards Track [Page 67]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ In the second style, the presence of the container itself carries
+ some meaning, representing a single bit of data.
+
+ For configuration data, the container acts as both a configuration
+ knob and a means of organizing related configuration nodes. These
+ containers are explicitly created and deleted.
+
+ YANG calls this style a "presence container", and it is indicated
+ using the "presence" statement, which takes as its argument a text
+ string indicating what the presence of the node means.
+
+ For example, an "ssh" container may turn on the ability to log into
+ the server using Secure SHell (SSH) but can also contain any
+ SSH-related configuration knobs, such as connection rates or retry
+ limits.
+
+ The "presence" statement (see Section 7.5.5) is used to give
+ semantics to the existence of the container in the data tree.
+
+7.5.2. The container's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | action | 7.15 | 0..n |
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | config | 7.21.1 | 0..1 |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | if-feature | 7.20.2 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | must | 7.5.3 | 0..n |
+ | notification | 7.16 | 0..n |
+ | presence | 7.5.5 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 68]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.5.3. The "must" Statement
+
+ The "must" statement, which is optional, takes as an argument a
+ string that contains an XPath expression (see Section 6.4). It is
+ used to formally declare a constraint on valid data. The constraint
+ is enforced according to the rules in Section 8.
+
+ When a datastore is validated, all "must" constraints are
+ conceptually evaluated once for each node in the accessible tree (see
+ Section 6.4.1).
+
+ All such constraints MUST evaluate to "true" for the data to be
+ valid.
+
+ The XPath expression is conceptually evaluated in the following
+ context, in addition to the definition in Section 6.4.1:
+
+ o If the "must" statement is a substatement of a "notification"
+ statement, the context node is the node representing the
+ notification in the accessible tree.
+
+ o If the "must" statement is a substatement of an "input" statement,
+ the context node is the node representing the operation in the
+ accessible tree.
+
+ o If the "must" statement is a substatement of an "output"
+ statement, the context node is the node representing the operation
+ in the accessible tree.
+
+ o Otherwise, the context node is the node in the accessible tree for
+ which the "must" statement is defined.
+
+ The result of the XPath expression is converted to a boolean value
+ using the standard XPath rules.
+
+ Note that since all leaf values in the data tree are conceptually
+ stored in their canonical form (see Section 9.1), any XPath
+ comparisons are done on the canonical value.
+
+ Also note that the XPath expression is conceptually evaluated. This
+ means that an implementation does not have to use an XPath evaluator
+ in the server. How the evaluation is done in practice is an
+ implementation decision.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 69]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.5.4. The must's Substatements
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | error-app-tag | 7.5.4.2 | 0..1 |
+ | error-message | 7.5.4.1 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ +---------------+---------+-------------+
+
+7.5.4.1. The "error-message" Statement
+
+ The "error-message" statement, which is optional, takes a string as
+ an argument. If the constraint evaluates to "false", the string is
+ passed as <error-message> in the <rpc-error> in NETCONF.
+
+7.5.4.2. The "error-app-tag" Statement
+
+ The "error-app-tag" statement, which is optional, takes a string as
+ an argument. If the constraint evaluates to "false", the string is
+ passed as <error-app-tag> in the <rpc-error> in NETCONF.
+
+7.5.4.3. Usage Example of must and error-message
+
+ container interface {
+ leaf ifType {
+ type enumeration {
+ enum ethernet;
+ enum atm;
+ }
+ }
+ leaf ifMTU {
+ type uint32;
+ }
+ must 'ifType != "ethernet" or ifMTU = 1500' {
+ error-message "An Ethernet MTU must be 1500";
+ }
+ must 'ifType != "atm" or'
+ + ' (ifMTU <= 17966 and ifMTU >= 64)' {
+ error-message "An ATM MTU must be 64 .. 17966";
+ }
+ }
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 70]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.5.5. The "presence" Statement
+
+ The "presence" statement assigns a meaning to the presence of a
+ container in the data tree. It takes as an argument a string that
+ contains a textual description of what the node's presence means.
+
+ If a container has the "presence" statement, the container's
+ existence in the data tree carries some meaning. Otherwise, the
+ container is used to give some structure to the data, and it carries
+ no meaning by itself.
+
+ See Section 7.5.1 for additional information.
+
+7.5.6. The container's Child Node Statements
+
+ Within a container, the "container", "leaf", "list", "leaf-list",
+ "uses", "choice", "anydata", and "anyxml" statements can be used to
+ define child nodes to the container.
+
+7.5.7. XML Encoding Rules
+
+ A container node is encoded as an XML element. The element's local
+ name is the container's identifier, and its namespace is the module's
+ XML namespace (see Section 7.1.3).
+
+ The container's child nodes are encoded as subelements to the
+ container element. If the container defines RPC or action input or
+ output parameters, these subelements are encoded in the same order as
+ they are defined within the "container" statement. Otherwise, the
+ subelements are encoded in any order.
+
+ Any whitespace between the subelements to the container is
+ insignificant, i.e., an implementation MAY insert whitespace
+ characters between subelements.
+
+ If a non-presence container does not have any child nodes, the
+ container may or may not be present in the XML encoding.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 71]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.5.8. NETCONF <edit-config> Operations
+
+ Containers can be created, deleted, replaced, and modified through
+ <edit-config> by using the "operation" attribute (see Section 7.2 in
+ [RFC6241]) in the container's XML element.
+
+ If a container does not have a "presence" statement and the last
+ child node is deleted, the NETCONF server MAY delete the container.
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for the container node are as follows:
+
+ o If the operation is "merge" or "replace", the node is created if
+ it does not exist.
+
+ o If the operation is "create", the node is created if it does not
+ exist. If the node already exists, a "data-exists" error is
+ returned.
+
+ o If the operation is "delete", the node is deleted if it exists.
+ If the node does not exist, a "data-missing" error is returned.
+
+7.5.9. Usage Example
+
+ Given the following container definition:
+
+ container system {
+ description
+ "Contains various system parameters.";
+ container services {
+ description
+ "Configure externally available services.";
+ container "ssh" {
+ presence "Enables SSH";
+ description
+ "SSH service-specific configuration.";
+ // more leafs, containers, and stuff here...
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 72]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A corresponding XML instance example:
+
+ <system>
+ <services>
+ <ssh/>
+ </services>
+ </system>
+
+ Since the <ssh> element is present, SSH is enabled.
+
+ To delete a container with an <edit-config>:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <services>
+ <ssh nc:operation="delete"/>
+ </services>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+7.6. The "leaf" Statement
+
+ The "leaf" statement is used to define a leaf node in the schema
+ tree. It takes one argument, which is an identifier, followed by a
+ block of substatements that holds detailed leaf information.
+
+ A leaf node has a value, but no child nodes, in the data tree.
+ Conceptually, the value in the data tree is always in the canonical
+ form (see Section 9.1).
+
+ A leaf node exists in zero or one instance in the data tree.
+
+ The "leaf" statement is used to define a scalar variable of a
+ particular built-in or derived type.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 73]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.6.1. The leaf's Default Value
+
+ The default value of a leaf is the value that the server uses if the
+ leaf does not exist in the data tree. The usage of the default value
+ depends on the leaf's closest ancestor node in the schema tree that
+ is not a non-presence container (see Section 7.5.1):
+
+ o If no such ancestor exists in the schema tree, the default value
+ MUST be used.
+
+ o Otherwise, if this ancestor is a case node, the default value MUST
+ be used if any node from the case exists in the data tree or the
+ case node is the choice's default case, and if no nodes from any
+ other case exist in the data tree.
+
+ o Otherwise, the default value MUST be used if the ancestor node
+ exists in the data tree.
+
+ In these cases, the default value is said to be in use.
+
+ Note that if the leaf or any of its ancestors has a "when" condition
+ or "if-feature" expression that evaluates to "false", then the
+ default value is not in use.
+
+ When the default value is in use, the server MUST operationally
+ behave as if the leaf was present in the data tree with the default
+ value as its value.
+
+ If a leaf has a "default" statement, the leaf's default value is the
+ value of the "default" statement. Otherwise, if the leaf's type has
+ a default value and the leaf is not mandatory, then the leaf's
+ default value is the type's default value. In all other cases, the
+ leaf does not have a default value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 74]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.6.2. The leaf's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | config | 7.21.1 | 0..1 |
+ | default | 7.6.4 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | mandatory | 7.6.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | type | 7.6.3 | 1 |
+ | units | 7.3.3 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.6.3. The leaf's "type" Statement
+
+ The "type" statement, which MUST be present, takes as an argument the
+ name of an existing built-in or derived type. The optional
+ substatements specify restrictions on this type. See Section 7.4 for
+ details.
+
+7.6.4. The leaf's "default" Statement
+
+ The "default" statement, which is optional, takes as an argument a
+ string that contains a default value for the leaf.
+
+ The value of the "default" statement MUST be valid according to the
+ type specified in the leaf's "type" statement.
+
+ The "default" statement MUST NOT be present on nodes where
+ "mandatory" is "true".
+
+ The definition of the default value MUST NOT be marked with an
+ "if-feature" statement. For example, the following is illegal:
+
+ leaf color {
+ type enumeration {
+ enum blue { if-feature blue; }
+ ...
+ }
+ default blue; // illegal - enum value is conditional
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 75]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.6.5. The leaf's "mandatory" Statement
+
+ The "mandatory" statement, which is optional, takes as an argument
+ the string "true" or "false" and puts a constraint on valid data. If
+ not specified, the default is "false".
+
+ If "mandatory" is "true", the behavior of the constraint depends on
+ the type of the leaf's closest ancestor node in the schema tree that
+ is not a non-presence container (see Section 7.5.1):
+
+ o If no such ancestor exists in the schema tree, the leaf MUST
+ exist.
+
+ o Otherwise, if this ancestor is a case node, the leaf MUST exist if
+ any node from the case exists in the data tree.
+
+ o Otherwise, the leaf MUST exist if the ancestor node exists in the
+ data tree.
+
+ This constraint is enforced according to the rules in Section 8.
+
+7.6.6. XML Encoding Rules
+
+ A leaf node is encoded as an XML element. The element's local name
+ is the leaf's identifier, and its namespace is the module's XML
+ namespace (see Section 7.1.3).
+
+ The value of the leaf node is encoded to XML according to the type
+ and is sent as character data in the element.
+
+ See Section 7.6.8 for an example.
+
+7.6.7. NETCONF <edit-config> Operations
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for the leaf node are as follows:
+
+ o If the operation is "merge" or "replace", the node is created if
+ it does not exist, and its value is set to the value found in the
+ XML RPC data.
+
+ o If the operation is "create", the node is created if it does not
+ exist. If the node already exists, a "data-exists" error is
+ returned.
+
+ o If the operation is "delete", the node is deleted if it exists.
+ If the node does not exist, a "data-missing" error is returned.
+
+
+
+
+Bjorklund Standards Track [Page 76]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.6.8. Usage Example
+
+ Given the following "leaf" statement, placed in the previously
+ defined "ssh" container (see Section 7.5.9):
+
+ leaf port {
+ type inet:port-number;
+ default 22;
+ description
+ "The port to which the SSH server listens.";
+ }
+
+ A corresponding XML instance example:
+
+ <port>2022</port>
+
+ To set the value of a leaf with an <edit-config>:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <services>
+ <ssh>
+ <port>2022</port>
+ </ssh>
+ </services>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+7.7. The "leaf-list" Statement
+
+ Where the "leaf" statement is used to define a simple scalar variable
+ of a particular type, the "leaf-list" statement is used to define an
+ array of a particular type. The "leaf-list" statement takes one
+ argument, which is an identifier, followed by a block of
+ substatements that holds detailed leaf-list information.
+
+ In configuration data, the values in a leaf-list MUST be unique.
+
+
+
+
+
+Bjorklund Standards Track [Page 77]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The definitions of the default values MUST NOT be marked with an
+ "if-feature" statement.
+
+ Conceptually, the values in the data tree MUST be in the canonical
+ form (see Section 9.1).
+
+7.7.1. Ordering
+
+ YANG supports two styles for ordering the entries within lists and
+ leaf-lists. In many lists, the order of list entries does not impact
+ the implementation of the list's configuration, and the server is
+ free to sort the list entries in any reasonable order. The
+ "description" string for the list may suggest an order to the server
+ implementor. YANG calls this style of list "system ordered"; such
+ lists are indicated with the statement "ordered-by system".
+
+ For example, a list of valid users would typically be sorted
+ alphabetically, since the order in which the users appeared in the
+ configuration would not impact the creation of those users' accounts.
+
+ In the other style of lists, the order of list entries matters for
+ the implementation of the list's configuration and the user is
+ responsible for ordering the entries, while the server maintains that
+ order. YANG calls this style of list "user ordered"; such lists are
+ indicated with the statement "ordered-by user".
+
+ For example, the order in which packet filter entries are applied to
+ incoming traffic may affect how that traffic is filtered. The user
+ would need to decide if the filter entry that discards all TCP
+ traffic should be applied before or after the filter entry that
+ allows all traffic from trusted interfaces. The choice of order
+ would be crucial.
+
+ YANG provides a rich set of facilities within NETCONF's <edit-config>
+ operation that allows the order of list entries in user-ordered lists
+ to be controlled. List entries may be inserted or rearranged,
+ positioned as the first or last entry in the list, or positioned
+ before or after another specific entry.
+
+ The "ordered-by" statement is covered in Section 7.7.7.
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 78]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.7.2. The leaf-list's Default Values
+
+ The default values of a leaf-list are the values that the server uses
+ if the leaf-list does not exist in the data tree. The usage of the
+ default values depends on the leaf-list's closest ancestor node in
+ the schema tree that is not a non-presence container (see
+ Section 7.5.1):
+
+ o If no such ancestor exists in the schema tree, the default values
+ MUST be used.
+
+ o Otherwise, if this ancestor is a case node, the default values
+ MUST be used if any node from the case exists in the data tree or
+ the case node is the choice's default case, and if no nodes from
+ any other case exist in the data tree.
+
+ o Otherwise, the default values MUST be used if the ancestor node
+ exists in the data tree.
+
+ In these cases, the default values are said to be in use.
+
+ Note that if the leaf-list or any of its ancestors has a "when"
+ condition or "if-feature" expression that evaluates to "false", then
+ the default values are not in use.
+
+ When the default values are in use, the server MUST operationally
+ behave as if the leaf-list was present in the data tree with the
+ default values as its values.
+
+ If a leaf-list has one or more "default" statements, the leaf-list's
+ default values are the values of the "default" statements, and if the
+ leaf-list is user ordered, the default values are used in the order
+ of the "default" statements. Otherwise, if the leaf-list's type has
+ a default value and the leaf-list does not have a "min-elements"
+ statement with a value greater than or equal to one, then the
+ leaf-list's default value is one instance of the type's default
+ value. In all other cases, the leaf-list does not have any default
+ values.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 79]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.7.3. The leaf-list's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | config | 7.21.1 | 0..1 |
+ | default | 7.7.4 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | max-elements | 7.7.6 | 0..1 |
+ | min-elements | 7.7.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | ordered-by | 7.7.7 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | type | 7.4 | 1 |
+ | units | 7.3.3 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.7.4. The leaf-list's "default" Statement
+
+ The "default" statement, which is optional, takes as an argument a
+ string that contains a default value for the leaf-list.
+
+ The value of the "default" statement MUST be valid according to the
+ type specified in the leaf-list's "type" statement.
+
+ The "default" statement MUST NOT be present on nodes where
+ "min-elements" has a value greater than or equal to one.
+
+7.7.5. The "min-elements" Statement
+
+ The "min-elements" statement, which is optional, takes as an argument
+ a non-negative integer that puts a constraint on valid list entries.
+ A valid leaf-list or list MUST have at least min-elements entries.
+
+ If no "min-elements" statement is present, it defaults to zero.
+
+ The behavior of the constraint depends on the type of the leaf-list's
+ or list's closest ancestor node in the schema tree that is not a
+ non-presence container (see Section 7.5.1):
+
+ o If no such ancestor exists in the schema tree, the constraint is
+ enforced.
+
+ o Otherwise, if this ancestor is a case node, the constraint is
+ enforced if any other node from the case exists.
+
+
+
+Bjorklund Standards Track [Page 80]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o Otherwise, it is enforced if the ancestor node exists.
+
+ The constraint is further enforced according to the rules in
+ Section 8.
+
+7.7.6. The "max-elements" Statement
+
+ The "max-elements" statement, which is optional, takes as an argument
+ a positive integer or the string "unbounded", which puts a constraint
+ on valid list entries. A valid leaf-list or list always has at most
+ max-elements entries.
+
+ If no "max-elements" statement is present, it defaults to
+ "unbounded".
+
+ The "max-elements" constraint is enforced according to the rules in
+ Section 8.
+
+7.7.7. The "ordered-by" Statement
+
+ The "ordered-by" statement defines whether the order of entries
+ within a list are determined by the user or the system. The argument
+ is one of the strings "system" or "user". If not present, ordering
+ defaults to "system".
+
+ This statement is ignored if the list represents state data, RPC
+ output parameters, or notification content.
+
+ See Section 7.7.1 for additional information.
+
+7.7.7.1. ordered-by system
+
+ The entries in the list are ordered according to an order determined
+ by the system. The "description" string for the list may suggest an
+ order to the server implementor. If not, an implementation is free
+ to order the entries in any order. An implementation SHOULD use the
+ same order for the same data, regardless of how the data were
+ created. Using a deterministic order will make comparisons possible
+ using simple tools like "diff".
+
+ This is the default order.
+
+7.7.7.2. ordered-by user
+
+ The entries in the list are ordered according to an order defined by
+ the user. In NETCONF, this order is controlled by using special XML
+ attributes in the <edit-config> request. See Section 7.7.9 for
+ details.
+
+
+
+Bjorklund Standards Track [Page 81]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.7.8. XML Encoding Rules
+
+ A leaf-list node is encoded as a series of XML elements. Each
+ element's local name is the leaf-list's identifier, and its namespace
+ is the module's XML namespace (see Section 7.1.3).
+
+ The value of each leaf-list entry is encoded to XML according to the
+ type and is sent as character data in the element.
+
+ The XML elements representing leaf-list entries MUST appear in the
+ order specified by the user if the leaf-list is "ordered-by user";
+ otherwise, the order is implementation dependent. The XML elements
+ representing leaf-list entries MAY be interleaved with elements for
+ siblings of the leaf-list, unless the leaf-list defines RPC or action
+ input or output parameters.
+
+ See Section 7.7.10 for an example.
+
+7.7.9. NETCONF <edit-config> Operations
+
+ Leaf-list entries can be created and deleted, but not modified,
+ through <edit-config>, by using the "operation" attribute in the
+ leaf-list entry's XML element.
+
+ In an "ordered-by user" leaf-list, the attributes "insert" and
+ "value" in the YANG XML namespace (Section 5.3.1) can be used to
+ control where in the leaf-list the entry is inserted. These can be
+ used during "create" operations to insert a new leaf-list entry, or
+ during "merge" or "replace" operations to insert a new leaf-list
+ entry or move an existing one.
+
+ The "insert" attribute can take the values "first", "last", "before",
+ and "after". If the value is "before" or "after", the "value"
+ attribute MUST also be used to specify an existing entry in the
+ leaf-list.
+
+ If no "insert" attribute is present in the "create" operation, it
+ defaults to "last".
+
+ If several entries in an "ordered-by user" leaf-list are modified in
+ the same <edit-config> request, the entries are modified one at a
+ time, in the order of the XML elements in the request.
+
+ In a <copy-config> or in an <edit-config> with a "replace" operation
+ that covers the entire leaf-list, the leaf-list order is the same as
+ the order of the XML elements in the request.
+
+
+
+
+
+Bjorklund Standards Track [Page 82]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for a leaf-list node are as follows:
+
+ o If the operation is "merge" or "replace", the leaf-list entry is
+ created if it does not exist.
+
+ o If the operation is "create", the leaf-list entry is created if it
+ does not exist. If the leaf-list entry already exists, a
+ "data-exists" error is returned.
+
+ o If the operation is "delete", the entry is deleted from the
+ leaf-list if it exists. If the leaf-list entry does not exist, a
+ "data-missing" error is returned.
+
+7.7.10. Usage Example
+
+ leaf-list allow-user {
+ type string;
+ description
+ "A list of user name patterns to allow.";
+ }
+
+ A corresponding XML instance example:
+
+ <allow-user>alice</allow-user>
+ <allow-user>bob</allow-user>
+
+ To create a new element in this list, using the default <edit-config>
+ operation "merge":
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <services>
+ <ssh>
+ <allow-user>eric</allow-user>
+ </ssh>
+ </services>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+
+
+Bjorklund Standards Track [Page 83]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Given the following ordered-by user leaf-list:
+
+ leaf-list cipher {
+ type string;
+ ordered-by user;
+ description
+ "A list of ciphers.";
+ }
+
+ The following would be used to insert a new cipher "blowfish-cbc"
+ after "3des-cbc":
+
+ <rpc message-id="102"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:yang="urn:ietf:params:xml:ns:yang:1">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <services>
+ <ssh>
+ <cipher nc:operation="create"
+ yang:insert="after"
+ yang:value="3des-cbc">blowfish-cbc</cipher>
+ </ssh>
+ </services>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+7.8. The "list" Statement
+
+ The "list" statement is used to define an interior data node in the
+ schema tree. A list node may exist in multiple instances in the data
+ tree. Each such instance is known as a list entry. The "list"
+ statement takes one argument, which is an identifier, followed by a
+ block of substatements that holds detailed list information.
+
+ A list entry is uniquely identified by the values of the list's keys,
+ if defined.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 84]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.8.1. The list's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | action | 7.15 | 0..n |
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | config | 7.21.1 | 0..1 |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | if-feature | 7.20.2 | 0..n |
+ | key | 7.8.2 | 0..1 |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | max-elements | 7.7.6 | 0..1 |
+ | min-elements | 7.7.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | notification | 7.16 | 0..n |
+ | ordered-by | 7.7.7 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ | unique | 7.8.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.8.2. The list's "key" Statement
+
+ The "key" statement, which MUST be present if the list represents
+ configuration and MAY be present otherwise, takes as an argument a
+ string that specifies a space-separated list of one or more leaf
+ identifiers of this list. A leaf identifier MUST NOT appear more
+ than once in the key. Each such leaf identifier MUST refer to a
+ child leaf of the list. The leafs can be defined directly in
+ substatements to the list or in groupings used in the list.
+
+ The combined values of all the leafs specified in the key are used to
+ uniquely identify a list entry. All key leafs MUST be given values
+ when a list entry is created. Thus, any default values in the key
+ leafs or their types are ignored. Any "mandatory" statements in the
+ key leafs are ignored.
+
+
+
+
+
+Bjorklund Standards Track [Page 85]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A leaf that is part of the key can be of any built-in or
+ derived type.
+
+ All key leafs in a list MUST have the same value for their "config"
+ as the list itself.
+
+ The key string syntax is formally defined by the rule "key-arg" in
+ Section 14.
+
+7.8.3. The list's "unique" Statement
+
+ The "unique" statement is used to put constraints on valid list
+ entries. It takes as an argument a string that contains a space-
+ separated list of schema node identifiers, which MUST be given in the
+ descendant form (see the rule "descendant-schema-nodeid" in
+ Section 14). Each such schema node identifier MUST refer to a leaf.
+
+ If one of the referenced leafs represents configuration data, then
+ all of the referenced leafs MUST represent configuration data.
+
+ The "unique" constraint specifies that the combined values of all the
+ leaf instances specified in the argument string, including leafs with
+ default values, MUST be unique within all list entry instances in
+ which all referenced leafs exist or have default values. The
+ constraint is enforced according to the rules in Section 8.
+
+ The unique string syntax is formally defined by the rule "unique-arg"
+ in Section 14.
+
+7.8.3.1. Usage Example
+
+ With the following list:
+
+ list server {
+ key "name";
+ unique "ip port";
+ leaf name {
+ type string;
+ }
+ leaf ip {
+ type inet:ip-address;
+ }
+ leaf port {
+ type inet:port-number;
+ }
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 86]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ the following configuration is not valid:
+
+ <server>
+ <name>smtp</name>
+ <ip>192.0.2.1</ip>
+ <port>25</port>
+ </server>
+
+ <server>
+ <name>http</name>
+ <ip>192.0.2.1</ip>
+ <port>25</port>
+ </server>
+
+ The following configuration is valid, since the "http" and "ftp" list
+ entries do not have a value for all referenced leafs and are thus not
+ taken into account when the "unique" constraint is enforced:
+
+ <server>
+ <name>smtp</name>
+ <ip>192.0.2.1</ip>
+ <port>25</port>
+ </server>
+
+ <server>
+ <name>http</name>
+ <ip>192.0.2.1</ip>
+ </server>
+
+ <server>
+ <name>ftp</name>
+ <ip>192.0.2.1</ip>
+ </server>
+
+7.8.4. The list's Child Node Statements
+
+ Within a list, the "container", "leaf", "list", "leaf-list", "uses",
+ "choice", "anydata", and "anyxml" statements can be used to define
+ child nodes to the list.
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 87]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.8.5. XML Encoding Rules
+
+ A list is encoded as a series of XML elements, one for each entry in
+ the list. Each element's local name is the list's identifier, and
+ its namespace is the module's XML namespace (see Section 7.1.3).
+ There is no XML element surrounding the list as a whole.
+
+ The list's key nodes are encoded as subelements to the list's
+ identifier element, in the same order as they are defined within the
+ "key" statement.
+
+ The rest of the list's child nodes are encoded as subelements to the
+ list element, after the keys. If the list defines RPC or action
+ input or output parameters, the subelements are encoded in the same
+ order as they are defined within the "list" statement. Otherwise,
+ the subelements are encoded in any order.
+
+ Any whitespace between the subelements to the list entry is
+ insignificant, i.e., an implementation MAY insert whitespace
+ characters between subelements.
+
+ The XML elements representing list entries MUST appear in the order
+ specified by the user if the list is "ordered-by user"; otherwise,
+ the order is implementation dependent. The XML elements representing
+ list entries MAY be interleaved with elements for siblings of the
+ list, unless the list defines RPC or action input or output
+ parameters.
+
+7.8.6. NETCONF <edit-config> Operations
+
+ List entries can be created, deleted, replaced, and modified through
+ <edit-config> by using the "operation" attribute in the list's XML
+ element. In each case, the values of all keys are used to uniquely
+ identify a list entry. If all keys are not specified for a list
+ entry, a "missing-element" error is returned.
+
+ In an "ordered-by user" list, the attributes "insert" and "key" in
+ the YANG XML namespace (Section 5.3.1) can be used to control where
+ in the list the entry is inserted. These can be used during "create"
+ operations to insert a new list entry, or during "merge" or "replace"
+ operations to insert a new list entry or move an existing one.
+
+ The "insert" attribute can take the values "first", "last", "before",
+ and "after". If the value is "before" or "after", the "key"
+ attribute MUST also be used, to specify an existing element in the
+ list. The value of the "key" attribute is the key predicates of the
+ full instance identifier (see Section 9.13) for the list entry.
+
+
+
+
+Bjorklund Standards Track [Page 88]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If no "insert" attribute is present in the "create" operation, it
+ defaults to "last".
+
+ If several entries in an "ordered-by user" list are modified in the
+ same <edit-config> request, the entries are modified one at a time,
+ in the order of the XML elements in the request.
+
+ In a <copy-config> or in an <edit-config> with a "replace" operation
+ that covers the entire list, the list entry order is the same as the
+ order of the XML elements in the request.
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for a list node are as follows:
+
+ o If the operation is "merge" or "replace", the list entry is
+ created if it does not exist. If the list entry already exists
+ and the "insert" and "key" attributes are present, the list entry
+ is moved according to the values of the "insert" and "key"
+ attributes. If the list entry exists and the "insert" and "key"
+ attributes are not present, the list entry is not moved.
+
+ o If the operation is "create", the list entry is created if it does
+ not exist. If the list entry already exists, a "data-exists"
+ error is returned.
+
+ o If the operation is "delete", the entry is deleted from the list
+ if it exists. If the list entry does not exist, a "data-missing"
+ error is returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 89]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.8.7. Usage Example
+
+ Given the following list:
+
+ list user {
+ key "name";
+ config true;
+ description
+ "This is a list of users in the system.";
+
+ leaf name {
+ type string;
+ }
+ leaf type {
+ type string;
+ }
+ leaf full-name {
+ type string;
+ }
+ }
+
+ A corresponding XML instance example:
+
+ <user>
+ <name>fred</name>
+ <type>admin</type>
+ <full-name>Fred Flintstone</full-name>
+ </user>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 90]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ To create a new user "barney":
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <user nc:operation="create">
+ <name>barney</name>
+ <type>admin</type>
+ <full-name>Barney Rubble</full-name>
+ </user>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+ To change the type of "fred" to "superuser":
+
+ <rpc message-id="102"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <user>
+ <name>fred</name>
+ <type>superuser</type>
+ </user>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 91]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Given the following ordered-by user list:
+
+ list user {
+ description
+ "This is a list of users in the system.";
+ ordered-by user;
+ config true;
+
+ key "first-name surname";
+
+ leaf first-name {
+ type string;
+ }
+ leaf surname {
+ type string;
+ }
+ leaf type {
+ type string;
+ }
+ }
+
+ The following would be used to insert a new user "barney rubble"
+ after the user "fred flintstone":
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:yang="urn:ietf:params:xml:ns:yang:1">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config"
+ xmlns:ex="urn:example:config">
+ <user nc:operation="create"
+ yang:insert="after"
+ yang:key="[ex:first-name='fred']
+ [ex:surname='flintstone']">
+ <first-name>barney</first-name>
+ <surname>rubble</surname>
+ <type>admin</type>
+ </user>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+
+
+
+Bjorklund Standards Track [Page 92]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following would be used to move the user "barney rubble" before
+ the user "fred flintstone":
+
+ <rpc message-id="102"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:yang="urn:ietf:params:xml:ns:yang:1">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config"
+ xmlns:ex="urn:example:config">
+ <user nc:operation="merge"
+ yang:insert="before"
+ yang:key="[ex:name='fred']
+ [ex:surname='flintstone']">
+ <first-name>barney</first-name>
+ <surname>rubble</surname>
+ </user>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+7.9. The "choice" Statement
+
+ The "choice" statement defines a set of alternatives, only one of
+ which may be present in any one data tree. The argument is an
+ identifier, followed by a block of substatements that holds detailed
+ choice information. The identifier is used to identify the choice
+ node in the schema tree. A choice node does not exist in the data
+ tree.
+
+ A choice consists of a number of branches, each defined with a "case"
+ substatement. Each branch contains a number of child nodes. The
+ nodes from at most one of the choice's branches exist at the same
+ time.
+
+ Since only one of the choice's cases can be valid at any time in the
+ data tree, the creation of a node from one case implicitly deletes
+ all nodes from all other cases. If a request creates a node from a
+ case, the server will delete any existing nodes that are defined in
+ other cases inside the choice.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 93]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.9.1. The choice's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | case | 7.9.2 | 0..n |
+ | choice | 7.9 | 0..n |
+ | config | 7.21.1 | 0..1 |
+ | container | 7.5 | 0..n |
+ | default | 7.9.3 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | mandatory | 7.9.4 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.9.2. The choice's "case" Statement
+
+ The "case" statement is used to define branches of the choice. It
+ takes as an argument an identifier, followed by a block of
+ substatements that holds detailed case information.
+
+ The identifier is used to identify the case node in the schema tree.
+ A case node does not exist in the data tree.
+
+ Within a "case" statement, the "anydata", "anyxml", "choice",
+ "container", "leaf", "list", "leaf-list", and "uses" statements can
+ be used to define child nodes to the case node. The identifiers of
+ all these child nodes MUST be unique within all cases in a choice.
+ For example, the following is illegal:
+
+ choice interface-type { // This example is illegal YANG
+ case a {
+ leaf ethernet { ... }
+ }
+ case b {
+ container ethernet { ...}
+ }
+ }
+
+
+
+
+
+Bjorklund Standards Track [Page 94]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ As a shorthand, the "case" statement can be omitted if the branch
+ contains a single "anydata", "anyxml", "choice", "container", "leaf",
+ "list", or "leaf-list" statement. In this case, the case node still
+ exists in the schema tree, and its identifier is the same as the
+ identifier of the child node. Schema node identifiers (Section 6.5)
+ MUST always explicitly include case node identifiers. The following
+ example:
+
+ choice interface-type {
+ container ethernet { ... }
+ }
+
+ is equivalent to:
+
+ choice interface-type {
+ case ethernet {
+ container ethernet { ... }
+ }
+ }
+
+ The case identifier MUST be unique within a choice.
+
+7.9.2.1. The case's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | uses | 7.13 | 0..n |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 95]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.9.3. The choice's "default" Statement
+
+ The "default" statement indicates if a case should be considered as
+ the default if no child nodes from any of the choice's cases exist.
+ The argument is the identifier of the default "case" statement. If
+ the "default" statement is missing, there is no default case.
+
+ The "default" statement MUST NOT be present on choices where
+ "mandatory" is "true".
+
+ The default case is only important when considering the "default"
+ statements of nodes under the cases (i.e., default values of leafs
+ and leaf-lists, and default cases of nested choices). The default
+ values and nested default cases under the default case are used if
+ none of the nodes under any of the cases are present.
+
+ There MUST NOT be any mandatory nodes (Section 3) directly under the
+ default case.
+
+ Default values for child nodes under a case are only used if one of
+ the nodes under that case is present or if that case is the default
+ case. If none of the nodes under a case are present and the case is
+ not the default case, the default values of the cases' child nodes
+ are ignored.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 96]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ In this example, the choice defaults to "interval", and the default
+ value will be used if none of "daily", "time-of-day", or "manual" are
+ present. If "daily" is present, the default value for "time-of-day"
+ will be used.
+
+ container transfer {
+ choice how {
+ default interval;
+ case interval {
+ leaf interval {
+ type uint16;
+ units minutes;
+ default 30;
+ }
+ }
+ case daily {
+ leaf daily {
+ type empty;
+ }
+ leaf time-of-day {
+ type string;
+ units 24-hour-clock;
+ default "01.00";
+ }
+ }
+ case manual {
+ leaf manual {
+ type empty;
+ }
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 97]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.9.4. The choice's "mandatory" Statement
+
+ The "mandatory" statement, which is optional, takes as an argument
+ the string "true" or "false" and puts a constraint on valid data. If
+ "mandatory" is "true", at least one node from exactly one of the
+ choice's case branches MUST exist.
+
+ If not specified, the default is "false".
+
+ The behavior of the constraint depends on the type of the choice's
+ closest ancestor node in the schema tree that is not a non-presence
+ container (see Section 7.5.1):
+
+ o If no such ancestor exists in the schema tree, the constraint is
+ enforced.
+
+ o Otherwise, if this ancestor is a case node, the constraint is
+ enforced if any other node from the case exists.
+
+ o Otherwise, it is enforced if the ancestor node exists.
+
+ The constraint is further enforced according to the rules in
+ Section 8.
+
+7.9.5. XML Encoding Rules
+
+ The choice and case nodes are not visible in XML.
+
+ The child nodes of the selected "case" statement MUST be encoded in
+ the same order as they are defined in the "case" statement if they
+ are part of an RPC or action input or output parameter definition.
+ Otherwise, the subelements are encoded in any order.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 98]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.9.6. Usage Example
+
+ Given the following choice:
+
+ container protocol {
+ choice name {
+ case a {
+ leaf udp {
+ type empty;
+ }
+ }
+ case b {
+ leaf tcp {
+ type empty;
+ }
+ }
+ }
+ }
+
+ A corresponding XML instance example:
+
+ <protocol>
+ <tcp/>
+ </protocol>
+
+ To change the protocol from TCP to UDP:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
+ xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <edit-config>
+ <target>
+ <running/>
+ </target>
+ <config>
+ <system xmlns="urn:example:config">
+ <protocol>
+ <udp nc:operation="create"/>
+ </protocol>
+ </system>
+ </config>
+ </edit-config>
+ </rpc>
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 99]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.10. The "anydata" Statement
+
+ The "anydata" statement defines an interior node in the schema tree.
+ It takes one argument, which is an identifier, followed by a block of
+ substatements that holds detailed anydata information.
+
+ The "anydata" statement is used to represent an unknown set of nodes
+ that can be modeled with YANG, except anyxml, but for which the data
+ model is not known at module design time. It is possible, though not
+ required, for the data model for anydata content to become known
+ through protocol signaling or other means that are outside the scope
+ of this document.
+
+ An example of where anydata can be useful is a list of received
+ notifications where the specific notifications are not known at
+ design time.
+
+ An anydata node cannot be augmented (see Section 7.17).
+
+ An anydata node exists in zero or one instance in the data tree.
+
+ An implementation may or may not know the data model used to model a
+ specific instance of an anydata node.
+
+ Since the use of anydata limits the manipulation of the content, the
+ "anydata" statement SHOULD NOT be used to define configuration data.
+
+7.10.1. The anydata's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | config | 7.21.1 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | mandatory | 7.6.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 100]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.10.2. XML Encoding Rules
+
+ An anydata node is encoded as an XML element. The element's local
+ name is the anydata's identifier, and its namespace is the module's
+ XML namespace (see Section 7.1.3). The value of the anydata node is
+ a set of nodes, which are encoded as XML subelements to the anydata
+ element.
+
+7.10.3. NETCONF <edit-config> Operations
+
+ An anydata node is treated as an opaque chunk of data. This data can
+ be modified in its entirety only.
+
+ Any "operation" attributes present on subelements of an anydata node
+ are ignored by the NETCONF server.
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for the anydata node are as follows:
+
+ o If the operation is "merge" or "replace", the node is created if
+ it does not exist, and its value is set to the subelements of the
+ anydata node found in the XML RPC data.
+
+ o If the operation is "create", the node is created if it does not
+ exist, and its value is set to the subelements of the anydata node
+ found in the XML RPC data. If the node already exists, a
+ "data-exists" error is returned.
+
+ o If the operation is "delete", the node is deleted if it exists.
+ If the node does not exist, a "data-missing" error is returned.
+
+7.10.4. Usage Example
+
+ Given the following "anydata" statement:
+
+ list logged-notification {
+ key time;
+ leaf time {
+ type yang:date-and-time;
+ }
+ anydata data;
+ }
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 101]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following is a valid encoding of such a list instance:
+
+ <logged-notification>
+ <time>2014-07-29T13:43:12Z</time>
+ <data>
+ <notification
+ xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ <eventTime>2014-07-29T13:43:01Z</eventTime>
+ <event xmlns="urn:example:event">
+ <event-class>fault</event-class>
+ <reporting-entity>
+ <card>Ethernet0</card>
+ </reporting-entity>
+ <severity>major</severity>
+ </event>
+ </notification>
+ </data>
+ </logged-notification>
+
+7.11. The "anyxml" Statement
+
+ The "anyxml" statement defines an interior node in the schema tree.
+ It takes one argument, which is an identifier, followed by a block of
+ substatements that holds detailed anyxml information.
+
+ The "anyxml" statement is used to represent an unknown chunk of XML.
+ No restrictions are placed on the XML. This can be useful, for
+ example, in RPC replies. An example is the <filter> parameter in the
+ <get-config> operation in NETCONF.
+
+ An anyxml node cannot be augmented (see Section 7.17).
+
+ An anyxml node exists in zero or one instance in the data tree.
+
+ Since the use of anyxml limits the manipulation of the content, the
+ "anyxml" statement SHOULD NOT be used to define configuration data.
+
+ It should be noted that in YANG version 1, "anyxml" was the only
+ statement that could model an unknown hierarchy of data. In many
+ cases, this unknown hierarchy of data is actually modeled in YANG,
+ but the specific YANG data model is not known at design time. In
+ these situations, it is RECOMMENDED to use "anydata" (Section 7.10)
+ instead of "anyxml".
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 102]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.11.1. The anyxml's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | config | 7.21.1 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | mandatory | 7.6.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.11.2. XML Encoding Rules
+
+ An anyxml node is encoded as an XML element. The element's local
+ name is the anyxml's identifier, and its namespace is the module's
+ XML namespace (see Section 7.1.3). The value of the anyxml node is
+ encoded as XML content of this element.
+
+ Note that any XML prefixes used in the encoding are local to each
+ instance encoding. This means that the same XML may be encoded
+ differently by different implementations.
+
+7.11.3. NETCONF <edit-config> Operations
+
+ An anyxml node is treated as an opaque chunk of data. This data can
+ be modified in its entirety only.
+
+ Any "operation" attributes present on subelements of an anyxml node
+ are ignored by the NETCONF server.
+
+ When a NETCONF server processes an <edit-config> request, the
+ elements of procedure for the anyxml node are as follows:
+
+ o If the operation is "merge" or "replace", the node is created if
+ it does not exist, and its value is set to the XML content of the
+ anyxml node found in the XML RPC data.
+
+ o If the operation is "create", the node is created if it does not
+ exist, and its value is set to the XML content of the anyxml node
+ found in the XML RPC data. If the node already exists, a
+ "data-exists" error is returned.
+
+ o If the operation is "delete", the node is deleted if it exists.
+ If the node does not exist, a "data-missing" error is returned.
+
+
+
+Bjorklund Standards Track [Page 103]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.11.4. Usage Example
+
+ Given the following "anyxml" statement:
+
+ anyxml html-info;
+
+ The following are two valid encodings of the same anyxml value:
+
+ <html-info>
+ <p xmlns="http://www.w3.org/1999/xhtml">
+ This is <em>very</em> cool.
+ </p>
+ </html-info>
+
+ <html-info>
+ <x:p xmlns:x="http://www.w3.org/1999/xhtml">
+ This is <x:em>very</x:em> cool.
+ </x:p>
+ </html-info>
+
+7.12. The "grouping" Statement
+
+ The "grouping" statement is used to define a reusable block of nodes,
+ which may be used locally in the module or submodule, and by other
+ modules that import from it, according to the rules in Section 5.5.
+ It takes one argument, which is an identifier, followed by a block of
+ substatements that holds detailed grouping information.
+
+ The "grouping" statement is not a data definition statement and, as
+ such, does not define any nodes in the schema tree.
+
+ A grouping is like a "structure" or a "record" in conventional
+ programming languages.
+
+ Once a grouping is defined, it can be referenced in a "uses"
+ statement (see Section 7.13). A grouping MUST NOT reference itself,
+ neither directly nor indirectly through a chain of other groupings.
+
+ If the grouping is defined at the top level of a YANG module or
+ submodule, the grouping's identifier MUST be unique within the
+ module.
+
+ A grouping is more than just a mechanism for textual substitution;
+ it also defines a collection of nodes. Identifiers appearing inside
+ the grouping are resolved relative to the scope in which the grouping
+ is defined, not where it is used. Prefix mappings, type names,
+ grouping names, and extension usage are evaluated in the hierarchy
+
+
+
+
+Bjorklund Standards Track [Page 104]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ where the "grouping" statement appears. For extensions, this means
+ that extensions defined as direct children to a "grouping" statement
+ are applied to the grouping itself.
+
+ Note that if a grouping defines an action or a notification node in
+ its hierarchy, then it cannot be used in all contexts. For example,
+ it cannot be used in an rpc definition. See Sections 7.15 and 7.16.
+
+7.12.1. The grouping's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | action | 7.15 | 0..n |
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | notification | 7.16 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ +--------------+---------+-------------+
+
+7.12.2. Usage Example
+
+ import ietf-inet-types {
+ prefix "inet";
+ }
+
+ grouping endpoint {
+ description "A reusable endpoint group.";
+ leaf ip {
+ type inet:ip-address;
+ }
+ leaf port {
+ type inet:port-number;
+ }
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 105]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.13. The "uses" Statement
+
+ The "uses" statement is used to reference a "grouping" definition.
+ It takes one argument, which is the name of the grouping.
+
+ The effect of a "uses" reference to a grouping is that the nodes
+ defined by the grouping are copied into the current schema tree and
+ are then updated according to the "refine" and "augment" statements.
+
+ The identifiers defined in the grouping are not bound to a namespace
+ until the contents of the grouping are added to the schema tree via a
+ "uses" statement that does not appear inside a "grouping" statement,
+ at which point they are bound to the namespace of the current module.
+
+7.13.1. The uses's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | augment | 7.17 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | refine | 7.13.2 | 0..n |
+ | status | 7.21.2 | 0..1 |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.13.2. The "refine" Statement
+
+ Some of the properties of each node in the grouping can be refined
+ with the "refine" statement. The argument is a string that
+ identifies a node in the grouping. This node is called the refine's
+ target node. If a node in the grouping is not present as a target
+ node of a "refine" statement, it is not refined and thus is used
+ exactly as it was defined in the grouping.
+
+ The argument string is a descendant schema node identifier (see
+ Section 6.5).
+
+ The following refinements can be done:
+
+ o A leaf or choice node may get a default value, or a new default
+ value if it already had one.
+
+ o A leaf-list node may get a set of default values, or a new set of
+ default values if it already had defaults; i.e., the set of
+ refined default values replaces the defaults already given.
+
+
+
+Bjorklund Standards Track [Page 106]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o Any node may get a specialized "description" string.
+
+ o Any node may get a specialized "reference" string.
+
+ o Any node may get a different "config" statement.
+
+ o A leaf, anydata, anyxml, or choice node may get a different
+ "mandatory" statement.
+
+ o A container node may get a "presence" statement.
+
+ o A leaf, leaf-list, list, container, anydata, or anyxml node may
+ get additional "must" expressions.
+
+ o A leaf-list or list node may get a different "min-elements" or
+ "max-elements" statement.
+
+ o A leaf, leaf-list, list, container, choice, case, anydata, or
+ anyxml node may get additional "if-feature" expressions.
+
+ o Any node can get refined extensions, if the extension allows
+ refinement. See Section 7.19 for details.
+
+7.13.3. XML Encoding Rules
+
+ Each node in the grouping is encoded as if it was defined inline,
+ even if it is imported from another module with another XML
+ namespace.
+
+7.13.4. Usage Example
+
+ To use the "endpoint" grouping defined in Section 7.12.2 in a
+ definition of an HTTP server in some other module, we can do:
+
+ import example-system {
+ prefix "sys";
+ }
+
+ container http-server {
+ leaf name {
+ type string;
+ }
+ uses sys:endpoint;
+ }
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 107]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A corresponding XML instance example:
+
+ <http-server>
+ <name>extern-web</name>
+ <ip>192.0.2.1</ip>
+ <port>80</port>
+ </http-server>
+
+ If port 80 should be the default for the HTTP server, a default can
+ be added:
+
+ container http-server {
+ leaf name {
+ type string;
+ }
+ uses sys:endpoint {
+ refine port {
+ default 80;
+ }
+ }
+ }
+
+ If we want to define a list of servers and each server has "ip" and
+ "port" as keys, we can do:
+
+ list server {
+ key "ip port";
+ leaf name {
+ type string;
+ }
+ uses sys:endpoint;
+ }
+
+ The following is an error:
+
+ container http-server {
+ uses sys:endpoint;
+ leaf ip { // illegal - same identifier "ip" used twice
+ type string;
+ }
+ }
+
+7.14. The "rpc" Statement
+
+ The "rpc" statement is used to define an RPC operation. It takes one
+ argument, which is an identifier, followed by a block of
+ substatements that holds detailed rpc information. This argument is
+ the name of the RPC.
+
+
+
+Bjorklund Standards Track [Page 108]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The "rpc" statement defines an rpc node in the schema tree. Under
+ the rpc node, a schema node with the name "input" and a schema node
+ with the name "output" are also defined. The nodes "input" and
+ "output" are defined in the module's namespace.
+
+7.14.1. The rpc's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | if-feature | 7.20.2 | 0..n |
+ | input | 7.14.2 | 0..1 |
+ | output | 7.14.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ +--------------+---------+-------------+
+
+7.14.2. The "input" Statement
+
+ The "input" statement, which is optional, is used to define input
+ parameters to the operation. It does not take an argument. The
+ substatements to "input" define nodes under the operation's input
+ node.
+
+ If a leaf in the input tree has a "mandatory" statement with the
+ value "true", the leaf MUST be present in an RPC invocation.
+
+ If a leaf in the input tree has a default value, the server MUST use
+ this value in the same cases as those described in Section 7.6.1. In
+ these cases, the server MUST operationally behave as if the leaf was
+ present in the RPC invocation with the default value as its value.
+
+ If a leaf-list in the input tree has one or more default values, the
+ server MUST use these values in the same cases as those described in
+ Section 7.7.2. In these cases, the server MUST operationally behave
+ as if the leaf-list was present in the RPC invocation with the
+ default values as its values.
+
+ Since the input tree is not part of any datastore, all "config"
+ statements for nodes in the input tree are ignored.
+
+ If any node has a "when" statement that would evaluate to "false",
+ then this node MUST NOT be present in the input tree.
+
+
+
+
+
+Bjorklund Standards Track [Page 109]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.14.2.1. The input's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | grouping | 7.12 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | must | 7.5.3 | 0..n |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ +--------------+---------+-------------+
+
+7.14.3. The "output" Statement
+
+ The "output" statement, which is optional, is used to define output
+ parameters to the RPC operation. It does not take an argument. The
+ substatements to "output" define nodes under the operation's output
+ node.
+
+ If a leaf in the output tree has a "mandatory" statement with the
+ value "true", the leaf MUST be present in an RPC reply.
+
+ If a leaf in the output tree has a default value, the client MUST use
+ this value in the same cases as those described in Section 7.6.1. In
+ these cases, the client MUST operationally behave as if the leaf was
+ present in the RPC reply with the default value as its value.
+
+ If a leaf-list in the output tree has one or more default values, the
+ client MUST use these values in the same cases as those described in
+ Section 7.7.2. In these cases, the client MUST operationally behave
+ as if the leaf-list was present in the RPC reply with the default
+ values as its values.
+
+ Since the output tree is not part of any datastore, all "config"
+ statements for nodes in the output tree are ignored.
+
+ If any node has a "when" statement that would evaluate to "false",
+ then this node MUST NOT be present in the output tree.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 110]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.14.3.1. The output's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | grouping | 7.12 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | must | 7.5.3 | 0..n |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ +--------------+---------+-------------+
+
+7.14.4. NETCONF XML Encoding Rules
+
+ An rpc node is encoded as a child XML element to the <rpc> element,
+ as designated by the substitution group "rpcOperation" in [RFC6241].
+ The element's local name is the rpc's identifier, and its namespace
+ is the module's XML namespace (see Section 7.1.3).
+
+ Input parameters are encoded as child XML elements to the rpc node's
+ XML element, in the same order as they are defined within the "input"
+ statement.
+
+ If the RPC operation invocation succeeded and no output parameters
+ are returned, the <rpc-reply> contains a single <ok/> element defined
+ in [RFC6241]. If output parameters are returned, they are encoded as
+ child elements to the <rpc-reply> element defined in [RFC6241], in
+ the same order as they are defined within the "output" statement.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 111]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.14.5. Usage Example
+
+ The following example defines an RPC operation:
+
+ module example-rock {
+ yang-version 1.1;
+ namespace "urn:example:rock";
+ prefix "rock";
+
+ rpc rock-the-house {
+ input {
+ leaf zip-code {
+ type string;
+ }
+ }
+ }
+ }
+
+ A corresponding XML instance example of the complete rpc and
+ rpc-reply:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <rock-the-house xmlns="urn:example:rock">
+ <zip-code>27606-0100</zip-code>
+ </rock-the-house>
+ </rpc>
+
+ <rpc-reply message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <ok/>
+ </rpc-reply>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 112]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.15. The "action" Statement
+
+ The "action" statement is used to define an operation connected to a
+ specific container or list data node. It takes one argument, which
+ is an identifier, followed by a block of substatements that holds
+ detailed action information. The argument is the name of the action.
+
+ The "action" statement defines an action node in the schema tree.
+ Under the action node, a schema node with the name "input" and a
+ schema node with the name "output" are also defined. The nodes
+ "input" and "output" are defined in the module's namespace.
+
+ An action MUST NOT be defined within an rpc, another action, or a
+ notification, i.e., an action node MUST NOT have an rpc, action, or a
+ notification node as one of its ancestors in the schema tree. For
+ example, this means that it is an error if a grouping that contains
+ an action somewhere in its node hierarchy is used in a notification
+ definition.
+
+ An action MUST NOT have any ancestor node that is a list node without
+ a "key" statement.
+
+ Since an action cannot be defined at the top level of a module or in
+ a "case" statement, it is an error if a grouping that contains an
+ action at the top of its node hierarchy is used at the top level of a
+ module or in a case definition.
+
+ The difference between an action and an rpc is that an action is tied
+ to a node in the datastore, whereas an rpc is not. When an action is
+ invoked, the node in the datastore is specified along with the name
+ of the action and the input parameters.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 113]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.15.1. The action's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | if-feature | 7.20.2 | 0..n |
+ | input | 7.14.2 | 0..1 |
+ | output | 7.14.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ +--------------+---------+-------------+
+
+7.15.2. NETCONF XML Encoding Rules
+
+ When an action is invoked, an element with the local name "action" in
+ the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is
+ encoded as a child XML element to the <rpc> element defined in
+ [RFC6241], as designated by the substitution group "rpcOperation" in
+ [RFC6241].
+
+ The <action> element contains a hierarchy of nodes that identifies
+ the node in the datastore. It MUST contain all containers and list
+ nodes in the direct path from the top level down to the list or
+ container containing the action. For lists, all key leafs MUST also
+ be included. The innermost container or list contains an XML element
+ that carries the name of the defined action. Within this element,
+ the input parameters are encoded as child XML elements, in the same
+ order as they are defined within the "input" statement.
+
+ Only one action can be invoked in one <rpc>. If more than one action
+ is present in the <rpc>, the server MUST reply with a "bad-element"
+ <error-tag> in the <rpc-error>.
+
+ If the action operation invocation succeeded and no output parameters
+ are returned, the <rpc-reply> contains a single <ok/> element defined
+ in [RFC6241]. If output parameters are returned, they are encoded as
+ child elements to the <rpc-reply> element defined in [RFC6241], in
+ the same order as they are defined within the "output" statement.
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 114]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.15.3. Usage Example
+
+ The following example defines an action to reset one server at a
+ server farm:
+
+ module example-server-farm {
+ yang-version 1.1;
+ namespace "urn:example:server-farm";
+ prefix "sfarm";
+
+ import ietf-yang-types {
+ prefix "yang";
+ }
+
+ list server {
+ key name;
+ leaf name {
+ type string;
+ }
+ action reset {
+ input {
+ leaf reset-at {
+ type yang:date-and-time;
+ mandatory true;
+ }
+ }
+ output {
+ leaf reset-finished-at {
+ type yang:date-and-time;
+ mandatory true;
+ }
+ }
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 115]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A corresponding XML instance example of the complete rpc and
+ rpc-reply:
+
+ <rpc message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <action xmlns="urn:ietf:params:xml:ns:yang:1">
+ <server xmlns="urn:example:server-farm">
+ <name>apache-1</name>
+ <reset>
+ <reset-at>2014-07-29T13:42:00Z</reset-at>
+ </reset>
+ </server>
+ </action>
+ </rpc>
+
+ <rpc-reply message-id="101"
+ xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
+ <reset-finished-at xmlns="urn:example:server-farm">
+ 2014-07-29T13:42:12Z
+ </reset-finished-at>
+ </rpc-reply>
+
+7.16. The "notification" Statement
+
+ The "notification" statement is used to define a notification. It
+ takes one argument, which is an identifier, followed by a block of
+ substatements that holds detailed notification information. The
+ "notification" statement defines a notification node in the schema
+ tree.
+
+ A notification can be defined at the top level of a module, or
+ connected to a specific container or list data node in the schema
+ tree.
+
+ A notification MUST NOT be defined within an rpc, action, or another
+ notification, i.e., a notification node MUST NOT have an rpc, action,
+ or a notification node as one of its ancestors in the schema tree.
+ For example, this means that it is an error if a grouping that
+ contains a notification somewhere in its node hierarchy is used in an
+ rpc definition.
+
+ A notification MUST NOT have any ancestor node that is a list node
+ without a "key" statement.
+
+ Since a notification cannot be defined in a "case" statement, it is
+ an error if a grouping that contains a notification at the top of its
+ node hierarchy is used in a case definition.
+
+
+
+
+Bjorklund Standards Track [Page 116]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If a leaf in the notification tree has a "mandatory" statement with
+ the value "true", the leaf MUST be present in a notification
+ instance.
+
+ If a leaf in the notification tree has a default value, the client
+ MUST use this value in the same cases as those described in
+ Section 7.6.1. In these cases, the client MUST operationally behave
+ as if the leaf was present in the notification instance with the
+ default value as its value.
+
+ If a leaf-list in the notification tree has one or more default
+ values, the client MUST use these values in the same cases as those
+ described in Section 7.7.2. In these cases, the client MUST
+ operationally behave as if the leaf-list was present in the
+ notification instance with the default values as its values.
+
+ Since the notification tree is not part of any datastore, all
+ "config" statements for nodes in the notification tree are ignored.
+
+7.16.1. The notification's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | grouping | 7.12 | 0..n |
+ | if-feature | 7.20.2 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | must | 7.5.3 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | typedef | 7.3 | 0..n |
+ | uses | 7.13 | 0..n |
+ +--------------+---------+-------------+
+
+7.16.2. NETCONF XML Encoding Rules
+
+ A notification node that is defined on the top level of a module is
+ encoded as a child XML element to the <notification> element defined
+ in "NETCONF Event Notifications" [RFC5277]. The element's local name
+ is the notification's identifier, and its namespace is the module's
+ XML namespace (see Section 7.1.3).
+
+
+
+Bjorklund Standards Track [Page 117]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ When a notification node is defined as a child to a data node, the
+ <notification> element defined in [RFC5277] contains a hierarchy of
+ nodes that identifies the node in the datastore. It MUST contain all
+ containers and list nodes from the top level down to the list or
+ container containing the notification. For lists, all key leafs MUST
+ also be included. The innermost container or list contains an XML
+ element that carries the name of the defined notification.
+
+ The notification's child nodes are encoded as subelements to the
+ notification node's XML element, in any order.
+
+7.16.3. Usage Example
+
+ The following example defines a notification at the top level of a
+ module:
+
+ module example-event {
+ yang-version 1.1;
+ namespace "urn:example:event";
+ prefix "ev";
+
+ notification event {
+ leaf event-class {
+ type string;
+ }
+ leaf reporting-entity {
+ type instance-identifier;
+ }
+ leaf severity {
+ type string;
+ }
+ }
+ }
+
+ A corresponding XML instance example of the complete notification:
+
+ <notification
+ xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ <eventTime>2008-07-08T00:01:00Z</eventTime>
+ <event xmlns="urn:example:event">
+ <event-class>fault</event-class>
+ <reporting-entity>
+ /ex:interface[ex:name='Ethernet0']
+ </reporting-entity>
+ <severity>major</severity>
+ </event>
+ </notification>
+
+
+
+
+Bjorklund Standards Track [Page 118]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following example defines a notification in a data node:
+
+ module example-interface-module {
+ yang-version 1.1;
+ namespace "urn:example:interface-module";
+ prefix "if";
+
+ container interfaces {
+ list interface {
+ key "name";
+ leaf name {
+ type string;
+ }
+ notification interface-enabled {
+ leaf by-user {
+ type string;
+ }
+ }
+ }
+ }
+ }
+
+ A corresponding XML instance example of the complete notification:
+
+ <notification
+ xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ <eventTime>2008-07-08T00:01:00Z</eventTime>
+ <interfaces xmlns="urn:example:interface-module">
+ <interface>
+ <name>eth1</name>
+ <interface-enabled>
+ <by-user>fred</by-user>
+ </interface-enabled>
+ </interface>
+ </interfaces>
+ </notification>
+
+7.17. The "augment" Statement
+
+ The "augment" statement allows a module or submodule to add to a
+ schema tree defined in an external module, or in the current module
+ and its submodules, and to add to the nodes from a grouping in a
+ "uses" statement. The argument is a string that identifies a node in
+ the schema tree. This node is called the augment's target node. The
+ target node MUST be either a container, list, choice, case, input,
+ output, or notification node. It is augmented with the nodes defined
+ in the substatements that follow the "augment" statement.
+
+
+
+
+Bjorklund Standards Track [Page 119]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The argument string is a schema node identifier (see Section 6.5).
+ If the "augment" statement is on the top level in a module or
+ submodule, the absolute form (defined by the rule
+ "absolute-schema-nodeid" in Section 14) of a schema node identifier
+ MUST be used. If the "augment" statement is a substatement to the
+ "uses" statement, the descendant form (defined by the rule
+ "descendant-schema-nodeid" in Section 14) MUST be used.
+
+ If the target node is a container, list, case, input, output, or
+ notification node, the "container", "leaf", "list", "leaf-list",
+ "uses", and "choice" statements can be used within the "augment"
+ statement.
+
+ If the target node is a container or list node, the "action" and
+ "notification" statements can be used within the "augment" statement.
+
+ If the target node is a choice node, the "case" statement or a
+ shorthand "case" statement (see Section 7.9.2) can be used within the
+ "augment" statement.
+
+ The "augment" statement MUST NOT add multiple nodes with the same
+ name from the same module to the target node.
+
+ If the augmentation adds mandatory nodes (see Section 3) that
+ represent configuration to a target node in another module, the
+ augmentation MUST be made conditional with a "when" statement. Care
+ must be taken when defining the "when" expression so that clients
+ that do not know about the augmenting module do not break.
+
+ In the following example, it is OK to augment the "interface" entry
+ with "mandatory-leaf" because the augmentation depends on support for
+ "some-new-iftype". The old client does not know about this type, so
+ it would never select this type and would therefore not be adding a
+ mandatory data node.
+
+ module example-augment {
+ yang-version 1.1;
+ namespace "urn:example:augment";
+ prefix mymod;
+
+ import ietf-interfaces {
+ prefix if;
+ }
+
+ identity some-new-iftype {
+ base if:interface-type;
+ }
+
+
+
+
+Bjorklund Standards Track [Page 120]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ augment "/if:interfaces/if:interface" {
+ when 'derived-from-or-self(if:type, "mymod:some-new-iftype")';
+
+ leaf mandatory-leaf {
+ mandatory true;
+ type string;
+ }
+ }
+ }
+
+7.17.1. The augment's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | action | 7.15 | 0..n |
+ | anydata | 7.10 | 0..n |
+ | anyxml | 7.11 | 0..n |
+ | case | 7.9.2 | 0..n |
+ | choice | 7.9 | 0..n |
+ | container | 7.5 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | leaf | 7.6 | 0..n |
+ | leaf-list | 7.7 | 0..n |
+ | list | 7.8 | 0..n |
+ | notification | 7.16 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | uses | 7.13 | 0..n |
+ | when | 7.21.5 | 0..1 |
+ +--------------+---------+-------------+
+
+7.17.2. XML Encoding Rules
+
+ All data nodes defined in the "augment" statement are defined as XML
+ elements in the XML namespace of the module where the "augment" is
+ specified.
+
+ When a node is augmented, the augmenting child nodes are encoded as
+ subelements to the augmented node, in any order.
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 121]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.17.3. Usage Example
+
+ In namespace urn:example:interface-module, we have:
+
+ container interfaces {
+ list ifEntry {
+ key "ifIndex";
+
+ leaf ifIndex {
+ type uint32;
+ }
+ leaf ifDescr {
+ type string;
+ }
+ leaf ifType {
+ type iana:IfType;
+ }
+ leaf ifMtu {
+ type int32;
+ }
+ }
+ }
+
+ Then, in namespace urn:example:ds0, we have:
+
+ import example-interface-module {
+ prefix "if";
+ }
+ augment "/if:interfaces/if:ifEntry" {
+ when "if:ifType='ds0'";
+ leaf ds0ChannelNumber {
+ type ChannelNumber;
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 122]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A corresponding XML instance example:
+
+ <interfaces xmlns="urn:example:interface-module"
+ xmlns:ds0="urn:example:ds0">
+ <ifEntry>
+ <ifIndex>1</ifIndex>
+ <ifDescr>Flintstone Inc Ethernet A562</ifDescr>
+ <ifType>ethernetCsmacd</ifType>
+ <ifMtu>1500</ifMtu>
+ </ifEntry>
+ <ifEntry>
+ <ifIndex>2</ifIndex>
+ <ifDescr>Flintstone Inc DS0</ifDescr>
+ <ifType>ds0</ifType>
+ <ds0:ds0ChannelNumber>1</ds0:ds0ChannelNumber>
+ </ifEntry>
+ </interfaces>
+
+ As another example, suppose we have the choice defined in
+ Section 7.9.6. The following construct can be used to extend the
+ protocol definition:
+
+ augment /ex:system/ex:protocol/ex:name {
+ case c {
+ leaf smtp {
+ type empty;
+ }
+ }
+ }
+
+ A corresponding XML instance example:
+
+ <ex:system>
+ <ex:protocol>
+ <ex:tcp/>
+ </ex:protocol>
+ </ex:system>
+
+ or
+
+ <ex:system>
+ <ex:protocol>
+ <other:smtp/>
+ </ex:protocol>
+ </ex:system>
+
+
+
+
+
+
+Bjorklund Standards Track [Page 123]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.18. The "identity" Statement
+
+ The "identity" statement is used to define a new globally unique,
+ abstract, and untyped identity. The identity's only purpose is to
+ denote its name, semantics, and existence. An identity can be either
+ defined from scratch or derived from one or more base identities.
+ The identity's argument is an identifier that is the name of the
+ identity. It is followed by a block of substatements that holds
+ detailed identity information.
+
+ The built-in datatype "identityref" (see Section 9.10) can be used to
+ reference identities within a data model.
+
+7.18.1. The identity's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | base | 7.18.2 | 0..n |
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ +--------------+---------+-------------+
+
+7.18.2. The "base" Statement
+
+ The "base" statement, which is optional, takes as an argument a
+ string that is the name of an existing identity, from which the new
+ identity is derived. If no "base" statement is present, the identity
+ is defined from scratch. If multiple "base" statements are present,
+ the identity is derived from all of them.
+
+ If a prefix is present on the base name, it refers to an identity
+ defined in the module that was imported with that prefix, or the
+ local module if the prefix matches the local module's prefix.
+ Otherwise, an identity with the matching name MUST be defined in the
+ current module or an included submodule.
+
+ An identity MUST NOT reference itself, neither directly nor
+ indirectly through a chain of other identities.
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 124]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The derivation of identities has the following properties:
+
+ o It is irreflexive, which means that an identity is not derived
+ from itself.
+
+ o It is transitive, which means that if identity B is derived from A
+ and C is derived from B, then C is also derived from A.
+
+7.18.3. Usage Example
+
+ module example-crypto-base {
+ yang-version 1.1;
+ namespace "urn:example:crypto-base";
+ prefix "crypto";
+
+ identity crypto-alg {
+ description
+ "Base identity from which all crypto algorithms
+ are derived.";
+ }
+
+ identity symmetric-key {
+ description
+ "Base identity used to identify symmetric-key crypto
+ algorithms.";
+ }
+
+ identity public-key {
+ description
+ "Base identity used to identify public-key crypto
+ algorithms.";
+ }
+ }
+
+ module example-des {
+ yang-version 1.1;
+ namespace "urn:example:des";
+ prefix "des";
+
+ import "example-crypto-base" {
+ prefix "crypto";
+ }
+
+ identity des {
+ base "crypto:crypto-alg";
+ base "crypto:symmetric-key";
+ description "DES crypto algorithm.";
+ }
+
+
+
+Bjorklund Standards Track [Page 125]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ identity des3 {
+ base "crypto:crypto-alg";
+ base "crypto:symmetric-key";
+ description "Triple DES crypto algorithm.";
+ }
+ }
+
+7.19. The "extension" Statement
+
+ The "extension" statement allows the definition of new statements
+ within the YANG language. This new statement definition can be
+ imported and used by other modules.
+
+ The "extension" statement's argument is an identifier that is the new
+ keyword for the extension and must be followed by a block of
+ substatements that holds detailed extension information. The purpose
+ of the "extension" statement is to define a keyword so that it can be
+ imported and used by other modules.
+
+ The extension can be used like a normal YANG statement, with the
+ statement name followed by an argument if one is defined by the
+ "extension" statement, and an optional block of substatements. The
+ statement's name is created by combining the prefix of the module in
+ which the extension was defined, a colon (":"), and the extension's
+ keyword, with no interleaving whitespace. The substatements of an
+ extension are defined by the "extension" statement, using some
+ mechanism outside the scope of this specification. Syntactically,
+ the substatements MUST be YANG statements, including extensions
+ defined using "extension" statements. YANG statements in extensions
+ MUST follow the syntactical rules in Section 14.
+
+ An extension can allow refinement (see Section 7.13.2) and deviations
+ (Section 7.20.3.2), but the mechanism for how this is defined is
+ outside the scope of this specification.
+
+7.19.1. The extension's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | argument | 7.19.2 | 0..1 |
+ | description | 7.21.3 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 126]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.19.2. The "argument" Statement
+
+ The "argument" statement, which is optional, takes as an argument a
+ string that is the name of the argument to the keyword. If no
+ "argument" statement is present, the keyword expects no argument when
+ it is used.
+
+ The argument's name is used in the YIN mapping, where it is used as
+ an XML attribute or element name, depending on the argument's
+ "yin-element" statement.
+
+7.19.2.1. The argument's Substatement
+
+ +--------------+----------+-------------+
+ | substatement | section | cardinality |
+ +--------------+----------+-------------+
+ | yin-element | 7.19.2.2 | 0..1 |
+ +--------------+----------+-------------+
+
+7.19.2.2. The "yin-element" Statement
+
+ The "yin-element" statement, which is optional, takes as an argument
+ the string "true" or "false". This statement indicates whether the
+ argument is mapped to an XML element in YIN or to an XML attribute
+ (see Section 13).
+
+ If no "yin-element" statement is present, it defaults to "false".
+
+7.19.3. Usage Example
+
+ To define an extension:
+
+ module example-extensions {
+ yang-version 1.1;
+ ...
+
+ extension c-define {
+ description
+ "Takes as an argument a name string.
+ Makes the code generator use the given name
+ in the #define.";
+ argument "name";
+ }
+ }
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 127]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ To use the extension:
+
+ module example-interfaces {
+ yang-version 1.1;
+
+ ...
+ import example-extensions {
+ prefix "myext";
+ }
+ ...
+
+ container interfaces {
+ ...
+ myext:c-define "MY_INTERFACES";
+ }
+ }
+
+7.20. Conformance-Related Statements
+
+ This section defines statements related to conformance, as described
+ in Section 5.6.
+
+7.20.1. The "feature" Statement
+
+ The "feature" statement is used to define a mechanism by which
+ portions of the schema are marked as conditional. A feature name is
+ defined that can later be referenced using the "if-feature" statement
+ (see Section 7.20.2). Schema nodes tagged with an "if-feature"
+ statement are ignored by the server unless the server supports the
+ given feature expression. This allows portions of the YANG module to
+ be conditional based on conditions in the server. The model can
+ represent the abilities of the server within the model, giving a
+ richer model that allows for differing server abilities and roles.
+
+ The argument to the "feature" statement is the name of the new
+ feature and follows the rules for identifiers in Section 6.2. This
+ name is used by the "if-feature" statement to tie the schema nodes to
+ the feature.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 128]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ In this example, a feature called "local-storage" represents the
+ ability for a server to store syslog messages on local storage of
+ some sort. This feature is used to make the "local-storage-limit"
+ leaf conditional on the presence of some sort of local storage. If
+ the server does not report that it supports this feature, the
+ "local-storage-limit" node is not supported.
+
+ module example-syslog {
+ yang-version 1.1;
+
+ ...
+ feature local-storage {
+ description
+ "This feature means that the server supports local
+ storage (memory, flash, or disk) that can be used to
+ store syslog messages.";
+ }
+
+ container syslog {
+ leaf local-storage-limit {
+ if-feature local-storage;
+ type uint64;
+ units "kilobyte";
+ config false;
+ description
+ "The amount of local storage that can be
+ used to hold syslog messages.";
+ }
+ }
+ }
+
+ The "if-feature" statement can be used in many places within the YANG
+ syntax. Definitions tagged with "if-feature" are ignored when the
+ server does not support that feature.
+
+ A feature MUST NOT reference itself, neither directly nor indirectly
+ through a chain of other features.
+
+ In order for a server to support a feature that is dependent on any
+ other features (i.e., the feature has one or more "if-feature"
+ substatements), the server MUST also support all the dependent
+ features.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 129]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.20.1.1. The feature's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ +--------------+---------+-------------+
+
+7.20.2. The "if-feature" Statement
+
+ The "if-feature" statement makes its parent statement conditional.
+ The argument is a boolean expression over feature names. In this
+ expression, a feature name evaluates to "true" if and only if the
+ feature is supported by the server. The parent statement is
+ implemented by servers where the boolean expression evaluates to
+ "true".
+
+ The if-feature boolean expression syntax is formally defined by the
+ rule "if-feature-expr" in Section 14. Parentheses are used to group
+ expressions. When the expression is evaluated, the order of
+ precedence is (highest precedence first): grouping (parentheses),
+ "not", "and", "or".
+
+ If a prefix is present on a feature name in the boolean expression,
+ the prefixed name refers to a feature defined in the module that was
+ imported with that prefix, or the local module if the prefix matches
+ the local module's prefix. Otherwise, a feature with the matching
+ name MUST be defined in the current module or an included submodule.
+
+ A leaf that is a list key MUST NOT have any "if-feature" statements.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 130]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.20.2.1. Usage Example
+
+ In this example, the container "target" is implemented if either the
+ "outbound-tls" or "outbound-ssh" feature is supported by the server.
+
+ container target {
+ if-feature "outbound-tls or outbound-ssh";
+ ...
+ }
+
+ The following examples are equivalent:
+
+ if-feature "not foo or bar and baz";
+
+ if-feature "(not foo) or (bar and baz)";
+
+7.20.3. The "deviation" Statement
+
+ The "deviation" statement defines a hierarchy of a module that the
+ server does not implement faithfully. The argument is a string that
+ identifies the node in the schema tree where a deviation from the
+ module occurs. This node is called the deviation's target node. The
+ contents of the "deviation" statement give details about the
+ deviation.
+
+ The argument string is an absolute schema node identifier (see
+ Section 6.5).
+
+ Deviations define the way a server or class of servers deviate from a
+ standard. This means that deviations MUST never be part of a
+ published standard, since they are the mechanism for learning how
+ implementations vary from the standards.
+
+ Server deviations are strongly discouraged and MUST only be used as a
+ last resort. Telling the application how a server fails to follow a
+ standard is no substitute for implementing the standard correctly. A
+ server that deviates from a module is not fully compliant with the
+ module.
+
+ However, in some cases, a particular device may not have the hardware
+ or software ability to support parts of a standard module. When this
+ occurs, the server makes a choice to either treat attempts to
+ configure unsupported parts of the module as an error that is
+ reported back to the unsuspecting application or ignore those
+ incoming requests. Neither choice is acceptable.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 131]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Instead, YANG allows servers to document portions of a base module
+ that are not supported, or that are supported but with different
+ syntax, by using the "deviation" statement.
+
+ After applying all deviations announced by a server, in any order,
+ the resulting data model MUST still be valid.
+
+7.20.3.1. The deviation's Substatements
+
+ +--------------+----------+-------------+
+ | substatement | section | cardinality |
+ +--------------+----------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | deviate | 7.20.3.2 | 1..n |
+ | reference | 7.21.4 | 0..1 |
+ +--------------+----------+-------------+
+
+7.20.3.2. The "deviate" Statement
+
+ The "deviate" statement defines how the server's implementation of
+ the target node deviates from its original definition. The argument
+ is one of the strings "not-supported", "add", "replace", or "delete".
+
+ The argument "not-supported" indicates that the target node is not
+ implemented by this server.
+
+ The argument "add" adds properties to the target node. The
+ properties to add are identified by substatements to the "deviate"
+ statement. If a property can only appear once, the property MUST NOT
+ exist in the target node.
+
+ The argument "replace" replaces properties of the target node. The
+ properties to replace are identified by substatements to the
+ "deviate" statement. The properties to replace MUST exist in the
+ target node.
+
+ The argument "delete" deletes properties from the target node. The
+ properties to delete are identified by substatements to the "delete"
+ statement. The substatement's keyword MUST match a corresponding
+ keyword in the target node, and the argument's string MUST be equal
+ to the corresponding keyword's argument string in the target node.
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 132]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ +--------------+--------------+-------------+
+ | substatement | section | cardinality |
+ +--------------+--------------+-------------+
+ | config | 7.21.1 | 0..1 |
+ | default | 7.6.4, 7.7.4 | 0..n |
+ | mandatory | 7.6.5 | 0..1 |
+ | max-elements | 7.7.6 | 0..1 |
+ | min-elements | 7.7.5 | 0..1 |
+ | must | 7.5.3 | 0..n |
+ | type | 7.4 | 0..1 |
+ | unique | 7.8.3 | 0..n |
+ | units | 7.3.3 | 0..1 |
+ +--------------+--------------+-------------+
+
+ The deviate's Substatements
+
+ If the target node has a property defined by an extension, this
+ property can be deviated if the extension allows deviations. See
+ Section 7.19 for details.
+
+7.20.3.3. Usage Example
+
+ In this example, the server is informing client applications that it
+ does not support the "daytime" service in the style of RFC 867.
+
+ module example-deviations {
+ yang-version 1.1;
+ namespace "urn:example:deviations";
+ prefix md;
+
+ import example-base {
+ prefix base;
+ }
+
+ deviation /base:system/base:daytime {
+ deviate not-supported;
+ }
+ ...
+ }
+
+ A server would advertise both modules "example-base" and
+ "example-deviations".
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 133]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following example sets a server-specific default value to a leaf
+ that does not have a default value defined:
+
+ deviation /base:system/base:user/base:type {
+ deviate add {
+ default "admin"; // new users are 'admin' by default
+ }
+ }
+
+ In this example, the server limits the number of name servers to 3:
+
+ deviation /base:system/base:name-server {
+ deviate replace {
+ max-elements 3;
+ }
+ }
+
+ If the original definition is:
+
+ container system {
+ must "daytime or time";
+ ...
+ }
+
+ a server might remove this "must" constraint by doing:
+
+ deviation /base:system {
+ deviate delete {
+ must "daytime or time";
+ }
+ }
+
+7.21. Common Statements
+
+ This section defines substatements common to several other
+ statements.
+
+7.21.1. The "config" Statement
+
+ The "config" statement takes as an argument the string "true" or
+ "false". If "config" is "true", the definition represents
+ configuration. Data nodes representing configuration are part of
+ configuration datastores.
+
+ If "config" is "false", the definition represents state data. Data
+ nodes representing state data are not part of configuration
+ datastores.
+
+
+
+
+Bjorklund Standards Track [Page 134]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If "config" is not specified, the default is the same as the parent
+ schema node's "config" value. If the parent node is a case node, the
+ value is the same as the case node's parent choice node.
+
+ If the top node does not specify a "config" statement, the default is
+ "true".
+
+ If a node has "config" set to "false", no node underneath it can have
+ "config" set to "true".
+
+7.21.2. The "status" Statement
+
+ The "status" statement takes as an argument one of the strings
+ "current", "deprecated", or "obsolete".
+
+ o "current" means that the definition is current and valid.
+
+ o "deprecated" indicates an obsolete definition, but it permits
+ new/continued implementation in order to foster interoperability
+ with older/existing implementations.
+
+ o "obsolete" means that the definition is obsolete and SHOULD NOT be
+ implemented and/or can be removed from implementations.
+
+ If no status is specified, the default is "current".
+
+ If a definition is "current", it MUST NOT reference a "deprecated" or
+ "obsolete" definition within the same module.
+
+ If a definition is "deprecated", it MUST NOT reference an "obsolete"
+ definition within the same module.
+
+ For example, the following is illegal:
+
+ typedef my-type {
+ status deprecated;
+ type int32;
+ }
+
+ leaf my-leaf {
+ status current;
+ type my-type; // illegal, since my-type is deprecated
+ }
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 135]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+7.21.3. The "description" Statement
+
+ The "description" statement takes as an argument a string that
+ contains a human-readable textual description of this definition.
+ The text is provided in a language (or languages) chosen by the
+ module developer; for the sake of interoperability, it is RECOMMENDED
+ to choose a language that is widely understood among the community of
+ network administrators who will use the module.
+
+7.21.4. The "reference" Statement
+
+ The "reference" statement takes as an argument a string that is a
+ human-readable cross-reference to an external document -- either
+ another module that defines related management information or a
+ document that provides additional information relevant to this
+ definition.
+
+ For example, a typedef for a "uri" data type could look like:
+
+ typedef uri {
+ type string;
+ reference
+ "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax";
+ ...
+ }
+
+7.21.5. The "when" Statement
+
+ The "when" statement makes its parent data definition statement
+ conditional. The node defined by the parent data definition
+ statement is only valid when the condition specified by the "when"
+ statement is satisfied. The statement's argument is an XPath
+ expression (see Section 6.4), which is used to formally specify this
+ condition. If the XPath expression conceptually evaluates to "true"
+ for a particular instance, then the node defined by the parent data
+ definition statement is valid; otherwise, it is not.
+
+ A leaf that is a list key MUST NOT have a "when" statement.
+
+ If a key leaf is defined in a grouping that is used in a list, the
+ "uses" statement MUST NOT have a "when" statement.
+
+ See Section 8.3.2 for additional information.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 136]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The XPath expression is conceptually evaluated in the following
+ context, in addition to the definition in Section 6.4.1:
+
+ o If the "when" statement is a child of an "augment" statement, then
+ the context node is the augment's target node in the data tree, if
+ the target node is a data node. Otherwise, the context node is
+ the closest ancestor node to the target node that is also a data
+ node. If no such node exists, the context node is the root node.
+ The accessible tree is tentatively altered during the processing
+ of the XPath expression by removing all instances (if any) of the
+ nodes added by the "augment" statement.
+
+ o If the "when" statement is a child of a "uses", "choice", or
+ "case" statement, then the context node is the closest ancestor
+ node to the node with the "when" statement that is also a data
+ node. If no such node exists, the context node is the root node.
+ The accessible tree is tentatively altered during the processing
+ of the XPath expression by removing all instances (if any) of the
+ nodes added by the "uses", "choice", or "case" statement.
+
+ o If the "when" statement is a child of any other data definition
+ statement, the accessible tree is tentatively altered during the
+ processing of the XPath expression by replacing all instances of
+ the data node for which the "when" statement is defined with a
+ single dummy node with the same name, but with no value and no
+ children. If no such instance exists, the dummy node is
+ tentatively created. The context node is this dummy node.
+
+ The result of the XPath expression is converted to a boolean value
+ using the standard XPath rules.
+
+ If the XPath expression references any node that also has associated
+ "when" statements, those "when" expressions MUST be evaluated first.
+ There MUST NOT be any circular dependencies among "when" expressions.
+
+ Note that the XPath expression is conceptually evaluated. This means
+ that an implementation does not have to use an XPath evaluator in the
+ server. The "when" statement can very well be implemented with
+ specially written code.
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 137]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+8. Constraints
+
+8.1. Constraints on Data
+
+ Several YANG statements define constraints on valid data. These
+ constraints are enforced in different ways, depending on what type of
+ data the statement defines.
+
+ o If the constraint is defined on configuration data, it MUST be
+ true in a valid configuration data tree.
+
+ o If the constraint is defined on state data, it MUST be true in a
+ valid state data tree.
+
+ o If the constraint is defined on notification content, it MUST be
+ true in any notification data tree.
+
+ o If the constraint is defined on RPC or action input parameters, it
+ MUST be true in an invocation of the RPC or action operation.
+
+ o If the constraint is defined on RPC or action output parameters,
+ it MUST be true in the RPC or action reply.
+
+ The following properties are true in all data trees:
+
+ o All leaf data values MUST match the type constraints for the leaf,
+ including those defined in the type's "range", "length", and
+ "pattern" properties.
+
+ o All key leafs MUST be present for all list entries.
+
+ o Nodes MUST be present for at most one case branch in all choices.
+
+ o There MUST be no nodes tagged with "if-feature" present if the
+ "if-feature" expression evaluates to "false" in the server.
+
+ o There MUST be no nodes tagged with "when" present if the "when"
+ condition evaluates to "false" in the data tree.
+
+ The following properties are true in a valid data tree:
+
+ o All "must" constraints MUST evaluate to "true".
+
+ o All referential integrity constraints defined via the "path"
+ statement MUST be satisfied.
+
+ o All "unique" constraints on lists MUST be satisfied.
+
+
+
+
+Bjorklund Standards Track [Page 138]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o The "mandatory" constraint is enforced for leafs and choices,
+ unless the node or any of its ancestors has a "when" condition or
+ "if-feature" expression that evaluates to "false".
+
+ o The "min-elements" and "max-elements" constraints are enforced for
+ lists and leaf-lists, unless the node or any of its ancestors has
+ a "when" condition or "if-feature" expression that evaluates to
+ "false".
+
+ The running configuration datastore MUST always be valid.
+
+8.2. Configuration Data Modifications
+
+ o If a request creates configuration data nodes under a choice, any
+ existing nodes from other case branches in the data tree are
+ deleted by the server.
+
+ o If a request modifies a configuration data node such that any
+ node's "when" expression becomes false, then the node in the data
+ tree with the "when" expression is deleted by the server.
+
+8.3. NETCONF Constraint Enforcement Model
+
+ For configuration data, there are three windows when constraints MUST
+ be enforced:
+
+ o during parsing of RPC payloads
+
+ o during processing of the <edit-config> operation
+
+ o during validation
+
+ Each of these scenarios is considered in the following sections.
+
+8.3.1. Payload Parsing
+
+ When content arrives in RPC payloads, it MUST be well-formed XML,
+ following the hierarchy and content rules defined by the set of
+ models the server implements.
+
+ o If a leaf data value does not match the type constraints for the
+ leaf, including those defined in the type's "range", "length", and
+ "pattern" properties, the server MUST reply with an
+ "invalid-value" <error-tag> in the <rpc-error>, and with the
+ error-app-tag (Section 7.5.4.2) and error-message
+ (Section 7.5.4.1) associated with the constraint, if any exist.
+
+
+
+
+
+Bjorklund Standards Track [Page 139]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o If all keys of a list entry are not present, the server MUST reply
+ with a "missing-element" <error-tag> in the <rpc-error>.
+
+ o If data for more than one case branch of a choice is present, the
+ server MUST reply with a "bad-element" <error-tag> in the
+ <rpc-error>.
+
+ o If data for a node tagged with "if-feature" is present and the
+ "if-feature" expression evaluates to "false" in the server, the
+ server MUST reply with an "unknown-element" <error-tag> in the
+ <rpc-error>.
+
+ o If data for a node tagged with "when" is present and the "when"
+ condition evaluates to "false", the server MUST reply with an
+ "unknown-element" <error-tag> in the <rpc-error>.
+
+ o For insert handling, if the values for the attributes "before" and
+ "after" are not valid for the type of the appropriate key leafs,
+ the server MUST reply with a "bad-attribute" <error-tag> in the
+ <rpc-error>.
+
+ o If the attributes "before" and "after" appear in any element that
+ is not a list whose "ordered-by" property is "user", the server
+ MUST reply with an "unknown-attribute" <error-tag> in the
+ <rpc-error>.
+
+8.3.2. NETCONF <edit-config> Processing
+
+ After the incoming data is parsed, the NETCONF server performs the
+ <edit-config> operation by applying the data to the configuration
+ datastore. During this processing, the following errors MUST be
+ detected:
+
+ o Delete requests for non-existent data.
+
+ o Create requests for existent data.
+
+ o Insert requests with "before" or "after" parameters that do not
+ exist.
+
+ o Modification requests for nodes tagged with "when", and the "when"
+ condition evaluates to "false". In this case, the server MUST
+ reply with an "unknown-element" <error-tag> in the <rpc-error>.
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 140]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+8.3.3. Validation
+
+ When datastore processing is complete, the final contents MUST obey
+ all validation constraints. This validation processing is performed
+ at differing times according to the datastore. If the datastore is
+ "running" or "startup", these constraints MUST be enforced at the end
+ of the <edit-config> or <copy-config> operation. If the datastore is
+ "candidate", the constraint enforcement is delayed until a <commit>
+ or <validate> operation takes place.
+
+9. Built-In Types
+
+ YANG has a set of built-in types, similar to those of many
+ programming languages, but with some differences due to special
+ requirements from the management information model.
+
+ Additional types may be defined that are derived from those built-in
+ types or from other derived types. Derived types may use subtyping
+ to formally restrict the set of possible values.
+
+ The different built-in types and their derived types allow different
+ kinds of subtyping, namely length and regular expression restrictions
+ of strings (Sections 9.4.4 and 9.4.5) and range restrictions of
+ numeric types (Section 9.2.4).
+
+ The lexical representation of a value of a certain type is used in
+ the XML encoding and when specifying default values and numerical
+ ranges in YANG modules.
+
+9.1. Canonical Representation
+
+ For most types, there is a single canonical representation of the
+ type's values. Some types allow multiple lexical representations of
+ the same value; for example, the positive integer "17" can be
+ represented as "+17" or "17". Implementations MUST support all
+ lexical representations specified in this document.
+
+ When a server sends XML-encoded data, it MUST use the canonical form
+ defined in this section. Other encodings may introduce alternate
+ representations. Note, however, that values in the data tree are
+ conceptually stored in the canonical representation as defined in
+ this section. In particular, any XPath expression evaluations are
+ done using the canonical form if the data type has a canonical form.
+ If the data type does not have a canonical form, the format of the
+ value MUST match the data type's lexical representation, but the
+ exact format is implementation dependent.
+
+
+
+
+
+Bjorklund Standards Track [Page 141]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Some types have a lexical representation that depends on the
+ encoding, e.g., the XML context in which they occur. These types do
+ not have a canonical form.
+
+9.2. The Integer Built-In Types
+
+ The integer built-in types are int8, int16, int32, int64, uint8,
+ uint16, uint32, and uint64. They represent signed and unsigned
+ integers of different sizes:
+
+ int8 represents integer values between -128 and 127, inclusively.
+
+ int16 represents integer values between -32768 and 32767,
+ inclusively.
+
+ int32 represents integer values between -2147483648 and 2147483647,
+ inclusively.
+
+ int64 represents integer values between -9223372036854775808 and
+ 9223372036854775807, inclusively.
+
+ uint8 represents integer values between 0 and 255, inclusively.
+
+ uint16 represents integer values between 0 and 65535, inclusively.
+
+ uint32 represents integer values between 0 and 4294967295,
+ inclusively.
+
+ uint64 represents integer values between 0 and 18446744073709551615,
+ inclusively.
+
+9.2.1. Lexical Representation
+
+ An integer value is lexically represented as an optional sign ("+" or
+ "-"), followed by a sequence of decimal digits. If no sign is
+ specified, "+" is assumed.
+
+ For convenience, when specifying a default value for an integer in a
+ YANG module, an alternative lexical representation can be used that
+ represents the value in a hexadecimal or octal notation. The
+ hexadecimal notation consists of an optional sign ("+" or "-"),
+ followed by the characters "0x", followed by a number of hexadecimal
+ digits where letters may be uppercase or lowercase. The octal
+ notation consists of an optional sign ("+" or "-"), followed by the
+ character "0", followed by a number of octal digits.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 142]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ Note that if a default value in a YANG module has a leading zero
+ ("0"), it is interpreted as an octal number. In the XML encoding, an
+ integer is always interpreted as a decimal number, and leading zeros
+ are allowed.
+
+ Examples:
+
+ // legal values
+ +4711 // legal positive value
+ 4711 // legal positive value
+ -123 // legal negative value
+ 0xf00f // legal positive hexadecimal value
+ -0xf // legal negative hexadecimal value
+ 052 // legal positive octal value
+
+ // illegal values
+ - 1 // illegal intermediate space
+
+9.2.2. Canonical Form
+
+ The canonical form of a positive integer does not include the sign
+ "+". Leading zeros are prohibited. The value zero is represented
+ as "0".
+
+9.2.3. Restrictions
+
+ All integer types can be restricted with the "range" statement
+ (Section 9.2.4).
+
+9.2.4. The "range" Statement
+
+ The "range" statement, which is an optional substatement to the
+ "type" statement, takes as an argument a range expression string. It
+ is used to restrict integer and decimal built-in types, or types
+ derived from them.
+
+ A range consists of an explicit value, or a lower-inclusive bound,
+ two consecutive dots "..", and an upper-inclusive bound. Multiple
+ values or ranges can be given, separated by "|". If multiple values
+ or ranges are given, they all MUST be disjoint and MUST be in
+ ascending order. If a range restriction is applied to a type that is
+ already range-restricted, the new restriction MUST be equally
+ limiting or more limiting, i.e., raising the lower bounds, reducing
+ the upper bounds, removing explicit values or ranges, or splitting
+ ranges into multiple ranges with intermediate gaps. Each explicit
+ value and range boundary value given in the range expression MUST
+
+
+
+
+
+Bjorklund Standards Track [Page 143]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ match the type being restricted or be one of the special values "min"
+ or "max". "min" and "max" mean the minimum and maximum values
+ accepted for the type being restricted, respectively.
+
+ The range expression syntax is formally defined by the rule
+ "range-arg" in Section 14.
+
+9.2.4.1. The range's Substatements
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | error-app-tag | 7.5.4.2 | 0..1 |
+ | error-message | 7.5.4.1 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ +---------------+---------+-------------+
+
+9.2.5. Usage Example
+
+ typedef my-base-int32-type {
+ type int32 {
+ range "1..4 | 10..20";
+ }
+ }
+
+ typedef my-type1 {
+ type my-base-int32-type {
+ // legal range restriction
+ range "11..max"; // 11..20
+ }
+ }
+
+ typedef my-type2 {
+ type my-base-int32-type {
+ // illegal range restriction
+ range "11..100";
+ }
+ }
+
+9.3. The decimal64 Built-In Type
+
+ The decimal64 built-in type represents a subset of the real numbers,
+ which can be represented by decimal numerals. The value space of
+ decimal64 is the set of numbers that can be obtained by multiplying a
+ 64-bit signed integer by a negative power of ten, i.e., expressible
+ as "i x 10^-n" where i is an integer64 and n is an integer between 1
+ and 18, inclusively.
+
+
+
+Bjorklund Standards Track [Page 144]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.3.1. Lexical Representation
+
+ A decimal64 value is lexically represented as an optional sign ("+"
+ or "-"), followed by a sequence of decimal digits, optionally
+ followed by a period ('.') as a decimal indicator and a sequence of
+ decimal digits. If no sign is specified, "+" is assumed.
+
+9.3.2. Canonical Form
+
+ The canonical form of a positive decimal64 value does not include the
+ sign "+". The decimal point is required. Leading and trailing zeros
+ are prohibited, subject to the rule that there MUST be at least one
+ digit before and after the decimal point. The value zero is
+ represented as "0.0".
+
+9.3.3. Restrictions
+
+ A decimal64 type can be restricted with the "range" statement
+ (Section 9.2.4).
+
+9.3.4. The "fraction-digits" Statement
+
+ The "fraction-digits" statement, which is a substatement to the
+ "type" statement, MUST be present if the type is "decimal64". It
+ takes as an argument an integer between 1 and 18, inclusively. It
+ controls the size of the minimum difference between values of a
+ decimal64 type by restricting the value space to numbers that are
+ expressible as "i x 10^-n" where n is the fraction-digits argument.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 145]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following table lists the minimum and maximum values for each
+ fraction-digit value:
+
+ +----------------+-----------------------+----------------------+
+ | fraction-digit | min | max |
+ +----------------+-----------------------+----------------------+
+ | 1 | -922337203685477580.8 | 922337203685477580.7 |
+ | 2 | -92233720368547758.08 | 92233720368547758.07 |
+ | 3 | -9223372036854775.808 | 9223372036854775.807 |
+ | 4 | -922337203685477.5808 | 922337203685477.5807 |
+ | 5 | -92233720368547.75808 | 92233720368547.75807 |
+ | 6 | -9223372036854.775808 | 9223372036854.775807 |
+ | 7 | -922337203685.4775808 | 922337203685.4775807 |
+ | 8 | -92233720368.54775808 | 92233720368.54775807 |
+ | 9 | -9223372036.854775808 | 9223372036.854775807 |
+ | 10 | -922337203.6854775808 | 922337203.6854775807 |
+ | 11 | -92233720.36854775808 | 92233720.36854775807 |
+ | 12 | -9223372.036854775808 | 9223372.036854775807 |
+ | 13 | -922337.2036854775808 | 922337.2036854775807 |
+ | 14 | -92233.72036854775808 | 92233.72036854775807 |
+ | 15 | -9223.372036854775808 | 9223.372036854775807 |
+ | 16 | -922.3372036854775808 | 922.3372036854775807 |
+ | 17 | -92.23372036854775808 | 92.23372036854775807 |
+ | 18 | -9.223372036854775808 | 9.223372036854775807 |
+ +----------------+-----------------------+----------------------+
+
+9.3.5. Usage Example
+
+ typedef my-decimal {
+ type decimal64 {
+ fraction-digits 2;
+ range "1 .. 3.14 | 10 | 20..max";
+ }
+ }
+
+9.4. The string Built-In Type
+
+ The string built-in type represents human-readable strings in YANG.
+ Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646]
+ characters, including tab, carriage return, and line feed but
+ excluding the other C0 control characters, the surrogate blocks, and
+ the noncharacters. The string syntax is formally defined by the rule
+ "yang-string" in Section 14.
+
+9.4.1. Lexical Representation
+
+ A string value is lexically represented as character data in the XML
+ encoding.
+
+
+
+Bjorklund Standards Track [Page 146]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.4.2. Canonical Form
+
+ The canonical form is the same as the lexical representation. No
+ Unicode normalization of string values is performed.
+
+9.4.3. Restrictions
+
+ A string can be restricted with the "length" (Section 9.4.4) and
+ "pattern" (Section 9.4.5) statements.
+
+9.4.4. The "length" Statement
+
+ The "length" statement, which is an optional substatement to the
+ "type" statement, takes as an argument a length expression string.
+ It is used to restrict the built-in types "string" and "binary" or
+ types derived from them.
+
+ A "length" statement restricts the number of Unicode characters in
+ the string.
+
+ A length range consists of an explicit value, or a lower bound, two
+ consecutive dots "..", and an upper bound. Multiple values or ranges
+ can be given, separated by "|". Length-restricting values MUST NOT
+ be negative. If multiple values or ranges are given, they all MUST
+ be disjoint and MUST be in ascending order. If a length restriction
+ is applied to a type that is already length-restricted, the new
+ restriction MUST be equally limiting or more limiting, i.e., raising
+ the lower bounds, reducing the upper bounds, removing explicit length
+ values or ranges, or splitting ranges into multiple ranges with
+ intermediate gaps. A length value is a non-negative integer or one
+ of the special values "min" or "max". "min" and "max" mean the
+ minimum and maximum lengths accepted for the type being restricted,
+ respectively. An implementation is not required to support a length
+ value larger than 18446744073709551615.
+
+ The length expression syntax is formally defined by the rule
+ "length-arg" in Section 14.
+
+9.4.4.1. The length's Substatements
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | error-app-tag | 7.5.4.2 | 0..1 |
+ | error-message | 7.5.4.1 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ +---------------+---------+-------------+
+
+
+
+Bjorklund Standards Track [Page 147]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.4.5. The "pattern" Statement
+
+ The "pattern" statement, which is an optional substatement to the
+ "type" statement, takes as an argument a regular expression string,
+ as defined in [XSD-TYPES]. It is used to restrict the built-in type
+ "string", or types derived from "string", to values that match the
+ pattern.
+
+ If the type has multiple "pattern" statements, the expressions are
+ ANDed together, i.e., all such expressions have to match.
+
+ If a pattern restriction is applied to a type that is already
+ pattern-restricted, values must match all patterns in the base type,
+ in addition to the new patterns.
+
+9.4.5.1. The pattern's Substatements
+
+ +---------------+---------+-------------+
+ | substatement | section | cardinality |
+ +---------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | error-app-tag | 7.5.4.2 | 0..1 |
+ | error-message | 7.5.4.1 | 0..1 |
+ | modifier | 9.4.6 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ +---------------+---------+-------------+
+
+9.4.6. The "modifier" Statement
+
+ The "modifier" statement, which is an optional substatement to the
+ "pattern" statement, takes as an argument the string "invert-match".
+
+ If a pattern has the "invert-match" modifier present, the type is
+ restricted to values that do not match the pattern.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 148]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.4.7. Usage Example
+
+ With the following typedef:
+
+ typedef my-base-str-type {
+ type string {
+ length "1..255";
+ }
+ }
+
+ the following refinement is legal:
+
+ type my-base-str-type {
+ // legal length refinement
+ length "11 | 42..max"; // 11 | 42..255
+ }
+
+ and the following refinement is illegal:
+
+ type my-base-str-type {
+ // illegal length refinement
+ length "1..999";
+ }
+
+ With the following type:
+
+ type string {
+ length "0..4";
+ pattern "[0-9a-fA-F]*";
+ }
+
+ the following strings match:
+
+ AB // legal
+ 9A00 // legal
+
+ and the following strings do not match:
+
+ 00ABAB // illegal, too long
+ xx00 // illegal, bad characters
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 149]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ With the following type:
+
+ type string {
+ length "1..max";
+ pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
+ pattern '[xX][mM][lL].*' {
+ modifier invert-match;
+ }
+ }
+
+ the following string matches:
+
+ enabled // legal
+
+ and the following strings do not match:
+
+ 10-mbit // illegal, starts with a number
+ xml-element // illegal, starts with illegal sequence
+
+9.5. The boolean Built-In Type
+
+ The boolean built-in type represents a boolean value.
+
+9.5.1. Lexical Representation
+
+ The lexical representation of a boolean value is a string with a
+ value of "true" or "false". These values MUST be in lowercase.
+
+9.5.2. Canonical Form
+
+ The canonical form is the same as the lexical representation.
+
+9.5.3. Restrictions
+
+ A boolean cannot be restricted.
+
+9.6. The enumeration Built-In Type
+
+ The enumeration built-in type represents values from a set of
+ assigned names.
+
+9.6.1. Lexical Representation
+
+ The lexical representation of an enumeration value is the assigned
+ name string.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 150]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.6.2. Canonical Form
+
+ The canonical form is the assigned name string.
+
+9.6.3. Restrictions
+
+ An enumeration can be restricted with one or more "enum"
+ (Section 9.6.4) statements, which enumerate a subset of the values
+ for the base type.
+
+9.6.4. The "enum" Statement
+
+ The "enum" statement, which is a substatement to the "type"
+ statement, MUST be present if the type is "enumeration". It is
+ repeatedly used to specify each assigned name of an enumeration type.
+ It takes as an argument a string that is the assigned name. The
+ string MUST NOT be zero-length and MUST NOT have any leading or
+ trailing whitespace characters (any Unicode character with the
+ "White_Space" property). The use of Unicode control codes SHOULD be
+ avoided.
+
+ The statement is optionally followed by a block of substatements that
+ holds detailed enum information.
+
+ All assigned names in an enumeration MUST be unique.
+
+ When an existing enumeration type is restricted, the set of assigned
+ names in the new type MUST be a subset of the base type's set of
+ assigned names. The value of such an assigned name MUST NOT be
+ changed.
+
+9.6.4.1. The enum's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ | value | 9.6.4.2 | 0..1 |
+ +--------------+---------+-------------+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 151]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.6.4.2. The "value" Statement
+
+ The "value" statement, which is optional, is used to associate an
+ integer value with the assigned name for the enum. This integer
+ value MUST be in the range -2147483648 to 2147483647, and it MUST be
+ unique within the enumeration type.
+
+ If a value is not specified, then one will be automatically assigned.
+ If the "enum" substatement is the first one defined, the assigned
+ value is zero (0); otherwise, the assigned value is one greater than
+ the current highest enum value (i.e., the highest enum value,
+ implicit or explicit, prior to the current "enum" substatement in the
+ parent "type" statement).
+
+ Note that the presence of an "if-feature" statement in an "enum"
+ statement does not affect the automatically assigned value.
+
+ If the current highest value is equal to 2147483647, then an enum
+ value MUST be specified for "enum" substatements following the one
+ with the current highest value.
+
+ When an existing enumeration type is restricted, the "value"
+ statement MUST either have the same value as in the base type or not
+ be present, in which case the value is the same as in the base type.
+
+9.6.5. Usage Example
+
+ leaf myenum {
+ type enumeration {
+ enum zero;
+ enum one;
+ enum seven {
+ value 7;
+ }
+ }
+ }
+
+ The lexical representation of the leaf "myenum" with
+ value "seven" is:
+
+ <myenum>seven</myenum>
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 152]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ With the following typedef:
+
+ typedef my-base-enumeration-type {
+ type enumeration {
+ enum white {
+ value 1;
+ }
+ enum yellow {
+ value 2;
+ }
+ enum red {
+ value 3;
+ }
+ }
+ }
+
+ the following refinement is legal:
+
+ type my-base-enumeration-type {
+ // legal enum refinement
+ enum yellow;
+ enum red {
+ value 3;
+ }
+ }
+
+ and the following refinement is illegal:
+
+ type my-base-enumeration-type {
+ // illegal enum refinement
+ enum yellow {
+ value 4; // illegal value change
+ }
+ enum black; // illegal addition of new name
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 153]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The following example shows how an "enum" can be tagged with
+ "if-feature", making the value legal only on servers that advertise
+ the corresponding feature:
+
+ type enumeration {
+ enum tcp;
+ enum ssh {
+ if-feature ssh;
+ }
+ enum tls {
+ if-feature tls;
+ }
+ }
+
+9.7. The bits Built-In Type
+
+ The bits built-in type represents a bit set. That is, a bits value
+ is a set of flags identified by small integer position numbers
+ starting at 0. Each bit number has an assigned name.
+
+ When an existing bits type is restricted, the set of assigned names
+ in the new type MUST be a subset of the base type's set of assigned
+ names. The bit position of such an assigned name MUST NOT be
+ changed.
+
+9.7.1. Restrictions
+
+ A bits type can be restricted with the "bit" (Section 9.7.4)
+ statement.
+
+9.7.2. Lexical Representation
+
+ The lexical representation of the bits type is a space-separated list
+ of the names of the bits that are set. A zero-length string thus
+ represents a value where no bits are set.
+
+9.7.3. Canonical Form
+
+ In the canonical form, the bit values are separated by a single space
+ character and they appear ordered by their position (see
+ Section 9.7.4.2).
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 154]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.7.4. The "bit" Statement
+
+ The "bit" statement, which is a substatement to the "type" statement,
+ MUST be present if the type is "bits". It is repeatedly used to
+ specify each assigned named bit of a bits type. It takes as an
+ argument a string that is the assigned name of the bit. It is
+ followed by a block of substatements that holds detailed bit
+ information. The assigned name follows the same syntax rules as an
+ identifier (see Section 6.2).
+
+ All assigned names in a bits type MUST be unique.
+
+9.7.4.1. The bit's Substatements
+
+ +--------------+---------+-------------+
+ | substatement | section | cardinality |
+ +--------------+---------+-------------+
+ | description | 7.21.3 | 0..1 |
+ | if-feature | 7.20.2 | 0..n |
+ | position | 9.7.4.2 | 0..1 |
+ | reference | 7.21.4 | 0..1 |
+ | status | 7.21.2 | 0..1 |
+ +--------------+---------+-------------+
+
+9.7.4.2. The "position" Statement
+
+ The "position" statement, which is optional, takes as an argument a
+ non-negative integer value that specifies the bit's position within a
+ hypothetical bit field. The position value MUST be in the range 0 to
+ 4294967295, and it MUST be unique within the bits type.
+
+ If a bit position is not specified, then one will be automatically
+ assigned. If the "bit" substatement is the first one defined, the
+ assigned value is zero (0); otherwise, the assigned value is one
+ greater than the current highest bit position (i.e., the highest bit
+ position, implicit or explicit, prior to the current "bit"
+ substatement in the parent "type" statement).
+
+ Note that the presence of an "if-feature" statement in a "bit"
+ statement does not affect the automatically assigned position.
+
+ If the current highest bit position value is equal to 4294967295,
+ then a position value MUST be specified for "bit" substatements
+ following the one with the current highest position value.
+
+ When an existing bits type is restricted, the "position" statement
+ MUST either have the same value as in the base type or not be
+ present, in which case the value is the same as in the base type.
+
+
+
+Bjorklund Standards Track [Page 155]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.7.5. Usage Example
+
+ Given the following typedef and leaf:
+
+ typedef mybits-type {
+ type bits {
+ bit disable-nagle {
+ position 0;
+ }
+ bit auto-sense-speed {
+ position 1;
+ }
+ bit ten-mb-only {
+ position 2;
+ }
+ }
+ }
+
+ leaf mybits {
+ type mybits-type;
+ default "auto-sense-speed";
+ }
+
+ The lexical representation of this leaf with bit values disable-nagle
+ and ten-mb-only set would be:
+
+ <mybits>disable-nagle ten-mb-only</mybits>
+
+ The following example shows a legal refinement of this type:
+
+ type mybits-type {
+ // legal bit refinement
+ bit disable-nagle {
+ position 0;
+ }
+ bit auto-sense-speed {
+ position 1;
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 156]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ and the following refinement is illegal:
+
+ type mybits-type {
+ // illegal bit refinement
+ bit disable-nagle {
+ position 2; // illegal position change
+ }
+ bit hundred-mb-only; // illegal addition of new name
+ }
+
+9.8. The binary Built-In Type
+
+ The binary built-in type represents any binary data, i.e., a sequence
+ of octets.
+
+9.8.1. Restrictions
+
+ A binary type can be restricted with the "length" (Section 9.4.4)
+ statement. The length of a binary value is the number of octets it
+ contains.
+
+9.8.2. Lexical Representation
+
+ Binary values are encoded with the base64 encoding scheme (see
+ Section 4 in [RFC4648]).
+
+9.8.3. Canonical Form
+
+ The canonical form of a binary value follows the rules of "Base 64
+ Encoding" in [RFC4648].
+
+9.9. The leafref Built-In Type
+
+ The leafref built-in type is restricted to the value space of some
+ leaf or leaf-list node in the schema tree and optionally further
+ restricted by corresponding instance nodes in the data tree. The
+ "path" substatement (Section 9.9.2) is used to identify the referred
+ leaf or leaf-list node in the schema tree. The value space of the
+ referring node is the value space of the referred node.
+
+ If the "require-instance" property (Section 9.9.3) is "true", there
+ MUST exist a node in the data tree, or a node with a default value in
+ use (see Sections 7.6.1 and 7.7.2), of the referred schema tree leaf
+ or leaf-list node with the same value as the leafref value in a valid
+ data tree.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 157]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If the referring node represents configuration data and the
+ "require-instance" property (Section 9.9.3) is "true", the referred
+ node MUST also represent configuration.
+
+ There MUST NOT be any circular chains of leafrefs.
+
+ If the leaf that the leafref refers to is conditional based on one or
+ more features (see Section 7.20.2), then the leaf with the leafref
+ type MUST also be conditional based on at least the same set of
+ features.
+
+9.9.1. Restrictions
+
+ A leafref can be restricted with the "require-instance" statement
+ (Section 9.9.3).
+
+9.9.2. The "path" Statement
+
+ The "path" statement, which is a substatement to the "type"
+ statement, MUST be present if the type is "leafref". It takes as an
+ argument a string that MUST refer to a leaf or leaf-list node.
+
+ The syntax for a path argument is a subset of the XPath abbreviated
+ syntax. Predicates are used only for constraining the values for the
+ key nodes for list entries. Each predicate consists of exactly one
+ equality test per key, and multiple adjacent predicates MAY be
+ present if a list has multiple keys. The syntax is formally defined
+ by the rule "path-arg" in Section 14.
+
+ The predicates are only used when more than one key reference is
+ needed to uniquely identify a leaf instance. This occurs if a list
+ has multiple keys or a reference to a leaf other than the key in a
+ list is needed. In these cases, multiple leafrefs are typically
+ specified, and predicates are used to tie them together.
+
+ The "path" expression evaluates to a node set consisting of zero,
+ one, or more nodes. If the "require-instance" property is "true",
+ this node set MUST be non-empty.
+
+ The "path" XPath expression is conceptually evaluated in the
+ following context, in addition to the definition in Section 6.4.1:
+
+ o If the "path" statement is defined within a typedef, the context
+ node is the leaf or leaf-list node in the data tree that
+ references the typedef.
+
+ o Otherwise, the context node is the node in the data tree for which
+ the "path" statement is defined.
+
+
+
+Bjorklund Standards Track [Page 158]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.9.3. The "require-instance" Statement
+
+ The "require-instance" statement, which is a substatement to the
+ "type" statement, MAY be present if the type is "instance-identifier"
+ or "leafref". It takes as an argument the string "true" or "false".
+ If this statement is not present, it defaults to "true".
+
+ If "require-instance" is "true", it means that the instance being
+ referred to MUST exist for the data to be valid. This constraint is
+ enforced according to the rules in Section 8.
+
+ If "require-instance" is "false", it means that the instance being
+ referred to MAY exist in valid data.
+
+9.9.4. Lexical Representation
+
+ A leafref value is lexically represented the same way as the leaf it
+ references represents its value.
+
+9.9.5. Canonical Form
+
+ The canonical form of a leafref is the same as the canonical form of
+ the leaf it references.
+
+9.9.6. Usage Example
+
+ With the following list:
+
+ list interface {
+ key "name";
+ leaf name {
+ type string;
+ }
+ leaf admin-status {
+ type admin-status;
+ }
+ list address {
+ key "ip";
+ leaf ip {
+ type yang:ip-address;
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 159]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ the following leafref refers to an existing interface:
+
+ leaf mgmt-interface {
+ type leafref {
+ path "../interface/name";
+ }
+ }
+
+ An example of a corresponding XML snippet:
+
+ <interface>
+ <name>eth0</name>
+ </interface>
+ <interface>
+ <name>lo</name>
+ </interface>
+
+ <mgmt-interface>eth0</mgmt-interface>
+
+ The following leafrefs refer to an existing address of an interface:
+
+ container default-address {
+ leaf ifname {
+ type leafref {
+ path "../../interface/name";
+ }
+ }
+ leaf address {
+ type leafref {
+ path "../../interface[name = current()/../ifname]"
+ + "/address/ip";
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 160]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ An example of a corresponding XML snippet:
+
+ <interface>
+ <name>eth0</name>
+ <admin-status>up</admin-status>
+ <address>
+ <ip>192.0.2.1</ip>
+ </address>
+ <address>
+ <ip>192.0.2.2</ip>
+ </address>
+ </interface>
+ <interface>
+ <name>lo</name>
+ <admin-status>up</admin-status>
+ <address>
+ <ip>127.0.0.1</ip>
+ </address>
+ </interface>
+
+ <default-address>
+ <ifname>eth0</ifname>
+ <address>192.0.2.2</address>
+ </default-address>
+
+ The following list uses a leafref for one of its keys. This is
+ similar to a foreign key in a relational database.
+
+ list packet-filter {
+ key "if-name filter-id";
+ leaf if-name {
+ type leafref {
+ path "/interface/name";
+ }
+ }
+ leaf filter-id {
+ type uint32;
+ }
+ ...
+ }
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 161]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ An example of a corresponding XML snippet:
+
+ <interface>
+ <name>eth0</name>
+ <admin-status>up</admin-status>
+ <address>
+ <ip>192.0.2.1</ip>
+ </address>
+ <address>
+ <ip>192.0.2.2</ip>
+ </address>
+ </interface>
+
+ <packet-filter>
+ <if-name>eth0</if-name>
+ <filter-id>1</filter-id>
+ ...
+ </packet-filter>
+ <packet-filter>
+ <if-name>eth0</if-name>
+ <filter-id>2</filter-id>
+ ...
+ </packet-filter>
+
+ The following notification defines two leafrefs to refer to an
+ existing admin-status:
+
+ notification link-failure {
+ leaf if-name {
+ type leafref {
+ path "/interface/name";
+ }
+ }
+ leaf admin-status {
+ type leafref {
+ path "/interface[name = current()/../if-name]"
+ + "/admin-status";
+ }
+ }
+ }
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 162]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ An example of a corresponding XML notification:
+
+ <notification
+ xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
+ <eventTime>2008-04-01T00:01:00Z</eventTime>
+ <link-failure xmlns="urn:example:system">
+ <if-name>eth0</if-name>
+ <admin-status>up</admin-status>
+ </link-failure>
+ </notification>
+
+9.10. The identityref Built-In Type
+
+ The identityref built-in type is used to reference an existing
+ identity (see Section 7.18).
+
+9.10.1. Restrictions
+
+ An identityref cannot be restricted.
+
+9.10.2. The identityref's "base" Statement
+
+ The "base" statement, which is a substatement to the "type"
+ statement, MUST be present at least once if the type is
+ "identityref". The argument is the name of an identity, as defined
+ by an "identity" statement. If a prefix is present on the identity
+ name, it refers to an identity defined in the module that was
+ imported with that prefix. Otherwise, an identity with the matching
+ name MUST be defined in the current module or an included submodule.
+
+ Valid values for an identityref are any identities derived from all
+ the identityref's base identities. On a particular server, the valid
+ values are further restricted to the set of identities defined in the
+ modules implemented by the server.
+
+9.10.3. Lexical Representation
+
+ An identityref is lexically represented as the referred identity's
+ qualified name as defined in [XML-NAMES]. If the prefix is not
+ present, the namespace of the identityref is the default namespace
+ in effect on the element that contains the identityref value.
+
+ When an identityref is given a default value using the "default"
+ statement, the identity name in the default value MAY have a prefix.
+ If a prefix is present on the identity name, it refers to an identity
+ defined in the module that was imported with that prefix, or the
+ prefix for the current module if the identity is defined in the
+
+
+
+
+Bjorklund Standards Track [Page 163]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ current module or one of its submodules. Otherwise, an identity with
+ the matching name MUST be defined in the current module or one of its
+ submodules.
+
+ The string value of a node of type "identityref" in a "must" or
+ "when" XPath expression is the referred identity's qualified name
+ with the prefix present. If the referred identity is defined in an
+ imported module, the prefix in the string value is the prefix defined
+ in the corresponding "import" statement. Otherwise, the prefix in
+ the string value is the prefix for the current module.
+
+9.10.4. Canonical Form
+
+ Since the lexical form depends on the XML context in which the value
+ occurs, this type does not have a canonical form.
+
+9.10.5. Usage Example
+
+ With the identity definitions in Section 7.18.3 and the following
+ module:
+
+ module example-my-crypto {
+ yang-version 1.1;
+ namespace "urn:example:my-crypto";
+ prefix mc;
+
+ import "example-crypto-base" {
+ prefix "crypto";
+ }
+
+ identity aes {
+ base "crypto:crypto-alg";
+ }
+
+ leaf crypto {
+ type identityref {
+ base "crypto:crypto-alg";
+ }
+ }
+
+ container aes-parameters {
+ when "../crypto = 'mc:aes'";
+ ...
+ }
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 164]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ the following is an example of how the leaf "crypto" can be encoded,
+ if the value is the "des3" identity defined in the "des" module:
+
+ <crypto xmlns:des="urn:example:des">des:des3</crypto>
+
+ Any prefixes used in the encoding are local to each instance
+ encoding. This means that the same identityref may be encoded
+ differently by different implementations. For example, the following
+ example encodes the same leaf as above:
+
+ <crypto xmlns:x="urn:example:des">x:des3</crypto>
+
+ If the "crypto" leaf's value is instead "aes", defined in the
+ "example-my-crypto" module, it can be encoded as:
+
+ <crypto xmlns:mc="urn:example:my-crypto">mc:aes</crypto>
+
+ or, using the default namespace:
+
+ <crypto>aes</crypto>
+
+9.11. The empty Built-In Type
+
+ The empty built-in type represents a leaf that does not have any
+ value; it conveys information by its presence or absence.
+
+ An empty type cannot have a default value.
+
+9.11.1. Restrictions
+
+ An empty type cannot be restricted.
+
+9.11.2. Lexical Representation
+
+ Not applicable.
+
+9.11.3. Canonical Form
+
+ Not applicable.
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 165]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.11.4. Usage Example
+
+ With the following leaf:
+
+ leaf enable-qos {
+ type empty;
+ }
+
+ the following is an example of a valid encoding if the leaf exists:
+
+ <enable-qos/>
+
+9.12. The union Built-In Type
+
+ The union built-in type represents a value that corresponds to one of
+ its member types.
+
+ When the type is "union", the "type" statement (Section 7.4) MUST be
+ present. It is repeatedly used to specify each member type of the
+ union. It takes as an argument a string that is the name of a
+ member type.
+
+ A member type can be of any built-in or derived type.
+
+ When generating an XML encoding, a value is encoded according to the
+ rules of the member type to which the value belongs. When
+ interpreting an XML encoding, a value is validated consecutively
+ against each member type, in the order they are specified in the
+ "type" statement, until a match is found. The type that matched will
+ be the type of the value for the node that was validated, and the
+ encoding is interpreted according to the rules for that type.
+
+ Any default value or "units" property defined in the member types is
+ not inherited by the union type.
+
+9.12.1. Restrictions
+
+ A union cannot be restricted. However, each member type can be
+ restricted, based on the rules defined in Section 9.
+
+9.12.2. Lexical Representation
+
+ The lexical representation of a union is a value that corresponds to
+ the representation of any one of the member types.
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 166]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.12.3. Canonical Form
+
+ The canonical form of a union value is the same as the canonical form
+ of the member type of the value.
+
+9.12.4. Usage Example
+
+ The following is a union of an int32 and an enumeration:
+
+ type union {
+ type int32;
+ type enumeration {
+ enum "unbounded";
+ }
+ }
+
+ Care must be taken when a member type is a leafref where the
+ "require-instance" property (Section 9.9.3) is "true". If a leaf of
+ such a type refers to an existing instance, the leaf's value must be
+ revalidated if the target instance is deleted. For example, with the
+ following definitions:
+
+ list filter {
+ key name;
+ leaf name {
+ type string;
+ }
+ ...
+ }
+
+ leaf outbound-filter {
+ type union {
+ type leafref {
+ path "/filter/name";
+ }
+ type enumeration {
+ enum default-filter;
+ }
+ }
+ }
+
+ assume that there exists an entry in the filter list with the name
+ "http" and that the outbound-filter leaf has this value:
+
+ <filter>
+ <name>http</name>
+ </filter>
+ <outbound-filter>http</outbound-filter>
+
+
+
+Bjorklund Standards Track [Page 167]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ If the filter entry "http" is removed, the outbound-filter leaf's
+ value doesn't match the leafref, and the next member type is checked.
+ The current value ("http") doesn't match the enumeration, so the
+ resulting configuration is invalid.
+
+ If the second member type in the union had been of type "string"
+ instead of an enumeration, the current value would have matched, and
+ the resulting configuration would have been valid.
+
+9.13. The instance-identifier Built-In Type
+
+ The instance-identifier built-in type is used to uniquely identify a
+ particular instance node in the data tree.
+
+ The syntax for an instance-identifier is a subset of the XPath
+ abbreviated syntax, formally defined by the rule
+ "instance-identifier" in Section 14. It is used to uniquely identify
+ a node in the data tree. Predicates are used only for specifying the
+ values for the key nodes for list entries, a value of a leaf-list
+ entry, or a positional index for a list without keys. For
+ identifying list entries with keys, each predicate consists of one
+ equality test per key, and each key MUST have a corresponding
+ predicate. If a key is of type "empty", it is represented as a
+ zero-length string ("").
+
+ If the leaf with the instance-identifier type represents
+ configuration data and the "require-instance" property
+ (Section 9.9.3) is "true", the node it refers to MUST also represent
+ configuration. Such a leaf puts a constraint on valid data. All
+ such leaf nodes MUST reference existing nodes or leaf or leaf-list
+ nodes with their default value in use (see Sections 7.6.1 and 7.7.2)
+ for the data to be valid. This constraint is enforced according to
+ the rules in Section 8.
+
+ The "instance-identifier" XPath expression is conceptually evaluated
+ in the following context, in addition to the definition in
+ Section 6.4.1:
+
+ o The context node is the root node in the accessible tree.
+
+9.13.1. Restrictions
+
+ An instance-identifier can be restricted with the "require-instance"
+ statement (Section 9.9.3).
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 168]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+9.13.2. Lexical Representation
+
+ An instance-identifier value is lexically represented as a string.
+ All node names in an instance-identifier value MUST be qualified with
+ explicit namespace prefixes, and these prefixes MUST be declared in
+ the XML namespace scope in the instance-identifier's XML element.
+
+ Any prefixes used in the encoding are local to each instance
+ encoding. This means that the same instance-identifier may be
+ encoded differently by different implementations.
+
+9.13.3. Canonical Form
+
+ Since the lexical form depends on the XML context in which the value
+ occurs, this type does not have a canonical form.
+
+9.13.4. Usage Example
+
+ The following are examples of instance identifiers:
+
+ /* instance-identifier for a container */
+ /ex:system/ex:services/ex:ssh
+
+ /* instance-identifier for a leaf */
+ /ex:system/ex:services/ex:ssh/ex:port
+
+ /* instance-identifier for a list entry */
+ /ex:system/ex:user[ex:name='fred']
+
+ /* instance-identifier for a leaf in a list entry */
+ /ex:system/ex:user[ex:name='fred']/ex:type
+
+ /* instance-identifier for a list entry with two keys */
+ /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80']
+
+ /* instance-identifier for a list entry where the second
+ key ("enabled") is of type "empty" */
+ /ex:system/ex:service[ex:name='foo'][ex:enabled='']
+
+ /* instance-identifier for a leaf-list entry */
+ /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc']
+
+ /* instance-identifier for a list entry without keys */
+ /ex:stats/ex:port[3]
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 169]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10. XPath Functions
+
+ This document defines two generic XPath functions and five YANG
+ type-specific XPath functions. The function signatures are specified
+ with the syntax used in [XPATH].
+
+10.1. Function for Node Sets
+
+10.1.1. current()
+
+ node-set current()
+
+ The current() function takes no input parameters and returns a node
+ set with the initial context node as its only member.
+
+10.1.1.1. Usage Example
+
+ With this list:
+
+ list interface {
+ key "name";
+ ...
+ leaf enabled {
+ type boolean;
+ }
+ ...
+ }
+
+ the following leaf defines a "must" expression that ensures that the
+ referred interface is enabled:
+
+ leaf outgoing-interface {
+ type leafref {
+ path "/interface/name";
+ }
+ must '/interface[name=current()]/enabled = "true"';
+ }
+
+10.2. Function for Strings
+
+10.2.1. re-match()
+
+ boolean re-match(string subject, string pattern)
+
+ The re-match() function returns "true" if the "subject" string
+ matches the regular expression "pattern"; otherwise, it returns
+ "false".
+
+
+
+
+Bjorklund Standards Track [Page 170]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ The re-match() function checks to see if a string matches a given
+ regular expression. The regular expressions used are the XML Schema
+ regular expressions [XSD-TYPES]. Note that this includes implicit
+ anchoring of the regular expression at the head and tail.
+
+10.2.1.1. Usage Example
+
+ The expression:
+
+ re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}")
+
+ returns "true".
+
+ To count all logical interfaces called eth0.<number>, do:
+
+ count(/interface[re-match(name, "eth0\.\d+")])
+
+10.3. Function for the YANG Types "leafref" and "instance-identifier"
+
+10.3.1. deref()
+
+ node-set deref(node-set nodes)
+
+ The deref() function follows the reference defined by the first node
+ in document order in the argument "nodes" and returns the nodes it
+ refers to.
+
+ If the first argument node is of type "instance-identifier", the
+ function returns a node set that contains the single node that the
+ instance identifier refers to, if it exists. If no such node exists,
+ an empty node set is returned.
+
+ If the first argument node is of type "leafref", the function returns
+ a node set that contains the nodes that the leafref refers to.
+ Specifically, this set contains the nodes selected by the leafref's
+ "path" statement (Section 9.9.2) that have the same value as the
+ first argument node.
+
+ If the first argument node is of any other type, an empty node set is
+ returned.
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 171]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10.3.1.1. Usage Example
+
+ list interface {
+ key "name type";
+ leaf name { ... }
+ leaf type { ... }
+ leaf enabled {
+ type boolean;
+ }
+ ...
+ }
+
+ container mgmt-interface {
+ leaf name {
+ type leafref {
+ path "/interface/name";
+ }
+ }
+ leaf type {
+ type leafref {
+ path "/interface[name=current()/../name]/type";
+ }
+ must 'deref(.)/../enabled = "true"' {
+ error-message
+ "The management interface cannot be disabled.";
+ }
+ }
+ }
+
+10.4. Functions for the YANG Type "identityref"
+
+10.4.1. derived-from()
+
+ boolean derived-from(node-set nodes, string identity)
+
+ The derived-from() function returns "true" if any node in the
+ argument "nodes" is a node of type "identityref" and its value is an
+ identity that is derived from (see Section 7.18.2) the identity
+ "identity"; otherwise, it returns "false".
+
+ The parameter "identity" is a string matching the rule
+ "identifier-ref" in Section 14. If a prefix is present on the
+ identity, it refers to an identity defined in the module that was
+ imported with that prefix, or the local module if the prefix matches
+ the local module's prefix. If no prefix is present, the identity
+ refers to an identity defined in the current module or an included
+ submodule.
+
+
+
+
+Bjorklund Standards Track [Page 172]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10.4.1.1. Usage Example
+
+ module example-interface {
+ yang-version 1.1;
+
+ ...
+ identity interface-type;
+
+ identity ethernet {
+ base interface-type;
+ }
+
+ identity fast-ethernet {
+ base ethernet;
+ }
+
+ identity gigabit-ethernet {
+ base ethernet;
+ }
+
+ list interface {
+ key name;
+ ...
+ leaf type {
+ type identityref {
+ base interface-type;
+ }
+ }
+ ...
+ }
+
+ augment "/interface" {
+ when 'derived-from(type, "exif:ethernet")';
+ // generic Ethernet definitions here
+ }
+ ...
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 173]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10.4.2. derived-from-or-self()
+
+ boolean derived-from-or-self(node-set nodes, string identity)
+
+ The derived-from-or-self() function returns "true" if any node in the
+ argument "nodes" is a node of type "identityref" and its value is an
+ identity that is equal to or derived from (see Section 7.18.2) the
+ identity "identity"; otherwise, it returns "false".
+
+ The parameter "identity" is a string matching the rule
+ "identifier-ref" in Section 14. If a prefix is present on the
+ identity, it refers to an identity defined in the module that was
+ imported with that prefix, or the local module if the prefix matches
+ the local module's prefix. If no prefix is present, the identity
+ refers to an identity defined in the current module or an included
+ submodule.
+
+10.4.2.1. Usage Example
+
+ The module defined in Section 10.4.1.1 might also have:
+
+ augment "/interface" {
+ when 'derived-from-or-self(type, "exif:fast-ethernet");
+ // Fast-Ethernet-specific definitions here
+ }
+
+10.5. Function for the YANG Type "enumeration"
+
+10.5.1. enum-value()
+
+ number enum-value(node-set nodes)
+
+ The enum-value() function checks to see if the first node in document
+ order in the argument "nodes" is a node of type "enumeration" and
+ returns the enum's integer value. If the "nodes" node set is empty
+ or if the first node in "nodes" is not of type "enumeration", it
+ returns NaN (not a number).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 174]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10.5.1.1. Usage Example
+
+ With this data model:
+
+ list alarm {
+ ...
+ leaf severity {
+ type enumeration {
+ enum cleared {
+ value 1;
+ }
+ enum indeterminate {
+ value 2;
+ }
+ enum minor {
+ value 3;
+ }
+ enum warning {
+ value 4;
+ }
+ enum major {
+ value 5;
+ }
+ enum critical {
+ value 6;
+ }
+ }
+ }
+ }
+
+ the following XPath expression selects only alarms that are of
+ severity "major" or higher:
+
+ /alarm[enum-value(severity) >= 5]
+
+10.6. Function for the YANG Type "bits"
+
+10.6.1. bit-is-set()
+
+ boolean bit-is-set(node-set nodes, string bit-name)
+
+ The bit-is-set() function returns "true" if the first node in
+ document order in the argument "nodes" is a node of type "bits" and
+ its value has the bit "bit-name" set; otherwise, it returns "false".
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 175]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+10.6.1.1. Usage Example
+
+ If an interface has this leaf:
+
+ leaf flags {
+ type bits {
+ bit UP;
+ bit PROMISCUOUS
+ bit DISABLED;
+ }
+ }
+
+ the following XPath expression can be used to select all interfaces
+ with the UP flag set:
+
+ /interface[bit-is-set(flags, "UP")]
+
+11. Updating a Module
+
+ As experience is gained with a module, it may be desirable to revise
+ that module. However, changes to published modules are not allowed
+ if they have any potential to cause interoperability problems between
+ a client using an original specification and a server using an
+ updated specification.
+
+ For any published change, a new "revision" statement (Section 7.1.9)
+ MUST be included in front of the existing "revision" statements. If
+ there are no existing "revision" statements, then one MUST be added
+ to identify the new revision. Furthermore, any necessary changes
+ MUST be applied to any metadata statements, including the
+ "organization" and "contact" statements (Sections 7.1.7 and 7.1.8).
+
+ Note that definitions contained in a module are available to be
+ imported by any other module and are referenced in "import"
+ statements via the module name. Thus, a module name MUST NOT be
+ changed. Furthermore, the "namespace" statement MUST NOT be changed,
+ since all XML elements are qualified by the namespace.
+
+ Obsolete definitions MUST NOT be removed from published modules,
+ since their identifiers may still be referenced by other modules.
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 176]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ A definition in a published module may be revised in any of the
+ following ways:
+
+ o An "enumeration" type may have new enums added, provided the old
+ enums's values do not change. Note that inserting a new enum
+ before an existing enum or reordering existing enums will result
+ in new values for the existing enums, unless they have explicit
+ values assigned to them.
+
+ o A "bits" type may have new bits added, provided the old bit
+ positions do not change. Note that inserting a new bit before an
+ existing bit or reordering existing bits will result in new
+ positions for the existing bits, unless they have explicit
+ positions assigned to them.
+
+ o A "range", "length", or "pattern" statement may expand the allowed
+ value space.
+
+ o A "default" statement may be added to a leaf that does not have a
+ default value (either directly or indirectly through its type).
+
+ o A "units" statement may be added.
+
+ o A "reference" statement may be added or updated.
+
+ o A "must" statement may be removed or its constraint relaxed.
+
+ o A "when" statement may be removed or its constraint relaxed.
+
+ o A "mandatory" statement may be removed or changed from "true" to
+ "false".
+
+ o A "min-elements" statement may be removed, or changed to require
+ fewer elements.
+
+ o A "max-elements" statement may be removed, or changed to allow
+ more elements.
+
+ o A "description" statement may be added or changed without changing
+ the semantics of the definition.
+
+ o A "base" statement may be added to an "identity" statement.
+
+ o A "base" statement may be removed from an "identityref" type,
+ provided there is at least one "base" statement left.
+
+ o New typedefs, groupings, rpcs, notifications, extensions,
+ features, and identities may be added.
+
+
+
+Bjorklund Standards Track [Page 177]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ o New data definition statements may be added if they do not add
+ mandatory nodes (Section 3) to existing nodes or at the top level
+ in a module or submodule, or if they are conditionally dependent
+ on a new feature (i.e., have an "if-feature" statement that refers
+ to a new feature).
+
+ o A new "case" statement may be added.
+
+ o A node that represented state data may be changed to represent
+ configuration, provided it is not mandatory (Section 3).
+
+ o An "if-feature" statement may be removed, provided its node is not
+ mandatory (Section 3).
+
+ o A "status" statement may be added, or changed from "current" to
+ "deprecated" or "obsolete", or changed from "deprecated" to
+ "obsolete".
+
+ o A "type" statement may be replaced with another "type" statement
+ that does not change the syntax or semantics of the type. For
+ example, an inline type definition may be replaced with a typedef,
+ but an int8 type cannot be replaced by an int16, since the syntax
+ would change.
+
+ o Any set of data definition nodes may be replaced with another set
+ of syntactically and semantically equivalent nodes. For example,
+ a set of leafs may be replaced by a "uses" statement of a grouping
+ with the same leafs.
+
+ o A module may be split into a set of submodules or a submodule may
+ be removed, provided the definitions in the module do not change
+ in any way other than those allowed here.
+
+ o The "prefix" statement may be changed, provided all local uses of
+ the prefix are also changed.
+
+ Otherwise, if the semantics of any previous definition are changed
+ (i.e., if a non-editorial change is made to any definition other than
+ those specifically allowed above), then this MUST be achieved by a
+ new definition with a new identifier.
+
+ In statements that have any data definition statements as
+ substatements, those data definition substatements MUST NOT be
+ reordered. If new data definition statements are added, they can be
+ added anywhere in the sequence of existing substatements.
+
+
+
+
+
+
+Bjorklund Standards Track [Page 178]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+12. Coexistence with YANG Version 1
+
+ A YANG version 1.1 module MUST NOT include a YANG version 1
+ submodule, and a YANG version 1 module MUST NOT include a YANG
+ version 1.1 submodule.
+
+ A YANG version 1 module or submodule MUST NOT import a YANG
+ version 1.1 module by revision.
+
+ A YANG version 1.1 module or submodule MAY import a YANG version 1
+ module by revision.
+
+ If a YANG version 1 module A imports module B without revision and
+ module B is updated to YANG version 1.1, a server MAY implement both
+ of these modules (A and B) at the same time. In such cases, a
+ NETCONF server MUST advertise both modules using the rules defined in
+ Section 5.6.4, and SHOULD advertise module A and the latest revision
+ of module B that is specified with YANG version 1 according to the
+ rules defined in [RFC6020].
+
+ This rule exists in order to allow implementations of existing YANG
+ version 1 modules together with YANG version 1.1 modules. Without
+ this rule, updating a single module to YANG version 1.1 would have a
+ cascading effect on modules that import it, requiring all of them to
+ also be updated to YANG version 1.1, and so on.
+
+13. YIN
+
+ A YANG module can be translated into an alternative XML-based syntax
+ called YIN. The translated module is called a YIN module. This
+ section describes bidirectional mapping rules between the two
+ formats.
+
+ The YANG and YIN formats contain equivalent information using
+ different notations. The YIN notation enables developers to
+ represent YANG data models in XML and therefore use the rich set of
+ XML-based tools for data filtering and validation, automated
+ generation of code and documentation, and other tasks. Tools like
+ XSLT or XML validators can be utilized.
+
+ The mapping between YANG and YIN does not modify the information
+ content of the model. Comments and whitespace are not preserved.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 179]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+13.1. Formal YIN Definition
+
+ There is a one-to-one correspondence between YANG keywords and YIN
+ elements. The local name of a YIN element is identical to the
+ corresponding YANG keyword. This means, in particular, that the
+ document element (root) of a YIN document is always <module> or
+ <submodule>.
+
+ YIN elements corresponding to the YANG keywords belong to the
+ namespace whose associated URI is
+ "urn:ietf:params:xml:ns:yang:yin:1".
+
+ YIN elements corresponding to extension keywords belong to the
+ namespace of the YANG module where the extension keyword is declared
+ via the "extension" statement.
+
+ The names of all YIN elements MUST be properly qualified with their
+ namespaces (as specified above) using the standard mechanisms of
+ [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes.
+
+ The argument of a YANG statement is represented in YIN as either an
+ XML attribute or a subelement of the keyword element. Table 1
+ defines the mapping for the set of YANG keywords. For extensions,
+ the argument mapping is specified within the "extension" statement
+ (see Section 7.19). The following rules hold for arguments:
+
+ o If the argument is represented as an attribute, this attribute has
+ no namespace.
+
+ o If the argument is represented as an element, it is qualified by
+ the same namespace as its parent keyword element.
+
+ o If the argument is represented as an element, it MUST be the first
+ child of the keyword element.
+
+ Substatements of a YANG statement are represented as (additional)
+ children of the keyword element, and their relative order MUST be the
+ same as the order of substatements in YANG.
+
+ Comments in YANG MAY be mapped to XML comments.
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 180]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ +------------------+---------------+-------------+
+ | keyword | argument name | yin-element |
+ +------------------+---------------+-------------+
+ | action | name | false |
+ | anydata | name | false |
+ | anyxml | name | false |
+ | argument | name | false |
+ | augment | target-node | false |
+ | base | name | false |
+ | belongs-to | module | false |
+ | bit | name | false |
+ | case | name | false |
+ | choice | name | false |
+ | config | value | false |
+ | contact | text | true |
+ | container | name | false |
+ | default | value | false |
+ | description | text | true |
+ | deviate | value | false |
+ | deviation | target-node | false |
+ | enum | name | false |
+ | error-app-tag | value | false |
+ | error-message | value | true |
+ | extension | name | false |
+ | feature | name | false |
+ | fraction-digits | value | false |
+ | grouping | name | false |
+ | identity | name | false |
+ | if-feature | name | false |
+ | import | module | false |
+ | include | module | false |
+ | input | <no argument> | n/a |
+ | key | value | false |
+ | leaf | name | false |
+ | leaf-list | name | false |
+ | length | value | false |
+ | list | name | false |
+ | mandatory | value | false |
+ | max-elements | value | false |
+ | min-elements | value | false |
+ | modifier | value | false |
+ | module | name | false |
+ | must | condition | false |
+ | namespace | uri | false |
+ | notification | name | false |
+ | ordered-by | value | false |
+ | organization | text | true |
+ | output | <no argument> | n/a |
+
+
+
+Bjorklund Standards Track [Page 181]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ | path | value | false |
+ | pattern | value | false |
+ | position | value | false |
+ | prefix | value | false |
+ | presence | value | false |
+ | range | value | false |
+ | reference | text | true |
+ | refine | target-node | false |
+ | require-instance | value | false |
+ | revision | date | false |
+ | revision-date | date | false |
+ | rpc | name | false |
+ | status | value | false |
+ | submodule | name | false |
+ | type | name | false |
+ | typedef | name | false |
+ | unique | tag | false |
+ | units | name | false |
+ | uses | name | false |
+ | value | value | false |
+ | when | condition | false |
+ | yang-version | value | false |
+ | yin-element | value | false |
+ +------------------+---------------+-------------+
+
+ Table 1: Mapping of Arguments of the YANG Statements
+
+13.1.1. Usage Example
+
+ The following YANG module:
+
+ module example-foo {
+ yang-version 1.1;
+ namespace "urn:example:foo";
+ prefix "foo";
+
+ import example-extensions {
+ prefix "myext";
+ }
+
+ list interface {
+ key "name";
+ leaf name {
+ type string;
+ }
+
+
+
+
+
+
+Bjorklund Standards Track [Page 182]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ leaf mtu {
+ type uint32;
+ description "The MTU of the interface.";
+ myext:c-define "MY_MTU";
+ }
+ }
+ }
+
+ where the extension "c-define" is defined in Section 7.19.3, is
+ translated into the following YIN:
+
+ <module name="example-foo"
+ xmlns="urn:ietf:params:xml:ns:yang:yin:1"
+ xmlns:foo="urn:example:foo"
+ xmlns:myext="urn:example:extensions">
+
+ <namespace uri="urn:example:foo"/>
+ <prefix value="foo"/>
+
+ <import module="example-extensions">
+ <prefix value="myext"/>
+ </import>
+
+ <list name="interface">
+ <key value="name"/>
+ <leaf name="name">
+ <type name="string"/>
+ </leaf>
+ <leaf name="mtu">
+ <type name="uint32"/>
+ <description>
+ <text>The MTU of the interface.</text>
+ </description>
+ <myext:c-define name="MY_MTU"/>
+ </leaf>
+ </list>
+ </module>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 183]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+14. YANG ABNF Grammar
+
+ In YANG, almost all statements are unordered. The ABNF grammar
+ [RFC5234] [RFC7405] defines the canonical order. To improve module
+ readability, it is RECOMMENDED that clauses be entered in this order.
+
+ Within the ABNF grammar, unordered statements are marked with
+ comments.
+
+ This grammar assumes that the scanner replaces YANG comments with a
+ single space character.
+
+ <CODE BEGINS> file "yang.abnf"
+
+ module-stmt = optsep module-keyword sep identifier-arg-str
+ optsep
+ "{" stmtsep
+ module-header-stmts
+ linkage-stmts
+ meta-stmts
+ revision-stmts
+ body-stmts
+ "}" optsep
+
+ submodule-stmt = optsep submodule-keyword sep identifier-arg-str
+ optsep
+ "{" stmtsep
+ submodule-header-stmts
+ linkage-stmts
+ meta-stmts
+ revision-stmts
+ body-stmts
+ "}" optsep
+
+ module-header-stmts = ;; these stmts can appear in any order
+ yang-version-stmt
+ namespace-stmt
+ prefix-stmt
+
+ submodule-header-stmts =
+ ;; these stmts can appear in any order
+ yang-version-stmt
+ belongs-to-stmt
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 184]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ meta-stmts = ;; these stmts can appear in any order
+ [organization-stmt]
+ [contact-stmt]
+ [description-stmt]
+ [reference-stmt]
+
+ linkage-stmts = ;; these stmts can appear in any order
+ *import-stmt
+ *include-stmt
+
+ revision-stmts = *revision-stmt
+
+ body-stmts = *(extension-stmt /
+ feature-stmt /
+ identity-stmt /
+ typedef-stmt /
+ grouping-stmt /
+ data-def-stmt /
+ augment-stmt /
+ rpc-stmt /
+ notification-stmt /
+ deviation-stmt)
+
+ data-def-stmt = container-stmt /
+ leaf-stmt /
+ leaf-list-stmt /
+ list-stmt /
+ choice-stmt /
+ anydata-stmt /
+ anyxml-stmt /
+ uses-stmt
+
+ yang-version-stmt = yang-version-keyword sep yang-version-arg-str
+ stmtend
+
+ yang-version-arg-str = < a string that matches the rule >
+ < yang-version-arg >
+
+ yang-version-arg = "1.1"
+
+ import-stmt = import-keyword sep identifier-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ prefix-stmt
+ [revision-date-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}" stmtsep
+
+
+
+Bjorklund Standards Track [Page 185]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ include-stmt = include-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [revision-date-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ namespace-stmt = namespace-keyword sep uri-str stmtend
+
+ uri-str = < a string that matches the rule >
+ < URI in RFC 3986 >
+
+ prefix-stmt = prefix-keyword sep prefix-arg-str stmtend
+
+ belongs-to-stmt = belongs-to-keyword sep identifier-arg-str
+ optsep
+ "{" stmtsep
+ prefix-stmt
+ "}" stmtsep
+
+ organization-stmt = organization-keyword sep string stmtend
+
+ contact-stmt = contact-keyword sep string stmtend
+
+ description-stmt = description-keyword sep string stmtend
+
+ reference-stmt = reference-keyword sep string stmtend
+
+ units-stmt = units-keyword sep string stmtend
+
+ revision-stmt = revision-keyword sep revision-date optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ revision-date = date-arg-str
+
+ revision-date-stmt = revision-date-keyword sep revision-date stmtend
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 186]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ extension-stmt = extension-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [argument-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ argument-stmt = argument-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ [yin-element-stmt]
+ "}") stmtsep
+
+ yin-element-stmt = yin-element-keyword sep yin-element-arg-str
+ stmtend
+
+ yin-element-arg-str = < a string that matches the rule >
+ < yin-element-arg >
+
+ yin-element-arg = true-keyword / false-keyword
+
+ identity-stmt = identity-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ *base-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ base-stmt = base-keyword sep identifier-ref-arg-str
+ stmtend
+
+ feature-stmt = feature-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+
+
+
+Bjorklund Standards Track [Page 187]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ if-feature-stmt = if-feature-keyword sep if-feature-expr-str
+ stmtend
+
+ if-feature-expr-str = < a string that matches the rule >
+ < if-feature-expr >
+
+ if-feature-expr = if-feature-term
+ [sep or-keyword sep if-feature-expr]
+
+ if-feature-term = if-feature-factor
+ [sep and-keyword sep if-feature-term]
+
+ if-feature-factor = not-keyword sep if-feature-factor /
+ "(" optsep if-feature-expr optsep ")" /
+ identifier-ref-arg
+
+ typedef-stmt = typedef-keyword sep identifier-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ type-stmt
+ [units-stmt]
+ [default-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}" stmtsep
+
+ type-stmt = type-keyword sep identifier-ref-arg-str optsep
+ (";" /
+ "{" stmtsep
+ [type-body-stmts]
+ "}") stmtsep
+
+ type-body-stmts = numerical-restrictions /
+ decimal64-specification /
+ string-restrictions /
+ enum-specification /
+ leafref-specification /
+ identityref-specification /
+ instance-identifier-specification /
+ bits-specification /
+ union-specification /
+ binary-specification
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 188]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ numerical-restrictions = [range-stmt]
+
+ range-stmt = range-keyword sep range-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [error-message-stmt]
+ [error-app-tag-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ decimal64-specification = ;; these stmts can appear in any order
+ fraction-digits-stmt
+ [range-stmt]
+
+ fraction-digits-stmt = fraction-digits-keyword sep
+ fraction-digits-arg-str stmtend
+
+ fraction-digits-arg-str = < a string that matches the rule >
+ < fraction-digits-arg >
+
+ fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" /
+ "5" / "6" / "7" / "8"])
+ / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
+
+ string-restrictions = ;; these stmts can appear in any order
+ [length-stmt]
+ *pattern-stmt
+
+ length-stmt = length-keyword sep length-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [error-message-stmt]
+ [error-app-tag-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 189]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ pattern-stmt = pattern-keyword sep string optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [modifier-stmt]
+ [error-message-stmt]
+ [error-app-tag-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ modifier-stmt = modifier-keyword sep modifier-arg-str stmtend
+
+ modifier-arg-str = < a string that matches the rule >
+ < modifier-arg >
+
+ modifier-arg = invert-match-keyword
+
+ default-stmt = default-keyword sep string stmtend
+
+ enum-specification = 1*enum-stmt
+
+ enum-stmt = enum-keyword sep string optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ [value-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ leafref-specification =
+ ;; these stmts can appear in any order
+ path-stmt
+ [require-instance-stmt]
+
+ path-stmt = path-keyword sep path-arg-str stmtend
+
+ require-instance-stmt = require-instance-keyword sep
+ require-instance-arg-str stmtend
+
+ require-instance-arg-str = < a string that matches the rule >
+ < require-instance-arg >
+
+ require-instance-arg = true-keyword / false-keyword
+
+
+
+
+Bjorklund Standards Track [Page 190]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ instance-identifier-specification =
+ [require-instance-stmt]
+
+ identityref-specification =
+ 1*base-stmt
+
+ union-specification = 1*type-stmt
+
+ binary-specification = [length-stmt]
+
+ bits-specification = 1*bit-stmt
+
+ bit-stmt = bit-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ [position-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ position-stmt = position-keyword sep
+ position-value-arg-str stmtend
+
+ position-value-arg-str = < a string that matches the rule >
+ < position-value-arg >
+
+ position-value-arg = non-negative-integer-value
+
+ status-stmt = status-keyword sep status-arg-str stmtend
+
+ status-arg-str = < a string that matches the rule >
+ < status-arg >
+
+ status-arg = current-keyword /
+ obsolete-keyword /
+ deprecated-keyword
+
+ config-stmt = config-keyword sep
+ config-arg-str stmtend
+
+ config-arg-str = < a string that matches the rule >
+ < config-arg >
+
+ config-arg = true-keyword / false-keyword
+
+
+
+
+Bjorklund Standards Track [Page 191]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ mandatory-stmt = mandatory-keyword sep
+ mandatory-arg-str stmtend
+
+ mandatory-arg-str = < a string that matches the rule >
+ < mandatory-arg >
+
+ mandatory-arg = true-keyword / false-keyword
+
+ presence-stmt = presence-keyword sep string stmtend
+
+ ordered-by-stmt = ordered-by-keyword sep
+ ordered-by-arg-str stmtend
+
+ ordered-by-arg-str = < a string that matches the rule >
+ < ordered-by-arg >
+
+ ordered-by-arg = user-keyword / system-keyword
+
+ must-stmt = must-keyword sep string optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [error-message-stmt]
+ [error-app-tag-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ error-message-stmt = error-message-keyword sep string stmtend
+
+ error-app-tag-stmt = error-app-tag-keyword sep string stmtend
+
+ min-elements-stmt = min-elements-keyword sep
+ min-value-arg-str stmtend
+
+ min-value-arg-str = < a string that matches the rule >
+ < min-value-arg >
+
+ min-value-arg = non-negative-integer-value
+
+ max-elements-stmt = max-elements-keyword sep
+ max-value-arg-str stmtend
+
+ max-value-arg-str = < a string that matches the rule >
+ < max-value-arg >
+
+ max-value-arg = unbounded-keyword /
+ positive-integer-value
+
+
+
+Bjorklund Standards Track [Page 192]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ value-stmt = value-keyword sep integer-value-str stmtend
+
+ integer-value-str = < a string that matches the rule >
+ < integer-value >
+
+ grouping-stmt = grouping-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ *data-def-stmt
+ *action-stmt
+ *notification-stmt
+ "}") stmtsep
+
+ container-stmt = container-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ *must-stmt
+ [presence-stmt]
+ [config-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ *data-def-stmt
+ *action-stmt
+ *notification-stmt
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 193]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ leaf-stmt = leaf-keyword sep identifier-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ type-stmt
+ [units-stmt]
+ *must-stmt
+ [default-stmt]
+ [config-stmt]
+ [mandatory-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}" stmtsep
+
+ leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ type-stmt stmtsep
+ [units-stmt]
+ *must-stmt
+ *default-stmt
+ [config-stmt]
+ [min-elements-stmt]
+ [max-elements-stmt]
+ [ordered-by-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}" stmtsep
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 194]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ list-stmt = list-keyword sep identifier-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ *must-stmt
+ [key-stmt]
+ *unique-stmt
+ [config-stmt]
+ [min-elements-stmt]
+ [max-elements-stmt]
+ [ordered-by-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ 1*data-def-stmt
+ *action-stmt
+ *notification-stmt
+ "}" stmtsep
+
+ key-stmt = key-keyword sep key-arg-str stmtend
+
+ key-arg-str = < a string that matches the rule >
+ < key-arg >
+
+ key-arg = node-identifier *(sep node-identifier)
+
+ unique-stmt = unique-keyword sep unique-arg-str stmtend
+
+ unique-arg-str = < a string that matches the rule >
+ < unique-arg >
+
+ unique-arg = descendant-schema-nodeid
+ *(sep descendant-schema-nodeid)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 195]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ choice-stmt = choice-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ [default-stmt]
+ [config-stmt]
+ [mandatory-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(short-case-stmt / case-stmt)
+ "}") stmtsep
+
+ short-case-stmt = choice-stmt /
+ container-stmt /
+ leaf-stmt /
+ leaf-list-stmt /
+ list-stmt /
+ anydata-stmt /
+ anyxml-stmt
+
+ case-stmt = case-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *data-def-stmt
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 196]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ anydata-stmt = anydata-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ *must-stmt
+ [config-stmt]
+ [mandatory-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ *must-stmt
+ [config-stmt]
+ [mandatory-stmt]
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ uses-stmt = uses-keyword sep identifier-ref-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *refine-stmt
+ *uses-augment-stmt
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 197]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ refine-stmt = refine-keyword sep refine-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ *must-stmt
+ [presence-stmt]
+ *default-stmt
+ [config-stmt]
+ [mandatory-stmt]
+ [min-elements-stmt]
+ [max-elements-stmt]
+ [description-stmt]
+ [reference-stmt]
+ "}" stmtsep
+
+ refine-arg-str = < a string that matches the rule >
+ < refine-arg >
+
+ refine-arg = descendant-schema-nodeid
+
+ uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ 1*(data-def-stmt / case-stmt /
+ action-stmt / notification-stmt)
+ "}" stmtsep
+
+ uses-augment-arg-str = < a string that matches the rule >
+ < uses-augment-arg >
+
+ uses-augment-arg = descendant-schema-nodeid
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 198]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ augment-stmt = augment-keyword sep augment-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [when-stmt]
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ 1*(data-def-stmt / case-stmt /
+ action-stmt / notification-stmt)
+ "}" stmtsep
+
+ augment-arg-str = < a string that matches the rule >
+ < augment-arg >
+
+ augment-arg = absolute-schema-nodeid
+
+ when-stmt = when-keyword sep string optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [description-stmt]
+ [reference-stmt]
+ "}") stmtsep
+
+ rpc-stmt = rpc-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ [input-stmt]
+ [output-stmt]
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 199]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ action-stmt = action-keyword sep identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ [input-stmt]
+ [output-stmt]
+ "}") stmtsep
+
+ input-stmt = input-keyword optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *must-stmt
+ *(typedef-stmt / grouping-stmt)
+ 1*data-def-stmt
+ "}" stmtsep
+
+ output-stmt = output-keyword optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *must-stmt
+ *(typedef-stmt / grouping-stmt)
+ 1*data-def-stmt
+ "}" stmtsep
+
+ notification-stmt = notification-keyword sep
+ identifier-arg-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ *if-feature-stmt
+ *must-stmt
+ [status-stmt]
+ [description-stmt]
+ [reference-stmt]
+ *(typedef-stmt / grouping-stmt)
+ *data-def-stmt
+ "}") stmtsep
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 200]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ deviation-stmt = deviation-keyword sep
+ deviation-arg-str optsep
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [description-stmt]
+ [reference-stmt]
+ (deviate-not-supported-stmt /
+ 1*(deviate-add-stmt /
+ deviate-replace-stmt /
+ deviate-delete-stmt))
+ "}" stmtsep
+
+ deviation-arg-str = < a string that matches the rule >
+ < deviation-arg >
+
+ deviation-arg = absolute-schema-nodeid
+
+ deviate-not-supported-stmt =
+ deviate-keyword sep
+ not-supported-keyword-str stmtend
+
+ deviate-add-stmt = deviate-keyword sep add-keyword-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [units-stmt]
+ *must-stmt
+ *unique-stmt
+ *default-stmt
+ [config-stmt]
+ [mandatory-stmt]
+ [min-elements-stmt]
+ [max-elements-stmt]
+ "}") stmtsep
+
+ deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [units-stmt]
+ *must-stmt
+ *unique-stmt
+ *default-stmt
+ "}") stmtsep
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 201]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep
+ (";" /
+ "{" stmtsep
+ ;; these stmts can appear in any order
+ [type-stmt]
+ [units-stmt]
+ [default-stmt]
+ [config-stmt]
+ [mandatory-stmt]
+ [min-elements-stmt]
+ [max-elements-stmt]
+ "}") stmtsep
+
+ not-supported-keyword-str = < a string that matches the rule >
+ < not-supported-keyword >
+
+ add-keyword-str = < a string that matches the rule >
+ < add-keyword >
+
+ delete-keyword-str = < a string that matches the rule >
+ < delete-keyword >
+
+ replace-keyword-str = < a string that matches the rule >
+ < replace-keyword >
+
+ ;; represents the usage of an extension
+ unknown-statement = prefix ":" identifier [sep string] optsep
+ (";" /
+ "{" optsep
+ *((yang-stmt / unknown-statement) optsep)
+ "}") stmtsep
+
+ yang-stmt = action-stmt /
+ anydata-stmt /
+ anyxml-stmt /
+ argument-stmt /
+ augment-stmt /
+ base-stmt /
+ belongs-to-stmt /
+ bit-stmt /
+ case-stmt /
+ choice-stmt /
+ config-stmt /
+ contact-stmt /
+ container-stmt /
+ default-stmt /
+ description-stmt /
+ deviate-add-stmt /
+
+
+
+Bjorklund Standards Track [Page 202]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ deviate-delete-stmt /
+ deviate-not-supported-stmt /
+ deviate-replace-stmt /
+ deviation-stmt /
+ enum-stmt /
+ error-app-tag-stmt /
+ error-message-stmt /
+ extension-stmt /
+ feature-stmt /
+ fraction-digits-stmt /
+ grouping-stmt /
+ identity-stmt /
+ if-feature-stmt /
+ import-stmt /
+ include-stmt /
+ input-stmt /
+ key-stmt /
+ leaf-list-stmt /
+ leaf-stmt /
+ length-stmt /
+ list-stmt /
+ mandatory-stmt /
+ max-elements-stmt /
+ min-elements-stmt /
+ modifier-stmt /
+ module-stmt /
+ must-stmt /
+ namespace-stmt /
+ notification-stmt /
+ ordered-by-stmt /
+ organization-stmt /
+ output-stmt /
+ path-stmt /
+ pattern-stmt /
+ position-stmt /
+ prefix-stmt /
+ presence-stmt /
+ range-stmt /
+ reference-stmt /
+ refine-stmt /
+ require-instance-stmt /
+ revision-date-stmt /
+ revision-stmt /
+ rpc-stmt /
+ status-stmt /
+ submodule-stmt /
+ typedef-stmt /
+ type-stmt /
+
+
+
+Bjorklund Standards Track [Page 203]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ unique-stmt /
+ units-stmt /
+ uses-augment-stmt /
+ uses-stmt /
+ value-stmt /
+ when-stmt /
+ yang-version-stmt /
+ yin-element-stmt
+
+ ;; Ranges
+
+ range-arg-str = < a string that matches the rule >
+ < range-arg >
+
+ range-arg = range-part *(optsep "|" optsep range-part)
+
+ range-part = range-boundary
+ [optsep ".." optsep range-boundary]
+
+ range-boundary = min-keyword / max-keyword /
+ integer-value / decimal-value
+
+ ;; Lengths
+
+ length-arg-str = < a string that matches the rule >
+ < length-arg >
+
+ length-arg = length-part *(optsep "|" optsep length-part)
+
+ length-part = length-boundary
+ [optsep ".." optsep length-boundary]
+
+ length-boundary = min-keyword / max-keyword /
+ non-negative-integer-value
+
+ ;; Date
+
+ date-arg-str = < a string that matches the rule >
+ < date-arg >
+
+ date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT
+
+ ;; Schema Node Identifiers
+
+ schema-nodeid = absolute-schema-nodeid /
+ descendant-schema-nodeid
+
+ absolute-schema-nodeid = 1*("/" node-identifier)
+
+
+
+Bjorklund Standards Track [Page 204]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ descendant-schema-nodeid =
+ node-identifier
+ [absolute-schema-nodeid]
+
+ node-identifier = [prefix ":"] identifier
+
+ ;; Instance Identifiers
+
+ instance-identifier = 1*("/" (node-identifier
+ [1*key-predicate /
+ leaf-list-predicate /
+ pos]))
+
+ key-predicate = "[" *WSP key-predicate-expr *WSP "]"
+
+ key-predicate-expr = node-identifier *WSP "=" *WSP quoted-string
+
+ leaf-list-predicate = "[" *WSP leaf-list-predicate-expr *WSP "]"
+
+ leaf-list-predicate-expr = "." *WSP "=" *WSP quoted-string
+
+ pos = "[" *WSP positive-integer-value *WSP "]"
+
+ quoted-string = (DQUOTE string DQUOTE) / (SQUOTE string SQUOTE)
+
+ ;; leafref path
+
+ path-arg-str = < a string that matches the rule >
+ < path-arg >
+
+ path-arg = absolute-path / relative-path
+
+ absolute-path = 1*("/" (node-identifier *path-predicate))
+
+ relative-path = 1*("../") descendant-path
+
+ descendant-path = node-identifier
+ [*path-predicate absolute-path]
+
+ path-predicate = "[" *WSP path-equality-expr *WSP "]"
+
+ path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr
+
+ path-key-expr = current-function-invocation *WSP "/" *WSP
+ rel-path-keyexpr
+
+
+
+
+
+
+Bjorklund Standards Track [Page 205]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ rel-path-keyexpr = 1*(".." *WSP "/" *WSP)
+ *(node-identifier *WSP "/" *WSP)
+ node-identifier
+
+ ;;; Keywords, using the syntax for case-sensitive strings (RFC 7405)
+
+ ;; statement keywords
+ action-keyword = %s"action"
+ anydata-keyword = %s"anydata"
+ anyxml-keyword = %s"anyxml"
+ argument-keyword = %s"argument"
+ augment-keyword = %s"augment"
+ base-keyword = %s"base"
+ belongs-to-keyword = %s"belongs-to"
+ bit-keyword = %s"bit"
+ case-keyword = %s"case"
+ choice-keyword = %s"choice"
+ config-keyword = %s"config"
+ contact-keyword = %s"contact"
+ container-keyword = %s"container"
+ default-keyword = %s"default"
+ description-keyword = %s"description"
+ deviate-keyword = %s"deviate"
+ deviation-keyword = %s"deviation"
+ enum-keyword = %s"enum"
+ error-app-tag-keyword = %s"error-app-tag"
+ error-message-keyword = %s"error-message"
+ extension-keyword = %s"extension"
+ feature-keyword = %s"feature"
+ fraction-digits-keyword = %s"fraction-digits"
+ grouping-keyword = %s"grouping"
+ identity-keyword = %s"identity"
+ if-feature-keyword = %s"if-feature"
+ import-keyword = %s"import"
+ include-keyword = %s"include"
+ input-keyword = %s"input"
+ key-keyword = %s"key"
+ leaf-keyword = %s"leaf"
+ leaf-list-keyword = %s"leaf-list"
+ length-keyword = %s"length"
+ list-keyword = %s"list"
+ mandatory-keyword = %s"mandatory"
+ max-elements-keyword = %s"max-elements"
+ min-elements-keyword = %s"min-elements"
+ modifier-keyword = %s"modifier"
+ module-keyword = %s"module"
+ must-keyword = %s"must"
+ namespace-keyword = %s"namespace"
+
+
+
+Bjorklund Standards Track [Page 206]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ notification-keyword = %s"notification"
+ ordered-by-keyword = %s"ordered-by"
+ organization-keyword = %s"organization"
+ output-keyword = %s"output"
+ path-keyword = %s"path"
+ pattern-keyword = %s"pattern"
+ position-keyword = %s"position"
+ prefix-keyword = %s"prefix"
+ presence-keyword = %s"presence"
+ range-keyword = %s"range"
+ reference-keyword = %s"reference"
+ refine-keyword = %s"refine"
+ require-instance-keyword = %s"require-instance"
+ revision-keyword = %s"revision"
+ revision-date-keyword = %s"revision-date"
+ rpc-keyword = %s"rpc"
+ status-keyword = %s"status"
+ submodule-keyword = %s"submodule"
+ type-keyword = %s"type"
+ typedef-keyword = %s"typedef"
+ unique-keyword = %s"unique"
+ units-keyword = %s"units"
+ uses-keyword = %s"uses"
+ value-keyword = %s"value"
+ when-keyword = %s"when"
+ yang-version-keyword = %s"yang-version"
+ yin-element-keyword = %s"yin-element"
+
+ ;; other keywords
+
+ add-keyword = %s"add"
+ current-keyword = %s"current"
+ delete-keyword = %s"delete"
+ deprecated-keyword = %s"deprecated"
+ false-keyword = %s"false"
+ invert-match-keyword = %s"invert-match"
+ max-keyword = %s"max"
+ min-keyword = %s"min"
+ not-supported-keyword = %s"not-supported"
+ obsolete-keyword = %s"obsolete"
+ replace-keyword = %s"replace"
+ system-keyword = %s"system"
+ true-keyword = %s"true"
+ unbounded-keyword = %s"unbounded"
+ user-keyword = %s"user"
+
+
+
+
+
+
+Bjorklund Standards Track [Page 207]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ and-keyword = %s"and"
+ or-keyword = %s"or"
+ not-keyword = %s"not"
+
+ current-function-invocation = current-keyword *WSP "(" *WSP ")"
+
+ ;;; Basic Rules
+
+ prefix-arg-str = < a string that matches the rule >
+ < prefix-arg >
+
+ prefix-arg = prefix
+
+ prefix = identifier
+
+ identifier-arg-str = < a string that matches the rule >
+ < identifier-arg >
+
+ identifier-arg = identifier
+
+ identifier = (ALPHA / "_")
+ *(ALPHA / DIGIT / "_" / "-" / ".")
+
+ identifier-ref-arg-str = < a string that matches the rule >
+ < identifier-ref-arg >
+
+ identifier-ref-arg = identifier-ref
+
+ identifier-ref = [prefix ":"] identifier
+
+ string = < an unquoted string, as returned by >
+ < the scanner, that matches the rule >
+ < yang-string >
+
+ yang-string = *yang-char
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 208]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ ;; any Unicode or ISO/IEC 10646 character, including tab, carriage
+ ;; return, and line feed but excluding the other C0 control
+ ;; characters, the surrogate blocks, and the noncharacters
+ yang-char = %x09 / %x0A / %x0D / %x20-D7FF /
+ ; exclude surrogate blocks %xD800-DFFF
+ %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF
+ %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF
+ %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF
+ %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF
+ %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF
+ %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF
+ %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF
+ %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF
+ %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF
+ %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF
+ %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF
+ %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF
+ %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF
+ %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF
+ %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF
+ %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF
+ %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF
+ %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF
+
+ integer-value = ("-" non-negative-integer-value) /
+ non-negative-integer-value
+
+ non-negative-integer-value = "0" / positive-integer-value
+
+ positive-integer-value = (non-zero-digit *DIGIT)
+
+ zero-integer-value = 1*DIGIT
+
+ stmtend = optsep (";" / "{" stmtsep "}") stmtsep
+
+ sep = 1*(WSP / line-break)
+ ; unconditional separator
+
+ optsep = *(WSP / line-break)
+
+ stmtsep = *(WSP / line-break / unknown-statement)
+
+ line-break = CRLF / LF
+
+ non-zero-digit = %x31-39
+
+ decimal-value = integer-value ("." zero-integer-value)
+
+
+
+
+Bjorklund Standards Track [Page 209]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ SQUOTE = %x27
+ ; single quote
+
+ ;;; core rules from RFC 5234
+
+ ALPHA = %x41-5A / %x61-7A
+ ; A-Z / a-z
+
+ CR = %x0D
+ ; carriage return
+
+ CRLF = CR LF
+ ; Internet standard newline
+
+ DIGIT = %x30-39
+ ; 0-9
+
+ DQUOTE = %x22
+ ; double quote
+
+ HTAB = %x09
+ ; horizontal tab
+
+ LF = %x0A
+ ; line feed
+
+ SP = %x20
+ ; space
+
+ WSP = SP / HTAB
+ ; whitespace
+
+ <CODE ENDS>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 210]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+15. NETCONF Error Responses for YANG-Related Errors
+
+ A number of NETCONF error responses are defined for error cases
+ related to the data model handling. If the relevant YANG statement
+ has an "error-app-tag" substatement, that overrides the default value
+ specified below.
+
+15.1. Error Message for Data That Violates a "unique" Statement
+
+ If a NETCONF operation would result in configuration data where a
+ "unique" constraint is invalidated, the following error MUST be
+ returned:
+
+ error-tag: operation-failed
+ error-app-tag: data-not-unique
+ error-info: <non-unique>: Contains an instance identifier that
+ points to a leaf that invalidates the "unique"
+ constraint. This element is present once for each
+ non-unique leaf.
+
+ The <non-unique> element is in the YANG
+ namespace ("urn:ietf:params:xml:ns:yang:1").
+
+15.2. Error Message for Data That Violates a "max-elements" Statement
+
+ If a NETCONF operation would result in configuration data where a
+ list or a leaf-list would have too many entries, the following error
+ MUST be returned:
+
+ error-tag: operation-failed
+ error-app-tag: too-many-elements
+
+ This error is returned once, with the error-path identifying the list
+ node, even if there is more than one extra child present.
+
+15.3. Error Message for Data That Violates a "min-elements" Statement
+
+ If a NETCONF operation would result in configuration data where a
+ list or a leaf-list would have too few entries, the following error
+ MUST be returned:
+
+ error-tag: operation-failed
+ error-app-tag: too-few-elements
+
+ This error is returned once, with the error-path identifying the list
+ node, even if there is more than one child missing.
+
+
+
+
+
+Bjorklund Standards Track [Page 211]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+15.4. Error Message for Data That Violates a "must" Statement
+
+ If a NETCONF operation would result in configuration data where the
+ restrictions imposed by a "must" statement are violated, the
+ following error MUST be returned, unless a specific "error-app-tag"
+ substatement is present for the "must" statement.
+
+ error-tag: operation-failed
+ error-app-tag: must-violation
+
+15.5. Error Message for Data That Violates a "require-instance"
+ Statement
+
+ If a NETCONF operation would result in configuration data where a
+ leaf of type "instance-identifier" or "leafref" marked with
+ require-instance "true" refers to an instance that does not exist,
+ the following error MUST be returned:
+
+ error-tag: data-missing
+ error-app-tag: instance-required
+ error-path: Path to the instance-identifier or leafref leaf.
+
+15.6. Error Message for Data That Violates a Mandatory "choice"
+ Statement
+
+ If a NETCONF operation would result in configuration data where no
+ nodes exists in a mandatory choice, the following error MUST be
+ returned:
+
+ error-tag: data-missing
+ error-app-tag: missing-choice
+ error-path: Path to the element with the missing choice.
+ error-info: <missing-choice>: Contains the name of the missing
+ mandatory choice.
+
+ The <missing-choice> element is in the YANG
+ namespace ("urn:ietf:params:xml:ns:yang:1").
+
+15.7. Error Message for the "insert" Operation
+
+ If the "insert" and "key" or "value" attributes are used in an
+ <edit-config> for a list or leaf-list node and the "key" or "value"
+ refers to an instance that does not exist, the following error MUST
+ be returned:
+
+ error-tag: bad-attribute
+ error-app-tag: missing-instance
+
+
+
+
+Bjorklund Standards Track [Page 212]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+16. IANA Considerations
+
+ This document registers one capability identifier URN from the
+ "Network Configuration Protocol (NETCONF) Capability URNs" registry:
+
+ Index Capability Identifier
+ ------------- ---------------------------------------------------
+ :yang-library urn:ietf:params:netconf:capability:yang-library:1.0
+
+17. Security Considerations
+
+ This document defines a language with which to write and read
+ descriptions of management information. The language itself has no
+ security impact on the Internet.
+
+ The same considerations are relevant as those for the base NETCONF
+ protocol (see Section 9 in [RFC6241]).
+
+ Data modeled in YANG might contain sensitive information. RPCs or
+ notifications defined in YANG might transfer sensitive information.
+
+ Security issues are related to the usage of data modeled in YANG.
+ Such issues shall be dealt with in documents describing the data
+ models and documents about the interfaces used to manipulate the
+ data, e.g., the NETCONF documents.
+
+ Data modeled in YANG is dependent upon:
+
+ o the security of the transmission infrastructure used to send
+ sensitive information.
+
+ o the security of applications that store or release such sensitive
+ information.
+
+ o adequate authentication and access control mechanisms to restrict
+ the usage of sensitive data.
+
+ YANG parsers need to be robust with respect to malformed documents.
+ Reading malformed documents from unknown or untrusted sources could
+ result in an attacker gaining the privileges of the user running the
+ YANG parser. In an extreme situation, the entire machine could be
+ compromised.
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 213]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+18. References
+
+18.1. Normative References
+
+ [ISO.10646]
+ International Organization for Standardization,
+ "Information Technology - Universal Multiple-Octet Coded
+ Character Set (UCS)", ISO Standard 10646:2014, 2014.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of
+ ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629,
+ November 2003, <http://www.rfc-editor.org/info/rfc3629>.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, DOI 10.17487/RFC3986, January 2005,
+ <http://www.rfc-editor.org/info/rfc3986>.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+ <http://www.rfc-editor.org/info/rfc4648>.
+
+ [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
+ Syntax Specifications: ABNF", STD 68, RFC 5234,
+ DOI 10.17487/RFC5234, January 2008,
+ <http://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
+ Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
+ <http://www.rfc-editor.org/info/rfc5277>.
+
+ [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
+ and A. Bierman, Ed., "Network Configuration Protocol
+ (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
+ <http://www.rfc-editor.org/info/rfc6241>.
+
+ [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
+ RFC 7405, DOI 10.17487/RFC7405, December 2014,
+ <http://www.rfc-editor.org/info/rfc7405>.
+
+ [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
+ Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
+ <http://www.rfc-editor.org/info/rfc7895>.
+
+
+
+Bjorklund Standards Track [Page 214]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
+ F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
+ Edition)", W3C Recommendation REC-xml-20081126,
+ November 2008,
+ <https://www.w3.org/TR/2008/REC-xml-20081126/>.
+
+ [XML-NAMES]
+ Bray, T., Hollander, D., Layman, A., Tobin, R., and H.
+ Thompson, "Namespaces in XML 1.0 (Third Edition)", World
+ Wide Web Consortium Recommendation REC-xml-names-20091208,
+ December 2009,
+ <http://www.w3.org/TR/2009/REC-xml-names-20091208>.
+
+ [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
+ Version 1.0", World Wide Web Consortium Recommendation
+ REC-xpath-19991116, November 1999,
+ <http://www.w3.org/TR/1999/REC-xpath-19991116>.
+
+ [XSD-TYPES]
+ Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
+ Second Edition", World Wide Web Consortium Recommendation
+ REC-xmlschema-2-20041028, October 2004,
+ <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
+
+18.2. Informative References
+
+ [CoMI] van der Stok, P. and A. Bierman, "CoAP Management
+ Interface", Work in Progress,
+ draft-vanderstok-core-comi-09, March 2016.
+
+ [IEEE754-2008]
+ IEEE, "IEEE Standard for Floating-Point Arithmetic",
+ IEEE 754-2008, DOI 10.1109/IEEESTD.2008.4610935, 2008,
+ <http://standards.ieee.org/findstds/
+ standard/754-2008.html>.
+
+ [RESTCONF]
+ Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
+ Protocol", Work in Progress,
+ draft-ietf-netconf-restconf-16, August 2016.
+
+ [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J.
+ Schoenwaelder, Ed., "Structure of Management Information
+ Version 2 (SMIv2)", STD 58, RFC 2578,
+ DOI 10.17487/RFC2578, April 1999,
+ <http://www.rfc-editor.org/info/rfc2578>.
+
+
+
+
+
+Bjorklund Standards Track [Page 215]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+ [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J.
+ Schoenwaelder, Ed., "Textual Conventions for SMIv2",
+ STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999,
+ <http://www.rfc-editor.org/info/rfc2579>.
+
+ [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation
+ Structure of Management Information", RFC 3780,
+ DOI 10.17487/RFC3780, May 2004,
+ <http://www.rfc-editor.org/info/rfc3780>.
+
+ [RFC4844] Daigle, L., Ed., and Internet Architecture Board, "The RFC
+ Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844,
+ July 2007, <http://www.rfc-editor.org/info/rfc4844>.
+
+ [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
+ the Network Configuration Protocol (NETCONF)", RFC 6020,
+ DOI 10.17487/RFC6020, October 2010,
+ <http://www.rfc-editor.org/info/rfc6020>.
+
+ [RFC6643] Schoenwaelder, J., "Translation of Structure of Management
+ Information Version 2 (SMIv2) MIB Modules to YANG
+ Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012,
+ <http://www.rfc-editor.org/info/rfc6643>.
+
+ [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
+ RFC 6991, DOI 10.17487/RFC6991, July 2013,
+ <http://www.rfc-editor.org/info/rfc6991>.
+
+ [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
+ RFC 7951, DOI 10.17487/RFC7951, August 2016,
+ <http://www.rfc-editor.org/info/rfc7951>.
+
+ [XPATH2.0]
+ Berglund, A., Boag, S., Chamberlin, D., Fernandez, M.,
+ Kay, M., Robie, J., and J. Simeon, "XML Path Language
+ (XPath) 2.0 (Second Edition)", World Wide Web Consortium
+ Recommendation REC-xpath20-20101214, December 2010,
+ <http://www.w3.org/TR/2010/REC-xpath20-20101214>.
+
+ [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World
+ Wide Web Consortium Recommendation REC-xslt-19991116,
+ November 1999,
+ <http://www.w3.org/TR/1999/REC-xslt-19991116>.
+
+ [YANG-Guidelines]
+ Bierman, A., "Guidelines for Authors and Reviewers of YANG
+ Data Model Documents", Work in Progress,
+ draft-ietf-netmod-rfc6087bis-07, July 2016.
+
+
+
+Bjorklund Standards Track [Page 216]
+
+RFC 7950 YANG 1.1 August 2016
+
+
+Acknowledgements
+
+ The editor wishes to thank the following individuals, who all
+ provided helpful comments on various draft versions of this document:
+ Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson,
+ Ladislav Lhotka, Lionel Morand, Gerhard Muenz, Peyman Owladi, Tom
+ Petch, Randy Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert
+ Wijnen, Robert Wilton, and Dale Worley.
+
+Contributors
+
+ The following people all contributed significantly to the initial
+ YANG document:
+
+ - Andy Bierman (YumaWorks)
+ - Balazs Lengyel (Ericsson)
+ - David Partain (Ericsson)
+ - Juergen Schoenwaelder (Jacobs University Bremen)
+ - Phil Shafer (Juniper Networks)
+
+Author's Address
+
+ Martin Bjorklund (editor)
+ Tail-f Systems
+
+ Email: mbj@tail-f.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund Standards Track [Page 217]
+