idnits 2.17.1 draft-ietf-netmod-rfc6020bis-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 9169 has weird spacing: '...library urn:...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 10, 2016) is 2875 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 7295 == Unused Reference: 'RFC6691' is defined on line 9470, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-13 == Outdated reference: A later version (-20) exists of draft-ietf-netmod-rfc6087bis-06 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-09 -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) -- Obsolete informational reference (is this intentional?): RFC 6691 (Obsoleted by RFC 9293) Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track June 10, 2016 5 Expires: December 12, 2016 7 The YANG 1.1 Data Modeling Language 8 draft-ietf-netmod-rfc6020bis-13 10 Abstract 12 YANG is a data modeling language used to model configuration data, 13 state data, remote procedure calls, and notifications for network 14 management protocols. This document describes the syntax and 15 semantics of version 1.1 of the YANG language. YANG version 1.1 is a 16 maintenance release of the YANG language, addressing ambiguities and 17 defects in the original specification. There are a small number of 18 backward incompatibilities from YANG version 1. This document also 19 specifies the YANG mappings to the Network Configuration Protocol 20 (NETCONF). 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 12, 2016. 39 Copyright Notice 41 Copyright (c) 2016 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 69 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 9 70 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 3.1. A Note on Examples . . . . . . . . . . . . . . . . . . . 14 73 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 74 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 15 75 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 16 76 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 16 77 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 17 78 4.2.3. Configuration and State Data . . . . . . . . . . . . 21 79 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 21 80 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 22 81 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 23 82 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 24 83 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 25 84 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 26 85 4.2.10. Notification Definitions . . . . . . . . . . . . . . 29 86 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 29 87 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 29 88 5.1.1. Import and Include by Revision . . . . . . . . . . . 31 89 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 32 90 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 33 91 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 34 92 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 34 93 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 34 94 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 34 95 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 35 96 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 36 97 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 36 98 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 36 99 5.6.4. Announcing Conformance Information in NETCONF . . . . 37 100 5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 38 101 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 41 102 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 41 103 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 42 104 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 42 105 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 42 106 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 42 107 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 44 108 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 44 109 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 45 110 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 46 111 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 46 112 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 47 113 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 51 114 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 52 115 7.1. The module Statement . . . . . . . . . . . . . . . . . . 52 116 7.1.1. The module's Substatements . . . . . . . . . . . . . 53 117 7.1.2. The yang-version Statement . . . . . . . . . . . . . 54 118 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 55 119 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 55 120 7.1.5. The import Statement . . . . . . . . . . . . . . . . 56 121 7.1.6. The include Statement . . . . . . . . . . . . . . . . 57 122 7.1.7. The organization Statement . . . . . . . . . . . . . 57 123 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 58 124 7.1.9. The revision Statement . . . . . . . . . . . . . . . 58 125 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 58 126 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 59 127 7.2.1. The submodule's Substatements . . . . . . . . . . . . 60 128 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 61 129 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 62 130 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 62 131 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 63 132 7.3.2. The typedef's type Statement . . . . . . . . . . . . 63 133 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 63 134 7.3.4. The typedef's default Statement . . . . . . . . . . . 63 135 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 64 136 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 64 137 7.4.1. The type's Substatements . . . . . . . . . . . . . . 64 138 7.5. The container Statement . . . . . . . . . . . . . . . . . 64 139 7.5.1. Containers with Presence . . . . . . . . . . . . . . 65 140 7.5.2. The container's Substatements . . . . . . . . . . . . 65 141 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 66 142 7.5.4. The must's Substatements . . . . . . . . . . . . . . 67 143 7.5.5. The presence Statement . . . . . . . . . . . . . . . 68 144 7.5.6. The container's Child Node Statements . . . . . . . . 68 145 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 68 146 7.5.8. NETCONF Operations . . . . . . . . . . 69 147 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 69 148 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 71 149 7.6.1. The leaf's default value . . . . . . . . . . . . . . 71 150 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 72 151 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 72 152 7.6.4. The leaf's default Statement . . . . . . . . . . . . 72 153 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 73 154 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 73 155 7.6.7. NETCONF Operations . . . . . . . . . . 73 156 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 74 157 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 74 158 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 75 159 7.7.2. The leaf-list's default values . . . . . . . . . . . 75 160 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 76 161 7.7.4. The leaf-list's default Statement . . . . . . . . . . 77 162 7.7.5. The min-elements Statement . . . . . . . . . . . . . 77 163 7.7.6. The max-elements Statement . . . . . . . . . . . . . 78 164 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 78 165 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 79 166 7.7.9. NETCONF Operations . . . . . . . . . . 79 167 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 80 168 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 81 169 7.8.1. The list's Substatements . . . . . . . . . . . . . . 82 170 7.8.2. The list's key Statement . . . . . . . . . . . . . . 82 171 7.8.3. The list's unique Statement . . . . . . . . . . . . . 83 172 7.8.4. The list's Child Node Statements . . . . . . . . . . 84 173 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 84 174 7.8.6. NETCONF Operations . . . . . . . . . . 85 175 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 176 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 89 177 7.9.1. The choice's Substatements . . . . . . . . . . . . . 89 178 7.9.2. The choice's case Statement . . . . . . . . . . . . . 90 179 7.9.3. The choice's default Statement . . . . . . . . . . . 91 180 7.9.4. The choice's mandatory Statement . . . . . . . . . . 93 181 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 93 182 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 93 183 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 94 184 7.10.1. The anydata's Substatements . . . . . . . . . . . . 95 185 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 95 186 7.10.3. NETCONF Operations . . . . . . . . . . 95 187 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 96 188 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 97 189 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 97 190 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 97 191 7.11.3. NETCONF Operations . . . . . . . . . . 98 192 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 98 194 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 99 195 7.12.1. The grouping's Substatements . . . . . . . . . . . . 99 196 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 100 197 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 100 198 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 101 199 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 101 200 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 201 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 102 202 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 103 203 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 103 204 7.14.2. The input Statement . . . . . . . . . . . . . . . . 104 205 7.14.3. The output Statement . . . . . . . . . . . . . . . . 105 206 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 106 207 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 106 208 7.15. The action Statement . . . . . . . . . . . . . . . . . . 107 209 7.15.1. The action's Substatements . . . . . . . . . . . . . 108 210 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 211 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 212 7.16. The notification Statement . . . . . . . . . . . . . . . 110 213 7.16.1. The notification's Substatements . . . . . . . . . . 111 214 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 111 215 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 216 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 113 217 7.17.1. The augment's Substatements . . . . . . . . . . . . 115 218 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 116 219 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 220 7.18. The identity Statement . . . . . . . . . . . . . . . . . 118 221 7.18.1. The identity's Substatements . . . . . . . . . . . . 118 222 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 118 223 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 224 7.19. The extension Statement . . . . . . . . . . . . . . . . . 121 225 7.19.1. The extension's Substatements . . . . . . . . . . . 121 226 7.19.2. The argument Statement . . . . . . . . . . . . . . . 121 227 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 122 228 7.20. Conformance-Related Statements . . . . . . . . . . . . . 123 229 7.20.1. The feature Statement . . . . . . . . . . . . . . . 123 230 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 125 231 7.20.3. The deviation Statement . . . . . . . . . . . . . . 125 232 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 129 233 7.21.1. The config Statement . . . . . . . . . . . . . . . . 129 234 7.21.2. The status Statement . . . . . . . . . . . . . . . . 129 235 7.21.3. The description Statement . . . . . . . . . . . . . 130 236 7.21.4. The reference Statement . . . . . . . . . . . . . . 130 237 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 131 238 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 132 239 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 132 240 8.2. Configuration Data Modifications . . . . . . . . . . . . 133 241 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 133 242 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 133 243 8.3.2. NETCONF Processing . . . . . . . . . . 134 244 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 135 245 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 135 246 9.1. Canonical Representation . . . . . . . . . . . . . . . . 135 247 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 136 248 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 136 249 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 137 250 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 137 251 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 137 252 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 253 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 138 254 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 139 255 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 139 256 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 139 257 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 139 258 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 140 259 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 140 260 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 140 261 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 262 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 263 9.4.4. The length Statement . . . . . . . . . . . . . . . . 141 264 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 142 265 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 142 266 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 142 267 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 144 268 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 144 269 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 270 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 271 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 144 272 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 144 273 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 274 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 275 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 144 276 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 277 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 147 278 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 279 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 147 280 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 281 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 148 282 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 149 283 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 150 284 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 285 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 150 286 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 150 287 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 150 288 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 289 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 151 290 9.9.3. The require-instance Statement . . . . . . . . . . . 152 291 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 152 292 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 152 293 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 152 294 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 156 295 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 296 9.10.2. The identityref's base Statement . . . . . . . . . . 156 297 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 156 298 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 157 299 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 157 300 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 158 301 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 302 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 158 303 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 304 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 305 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 159 306 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 159 307 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 159 308 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 159 309 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 310 9.13. The instance-identifier Built-In Type . . . . . . . . . . 160 311 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 161 312 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 161 313 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 161 314 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 162 315 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 162 316 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 162 317 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 162 318 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 163 319 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 163 320 10.3. Functions for the YANG Types "leafref" and "instance- 321 identifier" . . . . . . . . . . . . . . . . . . . . . . 164 322 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 164 323 10.4. Functions for the YANG Type "identityref" . . . . . . . 165 324 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 165 325 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 166 326 10.5. Functions for the YANG Type "enumeration" . . . . . . . 167 327 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 167 328 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 168 329 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 168 330 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 169 331 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 171 332 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 333 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 172 334 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 175 335 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 176 336 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 200 337 15.1. Error Message for Data That Violates a unique Statement 201 338 15.2. Error Message for Data That Violates a max-elements 339 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 340 15.3. Error Message for Data That Violates a min-elements 341 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 342 15.4. Error Message for Data That Violates a must Statement . 201 343 15.5. Error Message for Data That Violates a require-instance 344 Statement . . . . . . . . . . . . . . . . . . . . . . . 202 345 15.6. Error Message for Data That Violates a mandatory choice 346 Statement . . . . . . . . . . . . . . . . . . . . . . . 202 347 15.7. Error Message for the "insert" Operation . . . . . . . . 202 348 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 202 349 17. Security Considerations . . . . . . . . . . . . . . . . . . . 203 350 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 203 351 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 204 352 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 204 353 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 204 354 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 204 355 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 204 356 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 205 357 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 205 358 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 205 359 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 205 360 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 205 361 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 206 362 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 206 363 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 206 364 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 206 365 21.1. Normative References . . . . . . . . . . . . . . . . . . 207 366 21.2. Informative References . . . . . . . . . . . . . . . . . 208 367 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 209 369 1. Introduction 371 YANG is a data modeling language originally designed to model 372 configuration and state data manipulated by the Network Configuration 373 Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF 374 notifications [RFC6241]. Since the publication of YANG version 1 375 [RFC6020], YANG has been used or proposed to be used for other 376 protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI 377 [I-D.vanderstok-core-comi]). Further, other encodings than XML have 378 been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). 380 This document describes the syntax and semantics of version 1.1 of 381 the YANG language. It also describes how a data model defined in a 382 YANG module is encoded in the Extensible Markup Language (XML), and 383 how NETCONF operations are used to manipulate the data. Other 384 protocols and encodings are possible, but out of scope for this 385 specification. 387 In terms of developing YANG data models, [I-D.ietf-netmod-rfc6087bis] 388 provides some guidelines and recommendations. 390 Note that this document does not obsolete RFC 6020 [RFC6020]. 392 1.1. Summary of Changes from RFC 6020 394 This document defines version 1.1 of the YANG language. YANG version 395 1.1 is a maintenance release of the YANG language, addressing 396 ambiguities and defects in the original specification [RFC6020]. 398 The following changes are not backwards compatible with YANG version 399 1: 401 o Changed the rules for the interpretation of escaped characters in 402 double quoted strings. This is an backwards incompatible change 403 from YANG version 1. When updating a YANG version 1 module to 404 1.1, and the module uses a character sequence that is now illegal, 405 the string must be changed to match the new rules. See 406 Section 6.1.3 for details. 408 o An unquoted string cannot contain any single or double quote 409 characters. This is an backwards incompatible change from YANG 410 version 1. When updating a YANG version 1 module to 1.1, and the 411 module uses such quote characters, the string must be changed to 412 match the new rules. See Section 6.1.3 for details. 414 o Made "when" and "if-feature" illegal on list keys. This is an 415 backwards incompatible change from YANG version 1. When updating 416 a YANG version 1 module to 1.1, and the module uses these 417 constructs, they must be removed to match the new rules. 419 o Defined the legal characters in YANG modules. When updating a 420 YANG version 1 module to 1.1, any characters that are now illegal 421 must be removed. See Section 6 for details. 423 o Made noncharacters illegal in the built-in type "string". This 424 change affects the run-time behavior of YANG-based protocols. 426 The following additional changes have been done to YANG: 428 o Changed the YANG version from "1" to "1.1". 430 o Made the "yang-version" statement mandatory in YANG version "1.1". 432 o Extended the "if-feature" syntax to be a boolean expression over 433 feature names. 435 o Allow "if-feature" in "bit", "enum", and "identity". 437 o Allow "if-feature" in "refine". 439 o Allow "choice" as a shorthand case statement (see Section 7.9). 441 o Added a new substatement "modifier" to pattern (see 442 Section 9.4.6). 444 o Allow "must" in "input", "output", and "notification". 446 o Allow "require-instance" in leafref. 448 o Allow "description" and "reference" in "import" and "include". 450 o Allow imports of multiple revisions of a module. 452 o Allow "augment" to add conditionally mandatory nodes (see 453 Section 7.17). 455 o Added a set of new XPath functions in Section 10. 457 o Clarified the XPath context's tree in Section 6.4.1. 459 o Defined the string value of an identityref in XPath expressions 460 (see Section 9.10). 462 o Clarified what unprefixed names mean in leafrefs in typedefs (see 463 Section 6.4.1 and Section 9.9.2). 465 o Allow identities to be derived from multiple base identities (see 466 Section 7.18 and Section 9.10). 468 o Allow enumerations and bits to be subtyped (see Section 9.6 and 469 Section 9.7). 471 o Allow leaf-lists to have default values (see Section 7.7.2). 473 o Allow non-unique values in non-configuration leaf-lists (see 474 Section 7.7). 476 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 478 o Changed the module advertisement mechanism (see Section 5.6.4). 480 o Changed the scoping rules for definitions in submodules. A 481 submodule can now reference all definitions in all submodules that 482 belong to the same module, without using the "include" statement. 484 o Added a new statement "action" that is used to define operations 485 tied to data nodes. 487 o Allow notifications to be tied to data nodes. 489 o Added a new data definition statement "anydata" (see Section 7.10) 490 which is RECOMMENDED to be used instead of "anyxml" when the data 491 can be modeled in YANG 493 o Allow types empty and leafref in unions. 495 o Allow type empty in a key. 497 The following changes have been done to the NETCONF mapping: 499 o A server advertises support for YANG 1.1 modules by using ietf- 500 yang-library [I-D.ietf-netconf-yang-library] instead of listing 501 them as capabilities in the message. 503 2. Keywords 505 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 506 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 507 "OPTIONAL" in this document are to be interpreted as described in BCP 508 14, [RFC2119]. 510 3. Terminology 512 The following terms are used within this document: 514 o action: An operation defined for a node in the data tree. 516 o anydata: A data node that can contain an unknown set of nodes that 517 can be modelled by YANG, except anyxml. 519 o anyxml: A data node that can contain an unknown chunk of XML data. 521 o augment: Adds new schema nodes to a previously defined schema 522 node. 524 o base type: The type from which a derived type was derived, which 525 may be either a built-in type or another derived type. 527 o built-in type: A YANG data type defined in the YANG language, such 528 as uint32 or string. 530 o choice: A schema node where only one of a number of identified 531 alternatives is valid. 533 o client: An entity that can access YANG-defined data on a server, 534 over some network management protocol. 536 o conformance: A measure of how accurately a server follows a data 537 model. 539 o container: An interior data node that exists in at most one 540 instance in the data tree. A container has no value, but rather a 541 set of child nodes. 543 o data definition statement: A statement that defines new data 544 nodes. One of container, leaf, leaf-list, list, choice, case, 545 augment, uses, anydata, and anyxml. 547 o data model: A data model describes how data is represented and 548 accessed. 550 o data node: A node in the schema tree that can be instantiated in a 551 data tree. One of container, leaf, leaf-list, list, anydata, and 552 anyxml. 554 o data tree: An instantiated tree of any data modeled with YANG, 555 e.g., configuration data, state data, combined configuration and 556 state data, RPC or action input, RPC or action output, or 557 notification. 559 o derived type: A type that is derived from a built-in type (such as 560 uint32), or another derived type. 562 o extension: An extension attaches non-YANG semantics to statements. 563 The extension statement defines new statements to express these 564 semantics. 566 o feature: A mechanism for marking a portion of the model as 567 optional. Definitions can be tagged with a feature name and are 568 only valid on servers that support that feature. 570 o grouping: A reusable set of schema nodes, which may be used 571 locally in the module and by other modules that import from it. 572 The grouping statement is not a data definition statement and, as 573 such, does not define any nodes in the schema tree. 575 o identifier: A string used to identify different kinds of YANG 576 items by name. 578 o identity: A globally unique, abstract, and untyped name. 580 o instance identifier: A mechanism for identifying a particular node 581 in a data tree. 583 o interior node: Nodes within a hierarchy that are not leaf nodes. 585 o leaf: A data node that exists in at most one instance in the data 586 tree. A leaf has a value but no child nodes. 588 o leaf-list: Like the leaf node but defines a set of uniquely 589 identifiable nodes rather than a single node. Each node has a 590 value but no child nodes. 592 o list: An interior data node that may exist in multiple instances 593 in the data tree. A list has no value, but rather a set of child 594 nodes. 596 o mandatory node: A mandatory node is one of: 598 * A leaf, choice, anydata, or anyxml node with a "mandatory" 599 statement with the value "true". 601 * A list or leaf-list node with a "min-elements" statement with a 602 value greater than zero. 604 * A container node without a "presence" statement and which has 605 at least one mandatory node as a child. 607 o module: A YANG module defines hierarchies of schema nodes. With 608 its definitions and the definitions it imports or includes from 609 elsewhere, a module is self-contained and "compilable". 611 o non-presence container: A container that has no meaning of its 612 own, existing only to contain child nodes. 614 o presence container: A container where the presence of the 615 container itself carries some meaning. 617 o RPC: A Remote Procedure Call. 619 o RPC operation: A specific Remote Procedure Call. 621 o schema node: A node in the schema tree. One of action, container, 622 leaf, leaf-list, list, choice, case, rpc, input, output, 623 notification, anydata, and anyxml. 625 o schema node identifier: A mechanism for identifying a particular 626 node in the schema tree. 628 o schema tree: The definition hierarchy specified within a module. 630 o server: An entity that provides access to YANG-defined data to a 631 client, over some network management protocol. 633 o server deviation: A failure of the server to implement a module 634 faithfully. 636 o submodule: A partial module definition that contributes derived 637 types, groupings, data nodes, RPCs, actions, and notifications to 638 a module. A YANG module can be constructed from a number of 639 submodules. 641 o top-level data node: A data node where there is no other data node 642 between it and a module or submodule statement. 644 o uses: The "uses" statement is used to instantiate the set of 645 schema nodes defined in a grouping statement. The instantiated 646 nodes may be refined and augmented to tailor them to any specific 647 needs. 649 o value space: For a data type; the set of values permitted by the 650 data type. For a leaf or leaf-list instance; the value space of 651 its data type. 653 The following terms are defined in [RFC6241]: 655 o configuration data 657 o configuration datastore 659 o datastore 661 o state data 663 When modelled with YANG, a datastore is realized as an instantiated 664 data tree. 666 When modelled with YANG, a configuration datastore is realized as an 667 instantiated data tree with configuration data. 669 3.1. A Note on Examples 671 Throughout this document there are many examples of YANG statements. 672 These examples are supposed to illustrate certain features, and are 673 not supposed to be complete, valid YANG modules. 675 4. YANG Overview 677 This non-normative section is intended to give a high-level overview 678 of YANG to first-time readers. 680 4.1. Functional Overview 682 YANG is a language originally designed to model data for the NETCONF 683 protocol. A YANG module defines hierarchies of data that can be used 684 for NETCONF-based operations, including configuration, state data, 685 Remote Procedure Calls (RPCs), and notifications. This allows a 686 complete description of all data sent between a NETCONF client and 687 server. Although out of scope for this specification, YANG can also 688 be used with other protocols than NETCONF. 690 YANG models the hierarchical organization of data as a tree in which 691 each node has a name, and either a value or a set of child nodes. 692 YANG provides clear and concise descriptions of the nodes, as well as 693 the interaction between those nodes. 695 YANG structures data models into modules and submodules. A module 696 can import definitions from other external modules, and include 697 definitions from submodules. The hierarchy can be augmented, 698 allowing one module to add data nodes to the hierarchy defined in 699 another module. This augmentation can be conditional, with new nodes 700 appearing only if certain conditions are met. 702 YANG data models can describe constraints to be enforced on the data, 703 restricting the presence or value of nodes based on the presence or 704 value of other nodes in the hierarchy. These constraints are 705 enforceable by either the client or the server. 707 YANG defines a set of built-in types, and has a type mechanism 708 through which additional types may be defined. Derived types can 709 restrict their base type's set of valid values using mechanisms like 710 range or pattern restrictions that can be enforced by clients or 711 servers. They can also define usage conventions for use of the 712 derived type, such as a string-based type that contains a host name. 714 YANG permits the definition of reusable groupings of nodes. The 715 usage of these groupings can refine or augment the nodes, allowing it 716 to tailor the nodes to its particular needs. Derived types and 717 groupings can be defined in one module and used in either the same 718 module or in another module that imports it. 720 YANG data hierarchy constructs include defining lists where list 721 entries are identified by keys that distinguish them from each other. 722 Such lists may be defined as either sorted by user or automatically 723 sorted by the system. For user-sorted lists, operations are defined 724 for manipulating the order of the list entries. 726 YANG modules can be translated into an equivalent XML syntax called 727 YANG Independent Notation (YIN) (Section 13), allowing applications 728 using XML parsers and Extensible Stylesheet Language Transformations 729 (XSLT) scripts to operate on the models. The conversion from YANG to 730 YIN is semantically lossless, so content in YIN can be round-tripped 731 back into YANG. 733 YANG is an extensible language, allowing extension statements to be 734 defined by standards bodies, vendors, and individuals. The statement 735 syntax allows these extensions to coexist with standard YANG 736 statements in a natural way, while extensions in a YANG module stand 737 out sufficiently for the reader to notice them. 739 YANG resists the tendency to solve all possible problems, limiting 740 the problem space to allow expression of data models for network 741 management protocols such as NETCONF, not arbitrary XML documents or 742 arbitrary data models. 744 To the extent possible, YANG maintains compatibility with Simple 745 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 746 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 747 can be automatically translated into YANG modules for read-only 748 access [RFC6643]. However, YANG is not concerned with reverse 749 translation from YANG to SMIv2. 751 4.2. Language Overview 753 This section introduces some important constructs used in YANG that 754 will aid in the understanding of the language specifics in later 755 sections. 757 4.2.1. Modules and Submodules 759 YANG data models are defined in modules. A module contains a 760 collection of related definitions. 762 A module contains three types of statements: module-header 763 statements, revision statements, and definition statements. The 764 module header statements describe the module and give information 765 about the module itself, the revision statements give information 766 about the history of the module, and the definition statements are 767 the body of the module where the data model is defined. 769 A server may implement a number of modules, allowing multiple views 770 of the same data, or multiple views of disjoint subsections of the 771 server's data. Alternatively, the server may implement only one 772 module that defines all available data. 774 A module may have portions of its definitions separated into 775 submodules, based on the needs of the module designer. The external 776 view remains that of a single module, regardless of the presence or 777 size of its submodules. 779 The "import" statement allows a module or submodule to reference 780 definitions defined in other modules. 782 The "include" statement is used in a module to identify each 783 submodule that belongs to it. 785 4.2.2. Data Modeling Basics 787 YANG defines four main types of data nodes for data modeling. In 788 each of the following subsections, the examples show the YANG syntax 789 as well as a corresponding XML encoding. The syntax of YANG 790 statements is defined in Section 6.3. 792 4.2.2.1. Leaf Nodes 794 A leaf instance contains simple data like an integer or a string. It 795 has exactly one value of a particular type and no child nodes. 797 YANG Example: 799 leaf host-name { 800 type string; 801 description 802 "Hostname for this system"; 803 } 805 XML Encoding Example: 807 my.example.com 809 The "leaf" statement is covered in Section 7.6. 811 4.2.2.2. Leaf-List Nodes 813 A leaf-list defines a sequence of values of a particular type. 815 YANG Example: 817 leaf-list domain-search { 818 type string; 819 description 820 "List of domain names to search"; 821 } 823 XML Encoding Example: 825 high.example.com 826 low.example.com 827 everywhere.example.com 829 The "leaf-list" statement is covered in Section 7.7. 831 4.2.2.3. Container Nodes 833 A container is used to group related nodes in a subtree. A container 834 has only child nodes and no value. A container may contain any 835 number of child nodes of any type (leafs, lists, containers, leaf- 836 lists, actions, and notifications). 838 YANG Example: 840 container system { 841 container login { 842 leaf message { 843 type string; 844 description 845 "Message given at start of login session"; 846 } 847 } 848 } 850 XML Encoding Example: 852 853 854 Good morning 855 856 858 The "container" statement is covered in Section 7.5. 860 4.2.2.4. List Nodes 862 A list defines a sequence of list entries. Each entry is like a 863 container, and is uniquely identified by the values of its key leafs, 864 if it has any key leafs defined. A list can define multiple key 865 leafs and may contain any number of child nodes of any type 866 (including leafs, lists, containers etc.). 868 YANG Example: 870 list user { 871 key "name"; 872 leaf name { 873 type string; 874 } 875 leaf full-name { 876 type string; 877 } 878 leaf class { 879 type string; 880 } 881 } 883 XML Encoding Example: 885 886 glocks 887 Goldie Locks 888 intruder 889 890 891 snowey 892 Snow White 893 free-loader 894 895 896 rzell 897 Rapun Zell 898 tower 899 901 The "list" statement is covered in Section 7.8. 903 4.2.2.5. Example Module 905 These statements are combined to define the module: 907 // Contents of "example-system.yang" 908 module example-system { 909 yang-version 1.1; 910 namespace "urn:example:system"; 911 prefix "sys"; 912 organization "Example Inc."; 913 contact "joe@example.com"; 914 description 915 "The module for entities implementing the Example system."; 917 revision 2007-06-09 { 918 description "Initial revision."; 919 } 921 container system { 922 leaf host-name { 923 type string; 924 description 925 "Hostname for this system"; 926 } 928 leaf-list domain-search { 929 type string; 930 description 931 "List of domain names to search"; 932 } 934 container login { 935 leaf message { 936 type string; 937 description 938 "Message given at start of login session"; 939 } 941 list user { 942 key "name"; 943 leaf name { 944 type string; 945 } 946 leaf full-name { 947 type string; 948 } 949 leaf class { 950 type string; 951 } 952 } 953 } 954 } 955 } 957 4.2.3. Configuration and State Data 959 YANG can model state data, as well as configuration data, based on 960 the "config" statement. When a node is tagged with "config false", 961 its subhierarchy is flagged as state data. If it is tagged with 962 "config true", its subhierarchy is flagged as configuration data. 963 Parent containers, lists, and key leafs are reported also, giving the 964 context for the state data. 966 In this example, two leafs are defined for each interface, a 967 configured speed and an observed speed. 969 list interface { 970 key "name"; 971 config true; 973 leaf name { 974 type string; 975 } 976 leaf speed { 977 type enumeration { 978 enum 10m; 979 enum 100m; 980 enum auto; 981 } 982 } 983 leaf observed-speed { 984 type uint32; 985 config false; 986 } 987 } 989 The "config" statement is covered in Section 7.21.1. 991 4.2.4. Built-In Types 993 YANG has a set of built-in types, similar to those of many 994 programming languages, but with some differences due to special 995 requirements of network management. The following table summarizes 996 the built-in types discussed in Section 9: 998 +---------------------+-------------------------------------+ 999 | Name | Description | 1000 +---------------------+-------------------------------------+ 1001 | binary | Any binary data | 1002 | bits | A set of bits or flags | 1003 | boolean | "true" or "false" | 1004 | decimal64 | 64-bit signed decimal number | 1005 | empty | A leaf that does not have any value | 1006 | enumeration | One of an enumerated set of strings | 1007 | identityref | A reference to an abstract identity | 1008 | instance-identifier | A reference to a data tree node | 1009 | int8 | 8-bit signed integer | 1010 | int16 | 16-bit signed integer | 1011 | int32 | 32-bit signed integer | 1012 | int64 | 64-bit signed integer | 1013 | leafref | A reference to a leaf instance | 1014 | string | A character string | 1015 | uint8 | 8-bit unsigned integer | 1016 | uint16 | 16-bit unsigned integer | 1017 | uint32 | 32-bit unsigned integer | 1018 | uint64 | 64-bit unsigned integer | 1019 | union | Choice of member types | 1020 +---------------------+-------------------------------------+ 1022 The "type" statement is covered in Section 7.4. 1024 4.2.5. Derived Types (typedef) 1026 YANG can define derived types from base types using the "typedef" 1027 statement. A base type can be either a built-in type or a derived 1028 type, allowing a hierarchy of derived types. 1030 A derived type can be used as the argument for the "type" statement. 1032 YANG Example: 1034 typedef percent { 1035 type uint8 { 1036 range "0 .. 100"; 1037 } 1038 } 1040 leaf completed { 1041 type percent; 1042 } 1044 XML Encoding Example: 1046 20 1048 The "typedef" statement is covered in Section 7.3. 1050 4.2.6. Reusable Node Groups (grouping) 1052 Groups of nodes can be assembled into reusable collections using the 1053 "grouping" statement. A grouping defines a set of nodes that are 1054 instantiated with the "uses" statement. 1056 YANG Example: 1058 grouping target { 1059 leaf address { 1060 type inet:ip-address; 1061 description "Target IP address"; 1062 } 1063 leaf port { 1064 type inet:port-number; 1065 description "Target port number"; 1066 } 1067 } 1069 container peer { 1070 container destination { 1071 uses target; 1072 } 1073 } 1075 XML Encoding Example: 1077 1078 1079
2001:db8::2
1080 830 1081 1082 1084 The grouping can be refined as it is used, allowing certain 1085 statements to be overridden. In this example, the description is 1086 refined: 1088 container connection { 1089 container source { 1090 uses target { 1091 refine "address" { 1092 description "Source IP address"; 1093 } 1094 refine "port" { 1095 description "Source port number"; 1096 } 1097 } 1098 } 1099 container destination { 1100 uses target { 1101 refine "address" { 1102 description "Destination IP address"; 1103 } 1104 refine "port" { 1105 description "Destination port number"; 1106 } 1107 } 1108 } 1109 } 1111 The "grouping" statement is covered in Section 7.12. 1113 4.2.7. Choices 1115 YANG allows the data model to segregate incompatible nodes into 1116 distinct choices using the "choice" and "case" statements. The 1117 "choice" statement contains a set of "case" statements that define 1118 sets of schema nodes that cannot appear together. Each "case" may 1119 contain multiple nodes, but each node may appear in only one "case" 1120 under a "choice". 1122 The choice and case nodes appear only in the schema tree but not in 1123 the data tree. The additional levels of hierarchy are not needed 1124 beyond the conceptual schema. The presence of a case is indicated by 1125 the presence of one or more of the nodes within it. 1127 Since only one of the choice's cases can be valid at any time, when a 1128 node from one case is created in the data tree, all nodes from all 1129 other cases are implicitly deleted. The server handles the 1130 enforcement of the constraint, preventing incompatibilities from 1131 existing in the configuration. 1133 YANG Example: 1135 container food { 1136 choice snack { 1137 case sports-arena { 1138 leaf pretzel { 1139 type empty; 1140 } 1141 leaf beer { 1142 type empty; 1143 } 1144 } 1145 case late-night { 1146 leaf chocolate { 1147 type enumeration { 1148 enum dark; 1149 enum milk; 1150 enum first-available; 1151 } 1152 } 1153 } 1154 } 1155 } 1157 XML Encoding Example: 1159 1160 1161 1162 1164 The "choice" statement is covered in Section 7.9. 1166 4.2.8. Extending Data Models (augment) 1168 YANG allows a module to insert additional nodes into data models, 1169 including both the current module (and its submodules) or an external 1170 module. This is useful for example for vendors to add vendor- 1171 specific parameters to standard data models in an interoperable way. 1173 The "augment" statement defines the location in the data model 1174 hierarchy where new nodes are inserted, and the "when" statement 1175 defines the conditions when the new nodes are valid. 1177 When a server implements a module containing an "augment" statement, 1178 that implies that the server's implementation of the augmented module 1179 contains the additional nodes. 1181 YANG Example: 1183 augment /system/login/user { 1184 when "class != 'wheel'"; 1185 leaf uid { 1186 type uint16 { 1187 range "1000 .. 30000"; 1188 } 1189 } 1190 } 1192 This example defines a "uid" node that only is valid when the user's 1193 "class" is not "wheel". 1195 If a module augments another module, the XML elements that are added 1196 to the encoding are in the namespace of the augmenting module. For 1197 example, if the above augmentation were in a module with prefix 1198 "other", the XML would look like: 1200 XML Encoding Example: 1202 1203 alicew 1204 Alice N. Wonderland 1205 drop-out 1206 1024 1207 1209 The "augment" statement is covered in Section 7.17. 1211 4.2.9. Operation Definitions 1213 YANG allows the definition of operations. The operations' name, 1214 input parameters, and output parameters are modeled using YANG data 1215 definition statements. Operations on the top-level in a module are 1216 defined with the "rpc" statement. Operations can also be tied to a 1217 container or list data node. Such operations are defined with the 1218 "action" statement. 1220 YANG Example for an operation at the top-level: 1222 rpc activate-software-image { 1223 input { 1224 leaf image-name { 1225 type string; 1226 } 1227 } 1228 output { 1229 leaf status { 1230 type string; 1231 } 1232 } 1233 } 1235 NETCONF XML Example: 1237 1239 1240 example-fw-2.3 1241 1242 1244 1246 1247 The image example-fw-2.3 is being installed. 1248 1249 1251 YANG Example for an operation tied to a list data node: 1253 list interface { 1254 key "name"; 1256 leaf name { 1257 type string; 1258 } 1260 action ping { 1261 input { 1262 leaf destination { 1263 type inet:ip-address; 1264 } 1265 } 1266 output { 1267 leaf packet-loss { 1268 type uint8; 1269 } 1270 } 1271 } 1272 } 1274 NETCONF XML Example: 1276 1278 1279 1280 eth1 1281 1282 192.0.2.1 1283 1284 1285 1286 1288 1291 60 1292 1294 The "rpc" statement is covered in Section 7.14, and the "action" 1295 statement in Section 7.15. 1297 4.2.10. Notification Definitions 1299 YANG allows the definition of notifications. YANG data definition 1300 statements are used to model the content of the notification. 1302 YANG Example: 1304 notification link-failure { 1305 description 1306 "A link failure has been detected"; 1307 leaf if-name { 1308 type leafref { 1309 path "/interface/name"; 1310 } 1311 } 1312 leaf if-admin-status { 1313 type admin-status; 1314 } 1315 leaf if-oper-status { 1316 type oper-status; 1317 } 1318 } 1320 NETCONF XML Example: 1322 1324 2007-09-01T10:00:00Z 1325 1326 so-1/2/3.0 1327 up 1328 down 1329 1330 1332 The "notification" statement is covered in Section 7.16. 1334 5. Language Concepts 1336 5.1. Modules and Submodules 1338 The module is the base unit of definition in YANG. A module defines 1339 a single data model. A module can also augment an existing data 1340 model with additional nodes. 1342 Submodules are partial modules that contribute definitions to a 1343 module. A module may include any number of submodules, but each 1344 submodule may belong to only one module. 1346 Developers of YANG modules and submodules are RECOMMENDED to choose 1347 names for their modules that will have a low probability of colliding 1348 with standard or other enterprise modules, e.g., by using the 1349 enterprise or organization name as a prefix for the module name. 1350 Within a server, all module names MUST be unique. 1352 A module uses the "include" statement to list all its submodules. A 1353 module, or submodule belonging to that module, can reference 1354 definitions in the module and all submodules included by the module. 1356 A module or submodule uses the "import" statement to reference 1357 external modules. Statements in the module or submodule can 1358 reference definitions in the external module using the prefix 1359 specified in the "import" statement. 1361 For backward compatibility with YANG version 1, a submodule MAY use 1362 the "include" statement to reference other submodules within its 1363 module, but this is not necessary in YANG version 1.1. A submodule 1364 can reference any definition in the module it belongs to and in all 1365 submodules included by the module. A submodule MUST NOT include 1366 different revisions of other submodules than the revisions that its 1367 module includes. 1369 A module or submodule MUST NOT include submodules from other modules, 1370 and a submodule MUST NOT import its own module. 1372 The import and include statements are used to make definitions 1373 available from other modules: 1375 o For a module or submodule to reference definitions in an external 1376 module, the external module MUST be imported. 1378 o A module MUST include all its submodules. 1380 o A module, or submodule belonging to that module, MAY reference 1381 definitions in the module and all submodules included by the 1382 module. 1384 There MUST NOT be any circular chains of imports. For example, if 1385 module "a" imports module "b", "b" cannot import "a". 1387 When a definition in an external module is referenced, a locally 1388 defined prefix MUST be used, followed by a colon (":"), and then the 1389 external identifier. References to definitions in the local module 1390 MAY use the prefix notation. Since built-in data types do not belong 1391 to any module and have no prefix, references to built-in data types 1392 (e.g., int32) cannot use the prefix notation. The syntax for a 1393 reference to a definition is formally defined by the rule 1394 "identifier-ref" in Section 14. 1396 5.1.1. Import and Include by Revision 1398 Published modules evolve independently over time. In order to allow 1399 for this evolution, modules can be imported using specific revisions. 1400 Initially, a module imports the revisions of other modules that are 1401 current when the module is written. As future revisions of the 1402 imported modules are published, the importing module is unaffected 1403 and its contents are unchanged. When the author of the module is 1404 prepared to move to the most recently published revision of an 1405 imported module, the module is republished with an updated "import" 1406 statement. By republishing with the new revision, the authors 1407 explicitly indicate their acceptance of any changes in the imported 1408 module. 1410 For submodules, the issue is related but simpler. A module or 1411 submodule that includes submodules may specify the revision of the 1412 included submodules. If a submodule changes, any module or submodule 1413 that includes it by revision needs to be updated to reference the new 1414 revision. 1416 For example, module "b" imports module "a". 1418 module a { 1419 yang-version 1.1; 1420 namespace "urn:example:a"; 1421 prefix "a"; 1423 revision 2008-01-01 { ... } 1424 grouping a { 1425 leaf eh { .... } 1426 } 1427 } 1429 module b { 1430 yang-version 1.1; 1431 namespace "urn:example:b"; 1432 prefix "b"; 1434 import a { 1435 prefix "p"; 1436 revision-date 2008-01-01; 1437 } 1439 container bee { 1440 uses p:a; 1441 } 1442 } 1444 When the author of "a" publishes a new revision, the changes may not 1445 be acceptable to the author of "b". If the new revision is 1446 acceptable, the author of "b" can republish with an updated revision 1447 in the "import" statement. 1449 If a module is not imported with a specific revision, it is undefined 1450 which revision is used. 1452 5.1.2. Module Hierarchies 1454 YANG allows modeling of data in multiple hierarchies, where data may 1455 have more than one top-level node. Each top-level data node in a 1456 module defines a separate hierarchy. Models that have multiple top- 1457 level nodes are sometimes convenient, and are supported by YANG. 1459 5.1.2.1. NETCONF XML Encoding 1461 NETCONF is capable of carrying any XML content as the payload in the 1462 and elements. The top-level nodes of YANG modules 1463 are encoded as child elements, in any order, within these elements. 1464 This encapsulation guarantees that the corresponding NETCONF messages 1465 are always well-formed XML documents. 1467 For example, an instance of: 1469 module example-config { 1470 yang-version 1.1; 1471 namespace "urn:example:config"; 1472 prefix "co"; 1474 container system { ... } 1475 container routing { ... } 1476 } 1478 could be encoded in NETCONF as: 1480 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1498 5.2. File Layout 1500 YANG modules and submodules are typically stored in files, one module 1501 or submodule statement per file. The name of the file SHOULD be of 1502 the form: 1504 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1506 "module-or-submodule-name" is the name of the module or submodule, 1507 and the optional "revision-date" is the latest revision of the module 1508 or submodule, as defined by the "revision" statement (Section 7.1.9). 1510 The file extension ".yang" denotes that the contents of the file is 1511 written with YANG syntax (Section 6), and ".yin" denotes that it is 1512 written with YIN syntax (Section 13). 1514 YANG parsers can find imported modules and included submodules via 1515 this convention. 1517 5.3. XML Namespaces 1519 All YANG definitions are specified within a module. Each module is 1520 bound to a distinct XML namespace [XML-NAMES], which is a globally 1521 unique URI [RFC3986]. A NETCONF client or server uses the namespace 1522 during XML encoding of data. 1524 XML namespaces for modules published in RFC streams [RFC4844] MUST be 1525 assigned by IANA, see section 14 in [RFC6020]. 1527 XML namespaces for private modules are assigned by the organization 1528 owning the module without a central registry. Namespace URIs MUST be 1529 chosen so they cannot collide with standard or other enterprise 1530 namespaces, for example by using the enterprise or organization name 1531 in the namespace. 1533 The "namespace" statement is covered in Section 7.1.3. 1535 5.3.1. YANG XML Namespace 1537 YANG defines an XML namespace for NETCONF operations, 1538 content, and the element. The name of this 1539 namespace is "urn:ietf:params:xml:ns:yang:1". 1541 5.4. Resolving Grouping, Type, and Identity Names 1543 Grouping, type, and identity names are resolved in the context in 1544 which they are defined, rather than the context in which they are 1545 used. Users of groupings, typedefs, and identities are not required 1546 to import modules or include submodules to satisfy all references 1547 made by the original definition. This behaves like static scoping in 1548 a conventional programming language. 1550 For example, if a module defines a grouping in which a type is 1551 referenced, when the grouping is used in a second module, the type is 1552 resolved in the context of the original module, not the second 1553 module. There is no ambiguity if both modules define the type, since 1554 there is no ambiguity. 1556 5.5. Nested Typedefs and Groupings 1558 Typedefs and groupings may appear nested under many YANG statements, 1559 allowing these to be lexically scoped by the statement hierarchy 1560 under which they appear. This allows types and groupings to be 1561 defined near where they are used, rather than placing them at the top 1562 level of the hierarchy. The close proximity increases readability. 1564 Scoping also allows types to be defined without concern for naming 1565 conflicts between types in different submodules. Type names can be 1566 specified without adding leading strings designed to prevent name 1567 collisions within large modules. 1569 Finally, scoping allows the module author to keep types and groupings 1570 private to their module or submodule, preventing their reuse. Since 1571 only top-level types and groupings (i.e., those appearing as 1572 substatements to a module or submodule statement) can be used outside 1573 the module or submodule, the developer has more control over what 1574 pieces of their module are presented to the outside world, supporting 1575 the need to hide internal information and maintaining a boundary 1576 between what is shared with the outside world and what is kept 1577 private. 1579 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1580 type or grouping cannot be defined if a higher level in the statement 1581 hierarchy has a definition with a matching identifier. 1583 A reference to an unprefixed type or grouping, or one which uses the 1584 prefix of the current module, is resolved by locating the matching 1585 "typedef" or "grouping" statement among the immediate substatements 1586 of each ancestor statement. 1588 5.6. Conformance 1590 Conformance to a model is a measure of how accurately a server 1591 follows the model. Generally speaking, servers are responsible for 1592 implementing the model faithfully, allowing applications to treat 1593 servers which implement the model identically. Deviations from the 1594 model can reduce the utility of the model and increase fragility of 1595 applications that use it. 1597 YANG modelers have three mechanisms for conformance: 1599 o the basic behavior of the model 1601 o optional features that are part of the model 1603 o deviations from the model 1605 We will consider each of these in sequence. 1607 5.6.1. Basic Behavior 1609 The model defines a contract between a YANG-based client and server, 1610 which allows both parties to have faith the other knows the syntax 1611 and semantics behind the modeled data. The strength of YANG lies in 1612 the strength of this contract. 1614 5.6.2. Optional Features 1616 In many models, the modeler will allow sections of the model to be 1617 conditional. The server controls whether these conditional portions 1618 of the model are supported or valid for that particular server. 1620 For example, a syslog data model may choose to include the ability to 1621 save logs locally, but the modeler will realize that this is only 1622 possible if the server has local storage. If there is no local 1623 storage, an application should not tell the server to save logs. 1625 YANG supports this conditional mechanism using a construct called 1626 "feature". Features give the modeler a mechanism for making portions 1627 of the module conditional in a manner that is controlled by the 1628 server. The model can express constructs that are not universally 1629 present in all servers. These features are included in the model 1630 definition, allowing a consistent view and allowing applications to 1631 learn which features are supported and tailor their behavior to the 1632 server. 1634 A module may declare any number of features, identified by simple 1635 strings, and may make portions of the module optional based on those 1636 features. If the server supports a feature, then the corresponding 1637 portions of the module are valid for that server. If the server 1638 doesn't support the feature, those parts of the module are not valid, 1639 and applications should behave accordingly. 1641 Features are defined using the "feature" statement. Definitions in 1642 the module that are conditional to the feature are noted by the 1643 "if-feature" statement. 1645 Further details are available in Section 7.20.1. 1647 5.6.3. Deviations 1649 In an ideal world, all servers would be required to implement the 1650 model exactly as defined, and deviations from the model would not be 1651 allowed. But in the real world, servers are often not able or 1652 designed to implement the model as written. For YANG-based 1653 automation to deal with these server deviations, a mechanism must 1654 exist for servers to inform applications of the specifics of such 1655 deviations. 1657 For example, a BGP module may allow any number of BGP peers, but a 1658 particular server may only support 16 BGP peers. Any application 1659 configuring the 17th peer will receive an error. While an error may 1660 suffice to let the application know it cannot add another peer, it 1661 would be far better if the application had prior knowledge of this 1662 limitation and could prevent the user from starting down the path 1663 that could not succeed. 1665 Server deviations are declared using the "deviation" statement, which 1666 takes as its argument a string that identifies a node in the schema 1667 tree. The contents of the statement details the manner in which the 1668 server implementation deviates from the contract as defined in the 1669 module. 1671 Further details are available in Section 7.20.3. 1673 5.6.4. Announcing Conformance Information in NETCONF 1675 This document defines the following mechanism for announcing 1676 conformance information. Other mechanisms may be defined by future 1677 specifications. 1679 A NETCONF server MUST announce the modules it implements (see 1680 Section 5.6.5) by implementing the YANG module "ietf-yang-library" 1681 defined in [I-D.ietf-netconf-yang-library], and listing all 1682 implemented modules in the "/modules-state/module" list. 1684 The server also MUST advertise the following capability in the 1685 message (line-breaks and whitespaces are used for formatting 1686 reasons only): 1688 urn:ietf:params:netconf:capability:yang-library:1.0? 1689 revision=&module-set-id= 1691 The parameter "revision" has the same value as the revision date of 1692 the "ietf-yang-library" module implemented by the server. This 1693 parameter MUST be present. 1695 The parameter "module-set-id" has the same value as the leaf 1696 "/modules-state/module-set-id" from "ietf-yang-library". This 1697 parameter MUST be present. 1699 With this mechanism, a client can cache the supported modules for a 1700 server, and only update the cache if the "module-set-id" value in the 1701 message changes. 1703 5.6.5. Implementing a Module 1705 A server implements a module if it implements the module's data 1706 nodes, rpcs, actions, notifications, and deviations. 1708 A server MUST NOT implement more than one revision of a module. 1710 If a server implements a module A that imports a module B, and A uses 1711 any node from B in an "augment" or "path" statement that the server 1712 supports, then the server MUST implement a revision of module B that 1713 has these nodes defined. This is regardless of if module B is 1714 imported by revision or not. 1716 If a server implements a module A that imports a module C without 1717 specifying the revision date of module C, and the server does not 1718 implement C (e.g., if C only defines some typedefs), the server MUST 1719 list module C in the "/modules-state/module" list from 1720 "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set 1721 the leaf "conformance-type" to "import" for this module. 1723 If a server lists a module C in the "/modules-state/module" list from 1724 "ietf-yang-library", and there are other modules Ms listed that 1725 import C without specifying the revision date of module C, the server 1726 MUST use the definitions from the most recent revision of C listed 1727 for modules Ms. 1729 The reason for these rules is that clients need to be able to know 1730 the specific data model structure and types of all leafs and leaf- 1731 lists implemented in a server. 1733 For example, with these modules: 1735 module a { 1736 yang-version 1.1; 1737 namespace "urn:example:a"; 1738 prefix "a"; 1740 import b { 1741 revision-date 2015-01-01; 1742 } 1743 import c; 1745 revision 2015-01-01; 1747 feature foo; 1749 augment "/b:x" { 1750 if-feature foo; 1751 leaf y { 1752 type b:myenum; 1753 } 1754 } 1756 container a { 1757 leaf x { 1758 type c:bar; 1759 } 1760 } 1761 } 1763 module b { 1764 yang-version 1.1; 1765 namespace "urn:example:b"; 1766 prefix "b"; 1768 revision 2015-01-01; 1770 typedef myenum { 1771 type enumeration { 1772 enum zero; 1773 } 1774 } 1776 container x { 1777 } 1778 } 1780 module b { 1781 yang-version 1.1; 1782 namespace "urn:example:b"; 1783 prefix "b"; 1785 revision 2015-04-04; 1786 revision 2015-01-01; 1788 typedef myenum { 1789 type enumeration { 1790 enum zero; // added in 2015-01-01 1791 enum one; // added in 2015-04-04 1792 } 1793 } 1795 container x { // added in 2015-01-01 1796 container y; // added in 2015-04-04 1797 } 1798 } 1799 module c { 1800 yang-version 1.1; 1801 namespace "urn:example:c"; 1802 prefix "c"; 1804 revision 2015-02-02; 1806 typedef bar { 1807 ... 1808 } 1809 } 1811 module c { 1812 yang-version 1.1; 1813 namespace "urn:example:c"; 1814 prefix "c"; 1816 revision 2015-03-03; 1817 revision 2015-02-02; 1819 typedef bar { 1820 ... 1821 } 1822 } 1824 A server that implements revision "2015-01-01" of module "a" and 1825 supports feature "foo" can implement revision "2015-01-01" or 1826 "2015-04-04" of module "b". Since "b" was imported by revision, the 1827 type of leaf "/b:x/a:y" is the same regardless of which revision of 1828 "b" the server implements. 1830 A server that implements module "a", but does not support feature 1831 "foo" does not have to implement module "b". 1833 A server that implements revision "2015-01-01" of module "a" picks 1834 any revision of module "c", and list it in the "/modules-state/ 1835 module" list from "ietf-yang-library". 1837 The following XML encoding example shows valid data for the 1838 "/modules-state/module" list for a server that implements module "a": 1840 1842 ee1ecb017370cafd 1843 1844 a 1845 2015-01-01 1846 urn:example:a 1847 foo 1848 implement 1849 1850 1851 b 1852 2015-04-04 1853 urn:example:b 1854 implement 1855 1856 1857 c 1858 2015-02-02 1859 urn:example:c 1860 import 1861 1862 1864 5.7. Datastore Modification 1866 Data models may allow the server to alter the configuration datastore 1867 in ways not explicitly directed via network management protocol 1868 messages. For example, a data model may define leafs that are 1869 assigned system-generated values when the client does not provide 1870 one. A formal mechanism for specifying the circumstances where these 1871 changes are allowed is out of scope for this specification. 1873 6. YANG Syntax 1875 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1876 languages like C and C++. This C-like syntax was chosen specifically 1877 for its readability, since YANG values the time and effort of the 1878 readers of models above those of modules writers and YANG tool-chain 1879 developers. This section introduces the YANG syntax. 1881 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1882 [ISO.10646] characters, including tab, carriage return, and line feed 1883 but excluding the other C0 control characters, the surrogate blocks, 1884 and the noncharacters. The character syntax is formally defined by 1885 the rule "yang-char" in Section 14. 1887 YANG modules and submodules are stored in files using the UTF-8 1888 [RFC3629] character encoding. 1890 Lines in a YANG module end with a carriage return-line feed 1891 combination or with a line feed alone. A carriage return that is not 1892 followed by a line feed may only appear inside a quoted string 1893 (Section 6.1.3). Note that carriage returns and line feeds that 1894 appear inside quoted strings become part of the value of the string 1895 without modification; the value of a multi-line quoted string 1896 contains the same form of line ends as those lines of the YANG 1897 module. 1899 6.1. Lexical Tokenization 1901 YANG modules are parsed as a series of tokens. This section details 1902 the rules for recognizing tokens from an input stream. YANG 1903 tokenization rules are both simple and powerful. The simplicity is 1904 driven by a need to keep the parsers easy to implement, while the 1905 power is driven by the fact that modelers need to express their 1906 models in readable formats. 1908 6.1.1. Comments 1910 Comments are C++ style. A single line comment starts with "//" and 1911 ends at the end of the line. A block comment starts with "/*" and 1912 ends with the nearest following "*/". 1914 Note that inside a quoted string (Section 6.1.3), these character 1915 pairs are never interpreted as the start or end of a comment. 1917 6.1.2. Tokens 1919 A token in YANG is either a keyword, a string, a semicolon (";"), or 1920 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1921 is either one of the YANG keywords defined in this document, or a 1922 prefix identifier, followed by a colon (":"), followed by a language 1923 extension keyword. Keywords are case sensitive. See Section 6.2 for 1924 a formal definition of identifiers. 1926 6.1.3. Quoting 1928 An unquoted string is any sequence of characters that does not 1929 contain any space, tab, carriage return, or line feed characters, a 1930 single or double quote character, a semicolon (";"), braces ("{" or 1931 "}"), or comment sequences ("//", "/*", or "*/"). 1933 Note that any keyword can legally appear as an unquoted string. 1935 Within an unquoted string, every character is preserved. Note that 1936 this means that the backslash character does not have any special 1937 meaning in an unquoted string. 1939 If a double-quoted string contains a line break followed by space or 1940 tab characters that are used to indent the text according to the 1941 layout in the YANG file, this leading whitespace is stripped from the 1942 string, up to and including the column of the starting double quote 1943 character, or to the first non-whitespace character, whichever occurs 1944 first. Any tab character in a succeeding line that must be examined 1945 for stripping is first converted into 8 space characters. 1947 If a double-quoted string contains space or tab characters before a 1948 line break, this trailing whitespace is stripped from the string. 1950 A single-quoted string (enclosed within ' ') preserves each character 1951 within the quotes. A single quote character cannot occur in a 1952 single-quoted string, even when preceded by a backslash. 1954 Within a double-quoted string (enclosed within " "), a backslash 1955 character introduces a representation of a special character, which 1956 depends on the character that immediately follows the backslash: 1958 \n new line 1959 \t a tab character 1960 \" a double quote 1961 \\ a single backslash 1963 The backslash MUST NOT be followed by any other character. 1965 If a quoted string is followed by a plus character ("+"), followed by 1966 another quoted string, the two strings are concatenated into one 1967 string, allowing multiple concatenations to build one string. 1968 Whitespace, line breaks, and comments are allowed between the quoted 1969 strings and the plus character. 1971 In double-quoted strings, whitespace trimming is done before 1972 substitution of backslash-escaped characters. Concatenation is 1973 performed as the last step. 1975 6.1.3.1. Quoting Examples 1977 The following strings are equivalent: 1979 hello 1980 "hello" 1981 'hello' 1982 "hel" + "lo" 1983 'hel' + "lo" 1985 The following examples show some special strings: 1987 "\"" - string containing a double quote 1988 '"' - string containing a double quote 1989 "\n" - string containing a new line character 1990 '\n' - string containing a backslash followed 1991 by the character n 1993 The following examples show some illegal strings: 1995 '''' - a single-quoted string cannot contain single quotes 1996 """ - a double quote must be escaped in a double-quoted string 1998 The following strings are equivalent: 2000 "first line 2001 second line" 2003 "first line\n" + " second line" 2005 6.2. Identifiers 2007 Identifiers are used to identify different kinds of YANG items by 2008 name. Each identifier starts with an uppercase or lowercase ASCII 2009 letter or an underscore character, followed by zero or more ASCII 2010 letters, digits, underscore characters, hyphens, and dots. 2011 Implementations MUST support identifiers up to 64 characters in 2012 length, and MAY support longer identifiers. Identifiers are case 2013 sensitive. The identifier syntax is formally defined by the rule 2014 "identifier" in Section 14. Identifiers can be specified as quoted 2015 or unquoted strings. 2017 6.2.1. Identifiers and Their Namespaces 2019 Each identifier is valid in a namespace that depends on the type of 2020 the YANG item being defined. All identifiers defined in a namespace 2021 MUST be unique. 2023 o All module and submodule names share the same global module 2024 identifier namespace. 2026 o All extension names defined in a module and its submodules share 2027 the same extension identifier namespace. 2029 o All feature names defined in a module and its submodules share the 2030 same feature identifier namespace. 2032 o All identity names defined in a module and its submodules share 2033 the same identity identifier namespace. 2035 o All derived type names defined within a parent node or at the top 2036 level of the module or its submodules share the same type 2037 identifier namespace. This namespace is scoped to all descendant 2038 nodes of the parent node or module. This means that any 2039 descendent node may use that typedef, and it MUST NOT define a 2040 typedef with the same name. 2042 o All grouping names defined within a parent node or at the top 2043 level of the module or its submodules share the same grouping 2044 identifier namespace. This namespace is scoped to all descendant 2045 nodes of the parent node or module. This means that any 2046 descendent node may use that grouping, and it MUST NOT define a 2047 grouping with the same name. 2049 o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 2050 notifications, anydatas, and anyxmls defined (directly or through 2051 a uses statement) within a parent node or at the top level of the 2052 module or its submodules share the same identifier namespace. 2053 This namespace is scoped to the parent node or module, unless the 2054 parent node is a case node. In that case, the namespace is scoped 2055 to the closest ancestor node that is not a case or choice node. 2057 o All cases within a choice share the same case identifier 2058 namespace. This namespace is scoped to the parent choice node. 2060 Forward references are allowed in YANG. 2062 6.3. Statements 2064 A YANG module contains a sequence of statements. Each statement 2065 starts with a keyword, followed by zero or one argument, followed 2066 either by a semicolon (";") or a block of substatements enclosed 2067 within braces ("{ }"): 2069 statement = keyword [argument] (";" / "{" *statement "}") 2071 The argument is a string, as defined in Section 6.1.2. 2073 6.3.1. Language Extensions 2075 A module can introduce YANG extensions by using the "extension" 2076 keyword (see Section 7.19). The extensions can be imported by other 2077 modules with the "import" statement (see Section 7.1.5). When an 2078 imported extension is used, the extension's keyword MUST be qualified 2079 using the prefix with which the extension's module was imported. If 2080 an extension is used in the module where it is defined, the 2081 extension's keyword MUST be qualified with the prefix of this module. 2083 The processing of extensions depends on whether support for those 2084 extensions is claimed for a given YANG parser or the tool set in 2085 which it is embedded. An unsupported extension, appearing in a YANG 2086 module as an unknown-statement (see Section 14) MAY be ignored in its 2087 entirety. Any supported extension MUST be processed in accordance 2088 with the specification governing that extension. 2090 Care must be taken when defining extensions so that modules that use 2091 the extensions are meaningful also for applications that do not 2092 support the extensions. 2094 6.4. XPath Evaluations 2096 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 2097 for specifying many inter-node references and dependencies. An 2098 implementation is not required to implement an XPath interpreter, but 2099 MUST ensure that the requirements encoded in the data model are 2100 enforced. The manner of enforcement is an implementation decision. 2101 The XPath expressions MUST be syntactically correct, and all prefixes 2102 used MUST be present in the XPath context (see Section 6.4.1). An 2103 implementation may choose to implement them by hand, rather than 2104 using the XPath expression directly. 2106 The data model used in the XPath expressions is the same as that used 2107 in XPath 1.0 [XPATH], with the same extension for root node children 2108 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 2109 that the root node may have any number of element nodes as its 2110 children. 2112 The data tree has no concept of document order. An implementation 2113 needs to choose some document order but how it is done is an 2114 implementation decision. This means that XPath expressions in YANG 2115 modules SHOULD NOT rely on any specific document order. 2117 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 2118 values, see Section 3.5 in [XPATH]. This means that some values of 2119 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 2120 cannot be exactly represented in XPath expressions. Therefore, due 2121 caution should be exercised when using nodes with 64-bit numeric 2122 values in XPath expressions. In particular, numerical comparisons 2123 involving equality may yield unexpected results. 2125 For example, consider the following definition: 2127 leaf lxiv { 2128 type decimal64 { 2129 fraction-digits 18; 2130 } 2131 must ". <= 10"; 2132 } 2134 An instance of the "lxiv" leaf having the value of 2135 10.0000000000000001 will then successfully pass validation. 2137 6.4.1. XPath Context 2139 All YANG XPath expressions share the following XPath context 2140 definition: 2142 o The set of namespace declarations is the set of all "import" 2143 statements' prefix and namespace pairs in the module where the 2144 XPath expression is specified, and the "prefix" statement's prefix 2145 for the "namespace" statement's URI. 2147 o Names without a namespace prefix belong to the same namespace as 2148 the identifier of the current node. Inside a grouping, that 2149 namespace is affected by where the grouping is used (see 2150 Section 7.13). Inside a typedef, that namespace is affected by 2151 where the typedef is referenced. If a typedef is defined and 2152 referenced within a grouping, the namespace is affected by where 2153 the grouping is used (see Section 7.13). 2155 o The function library is the core function library defined in 2156 [XPATH], and the functions defined in Section 10. 2158 o The set of variable bindings is empty. 2160 The mechanism for handling unprefixed names is adopted from XPath 2.0 2161 [XPATH2.0], and helps simplify XPath expressions in YANG. No 2162 ambiguity may ever arise because YANG node identifiers are always 2163 qualified names with a non-null namespace URI. 2165 The accessible tree depends on where the statement with the XPath 2166 expression is defined: 2168 o If the XPath expression is defined in substatement to a data node 2169 that represents configuration, the accessible tree is the data in 2170 the datastore where the context node exists. The root node has 2171 all top-level configuration data nodes in all modules as children. 2173 o If the XPath expression is defined in a substatement to a data 2174 node that represents state data, the accessible tree is all state 2175 data in the server, and the running configuration datastore. The 2176 root node has all top-level data nodes in all modules as children. 2178 o If the XPath expression is defined in a substatement to a 2179 "notification" statement, the accessible tree is the notification 2180 instance, all state data in the server, and the running 2181 configuration datastore. If the notification is defined on the 2182 top-level in a module, then the root node has the node 2183 representing the notification being defined and all top-level data 2184 nodes in all modules as children. Otherwise, the root node has 2185 all top-level data nodes in all modules as children. 2187 o If the XPath expression is defined in a substatement to an "input" 2188 statement in an "rpc" or "action" statement, the accessible tree 2189 is the RPC or action operation instance, all state data in the 2190 server, and the running configuration datastore. The root node 2191 has top-level data nodes in all modules as children. 2192 Additionally, for an RPC, the root node also has the node 2193 representing the RPC operation being defined as a child. The node 2194 representing the operation being defined has the operation's input 2195 parameters as children. 2197 o If the XPath expression is defined in a substatement to an 2198 "output" statement in an "rpc" or "action" statement, the 2199 accessible tree is the RPC or action operation instance, all state 2200 data in the server, and the running configuration datastore. The 2201 root node has top-level data nodes in all modules as children. 2202 Additionally, for an RPC, the root node also has the node 2203 representing the RPC operation being defined as a child. The node 2204 representing the operation being defined has the operation's 2205 output parameters as children. 2207 In the accessible tree, all leafs and leaf-lists with default values 2208 in use exist (See Section 7.6.1 and Section 7.7.2). 2210 If a node that exists in the accessible tree has a non-presence 2211 container as a child, then the non-presence container also exists in 2212 the tree. 2214 The context node varies with the YANG XPath expression, and is 2215 specified where the YANG statement with the XPath expression is 2216 defined. 2218 6.4.1.1. Examples 2220 Given the following module: 2222 module example-a { 2223 yang-version 1.1; 2224 namespace urn:example:a; 2225 prefix a; 2227 container a { 2228 list b { 2229 key id; 2230 leaf id { 2231 type string; 2232 } 2233 notification down { 2234 leaf reason { 2235 type string; 2236 } 2237 } 2238 action reset { 2239 input { 2240 leaf delay { 2241 type uint32; 2242 } 2243 } 2244 output { 2245 leaf result { 2246 type string; 2247 } 2248 } 2249 } 2250 } 2251 } 2252 notification failure { 2253 leaf b-ref { 2254 type leafref { 2255 path "/a/b/id"; 2256 } 2257 } 2258 } 2259 } 2261 And given the following data tree, specified in XML: 2263 2264 2265 1 2266 2267 2268 2 2269 2270 2272 The accessible tree for a notification "down" on /a/b[id="2"] is: 2274 2275 2276 1 2277 2278 2279 2 2280 2281 error 2282 2283 2284 2285 // possibly other top-level nodes here 2287 The accessible tree for an action invocation of "reset" on /a/ 2288 b[id="1"] with the "when" parameter set to "10" would be: 2290 2291 2292 1 2293 2294 10 2295 2296 2297 2298 2 2299 2300 2301 // possibly other top-level nodes here 2303 The accessible tree for the action output of this action is: 2305 2306 2307 1 2308 2309 ok 2310 2311 2312 2313 2 2314 2315 2316 // possibly other top-level nodes here 2318 The accessible tree for a notification "failure" could be: 2320 2321 2322 1 2323 2324 2325 2 2326 2327 2328 2329 2 2330 2331 // possibly other top-level nodes here 2333 6.5. Schema Node Identifier 2335 A schema node identifier is a string that identifies a node in the 2336 schema tree. It has two forms, "absolute" and "descendant", defined 2337 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 2338 in Section 14, respectively. A schema node identifier consists of a 2339 path of identifiers, separated by slashes ("/"). In an absolute 2340 schema node identifier, the first identifier after the leading slash 2341 is any top-level schema node in the local module or in an imported 2342 module. 2344 References to identifiers defined in external modules MUST be 2345 qualified with appropriate prefixes, and references to identifiers 2346 defined in the current module and its submodules MAY use a prefix. 2348 For example, to identify the child node "b" of top-level node "a", 2349 the string "/a/b" can be used. 2351 7. YANG Statements 2353 The following sections describe all of the YANG statements. 2355 Note that even a statement that does not have any substatements 2356 defined in YANG can have vendor-specific extensions as substatements. 2357 For example, the "description" statement does not have any 2358 substatements defined in YANG, but the following is legal: 2360 description "some text" { 2361 ex:documentation-flag 5; 2362 } 2364 7.1. The module Statement 2366 The "module" statement defines the module's name, and groups all 2367 statements that belong to the module together. The "module" 2368 statement's argument is the name of the module, followed by a block 2369 of substatements that hold detailed module information. The module 2370 name is an identifier (see Section 6.2). 2372 Names of modules published in RFC streams [RFC4844] MUST be assigned 2373 by IANA, see section 14 in [RFC6020]. 2375 Private module names are assigned by the organization owning the 2376 module without a central registry. See Section 5.1 for 2377 recommendations on how to name modules. 2379 A module typically has the following layout: 2381 module { 2383 // header information 2384 2385 2386 2388 // linkage statements 2389 2390 2392 // meta information 2393 2394 2395 2396 2398 // revision history 2399 2401 // module definitions 2402 2403 } 2405 7.1.1. The module's Substatements 2406 +--------------+---------+-------------+ 2407 | substatement | section | cardinality | 2408 +--------------+---------+-------------+ 2409 | anydata | 7.10 | 0..n | 2410 | anyxml | 7.11 | 0..n | 2411 | augment | 7.17 | 0..n | 2412 | choice | 7.9 | 0..n | 2413 | contact | 7.1.8 | 0..1 | 2414 | container | 7.5 | 0..n | 2415 | description | 7.21.3 | 0..1 | 2416 | deviation | 7.20.3 | 0..n | 2417 | extension | 7.19 | 0..n | 2418 | feature | 7.20.1 | 0..n | 2419 | grouping | 7.12 | 0..n | 2420 | identity | 7.18 | 0..n | 2421 | import | 7.1.5 | 0..n | 2422 | include | 7.1.6 | 0..n | 2423 | leaf | 7.6 | 0..n | 2424 | leaf-list | 7.7 | 0..n | 2425 | list | 7.8 | 0..n | 2426 | namespace | 7.1.3 | 1 | 2427 | notification | 7.16 | 0..n | 2428 | organization | 7.1.7 | 0..1 | 2429 | prefix | 7.1.4 | 1 | 2430 | reference | 7.21.4 | 0..1 | 2431 | revision | 7.1.9 | 0..n | 2432 | rpc | 7.14 | 0..n | 2433 | typedef | 7.3 | 0..n | 2434 | uses | 7.13 | 0..n | 2435 | yang-version | 7.1.2 | 1 | 2436 +--------------+---------+-------------+ 2438 7.1.2. The yang-version Statement 2440 The "yang-version" statement specifies which version of the YANG 2441 language was used in developing the module. The statement's argument 2442 is a string. It MUST contain the value "1.1" for YANG modules 2443 defined based on this specification. 2445 A module or submodule that doesn't contain the "yang-version" 2446 statement, or one that contains the value "1", is developed for YANG 2447 version 1, defined in [RFC6020]. 2449 Handling of the "yang-version" statement for versions other than 2450 "1.1" (the version defined here) is out of scope for this 2451 specification. Any document that defines a higher version will need 2452 to define the backward compatibility of such a higher version. 2454 For compatibility between YANG version 1 and 1.1, see Section 12. 2456 7.1.3. The namespace Statement 2458 The "namespace" statement defines the XML namespace that all 2459 identifiers defined by the module are qualified by in the XML 2460 encoding, with the exception of identifiers for data nodes, action 2461 nodes, and notification nodes defined inside a grouping (see 2462 Section 7.13 for details). The argument to the "namespace" statement 2463 is the URI of the namespace. 2465 See also Section 5.3. 2467 7.1.4. The prefix Statement 2469 The "prefix" statement is used to define the prefix associated with 2470 the module and its namespace. The "prefix" statement's argument is 2471 the prefix string that is used as a prefix to access a module. The 2472 prefix string MAY be used with the module to refer to definitions 2473 contained in the module, e.g., "if:ifName". A prefix is an 2474 identifier (see Section 6.2). 2476 When used inside the "module" statement, the "prefix" statement 2477 defines the prefix suggested to be used when this module is imported. 2479 To improve readability of the NETCONF XML, a NETCONF client or server 2480 that generates XML or XPath that use prefixes SHOULD use the prefix 2481 defined by the module as the XML namespace prefix, unless there is a 2482 conflict. 2484 When used inside the "import" statement, the "prefix" statement 2485 defines the prefix to be used when accessing definitions inside the 2486 imported module. When a reference to an identifier from the imported 2487 module is used, the prefix string for the imported module followed by 2488 a colon (":") and the identifier is used, e.g., "if:ifIndex". To 2489 improve readability of YANG modules, the prefix defined by a module 2490 SHOULD be used when the module is imported, unless there is a 2491 conflict. If there is a conflict, i.e., two different modules that 2492 both have defined the same prefix are imported, at least one of them 2493 MUST be imported with a different prefix. 2495 All prefixes, including the prefix for the module itself MUST be 2496 unique within the module or submodule. 2498 7.1.5. The import Statement 2500 The "import" statement makes definitions from one module available 2501 inside another module or submodule. The argument is the name of the 2502 module to import, and the statement is followed by a block of 2503 substatements that holds detailed import information. When a module 2504 is imported, the importing module may: 2506 o use any grouping and typedef defined at the top level in the 2507 imported module or its submodules. 2509 o use any extension, feature, and identity defined in the imported 2510 module or its submodules. 2512 o use any node in the imported module's schema tree in "must", 2513 "path", and "when" statements, or as the target node in "augment" 2514 and "deviation" statements. 2516 The mandatory "prefix" substatement assigns a prefix for the imported 2517 module that is scoped to the importing module or submodule. Multiple 2518 "import" statements may be specified to import from different 2519 modules. 2521 When the optional "revision-date" substatement is present, any 2522 typedef, grouping, extension, feature, and identity referenced by 2523 definitions in the local module are taken from the specified revision 2524 of the imported module. It is an error if the specified revision of 2525 the imported module does not exist. If no "revision-date" 2526 substatement is present, it is undefined from which revision of the 2527 module they are taken. 2529 Multiple revisions of the same module can be imported, provided that 2530 different prefixes are used. 2532 +---------------+---------+-------------+ 2533 | substatement | section | cardinality | 2534 +---------------+---------+-------------+ 2535 | prefix | 7.1.4 | 1 | 2536 | revision-date | 7.1.5.1 | 0..1 | 2537 | description | 7.21.3 | 0..1 | 2538 | reference | 7.21.4 | 0..1 | 2539 +---------------+---------+-------------+ 2541 The import's Substatements 2543 7.1.5.1. The import's revision-date Statement 2545 The import's "revision-date" statement is used to specify the version 2546 of the module to import. 2548 7.1.6. The include Statement 2550 The "include" statement is used to make content from a submodule 2551 available to that submodule's parent module. The argument is an 2552 identifier that is the name of the submodule to include. Modules are 2553 only allowed to include submodules that belong to that module, as 2554 defined by the "belongs-to" statement (see Section 7.2.2). 2556 When a module includes a submodule, it incorporates the contents of 2557 the submodule into the node hierarchy of the module. 2559 For backward compatibility with YANG version 1, a submodule is 2560 allowed to include another submodule belonging to the same module, 2561 but this is not necessary in YANG version 1.1 (see Section 5.1). 2563 When the optional "revision-date" substatement is present, the 2564 specified revision of the submodule is included in the module. It is 2565 an error if the specified revision of the submodule does not exist. 2566 If no "revision-date" substatement is present, it is undefined which 2567 revision of the submodule is included. 2569 Multiple revisions of the same submodule MUST NOT be included. 2571 +---------------+---------+-------------+ 2572 | substatement | section | cardinality | 2573 +---------------+---------+-------------+ 2574 | revision-date | 7.1.5.1 | 0..1 | 2575 | description | 7.21.3 | 0..1 | 2576 | reference | 7.21.4 | 0..1 | 2577 +---------------+---------+-------------+ 2579 The includes's Substatements 2581 7.1.7. The organization Statement 2583 The "organization" statement defines the party responsible for this 2584 module. The argument is a string that is used to specify a textual 2585 description of the organization(s) under whose auspices this module 2586 was developed. 2588 7.1.8. The contact Statement 2590 The "contact" statement provides contact information for the module. 2591 The argument is a string that is used to specify contact information 2592 for the person or persons to whom technical queries concerning this 2593 module should be sent, such as their name, postal address, telephone 2594 number, and electronic mail address. 2596 7.1.9. The revision Statement 2598 The "revision" statement specifies the editorial revision history of 2599 the module, including the initial revision. A series of revision 2600 statements detail the changes in the module's definition. The 2601 argument is a date string in the format "YYYY-MM-DD", followed by a 2602 block of substatements that holds detailed revision information. A 2603 module SHOULD have at least one "revision" statement. For every 2604 published editorial change, a new one SHOULD be added in front of the 2605 revisions sequence, so that all revisions are in reverse 2606 chronological order. 2608 7.1.9.1. The revision's Substatement 2610 +--------------+---------+-------------+ 2611 | substatement | section | cardinality | 2612 +--------------+---------+-------------+ 2613 | description | 7.21.3 | 0..1 | 2614 | reference | 7.21.4 | 0..1 | 2615 +--------------+---------+-------------+ 2617 7.1.10. Usage Example 2618 module example-system { 2619 yang-version 1.1; 2620 namespace "urn:example:system"; 2621 prefix "sys"; 2623 import ietf-yang-types { 2624 prefix "yang"; 2625 reference "RFC 6991: Common YANG Data Types"; 2626 } 2628 include example-types; 2630 organization "Example Inc."; 2631 contact 2632 "Joe L. User 2634 Example Inc. 2635 42 Anywhere Drive 2636 Nowhere, CA 95134 2637 USA 2639 Phone: +1 800 555 0100 2640 EMail: joe@example.com"; 2642 description 2643 "The module for entities implementing the Example system."; 2645 revision 2007-06-09 { 2646 description "Initial revision."; 2647 } 2649 // definitions follow... 2650 } 2652 7.2. The submodule Statement 2654 While the primary unit in YANG is a module, a YANG module can itself 2655 be constructed out of several submodules. Submodules allow a module 2656 designer to split a complex model into several pieces where all the 2657 submodules contribute to a single namespace, which is defined by the 2658 module that includes the submodules. 2660 The "submodule" statement defines the submodule's name, and groups 2661 all statements that belong to the submodule together. The 2662 "submodule" statement's argument is the name of the submodule, 2663 followed by a block of substatements that hold detailed submodule 2664 information. The submodule name is an identifier (see Section 6.2). 2666 Names of submodules published in RFC streams [RFC4844] MUST be 2667 assigned by IANA, see section 14 in [RFC6020]. 2669 Private submodule names are assigned by the organization owning the 2670 submodule without a central registry. See Section 5.1 for 2671 recommendations on how to name submodules. 2673 A submodule typically has the following layout: 2675 submodule { 2677 2679 // module identification 2680 2682 // linkage statements 2683 2685 // meta information 2686 2687 2688 2689 2691 // revision history 2692 2694 // module definitions 2695 2696 } 2698 7.2.1. The submodule's Substatements 2699 +--------------+---------+-------------+ 2700 | substatement | section | cardinality | 2701 +--------------+---------+-------------+ 2702 | anydata | 7.10 | 0..n | 2703 | anyxml | 7.11 | 0..n | 2704 | augment | 7.17 | 0..n | 2705 | belongs-to | 7.2.2 | 1 | 2706 | choice | 7.9 | 0..n | 2707 | contact | 7.1.8 | 0..1 | 2708 | container | 7.5 | 0..n | 2709 | description | 7.21.3 | 0..1 | 2710 | deviation | 7.20.3 | 0..n | 2711 | extension | 7.19 | 0..n | 2712 | feature | 7.20.1 | 0..n | 2713 | grouping | 7.12 | 0..n | 2714 | identity | 7.18 | 0..n | 2715 | import | 7.1.5 | 0..n | 2716 | include | 7.1.6 | 0..n | 2717 | leaf | 7.6 | 0..n | 2718 | leaf-list | 7.7 | 0..n | 2719 | list | 7.8 | 0..n | 2720 | notification | 7.16 | 0..n | 2721 | organization | 7.1.7 | 0..1 | 2722 | reference | 7.21.4 | 0..1 | 2723 | revision | 7.1.9 | 0..n | 2724 | rpc | 7.14 | 0..n | 2725 | typedef | 7.3 | 0..n | 2726 | uses | 7.13 | 0..n | 2727 | yang-version | 7.1.2 | 1 | 2728 +--------------+---------+-------------+ 2730 7.2.2. The belongs-to Statement 2732 The "belongs-to" statement specifies the module to which the 2733 submodule belongs. The argument is an identifier that is the name of 2734 the module. 2736 A submodule MUST only be included by the module to which it belongs, 2737 or by another submodule that belongs to that module. 2739 The mandatory "prefix" substatement assigns a prefix for the module 2740 to which the submodule belongs. All definitions in the module that 2741 the submodule belongs to and all its submodules can be accessed by 2742 using the prefix. 2744 +--------------+---------+-------------+ 2745 | substatement | section | cardinality | 2746 +--------------+---------+-------------+ 2747 | prefix | 7.1.4 | 1 | 2748 +--------------+---------+-------------+ 2750 The belongs-to's Substatements 2752 7.2.3. Usage Example 2754 submodule example-types { 2755 yang-version 1.1; 2756 belongs-to "example-system" { 2757 prefix "sys"; 2758 } 2760 import ietf-yang-types { 2761 prefix "yang"; 2762 } 2764 organization "Example Inc."; 2765 contact 2766 "Joe L. User 2768 Example Inc. 2769 42 Anywhere Drive 2770 Nowhere, CA 95134 2771 USA 2773 Phone: +1 800 555 0100 2774 EMail: joe@example.com"; 2776 description 2777 "This submodule defines common Example types."; 2779 revision "2007-06-09" { 2780 description "Initial revision."; 2781 } 2783 // definitions follows... 2784 } 2786 7.3. The typedef Statement 2788 The "typedef" statement defines a new type that may be used locally 2789 in the module or submodule, and by other modules that import from it, 2790 according to the rules in Section 5.5. The new type is called the 2791 "derived type", and the type from which it was derived is called the 2792 "base type". All derived types can be traced back to a YANG built-in 2793 type. 2795 The "typedef" statement's argument is an identifier that is the name 2796 of the type to be defined, and MUST be followed by a block of 2797 substatements that holds detailed typedef information. 2799 The name of the type MUST NOT be one of the YANG built-in types. If 2800 the typedef is defined at the top level of a YANG module or 2801 submodule, the name of the type to be defined MUST be unique within 2802 the module. 2804 7.3.1. The typedef's Substatements 2806 +--------------+---------+-------------+ 2807 | substatement | section | cardinality | 2808 +--------------+---------+-------------+ 2809 | default | 7.3.4 | 0..1 | 2810 | description | 7.21.3 | 0..1 | 2811 | reference | 7.21.4 | 0..1 | 2812 | status | 7.21.2 | 0..1 | 2813 | type | 7.3.2 | 1 | 2814 | units | 7.3.3 | 0..1 | 2815 +--------------+---------+-------------+ 2817 7.3.2. The typedef's type Statement 2819 The "type" statement, which MUST be present, defines the base type 2820 from which this type is derived. See Section 7.4 for details. 2822 7.3.3. The units Statement 2824 The "units" statement, which is optional, takes as an argument a 2825 string that contains a textual definition of the units associated 2826 with the type. 2828 7.3.4. The typedef's default Statement 2830 The "default" statement takes as an argument a string that contains a 2831 default value for the new type. 2833 The value of the "default" statement MUST be valid according to the 2834 type specified in the "type" statement. 2836 If the base type has a default value, and the new derived type does 2837 not specify a new default value, the base type's default value is 2838 also the default value of the new derived type. 2840 If the type's default value is not valid according to the new 2841 restrictions specified in a derived type or leaf definition, the 2842 derived type or leaf definition MUST specify a new default value 2843 compatible with the restrictions. 2845 7.3.5. Usage Example 2847 typedef listen-ipv4-address { 2848 type inet:ipv4-address; 2849 default "0.0.0.0"; 2850 } 2852 7.4. The type Statement 2854 The "type" statement takes as an argument a string that is the name 2855 of a YANG built-in type (see Section 9) or a derived type (see 2856 Section 7.3), followed by an optional block of substatements that are 2857 used to put further restrictions on the type. 2859 The restrictions that can be applied depend on the type being 2860 restricted. The restriction statements for all built-in types are 2861 described in the subsections of Section 9. 2863 7.4.1. The type's Substatements 2865 +------------------+---------+-------------+ 2866 | substatement | section | cardinality | 2867 +------------------+---------+-------------+ 2868 | base | 7.18.2 | 0..n | 2869 | bit | 9.7.4 | 0..n | 2870 | enum | 9.6.4 | 0..n | 2871 | fraction-digits | 9.3.4 | 0..1 | 2872 | length | 9.4.4 | 0..1 | 2873 | path | 9.9.2 | 0..1 | 2874 | pattern | 9.4.5 | 0..n | 2875 | range | 9.2.4 | 0..1 | 2876 | require-instance | 9.9.3 | 0..1 | 2877 | type | 7.4 | 0..n | 2878 +------------------+---------+-------------+ 2880 7.5. The container Statement 2882 The "container" statement is used to define an interior data node in 2883 the schema tree. It takes one argument, which is an identifier, 2884 followed by a block of substatements that holds detailed container 2885 information. 2887 A container node does not have a value, but it has a list of child 2888 nodes in the data tree. The child nodes are defined in the 2889 container's substatements. 2891 7.5.1. Containers with Presence 2893 YANG supports two styles of containers, those that exist only for 2894 organizing the hierarchy of data nodes, and those whose presence in 2895 the data tree has an explicit meaning. 2897 In the first style, the container has no meaning of its own, existing 2898 only to contain child nodes. In particular, the presence of the 2899 container node with no child nodes is semantically equivalent to the 2900 absence of the container node. YANG calls this style a "non-presence 2901 container". This is the default style. 2903 For example, the set of scrambling options for Synchronous Optical 2904 Network (SONET) interfaces may be placed inside a "scrambling" 2905 container to enhance the organization of the configuration hierarchy, 2906 and to keep these nodes together. The "scrambling" node itself has 2907 no meaning, so removing the node when it becomes empty relieves the 2908 user from performing this task. 2910 In the second style, the presence of the container itself carries 2911 some meaning, representing a single bit of data. 2913 For configuration data, the container acts as both a configuration 2914 knob and a means of organizing related configuration. These 2915 containers are explicitly created and deleted. 2917 YANG calls this style a "presence container" and it is indicated 2918 using the "presence" statement, which takes as its argument a text 2919 string indicating what the presence of the node means. 2921 For example, an "ssh" container may turn on the ability to log into 2922 the server using ssh, but can also contain any ssh-related 2923 configuration knobs, such as connection rates or retry limits. 2925 The "presence" statement (see Section 7.5.5) is used to give 2926 semantics to the existence of the container in the data tree. 2928 7.5.2. The container's Substatements 2929 +--------------+---------+-------------+ 2930 | substatement | section | cardinality | 2931 +--------------+---------+-------------+ 2932 | action | 7.15 | 0..n | 2933 | anydata | 7.10 | 0..n | 2934 | anyxml | 7.11 | 0..n | 2935 | choice | 7.9 | 0..n | 2936 | config | 7.21.1 | 0..1 | 2937 | container | 7.5 | 0..n | 2938 | description | 7.21.3 | 0..1 | 2939 | grouping | 7.12 | 0..n | 2940 | if-feature | 7.20.2 | 0..n | 2941 | leaf | 7.6 | 0..n | 2942 | leaf-list | 7.7 | 0..n | 2943 | list | 7.8 | 0..n | 2944 | must | 7.5.3 | 0..n | 2945 | notification | 7.16 | 0..n | 2946 | presence | 7.5.5 | 0..1 | 2947 | reference | 7.21.4 | 0..1 | 2948 | status | 7.21.2 | 0..1 | 2949 | typedef | 7.3 | 0..n | 2950 | uses | 7.13 | 0..n | 2951 | when | 7.21.5 | 0..1 | 2952 +--------------+---------+-------------+ 2954 7.5.3. The must Statement 2956 The "must" statement, which is optional, takes as an argument a 2957 string that contains an XPath expression (see Section 6.4). It is 2958 used to formally declare a constraint on valid data. The constraint 2959 is enforced according to the rules in Section 8. 2961 When a datastore is validated, all "must" constraints are 2962 conceptually evaluated once for each node in the accessible tree (see 2963 Section 6.4.1). 2965 All such constraints MUST evaluate to "true" for the data to be 2966 valid. 2968 The XPath expression is conceptually evaluated in the following 2969 context, in addition to the definition in Section 6.4.1: 2971 o The context node is the node in the accessible tree for which the 2972 "must" statement is defined. 2974 The result of the XPath expression is converted to a boolean value 2975 using the standard XPath rules. 2977 Note that since all leaf values in the data tree are conceptually 2978 stored in their canonical form (see Section 9.1), any XPath 2979 comparisons are done on the canonical value. 2981 Also note that the XPath expression is conceptually evaluated. This 2982 means that an implementation does not have to use an XPath evaluator 2983 in the server. How the evaluation is done in practice is an 2984 implementation decision. 2986 7.5.4. The must's Substatements 2988 +---------------+---------+-------------+ 2989 | substatement | section | cardinality | 2990 +---------------+---------+-------------+ 2991 | description | 7.21.3 | 0..1 | 2992 | error-app-tag | 7.5.4.2 | 0..1 | 2993 | error-message | 7.5.4.1 | 0..1 | 2994 | reference | 7.21.4 | 0..1 | 2995 +---------------+---------+-------------+ 2997 7.5.4.1. The error-message Statement 2999 The "error-message" statement, which is optional, takes a string as 3000 an argument. If the constraint evaluates to "false", the string is 3001 passed as in the in NETCONF. 3003 7.5.4.2. The error-app-tag Statement 3005 The "error-app-tag" statement, which is optional, takes a string as 3006 an argument. If the constraint evaluates to "false", the string is 3007 passed as in the in NETCONF. 3009 7.5.4.3. Usage Example of must and error-message 3010 container interface { 3011 leaf ifType { 3012 type enumeration { 3013 enum ethernet; 3014 enum atm; 3015 } 3016 } 3017 leaf ifMTU { 3018 type uint32; 3019 } 3020 must 'ifType != "ethernet" or ifMTU = 1500' { 3021 error-message "An ethernet MTU must be 1500"; 3022 } 3023 must 'ifType != "atm" or' 3024 + ' (ifMTU <= 17966 and ifMTU >= 64)' { 3025 error-message "An atm MTU must be 64 .. 17966"; 3026 } 3027 } 3029 7.5.5. The presence Statement 3031 The "presence" statement assigns a meaning to the presence of a 3032 container in the data tree. It takes as an argument a string that 3033 contains a textual description of what the node's presence means. 3035 If a container has the "presence" statement, the container's 3036 existence in the data tree carries some meaning. Otherwise, the 3037 container is used to give some structure to the data, and it carries 3038 no meaning by itself. 3040 See Section 7.5.1 for additional information. 3042 7.5.6. The container's Child Node Statements 3044 Within a container, the "container", "leaf", "list", "leaf-list", 3045 "uses", "choice", "anydata", and "anyxml" statements can be used to 3046 define child nodes to the container. 3048 7.5.7. XML Encoding Rules 3050 A container node is encoded as an XML element. The element's local 3051 name is the container's identifier, and its namespace is the module's 3052 XML namespace (see Section 7.1.3). 3054 The container's child nodes are encoded as subelements to the 3055 container element. If the container defines RPC or action input or 3056 output parameters, these subelements are encoded in the same order as 3057 they are defined within the "container" statement. Otherwise, the 3058 subelements are encoded in any order. 3060 Any whitespace between the subelements to the container is 3061 insignificant, i.e., an implementation MAY insert whitespace 3062 characters between subelements. 3064 If a non-presence container does not have any child nodes, the 3065 container may or may not be present in the XML encoding. 3067 7.5.8. NETCONF Operations 3069 Containers can be created, deleted, replaced, and modified through 3070 , by using the "operation" attribute (see [RFC6241], 3071 Section 7.2) in the container's XML element. 3073 If a container does not have a "presence" statement and the last 3074 child node is deleted, the NETCONF server MAY delete the container. 3076 When a NETCONF server processes an request, the 3077 elements of procedure for the container node are: 3079 If the operation is "merge" or "replace", the node is created if 3080 it does not exist. 3082 If the operation is "create", the node is created if it does not 3083 exist. If the node already exists, a "data-exists" error is 3084 returned. 3086 If the operation is "delete", the node is deleted if it exists. 3087 If the node does not exist, a "data-missing" error is returned. 3089 7.5.9. Usage Example 3091 Given the following container definition: 3093 container system { 3094 description 3095 "Contains various system parameters"; 3096 container services { 3097 description 3098 "Configure externally available services"; 3099 container "ssh" { 3100 presence "Enables SSH"; 3101 description 3102 "SSH service specific configuration"; 3103 // more leafs, containers and stuff here... 3104 } 3105 } 3106 } 3108 A corresponding XML instance example: 3110 3111 3112 3113 3114 3116 Since the element is present, ssh is enabled. 3118 To delete a container with an : 3120 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3137 7.6. The leaf Statement 3139 The "leaf" statement is used to define a leaf node in the schema 3140 tree. It takes one argument, which is an identifier, followed by a 3141 block of substatements that holds detailed leaf information. 3143 A leaf node has a value, but no child nodes in the data tree. 3144 Conceptually, the value in the data tree is always in the canonical 3145 form (see Section 9.1). 3147 A leaf node exists in zero or one instances in the data tree. 3149 The "leaf" statement is used to define a scalar variable of a 3150 particular built-in or derived type. 3152 7.6.1. The leaf's default value 3154 The default value of a leaf is the value that the server uses if the 3155 leaf does not exist in the data tree. The usage of the default value 3156 depends on the leaf's closest ancestor node in the schema tree that 3157 is not a non-presence container (see Section 7.5.1): 3159 o If no such ancestor exists in the schema tree, the default value 3160 MUST be used. 3162 o Otherwise, if this ancestor is a case node, the default value MUST 3163 be used if any node from the case exists in the data tree, or if 3164 the case node is the choice's default case, and no nodes from any 3165 other case exist in the data tree. 3167 o Otherwise, the default value MUST be used if the ancestor node 3168 exists in the data tree. 3170 In these cases, the default value is said to be in use. 3172 Note that if the leaf or any of its ancestors has a "when" condition 3173 or "if-feature" expression that evaluates to "false", then the 3174 default value is not in use. 3176 When the default value is in use, the server MUST operationally 3177 behave as if the leaf was present in the data tree with the default 3178 value as its value. 3180 If a leaf has a "default" statement, the leaf's default value is the 3181 value of the "default" statement. Otherwise, if the leaf's type has 3182 a default value, and the leaf is not mandatory, then the leaf's 3183 default value is the type's default value. In all other cases, the 3184 leaf does not have a default value. 3186 7.6.2. The leaf's Substatements 3188 +--------------+---------+-------------+ 3189 | substatement | section | cardinality | 3190 +--------------+---------+-------------+ 3191 | config | 7.21.1 | 0..1 | 3192 | default | 7.6.4 | 0..1 | 3193 | description | 7.21.3 | 0..1 | 3194 | if-feature | 7.20.2 | 0..n | 3195 | mandatory | 7.6.5 | 0..1 | 3196 | must | 7.5.3 | 0..n | 3197 | reference | 7.21.4 | 0..1 | 3198 | status | 7.21.2 | 0..1 | 3199 | type | 7.6.3 | 1 | 3200 | units | 7.3.3 | 0..1 | 3201 | when | 7.21.5 | 0..1 | 3202 +--------------+---------+-------------+ 3204 7.6.3. The leaf's type Statement 3206 The "type" statement, which MUST be present, takes as an argument the 3207 name of an existing built-in or derived type. The optional 3208 substatements specify restrictions on this type. See Section 7.4 for 3209 details. 3211 7.6.4. The leaf's default Statement 3213 The "default" statement, which is optional, takes as an argument a 3214 string that contains a default value for the leaf. 3216 The value of the "default" statement MUST be valid according to the 3217 type specified in the leaf's "type" statement. 3219 The "default" statement MUST NOT be present on nodes where 3220 "mandatory" is "true". 3222 The definition of the default value MUST NOT be marked with an 3223 "if-feature" statement. For example, the following is illegal: 3225 leaf color { 3226 type enumeration { 3227 enum blue { if-feature blue; } 3228 ... 3229 } 3230 default blue; // illegal - enum value is conditional 3231 } 3233 7.6.5. The leaf's mandatory Statement 3235 The "mandatory" statement, which is optional, takes as an argument 3236 the string "true" or "false", and puts a constraint on valid data. 3237 If not specified, the default is "false". 3239 If "mandatory" is "true", the behavior of the constraint depends on 3240 the type of the leaf's closest ancestor node in the schema tree that 3241 is not a non-presence container (see Section 7.5.1): 3243 o If no such ancestor exists in the schema tree, the leaf MUST 3244 exist. 3246 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 3247 any node from the case exists in the data tree. 3249 o Otherwise, the leaf MUST exist if the ancestor node exists in the 3250 data tree. 3252 This constraint is enforced according to the rules in Section 8. 3254 7.6.6. XML Encoding Rules 3256 A leaf node is encoded as an XML element. The element's local name 3257 is the leaf's identifier, and its namespace is the module's XML 3258 namespace (see Section 7.1.3). 3260 The value of the leaf node is encoded to XML according to the type, 3261 and sent as character data in the element. 3263 See Section 7.6.8 for an example. 3265 7.6.7. NETCONF Operations 3267 When a NETCONF server processes an request, the 3268 elements of procedure for the leaf node are: 3270 If the operation is "merge" or "replace", the node is created if 3271 it does not exist, and its value is set to the value found in the 3272 XML RPC data. 3274 If the operation is "create", the node is created if it does not 3275 exist. If the node already exists, a "data-exists" error is 3276 returned. 3278 If the operation is "delete", the node is deleted if it exists. 3279 If the node does not exist, a "data-missing" error is returned. 3281 7.6.8. Usage Example 3283 Given the following "leaf" statement, placed in the previously 3284 defined "ssh" container (see Section 7.5.9): 3286 leaf port { 3287 type inet:port-number; 3288 default 22; 3289 description 3290 "The port to which the SSH server listens" 3291 } 3293 A corresponding XML instance example: 3295 2022 3297 To set the value of a leaf with an : 3299 3302 3303 3304 3305 3306 3307 3308 3309 3310 2022 3311 3312 3313 3314 3315 3316 3318 7.7. The leaf-list Statement 3320 Where the "leaf" statement is used to define a simple scalar variable 3321 of a particular type, the "leaf-list" statement is used to define an 3322 array of a particular type. The "leaf-list" statement takes one 3323 argument, which is an identifier, followed by a block of 3324 substatements that holds detailed leaf-list information. 3326 In configuration data, the values in a leaf-list MUST be unique. 3328 The definitions of the default values MUST NOT be marked with an 3329 "if-feature" statement. 3331 Conceptually, the values in the data tree MUST be in the canonical 3332 form (see Section 9.1). 3334 7.7.1. Ordering 3336 YANG supports two styles for ordering the entries within lists and 3337 leaf-lists. In many lists, the order of list entries does not impact 3338 the implementation of the list's configuration, and the server is 3339 free to sort the list entries in any reasonable order. The 3340 "description" string for the list may suggest an order to the server 3341 implementor. YANG calls this style of list "system ordered" and they 3342 are indicated with the statement "ordered-by system". 3344 For example, a list of valid users would typically be sorted 3345 alphabetically, since the order in which the users appeared in the 3346 configuration would not impact the creation of those users' accounts. 3348 In the other style of lists, the order of list entries matters for 3349 the implementation of the list's configuration and the user is 3350 responsible for ordering the entries, while the server maintains that 3351 order. YANG calls this style of list "user ordered" and they are 3352 indicated with the statement "ordered-by user". 3354 For example, the order in which packet filters entries are applied to 3355 incoming traffic may affect how that traffic is filtered. The user 3356 would need to decide if the filter entry that discards all TCP 3357 traffic should be applied before or after the filter entry that 3358 allows all traffic from trusted interfaces. The choice of order 3359 would be crucial. 3361 YANG provides a rich set of facilities within NETCONF's 3362 operation that allows the order of list entries in user-ordered lists 3363 to be controlled. List entries may be inserted or rearranged, 3364 positioned as the first or last entry in the list, or positioned 3365 before or after another specific entry. 3367 The "ordered-by" statement is covered in Section 7.7.7. 3369 7.7.2. The leaf-list's default values 3371 The default values of a leaf-list are the values that the server uses 3372 if the leaf-list does not exist in the data tree. The usage of the 3373 default values depends on the leaf-list's closest ancestor node in 3374 the schema tree that is not a non-presence container (see 3375 Section 7.5.1): 3377 o If no such ancestor exists in the schema tree, the default values 3378 MUST be used. 3380 o Otherwise, if this ancestor is a case node, the default values 3381 MUST be used if any node from the case exists in the data tree, or 3382 if the case node is the choice's default case, and no nodes from 3383 any other case exist in the data tree. 3385 o Otherwise, the default values MUST be used if the ancestor node 3386 exists in the data tree. 3388 In these cases, the default values are said to be in use. 3390 Note that if the leaf-list or any of its ancestors has a "when" 3391 condition or "if-feature" expression that evaluates to "false", then 3392 the default values are not in use. 3394 When the default values are in use, the server MUST operationally 3395 behave as if the leaf-list was present in the data tree with the 3396 default values as its values. 3398 If a leaf-list has one or more "default" statement, the leaf-list's 3399 default values are the values of the "default" statements, and if the 3400 leaf-list is user-ordered, the default values are used in the order 3401 of the "default" statements. Otherwise, if the leaf-list's type has 3402 a default value, and the leaf-list does not have a "min-elements" 3403 statement with a value greater than or equal to one, then the leaf- 3404 list's default value is one instance of the type's default value. In 3405 all other cases, the leaf-list does not have any default values. 3407 7.7.3. The leaf-list's Substatements 3408 +--------------+---------+-------------+ 3409 | substatement | section | cardinality | 3410 +--------------+---------+-------------+ 3411 | config | 7.21.1 | 0..1 | 3412 | default | 7.7.4 | 0..n | 3413 | description | 7.21.3 | 0..1 | 3414 | if-feature | 7.20.2 | 0..n | 3415 | max-elements | 7.7.6 | 0..1 | 3416 | min-elements | 7.7.5 | 0..1 | 3417 | must | 7.5.3 | 0..n | 3418 | ordered-by | 7.7.7 | 0..1 | 3419 | reference | 7.21.4 | 0..1 | 3420 | status | 7.21.2 | 0..1 | 3421 | type | 7.4 | 1 | 3422 | units | 7.3.3 | 0..1 | 3423 | when | 7.21.5 | 0..1 | 3424 +--------------+---------+-------------+ 3426 7.7.4. The leaf-list's default Statement 3428 The "default" statement, which is optional, takes as an argument a 3429 string that contains a default value for the leaf-list. 3431 The value of the "default" statement MUST be valid according to the 3432 type specified in the leaf-list's "type" statement. 3434 The "default" statement MUST NOT be present on nodes where 3435 "min-elements" has a value greater than or equal to one. 3437 7.7.5. The min-elements Statement 3439 The "min-elements" statement, which is optional, takes as an argument 3440 a non-negative integer that puts a constraint on valid list entries. 3441 A valid leaf-list or list MUST have at least min-elements entries. 3443 If no "min-elements" statement is present, it defaults to zero. 3445 The behavior of the constraint depends on the type of the leaf-list's 3446 or list's closest ancestor node in the schema tree that is not a non- 3447 presence container (see Section 7.5.1): 3449 o If no such ancestor exists in the schema tree, the constraint is 3450 enforced. 3452 o Otherwise, if this ancestor is a case node, the constraint is 3453 enforced if any other node from the case exists. 3455 o Otherwise, it is enforced if the ancestor node exists. 3457 The constraint is further enforced according to the rules in 3458 Section 8. 3460 7.7.6. The max-elements Statement 3462 The "max-elements" statement, which is optional, takes as an argument 3463 a positive integer or the string "unbounded", which puts a constraint 3464 on valid list entries. A valid leaf-list or list always has at most 3465 max-elements entries. 3467 If no "max-elements" statement is present, it defaults to 3468 "unbounded". 3470 The "max-elements" constraint is enforced according to the rules in 3471 Section 8. 3473 7.7.7. The ordered-by Statement 3475 The "ordered-by" statement defines whether the order of entries 3476 within a list are determined by the user or the system. The argument 3477 is one of the strings "system" or "user". If not present, order 3478 defaults to "system". 3480 This statement is ignored if the list represents state data, RPC 3481 output parameters, or notification content. 3483 See Section 7.7.1 for additional information. 3485 7.7.7.1. ordered-by system 3487 The entries in the list are ordered according to an order determined 3488 by the system. The "description" string for the list may suggest an 3489 order to the server implementor. If not, an implementation is free 3490 to order the entries in any order. An implementation SHOULD use the 3491 same order for the same data, regardless of how the data were 3492 created. Using a deterministic order will make comparisons possible 3493 using simple tools like "diff". 3495 This is the default order. 3497 7.7.7.2. ordered-by user 3499 The entries in the list are ordered according to an order defined by 3500 the user. In NETCONF, this order is controlled by using special XML 3501 attributes in the request. See Section 7.7.9 for 3502 details. 3504 7.7.8. XML Encoding Rules 3506 A leaf-list node is encoded as a series of XML elements. Each 3507 element's local name is the leaf-list's identifier, and its namespace 3508 is the module's XML namespace (see Section 7.1.3). 3510 The value of each leaf-list entry is encoded to XML according to the 3511 type, and sent as character data in the element. 3513 The XML elements representing leaf-list entries MUST appear in the 3514 order specified by the user if the leaf-list is "ordered-by user"; 3515 otherwise, the order is implementation-dependent. The XML elements 3516 representing leaf-list entries MAY be interleaved with elements for 3517 siblings of the leaf-list, unless the leaf-list defines RPC or action 3518 input or output parameters. 3520 See Section 7.7.10 for an example. 3522 7.7.9. NETCONF Operations 3524 Leaf-list entries can be created and deleted, but not modified, 3525 through , by using the "operation" attribute in the 3526 leaf-list entry's XML element. 3528 In an "ordered-by user" leaf-list, the attributes "insert" and 3529 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3530 control where in the leaf-list the entry is inserted. These can be 3531 used during "create" operations to insert a new leaf-list entry, or 3532 during "merge" or "replace" operations to insert a new leaf-list 3533 entry or move an existing one. 3535 The "insert" attribute can take the values "first", "last", "before", 3536 and "after". If the value is "before" or "after", the "value" 3537 attribute MUST also be used to specify an existing entry in the leaf- 3538 list. 3540 If no "insert" attribute is present in the "create" operation, it 3541 defaults to "last". 3543 If several entries in an "ordered-by user" leaf-list are modified in 3544 the same request, the entries are modified one at the 3545 time, in the order of the XML elements in the request. 3547 In a , or an with a "replace" operation 3548 that covers the entire leaf-list, the leaf-list order is the same as 3549 the order of the XML elements in the request. 3551 When a NETCONF server processes an request, the 3552 elements of procedure for a leaf-list node are: 3554 If the operation is "merge" or "replace", the leaf-list entry is 3555 created if it does not exist. 3557 If the operation is "create", the leaf-list entry is created if it 3558 does not exist. If the leaf-list entry already exists, a 3559 "data-exists" error is returned. 3561 If the operation is "delete", the entry is deleted from the leaf- 3562 list if it exists. If the leaf-list entry does not exist, a 3563 "data-missing" error is returned. 3565 7.7.10. Usage Example 3567 leaf-list allow-user { 3568 type string; 3569 description 3570 "A list of user name patterns to allow"; 3571 } 3573 A corresponding XML instance example: 3575 alice 3576 bob 3578 To create a new element in this list, using the default 3579 operation "merge": 3581 3584 3585 3586 3587 3588 3589 3590 3591 3592 eric 3593 3594 3595 3596 3597 3598 3600 Given the following ordered-by user leaf-list: 3602 leaf-list cipher { 3603 type string; 3604 ordered-by user; 3605 description 3606 "A list of ciphers"; 3607 } 3609 The following would be used to insert a new cipher "blowfish-cbc" 3610 after "3des-cbc": 3612 3616 3617 3618 3619 3620 3621 3622 3623 3624 blowfish-cbc 3627 3628 3629 3630 3631 3632 3634 7.8. The list Statement 3636 The "list" statement is used to define an interior data node in the 3637 schema tree. A list node may exist in multiple instances in the data 3638 tree. Each such instance is known as a list entry. The "list" 3639 statement takes one argument, which is an identifier, followed by a 3640 block of substatements that holds detailed list information. 3642 A list entry is uniquely identified by the values of the list's keys, 3643 if defined. 3645 7.8.1. The list's Substatements 3647 +--------------+---------+-------------+ 3648 | substatement | section | cardinality | 3649 +--------------+---------+-------------+ 3650 | action | 7.15 | 0..n | 3651 | anydata | 7.10 | 0..n | 3652 | anyxml | 7.11 | 0..n | 3653 | choice | 7.9 | 0..n | 3654 | config | 7.21.1 | 0..1 | 3655 | container | 7.5 | 0..n | 3656 | description | 7.21.3 | 0..1 | 3657 | grouping | 7.12 | 0..n | 3658 | if-feature | 7.20.2 | 0..n | 3659 | key | 7.8.2 | 0..1 | 3660 | leaf | 7.6 | 0..n | 3661 | leaf-list | 7.7 | 0..n | 3662 | list | 7.8 | 0..n | 3663 | max-elements | 7.7.6 | 0..1 | 3664 | min-elements | 7.7.5 | 0..1 | 3665 | must | 7.5.3 | 0..n | 3666 | notification | 7.16 | 0..n | 3667 | ordered-by | 7.7.7 | 0..1 | 3668 | reference | 7.21.4 | 0..1 | 3669 | status | 7.21.2 | 0..1 | 3670 | typedef | 7.3 | 0..n | 3671 | unique | 7.8.3 | 0..n | 3672 | uses | 7.13 | 0..n | 3673 | when | 7.21.5 | 0..1 | 3674 +--------------+---------+-------------+ 3676 7.8.2. The list's key Statement 3678 The "key" statement, which MUST be present if the list represents 3679 configuration, and MAY be present otherwise, takes as an argument a 3680 string that specifies a space-separated list of one or more leaf 3681 identifiers of this list. A leaf identifier MUST NOT appear more 3682 than once in the key. Each such leaf identifier MUST refer to a 3683 child leaf of the list. The leafs can be defined directly in 3684 substatements to the list, or in groupings used in the list. 3686 The combined values of all the leafs specified in the key are used to 3687 uniquely identify a list entry. All key leafs MUST be given values 3688 when a list entry is created. Thus, any default values in the key 3689 leafs or their types are ignored. It also implies that any mandatory 3690 statement in the key leafs are ignored. 3692 A leaf that is part of the key can be of any built-in or derived 3693 type. 3695 All key leafs in a list MUST have the same value for their "config" 3696 as the list itself. 3698 The key string syntax is formally defined by the rule "key-arg" in 3699 Section 14. 3701 7.8.3. The list's unique Statement 3703 The "unique" statement is used to put constraints on valid list 3704 entries. It takes as an argument a string that contains a space- 3705 separated list of schema node identifiers, which MUST be given in the 3706 descendant form (see the rule "descendant-schema-nodeid" in 3707 Section 14). Each such schema node identifier MUST refer to a leaf. 3709 If one of the referenced leafs represents configuration data, then 3710 all of the referenced leafs MUST represent configuration data. 3712 The "unique" constraint specifies that the combined values of all the 3713 leaf instances specified in the argument string, including leafs with 3714 default values, MUST be unique within all list entry instances in 3715 which all referenced leafs exist or have default values. The 3716 constraint is enforced according to the rules in Section 8. 3718 The unique string syntax is formally defined by the rule "unique-arg" 3719 in Section 14. 3721 7.8.3.1. Usage Example 3723 With the following list: 3725 list server { 3726 key "name"; 3727 unique "ip port"; 3728 leaf name { 3729 type string; 3730 } 3731 leaf ip { 3732 type inet:ip-address; 3733 } 3734 leaf port { 3735 type inet:port-number; 3736 } 3737 } 3739 The following configuration is not valid: 3741 3742 smtp 3743 192.0.2.1 3744 25 3745 3747 3748 http 3749 192.0.2.1 3750 25 3751 3753 The following configuration is valid, since the "http" and "ftp" list 3754 entries do not have a value for all referenced leafs, and are thus 3755 not taken into account when the "unique" constraint is enforced: 3757 3758 smtp 3759 192.0.2.1 3760 25 3761 3763 3764 http 3765 192.0.2.1 3766 3768 3769 ftp 3770 192.0.2.1 3771 3773 7.8.4. The list's Child Node Statements 3775 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3776 "choice", "anydata", and "anyxml" statements can be used to define 3777 child nodes to the list. 3779 7.8.5. XML Encoding Rules 3781 A list is encoded as a series of XML elements, one for each entry in 3782 the list. Each element's local name is the list's identifier, and 3783 its namespace is the module's XML namespace (see Section 7.1.3). 3784 There is no XML element surrounding the list as a whole. 3786 The list's key nodes are encoded as subelements to the list's 3787 identifier element, in the same order as they are defined within the 3788 "key" statement. 3790 The rest of the list's child nodes are encoded as subelements to the 3791 list element, after the keys. If the list defines RPC or action 3792 input or output parameters, the subelements are encoded in the same 3793 order as they are defined within the "list" statement. Otherwise, 3794 the subelements are encoded in any order. 3796 Any whitespace between the subelements to the list entry is 3797 insignificant, i.e., an implementation MAY insert whitespace 3798 characters between subelements. 3800 The XML elements representing list entries MUST appear in the order 3801 specified by the user if the list is "ordered-by user", otherwise the 3802 order is implementation-dependent. The XML elements representing 3803 list entries MAY be interleaved with elements for siblings of the 3804 list, unless the list defines RPC or action input or output 3805 parameters. 3807 7.8.6. NETCONF Operations 3809 List entries can be created, deleted, replaced, and modified through 3810 , by using the "operation" attribute in the list's XML 3811 element. In each case, the values of all keys are used to uniquely 3812 identify a list entry. If all keys are not specified for a list 3813 entry, a "missing-element" error is returned. 3815 In an "ordered-by user" list, the attributes "insert" and "key" in 3816 the YANG XML namespace (Section 5.3.1) can be used to control where 3817 in the list the entry is inserted. These can be used during "create" 3818 operations to insert a new list entry, or during "merge" or "replace" 3819 operations to insert a new list entry or move an existing one. 3821 The "insert" attribute can take the values "first", "last", "before", 3822 and "after". If the value is "before" or "after", the "key" 3823 attribute MUST also be used, to specify an existing element in the 3824 list. The value of the "key" attribute is the key predicates of the 3825 full instance identifier (see Section 9.13) for the list entry. 3827 If no "insert" attribute is present in the "create" operation, it 3828 defaults to "last". 3830 If several entries in an "ordered-by user" list are modified in the 3831 same request, the entries are modified one at the time, 3832 in the order of the XML elements in the request. 3834 In a , or an with a "replace" operation 3835 that covers the entire list, the list entry order is the same as the 3836 order of the XML elements in the request. 3838 When a NETCONF server processes an request, the 3839 elements of procedure for a list node are: 3841 If the operation is "merge" or "replace", the list entry is 3842 created if it does not exist. If the list entry already exists 3843 and the "insert" and "key" attributes are present, the list entry 3844 is moved according to the values of the "insert" and "key" 3845 attributes. If the list entry exists and the "insert" and "key" 3846 attributes are not present, the list entry is not moved. 3848 If the operation is "create", the list entry is created if it does 3849 not exist. If the list entry already exists, a "data-exists" 3850 error is returned. 3852 If the operation is "delete", the entry is deleted from the list 3853 if it exists. If the list entry does not exist, a "data-missing" 3854 error is returned. 3856 7.8.7. Usage Example 3858 Given the following list: 3860 list user { 3861 key "name"; 3862 config true; 3863 description 3864 "This is a list of users in the system."; 3866 leaf name { 3867 type string; 3868 } 3869 leaf type { 3870 type string; 3871 } 3872 leaf full-name { 3873 type string; 3874 } 3875 } 3877 A corresponding XML instance example: 3879 3880 fred 3881 admin 3882 Fred Flintstone 3883 3885 To create a new user "barney": 3887 3890 3891 3892 3893 3894 3895 3896 3897 barney 3898 admin 3899 Barney Rubble 3900 3901 3902 3903 3904 3906 To change the type of "fred" to "superuser": 3908 3911 3912 3913 3914 3915 3916 3917 3918 fred 3919 superuser 3920 3921 3922 3923 3924 3926 Given the following ordered-by user list: 3928 list user { 3929 description 3930 "This is a list of users in the system."; 3931 ordered-by user; 3932 config true; 3934 key "first-name surname"; 3936 leaf first-name { 3937 type string; 3938 } 3939 leaf surname { 3940 type string; 3941 } 3942 leaf type { 3943 type string; 3944 } 3945 } 3947 The following would be used to insert a new user "barney rubble" 3948 after the user "fred flintstone": 3950 3954 3955 3956 3957 3958 3959 3961 3965 barney 3966 rubble 3967 admin 3968 3969 3970 3971 3972 3974 The following would be used to move the user "barney rubble" before 3975 the user "fred flintstone": 3977 3981 3982 3983 3984 3985 3986 3988 3992 barney 3993 rubble 3994 3995 3996 3997 3998 4000 7.9. The choice Statement 4002 The "choice" statement defines a set of alternatives, only one of 4003 which may be present in any one data tree. The argument is an 4004 identifier, followed by a block of substatements that holds detailed 4005 choice information. The identifier is used to identify the choice 4006 node in the schema tree. A choice node does not exist in the data 4007 tree. 4009 A choice consists of a number of branches, each defined with a "case" 4010 substatement. Each branch contains a number of child nodes. The 4011 nodes from at most one of the choice's branches exist at the same 4012 time. 4014 Since only one of the choice's cases can be valid at any time in the 4015 data tree, the creation of a node from one case implicitly deletes 4016 all nodes from all other cases. If a request creates a node from a 4017 case, the server will delete any existing nodes that are defined in 4018 other cases inside the choice. 4020 7.9.1. The choice's Substatements 4021 +--------------+---------+-------------+ 4022 | substatement | section | cardinality | 4023 +--------------+---------+-------------+ 4024 | anydata | 7.10 | 0..n | 4025 | anyxml | 7.11 | 0..n | 4026 | case | 7.9.2 | 0..n | 4027 | choice | 7.9 | 0..n | 4028 | config | 7.21.1 | 0..1 | 4029 | container | 7.5 | 0..n | 4030 | default | 7.9.3 | 0..1 | 4031 | description | 7.21.3 | 0..1 | 4032 | if-feature | 7.20.2 | 0..n | 4033 | leaf | 7.6 | 0..n | 4034 | leaf-list | 7.7 | 0..n | 4035 | list | 7.8 | 0..n | 4036 | mandatory | 7.9.4 | 0..1 | 4037 | reference | 7.21.4 | 0..1 | 4038 | status | 7.21.2 | 0..1 | 4039 | when | 7.21.5 | 0..1 | 4040 +--------------+---------+-------------+ 4042 7.9.2. The choice's case Statement 4044 The "case" statement is used to define branches of the choice. It 4045 takes as an argument an identifier, followed by a block of 4046 substatements that holds detailed case information. 4048 The identifier is used to identify the case node in the schema tree. 4049 A case node does not exist in the data tree. 4051 Within a "case" statement, the "anydata", "anyxml", "choice", 4052 "container", "leaf", "list", "leaf-list", and "uses" statements can 4053 be used to define child nodes to the case node. The identifiers of 4054 all these child nodes MUST be unique within all cases in a choice. 4055 For example, the following is illegal: 4057 choice interface-type { // This example is illegal YANG 4058 case a { 4059 leaf ethernet { ... } 4060 } 4061 case b { 4062 container ethernet { ...} 4063 } 4064 } 4066 As a shorthand, the "case" statement can be omitted if the branch 4067 contains a single "anydata", "anyxml", "choice", "container", "leaf", 4068 "list", or "leaf-list" statement. In this case, the case node still 4069 exists in the schema tree, and its identifier is the same as the 4070 identifier of the child node. Schema node identifiers (Section 6.5) 4071 MUST always explicitly include case node identifiers. The following 4072 example: 4074 choice interface-type { 4075 container ethernet { ... } 4076 } 4078 is equivalent to: 4080 choice interface-type { 4081 case ethernet { 4082 container ethernet { ... } 4083 } 4084 } 4086 The case identifier MUST be unique within a choice. 4088 7.9.2.1. The case's Substatements 4090 +--------------+---------+-------------+ 4091 | substatement | section | cardinality | 4092 +--------------+---------+-------------+ 4093 | anydata | 7.10 | 0..n | 4094 | anyxml | 7.11 | 0..n | 4095 | choice | 7.9 | 0..n | 4096 | container | 7.5 | 0..n | 4097 | description | 7.21.3 | 0..1 | 4098 | if-feature | 7.20.2 | 0..n | 4099 | leaf | 7.6 | 0..n | 4100 | leaf-list | 7.7 | 0..n | 4101 | list | 7.8 | 0..n | 4102 | reference | 7.21.4 | 0..1 | 4103 | status | 7.21.2 | 0..1 | 4104 | uses | 7.13 | 0..n | 4105 | when | 7.21.5 | 0..1 | 4106 +--------------+---------+-------------+ 4108 7.9.3. The choice's default Statement 4110 The "default" statement indicates if a case should be considered as 4111 the default if no child nodes from any of the choice's cases exist. 4112 The argument is the identifier of the default "case" statement. If 4113 the "default" statement is missing, there is no default case. 4115 The "default" statement MUST NOT be present on choices where 4116 "mandatory" is "true". 4118 The default case is only important when considering the default 4119 statements of nodes under the cases (i.e., default values of leafs 4120 and leaf-lists, and default cases of nested choices). The default 4121 values and nested default cases under the default case are used if 4122 none of the nodes under any of the cases are present. 4124 There MUST NOT be any mandatory nodes (Section 3) directly under the 4125 default case. 4127 Default values for child nodes under a case are only used if one of 4128 the nodes under that case is present, or if that case is the default 4129 case. If none of the nodes under a case are present and the case is 4130 not the default case, the default values of the cases' child nodes 4131 are ignored. 4133 In this example, the choice defaults to "interval", and the default 4134 value will be used if none of "daily", "time-of-day", or "manual" are 4135 present. If "daily" is present, the default value for "time-of-day" 4136 will be used. 4138 container transfer { 4139 choice how { 4140 default interval; 4141 case interval { 4142 leaf interval { 4143 type uint16; 4144 units minutes; 4145 default 30; 4146 } 4147 } 4148 case daily { 4149 leaf daily { 4150 type empty; 4151 } 4152 leaf time-of-day { 4153 type string; 4154 units 24-hour-clock; 4155 default "01.00"; 4156 } 4157 } 4158 case manual { 4159 leaf manual { 4160 type empty; 4161 } 4162 } 4163 } 4164 } 4166 7.9.4. The choice's mandatory Statement 4168 The "mandatory" statement, which is optional, takes as an argument 4169 the string "true" or "false", and puts a constraint on valid data. 4170 If "mandatory" is "true", at least one node from exactly one of the 4171 choice's case branches MUST exist. 4173 If not specified, the default is "false". 4175 The behavior of the constraint depends on the type of the choice's 4176 closest ancestor node in the schema tree that is not a non-presence 4177 container (see Section 7.5.1): 4179 o If no such ancestor exists in the schema tree, the constraint is 4180 enforced. 4182 o Otherwise, if this ancestor is a case node, the constraint is 4183 enforced if any other node from the case exists. 4185 o Otherwise, it is enforced if the ancestor node exists. 4187 The constraint is further enforced according to the rules in 4188 Section 8. 4190 7.9.5. XML Encoding Rules 4192 The choice and case nodes are not visible in XML. 4194 The child nodes of the selected "case" statement MUST be encoded in 4195 the same order as they are defined in the "case" statement if they 4196 are part of an RPC or action input or output parameter definition. 4197 Otherwise, the subelements are encoded in any order. 4199 7.9.6. Usage Example 4201 Given the following choice: 4203 container protocol { 4204 choice name { 4205 case a { 4206 leaf udp { 4207 type empty; 4208 } 4209 } 4210 case b { 4211 leaf tcp { 4212 type empty; 4213 } 4214 } 4215 } 4216 } 4218 A corresponding XML instance example: 4220 4221 4222 4224 To change the protocol from tcp to udp: 4226 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4243 7.10. The anydata Statement 4245 The "anydata" statement defines an interior node in the schema tree. 4246 It takes one argument, which is an identifier, followed by a block of 4247 substatements that holds detailed anydata information. 4249 The "anydata" statement is used to represent an unknown set of nodes 4250 that can be modelled with YANG, except anyxml, but for which the data 4251 model is not known at module design time. It is possible, though not 4252 required, for the data model for "anydata" content to become known 4253 through protocol signalling or other means that are outside the scope 4254 of this document. 4256 An example of where anydata can be useful is a list of received 4257 notifications, where the specific notifications are not known at 4258 design time. 4260 An anydata node cannot be augmented (see Section 7.17). 4262 An anydata node exists in zero or one instances in the data tree. 4264 An implementation may or may not know the data model used to model a 4265 specific instance of an anydata node. 4267 Since the use of anydata limits the manipulation of the content, the 4268 "anydata" statement SHOULD NOT be used to define configuration data. 4270 7.10.1. The anydata's Substatements 4272 +--------------+---------+-------------+ 4273 | substatement | section | cardinality | 4274 +--------------+---------+-------------+ 4275 | config | 7.21.1 | 0..1 | 4276 | description | 7.21.3 | 0..1 | 4277 | if-feature | 7.20.2 | 0..n | 4278 | mandatory | 7.6.5 | 0..1 | 4279 | must | 7.5.3 | 0..n | 4280 | reference | 7.21.4 | 0..1 | 4281 | status | 7.21.2 | 0..1 | 4282 | when | 7.21.5 | 0..1 | 4283 +--------------+---------+-------------+ 4285 7.10.2. XML Encoding Rules 4287 An anydata node is encoded as an XML element. The element's local 4288 name is the anydata's identifier, and its namespace is the module's 4289 XML namespace (see Section 7.1.3). The value of the anydata node is 4290 a set of nodes, which are encoded as XML subelements to the anydata 4291 element. 4293 7.10.3. NETCONF Operations 4295 An anydata node is treated as an opaque chunk of data. This data can 4296 be modified in its entirety only. 4298 Any "operation" attributes present on subelements of an anydata node 4299 are ignored by the NETCONF server. 4301 When a NETCONF server processes an request, the 4302 elements of procedure for the anydata node are: 4304 If the operation is "merge" or "replace", the node is created if 4305 it does not exist, and its value is set to the subelements of the 4306 anydata node found in the XML RPC data. 4308 If the operation is "create", the node is created if it does not 4309 exist, and its value is set to the subelements of the anydata node 4310 found in the XML RPC data. If the node already exists, a 4311 "data-exists" error is returned. 4313 If the operation is "delete", the node is deleted if it exists. 4314 If the node does not exist, a "data-missing" error is returned. 4316 7.10.4. Usage Example 4318 Given the following "anydata" statement: 4320 list logged-notification { 4321 key time; 4322 leaf time { 4323 type yang:date-and-time; 4324 } 4325 anydata data; 4326 } 4328 The following is a valid encoding of such a list instance: 4330 4331 4332 4333 4335 2014-07-29T13:43:01Z 4336 4337 fault 4338 4339 Ethernet0 4340 4341 major 4342 4343 4344 4346 7.11. The anyxml Statement 4348 The "anyxml" statement defines an interior node in the schema tree. 4349 It takes one argument, which is an identifier, followed by a block of 4350 substatements that holds detailed anyxml information. 4352 The "anyxml" statement is used to represent an unknown chunk of XML. 4353 No restrictions are placed on the XML. This can be useful, for 4354 example, in RPC replies. An example is the parameter in the 4355 operation in NETCONF. 4357 An anyxml node cannot be augmented (see Section 7.17). 4359 An anyxml node exists in zero or one instances in the data tree. 4361 Since the use of anyxml limits the manipulation of the content, the 4362 "anyxml" statement SHOULD NOT be used to define configuration data. 4364 It should be noted that in YANG version 1, anyxml was the only 4365 statement that could model an unknown hierarchy of data. In many 4366 cases this unknown hierarchy of data is actually modelled in YANG, 4367 but the specific YANG data model is not known at design time. In 4368 these situations, it is RECOMMENDED to use anydata (Section 7.10) 4369 instead of anyxml. 4371 7.11.1. The anyxml's Substatements 4373 +--------------+---------+-------------+ 4374 | substatement | section | cardinality | 4375 +--------------+---------+-------------+ 4376 | config | 7.21.1 | 0..1 | 4377 | description | 7.21.3 | 0..1 | 4378 | if-feature | 7.20.2 | 0..n | 4379 | mandatory | 7.6.5 | 0..1 | 4380 | must | 7.5.3 | 0..n | 4381 | reference | 7.21.4 | 0..1 | 4382 | status | 7.21.2 | 0..1 | 4383 | when | 7.21.5 | 0..1 | 4384 +--------------+---------+-------------+ 4386 7.11.2. XML Encoding Rules 4388 An anyxml node is encoded as an XML element. The element's local 4389 name is the anyxml's identifier, and its namespace is the module's 4390 XML namespace (see Section 7.1.3). The value of the anyxml node is 4391 encoded as XML content of this element. 4393 Note that any XML prefixes used in the encoding are local to each 4394 instance encoding. This means that the same XML may be encoded 4395 differently by different implementations. 4397 7.11.3. NETCONF Operations 4399 An anyxml node is treated as an opaque chunk of data. This data can 4400 be modified in its entirety only. 4402 Any "operation" attributes present on subelements of an anyxml node 4403 are ignored by the NETCONF server. 4405 When a NETCONF server processes an request, the 4406 elements of procedure for the anyxml node are: 4408 If the operation is "merge" or "replace", the node is created if 4409 it does not exist, and its value is set to the XML content of the 4410 anyxml node found in the XML RPC data. 4412 If the operation is "create", the node is created if it does not 4413 exist, and its value is set to the XML content of the anyxml node 4414 found in the XML RPC data. If the node already exists, a 4415 "data-exists" error is returned. 4417 If the operation is "delete", the node is deleted if it exists. 4418 If the node does not exist, a "data-missing" error is returned. 4420 7.11.4. Usage Example 4422 Given the following "anyxml" statement: 4424 anyxml html-info; 4426 The following are two valid encodings of the same anyxml value: 4428 4429

4430 This is very cool. 4431

4432 4434 4435 4436 This is very cool. 4437 4438 4440 7.12. The grouping Statement 4442 The "grouping" statement is used to define a reusable block of nodes, 4443 which may be used locally in the module or submodule, and by other 4444 modules that import from it, according to the rules in Section 5.5. 4445 It takes one argument, which is an identifier, followed by a block of 4446 substatements that holds detailed grouping information. 4448 The "grouping" statement is not a data definition statement and, as 4449 such, does not define any nodes in the schema tree. 4451 A grouping is like a "structure" or a "record" in conventional 4452 programming languages. 4454 Once a grouping is defined, it can be referenced in a "uses" 4455 statement (see Section 7.13). A grouping MUST NOT reference itself, 4456 neither directly nor indirectly through a chain of other groupings. 4458 If the grouping is defined at the top level of a YANG module or 4459 submodule, the grouping's identifier MUST be unique within the 4460 module. 4462 A grouping is more than just a mechanism for textual substitution, 4463 but defines a collection of nodes. Identifiers appearing inside the 4464 grouping are resolved relative to the scope in which the grouping is 4465 defined, not where it is used. Prefix mappings, type names, grouping 4466 names, and extension usage are evaluated in the hierarchy where the 4467 "grouping" statement appears. For extensions, this means that 4468 extensions defined as direct children to a "grouping" statement are 4469 applied to the grouping itself. 4471 Note that if a grouping defines an "action" or a "notification" node 4472 in its hierarchy, then it cannot be used in all contexts. For 4473 example, it cannot be used in an rpc definition. See Section 7.15 4474 and Section 7.16. 4476 7.12.1. The grouping's Substatements 4477 +--------------+---------+-------------+ 4478 | substatement | section | cardinality | 4479 +--------------+---------+-------------+ 4480 | action | 7.15 | 0..n | 4481 | anydata | 7.10 | 0..n | 4482 | anyxml | 7.11 | 0..n | 4483 | choice | 7.9 | 0..n | 4484 | container | 7.5 | 0..n | 4485 | description | 7.21.3 | 0..1 | 4486 | grouping | 7.12 | 0..n | 4487 | leaf | 7.6 | 0..n | 4488 | leaf-list | 7.7 | 0..n | 4489 | list | 7.8 | 0..n | 4490 | notification | 7.16 | 0..n | 4491 | reference | 7.21.4 | 0..1 | 4492 | status | 7.21.2 | 0..1 | 4493 | typedef | 7.3 | 0..n | 4494 | uses | 7.13 | 0..n | 4495 +--------------+---------+-------------+ 4497 7.12.2. Usage Example 4499 import ietf-inet-types { 4500 prefix "inet"; 4501 } 4503 grouping endpoint { 4504 description "A reusable endpoint group."; 4505 leaf ip { 4506 type inet:ip-address; 4507 } 4508 leaf port { 4509 type inet:port-number; 4510 } 4511 } 4513 7.13. The uses Statement 4515 The "uses" statement is used to reference a "grouping" definition. 4516 It takes one argument, which is the name of the grouping. 4518 The effect of a "uses" reference to a grouping is that the nodes 4519 defined by the grouping are copied into the current schema tree, and 4520 then updated according to the "refine" and "augment" statements. 4522 The identifiers defined in the grouping are not bound to a namespace 4523 until the contents of the grouping are added to the schema tree via a 4524 "uses" statement that does not appear inside a "grouping" statement, 4525 at which point they are bound to the namespace of the current module. 4527 7.13.1. The uses's Substatements 4529 +--------------+---------+-------------+ 4530 | substatement | section | cardinality | 4531 +--------------+---------+-------------+ 4532 | augment | 7.17 | 0..n | 4533 | description | 7.21.3 | 0..1 | 4534 | if-feature | 7.20.2 | 0..n | 4535 | refine | 7.13.2 | 0..n | 4536 | reference | 7.21.4 | 0..1 | 4537 | status | 7.21.2 | 0..1 | 4538 | when | 7.21.5 | 0..1 | 4539 +--------------+---------+-------------+ 4541 7.13.2. The refine Statement 4543 Some of the properties of each node in the grouping can be refined 4544 with the "refine" statement. The argument is a string that 4545 identifies a node in the grouping. This node is called the refine's 4546 target node. If a node in the grouping is not present as a target 4547 node of a "refine" statement, it is not refined, and thus used 4548 exactly as it was defined in the grouping. 4550 The argument string is a descendant schema node identifier (see 4551 Section 6.5). 4553 The following refinements can be done: 4555 o A leaf or choice node may get a default value, or a new default 4556 value if it already had one. 4558 o A leaf-list node may get a set of default values, or a new set of 4559 default values if it already had defaults; i.e., the set of 4560 refined default values replaces the defaults already given. 4562 o Any node may get a specialized "description" string. 4564 o Any node may get a specialized "reference" string. 4566 o Any node may get a different "config" statement. 4568 o A leaf, anydata, anyxml, or choice node may get a different 4569 "mandatory" statement. 4571 o A container node may get a "presence" statement. 4573 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4574 get additional "must" expressions. 4576 o A leaf-list or list node may get a different "min-elements" or 4577 "max-elements" statement. 4579 o A leaf, leaf-list, list, container, choice, case, anydata, or 4580 anyxml node may get additional "if-feature" expressions. 4582 o Any node can get refined extensions, if the extension allows 4583 refinement. See Section 7.19 for details. 4585 7.13.3. XML Encoding Rules 4587 Each node in the grouping is encoded as if it was defined inline, 4588 even if it is imported from another module with another XML 4589 namespace. 4591 7.13.4. Usage Example 4593 To use the "endpoint" grouping defined in Section 7.12.2 in a 4594 definition of an HTTP server in some other module, we can do: 4596 import example-system { 4597 prefix "sys"; 4598 } 4600 container http-server { 4601 leaf name { 4602 type string; 4603 } 4604 uses sys:endpoint; 4605 } 4607 A corresponding XML instance example: 4609 4610 extern-web 4611 192.0.2.1 4612 80 4613 4615 If port 80 should be the default for the HTTP server, default can be 4616 added: 4618 container http-server { 4619 leaf name { 4620 type string; 4621 } 4622 uses sys:endpoint { 4623 refine port { 4624 default 80; 4625 } 4626 } 4627 } 4629 If we want to define a list of servers, and each server has the ip 4630 and port as keys, we can do: 4632 list server { 4633 key "ip port"; 4634 leaf name { 4635 type string; 4636 } 4637 uses sys:endpoint; 4638 } 4640 The following is an error: 4642 container http-server { 4643 uses sys:endpoint; 4644 leaf ip { // illegal - same identifier "ip" used twice 4645 type string; 4646 } 4647 } 4649 7.14. The rpc Statement 4651 The "rpc" statement is used to define an RPC operation. It takes one 4652 argument, which is an identifier, followed by a block of 4653 substatements that holds detailed rpc information. This argument is 4654 the name of the RPC. 4656 The "rpc" statement defines an rpc node in the schema tree. Under 4657 the rpc node, a schema node with the name "input", and a schema node 4658 with the name "output" are also defined. The nodes "input" and 4659 "output" are defined in the module's namespace. 4661 7.14.1. The rpc's Substatements 4662 +--------------+---------+-------------+ 4663 | substatement | section | cardinality | 4664 +--------------+---------+-------------+ 4665 | description | 7.21.3 | 0..1 | 4666 | grouping | 7.12 | 0..n | 4667 | if-feature | 7.20.2 | 0..n | 4668 | input | 7.14.2 | 0..1 | 4669 | output | 7.14.3 | 0..1 | 4670 | reference | 7.21.4 | 0..1 | 4671 | status | 7.21.2 | 0..1 | 4672 | typedef | 7.3 | 0..n | 4673 +--------------+---------+-------------+ 4675 7.14.2. The input Statement 4677 The "input" statement, which is optional, is used to define input 4678 parameters to the operation. It does not take an argument. The 4679 substatements to "input" define nodes under the operation's input 4680 node. 4682 If a leaf in the input tree has a "mandatory" statement with the 4683 value "true", the leaf MUST be present in an RPC invocation. 4685 If a leaf in the input tree has a default value, the server MUST use 4686 this value in the same cases as described in Section 7.6.1. In these 4687 cases, the server MUST operationally behave as if the leaf was 4688 present in the RPC invocation with the default value as its value. 4690 If a leaf-list in the input tree has one or more default values, the 4691 server MUST use these values in the same cases as described in 4692 Section 7.7.2. In these cases, the server MUST operationally behave 4693 as if the leaf-list was present in the RPC invocation with the 4694 default values as its values. 4696 Since the input tree is not part of any datastore, all "config" 4697 statements for nodes in the input tree are ignored. 4699 If any node has a "when" statement that would evaluate to "false", 4700 then this node MUST NOT be present in the input tree. 4702 7.14.2.1. The input's Substatements 4703 +--------------+---------+-------------+ 4704 | substatement | section | cardinality | 4705 +--------------+---------+-------------+ 4706 | anydata | 7.10 | 0..n | 4707 | anyxml | 7.11 | 0..n | 4708 | choice | 7.9 | 0..n | 4709 | container | 7.5 | 0..n | 4710 | grouping | 7.12 | 0..n | 4711 | leaf | 7.6 | 0..n | 4712 | leaf-list | 7.7 | 0..n | 4713 | list | 7.8 | 0..n | 4714 | must | 7.5.3 | 0..n | 4715 | typedef | 7.3 | 0..n | 4716 | uses | 7.13 | 0..n | 4717 +--------------+---------+-------------+ 4719 7.14.3. The output Statement 4721 The "output" statement, which is optional, is used to define output 4722 parameters to the RPC operation. It does not take an argument. The 4723 substatements to "output" define nodes under the operation's output 4724 node. 4726 If a leaf in the output tree has a "mandatory" statement with the 4727 value "true", the leaf MUST be present in an RPC reply. 4729 If a leaf in the output tree has a default value, the client MUST use 4730 this value in the same cases as described in Section 7.6.1. In these 4731 cases, the client MUST operationally behave as if the leaf was 4732 present in the RPC reply with the default value as its value. 4734 If a leaf-list in the output tree has one or more default values, the 4735 client MUST use these values in the same cases as described in 4736 Section 7.7.2. In these cases, the client MUST operationally behave 4737 as if the leaf-list was present in the RPC reply with the default 4738 values as its values. 4740 Since the output tree is not part of any datastore, all "config" 4741 statements for nodes in the output tree are ignored. 4743 If any node has a "when" statement that would evaluate to "false", 4744 then this node MUST NOT be present in the output tree. 4746 7.14.3.1. The output's Substatements 4747 +--------------+---------+-------------+ 4748 | substatement | section | cardinality | 4749 +--------------+---------+-------------+ 4750 | anydata | 7.10 | 0..n | 4751 | anyxml | 7.11 | 0..n | 4752 | choice | 7.9 | 0..n | 4753 | container | 7.5 | 0..n | 4754 | grouping | 7.12 | 0..n | 4755 | leaf | 7.6 | 0..n | 4756 | leaf-list | 7.7 | 0..n | 4757 | list | 7.8 | 0..n | 4758 | must | 7.5.3 | 0..n | 4759 | typedef | 7.3 | 0..n | 4760 | uses | 7.13 | 0..n | 4761 +--------------+---------+-------------+ 4763 7.14.4. NETCONF XML Encoding Rules 4765 An rpc node is encoded as a child XML element to the element, 4766 as designated by the substitution group "rpcOperation" in [RFC6241]. 4767 The element's local name is the rpc's identifier, and its namespace 4768 is the module's XML namespace (see Section 7.1.3). 4770 Input parameters are encoded as child XML elements to the rpc node's 4771 XML element, in the same order as they are defined within the "input" 4772 statement. 4774 If the RPC operation invocation succeeded, and no output parameters 4775 are returned, the contains a single element defined 4776 in [RFC6241]. If output parameters are returned, they are encoded as 4777 child elements to the element defined in [RFC6241], in 4778 the same order as they are defined within the "output" statement. 4780 7.14.5. Usage Example 4782 The following example defines an RPC operation: 4784 module example-rock { 4785 yang-version 1.1; 4786 namespace "urn:example:rock"; 4787 prefix "rock"; 4789 rpc rock-the-house { 4790 input { 4791 leaf zip-code { 4792 type string; 4793 } 4794 } 4795 } 4796 } 4798 A corresponding XML instance example of the complete rpc and rpc- 4799 reply: 4801 4803 4804 27606-0100 4805 4806 4808 4810 4811 4813 7.15. The action Statement 4815 The "action" statement is used to define an operation connected to a 4816 specific container or list data node. It takes one argument, which 4817 is an identifier, followed by a block of substatements that holds 4818 detailed action information. The argument is the name of the action. 4820 The "action" statement defines an action node in the schema tree. 4821 Under the action node, a schema node with the name "input", and a 4822 schema node with the name "output" are also defined. The nodes 4823 "input" and "output" are defined in the module's namespace. 4825 An action MUST NOT be defined within an rpc, another action or a 4826 notification, i.e., an action node MUST NOT have an rpc, action, or a 4827 notification node as one of its ancestors in the schema tree. For 4828 example, this means that it is an error if a grouping that contains 4829 an action somewhere in its node hierarchy is used in a notification 4830 definition. 4832 An action MUST NOT have any ancestor node that is a list node without 4833 a "key" statement. 4835 Since an action cannot be defined at the top-level of a module or in 4836 a case statement, it is an error if a grouping that contains an 4837 action at the top of its node hierarchy is used at the top-level of a 4838 module or in a case definition. 4840 The difference between an action and an rpc is that an action is tied 4841 to a node in the datastore, whereas an rpc is not. When an action is 4842 invoked, the node in the datastore is specified along with the name 4843 of the action and the input parameters. 4845 7.15.1. The action's Substatements 4847 +--------------+---------+-------------+ 4848 | substatement | section | cardinality | 4849 +--------------+---------+-------------+ 4850 | description | 7.21.3 | 0..1 | 4851 | grouping | 7.12 | 0..n | 4852 | if-feature | 7.20.2 | 0..n | 4853 | input | 7.14.2 | 0..1 | 4854 | output | 7.14.3 | 0..1 | 4855 | reference | 7.21.4 | 0..1 | 4856 | status | 7.21.2 | 0..1 | 4857 | typedef | 7.3 | 0..n | 4858 +--------------+---------+-------------+ 4860 7.15.2. NETCONF XML Encoding Rules 4862 When an action is invoked, an element with the local name "action" in 4863 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4864 encoded as a child XML element to the element defined in 4865 [RFC6241], as designated by the substitution group "rpcOperation" in 4866 [RFC6241]. 4868 The "action" element contains an hierarchy of nodes that identifies 4869 the node in the datastore. It MUST contain all containers and list 4870 nodes in the direct path from the top level down to the list or 4871 container containing the action. For lists, all key leafs MUST also 4872 be included. The innermost container or list contains an XML element 4873 that carries the name of the defined action. Within this element the 4874 input parameters are encoded as child XML elements, in the same order 4875 as they are defined within the "input" statement. 4877 Only one action can be invoked in one . If more than one action 4878 is present in the , the server MUST reply with an "bad-element" 4879 error-tag in the . 4881 If the action operation invocation succeeded, and no output 4882 parameters are returned, the contains a single 4883 element defined in [RFC6241]. If output parameters are returned, 4884 they are encoded as child elements to the element defined 4885 in [RFC6241], in the same order as they are defined within the 4886 "output" statement. 4888 7.15.3. Usage Example 4890 The following example defines an action to reset one server at a 4891 server farm: 4893 module example-server-farm { 4894 yang-version 1.1; 4895 namespace "urn:example:server-farm"; 4896 prefix "sfarm"; 4898 import ietf-yang-types { 4899 prefix "yang"; 4900 } 4902 list server { 4903 key name; 4904 leaf name { 4905 type string; 4906 } 4907 action reset { 4908 input { 4909 leaf reset-at { 4910 type yang:date-and-time; 4911 mandatory true; 4912 } 4913 } 4914 output { 4915 leaf reset-finished-at { 4916 type yang:date-and-time; 4917 mandatory true; 4918 } 4919 } 4920 } 4921 } 4922 } 4924 A corresponding XML instance example of the complete rpc and rpc- 4925 reply: 4927 4929 4930 4931 apache-1 4932 4933 2014-07-29T13:42:00Z 4934 4935 4936 4937 4939 4941 4942 2014-07-29T13:42:12Z 4943 4944 4946 7.16. The notification Statement 4948 The "notification" statement is used to define a notification. It 4949 takes one argument, which is an identifier, followed by a block of 4950 substatements that holds detailed notification information. The 4951 "notification" statement defines a notification node in the schema 4952 tree. 4954 A notification can be defined at the top-level of a module, or 4955 connected to a specific container or list data node in the schema 4956 tree. 4958 A notification MUST NOT be defined within an rpc, action or another 4959 notification, i.e., a notification node MUST NOT have an rpc, action, 4960 or a notification node as one of its ancestors in the schema tree. 4961 For example, this means that it is an error if a grouping that 4962 contains an notification somewhere in its node hierarchy is used in 4963 an rpc definition. 4965 A notification MUST NOT have any ancestor node that is a list node 4966 without a "key" statement. 4968 Since a notification cannot be defined in a case statement, it is an 4969 error if a grouping that contains a notification at the top of its 4970 node hierarchy is used in a case definition. 4972 If a leaf in the notification tree has a "mandatory" statement with 4973 the value "true", the leaf MUST be present in a notification 4974 instance. 4976 If a leaf in the notification tree has a default value, the client 4977 MUST use this value in the same cases as described in Section 7.6.1. 4978 In these cases, the client MUST operationally behave as if the leaf 4979 was present in the notification instance with the default value as 4980 its value. 4982 If a leaf-list in the notification tree has one or more default 4983 values, the client MUST use these values in the same cases as 4984 described in Section 7.7.2. In these cases, the client MUST 4985 operationally behave as if the leaf-list was present in the 4986 notification instance with the default values as its values. 4988 Since the notification tree is not part of any datastore, all 4989 "config" statements for nodes in the notification tree are ignored. 4991 7.16.1. The notification's Substatements 4993 +--------------+---------+-------------+ 4994 | substatement | section | cardinality | 4995 +--------------+---------+-------------+ 4996 | anydata | 7.10 | 0..n | 4997 | anyxml | 7.11 | 0..n | 4998 | choice | 7.9 | 0..n | 4999 | container | 7.5 | 0..n | 5000 | description | 7.21.3 | 0..1 | 5001 | grouping | 7.12 | 0..n | 5002 | if-feature | 7.20.2 | 0..n | 5003 | leaf | 7.6 | 0..n | 5004 | leaf-list | 7.7 | 0..n | 5005 | list | 7.8 | 0..n | 5006 | must | 7.5.3 | 0..n | 5007 | reference | 7.21.4 | 0..1 | 5008 | status | 7.21.2 | 0..1 | 5009 | typedef | 7.3 | 0..n | 5010 | uses | 7.13 | 0..n | 5011 +--------------+---------+-------------+ 5013 7.16.2. NETCONF XML Encoding Rules 5015 A notification node that is defined on the top-level of a module is 5016 encoded as a child XML element to the element defined 5017 in NETCONF Event Notifications [RFC5277]. The element's local name 5018 is the notification's identifier, and its namespace is the module's 5019 XML namespace (see Section 7.1.3). 5021 When a notification node is defined as a child to a data node, the 5022 element defined in NETCONF Event Notifications 5023 [RFC5277] contains an hierarchy of nodes that identifies the node in 5024 the datastore. It MUST contain all containers and list nodes from 5025 the top level down to the list or container containing the 5026 notification. For lists, all key leafs MUST also be included. The 5027 innermost container or list contains an XML element that carries the 5028 name of the defined notification. 5030 The notification's child nodes are encoded as subelements to the 5031 notification node's XML element, in any order. 5033 7.16.3. Usage Example 5035 The following example defines a notification at the top-level of a 5036 module: 5038 module example-event { 5039 yang-version 1.1; 5040 namespace "urn:example:event"; 5041 prefix "ev"; 5043 notification event { 5044 leaf event-class { 5045 type string; 5046 } 5047 leaf reporting-entity { 5048 type instance-identifier; 5049 } 5050 leaf severity { 5051 type string; 5052 } 5053 } 5054 } 5056 A corresponding XML instance example of the complete notification: 5058 5060 2008-07-08T00:01:00Z 5061 5062 fault 5063 5064 /ex:interface[ex:name='Ethernet0'] 5065 5066 major 5067 5068 5070 The following example defines a notification in a data node: 5072 module example-interface-module { 5073 yang-version 1.1; 5074 namespace "urn:example:interface-module"; 5075 prefix "if"; 5077 container interfaces { 5078 list interface { 5079 key "name"; 5080 leaf name { 5081 type string; 5082 } 5083 notification interface-enabled { 5084 leaf by-user { 5085 type string; 5086 } 5087 } 5088 } 5089 } 5090 } 5092 A corresponding XML instance example of the complete notification: 5094 5096 2008-07-08T00:01:00Z 5097 5098 5099 eth1 5100 5101 fred 5102 5103 5104 5105 5107 7.17. The augment Statement 5109 The "augment" statement allows a module or submodule to add to a 5110 schema tree defined in an external module, or in the current module 5111 and its submodules, and to add to the nodes from a grouping in a 5112 "uses" statement. The argument is a string that identifies a node in 5113 the schema tree. This node is called the augment's target node. The 5114 target node MUST be either a container, list, choice, case, input, 5115 output, or notification node. It is augmented with the nodes defined 5116 in the substatements that follow the "augment" statement. 5118 The argument string is a schema node identifier (see Section 6.5). 5119 If the "augment" statement is on the top level in a module or 5120 submodule, the absolute form (defined by the rule 5121 "absolute-schema-nodeid" in Section 14) of a schema node identifier 5122 MUST be used. If the "augment" statement is a substatement to the 5123 "uses" statement, the descendant form (defined by the rule 5124 "descendant-schema-nodeid" in Section 14) MUST be used. 5126 If the target node is a container, list, case, input, output, or 5127 notification node, the "container", "leaf", "list", "leaf-list", 5128 "uses", and "choice" statements can be used within the "augment" 5129 statement. 5131 If the target node is a container or list node, the "action" and 5132 "notification" statements can be used within the "augment" statement. 5134 If the target node is a choice node, the "case" statement, or a case 5135 shorthand statement (see Section 7.9.2) can be used within the 5136 "augment" statement. 5138 The "augment" statement MUST NOT add multiple nodes with the same 5139 name from the same module to the target node. 5141 If the augmentation adds mandatory nodes (see Section 3) that 5142 represent configuration to a target node in another module, the 5143 augmentation MUST be conditional with a "when" statement. Care must 5144 be taken when defining the "when" expression, so that clients that do 5145 not know about the augmenting module do not break. 5147 In the following example, it is OK to augment the "interface" entry 5148 with "mandatory-leaf" because the augmentation depends on support for 5149 "some-new-iftype". The old client does not know about this type so 5150 it would never select this type, and therefore not be adding a 5151 mandatory data node. 5153 module example-augment { 5154 yang-version 1.1; 5155 namespace "urn:example:augment"; 5156 prefix mymod; 5158 import ietf-interfaces { 5159 prefix if; 5160 } 5162 identity some-new-iftype { 5163 base if:interface-type; 5164 } 5166 augment "/if:interfaces/if:interface" { 5167 when 'derived-from-or-self(if:type, "mymod:some-new-iftype")'; 5169 leaf mandatory-leaf { 5170 mandatory true; 5171 type string; 5172 } 5173 } 5174 } 5176 7.17.1. The augment's Substatements 5178 +--------------+---------+-------------+ 5179 | substatement | section | cardinality | 5180 +--------------+---------+-------------+ 5181 | action | 7.15 | 0..n | 5182 | anydata | 7.10 | 0..n | 5183 | anyxml | 7.11 | 0..n | 5184 | case | 7.9.2 | 0..n | 5185 | choice | 7.9 | 0..n | 5186 | container | 7.5 | 0..n | 5187 | description | 7.21.3 | 0..1 | 5188 | if-feature | 7.20.2 | 0..n | 5189 | leaf | 7.6 | 0..n | 5190 | leaf-list | 7.7 | 0..n | 5191 | list | 7.8 | 0..n | 5192 | notification | 7.16 | 0..n | 5193 | reference | 7.21.4 | 0..1 | 5194 | status | 7.21.2 | 0..1 | 5195 | uses | 7.13 | 0..n | 5196 | when | 7.21.5 | 0..1 | 5197 +--------------+---------+-------------+ 5199 7.17.2. XML Encoding Rules 5201 All data nodes defined in the "augment" statement are defined as XML 5202 elements in the XML namespace of the module where the "augment" is 5203 specified. 5205 When a node is augmented, the augmenting child nodes are encoded as 5206 subelements to the augmented node, in any order. 5208 7.17.3. Usage Example 5210 In namespace urn:example:interface-module, we have: 5212 container interfaces { 5213 list ifEntry { 5214 key "ifIndex"; 5216 leaf ifIndex { 5217 type uint32; 5218 } 5219 leaf ifDescr { 5220 type string; 5221 } 5222 leaf ifType { 5223 type iana:IfType; 5224 } 5225 leaf ifMtu { 5226 type int32; 5227 } 5228 } 5229 } 5231 Then, in namespace urn:example:ds0, we have: 5233 import example-interface-module { 5234 prefix "if"; 5235 } 5236 augment "/if:interfaces/if:ifEntry" { 5237 when "if:ifType='ds0'"; 5238 leaf ds0ChannelNumber { 5239 type ChannelNumber; 5240 } 5241 } 5243 A corresponding XML instance example: 5245 5247 5248 1 5249 Flintstone Inc Ethernet A562 5250 ethernetCsmacd 5251 1500 5252 5253 5254 2 5255 Flintstone Inc DS0 5256 ds0 5257 1 5258 5259 5261 As another example, suppose we have the choice defined in 5262 Section 7.9.6. The following construct can be used to extend the 5263 protocol definition: 5265 augment /ex:system/ex:protocol/ex:name { 5266 case c { 5267 leaf smtp { 5268 type empty; 5269 } 5270 } 5271 } 5273 A corresponding XML instance example: 5275 5276 5277 5278 5279 5281 or 5283 5284 5285 5286 5287 5289 7.18. The identity Statement 5291 The "identity" statement is used to define a new globally unique, 5292 abstract, and untyped identity. The identity's only purpose is to 5293 denote its name, semantics, and existence. An identity can either be 5294 defined from scratch or derived from one or more base identities. 5295 The identity's argument is an identifier that is the name of the 5296 identity. It is followed by a block of substatements that holds 5297 detailed identity information. 5299 The built-in datatype "identityref" (see Section 9.10) can be used to 5300 reference identities within a data model. 5302 7.18.1. The identity's Substatements 5304 +--------------+---------+-------------+ 5305 | substatement | section | cardinality | 5306 +--------------+---------+-------------+ 5307 | base | 7.18.2 | 0..n | 5308 | description | 7.21.3 | 0..1 | 5309 | if-feature | 7.20.2 | 0..n | 5310 | reference | 7.21.4 | 0..1 | 5311 | status | 7.21.2 | 0..1 | 5312 +--------------+---------+-------------+ 5314 7.18.2. The base Statement 5316 The "base" statement, which is optional, takes as an argument a 5317 string that is the name of an existing identity, from which the new 5318 identity is derived. If no "base" statement is present, the identity 5319 is defined from scratch. If multiple "base" statements are present, 5320 the identity is derived from all of them. 5322 If a prefix is present on the base name, it refers to an identity 5323 defined in the module that was imported with that prefix, or the 5324 local module if the prefix matches the local module's prefix. 5325 Otherwise, an identity with the matching name MUST be defined in the 5326 current module or an included submodule. 5328 An identity MUST NOT reference itself, neither directly nor 5329 indirectly through a chain of other identities. 5331 The derivation of identities has the following properties: 5333 o It is irreflexive, which means that an identity is not derived 5334 from itself. 5336 o It is transitive, which means that if identity B is derived from A 5337 and C is derived from B, then C is also derived from A. 5339 7.18.3. Usage Example 5340 module example-crypto-base { 5341 yang-version 1.1; 5342 namespace "urn:example:crypto-base"; 5343 prefix "crypto"; 5345 identity crypto-alg { 5346 description 5347 "Base identity from which all crypto algorithms 5348 are derived."; 5349 } 5351 identity symmetric-key { 5352 description 5353 "Base identity used to identify symmetric-key crypto 5354 algorithms."; 5355 } 5357 identity public-key { 5358 description 5359 "Base identity used to identify public-key crypto 5360 algorithms."; 5361 } 5362 } 5364 module example-des { 5365 yang-version 1.1; 5366 namespace "urn:example:des"; 5367 prefix "des"; 5369 import "example-crypto-base" { 5370 prefix "crypto"; 5371 } 5373 identity des { 5374 base "crypto:crypto-alg"; 5375 base "crypto:symmetric-key"; 5376 description "DES crypto algorithm"; 5377 } 5379 identity des3 { 5380 base "crypto:crypto-alg"; 5381 base "crypto:symmetric-key"; 5382 description "Triple DES crypto algorithm"; 5383 } 5384 } 5386 7.19. The extension Statement 5388 The "extension" statement allows the definition of new statements 5389 within the YANG language. This new statement definition can be 5390 imported and used by other modules. 5392 The "extension" statement's argument is an identifier that is the new 5393 keyword for the extension and must be followed by a block of 5394 substatements that holds detailed extension information. The purpose 5395 of the "extension" statement is to define a keyword, so that it can 5396 be imported and used by other modules. 5398 The extension can be used like a normal YANG statement, with the 5399 statement name followed by an argument if one is defined by the 5400 "extension" statement, and an optional block of substatements. The 5401 statement's name is created by combining the prefix of the module in 5402 which the extension was defined, a colon (":"), and the extension's 5403 keyword, with no interleaving whitespace. The substatements of an 5404 extension are defined by the "extension" statement, using some 5405 mechanism outside the scope of this specification. Syntactically, 5406 the substatements MUST be YANG statements, or also extensions defined 5407 using "extension" statements. YANG statements in extensions MUST 5408 follow the syntactical rules in Section 14. 5410 An extension can allow refinement (see Section 7.13.2) and deviations 5411 (Section 7.20.3.2), but the mechanism for how this is defined is 5412 outside the scope of this specification. 5414 7.19.1. The extension's Substatements 5416 +--------------+---------+-------------+ 5417 | substatement | section | cardinality | 5418 +--------------+---------+-------------+ 5419 | argument | 7.19.2 | 0..1 | 5420 | description | 7.21.3 | 0..1 | 5421 | reference | 7.21.4 | 0..1 | 5422 | status | 7.21.2 | 0..1 | 5423 +--------------+---------+-------------+ 5425 7.19.2. The argument Statement 5427 The "argument" statement, which is optional, takes as an argument a 5428 string that is the name of the argument to the keyword. If no 5429 argument statement is present, the keyword expects no argument when 5430 it is used. 5432 The argument's name is used in the YIN mapping, where it is used as 5433 an XML attribute or element name, depending on the argument's 5434 "yin-element" statement. 5436 7.19.2.1. The argument's Substatements 5438 +--------------+----------+-------------+ 5439 | substatement | section | cardinality | 5440 +--------------+----------+-------------+ 5441 | yin-element | 7.19.2.2 | 0..1 | 5442 +--------------+----------+-------------+ 5444 7.19.2.2. The yin-element Statement 5446 The "yin-element" statement, which is optional, takes as an argument 5447 the string "true" or "false". This statement indicates if the 5448 argument is mapped to an XML element in YIN or to an XML attribute 5449 (see Section 13). 5451 If no "yin-element" statement is present, it defaults to "false". 5453 7.19.3. Usage Example 5455 To define an extension: 5457 module example-extensions { 5458 yang-version 1.1; 5459 ... 5461 extension c-define { 5462 description 5463 "Takes as argument a name string. 5464 Makes the code generator use the given name in the 5465 #define."; 5466 argument "name"; 5467 } 5468 } 5470 To use the extension: 5472 module example-interfaces { 5473 yang-version 1.1; 5475 ... 5476 import example-extensions { 5477 prefix "myext"; 5478 } 5479 ... 5481 container interfaces { 5482 ... 5483 myext:c-define "MY_INTERFACES"; 5484 } 5485 } 5487 7.20. Conformance-Related Statements 5489 This section defines statements related to conformance, as described 5490 in Section 5.6. 5492 7.20.1. The feature Statement 5494 The "feature" statement is used to define a mechanism by which 5495 portions of the schema are marked as conditional. A feature name is 5496 defined that can later be referenced using the "if-feature" statement 5497 (see Section 7.20.2). Schema nodes tagged with an "if-feature" 5498 statement are ignored by the server unless the server supports the 5499 given feature expression. This allows portions of the YANG module to 5500 be conditional based on conditions in the server. The model can 5501 represent the abilities of the server within the model, giving a 5502 richer model that allows for differing server abilities and roles. 5504 The argument to the "feature" statement is the name of the new 5505 feature, and follows the rules for identifiers in Section 6.2. This 5506 name is used by the "if-feature" statement to tie the schema nodes to 5507 the feature. 5509 In this example, a feature called "local-storage" represents the 5510 ability for a server to store syslog messages on local storage of 5511 some sort. This feature is used to make the "local-storage-limit" 5512 leaf conditional on the presence of some sort of local storage. If 5513 the server does not report that it supports this feature, the 5514 "local-storage-limit" node is not supported. 5516 module example-syslog { 5517 yang-version 1.1; 5519 ... 5520 feature local-storage { 5521 description 5522 "This feature means the server supports local 5523 storage (memory, flash or disk) that can be used to 5524 store syslog messages."; 5525 } 5527 container syslog { 5528 leaf local-storage-limit { 5529 if-feature local-storage; 5530 type uint64; 5531 units "kilobyte"; 5532 config false; 5533 description 5534 "The amount of local storage that can be 5535 used to hold syslog messages."; 5536 } 5537 } 5538 } 5540 The "if-feature" statement can be used in many places within the YANG 5541 syntax. Definitions tagged with "if-feature" are ignored when the 5542 server does not support that feature. 5544 A feature MUST NOT reference itself, neither directly nor indirectly 5545 through a chain of other features. 5547 In order for a server to support a feature that is dependent on any 5548 other features (i.e., the feature has one or more "if-feature" 5549 substatements), the server MUST also support all the dependant 5550 features. 5552 7.20.1.1. The feature's Substatements 5554 +--------------+---------+-------------+ 5555 | substatement | section | cardinality | 5556 +--------------+---------+-------------+ 5557 | description | 7.21.3 | 0..1 | 5558 | if-feature | 7.20.2 | 0..n | 5559 | status | 7.21.2 | 0..1 | 5560 | reference | 7.21.4 | 0..1 | 5561 +--------------+---------+-------------+ 5563 7.20.2. The if-feature Statement 5565 The "if-feature" statement makes its parent statement conditional. 5566 The argument is a boolean expression over feature names. In this 5567 expression, a feature name evaluates to "true" if and only if the 5568 feature is supported by the server. The parent statement is 5569 implemented by servers where the boolean expression evaluates to 5570 "true". 5572 The if-feature boolean expression syntax is formally defined by the 5573 rule "if-feature-expr" in Section 14. Parenthesis are used to group 5574 expressions. When the expression is evaluated, the order of 5575 precedence is (highest precedence first): grouping (parenthesis), 5576 "not", "and", "or". 5578 If a prefix is present on a feature name in the boolean expression, 5579 the prefixed name refers to a feature defined in the module that was 5580 imported with that prefix, or the local module if the prefix matches 5581 the local module's prefix. Otherwise, a feature with the matching 5582 name MUST be defined in the current module or an included submodule. 5584 A leaf that is a list key MUST NOT have any "if-feature" statements. 5586 7.20.2.1. Usage Example 5588 In this example, the container "target" is implemented if either of 5589 the features "outbound-tls" or "outbound-ssh" are supported by the 5590 server. 5592 container target { 5593 if-feature "outbound-tls or outbound-ssh"; 5594 ... 5595 } 5597 The following examples are equivalent: 5599 if-feature "not foo or bar and baz"; 5601 if-feature "(not foo) or (bar and baz)"; 5603 7.20.3. The deviation Statement 5605 The "deviation" statement defines a hierarchy of a module that the 5606 server does not implement faithfully. The argument is a string that 5607 identifies the node in the schema tree where a deviation from the 5608 module occurs. This node is called the deviation's target node. The 5609 contents of the "deviation" statement give details about the 5610 deviation. 5612 The argument string is an absolute schema node identifier (see 5613 Section 6.5). 5615 Deviations define the way a server or class of servers deviate from a 5616 standard. This means that deviations MUST never be part of a 5617 published standard, since they are the mechanism for learning how 5618 implementations vary from the standards. 5620 Server deviations are strongly discouraged and MUST only be used as a 5621 last resort. Telling the application how a server fails to follow a 5622 standard is no substitute for implementing the standard correctly. A 5623 server that deviates from a module is not fully compliant with the 5624 module. 5626 However, in some cases, a particular device may not have the hardware 5627 or software ability to support parts of a standard module. When this 5628 occurs, the server makes a choice either to treat attempts to 5629 configure unsupported parts of the module as an error that is 5630 reported back to the unsuspecting application or ignore those 5631 incoming requests. Neither choice is acceptable. 5633 Instead, YANG allows servers to document portions of a base module 5634 that are not supported or supported but with different syntax, by 5635 using the "deviation" statement. 5637 After applying all deviations announced by a server, in any order, 5638 the resulting data model MUST still be valid. 5640 7.20.3.1. The deviation's Substatements 5642 +--------------+----------+-------------+ 5643 | substatement | section | cardinality | 5644 +--------------+----------+-------------+ 5645 | description | 7.21.3 | 0..1 | 5646 | deviate | 7.20.3.2 | 1..n | 5647 | reference | 7.21.4 | 0..1 | 5648 +--------------+----------+-------------+ 5650 7.20.3.2. The deviate Statement 5652 The "deviate" statement defines how the server's implementation of 5653 the target node deviates from its original definition. The argument 5654 is one of the strings "not-supported", "add", "replace", or "delete". 5656 The argument "not-supported" indicates that the target node is not 5657 implemented by this server. 5659 The argument "add" adds properties to the target node. The 5660 properties to add are identified by substatements to the "deviate" 5661 statement. If a property can only appear once, the property MUST NOT 5662 exist in the target node. 5664 The argument "replace" replaces properties of the target node. The 5665 properties to replace are identified by substatements to the 5666 "deviate" statement. The properties to replace MUST exist in the 5667 target node. 5669 The argument "delete" deletes properties from the target node. The 5670 properties to delete are identified by substatements to the "delete" 5671 statement. The substatement's keyword MUST match a corresponding 5672 keyword in the target node, and the argument's string MUST be equal 5673 to the corresponding keyword's argument string in the target node. 5675 +--------------+-------------+-------------+ 5676 | substatement | section | cardinality | 5677 +--------------+-------------+-------------+ 5678 | config | 7.21.1 | 0..1 | 5679 | default | 7.6.4 7.7.4 | 0..n | 5680 | mandatory | 7.6.5 | 0..1 | 5681 | max-elements | 7.7.6 | 0..1 | 5682 | min-elements | 7.7.5 | 0..1 | 5683 | must | 7.5.3 | 0..n | 5684 | type | 7.4 | 0..1 | 5685 | unique | 7.8.3 | 0..n | 5686 | units | 7.3.3 | 0..1 | 5687 +--------------+-------------+-------------+ 5689 The deviate's Substatements 5691 If the target node has a property defined by an extension, this 5692 property can be deviated if the extension allows deviations. See 5693 Section 7.19 for details. 5695 7.20.3.3. Usage Example 5697 In this example, the server is informing client applications that it 5698 does not support the "daytime" service in the style of RFC 867. 5700 module example-deviations { 5701 yang-version 1.1; 5702 namespace "urn:example:deviations"; 5703 prefix md; 5705 import example-base { 5706 prefix base; 5707 } 5709 deviation /base:system/base:daytime { 5710 deviate not-supported; 5711 } 5712 ... 5713 } 5715 A server would advertise both modules "example-base" and 5716 "example-deviations". 5718 The following example sets a server-specific default value to a leaf 5719 that does not have a default value defined: 5721 deviation /base:system/base:user/base:type { 5722 deviate add { 5723 default "admin"; // new users are 'admin' by default 5724 } 5725 } 5727 In this example, the server limits the number of name servers to 3: 5729 deviation /base:system/base:name-server { 5730 deviate replace { 5731 max-elements 3; 5732 } 5733 } 5735 If the original definition is: 5737 container system { 5738 must "daytime or time"; 5739 ... 5740 } 5742 a server might remove this must constraint by doing: 5744 deviation /base:system { 5745 deviate delete { 5746 must "daytime or time"; 5747 } 5748 } 5750 7.21. Common Statements 5752 This section defines substatements common to several other 5753 statements. 5755 7.21.1. The config Statement 5757 The "config" statement takes as an argument the string "true" or 5758 "false". If "config" is "true", the definition represents 5759 configuration. Data nodes representing configuration are part of 5760 configuration datastores. 5762 If "config" is "false", the definition represents state data. Data 5763 nodes representing state data are not part of configuration 5764 datastores. 5766 If "config" is not specified, the default is the same as the parent 5767 schema node's "config" value. If the parent node is a "case" node, 5768 the value is the same as the "case" node's parent "choice" node. 5770 If the top node does not specify a "config" statement, the default is 5771 "true". 5773 If a node has "config" set to "false", no node underneath it can have 5774 "config" set to "true". 5776 7.21.2. The status Statement 5778 The "status" statement takes as an argument one of the strings 5779 "current", "deprecated", or "obsolete". 5781 o "current" means that the definition is current and valid. 5783 o "deprecated" indicates an obsolete definition, but it permits new/ 5784 continued implementation in order to foster interoperability with 5785 older/existing implementations. 5787 o "obsolete" means the definition is obsolete and SHOULD NOT be 5788 implemented and/or can be removed from implementations. 5790 If no status is specified, the default is "current". 5792 If a definition is "current", it MUST NOT reference a "deprecated" or 5793 "obsolete" definition within the same module. 5795 If a definition is "deprecated", it MUST NOT reference an "obsolete" 5796 definition within the same module. 5798 For example, the following is illegal: 5800 typedef my-type { 5801 status deprecated; 5802 type int32; 5803 } 5805 leaf my-leaf { 5806 status current; 5807 type my-type; // illegal, since my-type is deprecated 5808 } 5810 7.21.3. The description Statement 5812 The "description" statement takes as an argument a string that 5813 contains a human-readable textual description of this definition. 5814 The text is provided in a language (or languages) chosen by the 5815 module developer; for the sake of interoperability, it is RECOMMENDED 5816 to choose a language that is widely understood among the community of 5817 network administrators who will use the module. 5819 7.21.4. The reference Statement 5821 The "reference" statement takes as an argument a string that is a 5822 human-readable cross-reference to an external document, either 5823 another module that defines related management information, or a 5824 document that provides additional information relevant to this 5825 definition. 5827 For example, a typedef for a "uri" data type could look like: 5829 typedef uri { 5830 type string; 5831 reference 5832 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5833 ... 5834 } 5836 7.21.5. The when Statement 5838 The "when" statement makes its parent data definition statement 5839 conditional. The node defined by the parent data definition 5840 statement is only valid when the condition specified by the "when" 5841 statement is satisfied. The statement's argument is an XPath 5842 expression (see Section 6.4), which is used to formally specify this 5843 condition. If the XPath expression conceptually evaluates to "true" 5844 for a particular instance, then the node defined by the parent data 5845 definition statement is valid; otherwise, it is not. 5847 A leaf that is a list key MUST NOT have a "when" statement. 5849 If a leaf key is defined in a grouping that is used in a list, the 5850 "uses" statement MUST NOT have a "when" statement. 5852 See Section 8.3.2 for additional information. 5854 The XPath expression is conceptually evaluated in the following 5855 context, in addition to the definition in Section 6.4.1: 5857 o If the "when" statement is a child of an "augment" statement, then 5858 the context node is the augment's target node in the data tree, if 5859 the target node is a data node. Otherwise, the context node is 5860 the closest ancestor node to the target node that is also a data 5861 node. If no such node exists, the context node is the root node. 5862 The accessible tree is tentatively altered during the processing 5863 of the XPath expression by removing all instances (if any) of the 5864 nodes added by the "augment" statement. 5866 o If the "when" statement is a child of a "uses", "choice", or 5867 "case" statement, then the context node is the closest ancestor 5868 node to the "uses", "choice", or "case" node that is also a data 5869 node. If no such node exists, the context node is the root node. 5870 The accessible tree is tentatively altered during the processing 5871 of the XPath expression by removing all instances (if any) of the 5872 nodes added by the "uses", "choice", or "case" statement. 5874 o If the "when" statement is a child of any other data definition 5875 statement, the accessible tree is tentatively altered during the 5876 processing of the XPath expression by replacing all instances of 5877 the data node for which the "when" statement is defined with a 5878 single dummy node with the same name, but with no value and no 5879 children. If no such instance exists, the dummy node is 5880 tentatively created. The context node is this dummy node. 5882 The result of the XPath expression is converted to a boolean value 5883 using the standard XPath rules. 5885 If the XPath expression references any node that also has associated 5886 "when" statements, those "when" expressions MUST be evaluated first. 5887 There MUST NOT be any circular dependencies among "when" expressions. 5889 Note that the XPath expression is conceptually evaluated. This means 5890 that an implementation does not have to use an XPath evaluator in the 5891 server. The "when" statement can very well be implemented with 5892 specially written code. 5894 8. Constraints 5896 8.1. Constraints on Data 5898 Several YANG statements define constraints on valid data. These 5899 constraints are enforced in different ways, depending on what type of 5900 data the statement defines. 5902 o If the constraint is defined on configuration data, it MUST be 5903 true in a valid configuration data tree. 5905 o If the constraint is defined on state data, it MUST be true in a 5906 valid state data tree. 5908 o If the constraint is defined on notification content, it MUST be 5909 true in any notification data tree. 5911 o If the constraint is defined on RPC or action input parameters, it 5912 MUST be true in an invocation of the RPC or action operation. 5914 o If the constraint is defined on RPC or action output parameters, 5915 it MUST be true in the RPC or action reply. 5917 The following properties are true in all data trees: 5919 o All leaf data values MUST match the type constraints for the leaf, 5920 including those defined in the type's "range", "length", and 5921 "pattern" properties. 5923 o All key leafs MUST be present for all list entries. 5925 o Nodes MUST be present for at most one case branch in all choices. 5927 o There MUST be no nodes tagged with "if-feature" present if the 5928 "if-feature" expression evaluates to "false" in the server. 5930 o There MUST be no nodes tagged with "when" present if the "when" 5931 condition evaluates to "false" in the data tree. 5933 The following properties are true in a valid data tree: 5935 o All "must" constraints MUST evaluate to "true". 5937 o All referential integrity constraints defined via the "path" 5938 statement MUST be satisfied. 5940 o All "unique" constraints on lists MUST be satisfied. 5942 o The "mandatory" constraint is enforced for leafs and choices, 5943 unless the node or any of its ancestors has a "when" condition or 5944 "if-feature" expression that evaluates to "false". 5946 o The "min-elements" and "max-elements" constraints are enforced for 5947 lists and leaf-lists, unless the node or any of its ancestors has 5948 a "when" condition or "if-feature" expression that evaluates to 5949 "false". 5951 The running configuration datastore MUST always be valid. 5953 8.2. Configuration Data Modifications 5955 o If a request creates configuration data nodes under a "choice", 5956 any existing nodes from other "case" branches in the data tree are 5957 deleted by the server. 5959 o If a request modifies a configuration data node such that any 5960 node's "when" expression becomes false, then the node in the data 5961 tree with the "when" expression is deleted by the server. 5963 8.3. NETCONF Constraint Enforcement Model 5965 For configuration data, there are three windows when constraints MUST 5966 be enforced: 5968 o during parsing of RPC payloads 5970 o during processing of the operation 5972 o during validation 5974 Each of these scenarios is considered in the following sections. 5976 8.3.1. Payload Parsing 5978 When content arrives in RPC payloads, it MUST be well-formed XML, 5979 following the hierarchy and content rules defined by the set of 5980 models the server implements. 5982 o If a leaf data value does not match the type constraints for the 5983 leaf, including those defined in the type's "range", "length", and 5984 "pattern" properties, the server MUST reply with an 5985 "invalid-value" error-tag in the rpc-error, and with the error- 5986 app-tag and error-message associated with the constraint, if any 5987 exist. 5989 o If all keys of a list entry are not present, the server MUST reply 5990 with a "missing-element" error-tag in the rpc-error. 5992 o If data for more than one case branch of a choice is present, the 5993 server MUST reply with a "bad-element" in the rpc-error. 5995 o If data for a node tagged with "if-feature" is present, and the 5996 if-feature expression evaluates to "false" in the server, the 5997 server MUST reply with an "unknown-element" error-tag in the rpc- 5998 error. 6000 o If data for a node tagged with "when" is present, and the "when" 6001 condition evaluates to "false", the server MUST reply with an 6002 "unknown-element" error-tag in the rpc-error. 6004 o For insert handling, if the value for the attributes "before" and 6005 "after" are not valid for the type of the appropriate key leafs, 6006 the server MUST reply with a "bad-attribute" error-tag in the rpc- 6007 error. 6009 o If the attributes "before" and "after" appears in any element that 6010 is not a list whose "ordered-by" property is "user", the server 6011 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 6013 8.3.2. NETCONF Processing 6015 After the incoming data is parsed, the NETCONF server performs the 6016 operation by applying the data to the configuration 6017 datastore. During this processing, the following errors MUST be 6018 detected: 6020 o Delete requests for non-existent data. 6022 o Create requests for existent data. 6024 o Insert requests with "before" or "after" parameters that do not 6025 exist. 6027 o Modification requests for nodes tagged with "when", and the "when" 6028 condition evaluates to "false". In this case the server MUST 6029 reply with an "unknown-element" error-tag in the rpc-error. 6031 8.3.3. Validation 6033 When datastore processing is complete, the final contents MUST obey 6034 all validation constraints. This validation processing is performed 6035 at differing times according to the datastore. If the datastore is 6036 "running" or "startup", these constraints MUST be enforced at the end 6037 of the or operation. If the datastore is 6038 "candidate", the constraint enforcement is delayed until a 6039 or operation. 6041 9. Built-In Types 6043 YANG has a set of built-in types, similar to those of many 6044 programming languages, but with some differences due to special 6045 requirements from the management information model. 6047 Additional types may be defined, derived from those built-in types or 6048 from other derived types. Derived types may use subtyping to 6049 formally restrict the set of possible values. 6051 The different built-in types and their derived types allow different 6052 kinds of subtyping, namely length and regular expression restrictions 6053 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 6054 numeric types (Section 9.2.4). 6056 The lexical representation of a value of a certain type is used in 6057 the XML encoding and when specifying default values and numerical 6058 ranges in YANG modules. 6060 9.1. Canonical Representation 6062 For most types, there is a single canonical representation of the 6063 type's values. Some types allow multiple lexical representations of 6064 the same value, for example, the positive integer "17" can be 6065 represented as "+17" or "17". Implementations MUST support all 6066 lexical representations specified in this document. 6068 When a server sends XML encoded data, it MUST use the canonical form 6069 defined in this section. Other encodings may introduce alternate 6070 representations. Note, however, that values in the data tree are 6071 conceptually stored in the canonical representation as defined in 6072 this section. In particular, any XPath expression evaluations are 6073 done using the canonical form, if the data type has a canonical form. 6074 If the data type does not have a canonical form, the format of the 6075 value MUST match the data type's lexical representation, but the 6076 exact format is implementation dependent. 6078 Some types have a lexical representation that depends on the 6079 encoding, e.g., the XML context in which they occur. These types do 6080 not have a canonical form. 6082 9.2. The Integer Built-In Types 6084 The integer built-in types are int8, int16, int32, int64, uint8, 6085 uint16, uint32, and uint64. They represent signed and unsigned 6086 integers of different sizes: 6088 int8 represents integer values between -128 and 127, inclusively. 6090 int16 represents integer values between -32768 and 32767, 6091 inclusively. 6093 int32 represents integer values between -2147483648 and 2147483647, 6094 inclusively. 6096 int64 represents integer values between -9223372036854775808 and 6097 9223372036854775807, inclusively. 6099 uint8 represents integer values between 0 and 255, inclusively. 6101 uint16 represents integer values between 0 and 65535, inclusively. 6103 uint32 represents integer values between 0 and 4294967295, 6104 inclusively. 6106 uint64 represents integer values between 0 and 18446744073709551615, 6107 inclusively. 6109 9.2.1. Lexical Representation 6111 An integer value is lexically represented as an optional sign ("+" or 6112 "-"), followed by a sequence of decimal digits. If no sign is 6113 specified, "+" is assumed. 6115 For convenience, when specifying a default value for an integer in a 6116 YANG module, an alternative lexical representation can be used, which 6117 represents the value in a hexadecimal or octal notation. The 6118 hexadecimal notation consists of an optional sign ("+" or "-"), the 6119 characters "0x" followed a number of hexadecimal digits, where 6120 letters may be uppercase or lowercase. The octal notation consists 6121 of an optional sign ("+" or "-"), the character "0" followed a number 6122 of octal digits. 6124 Note that if a default value in a YANG module has a leading zero 6125 ("0"), it is interpreted as an octal number. In the XML encoding, an 6126 integer is always interpreted as a decimal number, and leading zeros 6127 are allowed. 6129 Examples: 6131 // legal values 6132 +4711 // legal positive value 6133 4711 // legal positive value 6134 -123 // legal negative value 6135 0xf00f // legal positive hexadecimal value 6136 -0xf // legal negative hexadecimal value 6137 052 // legal positive octal value 6139 // illegal values 6140 - 1 // illegal intermediate space 6142 9.2.2. Canonical Form 6144 The canonical form of a positive integer does not include the sign 6145 "+". Leading zeros are prohibited. The value zero is represented as 6146 "0". 6148 9.2.3. Restrictions 6150 All integer types can be restricted with the "range" statement 6151 (Section 9.2.4). 6153 9.2.4. The range Statement 6155 The "range" statement, which is an optional substatement to the 6156 "type" statement, takes as an argument a range expression string. It 6157 is used to restrict integer and decimal built-in types, or types 6158 derived from those. 6160 A range consists of an explicit value, or a lower-inclusive bound, 6161 two consecutive dots "..", and an upper-inclusive bound. Multiple 6162 values or ranges can be given, separated by "|". If multiple values 6163 or ranges are given, they all MUST be disjoint and MUST be in 6164 ascending order. If a range restriction is applied to an already 6165 range-restricted type, the new restriction MUST be equal or more 6166 limiting, that is raising the lower bounds, reducing the upper 6167 bounds, removing explicit values or ranges, or splitting ranges into 6168 multiple ranges with intermediate gaps. Each explicit value and 6169 range boundary value given in the range expression MUST match the 6170 type being restricted, or be one of the special values "min" or 6171 "max". "min" and "max" mean the minimum and maximum value accepted 6172 for the type being restricted, respectively. 6174 The range expression syntax is formally defined by the rule 6175 "range-arg" in Section 14. 6177 9.2.4.1. The range's Substatements 6179 +---------------+---------+-------------+ 6180 | substatement | section | cardinality | 6181 +---------------+---------+-------------+ 6182 | description | 7.21.3 | 0..1 | 6183 | error-app-tag | 7.5.4.2 | 0..1 | 6184 | error-message | 7.5.4.1 | 0..1 | 6185 | reference | 7.21.4 | 0..1 | 6186 +---------------+---------+-------------+ 6188 9.2.5. Usage Example 6190 typedef my-base-int32-type { 6191 type int32 { 6192 range "1..4 | 10..20"; 6193 } 6194 } 6196 typedef my-type1 { 6197 type my-base-int32-type { 6198 // legal range restriction 6199 range "11..max"; // 11..20 6200 } 6201 } 6203 typedef my-type2 { 6204 type my-base-int32-type { 6205 // illegal range restriction 6206 range "11..100"; 6207 } 6208 } 6210 9.3. The decimal64 Built-In Type 6212 The decimal64 type represents a subset of the real numbers, which can 6213 be represented by decimal numerals. The value space of decimal64 is 6214 the set of numbers that can be obtained by multiplying a 64-bit 6215 signed integer by a negative power of ten, i.e., expressible as "i x 6216 10^-n" where i is an integer64 and n is an integer between 1 and 18, 6217 inclusively. 6219 9.3.1. Lexical Representation 6221 A decimal64 value is lexically represented as an optional sign ("+" 6222 or "-"), followed by a sequence of decimal digits, optionally 6223 followed by a period ('.') as a decimal indicator and a sequence of 6224 decimal digits. If no sign is specified, "+" is assumed. 6226 9.3.2. Canonical Form 6228 The canonical form of a positive decimal64 does not include the sign 6229 "+". The decimal point is required. Leading and trailing zeros are 6230 prohibited, subject to the rule that there MUST be at least one digit 6231 before and after the decimal point. The value zero is represented as 6232 "0.0". 6234 9.3.3. Restrictions 6236 A decimal64 type can be restricted with the "range" statement 6237 (Section 9.2.4). 6239 9.3.4. The fraction-digits Statement 6241 The "fraction-digits" statement, which is a substatement to the 6242 "type" statement, MUST be present if the type is "decimal64". It 6243 takes as an argument an integer between 1 and 18, inclusively. It 6244 controls the size of the minimum difference between values of a 6245 decimal64 type, by restricting the value space to numbers that are 6246 expressible as "i x 10^-n" where n is the fraction-digits argument. 6248 The following table lists the minimum and maximum value for each 6249 fraction-digit value: 6251 +----------------+-----------------------+----------------------+ 6252 | fraction-digit | min | max | 6253 +----------------+-----------------------+----------------------+ 6254 | 1 | -922337203685477580.8 | 922337203685477580.7 | 6255 | 2 | -92233720368547758.08 | 92233720368547758.07 | 6256 | 3 | -9223372036854775.808 | 9223372036854775.807 | 6257 | 4 | -922337203685477.5808 | 922337203685477.5807 | 6258 | 5 | -92233720368547.75808 | 92233720368547.75807 | 6259 | 6 | -9223372036854.775808 | 9223372036854.775807 | 6260 | 7 | -922337203685.4775808 | 922337203685.4775807 | 6261 | 8 | -92233720368.54775808 | 92233720368.54775807 | 6262 | 9 | -9223372036.854775808 | 9223372036.854775807 | 6263 | 10 | -922337203.6854775808 | 922337203.6854775807 | 6264 | 11 | -92233720.36854775808 | 92233720.36854775807 | 6265 | 12 | -9223372.036854775808 | 9223372.036854775807 | 6266 | 13 | -922337.2036854775808 | 922337.2036854775807 | 6267 | 14 | -92233.72036854775808 | 92233.72036854775807 | 6268 | 15 | -9223.372036854775808 | 9223.372036854775807 | 6269 | 16 | -922.3372036854775808 | 922.3372036854775807 | 6270 | 17 | -92.23372036854775808 | 92.23372036854775807 | 6271 | 18 | -9.223372036854775808 | 9.223372036854775807 | 6272 +----------------+-----------------------+----------------------+ 6274 9.3.5. Usage Example 6276 typedef my-decimal { 6277 type decimal64 { 6278 fraction-digits 2; 6279 range "1 .. 3.14 | 10 | 20..max"; 6280 } 6281 } 6283 9.4. The string Built-In Type 6285 The string built-in type represents human-readable strings in YANG. 6286 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 6287 characters, including tab, carriage return, and line feed but 6288 excluding the other C0 control characters, the surrogate blocks, and 6289 the noncharacters. The string syntax is formally defined by the rule 6290 "yang-string" in Section 14. 6292 9.4.1. Lexical Representation 6294 A string value is lexically represented as character data in the XML 6295 encoding. 6297 9.4.2. Canonical Form 6299 The canonical form is the same as the lexical representation. No 6300 Unicode normalization is performed of string values. 6302 9.4.3. Restrictions 6304 A string can be restricted with the "length" (Section 9.4.4) and 6305 "pattern" (Section 9.4.5) statements. 6307 9.4.4. The length Statement 6309 The "length" statement, which is an optional substatement to the 6310 "type" statement, takes as an argument a length expression string. 6311 It is used to restrict the built-in types "string" and "binary" or 6312 types derived from them. 6314 A "length" statement restricts the number of Unicode characters in 6315 the string. 6317 A length range consists of an explicit value, or a lower bound, two 6318 consecutive dots "..", and an upper bound. Multiple values or ranges 6319 can be given, separated by "|". Length-restricting values MUST NOT 6320 be negative. If multiple values or ranges are given, they all MUST 6321 be disjoint and MUST be in ascending order. If a length restriction 6322 is applied to an already length-restricted type, the new restriction 6323 MUST be equal or more limiting, that is, raising the lower bounds, 6324 reducing the upper bounds, removing explicit length values or ranges, 6325 or splitting ranges into multiple ranges with intermediate gaps. A 6326 length value is a non-negative integer, or one of the special values 6327 "min" or "max". "min" and "max" mean the minimum and maximum length 6328 accepted for the type being restricted, respectively. An 6329 implementation is not required to support a length value larger than 6330 18446744073709551615. 6332 The length expression syntax is formally defined by the rule 6333 "length-arg" in Section 14. 6335 9.4.4.1. The length's Substatements 6337 +---------------+---------+-------------+ 6338 | substatement | section | cardinality | 6339 +---------------+---------+-------------+ 6340 | description | 7.21.3 | 0..1 | 6341 | error-app-tag | 7.5.4.2 | 0..1 | 6342 | error-message | 7.5.4.1 | 0..1 | 6343 | reference | 7.21.4 | 0..1 | 6344 +---------------+---------+-------------+ 6346 9.4.5. The pattern Statement 6348 The "pattern" statement, which is an optional substatement to the 6349 "type" statement, takes as an argument a regular expression string, 6350 as defined in [XSD-TYPES]. It is used to restrict the built-in type 6351 "string", or types derived from "string", to values that match the 6352 pattern. 6354 If the type has multiple "pattern" statements, the expressions are 6355 ANDed together, i.e., all such expressions have to match. 6357 If a pattern restriction is applied to an already pattern-restricted 6358 type, values must match all patterns in the base type, in addition to 6359 the new patterns. 6361 9.4.5.1. The pattern's Substatements 6363 +---------------+---------+-------------+ 6364 | substatement | section | cardinality | 6365 +---------------+---------+-------------+ 6366 | description | 7.21.3 | 0..1 | 6367 | error-app-tag | 7.5.4.2 | 0..1 | 6368 | error-message | 7.5.4.1 | 0..1 | 6369 | modifier | 9.4.6 | 0..1 | 6370 | reference | 7.21.4 | 0..1 | 6371 +---------------+---------+-------------+ 6373 9.4.6. The modifier Statement 6375 The "modifier" statement, which is an optional substatement to the 6376 "pattern" statement, takes as an argument the string "invert-match". 6378 If a pattern has the "invert-match" modifier present, the type is 6379 restricted to values that do not match the pattern. 6381 9.4.7. Usage Example 6383 With the following typedef: 6385 typedef my-base-str-type { 6386 type string { 6387 length "1..255"; 6388 } 6389 } 6391 the following refinement is legal: 6393 type my-base-str-type { 6394 // legal length refinement 6395 length "11 | 42..max"; // 11 | 42..255 6396 } 6398 and the following refinement is illegal: 6400 type my-base-str-type { 6401 // illegal length refinement 6402 length "1..999"; 6403 } 6405 With the following type: 6407 type string { 6408 length "0..4"; 6409 pattern "[0-9a-fA-F]*"; 6410 } 6412 the following strings match: 6414 AB // legal 6415 9A00 // legal 6417 and the following strings do not match: 6419 00ABAB // illegal, too long 6420 xx00 // illegal, bad characters 6422 With the following type: 6424 typedef yang-identifier { 6425 type string { 6426 length "1..max"; 6427 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 6428 pattern '[xX][mM][lL].*' { 6429 modifier invert-match; 6430 } 6431 } 6432 } 6434 the following string match: 6436 enabled // legal 6438 and the following strings do not match: 6440 10-mbit // illegal, starts with a number 6441 xml-element // illegal, starts with illegal sequence 6443 9.5. The boolean Built-In Type 6445 The boolean built-in type represents a boolean value. 6447 9.5.1. Lexical Representation 6449 The lexical representation of a boolean value is a string with a 6450 value of "true" or "false". These values MUST be in lowercase. 6452 9.5.2. Canonical Form 6454 The canonical form is the same as the lexical representation. 6456 9.5.3. Restrictions 6458 A boolean cannot be restricted. 6460 9.6. The enumeration Built-In Type 6462 The enumeration built-in type represents values from a set of 6463 assigned names. 6465 9.6.1. Lexical Representation 6467 The lexical representation of an enumeration value is the assigned 6468 name string. 6470 9.6.2. Canonical Form 6472 The canonical form is the assigned name string. 6474 9.6.3. Restrictions 6476 An enumeration can be restricted with one or more "enum" 6477 (Section 9.6.4) statements, which enumerate a subset of the values 6478 for the base type. 6480 9.6.4. The enum Statement 6482 The "enum" statement, which is a substatement to the "type" 6483 statement, MUST be present if the type is "enumeration". It is 6484 repeatedly used to specify each assigned name of an enumeration type. 6485 It takes as an argument a string which is the assigned name. The 6486 string MUST NOT be zero-length and MUST NOT have any leading or 6487 trailing whitespace characters (any Unicode character with the 6488 "White_Space" property). The use of Unicode control codes SHOULD be 6489 avoided. 6491 The statement is optionally followed by a block of substatements that 6492 holds detailed enum information. 6494 All assigned names in an enumeration MUST be unique. 6496 When an existing enumeration type is restricted, the set of assigned 6497 names in the new type MUST be a subset of the base type's set of 6498 assigned names. The value of such an assigned name MUST NOT be 6499 changed. 6501 9.6.4.1. The enum's Substatements 6503 +--------------+---------+-------------+ 6504 | substatement | section | cardinality | 6505 +--------------+---------+-------------+ 6506 | description | 7.21.3 | 0..1 | 6507 | if-feature | 7.20.2 | 0..n | 6508 | reference | 7.21.4 | 0..1 | 6509 | status | 7.21.2 | 0..1 | 6510 | value | 9.6.4.2 | 0..1 | 6511 +--------------+---------+-------------+ 6513 9.6.4.2. The value Statement 6515 The "value" statement, which is optional, is used to associate an 6516 integer value with the assigned name for the enum. This integer 6517 value MUST be in the range -2147483648 to 2147483647, and it MUST be 6518 unique within the enumeration type. 6520 If a value is not specified, then one will be automatically assigned. 6521 If the "enum" substatement is the first one defined, the assigned 6522 value is zero (0); otherwise, the assigned value is one greater than 6523 the current highest enum value (i.e., the highest enum value, 6524 implicit or explicit, prior to the current "enum" substatement in the 6525 parent "type" statement). 6527 Note that the the presence of an "if-feature" statement in an "enum" 6528 statement does not affect the automatically assigned value. 6530 If the current highest value is equal to 2147483647, then an enum 6531 value MUST be specified for "enum" substatements following the one 6532 with the current highest value. 6534 When an existing enumeration type is restricted, the "value" 6535 statement MUST either have the same value as in the base type or not 6536 be present, in which case the value is the same as in the base type. 6538 9.6.5. Usage Example 6540 leaf myenum { 6541 type enumeration { 6542 enum zero; 6543 enum one; 6544 enum seven { 6545 value 7; 6546 } 6547 } 6548 } 6550 The lexical representation of the leaf "myenum" with value "seven" 6551 is: 6553 seven 6555 With the following typedef: 6557 typedef my-base-enumeration-type { 6558 type enumeration { 6559 enum white { 6560 value 1; 6561 } 6562 enum yellow { 6563 value 2; 6564 } 6565 enum red { 6566 value 3; 6567 } 6568 } 6569 } 6571 the following refinement is legal: 6573 type my-base-enumeration-type { 6574 // legal enum refinement 6575 enum yellow; 6576 enum red { 6577 value 3; 6578 } 6579 } 6581 and the following refinement is illegal: 6583 type my-base-enumeration-type { 6584 // illegal enum refinement 6585 enum yellow { 6586 value 4; // illegal value change 6587 } 6588 enum black; // illegal addition of new name 6589 } 6591 The following example shows how an "enum" can be tagged with 6592 "if-feature", making the value legal only on servers that advertise 6593 the corresponding feature: 6595 type enumeration { 6596 enum tcp; 6597 enum ssh { 6598 if-feature ssh; 6599 } 6600 enum tls { 6601 if-feature tls; 6602 } 6603 } 6605 9.7. The bits Built-In Type 6607 The bits built-in type represents a bit set. That is, a bits value 6608 is a set of flags identified by small integer position numbers 6609 starting at 0. Each bit number has an assigned name. 6611 When an existing bits type is restricted, the set of assigned names 6612 in the new type MUST be a subset of the base type's set of assigned 6613 names. The bit position of such an assigned name MUST NOT be 6614 changed. 6616 9.7.1. Restrictions 6618 A bits type can be restricted with the "bit" (Section 9.7.4) 6619 statement. 6621 9.7.2. Lexical Representation 6623 The lexical representation of the bits type is a space-separated list 6624 of the names of the bits that are set. A zero-length string thus 6625 represents a value where no bits are set. 6627 9.7.3. Canonical Form 6629 In the canonical form, the bit values are separated by a single space 6630 character and they appear ordered by their position (see 6631 Section 9.7.4.2). 6633 9.7.4. The bit Statement 6635 The "bit" statement, which is a substatement to the "type" statement, 6636 MUST be present if the type is "bits". It is repeatedly used to 6637 specify each assigned named bit of a bits type. It takes as an 6638 argument a string that is the assigned name of the bit. It is 6639 followed by a block of substatements that holds detailed bit 6640 information. The assigned name follows the same syntax rules as an 6641 identifier (see Section 6.2). 6643 All assigned names in a bits type MUST be unique. 6645 9.7.4.1. The bit's Substatements 6647 +--------------+---------+-------------+ 6648 | substatement | section | cardinality | 6649 +--------------+---------+-------------+ 6650 | description | 7.21.3 | 0..1 | 6651 | if-feature | 7.20.2 | 0..n | 6652 | reference | 7.21.4 | 0..1 | 6653 | status | 7.21.2 | 0..1 | 6654 | position | 9.7.4.2 | 0..1 | 6655 +--------------+---------+-------------+ 6657 9.7.4.2. The position Statement 6659 The "position" statement, which is optional, takes as an argument a 6660 non-negative integer value that specifies the bit's position within a 6661 hypothetical bit field. The position value MUST be in the range 0 to 6662 4294967295, and it MUST be unique within the bits type. 6664 If a bit position is not specified, then one will be automatically 6665 assigned. If the "bit" substatement is the first one defined, the 6666 assigned value is zero (0); otherwise, the assigned value is one 6667 greater than the current highest bit position (i.e., the highest bit 6668 position, implicit or explicit, prior to the current "bit" 6669 substatement in the parent "type" statement). 6671 Note that the the presence of an "if-feature" statement in an "bit" 6672 statement does not affect the automatically assigned position. 6674 If the current highest bit position value is equal to 4294967295, 6675 then a position value MUST be specified for "bit" substatements 6676 following the one with the current highest position value. 6678 When an existing bits type is restricted, the "position" statement 6679 MUST either have the same value as in the base type or not be 6680 present, in which case the value is the same as in the base type. 6682 9.7.5. Usage Example 6684 Given the following typedef and leaf: 6686 typedef mybits-type { 6687 type bits { 6688 bit disable-nagle { 6689 position 0; 6690 } 6691 bit auto-sense-speed { 6692 position 1; 6693 } 6694 bit ten-mb-only { 6695 position 2; 6696 } 6697 } 6698 } 6700 leaf mybits { 6701 type mybits-type; 6702 default "auto-sense-speed"; 6703 } 6705 The lexical representation of this leaf with bit values disable-nagle 6706 and ten-mb-only set would be: 6708 disable-nagle ten-mb-only 6710 The following example shows a legal refinement of this type: 6712 type mybits-type { 6713 // legal bit refinement 6714 bit disable-nagle { 6715 position 0; 6716 } 6717 bit auto-sense-speed { 6718 position 1; 6719 } 6720 } 6722 and the following refinement is illegal: 6724 type mybits-type { 6725 // illegal bit refinement 6726 bit disable-nagle { 6727 position 2; // illegal position change 6728 } 6729 bit hundred-mb-only; // illegal addition of new name 6730 } 6732 9.8. The binary Built-In Type 6734 The binary built-in type represents any binary data, i.e., a sequence 6735 of octets. 6737 9.8.1. Restrictions 6739 A binary type can be restricted with the "length" (Section 9.4.4) 6740 statement. The length of a binary value is the number of octets it 6741 contains. 6743 9.8.2. Lexical Representation 6745 Binary values are encoded with the base64 encoding scheme (see 6746 [RFC4648], Section 4). 6748 9.8.3. Canonical Form 6750 The canonical form of a binary value follows the rules of "Base 64 6751 Encoding" in [RFC4648]. 6753 9.9. The leafref Built-In Type 6755 The leafref type is restricted to the value space of some leaf or 6756 leaf-list node in the schema tree and optionally further restricted 6757 by corresponding instance nodes in the data tree. The "path" 6758 substatement (Section 9.9.2) is used to identify the referred leaf or 6759 leaf-list node in the schema tree. The value space of the referring 6760 node is the value space of the referred node. 6762 If the "require-instance" property (Section 9.9.3) is "true", there 6763 MUST exist an node in the data tree, or a node with a default value 6764 in use (see Section 7.6.1 and Section 7.7.2), of the referred schema 6765 tree leaf or leaf-list node with the same value as the leafref value 6766 in a valid data tree. 6768 If the referring node represents configuration data, and the 6769 "require-instance" property (Section 9.9.3) is "true", the referred 6770 node MUST also represent configuration. 6772 There MUST NOT be any circular chains of leafrefs. 6774 If the leaf that the leafref refers to is conditional based on one or 6775 more features (see Section 7.20.2), then the leaf with the leafref 6776 type MUST also be conditional based on at least the same set of 6777 features. 6779 9.9.1. Restrictions 6781 A leafref can be restricted with the "require-instance" statement 6782 (Section 9.9.3). 6784 9.9.2. The path Statement 6786 The "path" statement, which is a substatement to the "type" 6787 statement, MUST be present if the type is "leafref". It takes as an 6788 argument a string that MUST refer to a leaf or leaf-list node. 6790 The syntax for a path argument is a subset of the XPath abbreviated 6791 syntax. Predicates are used only for constraining the values for the 6792 key nodes for list entries. Each predicate consists of exactly one 6793 equality test per key, and multiple adjacent predicates MAY be 6794 present if a list has multiple keys. The syntax is formally defined 6795 by the rule "path-arg" in Section 14. 6797 The predicates are only used when more than one key reference is 6798 needed to uniquely identify a leaf instance. This occurs if a list 6799 has multiple keys, or a reference to a leaf other than the key in a 6800 list is needed. In these cases, multiple leafrefs are typically 6801 specified, and predicates are used to tie them together. 6803 The "path" expression evaluates to a node set consisting of zero, 6804 one, or more nodes. If the leaf with the leafref type represents 6805 configuration data, this node set MUST be non-empty. 6807 The "path" XPath expression is conceptually evaluated in the 6808 following context, in addition to the definition in Section 6.4.1: 6810 o If the "path" statement is defined within a typedef, the context 6811 node is the leaf or leaf-list node in the data tree that 6812 references the typedef. 6814 o Otherwise, the context node is the node in the data tree for which 6815 the "path" statement is defined. 6817 9.9.3. The require-instance Statement 6819 The "require-instance" statement, which is a substatement to the 6820 "type" statement, MAY be present if the type is "instance-identifier" 6821 or "leafref". It takes as an argument the string "true" or "false". 6822 If this statement is not present, it defaults to "true". 6824 If "require-instance" is "true", it means that the instance being 6825 referred to MUST exist for the data to be valid. This constraint is 6826 enforced according to the rules in Section 8. 6828 If "require-instance" is "false", it means that the instance being 6829 referred to MAY exist in valid data. 6831 9.9.4. Lexical Representation 6833 A leafref value is lexically represented the same way as the leaf it 6834 references represents its value. 6836 9.9.5. Canonical Form 6838 The canonical form of a leafref is the same as the canonical form of 6839 the leaf it references. 6841 9.9.6. Usage Example 6843 With the following list: 6845 list interface { 6846 key "name"; 6847 leaf name { 6848 type string; 6849 } 6850 leaf admin-status { 6851 type admin-status; 6852 } 6853 list address { 6854 key "ip"; 6855 leaf ip { 6856 type yang:ip-address; 6857 } 6858 } 6859 } 6861 The following leafref refers to an existing interface: 6863 leaf mgmt-interface { 6864 type leafref { 6865 path "../interface/name"; 6866 } 6867 } 6869 An example of a corresponding XML snippet: 6871 6872 eth0 6873 6874 6875 lo 6876 6878 eth0 6880 The following leafrefs refer to an existing address of an interface: 6882 container default-address { 6883 leaf ifname { 6884 type leafref { 6885 path "../../interface/name"; 6886 } 6887 } 6888 leaf address { 6889 type leafref { 6890 path "../../interface[name = current()/../ifname]" 6891 + "/address/ip"; 6892 } 6893 } 6894 } 6896 An example of a corresponding XML snippet: 6898 6899 eth0 6900 up 6901
6902 192.0.2.1 6903
6904
6905 192.0.2.2 6906
6907 6908 6909 lo 6910 up 6911
6912 127.0.0.1 6913
6914 6916 6917 eth0 6918
192.0.2.2
6919 6921 The following list uses a leafref for one of its keys. This is 6922 similar to a foreign key in a relational database. 6924 list packet-filter { 6925 key "if-name filter-id"; 6926 leaf if-name { 6927 type leafref { 6928 path "/interface/name"; 6929 } 6930 } 6931 leaf filter-id { 6932 type uint32; 6933 } 6934 ... 6935 } 6937 An example of a corresponding XML snippet: 6939 6940 eth0 6941 up 6942
6943 192.0.2.1 6944
6945
6946 192.0.2.2 6947
6948 6950 6951 eth0 6952 1 6953 ... 6954 6955 6956 eth0 6957 2 6958 ... 6959 6961 The following notification defines two leafrefs to refer to an 6962 existing admin-status: 6964 notification link-failure { 6965 leaf if-name { 6966 type leafref { 6967 path "/interface/name"; 6968 } 6969 } 6970 leaf admin-status { 6971 type leafref { 6972 path "/interface[name = current()/../if-name]" 6973 + "/admin-status"; 6974 } 6975 } 6976 } 6978 An example of a corresponding XML notification: 6980 6982 2008-04-01T00:01:00Z 6983 6984 eth0 6985 up 6986 6987 6989 9.10. The identityref Built-In Type 6991 The identityref type is used to reference an existing identity (see 6992 Section 7.18). 6994 9.10.1. Restrictions 6996 An identityref cannot be restricted. 6998 9.10.2. The identityref's base Statement 7000 The "base" statement, which is a substatement to the "type" 7001 statement, MUST be present at least once if the type is 7002 "identityref". The argument is the name of an identity, as defined 7003 by an "identity" statement. If a prefix is present on the identity 7004 name, it refers to an identity defined in the module that was 7005 imported with that prefix. Otherwise, an identity with the matching 7006 name MUST be defined in the current module or an included submodule. 7008 Valid values for an identityref are any identities derived from all 7009 the identityref's base identities. On a particular server, the valid 7010 values are further restricted to the set of identities defined in the 7011 modules implemented by the server. 7013 9.10.3. Lexical Representation 7015 An identityref is lexically represented as the referred identity's 7016 qualified name as defined in [XML-NAMES]. If the prefix is not 7017 present, the namespace of the identityref is the default namespace in 7018 effect on the element that contains the identityref value. 7020 When an identityref is given a default value using the "default" 7021 statement, the identity name in the default value MAY have a prefix. 7022 If a prefix is present on the identity name, it refers to an identity 7023 defined in the module that was imported with that prefix, or the 7024 prefix for the current module if the identity is defined in the 7025 current module or one of its submodules. Otherwise, an identity with 7026 the matching name MUST be defined in the current module or one of its 7027 submodules. 7029 The string value of a node of type identityref in a "must" or "when" 7030 XPath expression is the referred identity's qualified name with the 7031 prefix present. If the referred identity is defined in an imported 7032 module, the prefix in the string value is the prefix defined in the 7033 corresponding "import" statement. Otherwise, the prefix in the 7034 string value is the prefix for the current module. 7036 9.10.4. Canonical Form 7038 Since the lexical form depends on the XML context in which the value 7039 occurs, this type does not have a canonical form. 7041 9.10.5. Usage Example 7043 With the identity definitions in Section 7.18.3 and the following 7044 module: 7046 module example-my-crypto { 7047 yang-version 1.1; 7048 namespace "urn:example:my-crypto"; 7049 prefix mc; 7051 import "example-crypto-base" { 7052 prefix "crypto"; 7053 } 7055 identity aes { 7056 base "crypto:crypto-alg"; 7057 } 7059 leaf crypto { 7060 type identityref { 7061 base "crypto:crypto-alg"; 7062 } 7063 } 7065 container aes-parameters { 7066 when "../crypto = 'mc:aes'"; 7067 ... 7068 } 7069 } 7071 the following is an example how the leaf "crypto" can be encoded, if 7072 the value is the "des3" identity defined in the "des" module: 7074 des:des3 7076 Any prefixes used in the encoding are local to each instance 7077 encoding. This means that the same identityref may be encoded 7078 differently by different implementations. For example, the following 7079 example encodes the same leaf as above: 7081 x:des3 7083 If the "crypto" leaf's value instead is "aes" defined in the 7084 "example-my-crypto" module, it can be encoded as: 7086 mc:aes 7088 or, using the default namespace: 7090 aes 7092 9.11. The empty Built-In Type 7094 The empty built-in type represents a leaf that does not have any 7095 value, it conveys information by its presence or absence. 7097 An empty type cannot have a default value. 7099 9.11.1. Restrictions 7101 An empty type cannot be restricted. 7103 9.11.2. Lexical Representation 7105 Not applicable. 7107 9.11.3. Canonical Form 7109 Not applicable. 7111 9.11.4. Usage Example 7113 With the following leaf 7115 leaf enable-qos { 7116 type empty; 7117 } 7119 the following is an example of a valid encoding 7121 7123 if the leaf exists. 7125 9.12. The union Built-In Type 7127 The union built-in type represents a value that corresponds to one of 7128 its member types. 7130 When the type is "union", the "type" statement (Section 7.4) MUST be 7131 present. It is repeatedly used to specify each member type of the 7132 union. It takes as an argument a string that is the name of a member 7133 type. 7135 A member type can be of any built-in or derived type. 7137 When generating an XML encoding, a value is encoded according to the 7138 rules of the member type to which the value belongs. When 7139 interpreting an XML encoding, a value is validated consecutively 7140 against each member type, in the order they are specified in the 7141 "type" statement, until a match is found. The type that matched will 7142 be the type of the value for the node that was validated, and the 7143 encoding is interpreted according to the rules for that type. 7145 Any default value or "units" property defined in the member types is 7146 not inherited by the union type. 7148 9.12.1. Restrictions 7150 A union cannot be restricted. However, each member type can be 7151 restricted, based on the rules defined in Section 9. 7153 9.12.2. Lexical Representation 7155 The lexical representation of a union is a value that corresponds to 7156 the representation of any one of the member types. 7158 9.12.3. Canonical Form 7160 The canonical form of a union value is the same as the canonical form 7161 of the member type of the value. 7163 9.12.4. Usage Example 7165 The following is a union of an int32 and an enumeration: 7167 type union { 7168 type int32; 7169 type enumeration { 7170 enum "unbounded"; 7171 } 7172 } 7174 Care must be taken when a member type is a leafref where the 7175 "require-instance" property (Section 9.9.3) is "true". If a leaf of 7176 such a type refers to an existing instance, the leaf's value must be 7177 re-validated if the target instance is deleted. For example, with 7178 the following definitions: 7180 list filter { 7181 key name; 7182 leaf name { 7183 type string; 7184 } 7185 ... 7186 } 7188 leaf outbound-filter { 7189 type union { 7190 type leafref { 7191 path "/filter/name"; 7192 } 7193 type enumeration { 7194 enum default-filter; 7195 } 7196 } 7197 } 7199 assume that there exists an entry in the filter list with the name 7200 "http", and that the outbound-filter leaf has this value: 7202 7203 http 7204 7205 http 7207 If the filter entry "http" is removed, the outbound-filter leaf's 7208 value doesn't match the leafref, and the next member type is checked. 7209 The current value ("http") doesn't match the enumeration, so the 7210 resulting configuration is invalid. 7212 If the second member type in the union had been of type "string" 7213 instead of an enumeration, the current value would have matched, and 7214 the resulting configuration would have been valid. 7216 9.13. The instance-identifier Built-In Type 7218 The instance-identifier built-in type is used to uniquely identify a 7219 particular instance node in the data tree. 7221 The syntax for an instance-identifier is a subset of the XPath 7222 abbreviated syntax, formally defined by the rule 7223 "instance-identifier" in Section 14. It is used to uniquely identify 7224 a node in the data tree. Predicates are used only for specifying the 7225 values for the key nodes for list entries, a value of a leaf-list 7226 entry, or a positional index for a list without keys. For 7227 identifying list entries with keys, each predicate consists of one 7228 equality test per key, and each key MUST have a corresponding 7229 predicate. If a key is of type "empty", it is represented as a zero- 7230 length string (""). 7232 If the leaf with the instance-identifier type represents 7233 configuration data, and the "require-instance" property 7234 (Section 9.9.3) is "true", the node it refers to MUST also represent 7235 configuration. Such a leaf puts a constraint on valid data. All 7236 such leaf nodes MUST reference existing nodes or leaf or leaf-list 7237 nodes with their default value in use (see Section 7.6.1 and 7238 Section 7.7.2) for the data to be valid. This constraint is enforced 7239 according to the rules in Section 8. 7241 The "instance-identifier" XPath expression is conceptually evaluated 7242 in the following context, in addition to the definition in 7243 Section 6.4.1: 7245 o The context node is the root node in the accessible tree. 7247 9.13.1. Restrictions 7249 An instance-identifier can be restricted with the "require-instance" 7250 statement (Section 9.9.3). 7252 9.13.2. Lexical Representation 7254 An instance-identifier value is lexically represented as a string. 7255 All node names in an instance-identifier value MUST be qualified with 7256 explicit namespace prefixes, and these prefixes MUST be declared in 7257 the XML namespace scope in the instance-identifier's XML element. 7259 Any prefixes used in the encoding are local to each instance 7260 encoding. This means that the same instance-identifier may be 7261 encoded differently by different implementations. 7263 9.13.3. Canonical Form 7265 Since the lexical form depends on the XML context in which the value 7266 occurs, this type does not have a canonical form. 7268 9.13.4. Usage Example 7270 The following are examples of instance identifiers: 7272 /* instance-identifier for a container */ 7273 /ex:system/ex:services/ex:ssh 7275 /* instance-identifier for a leaf */ 7276 /ex:system/ex:services/ex:ssh/ex:port 7278 /* instance-identifier for a list entry */ 7279 /ex:system/ex:user[ex:name='fred'] 7281 /* instance-identifier for a leaf in a list entry */ 7282 /ex:system/ex:user[ex:name='fred']/ex:type 7284 /* instance-identifier for a list entry with two keys */ 7285 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 7287 /* instance-identifier for a list entry where the second 7288 key ("enabled") is of type empty */ 7289 /ex:system/ex:service[ex:name='foo'][ex:enabled=''] 7291 /* instance-identifier for a leaf-list entry */ 7292 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 7294 /* instance-identifier for a list entry without keys */ 7295 /ex:stats/ex:port[3] 7297 10. XPath Functions 7299 This document defines two generic XPath functions and five YANG type- 7300 specific XPath functions. The function signatures are specified with 7301 the syntax used in [XPATH]. 7303 10.1. Functions for Node Sets 7305 10.1.1. current() 7307 node-set current() 7309 The function current() takes no input parameters, and returns a node 7310 set with the initial context node as its only member. 7312 10.1.1.1. Usage Example 7314 With this list: 7316 list interface { 7317 key "name"; 7318 ... 7319 leaf enabled { 7320 type boolean; 7321 } 7322 ... 7323 } 7325 the following leaf defines a must expression that ensures that the 7326 referred interface is enabled: 7328 leaf outgoing-interface { 7329 type leafref { 7330 path "/interface/name"; 7331 } 7332 must '/interface[name=current()]/enabled = "true"'; 7333 } 7335 10.2. Functions for Strings 7337 10.2.1. re-match() 7339 boolean re-match(string subject, string pattern) 7341 The re-match() function returns "true" if the "subject" string 7342 matches the regular expression "pattern"; otherwise it returns 7343 "false". 7345 The function "re-match" checks if a string matches a given regular 7346 expression. The regular expressions used are the XML Schema regular 7347 expressions [XSD-TYPES]. Note that this includes implicit anchoring 7348 of the regular expression at the head and tail. 7350 10.2.1.1. Usage Example 7352 The expression: 7354 re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}") 7356 returns "true". 7358 To count all logical interfaces called eth0., do: 7360 count(/interface[re-match(name, "eth0\.\d+")]) 7362 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 7364 10.3.1. deref() 7366 node-set deref(node-set nodes) 7368 The deref() function follows the reference defined by the first node 7369 in document order in the argument "nodes", and returns the nodes it 7370 refers to. 7372 If the first argument node is of type instance-identifier, the 7373 function returns a node set that contains the single node that the 7374 instance identifier refers to, if it exists. If no such node exists, 7375 an empty node-set is returned. 7377 If the first argument node is of type leafref, the function returns a 7378 node set that contains the nodes that the leafref refers to. 7379 Specifically, this set contains the nodes selected by the leafref's 7380 "path" statement (Section 9.9.2) that have the same value as the 7381 first argument node. 7383 If the first argument node is of any other type, an empty node set is 7384 returned. 7386 10.3.1.1. Usage Example 7387 list interface { 7388 key "name type"; 7389 leaf name { ... } 7390 leaf type { ... } 7391 leaf enabled { 7392 type boolean; 7393 } 7394 ... 7395 } 7397 container mgmt-interface { 7398 leaf name { 7399 type leafref { 7400 path "/interface/name"; 7401 } 7402 } 7403 leaf type { 7404 type leafref { 7405 path "/interface[name=current()/../name]/type"; 7406 } 7407 must 'deref(.)/../enabled = "true"' { 7408 error-message 7409 "The management interface cannot be disabled."; 7410 } 7411 } 7412 } 7414 10.4. Functions for the YANG Type "identityref" 7416 10.4.1. derived-from() 7418 boolean derived-from(node-set nodes, string identity) 7420 The derived-from() function returns "true" if any node in the 7421 argument "nodes" is a node of type identityref, and its value is an 7422 identity that is derived from (see Section 7.18.2) the identity 7423 "identity"; otherwise it returns "false". 7425 The parameter "identity" is a string matching the rule 7426 "identifier-ref" in Section 14. If a prefix is present on the 7427 identity, it refers to an identity defined in the module that was 7428 imported with that prefix, or the local module if the prefix matches 7429 the local module's prefix. If no prefix is present, the identity 7430 refers to an identity defined in the current module or an included 7431 submodule. 7433 10.4.1.1. Usage Example 7435 module example-interface { 7436 yang-version 1.1; 7438 ... 7439 identity interface-type; 7441 identity ethernet { 7442 base interface-type; 7443 } 7445 identity fast-ethernet { 7446 base ethernet; 7447 } 7449 identity gigabit-ethernet { 7450 base ethernet; 7451 } 7453 list interface { 7454 key name; 7455 ... 7456 leaf type { 7457 type identityref { 7458 base interface-type; 7459 } 7460 } 7461 ... 7462 } 7464 augment "/interface" { 7465 when 'derived-from(type, "exif:ethernet")'; 7466 // generic ethernet definitions here 7467 } 7468 ... 7469 } 7471 10.4.2. derived-from-or-self() 7473 boolean derived-from-or-self(node-set nodes, string identity) 7475 The derived-from-or-self() function returns "true" if any node in the 7476 argument "nodes" is a node of type identityref, and its value is an 7477 identity that is equal to or derived from (see Section 7.18.2) the 7478 identity "identity"; otherwise it returns "false". 7480 The parameter "identity" is a string matching the rule 7481 "identifier-ref" in Section 14. If a prefix is present on the 7482 identity, it refers to an identity defined in the module that was 7483 imported with that prefix, or the local module if the prefix matches 7484 the local module's prefix. If no prefix is present, the identity 7485 refers to an identity defined in the current module or an included 7486 submodule. 7488 10.4.2.1. Usage Example 7490 The module defined in Section 10.4.1.1 might also have: 7492 augment "/interface" { 7493 when 'derived-from-or-self(type, "exif:fast-ethernet"); 7494 // fast-ethernet-specific definitions here 7495 } 7497 10.5. Functions for the YANG Type "enumeration" 7499 10.5.1. enum-value() 7501 number enum-value(node-set nodes) 7503 The enum-value() function checks if the first node in document order 7504 in the argument "nodes" is a node of type enumeration, and returns 7505 the enum's integer value. If the "nodes" node set is empty, or if 7506 the first node in "nodes" is not of type enumeration, it returns NaN. 7508 10.5.1.1. Usage Example 7510 With this data model: 7512 list alarm { 7513 ... 7514 leaf severity { 7515 type enumeration { 7516 enum cleared { 7517 value 1; 7518 } 7519 enum indeterminate { 7520 value 2; 7521 } 7522 enum minor { 7523 value 3; 7524 } 7525 enum warning { 7526 value 4; 7527 } 7528 enum major { 7529 value 5; 7530 } 7531 enum critical { 7532 value 6; 7533 } 7534 } 7535 } 7536 } 7538 the following XPath expression selects only alarms that are of 7539 severity "major" or higher: 7541 /alarm[enum-value(severity) >= 5] 7543 10.6. Functions for the YANG Type "bits" 7545 10.6.1. bit-is-set() 7547 boolean bit-is-set(node-set nodes, string bit-name) 7549 The bit-is-set() function returns "true" if the first node in 7550 document order in the argument "nodes" is a node of type bits, and 7551 its value has the bit "'bit-name" set; otherwise it returns "false". 7553 10.6.1.1. Usage Example 7555 If an interface has this leaf: 7557 leaf flags { 7558 type bits { 7559 bit UP; 7560 bit PROMISCUOUS 7561 bit DISABLED; 7562 } 7563 } 7565 the following XPath expression can be used to select all interfaces 7566 with the UP flag set: 7568 /interface[bit-is-set(flags, "UP")] 7570 11. Updating a Module 7572 As experience is gained with a module, it may be desirable to revise 7573 that module. However, changes to published modules are not allowed 7574 if they have any potential to cause interoperability problems between 7575 a client using an original specification and a server using an 7576 updated specification. 7578 For any published change, a new "revision" statement (Section 7.1.9) 7579 MUST be included in front of the existing "revision" statements. If 7580 there are no existing "revision" statements, then one MUST be added 7581 to identify the new revision. Furthermore, any necessary changes 7582 MUST be applied to any meta-data statements, including the 7583 "organization" and "contact" statements (Section 7.1.7, 7584 Section 7.1.8). 7586 Note that definitions contained in a module are available to be 7587 imported by any other module, and are referenced in "import" 7588 statements via the module name. Thus, a module name MUST NOT be 7589 changed. Furthermore, the "namespace" statement MUST NOT be changed, 7590 since all XML elements are qualified by the namespace. 7592 Obsolete definitions MUST NOT be removed from published modules since 7593 their identifiers may still be referenced by other modules. 7595 A definition in a published module may be revised in any of the 7596 following ways: 7598 o An "enumeration" type may have new enums added, provided the old 7599 enums's values do not change. Note that inserting a new enum 7600 before an existing enum or reordering existing enums will result 7601 in new values for the existing enums, unless they have explicit 7602 values assigned to them. 7604 o A "bits" type may have new bits added, provided the old bit 7605 positions do not change. Note that inserting a new bit before an 7606 existing bit or reordering existing bit will result in new 7607 positions for the existing bits, unless they have explicit 7608 positions assigned to them. 7610 o A "range", "length", or "pattern" statement may expand the allowed 7611 value space. 7613 o A "default" statement may be added to a leaf that does not have a 7614 default value (either directly or indirectly through its type). 7616 o A "units" statement may be added. 7618 o A "reference" statement may be added or updated. 7620 o A "must" statement may be removed or its constraint relaxed. 7622 o A "when" statement may be removed or its constraint relaxed. 7624 o A "mandatory" statement may be removed or changed from "true" to 7625 "false". 7627 o A "min-elements" statement may be removed, or changed to require 7628 fewer elements. 7630 o A "max-elements" statement may be removed, or changed to allow 7631 more elements. 7633 o A "description" statement may be added or changed without changing 7634 the semantics of the definition. 7636 o A "base" statement may be added to an "identity" statement. 7638 o A "base" statement may be removed from an "identityref" type, 7639 provided there is at least one "base" statement left. 7641 o New typedefs, groupings, rpcs, notifications, extensions, 7642 features, and identities may be added. 7644 o New data definition statements may be added if they do not add 7645 mandatory nodes (Section 3) to existing nodes or at the top level 7646 in a module or submodule, or if they are conditionally dependent 7647 on a new feature (i.e., have an "if-feature" statement that refers 7648 to a new feature). 7650 o A new "case" statement may be added. 7652 o A node that represented state data may be changed to represent 7653 configuration, provided it is not mandatory (Section 3). 7655 o An "if-feature" statement may be removed, provided its node is not 7656 mandatory (Section 3). 7658 o A "status" statement may be added, or changed from "current" to 7659 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 7661 o A "type" statement may be replaced with another "type" statement 7662 that does not change the syntax or semantics of the type. For 7663 example, an inline type definition may be replaced with a typedef, 7664 but an int8 type cannot be replaced by an int16, since the syntax 7665 would change. 7667 o Any set of data definition nodes may be replaced with another set 7668 of syntactically and semantically equivalent nodes. For example, 7669 a set of leafs may be replaced by a uses of a grouping with the 7670 same leafs. 7672 o A module may be split into a set of submodules, or a submodule may 7673 be removed, provided the definitions in the module do not change 7674 in any other way than allowed here. 7676 o The "prefix" statement may be changed, provided all local uses of 7677 the prefix also are changed. 7679 Otherwise, if the semantics of any previous definition are changed 7680 (i.e., if a non-editorial change is made to any definition other than 7681 those specifically allowed above), then this MUST be achieved by a 7682 new definition with a new identifier. 7684 In statements that have any data definition statements as 7685 substatements, those data definition substatements MUST NOT be 7686 reordered. If new data definition statements are added, they can be 7687 added anywhere in the sequence of existing substatement. 7689 12. Coexistence with YANG version 1 7691 A YANG version 1.1 module MUST NOT include a YANG version 1 7692 submodule, and a YANG version 1 module MUST NOT include a YANG 7693 version 1.1 submodule. 7695 A YANG version 1 module or submodule MUST NOT import a YANG version 7696 1.1 module by revision. 7698 A YANG version 1.1 module or submodule MAY import a YANG version 1 7699 module by revision. 7701 If a YANG version 1 module A imports module B without revision, and 7702 module B is updated to YANG version 1.1, a server MAY implement both 7703 these modules (A and B) at the same time. In such cases, a NETCONF 7704 server MUST advertise both modules using the rules defined in 7705 Section 5.6.4, and SHOULD advertise module A and the latest revision 7706 of module B that is specified with YANG version 1 according to the 7707 rules defined in [RFC6020]. 7709 This rule exists in order to allow implementations of existing YANG 7710 version 1 modules together with YANG version 1.1 modules. Without 7711 this rule, updating a single module to YANG version 1.1 would have a 7712 cascading effect on modules that import it, requiring all of them to 7713 also be updated to YANG version 1.1, and so on. 7715 13. YIN 7717 A YANG module can be translated into an alternative XML-based syntax 7718 called YIN. The translated module is called a YIN module. This 7719 section describes bidirectional mapping rules between the two 7720 formats. 7722 The YANG and YIN formats contain equivalent information using 7723 different notations. The YIN notation enables developers to 7724 represent YANG data models in XML and therefore use the rich set of 7725 XML-based tools for data filtering and validation, automated 7726 generation of code and documentation, and other tasks. Tools like 7727 XSLT or XML validators can be utilized. 7729 The mapping between YANG and YIN does not modify the information 7730 content of the model. Comments and whitespace are not preserved. 7732 13.1. Formal YIN Definition 7734 There is a one-to-one correspondence between YANG keywords and YIN 7735 elements. The local name of a YIN element is identical to the 7736 corresponding YANG keyword. This means, in particular, that the 7737 document element (root) of a YIN document is always or 7738 . 7740 YIN elements corresponding to the YANG keywords belong to the 7741 namespace whose associated URI is 7742 "urn:ietf:params:xml:ns:yang:yin:1". 7744 YIN elements corresponding to extension keywords belong to the 7745 namespace of the YANG module where the extension keyword is declared 7746 via the "extension" statement. 7748 The names of all YIN elements MUST be properly qualified with their 7749 namespaces specified above using the standard mechanisms of 7750 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 7752 The argument of a YANG statement is represented in YIN either as an 7753 XML attribute or a subelement of the keyword element. Table 1 7754 defines the mapping for the set of YANG keywords. For extensions, 7755 the argument mapping is specified within the "extension" statement 7756 (see Section 7.19). The following rules hold for arguments: 7758 o If the argument is represented as an attribute, this attribute has 7759 no namespace. 7761 o If the argument is represented as an element, it is qualified by 7762 the same namespace as its parent keyword element. 7764 o If the argument is represented as an element, it MUST be the first 7765 child of the keyword element. 7767 Substatements of a YANG statement are represented as (additional) 7768 children of the keyword element and their relative order MUST be the 7769 same as the order of substatements in YANG. 7771 Comments in YANG MAY be mapped to XML comments. 7773 +------------------+---------------+-------------+ 7774 | keyword | argument name | yin-element | 7775 +------------------+---------------+-------------+ 7776 | action | name | false | 7777 | anydata | name | false | 7778 | anyxml | name | false | 7779 | argument | name | false | 7780 | augment | target-node | false | 7781 | base | name | false | 7782 | belongs-to | module | false | 7783 | bit | name | false | 7784 | case | name | false | 7785 | choice | name | false | 7786 | config | value | false | 7787 | contact | text | true | 7788 | container | name | false | 7789 | default | value | false | 7790 | description | text | true | 7791 | deviate | value | false | 7792 | deviation | target-node | false | 7793 | enum | name | false | 7794 | error-app-tag | value | false | 7795 | error-message | value | true | 7796 | extension | name | false | 7797 | feature | name | false | 7798 | fraction-digits | value | false | 7799 | grouping | name | false | 7800 | identity | name | false | 7801 | if-feature | name | false | 7802 | import | module | false | 7803 | include | module | false | 7804 | input | | n/a | 7805 | key | value | false | 7806 | leaf | name | false | 7807 | leaf-list | name | false | 7808 | length | value | false | 7809 | list | name | false | 7810 | mandatory | value | false | 7811 | max-elements | value | false | 7812 | min-elements | value | false | 7813 | modifier | value | false | 7814 | module | name | false | 7815 | must | condition | false | 7816 | namespace | uri | false | 7817 | notification | name | false | 7818 | ordered-by | value | false | 7819 | organization | text | true | 7820 | output | | n/a | 7821 | path | value | false | 7822 | pattern | value | false | 7823 | position | value | false | 7824 | prefix | value | false | 7825 | presence | value | false | 7826 | range | value | false | 7827 | reference | text | true | 7828 | refine | target-node | false | 7829 | require-instance | value | false | 7830 | revision | date | false | 7831 | revision-date | date | false | 7832 | rpc | name | false | 7833 | status | value | false | 7834 | submodule | name | false | 7835 | type | name | false | 7836 | typedef | name | false | 7837 | unique | tag | false | 7838 | units | name | false | 7839 | uses | name | false | 7840 | value | value | false | 7841 | when | condition | false | 7842 | yang-version | value | false | 7843 | yin-element | value | false | 7844 +------------------+---------------+-------------+ 7846 Table 1: Mapping of arguments of the YANG statements. 7848 13.1.1. Usage Example 7850 The following YANG module: 7852 module example-foo { 7853 yang-version 1.1; 7854 namespace "urn:example:foo"; 7855 prefix "foo"; 7857 import example-extensions { 7858 prefix "myext"; 7859 } 7861 list interface { 7862 key "name"; 7863 leaf name { 7864 type string; 7865 } 7867 leaf mtu { 7868 type uint32; 7869 description "The MTU of the interface."; 7870 myext:c-define "MY_MTU"; 7871 } 7872 } 7873 } 7875 where the extension "c-define" is defined in Section 7.19.3, is 7876 translated into the following YIN: 7878 7883 7884 7886 7887 7888 7890 7891 7892 7893 7894 7895 7896 7897 7898 The MTU of the interface. 7899 7900 7901 7902 7903 7905 14. YANG ABNF Grammar 7907 In YANG, almost all statements are unordered. The ABNF grammar 7908 [RFC5234] [RFC7405] defines the canonical order. To improve module 7909 readability, it is RECOMMENDED that clauses be entered in this order. 7911 Within the ABNF grammar, unordered statements are marked with 7912 comments. 7914 This grammar assumes that the scanner replaces YANG comments with a 7915 single space character. 7917 file "yang.abnf" 7919 module-stmt = optsep module-keyword sep identifier-arg-str 7920 optsep 7921 "{" stmtsep 7922 module-header-stmts 7923 linkage-stmts 7924 meta-stmts 7925 revision-stmts 7926 body-stmts 7927 "}" optsep 7929 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 7930 optsep 7931 "{" stmtsep 7932 submodule-header-stmts 7933 linkage-stmts 7934 meta-stmts 7935 revision-stmts 7936 body-stmts 7937 "}" optsep 7939 module-header-stmts = ;; these stmts can appear in any order 7940 yang-version-stmt 7941 namespace-stmt 7942 prefix-stmt 7944 submodule-header-stmts = 7945 ;; these stmts can appear in any order 7946 yang-version-stmt 7947 belongs-to-stmt 7949 meta-stmts = ;; these stmts can appear in any order 7950 [organization-stmt] 7951 [contact-stmt] 7952 [description-stmt] 7953 [reference-stmt] 7955 linkage-stmts = ;; these stmts can appear in any order 7956 *import-stmt 7957 *include-stmt 7959 revision-stmts = *revision-stmt 7961 body-stmts = *(extension-stmt / 7962 feature-stmt / 7963 identity-stmt / 7964 typedef-stmt / 7965 grouping-stmt / 7966 data-def-stmt / 7967 augment-stmt / 7968 rpc-stmt / 7969 notification-stmt / 7970 deviation-stmt) 7972 data-def-stmt = container-stmt / 7973 leaf-stmt / 7974 leaf-list-stmt / 7975 list-stmt / 7976 choice-stmt / 7977 anydata-stmt / 7978 anyxml-stmt / 7979 uses-stmt 7981 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 7982 stmtend 7984 yang-version-arg-str = < a string that matches the rule > 7985 < yang-version-arg > 7987 yang-version-arg = "1.1" 7989 import-stmt = import-keyword sep identifier-arg-str optsep 7990 "{" stmtsep 7991 ;; these stmts can appear in any order 7992 prefix-stmt 7993 [revision-date-stmt] 7994 [description-stmt] 7995 [reference-stmt] 7996 "}" stmtsep 7998 include-stmt = include-keyword sep identifier-arg-str optsep 7999 (";" / 8000 "{" stmtsep 8001 ;; these stmts can appear in any order 8002 [revision-date-stmt] 8003 [description-stmt] 8004 [reference-stmt] 8005 "}") stmtsep 8007 namespace-stmt = namespace-keyword sep uri-str stmtend 8009 uri-str = < a string that matches the rule > 8010 < URI in RFC 3986 > 8012 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 8014 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 8015 optsep 8016 "{" stmtsep 8017 prefix-stmt 8018 "}" stmtsep 8020 organization-stmt = organization-keyword sep string stmtend 8021 contact-stmt = contact-keyword sep string stmtend 8023 description-stmt = description-keyword sep string stmtend 8025 reference-stmt = reference-keyword sep string stmtend 8027 units-stmt = units-keyword sep string stmtend 8029 revision-stmt = revision-keyword sep revision-date optsep 8030 (";" / 8031 "{" stmtsep 8032 ;; these stmts can appear in any order 8033 [description-stmt] 8034 [reference-stmt] 8035 "}") stmtsep 8037 revision-date = date-arg-str 8039 revision-date-stmt = revision-date-keyword sep revision-date stmtend 8041 extension-stmt = extension-keyword sep identifier-arg-str optsep 8042 (";" / 8043 "{" stmtsep 8044 ;; these stmts can appear in any order 8045 [argument-stmt] 8046 [status-stmt] 8047 [description-stmt] 8048 [reference-stmt] 8049 "}") stmtsep 8051 argument-stmt = argument-keyword sep identifier-arg-str optsep 8052 (";" / 8053 "{" stmtsep 8054 [yin-element-stmt] 8055 "}") stmtsep 8057 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 8058 stmtend 8060 yin-element-arg-str = < a string that matches the rule > 8061 < yin-element-arg > 8063 yin-element-arg = true-keyword / false-keyword 8065 identity-stmt = identity-keyword sep identifier-arg-str optsep 8066 (";" / 8067 "{" stmtsep 8068 ;; these stmts can appear in any order 8069 *if-feature-stmt 8070 *base-stmt 8071 [status-stmt] 8072 [description-stmt] 8073 [reference-stmt] 8074 "}") stmtsep 8076 base-stmt = base-keyword sep identifier-ref-arg-str 8077 stmtend 8079 feature-stmt = feature-keyword sep identifier-arg-str optsep 8080 (";" / 8081 "{" stmtsep 8082 ;; these stmts can appear in any order 8083 *if-feature-stmt 8084 [status-stmt] 8085 [description-stmt] 8086 [reference-stmt] 8087 "}") stmtsep 8089 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 8090 stmtend 8092 if-feature-expr-str = < a string that matches the rule > 8093 < if-feature-expr > 8095 if-feature-expr = if-feature-term 8096 [sep or-keyword sep if-feature-expr] 8098 if-feature-term = if-feature-factor 8099 [sep and-keyword sep if-feature-term] 8101 if-feature-factor = not-keyword sep if-feature-factor / 8102 "(" sep if-feature-expr sep ")" / 8103 identifier-ref-arg 8105 boolean-operator = and-keyword / or-keyword 8107 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 8108 "{" stmtsep 8109 ;; these stmts can appear in any order 8110 type-stmt 8111 [units-stmt] 8112 [default-stmt] 8113 [status-stmt] 8114 [description-stmt] 8115 [reference-stmt] 8116 "}" stmtsep 8118 type-stmt = type-keyword sep identifier-ref-arg-str optsep 8119 (";" / 8120 "{" stmtsep 8121 [type-body-stmts] 8122 "}") stmtsep 8124 type-body-stmts = numerical-restrictions / 8125 decimal64-specification / 8126 string-restrictions / 8127 enum-specification / 8128 leafref-specification / 8129 identityref-specification / 8130 instance-identifier-specification / 8131 bits-specification / 8132 union-specification / 8133 binary-specification 8135 numerical-restrictions = [range-stmt] 8137 range-stmt = range-keyword sep range-arg-str optsep 8138 (";" / 8139 "{" stmtsep 8140 ;; these stmts can appear in any order 8141 [error-message-stmt] 8142 [error-app-tag-stmt] 8143 [description-stmt] 8144 [reference-stmt] 8145 "}") stmtsep 8147 decimal64-specification = ;; these stmts can appear in any order 8148 fraction-digits-stmt 8149 [range-stmt] 8151 fraction-digits-stmt = fraction-digits-keyword sep 8152 fraction-digits-arg-str stmtend 8154 fraction-digits-arg-str = < a string that matches the rule > 8155 < fraction-digits-arg > 8157 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 8158 "5" / "6" / "7" / "8"]) 8159 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 8161 string-restrictions = ;; these stmts can appear in any order 8162 [length-stmt] 8163 *pattern-stmt 8165 length-stmt = length-keyword sep length-arg-str optsep 8166 (";" / 8167 "{" stmtsep 8168 ;; these stmts can appear in any order 8169 [error-message-stmt] 8170 [error-app-tag-stmt] 8171 [description-stmt] 8172 [reference-stmt] 8173 "}") stmtsep 8175 pattern-stmt = pattern-keyword sep string optsep 8176 (";" / 8177 "{" stmtsep 8178 ;; these stmts can appear in any order 8179 [modifier-stmt] 8180 [error-message-stmt] 8181 [error-app-tag-stmt] 8182 [description-stmt] 8183 [reference-stmt] 8184 "}") stmtsep 8186 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 8188 modifier-arg-str = < a string that matches the rule > 8189 < modifier-arg > 8191 modifier-arg = invert-match-keyword 8193 default-stmt = default-keyword sep string stmtend 8195 enum-specification = 1*enum-stmt 8197 enum-stmt = enum-keyword sep string optsep 8198 (";" / 8199 "{" stmtsep 8200 ;; these stmts can appear in any order 8201 *if-feature-stmt 8202 [value-stmt] 8203 [status-stmt] 8204 [description-stmt] 8205 [reference-stmt] 8206 "}") stmtsep 8208 leafref-specification = 8209 ;; these stmts can appear in any order 8210 path-stmt 8211 [require-instance-stmt] 8213 path-stmt = path-keyword sep path-arg-str stmtend 8214 require-instance-stmt = require-instance-keyword sep 8215 require-instance-arg-str stmtend 8217 require-instance-arg-str = < a string that matches the rule > 8218 < require-instance-arg > 8220 require-instance-arg = true-keyword / false-keyword 8222 instance-identifier-specification = 8223 [require-instance-stmt] 8225 identityref-specification = 8226 1*base-stmt 8228 union-specification = 1*type-stmt 8230 binary-specification = [length-stmt] 8232 bits-specification = 1*bit-stmt 8234 bit-stmt = bit-keyword sep identifier-arg-str optsep 8235 (";" / 8236 "{" stmtsep 8237 ;; these stmts can appear in any order 8238 *if-feature-stmt 8239 [position-stmt] 8240 [status-stmt] 8241 [description-stmt] 8242 [reference-stmt] 8243 "}") stmtsep 8245 position-stmt = position-keyword sep 8246 position-value-arg-str stmtend 8248 position-value-arg-str = < a string that matches the rule > 8249 < position-value-arg > 8251 position-value-arg = non-negative-integer-value 8253 status-stmt = status-keyword sep status-arg-str stmtend 8255 status-arg-str = < a string that matches the rule > 8256 < status-arg > 8258 status-arg = current-keyword / 8259 obsolete-keyword / 8260 deprecated-keyword 8262 config-stmt = config-keyword sep 8263 config-arg-str stmtend 8265 config-arg-str = < a string that matches the rule > 8266 < config-arg > 8268 config-arg = true-keyword / false-keyword 8270 mandatory-stmt = mandatory-keyword sep 8271 mandatory-arg-str stmtend 8273 mandatory-arg-str = < a string that matches the rule > 8274 < mandatory-arg > 8276 mandatory-arg = true-keyword / false-keyword 8278 presence-stmt = presence-keyword sep string stmtend 8280 ordered-by-stmt = ordered-by-keyword sep 8281 ordered-by-arg-str stmtend 8283 ordered-by-arg-str = < a string that matches the rule > 8284 < ordered-by-arg > 8286 ordered-by-arg = user-keyword / system-keyword 8288 must-stmt = must-keyword sep string optsep 8289 (";" / 8290 "{" stmtsep 8291 ;; these stmts can appear in any order 8292 [error-message-stmt] 8293 [error-app-tag-stmt] 8294 [description-stmt] 8295 [reference-stmt] 8296 "}") stmtsep 8298 error-message-stmt = error-message-keyword sep string stmtend 8300 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 8302 min-elements-stmt = min-elements-keyword sep 8303 min-value-arg-str stmtend 8305 min-value-arg-str = < a string that matches the rule > 8306 < min-value-arg > 8308 min-value-arg = non-negative-integer-value 8309 max-elements-stmt = max-elements-keyword sep 8310 max-value-arg-str stmtend 8312 max-value-arg-str = < a string that matches the rule > 8313 < max-value-arg > 8315 max-value-arg = unbounded-keyword / 8316 positive-integer-value 8318 value-stmt = value-keyword sep integer-value-str stmtend 8320 integer-value-str = < a string that matches the rule > 8321 < integer-value > 8323 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 8324 (";" / 8325 "{" stmtsep 8326 ;; these stmts can appear in any order 8327 [status-stmt] 8328 [description-stmt] 8329 [reference-stmt] 8330 *(typedef-stmt / grouping-stmt) 8331 *data-def-stmt 8332 *action-stmt 8333 *notification-stmt 8334 "}") stmtsep 8336 container-stmt = container-keyword sep identifier-arg-str optsep 8337 (";" / 8338 "{" stmtsep 8339 ;; these stmts can appear in any order 8340 [when-stmt] 8341 *if-feature-stmt 8342 *must-stmt 8343 [presence-stmt] 8344 [config-stmt] 8345 [status-stmt] 8346 [description-stmt] 8347 [reference-stmt] 8348 *(typedef-stmt / grouping-stmt) 8349 *data-def-stmt 8350 *action-stmt 8351 *notification-stmt 8352 "}") stmtsep 8354 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 8355 "{" stmtsep 8356 ;; these stmts can appear in any order 8358 [when-stmt] 8359 *if-feature-stmt 8360 type-stmt 8361 [units-stmt] 8362 *must-stmt 8363 [default-stmt] 8364 [config-stmt] 8365 [mandatory-stmt] 8366 [status-stmt] 8367 [description-stmt] 8368 [reference-stmt] 8369 "}" stmtsep 8371 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 8372 "{" stmtsep 8373 ;; these stmts can appear in any order 8374 [when-stmt] 8375 *if-feature-stmt 8376 type-stmt stmtsep 8377 [units-stmt] 8378 *must-stmt 8379 *default-stmt 8380 [config-stmt] 8381 [min-elements-stmt] 8382 [max-elements-stmt] 8383 [ordered-by-stmt] 8384 [status-stmt] 8385 [description-stmt] 8386 [reference-stmt] 8387 "}" stmtsep 8389 list-stmt = list-keyword sep identifier-arg-str optsep 8390 "{" stmtsep 8391 ;; these stmts can appear in any order 8392 [when-stmt] 8393 *if-feature-stmt 8394 *must-stmt 8395 [key-stmt] 8396 *unique-stmt 8397 [config-stmt] 8398 [min-elements-stmt] 8399 [max-elements-stmt] 8400 [ordered-by-stmt] 8401 [status-stmt] 8402 [description-stmt] 8403 [reference-stmt] 8404 *(typedef-stmt / grouping-stmt) 8405 1*data-def-stmt 8406 *action-stmt 8407 *notification-stmt 8408 "}" stmtsep 8410 key-stmt = key-keyword sep key-arg-str stmtend 8412 key-arg-str = < a string that matches the rule > 8413 < key-arg > 8415 key-arg = node-identifier *(sep node-identifier) 8417 unique-stmt = unique-keyword sep unique-arg-str stmtend 8419 unique-arg-str = < a string that matches the rule > 8420 < unique-arg > 8422 unique-arg = descendant-schema-nodeid 8423 *(sep descendant-schema-nodeid) 8425 choice-stmt = choice-keyword sep identifier-arg-str optsep 8426 (";" / 8427 "{" stmtsep 8428 ;; these stmts can appear in any order 8429 [when-stmt] 8430 *if-feature-stmt 8431 [default-stmt] 8432 [config-stmt] 8433 [mandatory-stmt] 8434 [status-stmt] 8435 [description-stmt] 8436 [reference-stmt] 8437 *(short-case-stmt / case-stmt) 8438 "}") stmtsep 8440 short-case-stmt = choice-stmt / 8441 container-stmt / 8442 leaf-stmt / 8443 leaf-list-stmt / 8444 list-stmt / 8445 anydata-stmt / 8446 anyxml-stmt 8448 case-stmt = case-keyword sep identifier-arg-str optsep 8449 (";" / 8450 "{" stmtsep 8451 ;; these stmts can appear in any order 8452 [when-stmt] 8453 *if-feature-stmt 8455 [status-stmt] 8456 [description-stmt] 8457 [reference-stmt] 8458 *data-def-stmt 8459 "}") stmtsep 8461 anydata-stmt = anydata-keyword sep identifier-arg-str optsep 8462 (";" / 8463 "{" stmtsep 8464 ;; these stmts can appear in any order 8465 [when-stmt] 8466 *if-feature-stmt 8467 *must-stmt 8468 [config-stmt] 8469 [mandatory-stmt] 8470 [status-stmt] 8471 [description-stmt] 8472 [reference-stmt] 8473 "}") stmtsep 8475 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 8476 (";" / 8477 "{" stmtsep 8478 ;; these stmts can appear in any order 8479 [when-stmt] 8480 *if-feature-stmt 8481 *must-stmt 8482 [config-stmt] 8483 [mandatory-stmt] 8484 [status-stmt] 8485 [description-stmt] 8486 [reference-stmt] 8487 "}") stmtsep 8489 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 8490 (";" / 8491 "{" stmtsep 8492 ;; these stmts can appear in any order 8493 [when-stmt] 8494 *if-feature-stmt 8495 [status-stmt] 8496 [description-stmt] 8497 [reference-stmt] 8498 *refine-stmt 8499 *uses-augment-stmt 8500 "}") stmtsep 8502 refine-stmt = refine-keyword sep refine-arg-str optsep 8503 "{" stmtsep 8504 ;; these stmts can appear in any order 8505 *if-feature-stmt 8506 *must-stmt 8507 [presence-stmt] 8508 *default-stmt 8509 [config-stmt] 8510 [mandatory-stmt] 8511 [min-elements-stmt] 8512 [max-elements-stmt] 8513 [description-stmt] 8514 [reference-stmt] 8515 "}" stmtsep 8517 refine-arg-str = < a string that matches the rule > 8518 < refine-arg > 8520 refine-arg = descendant-schema-nodeid 8522 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 8523 "{" stmtsep 8524 ;; these stmts can appear in any order 8525 [when-stmt] 8526 *if-feature-stmt 8527 [status-stmt] 8528 [description-stmt] 8529 [reference-stmt] 8530 1*(data-def-stmt / case-stmt / 8531 action-stmt / notification-stmt) 8532 "}" stmtsep 8534 uses-augment-arg-str = < a string that matches the rule > 8535 < uses-augment-arg > 8537 uses-augment-arg = descendant-schema-nodeid 8539 augment-stmt = augment-keyword sep augment-arg-str optsep 8540 "{" stmtsep 8541 ;; these stmts can appear in any order 8542 [when-stmt] 8543 *if-feature-stmt 8544 [status-stmt] 8545 [description-stmt] 8546 [reference-stmt] 8547 1*(data-def-stmt / case-stmt / 8548 action-stmt / notification-stmt) 8549 "}" stmtsep 8551 augment-arg-str = < a string that matches the rule > 8552 < augment-arg > 8554 augment-arg = absolute-schema-nodeid 8556 when-stmt = when-keyword sep string optsep 8557 (";" / 8558 "{" stmtsep 8559 ;; these stmts can appear in any order 8560 [description-stmt] 8561 [reference-stmt] 8562 "}") stmtsep 8564 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 8565 (";" / 8566 "{" stmtsep 8567 ;; these stmts can appear in any order 8568 *if-feature-stmt 8569 [status-stmt] 8570 [description-stmt] 8571 [reference-stmt] 8572 *(typedef-stmt / grouping-stmt) 8573 [input-stmt] 8574 [output-stmt] 8575 "}") stmtsep 8577 action-stmt = action-keyword sep identifier-arg-str optsep 8578 (";" / 8579 "{" stmtsep 8580 ;; these stmts can appear in any order 8581 *if-feature-stmt 8582 [status-stmt] 8583 [description-stmt] 8584 [reference-stmt] 8585 *(typedef-stmt / grouping-stmt) 8586 [input-stmt] 8587 [output-stmt] 8588 "}") stmtsep 8590 input-stmt = input-keyword optsep 8591 "{" stmtsep 8592 ;; these stmts can appear in any order 8593 *must-stmt 8594 *(typedef-stmt / grouping-stmt) 8595 1*data-def-stmt 8596 "}" stmtsep 8598 output-stmt = output-keyword optsep 8599 "{" stmtsep 8600 ;; these stmts can appear in any order 8601 *must-stmt 8602 *(typedef-stmt / grouping-stmt) 8603 1*data-def-stmt 8604 "}" stmtsep 8606 notification-stmt = notification-keyword sep 8607 identifier-arg-str optsep 8608 (";" / 8609 "{" stmtsep 8610 ;; these stmts can appear in any order 8611 *if-feature-stmt 8612 *must-stmt 8613 [status-stmt] 8614 [description-stmt] 8615 [reference-stmt] 8616 *(typedef-stmt / grouping-stmt) 8617 *data-def-stmt 8618 "}") stmtsep 8620 deviation-stmt = deviation-keyword sep 8621 deviation-arg-str optsep 8622 "{" stmtsep 8623 ;; these stmts can appear in any order 8624 [description-stmt] 8625 [reference-stmt] 8626 (deviate-not-supported-stmt / 8627 1*(deviate-add-stmt / 8628 deviate-replace-stmt / 8629 deviate-delete-stmt)) 8630 "}" stmtsep 8632 deviation-arg-str = < a string that matches the rule > 8633 < deviation-arg > 8635 deviation-arg = absolute-schema-nodeid 8637 deviate-not-supported-stmt = 8638 deviate-keyword sep 8639 not-supported-keyword-str stmtend 8641 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 8642 (";" / 8643 "{" stmtsep 8644 ;; these stmts can appear in any order 8645 [units-stmt] 8646 *must-stmt 8647 *unique-stmt 8648 *default-stmt 8649 [config-stmt] 8650 [mandatory-stmt] 8651 [min-elements-stmt] 8652 [max-elements-stmt] 8653 "}") stmtsep 8655 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 8656 (";" / 8657 "{" stmtsep 8658 ;; these stmts can appear in any order 8659 [units-stmt] 8660 *must-stmt 8661 *unique-stmt 8662 *default-stmt 8663 "}") stmtsep 8665 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 8666 (";" / 8667 "{" stmtsep 8668 ;; these stmts can appear in any order 8669 [type-stmt] 8670 [units-stmt] 8671 [default-stmt] 8672 [config-stmt] 8673 [mandatory-stmt] 8674 [min-elements-stmt] 8675 [max-elements-stmt] 8676 "}") stmtsep 8678 not-supported-keyword-str = < a string that matches the rule > 8679 < not-supported-keyword > 8681 add-keyword-str = < a string that matches the rule > 8682 < add-keyword > 8684 delete-keyword-str = < a string that matches the rule > 8685 < delete-keyword > 8687 replace-keyword-str = < a string that matches the rule > 8688 < replace-keyword > 8690 ;; represents the usage of an extension statement 8691 unknown-statement = prefix ":" identifier [sep string] optsep 8692 (";" / 8693 "{" optsep 8694 *((yang-stmt / unknown-statement) optsep) 8696 "}") stmtsep 8698 yang-stmt = action-stmt / 8699 anydata-stmt / 8700 anyxml-stmt / 8701 argument-stmt / 8702 augment-stmt / 8703 base-stmt / 8704 belongs-to-stmt / 8705 bit-stmt / 8706 case-stmt / 8707 choice-stmt / 8708 config-stmt / 8709 contact-stmt / 8710 container-stmt / 8711 default-stmt / 8712 description-stmt / 8713 deviate-add-stmt / 8714 deviate-delete-stmt / 8715 deviate-not-supported-stmt / 8716 deviate-replace-stmt / 8717 deviation-stmt / 8718 enum-stmt / 8719 error-app-tag-stmt / 8720 error-message-stmt / 8721 extension-stmt / 8722 feature-stmt / 8723 fraction-digits-stmt / 8724 grouping-stmt / 8725 identity-stmt / 8726 if-feature-stmt / 8727 import-stmt / 8728 include-stmt / 8729 input-stmt / 8730 key-stmt / 8731 leaf-list-stmt / 8732 leaf-stmt / 8733 length-stmt / 8734 list-stmt / 8735 mandatory-stmt / 8736 max-elements-stmt / 8737 min-elements-stmt / 8738 modifier-stmt / 8739 module-stmt / 8740 must-stmt / 8741 namespace-stmt / 8742 notification-stmt / 8743 ordered-by-stmt / 8744 organization-stmt / 8745 output-stmt / 8746 path-stmt / 8747 pattern-stmt / 8748 position-stmt / 8749 prefix-stmt / 8750 presence-stmt / 8751 range-stmt / 8752 reference-stmt / 8753 refine-stmt / 8754 require-instance-stmt / 8755 revision-date-stmt / 8756 revision-stmt / 8757 rpc-stmt / 8758 status-stmt / 8759 submodule-stmt / 8760 typedef-stmt / 8761 type-stmt / 8762 unique-stmt / 8763 units-stmt / 8764 uses-augment-stmt / 8765 uses-stmt / 8766 value-stmt / 8767 when-stmt / 8768 yang-version-stmt / 8769 yin-element-stmt 8771 ;; Ranges 8773 range-arg-str = < a string that matches the rule > 8774 < range-arg > 8776 range-arg = range-part *(optsep "|" optsep range-part) 8778 range-part = range-boundary 8779 [optsep ".." optsep range-boundary] 8781 range-boundary = min-keyword / max-keyword / 8782 integer-value / decimal-value 8784 ;; Lengths 8786 length-arg-str = < a string that matches the rule > 8787 < length-arg > 8789 length-arg = length-part *(optsep "|" optsep length-part) 8791 length-part = length-boundary 8793 [optsep ".." optsep length-boundary] 8795 length-boundary = min-keyword / max-keyword / 8796 non-negative-integer-value 8798 ;; Date 8800 date-arg-str = < a string that matches the rule > 8801 < date-arg > 8803 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 8805 ;; Schema Node Identifiers 8807 schema-nodeid = absolute-schema-nodeid / 8808 descendant-schema-nodeid 8810 absolute-schema-nodeid = 1*("/" node-identifier) 8812 descendant-schema-nodeid = 8813 node-identifier 8814 [absolute-schema-nodeid] 8816 node-identifier = [prefix ":"] identifier 8818 ;; Instance Identifiers 8820 instance-identifier = 1*("/" (node-identifier 8821 [1*key-predicate / 8822 leaf-list-predicate / 8823 pos])) 8825 key-predicate = "[" *WSP key-predicate-expr *WSP "]" 8827 key-predicate-expr = node-identifier *WSP "=" *WSP quoted-string 8829 leaf-list-predicate = "[" *WSP leaf-list-predicate-expr *WSP "]" 8831 leaf-list-predicate-expr = "." *WSP "=" *WSP quoted-string 8833 pos = "[" *WSP positive-integer-value *WSP "]" 8835 quoted-string = (DQUOTE string DQUOTE) / (SQUOTE string SQUOTE) 8837 ;; leafref path 8839 path-arg-str = < a string that matches the rule > 8840 < path-arg > 8842 path-arg = absolute-path / relative-path 8844 absolute-path = 1*("/" (node-identifier *path-predicate)) 8846 relative-path = 1*("../") descendant-path 8848 descendant-path = node-identifier 8849 [*path-predicate absolute-path] 8851 path-predicate = "[" *WSP path-equality-expr *WSP "]" 8853 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 8855 path-key-expr = current-function-invocation *WSP "/" *WSP 8856 rel-path-keyexpr 8858 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 8859 *(node-identifier *WSP "/" *WSP) 8860 node-identifier 8862 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 8864 ;; statement keywords 8865 action-keyword = %s"action" 8866 anydata-keyword = %s"anydata" 8867 anyxml-keyword = %s"anyxml" 8868 argument-keyword = %s"argument" 8869 augment-keyword = %s"augment" 8870 base-keyword = %s"base" 8871 belongs-to-keyword = %s"belongs-to" 8872 bit-keyword = %s"bit" 8873 case-keyword = %s"case" 8874 choice-keyword = %s"choice" 8875 config-keyword = %s"config" 8876 contact-keyword = %s"contact" 8877 container-keyword = %s"container" 8878 default-keyword = %s"default" 8879 description-keyword = %s"description" 8880 enum-keyword = %s"enum" 8881 error-app-tag-keyword = %s"error-app-tag" 8882 error-message-keyword = %s"error-message" 8883 extension-keyword = %s"extension" 8884 deviation-keyword = %s"deviation" 8885 deviate-keyword = %s"deviate" 8886 feature-keyword = %s"feature" 8887 fraction-digits-keyword = %s"fraction-digits" 8888 grouping-keyword = %s"grouping" 8889 identity-keyword = %s"identity" 8890 if-feature-keyword = %s"if-feature" 8891 import-keyword = %s"import" 8892 include-keyword = %s"include" 8893 input-keyword = %s"input" 8894 key-keyword = %s"key" 8895 leaf-keyword = %s"leaf" 8896 leaf-list-keyword = %s"leaf-list" 8897 length-keyword = %s"length" 8898 list-keyword = %s"list" 8899 mandatory-keyword = %s"mandatory" 8900 max-elements-keyword = %s"max-elements" 8901 min-elements-keyword = %s"min-elements" 8902 modifier-keyword = %s"modifier" 8903 module-keyword = %s"module" 8904 must-keyword = %s"must" 8905 namespace-keyword = %s"namespace" 8906 notification-keyword = %s"notification" 8907 ordered-by-keyword = %s"ordered-by" 8908 organization-keyword = %s"organization" 8909 output-keyword = %s"output" 8910 path-keyword = %s"path" 8911 pattern-keyword = %s"pattern" 8912 position-keyword = %s"position" 8913 prefix-keyword = %s"prefix" 8914 presence-keyword = %s"presence" 8915 range-keyword = %s"range" 8916 reference-keyword = %s"reference" 8917 refine-keyword = %s"refine" 8918 require-instance-keyword = %s"require-instance" 8919 revision-keyword = %s"revision" 8920 revision-date-keyword = %s"revision-date" 8921 rpc-keyword = %s"rpc" 8922 status-keyword = %s"status" 8923 submodule-keyword = %s"submodule" 8924 type-keyword = %s"type" 8925 typedef-keyword = %s"typedef" 8926 unique-keyword = %s"unique" 8927 units-keyword = %s"units" 8928 uses-keyword = %s"uses" 8929 value-keyword = %s"value" 8930 when-keyword = %s"when" 8931 yang-version-keyword = %s"yang-version" 8932 yin-element-keyword = %s"yin-element" 8934 ;; other keywords 8935 add-keyword = %s"add" 8936 current-keyword = %s"current" 8937 delete-keyword = %s"delete" 8938 deprecated-keyword = %s"deprecated" 8939 false-keyword = %s"false" 8940 invert-match-keyword = %s"invert-match" 8941 max-keyword = %s"max" 8942 min-keyword = %s"min" 8943 not-supported-keyword = %s"not-supported" 8944 obsolete-keyword = %s"obsolete" 8945 replace-keyword = %s"replace" 8946 system-keyword = %s"system" 8947 true-keyword = %s"true" 8948 unbounded-keyword = %s"unbounded" 8949 user-keyword = %s"user" 8951 and-keyword = %s"and" 8952 or-keyword = %s"or" 8953 not-keyword = %s"not" 8955 current-function-invocation = current-keyword *WSP "(" *WSP ")" 8957 ;;; Basic Rules 8959 prefix-arg-str = < a string that matches the rule > 8960 < prefix-arg > 8962 prefix-arg = prefix 8964 prefix = identifier 8966 identifier-arg-str = < a string that matches the rule > 8967 < identifier-arg > 8969 identifier-arg = identifier 8971 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 8972 identifier = (ALPHA / "_") 8973 *(ALPHA / DIGIT / "_" / "-" / ".") 8975 identifier-ref-arg-str = < a string that matches the rule > 8976 < identifier-ref-arg > 8978 identifier-ref-arg = identifier-ref 8980 identifier-ref = [prefix ":"] identifier 8982 string = < an unquoted string as returned by > 8983 < the scanner, that matches the rule > 8984 < yang-string > 8986 yang-string = *yang-char 8988 ;; any Unicode or ISO/IEC 10646 character including tab, carriage 8989 ;; return, and line feed, but excluding the other C0 control 8990 ;; characters, the surrogate blocks, and the noncharacters. 8991 yang-char = %x09 / %x0A / %x0D / %x20-D7FF / 8992 ; exclude surrogate blocks %xD800-DFFF 8993 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 8994 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 8995 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 8996 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 8997 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 8998 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 8999 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 9000 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 9001 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 9002 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 9003 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 9004 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 9005 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 9006 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 9007 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 9008 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 9009 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 9010 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 9012 integer-value = ("-" non-negative-integer-value) / 9013 non-negative-integer-value 9015 non-negative-integer-value = "0" / positive-integer-value 9017 positive-integer-value = (non-zero-digit *DIGIT) 9019 zero-integer-value = 1*DIGIT 9021 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 9023 sep = 1*(WSP / line-break) 9024 ; unconditional separator 9026 optsep = *(WSP / line-break) 9028 stmtsep = *(WSP / line-break / unknown-statement) 9030 line-break = CRLF / LF 9031 non-zero-digit = %x31-39 9033 decimal-value = integer-value ("." zero-integer-value) 9035 SQUOTE = %x27 9036 ; single quote 9038 ;;; RFC 5234 core rules. 9040 ALPHA = %x41-5A / %x61-7A 9041 ; A-Z / a-z 9043 CR = %x0D 9044 ; carriage return 9046 CRLF = CR LF 9047 ; Internet standard new line 9049 DIGIT = %x30-39 9050 ; 0-9 9052 DQUOTE = %x22 9053 ; double quote 9055 HTAB = %x09 9056 ; horizontal tab 9058 LF = %x0A 9059 ; linefeed 9061 SP = %x20 9062 ; space 9064 WSP = SP / HTAB 9065 ; whitespace 9067 9069 15. NETCONF Error Responses for YANG Related Errors 9071 A number of NETCONF error responses are defined for error cases 9072 related to the data-model handling. If the relevant YANG statement 9073 has an "error-app-tag" substatement, that overrides the default value 9074 specified below. 9076 15.1. Error Message for Data That Violates a unique Statement 9078 If a NETCONF operation would result in configuration data where a 9079 unique constraint is invalidated, the following error MUST be 9080 returned: 9082 error-tag: operation-failed 9083 error-app-tag: data-not-unique 9084 error-info: : Contains an instance identifier that 9085 points to a leaf that invalidates the unique 9086 constraint. This element is present once for each 9087 non-unique leaf. 9089 The element is in the YANG 9090 namespace ("urn:ietf:params:xml:ns:yang:1"). 9092 15.2. Error Message for Data That Violates a max-elements Statement 9094 If a NETCONF operation would result in configuration data where a 9095 list or a leaf-list would have too many entries the following error 9096 MUST be returned: 9098 error-tag: operation-failed 9099 error-app-tag: too-many-elements 9101 This error is returned once, with the error-path identifying the list 9102 node, even if there are more than one extra child present. 9104 15.3. Error Message for Data That Violates a min-elements Statement 9106 If a NETCONF operation would result in configuration data where a 9107 list or a leaf-list would have too few entries the following error 9108 MUST be returned: 9110 error-tag: operation-failed 9111 error-app-tag: too-few-elements 9113 This error is returned once, with the error-path identifying the list 9114 node, even if there are more than one child missing. 9116 15.4. Error Message for Data That Violates a must Statement 9118 If a NETCONF operation would result in configuration data where the 9119 restrictions imposed by a "must" statement is violated the following 9120 error MUST be returned, unless a specific "error-app-tag" 9121 substatement is present for the "must" statement. 9123 error-tag: operation-failed 9124 error-app-tag: must-violation 9126 15.5. Error Message for Data That Violates a require-instance Statement 9128 If a NETCONF operation would result in configuration data where a 9129 leaf of type "instance-identifier" or "leafref" marked with require- 9130 instance "true" refers to a non-existing instance, the following 9131 error MUST be returned: 9133 error-tag: data-missing 9134 error-app-tag: instance-required 9135 error-path: Path to the instance-identifier or leafref leaf. 9137 15.6. Error Message for Data That Violates a mandatory choice Statement 9139 If a NETCONF operation would result in configuration data where no 9140 nodes exists in a mandatory choice, the following error MUST be 9141 returned: 9143 error-tag: data-missing 9144 error-app-tag: missing-choice 9145 error-path: Path to the element with the missing choice. 9146 error-info: : Contains the name of the missing 9147 mandatory choice. 9149 The element is in the YANG 9150 namespace ("urn:ietf:params:xml:ns:yang:1"). 9152 15.7. Error Message for the "insert" Operation 9154 If the "insert" and "key" or "value" attributes are used in an 9155 for a list or leaf-list node, and the "key" or "value" 9156 refers to a non-existing instance, the following error MUST be 9157 returned: 9159 error-tag: bad-attribute 9160 error-app-tag: missing-instance 9162 16. IANA Considerations 9164 This document registers one capability identifier URN from the 9165 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 9167 Index Capability Identifier 9168 ------------- --------------------------------------------------- 9169 :yang-library urn:ietf:params:netconf:capability:yang-library:1.0 9171 17. Security Considerations 9173 This document defines a language with which to write and read 9174 descriptions of management information. The language itself has no 9175 security impact on the Internet. 9177 The same considerations are relevant as for the base NETCONF protocol 9178 (see [RFC6241], Section 9). 9180 Data modeled in YANG might contain sensitive information. RPCs or 9181 notifications defined in YANG might transfer sensitive information. 9183 Security issues are related to the usage of data modeled in YANG. 9184 Such issues shall be dealt with in documents describing the data 9185 models and documents about the interfaces used to manipulate the data 9186 e.g., the NETCONF documents. 9188 Data modeled in YANG is dependent upon: 9190 o the security of the transmission infrastructure used to send 9191 sensitive information. 9193 o the security of applications that store or release such sensitive 9194 information. 9196 o adequate authentication and access control mechanisms to restrict 9197 the usage of sensitive data. 9199 YANG parsers need to be robust with respect to malformed documents. 9200 Reading malformed documents from unknown or untrusted sources could 9201 result in an attacker gaining privileges of the user running the YANG 9202 parser. In an extreme situation, the entire machine could be 9203 compromised. 9205 18. Contributors 9207 The following people all contributed significantly to the initial 9208 YANG document: 9210 - Andy Bierman (YumaWorks) 9211 - Balazs Lengyel (Ericsson) 9212 - David Partain (Ericsson) 9213 - Juergen Schoenwaelder (Jacobs University Bremen) 9214 - Phil Shafer (Juniper Networks) 9216 19. Acknowledgements 9218 The editor wishes to thank the following individuals, who all 9219 provided helpful comments on various versions of this document: 9220 Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, 9221 Ladislav Lhotka, Lionel Morand, Gerhard Muenz, Peyman Owladi, Tom 9222 Petch, Randy Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert 9223 Wijnen, Robert Wilton, and Dale Worley. 9225 20. ChangeLog 9227 RFC Editor: remove this section upon publication as an RFC. 9229 20.1. Version -10 9231 o Made single and double quote characters illegal in unquoted 9232 strings. 9234 o Allow "description" and "reference" in "import" and "include". 9236 o Removed redundant NETCONF Error Message subsection. 9238 o Editorial fixes and clarifications after second WGLC reviews. 9240 20.2. Version -09 9242 o Editorial fixes and clarifications after WGLC reviews. 9244 o when statement context clarification. 9246 o Allow "augment" to add conditionally mandatory nodes (see 9247 Section 7.17). 9249 o Allow non-unique config false leaf-lists. 9251 o Made handling of choice and false "when" expressions non-NETCONF 9252 specific. 9254 o Changed the function signatures for "derived-from" and 9255 "derived-from-or-self". 9257 20.3. Version -08 9259 o Fixes after WGLC reviews. 9261 20.4. Version -07 9263 o Fixes after WG review. 9265 o Included solution Y60-01. 9267 20.5. Version -06 9269 o Included solution Y45-05. 9271 20.6. Version -05 9273 o Included solution Y18-01. 9275 o Included solution Y25-02 (parts of it was included in -04). 9277 o Included solution Y34-05. 9279 o Included solution Y36-03. 9281 20.7. Version -04 9283 o Incorporated changes to ABNF grammar after review and errata for 9284 RFC 6020. 9286 o Included solution Y16-03. 9288 o Included solution Y49-04. 9290 o Included solution Y58-01. 9292 o Included solution Y59-01. 9294 20.8. Version -03 9296 o Incorporated changes from WG reviews. 9298 o Included solution Y05-01. 9300 o Included solution Y10-01. 9302 o Included solution Y13-01. 9304 o Included solution Y28-02. 9306 o Included solution Y55-01 (parts of it was included in -01). 9308 20.9. Version -02 9310 o Included solution Y02-01. 9312 o Included solution Y04-02. 9314 o Included solution Y11-01. 9316 o Included solution Y41-01. 9318 o Included solution Y56-01. 9320 20.10. Version -01 9322 o Included solution Y01-01. 9324 o Included solution Y03-01. 9326 o Included solution Y06-02. 9328 o Included solution Y07-01. 9330 o Included solution Y14-01. 9332 o Included solution Y20-01. 9334 o Included solution Y23-01. 9336 o Included solution Y29-01. 9338 o Included solution Y30-01. 9340 o Included solution Y31-01. 9342 o Included solution Y35-01. 9344 20.11. Version -00 9346 o Applied all reported errata for RFC 6020. 9348 o Updated YANG version to 1.1, and made the "yang-version" statement 9349 mandatory. 9351 21. References 9352 21.1. Normative References 9354 [I-D.ietf-netconf-yang-library] 9355 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 9356 Library", draft-ietf-netconf-yang-library-06 (work in 9357 progress), April 2016. 9359 [ISO.10646] 9360 International Organization for Standardization, 9361 "Information Technology - Universal Multiple-Octet Coded 9362 Character Set (UCS)", ISO Standard 10646:2003, 2003. 9364 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9365 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 9366 RFC2119, March 1997, 9367 . 9369 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 9370 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 9371 2003, . 9373 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9374 Resource Identifier (URI): Generic Syntax", STD 66, RFC 9375 3986, DOI 10.17487/RFC3986, January 2005, 9376 . 9378 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9379 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9380 . 9382 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9383 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 9384 RFC5234, January 2008, 9385 . 9387 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 9388 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 9389 . 9391 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 9392 and A. Bierman, Ed., "Network Configuration Protocol 9393 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 9394 . 9396 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 9397 7405, DOI 10.17487/RFC7405, December 2014, 9398 . 9400 [XML-NAMES] 9401 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 9402 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 9403 Wide Web Consortium Recommendation REC-xml-names-20091208, 9404 December 2009, 9405 . 9407 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 9408 Version 1.0", World Wide Web Consortium Recommendation 9409 REC-xpath-19991116, November 1999, 9410 . 9412 [XSD-TYPES] 9413 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 9414 Second Edition", World Wide Web Consortium Recommendation 9415 REC-xmlschema-2-20041028, October 2004, 9416 . 9418 21.2. Informative References 9420 [I-D.ietf-netconf-restconf] 9421 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 9422 Protocol", draft-ietf-netconf-restconf-13 (work in 9423 progress), April 2016. 9425 [I-D.ietf-netmod-rfc6087bis] 9426 Bierman, A., "Guidelines for Authors and Reviewers of YANG 9427 Data Model Documents", draft-ietf-netmod-rfc6087bis-06 9428 (work in progress), March 2016. 9430 [I-D.ietf-netmod-yang-json] 9431 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 9432 draft-ietf-netmod-yang-json-10 (work in progress), March 9433 2016. 9435 [I-D.vanderstok-core-comi] 9436 Stok, P. and A. Bierman, "CoAP Management Interface", 9437 draft-vanderstok-core-comi-09 (work in progress), March 9438 2016. 9440 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9441 Schoenwaelder, Ed., "Structure of Management Information 9442 Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/ 9443 RFC2578, April 1999, 9444 . 9446 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9447 Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 9448 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 9449 . 9451 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 9452 Structure of Management Information", RFC 3780, DOI 9453 10.17487/RFC3780, May 2004, 9454 . 9456 [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC 9457 Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, 9458 July 2007, . 9460 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 9461 the Network Configuration Protocol (NETCONF)", RFC 6020, 9462 DOI 10.17487/RFC6020, October 2010, 9463 . 9465 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 9466 Information Version 2 (SMIv2) MIB Modules to YANG 9467 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 9468 . 9470 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)", 9471 RFC 6691, DOI 10.17487/RFC6691, July 2012, 9472 . 9474 [XPATH2.0] 9475 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 9476 Kay, M., Robie, J., and J. Simeon, "XML Path Language 9477 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 9478 Recommendation REC-xpath20-20101214, December 2010, 9479 . 9481 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 9482 Wide Web Consortium Recommendation REC-xslt-19991116, 9483 November 1999, 9484 . 9486 Author's Address 9488 Martin Bjorklund (editor) 9489 Tail-f Systems 9491 Email: mbj@tail-f.com