idnits 2.17.1 draft-ietf-netmod-rfc6020bis-01.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 == 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 (October 2, 2014) is 3492 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 6153 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- 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' -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 7 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 Obsoletes: 6020 (if approved) October 2, 2014 5 Intended status: Standards Track 6 Expires: April 5, 2015 8 YANG - A Data Modeling Language for the Network Configuration Protocol 9 (NETCONF) 10 draft-ietf-netmod-rfc6020bis-01 12 Abstract 14 YANG is a data modeling language used to model configuration and 15 state data manipulated by the Network Configuration Protocol 16 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 17 This document obsoletes RFC 6020. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 5, 2015. 36 Copyright Notice 38 Copyright (c) 2014 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 66 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 67 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 11 70 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 71 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 72 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 73 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 74 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 14 75 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 18 76 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 18 77 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 19 78 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 20 79 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 21 80 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 22 81 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 23 82 4.2.10. Notification Definitions . . . . . . . . . . . . . . 24 83 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 25 84 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 25 85 5.1.1. Import and Include by Revision . . . . . . . . . . . 26 86 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 27 87 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 28 88 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 28 89 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 29 90 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 29 91 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 29 92 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 30 93 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 30 94 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 31 95 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 31 96 5.6.4. Announcing Conformance Information in the 97 Message . . . . . . . . . . . . . . . . . . . . . . . 32 98 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 34 99 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 34 100 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 34 101 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 34 102 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 35 103 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 35 104 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 36 105 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 36 106 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 37 107 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 38 108 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 38 109 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 38 110 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 39 111 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 39 112 7.1. The module Statement . . . . . . . . . . . . . . . . . . 40 113 7.1.1. The module's Substatements . . . . . . . . . . . . . 41 114 7.1.2. The yang-version Statement . . . . . . . . . . . . . 41 115 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 42 116 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 42 117 7.1.5. The import Statement . . . . . . . . . . . . . . . . 42 118 7.1.6. The include Statement . . . . . . . . . . . . . . . . 43 119 7.1.7. The organization Statement . . . . . . . . . . . . . 44 120 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 44 121 7.1.9. The revision Statement . . . . . . . . . . . . . . . 44 122 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 45 123 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 46 124 7.2.1. The submodule's Substatements . . . . . . . . . . . . 47 125 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 48 126 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 49 127 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 49 128 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 50 129 7.3.2. The typedef's type Statement . . . . . . . . . . . . 50 130 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 50 131 7.3.4. The typedef's default Statement . . . . . . . . . . . 50 132 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 51 133 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 51 134 7.4.1. The type's Substatements . . . . . . . . . . . . . . 51 135 7.5. The container Statement . . . . . . . . . . . . . . . . . 51 136 7.5.1. Containers with Presence . . . . . . . . . . . . . . 52 137 7.5.2. The container's Substatements . . . . . . . . . . . . 52 138 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 53 139 7.5.4. The must's Substatements . . . . . . . . . . . . . . 54 140 7.5.5. The presence Statement . . . . . . . . . . . . . . . 55 141 7.5.6. The container's Child Node Statements . . . . . . . . 56 142 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 56 143 7.5.8. NETCONF Operations . . . . . . . . . . 56 144 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 57 145 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 58 146 7.6.1. The leaf's default value . . . . . . . . . . . . . . 58 147 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 59 148 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 59 149 7.6.4. The leaf's default Statement . . . . . . . . . . . . 59 150 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 59 151 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 60 152 7.6.7. NETCONF Operations . . . . . . . . . . 60 153 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 60 154 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 61 155 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 62 156 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 62 157 7.7.3. The min-elements Statement . . . . . . . . . . . . . 63 158 7.7.4. The max-elements Statement . . . . . . . . . . . . . 63 159 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 64 160 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 64 161 7.7.7. NETCONF Operations . . . . . . . . . . 65 162 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 163 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 67 164 7.8.1. The list's Substatements . . . . . . . . . . . . . . 67 165 7.8.2. The list's key Statement . . . . . . . . . . . . . . 68 166 7.8.3. The list's unique Statement . . . . . . . . . . . . . 69 167 7.8.4. The list's Child Node Statements . . . . . . . . . . 70 168 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 70 169 7.8.6. NETCONF Operations . . . . . . . . . . 71 170 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 72 171 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 75 172 7.9.1. The choice's Substatements . . . . . . . . . . . . . 75 173 7.9.2. The choice's case Statement . . . . . . . . . . . . . 76 174 7.9.3. The choice's default Statement . . . . . . . . . . . 77 175 7.9.4. The choice's mandatory Statement . . . . . . . . . . 79 176 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 79 177 7.9.6. NETCONF Operations . . . . . . . . . . 79 178 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 79 179 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 80 180 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 81 181 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 81 182 7.10.3. NETCONF Operations . . . . . . . . . . 81 183 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 82 184 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 82 185 7.11.1. The grouping's Substatements . . . . . . . . . . . . 83 186 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . 83 187 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 84 188 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 84 189 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 84 190 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 85 191 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 85 193 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 87 194 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . 87 195 7.13.2. The input Statement . . . . . . . . . . . . . . . . 87 196 7.13.3. The output Statement . . . . . . . . . . . . . . . . 88 197 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 89 198 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . 89 199 7.14. The notification Statement . . . . . . . . . . . . . . . 90 200 7.14.1. The notification's Substatements . . . . . . . . . . 91 201 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 91 202 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . 91 203 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 92 204 7.15.1. The augment's Substatements . . . . . . . . . . . . 93 205 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 93 206 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 93 207 7.16. The identity Statement . . . . . . . . . . . . . . . . . 95 208 7.16.1. The identity's Substatements . . . . . . . . . . . . 95 209 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 96 210 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 96 211 7.17. The extension Statement . . . . . . . . . . . . . . . . . 97 212 7.17.1. The extension's Substatements . . . . . . . . . . . 98 213 7.17.2. The argument Statement . . . . . . . . . . . . . . . 98 214 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 99 215 7.18. Conformance-Related Statements . . . . . . . . . . . . . 99 216 7.18.1. The feature Statement . . . . . . . . . . . . . . . 99 217 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 101 218 7.18.3. The deviation Statement . . . . . . . . . . . . . . 102 219 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 104 220 7.19.1. The config Statement . . . . . . . . . . . . . . . . 104 221 7.19.2. The status Statement . . . . . . . . . . . . . . . . 105 222 7.19.3. The description Statement . . . . . . . . . . . . . 106 223 7.19.4. The reference Statement . . . . . . . . . . . . . . 106 224 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 106 225 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 108 226 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 108 227 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 108 228 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 108 229 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 109 230 8.3.2. NETCONF Processing . . . . . . . . . . 109 231 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 110 232 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 110 233 9.1. Canonical Representation . . . . . . . . . . . . . . . . 111 234 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 111 235 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 112 236 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 112 237 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 113 238 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 113 239 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 113 240 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 114 241 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 114 242 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 114 243 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 115 244 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 115 245 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 115 246 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 116 247 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 116 248 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 249 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 250 9.4.4. The length Statement . . . . . . . . . . . . . . . . 116 251 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 117 252 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 118 253 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 118 254 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 119 255 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 119 256 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 257 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 258 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 119 259 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 119 260 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 261 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 262 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 120 263 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 264 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 121 265 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 121 266 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 121 267 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 121 268 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 121 269 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 122 270 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 123 271 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 123 272 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 123 273 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 123 274 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 123 275 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 276 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 124 277 9.9.3. The require-instance Statement . . . . . . . . . . . 125 278 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 125 279 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 125 280 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 125 281 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 129 282 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 129 283 9.10.2. The identityref's base Statement . . . . . . . . . . 129 284 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 130 285 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 130 286 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 130 287 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 132 288 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 289 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 132 290 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 291 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 132 292 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 132 293 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 133 294 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 133 295 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 133 296 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 133 297 9.13. The instance-identifier Built-In Type . . . . . . . . . . 134 298 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 299 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 135 300 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 136 301 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 136 302 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 136 303 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 136 304 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 136 305 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 137 306 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 137 307 10.3. Functions for the YANG Types "leafref" and "instance- 308 identifier" . . . . . . . . . . . . . . . . . . . . . . 137 309 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 137 310 10.4. Functions for the YANG Type "identityref" . . . . . . . 138 311 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 138 312 10.5. Functions for the YANG Type "enumeration" . . . . . . . 139 313 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 139 314 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 140 315 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 140 316 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 141 317 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 318 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 143 319 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 146 320 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 147 321 14. Error Responses for YANG Related Errors . . . . . . . . . . . 170 322 14.1. Error Message for Data That Violates a unique Statement 170 323 14.2. Error Message for Data That Violates a max-elements 324 Statement . . . . . . . . . . . . . . . . . . . . . . . 170 325 14.3. Error Message for Data That Violates a min-elements 326 Statement . . . . . . . . . . . . . . . . . . . . . . . 170 327 14.4. Error Message for Data That Violates a must Statement . 171 328 14.5. Error Message for Data That Violates a require-instance 329 Statement . . . . . . . . . . . . . . . . . . . . . . . 171 330 14.6. Error Message for Data That Does Not Match a leafref 331 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 171 332 14.7. Error Message for Data That Violates a mandatory choice 333 Statement . . . . . . . . . . . . . . . . . . . . . . . 171 334 14.8. Error Message for the "insert" Operation . . . . . . . . 172 335 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 172 336 15.1. Media type application/yang . . . . . . . . . . . . . . 173 337 15.2. Media type application/yin+xml . . . . . . . . . . . . . 174 338 16. Security Considerations . . . . . . . . . . . . . . . . . . . 176 339 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 176 340 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 177 341 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 177 342 19.1. Version -01 . . . . . . . . . . . . . . . . . . . . . . 177 343 19.2. Version -00 . . . . . . . . . . . . . . . . . . . . . . 177 344 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 177 345 20.1. Normative References . . . . . . . . . . . . . . . . . . 178 346 20.2. Informative References . . . . . . . . . . . . . . . . . 179 347 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 179 349 1. Introduction 351 YANG is a data modeling language used to model configuration and 352 state data manipulated by the Network Configuration Protocol 353 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 354 YANG is used to model the operations and content layers of NETCONF 355 (see the NETCONF Configuration Protocol [RFC6241], Section 1.2). 357 This document describes the syntax and semantics of the YANG 358 language, how the data model defined in a YANG module is represented 359 in the Extensible Markup Language (XML), and how NETCONF operations 360 are used to manipulate the data. 362 1.1. Summary of Changes from RFC 6020 364 This document defines version 1.1 of the YANG language. YANG version 365 1.1 is a maintenance release of the YANG language, addressing 366 ambiguities and defects in the original specification [RFC6020]. 368 o Changed the YANG version from "1" to "1.1". 370 o Made the "yang-version" statement mandatory. 372 o Changed the rules for the interpretation of escaped characters in 373 double quoted strings. This is an backwards incompatible change 374 from YANG 1.0. A module that uses a character sequence that is 375 now illegal must change the string to match the new rules. See 376 Section 6.1.3 for details. 378 o Extended the "if-feature" syntax to be a boolean expression over 379 feature names. 381 o Added a set of new XPath functions in Section 10. 383 o Added a new substatement "modifier" to pattern (see 384 Section 9.4.6). 386 o Defined the string value of an identityref in XPath expressions 387 (see Section 9.10). 389 o Allow "if-feature" in "refine". 391 o Made "when" and "if-feature" illegal on list keys, unless the 392 parent is also conditional, and the condition matches the parent's 393 condition. 395 o Allow "choice" as a shorthand case statement (see Section 7.9). 397 2. Keywords 399 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 400 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 401 "OPTIONAL" in this document are to be interpreted as described in BCP 402 14, [RFC2119]. 404 3. Terminology 406 o anyxml: A data node that can contain an unknown chunk of XML data. 408 o augment: Adds new schema nodes to a previously defined schema 409 node. 411 o base type: The type from which a derived type was derived, which 412 may be either a built-in type or another derived type. 414 o built-in type: A YANG data type defined in the YANG language, such 415 as uint32 or string. 417 o choice: A schema node where only one of a number of identified 418 alternatives is valid. 420 o configuration data: The set of writable data that is required to 421 transform a system from its initial default state into its current 422 state [RFC6241]. 424 o conformance: A measure of how accurately a device follows a data 425 model. 427 o container: An interior data node that exists in at most one 428 instance in the data tree. A container has no value, but rather a 429 set of child nodes. 431 o data definition statement: A statement that defines new data 432 nodes. One of container, leaf, leaf-list, list, choice, case, 433 augment, uses, and anyxml. 435 o data model: A data model describes how data is represented and 436 accessed. 438 o data node: A node in the schema tree that can be instantiated in a 439 data tree. One of container, leaf, leaf-list, list, and anyxml. 441 o data tree: The instantiated tree of configuration and state data 442 on a device. 444 o derived type: A type that is derived from a built-in type (such as 445 uint32), or another derived type. 447 o device deviation: A failure of the device to implement the module 448 faithfully. 450 o extension: An extension attaches non-YANG semantics to statements. 451 The extension statement defines new statements to express these 452 semantics. 454 o feature: A mechanism for marking a portion of the model as 455 optional. Definitions can be tagged with a feature name and are 456 only valid on devices that support that feature. 458 o grouping: A reusable set of schema nodes, which may be used 459 locally in the module, in modules that include it, and by other 460 modules that import from it. The grouping statement is not a data 461 definition statement and, as such, does not define any nodes in 462 the schema tree. 464 o identifier: Used to identify different kinds of YANG items by 465 name. 467 o instance identifier: A mechanism for identifying a particular node 468 in a data tree. 470 o interior node: Nodes within a hierarchy that are not leaf nodes. 472 o leaf: A data node that exists in at most one instance in the data 473 tree. A leaf has a value but no child nodes. 475 o leaf-list: Like the leaf node but defines a set of uniquely 476 identifiable nodes rather than a single node. Each node has a 477 value but no child nodes. 479 o list: An interior data node that may exist in multiple instances 480 in the data tree. A list has no value, but rather a set of child 481 nodes. 483 o module: A YANG module defines a hierarchy of nodes that can be 484 used for NETCONF-based operations. With its definitions and the 485 definitions it imports or includes from elsewhere, a module is 486 self-contained and "compilable". 488 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 490 o RPC operation: A specific Remote Procedure Call, as used within 491 the NETCONF protocol. It is also called a protocol operation. 493 o schema node: A node in the schema tree. One of container, leaf, 494 leaf-list, list, choice, case, rpc, input, output, notification, 495 and anyxml. 497 o schema node identifier: A mechanism for identifying a particular 498 node in the schema tree. 500 o schema tree: The definition hierarchy specified within a module. 502 o state data: The additional data on a system that is not 503 configuration data such as read-only status information and 504 collected statistics [RFC6241]. 506 o submodule: A partial module definition that contributes derived 507 types, groupings, data nodes, RPCs, and notifications to a module. 508 A YANG module can be constructed from a number of submodules. 510 o top-level data node: A data node where there is no other data node 511 between it and a module or submodule statement. 513 o uses: The "uses" statement is used to instantiate the set of 514 schema nodes defined in a grouping statement. The instantiated 515 nodes may be refined and augmented to tailor them to any specific 516 needs. 518 3.1. Mandatory Nodes 520 A mandatory node is one of: 522 o A leaf, choice, or anyxml node with a "mandatory" statement with 523 the value "true". 525 o A list or leaf-list node with a "min-elements" statement with a 526 value greater than zero. 528 o A container node without a "presence" statement, which has at 529 least one mandatory node as a child. 531 4. YANG Overview 533 4.1. Functional Overview 535 YANG is a language used to model data for the NETCONF protocol. A 536 YANG module defines a hierarchy of data that can be used for NETCONF- 537 based operations, including configuration, state data, Remote 538 Procedure Calls (RPCs), and notifications. This allows a complete 539 description of all data sent between a NETCONF client and server. 541 YANG models the hierarchical organization of data as a tree in which 542 each node has a name, and either a value or a set of child nodes. 543 YANG provides clear and concise descriptions of the nodes, as well as 544 the interaction between those nodes. 546 YANG structures data models into modules and submodules. A module 547 can import data from other external modules, and include data from 548 submodules. The hierarchy can be augmented, allowing one module to 549 add data nodes to the hierarchy defined in another module. This 550 augmentation can be conditional, with new nodes appearing only if 551 certain conditions are met. 553 YANG models can describe constraints to be enforced on the data, 554 restricting the appearance or value of nodes based on the presence or 555 value of other nodes in the hierarchy. These constraints are 556 enforceable by either the client or the server, and valid content 557 MUST abide by them. 559 YANG defines a set of built-in types, and has a type mechanism 560 through which additional types may be defined. Derived types can 561 restrict their base type's set of valid values using mechanisms like 562 range or pattern restrictions that can be enforced by clients or 563 servers. They can also define usage conventions for use of the 564 derived type, such as a string-based type that contains a host name. 566 YANG permits the definition of reusable groupings of nodes. The 567 instantiation of these groupings can refine or augment the nodes, 568 allowing it to tailor the nodes to its particular needs. Derived 569 types and groupings can be defined in one module or submodule and 570 used in either that location or in another module or submodule that 571 imports or includes it. 573 YANG data hierarchy constructs include defining lists where list 574 entries are identified by keys that distinguish them from each other. 575 Such lists may be defined as either sorted by user or automatically 576 sorted by the system. For user-sorted lists, operations are defined 577 for manipulating the order of the list entries. 579 YANG modules can be translated into an equivalent XML syntax called 580 YANG Independent Notation (YIN) (Section 12), allowing applications 581 using XML parsers and Extensible Stylesheet Language Transformations 582 (XSLT) scripts to operate on the models. The conversion from YANG to 583 YIN is lossless, so content in YIN can be round-tripped back into 584 YANG. 586 YANG strikes a balance between high-level data modeling and low-level 587 bits-on-the-wire encoding. The reader of a YANG module can see the 588 high-level view of the data model while understanding how the data 589 will be encoded in NETCONF operations. 591 YANG is an extensible language, allowing extension statements to be 592 defined by standards bodies, vendors, and individuals. The statement 593 syntax allows these extensions to coexist with standard YANG 594 statements in a natural way, while extensions in a YANG module stand 595 out sufficiently for the reader to notice them. 597 YANG resists the tendency to solve all possible problems, limiting 598 the problem space to allow expression of NETCONF data models, not 599 arbitrary XML documents or arbitrary data models. The data models 600 described by YANG are designed to be easily operated upon by NETCONF 601 operations. 603 To the extent possible, YANG maintains compatibility with Simple 604 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 605 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 606 can be automatically translated into YANG modules for read-only 607 access. However, YANG is not concerned with reverse translation from 608 YANG to SMIv2. 610 Like NETCONF, YANG targets smooth integration with the device's 611 native management infrastructure. This allows implementations to 612 leverage their existing access control mechanisms to protect or 613 expose elements of the data model. 615 4.2. Language Overview 617 This section introduces some important constructs used in YANG that 618 will aid in the understanding of the language specifics in later 619 sections. This progressive approach handles the inter-related nature 620 of YANG concepts and statements. A detailed description of YANG 621 statements and syntax begins in Section 7. 623 4.2.1. Modules and Submodules 625 A module contains three types of statements: module-header 626 statements, revision statements, and definition statements. The 627 module header statements describe the module and give information 628 about the module itself, the revision statements give information 629 about the history of the module, and the definition statements are 630 the body of the module where the data model is defined. 632 A NETCONF server may implement a number of modules, allowing multiple 633 views of the same data, or multiple views of disjoint subsections of 634 the device's data. Alternatively, the server may implement only one 635 module that defines all available data. 637 A module may be divided into submodules, based on the needs of the 638 module owner. The external view remains that of a single module, 639 regardless of the presence or size of its submodules. 641 The "include" statement allows a module or submodule to reference 642 material in submodules, and the "import" statement allows references 643 to material defined in other modules. 645 4.2.2. Data Modeling Basics 647 YANG defines four types of nodes for data modeling. In each of the 648 following subsections, the example shows the YANG syntax as well as a 649 corresponding NETCONF XML representation. 651 4.2.2.1. Leaf Nodes 653 A leaf node contains simple data like an integer or a string. It has 654 exactly one value of a particular type and no child nodes. 656 YANG Example: 658 leaf host-name { 659 type string; 660 description "Hostname for this system"; 661 } 663 NETCONF XML Example: 665 my.example.com 667 The "leaf" statement is covered in Section 7.6. 669 4.2.2.2. Leaf-List Nodes 671 A leaf-list is a sequence of leaf nodes with exactly one value of a 672 particular type per leaf. 674 YANG Example: 676 leaf-list domain-search { 677 type string; 678 description "List of domain names to search"; 679 } 681 NETCONF XML Example: 683 high.example.com 684 low.example.com 685 everywhere.example.com 687 The "leaf-list" statement is covered in Section 7.7. 689 4.2.2.3. Container Nodes 691 A container node is used to group related nodes in a subtree. A 692 container has only child nodes and no value. A container may contain 693 any number of child nodes of any type (including leafs, lists, 694 containers, and leaf-lists). 696 YANG Example: 698 container system { 699 container login { 700 leaf message { 701 type string; 702 description 703 "Message given at start of login session"; 704 } 705 } 706 } 708 NETCONF XML Example: 710 711 712 Good morning 713 714 716 The "container" statement is covered in Section 7.5. 718 4.2.2.4. List Nodes 720 A list defines a sequence of list entries. Each entry is like a 721 structure or a record instance, and is uniquely identified by the 722 values of its key leafs. A list can define multiple key leafs and 723 may contain any number of child nodes of any type (including leafs, 724 lists, containers etc.). 726 YANG Example: 728 list user { 729 key "name"; 730 leaf name { 731 type string; 732 } 733 leaf full-name { 734 type string; 735 } 736 leaf class { 737 type string; 738 } 739 } 741 NETCONF XML Example: 743 744 glocks 745 Goldie Locks 746 intruder 747 748 749 snowey 750 Snow White 751 free-loader 752 753 754 rzell 755 Rapun Zell 756 tower 757 759 The "list" statement is covered in Section 7.8. 761 4.2.2.5. Example Module 763 These statements are combined to define the module: 765 // Contents of "acme-system.yang" 766 module acme-system { 767 yang-version 1.1; 768 namespace "http://acme.example.com/system"; 769 prefix "acme"; 771 organization "ACME Inc."; 772 contact "joe@acme.example.com"; 773 description 774 "The module for entities implementing the ACME system."; 776 revision 2007-06-09 { 777 description "Initial revision."; 778 } 780 container system { 781 leaf host-name { 782 type string; 783 description "Hostname for this system"; 784 } 786 leaf-list domain-search { 787 type string; 788 description "List of domain names to search"; 789 } 791 container login { 792 leaf message { 793 type string; 794 description 795 "Message given at start of login session"; 796 } 798 list user { 799 key "name"; 800 leaf name { 801 type string; 802 } 803 leaf full-name { 804 type string; 805 } 806 leaf class { 807 type string; 808 } 809 } 810 } 811 } 812 } 814 4.2.3. State Data 816 YANG can model state data, as well as configuration data, based on 817 the "config" statement. When a node is tagged with "config false", 818 its subhierarchy is flagged as state data, to be reported using 819 NETCONF's operation, not the operation. Parent 820 containers, lists, and key leafs are reported also, giving the 821 context for the state data. 823 In this example, two leafs are defined for each interface, a 824 configured speed and an observed speed. The observed speed is not 825 configuration, so it can be returned with NETCONF operations, 826 but not with operations. The observed speed is not 827 configuration data, and it cannot be manipulated using . 829 list interface { 830 key "name"; 832 leaf name { 833 type string; 834 } 835 leaf speed { 836 type enumeration { 837 enum 10m; 838 enum 100m; 839 enum auto; 840 } 841 } 842 leaf observed-speed { 843 type uint32; 844 config false; 845 } 846 } 848 4.2.4. Built-In Types 850 YANG has a set of built-in types, similar to those of many 851 programming languages, but with some differences due to special 852 requirements from the management domain. The following table 853 summarizes the built-in types discussed in Section 9: 855 +---------------------+-------------------------------------+ 856 | Name | Description | 857 +---------------------+-------------------------------------+ 858 | binary | Any binary data | 859 | bits | A set of bits or flags | 860 | boolean | "true" or "false" | 861 | decimal64 | 64-bit signed decimal number | 862 | empty | A leaf that does not have any value | 863 | enumeration | Enumerated strings | 864 | identityref | A reference to an abstract identity | 865 | instance-identifier | References a data tree node | 866 | int8 | 8-bit signed integer | 867 | int16 | 16-bit signed integer | 868 | int32 | 32-bit signed integer | 869 | int64 | 64-bit signed integer | 870 | leafref | A reference to a leaf instance | 871 | string | Human-readable string | 872 | uint8 | 8-bit unsigned integer | 873 | uint16 | 16-bit unsigned integer | 874 | uint32 | 32-bit unsigned integer | 875 | uint64 | 64-bit unsigned integer | 876 | union | Choice of member types | 877 +---------------------+-------------------------------------+ 879 The "type" statement is covered in Section 7.4. 881 4.2.5. Derived Types (typedef) 883 YANG can define derived types from base types using the "typedef" 884 statement. A base type can be either a built-in type or a derived 885 type, allowing a hierarchy of derived types. 887 A derived type can be used as the argument for the "type" statement. 889 YANG Example: 891 typedef percent { 892 type uint8 { 893 range "0 .. 100"; 894 } 895 description "Percentage"; 896 } 898 leaf completed { 899 type percent; 900 } 902 NETCONF XML Example: 904 20 906 The "typedef" statement is covered in Section 7.3. 908 4.2.6. Reusable Node Groups (grouping) 910 Groups of nodes can be assembled into reusable collections using the 911 "grouping" statement. A grouping defines a set of nodes that are 912 instantiated with the "uses" statement: 914 grouping target { 915 leaf address { 916 type inet:ip-address; 917 description "Target IP address"; 918 } 919 leaf port { 920 type inet:port-number; 921 description "Target port number"; 922 } 923 } 925 container peer { 926 container destination { 927 uses target; 928 } 929 } 931 NETCONF XML Example: 933 934 935
192.0.2.1
936 830 937 938 940 The grouping can be refined as it is used, allowing certain 941 statements to be overridden. In this example, the description is 942 refined: 944 container connection { 945 container source { 946 uses target { 947 refine "address" { 948 description "Source IP address"; 949 } 950 refine "port" { 951 description "Source port number"; 952 } 953 } 954 } 955 container destination { 956 uses target { 957 refine "address" { 958 description "Destination IP address"; 959 } 960 refine "port" { 961 description "Destination port number"; 962 } 963 } 964 } 965 } 967 The "grouping" statement is covered in Section 7.11. 969 4.2.7. Choices 971 YANG allows the data model to segregate incompatible nodes into 972 distinct choices using the "choice" and "case" statements. The 973 "choice" statement contains a set of "case" statements that define 974 sets of schema nodes that cannot appear together. Each "case" may 975 contain multiple nodes, but each node may appear in only one "case" 976 under a "choice". 978 When a node from one case is created, all nodes from all other cases 979 are implicitly deleted. The device handles the enforcement of the 980 constraint, preventing incompatibilities from existing in the 981 configuration. 983 The choice and case nodes appear only in the schema tree, not in the 984 data tree or NETCONF messages. The additional levels of hierarchy 985 are not needed beyond the conceptual schema. 987 YANG Example: 989 container food { 990 choice snack { 991 case sports-arena { 992 leaf pretzel { 993 type empty; 994 } 995 leaf beer { 996 type empty; 997 } 998 } 999 case late-night { 1000 leaf chocolate { 1001 type enumeration { 1002 enum dark; 1003 enum milk; 1004 enum first-available; 1005 } 1006 } 1007 } 1008 } 1009 } 1011 NETCONF XML Example: 1013 1014 1015 1016 1018 The "choice" statement is covered in Section 7.9. 1020 4.2.8. Extending Data Models (augment) 1022 YANG allows a module to insert additional nodes into data models, 1023 including both the current module (and its submodules) or an external 1024 module. This is useful for example for vendors to add vendor- 1025 specific parameters to standard data models in an interoperable way. 1027 The "augment" statement defines the location in the data model 1028 hierarchy where new nodes are inserted, and the "when" statement 1029 defines the conditions when the new nodes are valid. 1031 YANG Example: 1033 augment /system/login/user { 1034 when "class != 'wheel'"; 1035 leaf uid { 1036 type uint16 { 1037 range "1000 .. 30000"; 1038 } 1039 } 1040 } 1042 This example defines a "uid" node that only is valid when the user's 1043 "class" is not "wheel". 1045 If a module augments another module, the XML representation of the 1046 data will reflect the prefix of the augmenting module. For example, 1047 if the above augmentation were in a module with prefix "other", the 1048 XML would look like: 1050 NETCONF XML Example: 1052 1053 alicew 1054 Alice N. Wonderland 1055 drop-out 1056 1024 1057 1059 The "augment" statement is covered in Section 7.15. 1061 4.2.9. RPC Definitions 1063 YANG allows the definition of NETCONF RPCs. The operations' names, 1064 input parameters, and output parameters are modeled using YANG data 1065 definition statements. 1067 YANG Example: 1069 rpc activate-software-image { 1070 input { 1071 leaf image-name { 1072 type string; 1073 } 1074 } 1075 output { 1076 leaf status { 1077 type string; 1078 } 1079 } 1080 } 1082 NETCONF XML Example: 1084 1086 1087 acmefw-2.3 1088 1089 1091 1093 1094 The image acmefw-2.3 is being installed. 1095 1096 1098 The "rpc" statement is covered in Section 7.13. 1100 4.2.10. Notification Definitions 1102 YANG allows the definition of notifications suitable for NETCONF. 1103 YANG data definition statements are used to model the content of the 1104 notification. 1106 YANG Example: 1108 notification link-failure { 1109 description "A link failure has been detected"; 1110 leaf if-name { 1111 type leafref { 1112 path "/interface/name"; 1113 } 1114 } 1115 leaf if-admin-status { 1116 type admin-status; 1117 } 1118 leaf if-oper-status { 1119 type oper-status; 1120 } 1121 } 1123 NETCONF XML Example: 1125 1127 2007-09-01T10:00:00Z 1128 1129 so-1/2/3.0 1130 up 1131 down 1132 1133 1135 The "notification" statement is covered in Section 7.14. 1137 5. Language Concepts 1139 5.1. Modules and Submodules 1141 The module is the base unit of definition in YANG. A module defines 1142 a single data model. A module can define a complete, cohesive model, 1143 or augment an existing data model with additional nodes. 1145 Submodules are partial modules that contribute definitions to a 1146 module. A module may include any number of submodules, but each 1147 submodule may belong to only one module. 1149 The names of all standard modules and submodules MUST be unique. 1150 Developers of enterprise modules are RECOMMENDED to choose names for 1151 their modules that will have a low probability of colliding with 1152 standard or other enterprise modules, e.g., by using the enterprise 1153 or organization name as a prefix for the module name. 1155 A module uses the "include" statement to include its submodules, and 1156 the "import" statement to reference external modules. Similarly, a 1157 submodule uses the "import" statement to reference other modules, and 1158 uses the "include" statement to reference other submodules within its 1159 module. A module or submodule MUST NOT include submodules from other 1160 modules, and a submodule MUST NOT import its own module. 1162 The import and include statements are used to make definitions 1163 available to other modules and submodules: 1165 o For a module or submodule to reference definitions in an external 1166 module, the external module MUST be imported. 1168 o For a module to reference definitions in one of its submodules, 1169 the module MUST include the submodule. 1171 o For a submodule to reference definitions in a second submodule of 1172 the same module, the first submodule MUST include the second 1173 submodule. 1175 There MUST NOT be any circular chains of imports or includes. For 1176 example, if submodule "a" includes submodule "b", "b" cannot include 1177 "a". 1179 When a definition in an external module is referenced, a locally 1180 defined prefix MUST be used, followed by ":", and then the external 1181 identifier. References to definitions in the local module MAY use 1182 the prefix notation. Since built-in data types do not belong to any 1183 module and have no prefix, references to built-in data types (e.g., 1184 int32) cannot use the prefix notation. 1186 5.1.1. Import and Include by Revision 1188 Published modules evolve independently over time. In order to allow 1189 for this evolution, modules need to be imported using specific 1190 revisions. When a module is written, it uses the current revisions 1191 of other modules, based on what is available at the time. As future 1192 revisions of the imported modules are published, the importing module 1193 is unaffected and its contents are unchanged. When the author of the 1194 module is prepared to move to the most recently published revision of 1195 an imported module, the module is republished with an updated 1196 "import" statement. By republishing with the new revision, the 1197 authors explicitly indicate their acceptance of any changes in the 1198 imported module. 1200 For submodules, the issue is related but simpler. A module or 1201 submodule that includes submodules needs to specify the revision of 1202 the included submodules. If a submodule changes, any module or 1203 submodule that includes it needs to be updated. 1205 For example, module "b" imports module "a". 1207 module a { 1208 yang-version 1.1; 1209 namespace "http://example.com/a"; 1210 prefix "a"; 1212 revision 2008-01-01 { ... } 1213 grouping a { 1214 leaf eh { .... } 1215 } 1216 } 1218 module b { 1219 yang-version 1.1; 1220 namespace "http://example.com/b"; 1221 prefix "b"; 1223 import a { 1224 prefix p; 1225 revision-date 2008-01-01; 1226 } 1228 container bee { 1229 uses p:a; 1230 } 1231 } 1233 When the author of "a" publishes a new revision, the changes may not 1234 be acceptable to the author of "b". If the new revision is 1235 acceptable, the author of "b" can republish with an updated revision 1236 in the "import" statement. 1238 5.1.2. Module Hierarchies 1240 YANG allows modeling of data in multiple hierarchies, where data may 1241 have more than one top-level node. Models that have multiple top- 1242 level nodes are sometimes convenient, and are supported by YANG. 1244 NETCONF is capable of carrying any XML content as the payload in the 1245 and elements. The top-level nodes of YANG modules 1246 are encoded as child elements, in any order, within these elements. 1247 This encapsulation guarantees that the corresponding NETCONF messages 1248 are always well-formed XML documents. 1250 For example: 1252 module my-config { 1253 yang-version 1.1; 1254 namespace "http://example.com/schema/config"; 1255 prefix "co"; 1257 container system { ... } 1258 container routing { ... } 1259 } 1261 could be encoded in NETCONF as: 1263 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1281 5.2. File Layout 1283 YANG modules and submodules are typically stored in files, one module 1284 or submodule per file. The name of the file SHOULD be of the form: 1286 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1288 YANG compilers can find imported modules and included submodules via 1289 this convention. While the YANG language defines modules, tools may 1290 compile submodules independently for performance and manageability 1291 reasons. Errors and warnings that cannot be detected during 1292 submodule compilation may be delayed until the submodules are linked 1293 into a cohesive module. 1295 5.3. XML Namespaces 1297 All YANG definitions are specified within a module that is bound to a 1298 particular XML namespace [XML-NAMES], which is a globally unique URI 1300 [RFC3986]. A NETCONF client or server uses the namespace during XML 1301 encoding of data. 1303 Namespaces for modules published in RFC streams [RFC4844] MUST be 1304 assigned by IANA, see Section 15. 1306 Namespaces for private modules are assigned by the organization 1307 owning the module without a central registry. Namespace URIs MUST be 1308 chosen so they cannot collide with standard or other enterprise 1309 namespaces, for example by using the enterprise or organization name 1310 in the namespace. 1312 The "namespace" statement is covered in Section 7.1.3. 1314 5.3.1. YANG XML Namespace 1316 YANG defines an XML namespace for NETCONF operations 1317 and content. The name of this namespace is 1318 "urn:ietf:params:xml:ns:yang:1". 1320 5.4. Resolving Grouping, Type, and Identity Names 1322 Grouping, type, and identity names are resolved in the context in 1323 which they are defined, rather than the context in which they are 1324 used. Users of groupings, typedefs, and identities are not required 1325 to import modules or include submodules to satisfy all references 1326 made by the original definition. This behaves like static scoping in 1327 a conventional programming language. 1329 For example, if a module defines a grouping in which a type is 1330 referenced, when the grouping is used in a second module, the type is 1331 resolved in the context of the original module, not the second 1332 module. There is no worry over conflicts if both modules define the 1333 type, since there is no ambiguity. 1335 5.5. Nested Typedefs and Groupings 1337 Typedefs and groupings may appear nested under many YANG statements, 1338 allowing these to be lexically scoped by the hierarchy under which 1339 they appear. This allows types and groupings to be defined near 1340 where they are used, rather than placing them at the top level of the 1341 hierarchy. The close proximity increases readability. 1343 Scoping also allows types to be defined without concern for naming 1344 conflicts between types in different submodules. Type names can be 1345 specified without adding leading strings designed to prevent name 1346 collisions within large modules. 1348 Finally, scoping allows the module author to keep types and groupings 1349 private to their module or submodule, preventing their reuse. Since 1350 only top-level types and groupings (i.e., those appearing as 1351 substatements to a module or submodule statement) can be used outside 1352 the module or submodule, the developer has more control over what 1353 pieces of their module are presented to the outside world, supporting 1354 the need to hide internal information and maintaining a boundary 1355 between what is shared with the outside world and what is kept 1356 private. 1358 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1359 type or grouping cannot be defined if a higher level in the schema 1360 hierarchy has a definition with a matching identifier. 1362 A reference to an unprefixed type or grouping, or one which uses the 1363 prefix of the current module, is resolved by locating the closest 1364 matching "typedef" or "grouping" statement among the immediate 1365 substatements of each ancestor statement. 1367 5.6. Conformance 1369 Conformance is a measure of how accurately a device follows the 1370 model. Generally speaking, devices are responsible for implementing 1371 the model faithfully, allowing applications to treat devices which 1372 implement the model identically. Deviations from the model can 1373 reduce the utility of the model and increase fragility of 1374 applications that use it. 1376 YANG modelers have three mechanisms for conformance: 1378 o the basic behavior of the model 1380 o optional features that are part of the model 1382 o deviations from the model 1384 We will consider each of these in sequence. 1386 5.6.1. Basic Behavior 1388 The model defines a contract between the NETCONF client and server, 1389 which allows both parties to have faith the other knows the syntax 1390 and semantics behind the modeled data. The strength of YANG lies in 1391 the strength of this contract. 1393 5.6.2. Optional Features 1395 In many models, the modeler will allow sections of the model to be 1396 conditional. The device controls whether these conditional portions 1397 of the model are supported or valid for that particular device. 1399 For example, a syslog data model may choose to include the ability to 1400 save logs locally, but the modeler will realize that this is only 1401 possible if the device has local storage. If there is no local 1402 storage, an application should not tell the device to save logs. 1404 YANG supports this conditional mechanism using a construct called 1405 "feature". Features give the modeler a mechanism for making portions 1406 of the module conditional in a manner that is controlled by the 1407 device. The model can express constructs that are not universally 1408 present in all devices. These features are included in the model 1409 definition, allowing a consistent view and allowing applications to 1410 learn which features are supported and tailor their behavior to the 1411 device. 1413 A module may declare any number of features, identified by simple 1414 strings, and may make portions of the module optional based on those 1415 features. If the device supports a feature, then the corresponding 1416 portions of the module are valid for that device. If the device 1417 doesn't support the feature, those parts of the module are not valid, 1418 and applications should behave accordingly. 1420 Features are defined using the "feature" statement. Definitions in 1421 the module that are conditional to the feature are noted by the 1422 "if-feature" statement. 1424 Further details are available in Section 7.18.1. 1426 5.6.3. Deviations 1428 In an ideal world, all devices would be required to implement the 1429 model exactly as defined, and deviations from the model would not be 1430 allowed. But in the real world, devices are often not able or 1431 designed to implement the model as written. For YANG-based 1432 automation to deal with these device deviations, a mechanism must 1433 exist for devices to inform applications of the specifics of such 1434 deviations. 1436 For example, a BGP module may allow any number of BGP peers, but a 1437 particular device may only support 16 BGP peers. Any application 1438 configuring the 17th peer will receive an error. While an error may 1439 suffice to let the application know it cannot add another peer, it 1440 would be far better if the application had prior knowledge of this 1441 limitation and could prevent the user from starting down the path 1442 that could not succeed. 1444 Device deviations are declared using the "deviation" statement, which 1445 takes as its argument a string that identifies a node in the schema 1446 tree. The contents of the statement details the manner in which the 1447 device implementation deviates from the contract as defined in the 1448 module. 1450 Further details are available in Section 7.18.3. 1452 5.6.4. Announcing Conformance Information in the Message 1454 The namespace URI MUST be advertised as a capability in the NETCONF 1455 message to indicate support for the YANG module by a NETCONF 1456 server. The capability URI advertised MUST be of the form: 1458 capability-string = namespace-uri [ parameter-list ] 1459 parameter-list = "?" parameter *( "&" parameter ) 1460 parameter = revision-parameter / 1461 module-parameter / 1462 feature-parameter / 1463 deviation-parameter 1464 revision-parameter = "revision=" revision-date 1465 module-parameter = "module=" module-name 1466 feature-parameter = "features=" feature *( "," feature ) 1467 deviation-parameter = "deviations=" deviation *( "," deviation ) 1469 Where "revision-date" is the revision of the module (see 1470 Section 7.1.9) that the NETCONF server implements, "module-name" is 1471 the name of module as it appears in the "module" statement (see 1472 Section 7.1), "namespace-uri" is the namespace URI for the module as 1473 it appears in the "namespace" statement (see Section 7.1.3), 1474 "feature" is the name of an optional feature implemented by the 1475 device (see Section 7.18.1), and "deviation" is the name of a module 1476 defining device deviations (see Section 7.18.3). 1478 In the parameter list, each named parameter MUST occur at most once. 1480 5.6.4.1. Modules 1482 Servers indicate the names of supported modules via the 1483 message. Module namespaces are encoded as the base URI in the 1484 capability string, and the module name is encoded as the "module" 1485 parameter to the base URI. 1487 A server MUST advertise all revisions of all modules it implements. 1489 For example, this message advertises one module "syslog". 1491 1492 1493 1494 1495 http://example.com/syslog?module=syslog& 1496 revision=2008-04-01 1497 1498 1499 42 1500 1502 5.6.4.2. Features 1504 Servers indicate the names of supported features via the 1505 message. In messages, the features are encoded in the 1506 "features" parameter within the URI. The value of this parameter is 1507 a comma-separated list of feature names that the device supports for 1508 the specific module. 1510 For example, this message advertises one module, informing 1511 the client that it supports the "local-storage" feature of module 1512 "syslog". 1514 1515 1516 1517 1518 http://example.com/syslog?module=syslog& 1519 features=local-storage 1520 1521 1522 43 1523 1525 5.6.4.3. Deviations 1527 Device deviations are announced via the "deviations" parameter. The 1528 value of the "deviations" parameter is a comma-separated list of 1529 modules containing deviations from the capability's module. 1531 For example, this message advertises two modules, informing 1532 the client that it deviates from module "syslog" according to the 1533 deviations listed in the module "my-devs". 1535 1536 1537 1538 1539 http://example.com/syslog?module=syslog& 1540 deviations=my-devs 1541 1542 1543 http://example.com/my-deviations?module=my-devs 1544 1545 1546 44 1547 1549 5.7. Data Store Modification 1551 Data models may allow the server to alter the configuration data 1552 store in ways not explicitly directed via NETCONF protocol messages. 1553 For example, a data model may define leafs that are assigned system- 1554 generated values when the client does not provide one. A formal 1555 mechanism for specifying the circumstances where these changes are 1556 allowed is out of scope for this specification. 1558 6. YANG Syntax 1560 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1561 languages like C and C++. This C-like syntax was chosen specifically 1562 for its readability, since YANG values the time and effort of the 1563 readers of models above those of modules writers and YANG tool-chain 1564 developers. This section introduces the YANG syntax. 1566 YANG modules use the UTF-8 [RFC3629] character encoding. 1568 6.1. Lexical Tokenization 1570 YANG modules are parsed as a series of tokens. This section details 1571 the rules for recognizing tokens from an input stream. YANG 1572 tokenization rules are both simple and powerful. The simplicity is 1573 driven by a need to keep the parsers easy to implement, while the 1574 power is driven by the fact that modelers need to express their 1575 models in readable formats. 1577 6.1.1. Comments 1579 Comments are C++ style. A single line comment starts with "//" and 1580 ends at the end of the line. A block comment is enclosed within "/*" 1581 and "*/". 1583 6.1.2. Tokens 1585 A token in YANG is either a keyword, a string, a semicolon (";"), or 1586 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1587 is either one of the YANG keywords defined in this document, or a 1588 prefix identifier, followed by ":", followed by a language extension 1589 keyword. Keywords are case sensitive. See Section 6.2 for a formal 1590 definition of identifiers. 1592 6.1.3. Quoting 1594 If a string contains any space or tab characters, a semicolon (";"), 1595 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1596 it MUST be enclosed within double or single quotes. 1598 If the double-quoted string contains a line break followed by space 1599 or tab characters that are used to indent the text according to the 1600 layout in the YANG file, this leading whitespace is stripped from the 1601 string, up to and including the column of the double quote character, 1602 or to the first non-whitespace character, whichever occurs first. In 1603 this process, a tab character is treated as 8 space characters. 1605 If the double-quoted string contains space or tab characters before a 1606 line break, this trailing whitespace is stripped from the string. 1608 A single-quoted string (enclosed within ' ') preserves each character 1609 within the quotes. A single quote character cannot occur in a 1610 single-quoted string, even when preceded by a backslash. 1612 Within a double-quoted string (enclosed within " "), a backslash 1613 character introduces a special character, which depends on the 1614 character that immediately follows the backslash: 1616 \n new line 1617 \t a tab character 1618 \" a double quote 1619 \\ a single backslash 1621 It is an error if any other character follows the backslash 1622 character. 1624 If a quoted string is followed by a plus character ("+"), followed by 1625 another quoted string, the two strings are concatenated into one 1626 string, allowing multiple concatenations to build one string. 1627 Whitespace trimming and substitution of backslash-escaped characters 1628 in double-quoted strings is done before concatenation. 1630 6.1.3.1. Quoting Examples 1632 The following strings are equivalent: 1634 hello 1635 "hello" 1636 'hello' 1637 "hel" + "lo" 1638 'hel' + "lo" 1640 The following examples show some special strings: 1642 "\"" - string containing a double quote 1643 '"' - string containing a double quote 1644 "\n" - string containing a new line character 1645 '\n' - string containing a backslash followed 1646 by the character n 1648 The following examples show some illegal strings: 1650 '''' - a single-quoted string cannot contain single quotes 1651 """ - a double quote must be escaped in a double-quoted string 1653 The following strings are equivalent: 1655 "first line 1656 second line" 1658 "first line\n" + " second line" 1660 6.2. Identifiers 1662 Identifiers are used to identify different kinds of YANG items by 1663 name. Each identifier starts with an uppercase or lowercase ASCII 1664 letter or an underscore character, followed by zero or more ASCII 1665 letters, digits, underscore characters, hyphens, and dots. 1666 Implementations MUST support identifiers up to 64 characters in 1667 length. Identifiers are case sensitive. The identifier syntax is 1668 formally defined by the rule "identifier" in Section 13. Identifiers 1669 can be specified as quoted or unquoted strings. 1671 6.2.1. Identifiers and Their Namespaces 1673 Each identifier is valid in a namespace that depends on the type of 1674 the YANG item being defined. All identifiers defined in a namespace 1675 MUST be unique. 1677 o All module and submodule names share the same global module 1678 identifier namespace. 1680 o All extension names defined in a module and its submodules share 1681 the same extension identifier namespace. 1683 o All feature names defined in a module and its submodules share the 1684 same feature identifier namespace. 1686 o All identity names defined in a module and its submodules share 1687 the same identity identifier namespace. 1689 o All derived type names defined within a parent node or at the top 1690 level of the module or its submodules share the same type 1691 identifier namespace. This namespace is scoped to all descendant 1692 nodes of the parent node or module. This means that any 1693 descendent node may use that typedef, and it MUST NOT define a 1694 typedef with the same name. 1696 o All grouping names defined within a parent node or at the top 1697 level of the module or its submodules share the same grouping 1698 identifier namespace. This namespace is scoped to all descendant 1699 nodes of the parent node or module. This means that any 1700 descendent node may use that grouping, and it MUST NOT define a 1701 grouping with the same name. 1703 o All leafs, leaf-lists, lists, containers, choices, rpcs, 1704 notifications, and anyxmls defined (directly or through a uses 1705 statement) within a parent node or at the top level of the module 1706 or its submodules share the same identifier namespace. This 1707 namespace is scoped to the parent node or module, unless the 1708 parent node is a case node. In that case, the namespace is scoped 1709 to the closest ancestor node that is not a case or choice node. 1711 o All cases within a choice share the same case identifier 1712 namespace. This namespace is scoped to the parent choice node. 1714 Forward references are allowed in YANG. 1716 6.3. Statements 1718 A YANG module contains a sequence of statements. Each statement 1719 starts with a keyword, followed by zero or one argument, followed 1720 either by a semicolon (";") or a block of substatements enclosed 1721 within braces ("{ }"): 1723 statement = keyword [argument] (";" / "{" *statement "}") 1725 The argument is a string, as defined in Section 6.1.2. 1727 6.3.1. Language Extensions 1729 A module can introduce YANG extensions by using the "extension" 1730 keyword (see Section 7.17). The extensions can be imported by other 1731 modules with the "import" statement (see Section 7.1.5). When an 1732 imported extension is used, the extension's keyword MUST be qualified 1733 using the prefix with which the extension's module was imported. If 1734 an extension is used in the module where it is defined, the 1735 extension's keyword MUST be qualified with the module's prefix. 1737 Since submodules cannot include the parent module, any extensions in 1738 the module that need to be exposed to submodules MUST be defined in a 1739 submodule. Submodules can then include this submodule to find the 1740 definition of the extension. 1742 If a YANG compiler does not support a particular extension, which 1743 appears in a YANG module as an unknown-statement (see Section 13), 1744 the entire unknown-statement MAY be ignored by the compiler. 1746 6.4. XPath Evaluations 1748 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 1749 for specifying many inter-node references and dependencies. NETCONF 1750 clients and servers are not required to implement an XPath 1751 interpreter, but MUST ensure that the requirements encoded in the 1752 data model are enforced. The manner of enforcement is an 1753 implementation decision. The XPath expressions MUST be syntactically 1754 correct, and all prefixes used MUST be present in the XPath context 1755 (see Section 6.4.1). An implementation may choose to implement them 1756 by hand, rather than using the XPath expression directly. 1758 The data model used in the XPath expressions is the same as that used 1759 in XPath 1.0 [XPATH], with the same extension for root node children 1760 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 1761 that the root node may have any number of element nodes as its 1762 children. 1764 6.4.1. XPath Context 1766 All YANG XPath expressions share the following XPath context 1767 definition: 1769 o The set of namespace declarations is the set of all "import" 1770 statements' prefix and namespace pairs in the module where the 1771 XPath expression is specified, and the "prefix" statement's prefix 1772 for the "namespace" statement's URI. 1774 o Names without a namespace prefix belong to the same namespace as 1775 the identifier of the current node. Inside a grouping, that 1776 namespace is affected by where the grouping is used (see 1777 Section 7.12). 1779 o The function library is the core function library defined in 1780 [XPATH], and the functions defined in Section 10. 1782 o The set of variable bindings is empty. 1784 The mechanism for handling unprefixed names is adopted from XPath 2.0 1785 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1786 ambiguity may ever arise because YANG node identifiers are always 1787 qualified names with a non-null namespace URI. 1789 The context node varies with the YANG XPath expression, and is 1790 specified where the YANG statement with the XPath expression is 1791 defined. 1793 6.5. Schema Node Identifier 1795 A schema node identifier is a string that identifies a node in the 1796 schema tree. It has two forms, "absolute" and "descendant", defined 1797 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1798 in Section 13, respectively. A schema node identifier consists of a 1799 path of identifiers, separated by slashes ("/"). In an absolute 1800 schema node identifier, the first identifier after the leading slash 1801 is any top-level schema node in the local module or in all imported 1802 modules. 1804 References to identifiers defined in external modules MUST be 1805 qualified with appropriate prefixes, and references to identifiers 1806 defined in the current module and its submodules MAY use a prefix. 1808 For example, to identify the child node "b" of top-level node "a", 1809 the string "/a/b" can be used. 1811 7. YANG Statements 1813 The following sections describe all of the YANG statements. 1815 Note that even a statement that does not have any substatements 1816 defined in YANG can have vendor-specific extensions as substatements. 1817 For example, the "description" statement does not have any 1818 substatements defined in YANG, but the following is legal: 1820 description "some text" { 1821 acme:documentation-flag 5; 1822 } 1824 7.1. The module Statement 1826 The "module" statement defines the module's name, and groups all 1827 statements that belong to the module together. The "module" 1828 statement's argument is the name of the module, followed by a block 1829 of substatements that hold detailed module information. The module 1830 name follows the rules for identifiers in Section 6.2. 1832 Names of modules published in RFC streams [RFC4844] MUST be assigned 1833 by IANA, see Section 15. 1835 Private module names are assigned by the organization owning the 1836 module without a central registry. It is RECOMMENDED to choose 1837 module names that will have a low probability of colliding with 1838 standard or other enterprise modules and submodules, e.g., by using 1839 the enterprise or organization name as a prefix for the module name. 1841 A module typically has the following layout: 1843 module { 1845 // header information 1846 1847 1848 1850 // linkage statements 1851 1852 1854 // meta information 1855 1856 1857 1858 1860 // revision history 1861 1863 // module definitions 1864 1865 } 1867 7.1.1. The module's Substatements 1869 +--------------+---------+-------------+ 1870 | substatement | section | cardinality | 1871 +--------------+---------+-------------+ 1872 | anyxml | 7.10 | 0..n | 1873 | augment | 7.15 | 0..n | 1874 | choice | 7.9 | 0..n | 1875 | contact | 7.1.8 | 0..1 | 1876 | container | 7.5 | 0..n | 1877 | description | 7.19.3 | 0..1 | 1878 | deviation | 7.18.3 | 0..n | 1879 | extension | 7.17 | 0..n | 1880 | feature | 7.18.1 | 0..n | 1881 | grouping | 7.11 | 0..n | 1882 | identity | 7.16 | 0..n | 1883 | import | 7.1.5 | 0..n | 1884 | include | 7.1.6 | 0..n | 1885 | leaf | 7.6 | 0..n | 1886 | leaf-list | 7.7 | 0..n | 1887 | list | 7.8 | 0..n | 1888 | namespace | 7.1.3 | 1 | 1889 | notification | 7.14 | 0..n | 1890 | organization | 7.1.7 | 0..1 | 1891 | prefix | 7.1.4 | 1 | 1892 | reference | 7.19.4 | 0..1 | 1893 | revision | 7.1.9 | 0..n | 1894 | rpc | 7.13 | 0..n | 1895 | typedef | 7.3 | 0..n | 1896 | uses | 7.12 | 0..n | 1897 | yang-version | 7.1.2 | 1 | 1898 +--------------+---------+-------------+ 1900 7.1.2. The yang-version Statement 1902 The "yang-version" statement specifies which version of the YANG 1903 language was used in developing the module. The statement's argument 1904 is a string. It MUST contain the value "1.1", which is the current 1905 YANG version. 1907 A module or submodule that doesn't contain the "yang-version" 1908 statement, or one that contains the value "1", is developed for YANG 1909 version 1, defined in [RFC6020]. 1911 Handling of the "yang-version" statement for versions other than 1912 "1.1" (the version defined here) is out of scope for this 1913 specification. Any document that defines a higher version will need 1914 to define the backward compatibility of such a higher version. 1916 7.1.3. The namespace Statement 1918 The "namespace" statement defines the XML namespace that all 1919 identifiers defined by the module are qualified by, with the 1920 exception of data node identifiers defined inside a grouping (see 1921 Section 7.12 for details). The argument to the "namespace" statement 1922 is the URI of the namespace. 1924 See also Section 5.3. 1926 7.1.4. The prefix Statement 1928 The "prefix" statement is used to define the prefix associated with 1929 the module and its namespace. The "prefix" statement's argument is 1930 the prefix string that is used as a prefix to access a module. The 1931 prefix string MAY be used to refer to definitions contained in the 1932 module, e.g., "if:ifName". A prefix follows the same rules as an 1933 identifier (see Section 6.2). 1935 When used inside the "module" statement, the "prefix" statement 1936 defines the prefix to be used when this module is imported. To 1937 improve readability of the NETCONF XML, a NETCONF client or server 1938 that generates XML or XPath that use prefixes SHOULD use the prefix 1939 defined by the module, unless there is a conflict. 1941 When used inside the "import" statement, the "prefix" statement 1942 defines the prefix to be used when accessing definitions inside the 1943 imported module. When a reference to an identifier from the imported 1944 module is used, the prefix string for the imported module is used in 1945 combination with a colon (":") and the identifier, e.g., 1946 "if:ifIndex". To improve readability of YANG modules, the prefix 1947 defined by a module SHOULD be used when the module is imported, 1948 unless there is a conflict. If there is a conflict, i.e., two 1949 different modules that both have defined the same prefix are 1950 imported, at least one of them MUST be imported with a different 1951 prefix. 1953 All prefixes, including the prefix for the module itself MUST be 1954 unique within the module or submodule. 1956 7.1.5. The import Statement 1958 The "import" statement makes definitions from one module available 1959 inside another module or submodule. The argument is the name of the 1960 module to import, and the statement is followed by a block of 1961 substatements that holds detailed import information. When a module 1962 is imported, the importing module may: 1964 o use any grouping and typedef defined at the top level in the 1965 imported module or its submodules. 1967 o use any extension, feature, and identity defined in the imported 1968 module or its submodules. 1970 o use any node in the imported module's schema tree in "must", 1971 "path", and "when" statements, or as the target node in "augment" 1972 and "deviation" statements. 1974 The mandatory "prefix" substatement assigns a prefix for the imported 1975 module that is scoped to the importing module or submodule. Multiple 1976 "import" statements may be specified to import from different 1977 modules. 1979 When the optional "revision-date" substatement is present, any 1980 typedef, grouping, extension, feature, and identity referenced by 1981 definitions in the local module are taken from the specified revision 1982 of the imported module. It is an error if the specified revision of 1983 the imported module does not exist. If no "revision-date" 1984 substatement is present, it is undefined from which revision of the 1985 module they are taken. 1987 Multiple revisions of the same module MUST NOT be imported. 1989 +---------------+---------+-------------+ 1990 | substatement | section | cardinality | 1991 +---------------+---------+-------------+ 1992 | prefix | 7.1.4 | 1 | 1993 | revision-date | 7.1.5.1 | 0..1 | 1994 +---------------+---------+-------------+ 1996 The import's Substatements 1998 7.1.5.1. The import's revision-date Statement 2000 The import's "revision-date" statement is used to specify the exact 2001 version of the module to import. The "revision-date" statement MUST 2002 match the most recent "revision" statement in the imported module. 2004 7.1.6. The include Statement 2006 The "include" statement is used to make content from a submodule 2007 available to that submodule's parent module, or to another submodule 2008 of that parent module. The argument is an identifier that is the 2009 name of the submodule to include. Modules are only allowed to 2010 include submodules that belong to that module, as defined by the 2011 "belongs-to" statement (see Section 7.2.2). Submodules are only 2012 allowed to include other submodules belonging to the same module. 2014 When a module includes a submodule, it incorporates the contents of 2015 the submodule into the node hierarchy of the module. When a 2016 submodule includes another submodule, the target submodule's 2017 definitions are made available to the current submodule. 2019 When the optional "revision-date" substatement is present, the 2020 specified revision of the submodule is included in the module. It is 2021 an error if the specified revision of the submodule does not exist. 2022 If no "revision-date" substatement is present, it is undefined which 2023 revision of the submodule is included. 2025 Multiple revisions of the same submodule MUST NOT be included. 2027 +---------------+---------+-------------+ 2028 | substatement | section | cardinality | 2029 +---------------+---------+-------------+ 2030 | revision-date | 7.1.5.1 | 0..1 | 2031 +---------------+---------+-------------+ 2033 The includes's Substatements 2035 7.1.7. The organization Statement 2037 The "organization" statement defines the party responsible for this 2038 module. The argument is a string that is used to specify a textual 2039 description of the organization(s) under whose auspices this module 2040 was developed. 2042 7.1.8. The contact Statement 2044 The "contact" statement provides contact information for the module. 2045 The argument is a string that is used to specify contact information 2046 for the person or persons to whom technical queries concerning this 2047 module should be sent, such as their name, postal address, telephone 2048 number, and electronic mail address. 2050 7.1.9. The revision Statement 2052 The "revision" statement specifies the editorial revision history of 2053 the module, including the initial revision. A series of revision 2054 statements detail the changes in the module's definition. The 2055 argument is a date string in the format "YYYY-MM-DD", followed by a 2056 block of substatements that holds detailed revision information. A 2057 module SHOULD have at least one "revision" statement. For every 2058 published editorial change, a new one SHOULD be added in front of the 2059 revisions sequence, so that all revisions are in reverse 2060 chronological order. 2062 7.1.9.1. The revision's Substatement 2064 +--------------+---------+-------------+ 2065 | substatement | section | cardinality | 2066 +--------------+---------+-------------+ 2067 | description | 7.19.3 | 0..1 | 2068 | reference | 7.19.4 | 0..1 | 2069 +--------------+---------+-------------+ 2071 7.1.10. Usage Example 2073 module acme-system { 2074 yang-version 1.1; 2075 namespace "http://acme.example.com/system"; 2076 prefix "acme"; 2078 import ietf-yang-types { 2079 prefix "yang"; 2080 } 2082 include acme-types; 2084 organization "ACME Inc."; 2085 contact 2086 "Joe L. User 2088 ACME, Inc. 2089 42 Anywhere Drive 2090 Nowhere, CA 95134 2091 USA 2093 Phone: +1 800 555 0100 2094 EMail: joe@acme.example.com"; 2096 description 2097 "The module for entities implementing the ACME protocol."; 2099 revision "2007-06-09" { 2100 description "Initial revision."; 2101 } 2103 // definitions follow... 2104 } 2106 7.2. The submodule Statement 2108 While the primary unit in YANG is a module, a YANG module can itself 2109 be constructed out of several submodules. Submodules allow a module 2110 designer to split a complex model into several pieces where all the 2111 submodules contribute to a single namespace, which is defined by the 2112 module that includes the submodules. 2114 The "submodule" statement defines the submodule's name, and groups 2115 all statements that belong to the submodule together. The 2116 "submodule" statement's argument is the name of the submodule, 2117 followed by a block of substatements that hold detailed submodule 2118 information. The submodule name follows the rules for identifiers in 2119 Section 6.2. 2121 Names of submodules published in RFC streams [RFC4844] MUST be 2122 assigned by IANA, see Section 15. 2124 Private submodule names are assigned by the organization owning the 2125 submodule without a central registry. It is RECOMMENDED to choose 2126 submodule names that will have a low probability of colliding with 2127 standard or other enterprise modules and submodules, e.g., by using 2128 the enterprise or organization name as a prefix for the submodule 2129 name. 2131 A submodule typically has the following layout: 2133 submodule { 2135 2136 // module identification 2137 2139 // linkage statements 2140 2141 2143 // meta information 2144 2145 2146 2147 2149 // revision history 2150 2152 // module definitions 2153 2154 } 2156 7.2.1. The submodule's Substatements 2157 +--------------+---------+-------------+ 2158 | substatement | section | cardinality | 2159 +--------------+---------+-------------+ 2160 | anyxml | 7.10 | 0..n | 2161 | augment | 7.15 | 0..n | 2162 | belongs-to | 7.2.2 | 1 | 2163 | choice | 7.9 | 0..n | 2164 | contact | 7.1.8 | 0..1 | 2165 | container | 7.5 | 0..n | 2166 | description | 7.19.3 | 0..1 | 2167 | deviation | 7.18.3 | 0..n | 2168 | extension | 7.17 | 0..n | 2169 | feature | 7.18.1 | 0..n | 2170 | grouping | 7.11 | 0..n | 2171 | identity | 7.16 | 0..n | 2172 | import | 7.1.5 | 0..n | 2173 | include | 7.1.6 | 0..n | 2174 | leaf | 7.6 | 0..n | 2175 | leaf-list | 7.7 | 0..n | 2176 | list | 7.8 | 0..n | 2177 | notification | 7.14 | 0..n | 2178 | organization | 7.1.7 | 0..1 | 2179 | reference | 7.19.4 | 0..1 | 2180 | revision | 7.1.9 | 0..n | 2181 | rpc | 7.13 | 0..n | 2182 | typedef | 7.3 | 0..n | 2183 | uses | 7.12 | 0..n | 2184 | yang-version | 7.1.2 | 1 | 2185 +--------------+---------+-------------+ 2187 7.2.2. The belongs-to Statement 2189 The "belongs-to" statement specifies the module to which the 2190 submodule belongs. The argument is an identifier that is the name of 2191 the module. 2193 A submodule MUST only be included by the module to which it belongs, 2194 or by another submodule that belongs to that module. 2196 The mandatory "prefix" substatement assigns a prefix for the module 2197 to which the submodule belongs. All definitions in the local 2198 submodule and any included submodules can be accessed by using the 2199 prefix. 2201 +--------------+---------+-------------+ 2202 | substatement | section | cardinality | 2203 +--------------+---------+-------------+ 2204 | prefix | 7.1.4 | 1 | 2205 +--------------+---------+-------------+ 2207 The belongs-to's Substatements 2209 7.2.3. Usage Example 2211 submodule acme-types { 2212 yang-version 1.1; 2213 belongs-to "acme-system" { 2214 prefix "acme"; 2215 } 2217 import ietf-yang-types { 2218 prefix "yang"; 2219 } 2221 organization "ACME Inc."; 2222 contact 2223 "Joe L. User 2225 ACME, Inc. 2226 42 Anywhere Drive 2227 Nowhere, CA 95134 2228 USA 2230 Phone: +1 800 555 0100 2231 EMail: joe@acme.example.com"; 2233 description 2234 "This submodule defines common ACME types."; 2236 revision "2007-06-09" { 2237 description "Initial revision."; 2238 } 2240 // definitions follows... 2241 } 2243 7.3. The typedef Statement 2245 The "typedef" statement defines a new type that may be used locally 2246 in the module, in modules or submodules which include it, and by 2247 other modules that import from it, according to the rules in 2248 Section 5.5. The new type is called the "derived type", and the type 2249 from which it was derived is called the "base type". All derived 2250 types can be traced back to a YANG built-in type. 2252 The "typedef" statement's argument is an identifier that is the name 2253 of the type to be defined, and MUST be followed by a block of 2254 substatements that holds detailed typedef information. 2256 The name of the type MUST NOT be one of the YANG built-in types. If 2257 the typedef is defined at the top level of a YANG module or 2258 submodule, the name of the type to be defined MUST be unique within 2259 the module. 2261 7.3.1. The typedef's Substatements 2263 +--------------+---------+-------------+ 2264 | substatement | section | cardinality | 2265 +--------------+---------+-------------+ 2266 | default | 7.3.4 | 0..1 | 2267 | description | 7.19.3 | 0..1 | 2268 | reference | 7.19.4 | 0..1 | 2269 | status | 7.19.2 | 0..1 | 2270 | type | 7.3.2 | 1 | 2271 | units | 7.3.3 | 0..1 | 2272 +--------------+---------+-------------+ 2274 7.3.2. The typedef's type Statement 2276 The "type" statement, which MUST be present, defines the base type 2277 from which this type is derived. See Section 7.4 for details. 2279 7.3.3. The units Statement 2281 The "units" statement, which is optional, takes as an argument a 2282 string that contains a textual definition of the units associated 2283 with the type. 2285 7.3.4. The typedef's default Statement 2287 The "default" statement takes as an argument a string that contains a 2288 default value for the new type. 2290 The value of the "default" statement MUST be valid according to the 2291 type specified in the "type" statement. 2293 If the base type has a default value, and the new derived type does 2294 not specify a new default value, the base type's default value is 2295 also the default value of the new derived type. 2297 If the type's default value is not valid according to the new 2298 restrictions specified in a derived type or leaf definition, the 2299 derived type or leaf definition MUST specify a new default value 2300 compatible with the restrictions. 2302 7.3.5. Usage Example 2304 typedef listen-ipv4-address { 2305 type inet:ipv4-address; 2306 default "0.0.0.0"; 2307 } 2309 7.4. The type Statement 2311 The "type" statement takes as an argument a string that is the name 2312 of a YANG built-in type (see Section 9) or a derived type (see 2313 Section 7.3), followed by an optional block of substatements that are 2314 used to put further restrictions on the type. 2316 The restrictions that can be applied depend on the type being 2317 restricted. The restriction statements for all built-in types are 2318 described in the subsections of Section 9. 2320 7.4.1. The type's Substatements 2322 +------------------+---------+-------------+ 2323 | substatement | section | cardinality | 2324 +------------------+---------+-------------+ 2325 | base | 7.16.2 | 0..1 | 2326 | bit | 9.7.4 | 0..n | 2327 | enum | 9.6.4 | 0..n | 2328 | fraction-digits | 9.3.4 | 0..1 | 2329 | length | 9.4.4 | 0..1 | 2330 | path | 9.9.2 | 0..1 | 2331 | pattern | 9.4.5 | 0..n | 2332 | range | 9.2.4 | 0..1 | 2333 | require-instance | 9.9.3 | 0..1 | 2334 | type | 7.4 | 0..n | 2335 +------------------+---------+-------------+ 2337 7.5. The container Statement 2339 The "container" statement is used to define an interior data node in 2340 the schema tree. It takes one argument, which is an identifier, 2341 followed by a block of substatements that holds detailed container 2342 information. 2344 A container node does not have a value, but it has a list of child 2345 nodes in the data tree. The child nodes are defined in the 2346 container's substatements. 2348 7.5.1. Containers with Presence 2350 YANG supports two styles of containers, those that exist only for 2351 organizing the hierarchy of data nodes, and those whose presence in 2352 the configuration has an explicit meaning. 2354 In the first style, the container has no meaning of its own, existing 2355 only to contain child nodes. This is the default style. 2357 For example, the set of scrambling options for Synchronous Optical 2358 Network (SONET) interfaces may be placed inside a "scrambling" 2359 container to enhance the organization of the configuration hierarchy, 2360 and to keep these nodes together. The "scrambling" node itself has 2361 no meaning, so removing the node when it becomes empty relieves the 2362 user from performing this task. 2364 In the second style, the presence of the container itself is 2365 configuration data, representing a single bit of configuration data. 2366 The container acts as both a configuration knob and a means of 2367 organizing related configuration. These containers are explicitly 2368 created and deleted. 2370 YANG calls this style a "presence container" and it is indicated 2371 using the "presence" statement, which takes as its argument a text 2372 string indicating what the presence of the node means. 2374 For example, an "ssh" container may turn on the ability to log into 2375 the device using ssh, but can also contain any ssh-related 2376 configuration knobs, such as connection rates or retry limits. 2378 The "presence" statement (see Section 7.5.5) is used to give 2379 semantics to the existence of the container in the data tree. 2381 7.5.2. The container's Substatements 2382 +--------------+---------+-------------+ 2383 | substatement | section | cardinality | 2384 +--------------+---------+-------------+ 2385 | anyxml | 7.10 | 0..n | 2386 | choice | 7.9 | 0..n | 2387 | config | 7.19.1 | 0..1 | 2388 | container | 7.5 | 0..n | 2389 | description | 7.19.3 | 0..1 | 2390 | grouping | 7.11 | 0..n | 2391 | if-feature | 7.18.2 | 0..n | 2392 | leaf | 7.6 | 0..n | 2393 | leaf-list | 7.7 | 0..n | 2394 | list | 7.8 | 0..n | 2395 | must | 7.5.3 | 0..n | 2396 | presence | 7.5.5 | 0..1 | 2397 | reference | 7.19.4 | 0..1 | 2398 | status | 7.19.2 | 0..1 | 2399 | typedef | 7.3 | 0..n | 2400 | uses | 7.12 | 0..n | 2401 | when | 7.19.5 | 0..1 | 2402 +--------------+---------+-------------+ 2404 7.5.3. The must Statement 2406 The "must" statement, which is optional, takes as an argument a 2407 string that contains an XPath expression (see Section 6.4). It is 2408 used to formally declare a constraint on valid data. The constraint 2409 is enforced according to the rules in Section 8. 2411 When a datastore is validated, all "must" constraints are 2412 conceptually evaluated once for each data node in the data tree, and 2413 for all leafs with default values in use (see Section 7.6.1). If a 2414 data node does not exist in the data tree, and it does not have a 2415 default value, its "must" statements are not evaluated. 2417 All such constraints MUST evaluate to true for the data to be valid. 2419 The XPath expression is conceptually evaluated in the following 2420 context, in addition to the definition in Section 6.4.1: 2422 o The context node is the node in the data tree for which the "must" 2423 statement is defined. 2425 o The accessible tree is made up of all nodes in the data tree, and 2426 all leafs with default values in use (see Section 7.6.1). 2428 The accessible tree depends on the context node: 2430 o If the context node represents configuration, the tree is the data 2431 in the NETCONF datastore where the context node exists. The XPath 2432 root node has all top-level configuration data nodes in all 2433 modules as children. 2435 o If the context node represents state data, the tree is all state 2436 data on the device, and the "running" datastore. The XPath root 2437 node has all top-level data nodes in all modules as children. 2439 o If the context node represents notification content, the tree is 2440 the notification XML instance document. The XPath root node has 2441 the element representing the notification being defined as the 2442 only child. 2444 o If the context node represents RPC input parameters, the tree is 2445 the RPC XML instance document. The XPath root node has the 2446 element representing the RPC operation being defined as the only 2447 child. 2449 o If the context node represents RPC output parameters, the tree is 2450 the RPC reply instance document. The XPath root node has the 2451 elements representing the RPC output parameters as children. 2453 The result of the XPath expression is converted to a boolean value 2454 using the standard XPath rules. 2456 Note that since all leaf values in the data tree are conceptually 2457 stored in their canonical form (see Section 7.6 and Section 7.7), any 2458 XPath comparisons are done on the canonical value. 2460 Also note that the XPath expression is conceptually evaluated. This 2461 means that an implementation does not have to use an XPath evaluator 2462 on the device. How the evaluation is done in practice is an 2463 implementation decision. 2465 7.5.4. The must's Substatements 2467 +---------------+---------+-------------+ 2468 | substatement | section | cardinality | 2469 +---------------+---------+-------------+ 2470 | description | 7.19.3 | 0..1 | 2471 | error-app-tag | 7.5.4.2 | 0..1 | 2472 | error-message | 7.5.4.1 | 0..1 | 2473 | reference | 7.19.4 | 0..1 | 2474 +---------------+---------+-------------+ 2476 7.5.4.1. The error-message Statement 2478 The "error-message" statement, which is optional, takes a string as 2479 an argument. If the constraint evaluates to false, the string is 2480 passed as in the . 2482 7.5.4.2. The error-app-tag Statement 2484 The "error-app-tag" statement, which is optional, takes a string as 2485 an argument. If the constraint evaluates to false, the string is 2486 passed as in the . 2488 7.5.4.3. Usage Example of must and error-message 2490 container interface { 2491 leaf ifType { 2492 type enumeration { 2493 enum ethernet; 2494 enum atm; 2495 } 2496 } 2497 leaf ifMTU { 2498 type uint32; 2499 } 2500 must "ifType != 'ethernet' or " + 2501 "(ifType = 'ethernet' and ifMTU = 1500)" { 2502 error-message "An ethernet MTU must be 1500"; 2503 } 2504 must "ifType != 'atm' or " + 2505 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2506 error-message "An atm MTU must be 64 .. 17966"; 2507 } 2508 } 2510 7.5.5. The presence Statement 2512 The "presence" statement assigns a meaning to the presence of a 2513 container in the data tree. It takes as an argument a string that 2514 contains a textual description of what the node's presence means. 2516 If a container has the "presence" statement, the container's 2517 existence in the data tree carries some meaning. Otherwise, the 2518 container is used to give some structure to the data, and it carries 2519 no meaning by itself. 2521 See Section 7.5.1 for additional information. 2523 7.5.6. The container's Child Node Statements 2525 Within a container, the "container", "leaf", "list", "leaf-list", 2526 "uses", "choice", and "anyxml" statements can be used to define child 2527 nodes to the container. 2529 7.5.7. XML Mapping Rules 2531 A container node is encoded as an XML element. The element's local 2532 name is the container's identifier, and its namespace is the module's 2533 XML namespace (see Section 7.1.3). 2535 The container's child nodes are encoded as subelements to the 2536 container element. If the container defines RPC input or output 2537 parameters, these subelements are encoded in the same order as they 2538 are defined within the "container" statement. Otherwise, the 2539 subelements are encoded in any order. 2541 A NETCONF server that replies to a or request MAY 2542 choose not to send a container element if the container node does not 2543 have the "presence" statement and no child nodes exist. Thus, a 2544 client that receives an for a or 2545 request, must be prepared to handle the case that a container node 2546 without a "presence" statement is not present in the XML. 2548 7.5.8. NETCONF Operations 2550 Containers can be created, deleted, replaced, and modified through 2551 , by using the "operation" attribute (see [RFC6241], 2552 Section 7.2) in the container's XML element. 2554 If a container does not have a "presence" statement and the last 2555 child node is deleted, the NETCONF server MAY delete the container. 2557 When a NETCONF server processes an request, the 2558 elements of procedure for the container node are: 2560 If the operation is "merge" or "replace", the node is created if 2561 it does not exist. 2563 If the operation is "create", the node is created if it does not 2564 exist. If the node already exists, a "data-exists" error is 2565 returned. 2567 If the operation is "delete", the node is deleted if it exists. 2568 If the node does not exist, a "data-missing" error is returned. 2570 7.5.9. Usage Example 2572 Given the following container definition: 2574 container system { 2575 description "Contains various system parameters"; 2576 container services { 2577 description "Configure externally available services"; 2578 container "ssh" { 2579 presence "Enables SSH"; 2580 description "SSH service specific configuration"; 2581 // more leafs, containers and stuff here... 2582 } 2583 } 2584 } 2586 A corresponding XML instance example: 2588 2589 2590 2591 2592 2594 Since the element is present, ssh is enabled. 2596 To delete a container with an : 2598 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2615 7.6. The leaf Statement 2617 The "leaf" statement is used to define a leaf node in the schema 2618 tree. It takes one argument, which is an identifier, followed by a 2619 block of substatements that holds detailed leaf information. 2621 A leaf node has a value, but no child nodes in the data tree. 2622 Conceptually, the value in the data tree is always in the canonical 2623 form (see Section 9.1). 2625 A leaf node exists in zero or one instances in the data tree. 2627 The "leaf" statement is used to define a scalar variable of a 2628 particular built-in or derived type. 2630 7.6.1. The leaf's default value 2632 The default value of a leaf is the value that the server uses if the 2633 leaf does not exist in the data tree. The usage of the default value 2634 depends on the leaf's closest ancestor node in the schema tree that 2635 is not a non-presence container: 2637 o If no such ancestor exists in the schema tree, the default value 2638 MUST be used. 2640 o Otherwise, if this ancestor is a case node, the default value MUST 2641 be used if any node from the case exists in the data tree, or if 2642 the case node is the choice's default case, and no nodes from any 2643 other case exist in the data tree. 2645 o Otherwise, the default value MUST be used if the ancestor node 2646 exists in the data tree. 2648 In these cases, the default value is said to be in use. 2650 When the default value is in use, the server MUST operationally 2651 behave as if the leaf was present in the data tree with the default 2652 value as its value. 2654 If a leaf has a "default" statement, the leaf's default value is the 2655 value of the "default" statement. Otherwise, if the leaf's type has 2656 a default value, and the leaf is not mandatory, then the leaf's 2657 default value is the type's default value. In all other cases, the 2658 leaf does not have a default value. 2660 7.6.2. The leaf's Substatements 2662 +--------------+---------+-------------+ 2663 | substatement | section | cardinality | 2664 +--------------+---------+-------------+ 2665 | config | 7.19.1 | 0..1 | 2666 | default | 7.6.4 | 0..1 | 2667 | description | 7.19.3 | 0..1 | 2668 | if-feature | 7.18.2 | 0..n | 2669 | mandatory | 7.6.5 | 0..1 | 2670 | must | 7.5.3 | 0..n | 2671 | reference | 7.19.4 | 0..1 | 2672 | status | 7.19.2 | 0..1 | 2673 | type | 7.6.3 | 1 | 2674 | units | 7.3.3 | 0..1 | 2675 | when | 7.19.5 | 0..1 | 2676 +--------------+---------+-------------+ 2678 7.6.3. The leaf's type Statement 2680 The "type" statement, which MUST be present, takes as an argument the 2681 name of an existing built-in or derived type. The optional 2682 substatements specify restrictions on this type. See Section 7.4 for 2683 details. 2685 7.6.4. The leaf's default Statement 2687 The "default" statement, which is optional, takes as an argument a 2688 string that contains a default value for the leaf. 2690 The value of the "default" statement MUST be valid according to the 2691 type specified in the leaf's "type" statement. 2693 The "default" statement MUST NOT be present on nodes where 2694 "mandatory" is true. 2696 7.6.5. The leaf's mandatory Statement 2698 The "mandatory" statement, which is optional, takes as an argument 2699 the string "true" or "false", and puts a constraint on valid data. 2700 If not specified, the default is "false". 2702 If "mandatory" is "true", the behavior of the constraint depends on 2703 the type of the leaf's closest ancestor node in the schema tree that 2704 is not a non-presence container (see Section 7.5.1): 2706 o If no such ancestor exists in the schema tree, the leaf MUST 2707 exist. 2709 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2710 any node from the case exists in the data tree. 2712 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2713 data tree. 2715 This constraint is enforced according to the rules in Section 8. 2717 7.6.6. XML Mapping Rules 2719 A leaf node is encoded as an XML element. The element's local name 2720 is the leaf's identifier, and its namespace is the module's XML 2721 namespace (see Section 7.1.3). 2723 The value of the leaf node is encoded to XML according to the type, 2724 and sent as character data in the element. 2726 A NETCONF server that replies to a or request MAY 2727 choose not to send the leaf element if its value is the default 2728 value. Thus, a client that receives an for a or 2729 request, MUST be prepared to handle the case that a leaf 2730 node with a default value is not present in the XML. In this case, 2731 the value used by the server is known to be the default value. 2733 See Section 7.6.8 for an example. 2735 7.6.7. NETCONF Operations 2737 When a NETCONF server processes an request, the 2738 elements of procedure for the leaf node are: 2740 If the operation is "merge" or "replace", the node is created if 2741 it does not exist, and its value is set to the value found in the 2742 XML RPC data. 2744 If the operation is "create", the node is created if it does not 2745 exist. If the node already exists, a "data-exists" error is 2746 returned. 2748 If the operation is "delete", the node is deleted if it exists. 2749 If the node does not exist, a "data-missing" error is returned. 2751 7.6.8. Usage Example 2753 Given the following "leaf" statement, placed in the previously 2754 defined "ssh" container (see Section 7.5.9): 2756 leaf port { 2757 type inet:port-number; 2758 default 22; 2759 description "The port to which the SSH server listens" 2760 } 2762 A corresponding XML instance example: 2764 2022 2766 To set the value of a leaf with an : 2768 2771 2772 2773 2774 2775 2776 2777 2778 2779 2022 2780 2781 2782 2783 2784 2785 2787 7.7. The leaf-list Statement 2789 Where the "leaf" statement is used to define a simple scalar variable 2790 of a particular type, the "leaf-list" statement is used to define an 2791 array of a particular type. The "leaf-list" statement takes one 2792 argument, which is an identifier, followed by a block of 2793 substatements that holds detailed leaf-list information. 2795 The values in a leaf-list MUST be unique. 2797 Conceptually, the values in the data tree are always in the canonical 2798 form (see Section 9.1). 2800 If the type referenced by the leaf-list has a default value, it has 2801 no effect in the leaf-list. 2803 7.7.1. Ordering 2805 YANG supports two styles for ordering the entries within lists and 2806 leaf-lists. In many lists, the order of list entries does not impact 2807 the implementation of the list's configuration, and the device is 2808 free to sort the list entries in any reasonable order. The 2809 "description" string for the list may suggest an order to the device 2810 implementor. YANG calls this style of list "system ordered" and they 2811 are indicated with the statement "ordered-by system". 2813 For example, a list of valid users would typically be sorted 2814 alphabetically, since the order in which the users appeared in the 2815 configuration would not impact the creation of those users' accounts. 2817 In the other style of lists, the order of list entries matters for 2818 the implementation of the list's configuration and the user is 2819 responsible for ordering the entries, while the device maintains that 2820 order. YANG calls this style of list "user ordered" and they are 2821 indicated with the statement "ordered-by user". 2823 For example, the order in which firewall filters entries are applied 2824 to incoming traffic may affect how that traffic is filtered. The 2825 user would need to decide if the filter entry that discards all TCP 2826 traffic should be applied before or after the filter entry that 2827 allows all traffic from trusted interfaces. The choice of order 2828 would be crucial. 2830 YANG provides a rich set of facilities within NETCONF's 2831 operation that allows the order of list entries in user-ordered lists 2832 to be controlled. List entries may be inserted or rearranged, 2833 positioned as the first or last entry in the list, or positioned 2834 before or after another specific entry. 2836 The "ordered-by" statement is covered in Section 7.7.5. 2838 7.7.2. The leaf-list's Substatements 2839 +--------------+---------+-------------+ 2840 | substatement | section | cardinality | 2841 +--------------+---------+-------------+ 2842 | config | 7.19.1 | 0..1 | 2843 | description | 7.19.3 | 0..1 | 2844 | if-feature | 7.18.2 | 0..n | 2845 | max-elements | 7.7.4 | 0..1 | 2846 | min-elements | 7.7.3 | 0..1 | 2847 | must | 7.5.3 | 0..n | 2848 | ordered-by | 7.7.5 | 0..1 | 2849 | reference | 7.19.4 | 0..1 | 2850 | status | 7.19.2 | 0..1 | 2851 | type | 7.4 | 1 | 2852 | units | 7.3.3 | 0..1 | 2853 | when | 7.19.5 | 0..1 | 2854 +--------------+---------+-------------+ 2856 7.7.3. The min-elements Statement 2858 The "min-elements" statement, which is optional, takes as an argument 2859 a non-negative integer that puts a constraint on valid list entries. 2860 A valid leaf-list or list MUST have at least min-elements entries. 2862 If no "min-elements" statement is present, it defaults to zero. 2864 The behavior of the constraint depends on the type of the leaf-list's 2865 or list's closest ancestor node in the schema tree that is not a non- 2866 presence container (see Section 7.5.1): 2868 o If this ancestor is a case node, the constraint is enforced if any 2869 other node from the case exists. 2871 o Otherwise, it is enforced if the ancestor node exists. 2873 The constraint is further enforced according to the rules in 2874 Section 8. 2876 7.7.4. The max-elements Statement 2878 The "max-elements" statement, which is optional, takes as an argument 2879 a positive integer or the string "unbounded", which puts a constraint 2880 on valid list entries. A valid leaf-list or list always has at most 2881 max-elements entries. 2883 If no "max-elements" statement is present, it defaults to 2884 "unbounded". 2886 The "max-elements" constraint is enforced according to the rules in 2887 Section 8. 2889 7.7.5. The ordered-by Statement 2891 The "ordered-by" statement defines whether the order of entries 2892 within a list are determined by the user or the system. The argument 2893 is one of the strings "system" or "user". If not present, order 2894 defaults to "system". 2896 This statement is ignored if the list represents state data, RPC 2897 output parameters, or notification content. 2899 See Section 7.7.1 for additional information. 2901 7.7.5.1. ordered-by system 2903 The entries in the list are sorted according to an unspecified order. 2904 Thus, an implementation is free to sort the entries in the most 2905 appropriate order. An implementation SHOULD use the same order for 2906 the same data, regardless of how the data were created. Using a 2907 deterministic order will make comparisons possible using simple tools 2908 like "diff". 2910 This is the default order. 2912 7.7.5.2. ordered-by user 2914 The entries in the list are sorted according to an order defined by 2915 the user. This order is controlled by using special XML attributes 2916 in the request. See Section 7.7.7 for details. 2918 7.7.6. XML Mapping Rules 2920 A leaf-list node is encoded as a series of XML elements. Each 2921 element's local name is the leaf-list's identifier, and its namespace 2922 is the module's XML namespace (see Section 7.1.3). 2924 The value of each leaf-list entry is encoded to XML according to the 2925 type, and sent as character data in the element. 2927 The XML elements representing leaf-list entries MUST appear in the 2928 order specified by the user if the leaf-list is "ordered-by user"; 2929 otherwise, the order is implementation-dependent. The XML elements 2930 representing leaf-list entries MAY be interleaved with other sibling 2931 elements, unless the leaf-list defines RPC input or output 2932 parameters. 2934 See Section 7.7.8 for an example. 2936 7.7.7. NETCONF Operations 2938 Leaf-list entries can be created and deleted, but not modified, 2939 through , by using the "operation" attribute in the 2940 leaf-list entry's XML element. 2942 In an "ordered-by user" leaf-list, the attributes "insert" and 2943 "value" in the YANG XML namespace (Section 5.3.1) can be used to 2944 control where in the leaf-list the entry is inserted. These can be 2945 used during "create" operations to insert a new leaf-list entry, or 2946 during "merge" or "replace" operations to insert a new leaf-list 2947 entry or move an existing one. 2949 The "insert" attribute can take the values "first", "last", "before", 2950 and "after". If the value is "before" or "after", the "value" 2951 attribute MUST also be used to specify an existing entry in the leaf- 2952 list. 2954 If no "insert" attribute is present in the "create" operation, it 2955 defaults to "last". 2957 If several entries in an "ordered-by user" leaf-list are modified in 2958 the same request, the entries are modified one at the 2959 time, in the order of the XML elements in the request. 2961 In a , or an with a "replace" operation 2962 that covers the entire leaf-list, the leaf-list order is the same as 2963 the order of the XML elements in the request. 2965 When a NETCONF server processes an request, the 2966 elements of procedure for a leaf-list node are: 2968 If the operation is "merge" or "replace", the leaf-list entry is 2969 created if it does not exist. 2971 If the operation is "create", the leaf-list entry is created if it 2972 does not exist. If the leaf-list entry already exists, a 2973 "data-exists" error is returned. 2975 If the operation is "delete", the entry is deleted from the leaf- 2976 list if it exists. If the leaf-list entry does not exist, a 2977 "data-missing" error is returned. 2979 7.7.8. Usage Example 2981 leaf-list allow-user { 2982 type string; 2983 description "A list of user name patterns to allow"; 2984 } 2986 A corresponding XML instance example: 2988 alice 2989 bob 2991 To create a new element in this list, using the default 2992 operation "merge": 2994 2997 2998 2999 3000 3001 3002 3003 3004 3005 eric 3006 3007 3008 3009 3010 3011 3013 Given the following ordered-by user leaf-list: 3015 leaf-list cipher { 3016 type string; 3017 ordered-by user; 3018 description "A list of ciphers"; 3019 } 3021 The following would be used to insert a new cipher "blowfish-cbc" 3022 after "3des-cbc": 3024 3028 3029 3030 3031 3032 3033 3034 3035 3036 blowfish-cbc 3039 3040 3041 3042 3043 3044 3046 7.8. The list Statement 3048 The "list" statement is used to define an interior data node in the 3049 schema tree. A list node may exist in multiple instances in the data 3050 tree. Each such instance is known as a list entry. The "list" 3051 statement takes one argument, which is an identifier, followed by a 3052 block of substatements that holds detailed list information. 3054 A list entry is uniquely identified by the values of the list's keys, 3055 if defined. 3057 7.8.1. The list's Substatements 3058 +--------------+---------+-------------+ 3059 | substatement | section | cardinality | 3060 +--------------+---------+-------------+ 3061 | anyxml | 7.10 | 0..n | 3062 | choice | 7.9 | 0..n | 3063 | config | 7.19.1 | 0..1 | 3064 | container | 7.5 | 0..n | 3065 | description | 7.19.3 | 0..1 | 3066 | grouping | 7.11 | 0..n | 3067 | if-feature | 7.18.2 | 0..n | 3068 | key | 7.8.2 | 0..1 | 3069 | leaf | 7.6 | 0..n | 3070 | leaf-list | 7.7 | 0..n | 3071 | list | 7.8 | 0..n | 3072 | max-elements | 7.7.4 | 0..1 | 3073 | min-elements | 7.7.3 | 0..1 | 3074 | must | 7.5.3 | 0..n | 3075 | ordered-by | 7.7.5 | 0..1 | 3076 | reference | 7.19.4 | 0..1 | 3077 | status | 7.19.2 | 0..1 | 3078 | typedef | 7.3 | 0..n | 3079 | unique | 7.8.3 | 0..n | 3080 | uses | 7.12 | 0..n | 3081 | when | 7.19.5 | 0..1 | 3082 +--------------+---------+-------------+ 3084 7.8.2. The list's key Statement 3086 The "key" statement, which MUST be present if the list represents 3087 configuration, and MAY be present otherwise, takes as an argument a 3088 string that specifies a space-separated list of leaf identifiers of 3089 this list. A leaf identifier MUST NOT appear more than once in the 3090 key. Each such leaf identifier MUST refer to a child leaf of the 3091 list. The leafs can be defined directly in substatements to the 3092 list, or in groupings used in the list. 3094 The combined values of all the leafs specified in the key are used to 3095 uniquely identify a list entry. All key leafs MUST be given values 3096 when a list entry is created. Thus, any default values in the key 3097 leafs or their types are ignored. It also implies that any mandatory 3098 statement in the key leafs are ignored. 3100 A leaf that is part of the key can be of any built-in or derived 3101 type, except it MUST NOT be the built-in type "empty". 3103 All key leafs in a list MUST have the same value for their "config" 3104 as the list itself. 3106 The key string syntax is formally defined by the rule "key-arg" in 3107 Section 13. 3109 7.8.3. The list's unique Statement 3111 The "unique" statement is used to put constraints on valid list 3112 entries. It takes as an argument a string that contains a space- 3113 separated list of schema node identifiers, which MUST be given in the 3114 descendant form (see the rule "descendant-schema-nodeid" in 3115 Section 13). Each such schema node identifier MUST refer to a leaf. 3117 If one of the referenced leafs represents configuration data, then 3118 all of the referenced leafs MUST represent configuration data. 3120 The "unique" constraint specifies that the combined values of all the 3121 leaf instances specified in the argument string, including leafs with 3122 default values, MUST be unique within all list entry instances in 3123 which all referenced leafs exist. The constraint is enforced 3124 according to the rules in Section 8. 3126 The unique string syntax is formally defined by the rule "unique-arg" 3127 in Section 13. 3129 7.8.3.1. Usage Example 3131 With the following list: 3133 list server { 3134 key "name"; 3135 unique "ip port"; 3136 leaf name { 3137 type string; 3138 } 3139 leaf ip { 3140 type inet:ip-address; 3141 } 3142 leaf port { 3143 type inet:port-number; 3144 } 3145 } 3147 The following configuration is not valid: 3149 3150 smtp 3151 192.0.2.1 3152 25 3153 3155 3156 http 3157 192.0.2.1 3158 25 3159 3161 The following configuration is valid, since the "http" and "ftp" list 3162 entries do not have a value for all referenced leafs, and are thus 3163 not taken into account when the "unique" constraint is enforced: 3165 3166 smtp 3167 192.0.2.1 3168 25 3169 3171 3172 http 3173 192.0.2.1 3174 3176 3177 ftp 3178 192.0.2.1 3179 3181 7.8.4. The list's Child Node Statements 3183 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3184 "choice", and "anyxml" statements can be used to define child nodes 3185 to the list. 3187 7.8.5. XML Mapping Rules 3189 A list is encoded as a series of XML elements, one for each entry in 3190 the list. Each element's local name is the list's identifier, and 3191 its namespace is the module's XML namespace (see Section 7.1.3). 3193 The list's key nodes are encoded as subelements to the list's 3194 identifier element, in the same order as they are defined within the 3195 "key" statement. 3197 The rest of the list's child nodes are encoded as subelements to the 3198 list element, after the keys. If the list defines RPC input or 3199 output parameters, the subelements are encoded in the same order as 3200 they are defined within the "list" statement. Otherwise, the 3201 subelements are encoded in any order. 3203 The XML elements representing list entries MUST appear in the order 3204 specified by the user if the list is "ordered-by user", otherwise the 3205 order is implementation-dependent. The XML elements representing 3206 list entries MAY be interleaved with other sibling elements, unless 3207 the list defines RPC input or output parameters. 3209 7.8.6. NETCONF Operations 3211 List entries can be created, deleted, replaced, and modified through 3212 , by using the "operation" attribute in the list's XML 3213 element. In each case, the values of all keys are used to uniquely 3214 identify a list entry. If all keys are not specified for a list 3215 entry, a "missing-element" error is returned. 3217 In an "ordered-by user" list, the attributes "insert" and "key" in 3218 the YANG XML namespace (Section 5.3.1) can be used to control where 3219 in the list the entry is inserted. These can be used during "create" 3220 operations to insert a new list entry, or during "merge" or "replace" 3221 operations to insert a new list entry or move an existing one. 3223 The "insert" attribute can take the values "first", "last", "before", 3224 and "after". If the value is "before" or "after", the "key" 3225 attribute MUST also be used, to specify an existing element in the 3226 list. The value of the "key" attribute is the key predicates of the 3227 full instance identifier (see Section 9.13) for the list entry. 3229 If no "insert" attribute is present in the "create" operation, it 3230 defaults to "last". 3232 If several entries in an "ordered-by user" list are modified in the 3233 same request, the entries are modified one at the time, 3234 in the order of the XML elements in the request. 3236 In a , or an with a "replace" operation 3237 that covers the entire list, the list entry order is the same as the 3238 order of the XML elements in the request. 3240 When a NETCONF server processes an request, the 3241 elements of procedure for a list node are: 3243 If the operation is "merge" or "replace", the list entry is 3244 created if it does not exist. If the list entry already exists 3245 and the "insert" and "key" attributes are present, the list entry 3246 is moved according to the values of the "insert" and "key" 3247 attributes. If the list entry exists and the "insert" and "key" 3248 attributes are not present, the list entry is not moved. 3250 If the operation is "create", the list entry is created if it does 3251 not exist. If the list entry already exists, a "data-exists" 3252 error is returned. 3254 If the operation is "delete", the entry is deleted from the list 3255 if it exists. If the list entry does not exist, a "data-missing" 3256 error is returned. 3258 7.8.7. Usage Example 3260 Given the following list: 3262 list user { 3263 key "name"; 3264 config true; 3265 description "This is a list of users in the system."; 3267 leaf name { 3268 type string; 3269 } 3270 leaf type { 3271 type string; 3272 } 3273 leaf full-name { 3274 type string; 3275 } 3276 } 3278 A corresponding XML instance example: 3280 3281 fred 3282 admin 3283 Fred Flintstone 3284 3286 To create a new user "barney": 3288 3291 3292 3293 3294 3295 3296 3297 3298 barney 3299 admin 3300 Barney Rubble 3301 3302 3303 3304 3305 3307 To change the type of "fred" to "superuser": 3309 3312 3313 3314 3315 3316 3317 3318 3319 fred 3320 superuser 3321 3322 3323 3324 3325 3327 Given the following ordered-by user list: 3329 list user { 3330 description "This is a list of users in the system."; 3331 ordered-by user; 3332 config true; 3334 key "name"; 3336 leaf name { 3337 type string; 3338 } 3339 leaf type { 3340 type string; 3341 } 3342 leaf full-name { 3343 type string; 3344 } 3345 } 3347 The following would be used to insert a new user "barney" after the 3348 user "fred": 3350 3354 3355 3356 3357 3358 3359 3361 3364 barney 3365 admin 3366 Barney Rubble 3367 3368 3369 3370 3371 3373 The following would be used to move the user "barney" before the user 3374 "fred": 3376 3380 3381 3382 3383 3384 3385 3387 3390 barney 3391 3392 3393 3394 3395 3397 7.9. The choice Statement 3399 The "choice" statement defines a set of alternatives, only one of 3400 which may exist at any one time. The argument is an identifier, 3401 followed by a block of substatements that holds detailed choice 3402 information. The identifier is used to identify the choice node in 3403 the schema tree. A choice node does not exist in the data tree. 3405 A choice consists of a number of branches, defined with the "case" 3406 substatement. Each branch contains a number of child nodes. The 3407 nodes from at most one of the choice's branches exist at the same 3408 time. 3410 See Section 8.3.2 for additional information. 3412 7.9.1. The choice's Substatements 3413 +--------------+---------+-------------+ 3414 | substatement | section | cardinality | 3415 +--------------+---------+-------------+ 3416 | anyxml | 7.10 | 0..n | 3417 | case | 7.9.2 | 0..n | 3418 | choice | 7.9 | 0..n | 3419 | config | 7.19.1 | 0..1 | 3420 | container | 7.5 | 0..n | 3421 | default | 7.9.3 | 0..1 | 3422 | description | 7.19.3 | 0..1 | 3423 | if-feature | 7.18.2 | 0..n | 3424 | leaf | 7.6 | 0..n | 3425 | leaf-list | 7.7 | 0..n | 3426 | list | 7.8 | 0..n | 3427 | mandatory | 7.9.4 | 0..1 | 3428 | reference | 7.19.4 | 0..1 | 3429 | status | 7.19.2 | 0..1 | 3430 | when | 7.19.5 | 0..1 | 3431 +--------------+---------+-------------+ 3433 7.9.2. The choice's case Statement 3435 The "case" statement is used to define branches of the choice. It 3436 takes as an argument an identifier, followed by a block of 3437 substatements that holds detailed case information. 3439 The identifier is used to identify the case node in the schema tree. 3440 A case node does not exist in the data tree. 3442 Within a "case" statement, the "anyxml", "choice", "container", 3443 "leaf", "list", "leaf-list", and "uses" statements can be used to 3444 define child nodes to the case node. The identifiers of all these 3445 child nodes MUST be unique within all cases in a choice. For 3446 example, the following is illegal: 3448 choice interface-type { // This example is illegal YANG 3449 case a { 3450 leaf ethernet { ... } 3451 } 3452 case b { 3453 container ethernet { ...} 3454 } 3455 } 3457 As a shorthand, the "case" statement can be omitted if the branch 3458 contains a single "anyxml", "choice", "container", "leaf", "list", or 3459 "leaf-list" statement. In this case, the identifier of the case node 3460 is the same as the identifier in the branch statement. The following 3461 example: 3463 choice interface-type { 3464 container ethernet { ... } 3465 } 3467 is equivalent to: 3469 choice interface-type { 3470 case ethernet { 3471 container ethernet { ... } 3472 } 3473 } 3475 The case identifier MUST be unique within a choice. 3477 7.9.2.1. The case's Substatements 3479 +--------------+---------+-------------+ 3480 | substatement | section | cardinality | 3481 +--------------+---------+-------------+ 3482 | anyxml | 7.10 | 0..n | 3483 | choice | 7.9 | 0..n | 3484 | container | 7.5 | 0..n | 3485 | description | 7.19.3 | 0..1 | 3486 | if-feature | 7.18.2 | 0..n | 3487 | leaf | 7.6 | 0..n | 3488 | leaf-list | 7.7 | 0..n | 3489 | list | 7.8 | 0..n | 3490 | reference | 7.19.4 | 0..1 | 3491 | status | 7.19.2 | 0..1 | 3492 | uses | 7.12 | 0..n | 3493 | when | 7.19.5 | 0..1 | 3494 +--------------+---------+-------------+ 3496 7.9.3. The choice's default Statement 3498 The "default" statement indicates if a case should be considered as 3499 the default if no child nodes from any of the choice's cases exist. 3500 The argument is the identifier of the "case" statement. If the 3501 "default" statement is missing, there is no default case. 3503 The "default" statement MUST NOT be present on choices where 3504 "mandatory" is true. 3506 The default case is only important when considering the default 3507 values of nodes under the cases. The default values for nodes under 3508 the default case are used if none of the nodes under any of the cases 3509 are present. 3511 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3512 the default case. 3514 Default values for child nodes under a case are only used if one of 3515 the nodes under that case is present, or if that case is the default 3516 case. If none of the nodes under a case are present and the case is 3517 not the default case, the default values of the cases' child nodes 3518 are ignored. 3520 In this example, the choice defaults to "interval", and the default 3521 value will be used if none of "daily", "time-of-day", or "manual" are 3522 present. If "daily" is present, the default value for "time-of-day" 3523 will be used. 3525 container transfer { 3526 choice how { 3527 default interval; 3528 case interval { 3529 leaf interval { 3530 type uint16; 3531 default 30; 3532 units minutes; 3533 } 3534 } 3535 case daily { 3536 leaf daily { 3537 type empty; 3538 } 3539 leaf time-of-day { 3540 type string; 3541 units 24-hour-clock; 3542 default 1am; 3543 } 3544 } 3545 case manual { 3546 leaf manual { 3547 type empty; 3548 } 3549 } 3550 } 3551 } 3553 7.9.4. The choice's mandatory Statement 3555 The "mandatory" statement, which is optional, takes as an argument 3556 the string "true" or "false", and puts a constraint on valid data. 3557 If "mandatory" is "true", at least one node from exactly one of the 3558 choice's case branches MUST exist. 3560 If not specified, the default is "false". 3562 The behavior of the constraint depends on the type of the choice's 3563 closest ancestor node in the schema tree which is not a non-presence 3564 container (see Section 7.5.1): 3566 o If this ancestor is a case node, the constraint is enforced if any 3567 other node from the case exists. 3569 o Otherwise, it is enforced if the ancestor node exists. 3571 The constraint is further enforced according to the rules in 3572 Section 8. 3574 7.9.5. XML Mapping Rules 3576 The choice and case nodes are not visible in XML. 3578 The child nodes of the selected "case" statement MUST be encoded in 3579 the same order as they are defined in the "case" statement if they 3580 are part of an RPC input or output parameter definition. Otherwise, 3581 the subelements are encoded in any order. 3583 7.9.6. NETCONF Operations 3585 Since only one of the choice's cases can be valid at any time, the 3586 creation of a node from one case implicitly deletes all nodes from 3587 all other cases. If an operation creates a node from a 3588 case, the NETCONF server will delete any existing nodes that are 3589 defined in other cases inside the choice. 3591 7.9.7. Usage Example 3593 Given the following choice: 3595 container protocol { 3596 choice name { 3597 case a { 3598 leaf udp { 3599 type empty; 3600 } 3601 } 3602 case b { 3603 leaf tcp { 3604 type empty; 3605 } 3606 } 3607 } 3608 } 3610 A corresponding XML instance example: 3612 3613 3614 3616 To change the protocol from tcp to udp: 3618 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3635 7.10. The anyxml Statement 3637 The "anyxml" statement defines an interior node in the schema tree. 3638 It takes one argument, which is an identifier, followed by a block of 3639 substatements that holds detailed anyxml information. 3641 The "anyxml" statement is used to represent an unknown chunk of XML. 3642 No restrictions are placed on the XML. This can be useful, for 3643 example, in RPC replies. An example is the parameter in the 3644 operation. 3646 An anyxml node cannot be augmented (see Section 7.15). 3648 Since the use of anyxml limits the manipulation of the content, it is 3649 RECOMMENDED that the "anyxml" statement not be used to represent 3650 configuration data. 3652 An anyxml node exists in zero or one instances in the data tree. 3654 7.10.1. The anyxml's Substatements 3656 +--------------+---------+-------------+ 3657 | substatement | section | cardinality | 3658 +--------------+---------+-------------+ 3659 | config | 7.19.1 | 0..1 | 3660 | description | 7.19.3 | 0..1 | 3661 | if-feature | 7.18.2 | 0..n | 3662 | mandatory | 7.6.5 | 0..1 | 3663 | must | 7.5.3 | 0..n | 3664 | reference | 7.19.4 | 0..1 | 3665 | status | 7.19.2 | 0..1 | 3666 | when | 7.19.5 | 0..1 | 3667 +--------------+---------+-------------+ 3669 7.10.2. XML Mapping Rules 3671 An anyxml node is encoded as an XML element. The element's local 3672 name is the anyxml's identifier, and its namespace is the module's 3673 XML namespace (see Section 7.1.3). The value of the anyxml node is 3674 encoded as XML content of this element. 3676 Note that any prefixes used in the encoding are local to each 3677 instance encoding. This means that the same XML may be encoded 3678 differently by different implementations. 3680 7.10.3. NETCONF Operations 3682 An anyxml node is treated as an opaque chunk of data. This data can 3683 be modified in its entirety only. 3685 Any "operation" attributes present on subelements of an anyxml node 3686 are ignored by the NETCONF server. 3688 When a NETCONF server processes an request, the 3689 elements of procedure for the anyxml node are: 3691 If the operation is "merge" or "replace", the node is created if 3692 it does not exist, and its value is set to the XML content of the 3693 anyxml node found in the XML RPC data. 3695 If the operation is "create", the node is created if it does not 3696 exist, and its value is set to the XML content of the anyxml node 3697 found in the XML RPC data. If the node already exists, a 3698 "data-exists" error is returned. 3700 If the operation is "delete", the node is deleted if it exists. 3701 If the node does not exist, a "data-missing" error is returned. 3703 7.10.4. Usage Example 3705 Given the following "anyxml" statement: 3707 anyxml data; 3709 The following are two valid encodings of the same anyxml value: 3711 3712 3713 1 3714 3715 3717 3718 3719 1 3720 3721 3723 7.11. The grouping Statement 3725 The "grouping" statement is used to define a reusable block of nodes, 3726 which may be used locally in the module, in modules that include it, 3727 and by other modules that import from it, according to the rules in 3728 Section 5.5. It takes one argument, which is an identifier, followed 3729 by a block of substatements that holds detailed grouping information. 3731 The "grouping" statement is not a data definition statement and, as 3732 such, does not define any nodes in the schema tree. 3734 A grouping is like a "structure" or a "record" in conventional 3735 programming languages. 3737 Once a grouping is defined, it can be referenced in a "uses" 3738 statement (see Section 7.12). A grouping MUST NOT reference itself, 3739 neither directly nor indirectly through a chain of other groupings. 3741 If the grouping is defined at the top level of a YANG module or 3742 submodule, the grouping's identifier MUST be unique within the 3743 module. 3745 A grouping is more than just a mechanism for textual substitution, 3746 but defines a collection of nodes. Identifiers appearing inside the 3747 grouping are resolved relative to the scope in which the grouping is 3748 defined, not where it is used. Prefix mappings, type names, grouping 3749 names, and extension usage are evaluated in the hierarchy where the 3750 "grouping" statement appears. For extensions, this means that 3751 extensions are applied to the grouping node, not the uses node. 3753 7.11.1. The grouping's Substatements 3755 +--------------+---------+-------------+ 3756 | substatement | section | cardinality | 3757 +--------------+---------+-------------+ 3758 | anyxml | 7.10 | 0..n | 3759 | choice | 7.9 | 0..n | 3760 | container | 7.5 | 0..n | 3761 | description | 7.19.3 | 0..1 | 3762 | grouping | 7.11 | 0..n | 3763 | leaf | 7.6 | 0..n | 3764 | leaf-list | 7.7 | 0..n | 3765 | list | 7.8 | 0..n | 3766 | reference | 7.19.4 | 0..1 | 3767 | status | 7.19.2 | 0..1 | 3768 | typedef | 7.3 | 0..n | 3769 | uses | 7.12 | 0..n | 3770 +--------------+---------+-------------+ 3772 7.11.2. Usage Example 3773 import ietf-inet-types { 3774 prefix "inet"; 3775 } 3777 grouping endpoint { 3778 description "A reusable endpoint group."; 3779 leaf ip { 3780 type inet:ip-address; 3781 } 3782 leaf port { 3783 type inet:port-number; 3784 } 3785 } 3787 7.12. The uses Statement 3789 The "uses" statement is used to reference a "grouping" definition. 3790 It takes one argument, which is the name of the grouping. 3792 The effect of a "uses" reference to a grouping is that the nodes 3793 defined by the grouping are copied into the current schema tree, and 3794 then updated according to the "refine" and "augment" statements. 3796 The identifiers defined in the grouping are not bound to a namespace 3797 until the contents of the grouping are added to the schema tree via a 3798 "uses" statement that does not appear inside a "grouping" statement, 3799 at which point they are bound to the namespace of the current module. 3801 7.12.1. The uses's Substatements 3803 +--------------+---------+-------------+ 3804 | substatement | section | cardinality | 3805 +--------------+---------+-------------+ 3806 | augment | 7.15 | 0..n | 3807 | description | 7.19.3 | 0..1 | 3808 | if-feature | 7.18.2 | 0..n | 3809 | refine | 7.12.2 | 0..n | 3810 | reference | 7.19.4 | 0..1 | 3811 | status | 7.19.2 | 0..1 | 3812 | when | 7.19.5 | 0..1 | 3813 +--------------+---------+-------------+ 3815 7.12.2. The refine Statement 3817 Some of the properties of each node in the grouping can be refined 3818 with the "refine" statement. The argument is a string that 3819 identifies a node in the grouping. This node is called the refine's 3820 target node. If a node in the grouping is not present as a target 3821 node of a "refine" statement, it is not refined, and thus used 3822 exactly as it was defined in the grouping. 3824 The argument string is a descendant schema node identifier (see 3825 Section 6.5). 3827 The following refinements can be done: 3829 o A leaf or choice node may get a default value, or a new default 3830 value if it already had one. 3832 o Any node may get a specialized "description" string. 3834 o Any node may get a specialized "reference" string. 3836 o Any node may get a different "config" statement. 3838 o A leaf, anyxml, or choice node may get a different "mandatory" 3839 statement. 3841 o A container node may get a "presence" statement. 3843 o A leaf, leaf-list, list, container, or anyxml node may get 3844 additional "must" expressions. 3846 o A leaf-list or list node may get a different "min-elements" or 3847 "max-elements" statement. 3849 o A leaf, leaf-list, list, container, or anyxml node may get 3850 additional "if-feature" expressions. 3852 7.12.3. XML Mapping Rules 3854 Each node in the grouping is encoded as if it was defined inline, 3855 even if it is imported from another module with another XML 3856 namespace. 3858 7.12.4. Usage Example 3860 To use the "endpoint" grouping defined in Section 7.11.2 in a 3861 definition of an HTTP server in some other module, we can do: 3863 import acme-system { 3864 prefix "acme"; 3865 } 3867 container http-server { 3868 leaf name { 3869 type string; 3870 } 3871 uses acme:endpoint; 3872 } 3874 A corresponding XML instance example: 3876 3877 extern-web 3878 192.0.2.1 3879 80 3880 3882 If port 80 should be the default for the HTTP server, default can be 3883 added: 3885 container http-server { 3886 leaf name { 3887 type string; 3888 } 3889 uses acme:endpoint { 3890 refine port { 3891 default 80; 3892 } 3893 } 3894 } 3896 If we want to define a list of servers, and each server has the ip 3897 and port as keys, we can do: 3899 list server { 3900 key "ip port"; 3901 leaf name { 3902 type string; 3903 } 3904 uses acme:endpoint; 3905 } 3907 The following is an error: 3909 container http-server { 3910 uses acme:endpoint; 3911 leaf ip { // illegal - same identifier "ip" used twice 3912 type string; 3913 } 3914 } 3916 7.13. The rpc Statement 3918 The "rpc" statement is used to define a NETCONF RPC operation. It 3919 takes one argument, which is an identifier, followed by a block of 3920 substatements that holds detailed rpc information. This argument is 3921 the name of the RPC, and is used as the element name directly under 3922 the element, as designated by the substitution group 3923 "rpcOperation" in [RFC6241]. 3925 The "rpc" statement defines an rpc node in the schema tree. Under 3926 the rpc node, a schema node with the name "input", and a schema node 3927 with the name "output" are also defined. The nodes "input" and 3928 "output" are defined in the module's namespace. 3930 7.13.1. The rpc's Substatements 3932 +--------------+---------+-------------+ 3933 | substatement | section | cardinality | 3934 +--------------+---------+-------------+ 3935 | description | 7.19.3 | 0..1 | 3936 | grouping | 7.11 | 0..n | 3937 | if-feature | 7.18.2 | 0..n | 3938 | input | 7.13.2 | 0..1 | 3939 | output | 7.13.3 | 0..1 | 3940 | reference | 7.19.4 | 0..1 | 3941 | status | 7.19.2 | 0..1 | 3942 | typedef | 7.3 | 0..n | 3943 +--------------+---------+-------------+ 3945 7.13.2. The input Statement 3947 The "input" statement, which is optional, is used to define input 3948 parameters to the RPC operation. It does not take an argument. The 3949 substatements to "input" define nodes under the RPC's input node. 3951 If a leaf in the input tree has a "mandatory" statement with the 3952 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3953 Otherwise, the server MUST return a "missing-element" error. 3955 If a leaf in the input tree has a default value, the NETCONF server 3956 MUST use this value in the same cases as described in Section 7.6.1. 3958 In these cases, the server MUST operationally behave as if the leaf 3959 was present in the NETCONF RPC invocation with the default value as 3960 its value. 3962 If a "config" statement is present for any node in the input tree, 3963 the "config" statement is ignored. 3965 If any node has a "when" statement that would evaluate to false, then 3966 this node MUST NOT be present in the input tree. 3968 7.13.2.1. The input's Substatements 3970 +--------------+---------+-------------+ 3971 | substatement | section | cardinality | 3972 +--------------+---------+-------------+ 3973 | anyxml | 7.10 | 0..n | 3974 | choice | 7.9 | 0..n | 3975 | container | 7.5 | 0..n | 3976 | grouping | 7.11 | 0..n | 3977 | leaf | 7.6 | 0..n | 3978 | leaf-list | 7.7 | 0..n | 3979 | list | 7.8 | 0..n | 3980 | typedef | 7.3 | 0..n | 3981 | uses | 7.12 | 0..n | 3982 +--------------+---------+-------------+ 3984 7.13.3. The output Statement 3986 The "output" statement, which is optional, is used to define output 3987 parameters to the RPC operation. It does not take an argument. The 3988 substatements to "output" define nodes under the RPC's output node. 3990 If a leaf in the output tree has a "mandatory" statement with the 3991 value "true", the leaf MUST be present in a NETCONF RPC reply. 3993 If a leaf in the output tree has a default value, the NETCONF client 3994 MUST use this value in the same cases as described in Section 7.6.1. 3995 In these cases, the client MUST operationally behave as if the leaf 3996 was present in the NETCONF RPC reply with the default value as its 3997 value. 3999 If a "config" statement is present for any node in the output tree, 4000 the "config" statement is ignored. 4002 If any node has a "when" statement that would evaluate to false, then 4003 this node MUST NOT be present in the output tree. 4005 7.13.3.1. The output's Substatements 4007 +--------------+---------+-------------+ 4008 | substatement | section | cardinality | 4009 +--------------+---------+-------------+ 4010 | anyxml | 7.10 | 0..n | 4011 | choice | 7.9 | 0..n | 4012 | container | 7.5 | 0..n | 4013 | grouping | 7.11 | 0..n | 4014 | leaf | 7.6 | 0..n | 4015 | leaf-list | 7.7 | 0..n | 4016 | list | 7.8 | 0..n | 4017 | typedef | 7.3 | 0..n | 4018 | uses | 7.12 | 0..n | 4019 +--------------+---------+-------------+ 4021 7.13.4. XML Mapping Rules 4023 An rpc node is encoded as a child XML element to the element 4024 defined in [RFC6241]. The element's local name is the rpc's 4025 identifier, and its namespace is the module's XML namespace (see 4026 Section 7.1.3). 4028 Input parameters are encoded as child XML elements to the rpc node's 4029 XML element, in the same order as they are defined within the "input" 4030 statement. 4032 If the RPC operation invocation succeeded, and no output parameters 4033 are returned, the contains a single element defined 4034 in [RFC6241]. If output parameters are returned, they are encoded as 4035 child elements to the element defined in [RFC6241], in 4036 the same order as they are defined within the "output" statement. 4038 7.13.5. Usage Example 4040 The following example defines an RPC operation: 4042 module rock { 4043 yang-version 1.1; 4044 namespace "http://example.net/rock"; 4045 prefix "rock"; 4047 rpc rock-the-house { 4048 input { 4049 leaf zip-code { 4050 type string; 4051 } 4052 } 4053 } 4054 } 4056 A corresponding XML instance example of the complete rpc and rpc- 4057 reply: 4059 4061 4062 27606-0100 4063 4064 4066 4068 4069 4071 7.14. The notification Statement 4073 The "notification" statement is used to define a NETCONF 4074 notification. It takes one argument, which is an identifier, 4075 followed by a block of substatements that holds detailed notification 4076 information. The "notification" statement defines a notification 4077 node in the schema tree. 4079 If a leaf in the notification tree has a "mandatory" statement with 4080 the value "true", the leaf MUST be present in a NETCONF notification. 4082 If a leaf in the notification tree has a default value, the NETCONF 4083 client MUST use this value in the same cases as described in 4084 Section 7.6.1. In these cases, the client MUST operationally behave 4085 as if the leaf was present in the NETCONF notification with the 4086 default value as its value. 4088 If a "config" statement is present for any node in the notification 4089 tree, the "config" statement is ignored. 4091 7.14.1. The notification's Substatements 4093 +--------------+---------+-------------+ 4094 | substatement | section | cardinality | 4095 +--------------+---------+-------------+ 4096 | anyxml | 7.10 | 0..n | 4097 | choice | 7.9 | 0..n | 4098 | container | 7.5 | 0..n | 4099 | description | 7.19.3 | 0..1 | 4100 | grouping | 7.11 | 0..n | 4101 | if-feature | 7.18.2 | 0..n | 4102 | leaf | 7.6 | 0..n | 4103 | leaf-list | 7.7 | 0..n | 4104 | list | 7.8 | 0..n | 4105 | reference | 7.19.4 | 0..1 | 4106 | status | 7.19.2 | 0..1 | 4107 | typedef | 7.3 | 0..n | 4108 | uses | 7.12 | 0..n | 4109 +--------------+---------+-------------+ 4111 7.14.2. XML Mapping Rules 4113 A notification node is encoded as a child XML element to the 4114 element defined in NETCONF Event Notifications 4115 [RFC5277]. The element's local name is the notification's 4116 identifier, and its namespace is the module's XML namespace (see 4117 Section 7.1.3). 4119 7.14.3. Usage Example 4121 The following example defines a notification: 4123 module event { 4124 yang-version 1.1; 4125 namespace "http://example.com/event"; 4126 prefix "ev"; 4128 notification event { 4129 leaf event-class { 4130 type string; 4131 } 4132 anyxml reporting-entity; 4133 leaf severity { 4134 type string; 4135 } 4136 } 4137 } 4139 A corresponding XML instance example of the complete notification: 4141 4143 2008-07-08T00:01:00Z 4144 4145 fault 4146 4147 Ethernet0 4148 4149 major 4150 4151 4153 7.15. The augment Statement 4155 The "augment" statement allows a module or submodule to add to the 4156 schema tree defined in an external module, or the current module and 4157 its submodules, and to add to the nodes from a grouping in a "uses" 4158 statement. The argument is a string that identifies a node in the 4159 schema tree. This node is called the augment's target node. The 4160 target node MUST be either a container, list, choice, case, input, 4161 output, or notification node. It is augmented with the nodes defined 4162 in the substatements that follow the "augment" statement. 4164 The argument string is a schema node identifier (see Section 6.5). 4165 If the "augment" statement is on the top level in a module or 4166 submodule, the absolute form (defined by the rule 4167 "absolute-schema-nodeid" in Section 13) of a schema node identifier 4168 MUST be used. If the "augment" statement is a substatement to the 4169 "uses" statement, the descendant form (defined by the rule 4170 "descendant-schema-nodeid" in Section 13) MUST be used. 4172 If the target node is a container, list, case, input, output, or 4173 notification node, the "container", "leaf", "list", "leaf-list", 4174 "uses", and "choice" statements can be used within the "augment" 4175 statement. 4177 If the target node is a choice node, the "case" statement, or a case 4178 shorthand statement (see Section 7.9.2) can be used within the 4179 "augment" statement. 4181 If the target node is in another module, then nodes added by the 4182 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4184 The "augment" statement MUST NOT add multiple nodes with the same 4185 name from the same module to the target node. 4187 7.15.1. The augment's Substatements 4189 +--------------+---------+-------------+ 4190 | substatement | section | cardinality | 4191 +--------------+---------+-------------+ 4192 | anyxml | 7.10 | 0..n | 4193 | case | 7.9.2 | 0..n | 4194 | choice | 7.9 | 0..n | 4195 | container | 7.5 | 0..n | 4196 | description | 7.19.3 | 0..1 | 4197 | if-feature | 7.18.2 | 0..n | 4198 | leaf | 7.6 | 0..n | 4199 | leaf-list | 7.7 | 0..n | 4200 | list | 7.8 | 0..n | 4201 | reference | 7.19.4 | 0..1 | 4202 | status | 7.19.2 | 0..1 | 4203 | uses | 7.12 | 0..n | 4204 | when | 7.19.5 | 0..1 | 4205 +--------------+---------+-------------+ 4207 7.15.2. XML Mapping Rules 4209 All data nodes defined in the "augment" statement are defined as XML 4210 elements in the XML namespace of the module where the "augment" is 4211 specified. 4213 When a node is augmented, the augmenting child nodes are encoded as 4214 subelements to the augmented node, in any order. 4216 7.15.3. Usage Example 4218 In namespace http://example.com/schema/interfaces, we have: 4220 container interfaces { 4221 list ifEntry { 4222 key "ifIndex"; 4224 leaf ifIndex { 4225 type uint32; 4226 } 4227 leaf ifDescr { 4228 type string; 4229 } 4230 leaf ifType { 4231 type iana:IfType; 4232 } 4233 leaf ifMtu { 4234 type int32; 4235 } 4236 } 4237 } 4239 Then, in namespace http://example.com/schema/ds0, we have: 4241 import interface-module { 4242 prefix "if"; 4243 } 4244 augment "/if:interfaces/if:ifEntry" { 4245 when "if:ifType='ds0'"; 4246 leaf ds0ChannelNumber { 4247 type ChannelNumber; 4248 } 4249 } 4251 A corresponding XML instance example: 4253 4255 4256 1 4257 Flintstone Inc Ethernet A562 4258 ethernetCsmacd 4259 1500 4260 4261 4262 2 4263 Flintstone Inc DS0 4264 ds0 4265 1 4266 4267 4269 As another example, suppose we have the choice defined in 4270 Section 7.9.7. The following construct can be used to extend the 4271 protocol definition: 4273 augment /ex:system/ex:protocol/ex:name { 4274 case c { 4275 leaf smtp { 4276 type empty; 4277 } 4278 } 4279 } 4281 A corresponding XML instance example: 4283 4284 4285 4286 4287 4289 or 4291 4292 4293 4294 4295 4297 7.16. The identity Statement 4299 The "identity" statement is used to define a new globally unique, 4300 abstract, and untyped identity. Its only purpose is to denote its 4301 name, semantics, and existence. An identity can either be defined 4302 from scratch or derived from a base identity. The identity's 4303 argument is an identifier that is the name of the identity. It is 4304 followed by a block of substatements that holds detailed identity 4305 information. 4307 The built-in datatype "identityref" (see Section 9.10) can be used to 4308 reference identities within a data model. 4310 7.16.1. The identity's Substatements 4311 +--------------+---------+-------------+ 4312 | substatement | section | cardinality | 4313 +--------------+---------+-------------+ 4314 | base | 7.16.2 | 0..1 | 4315 | description | 7.19.3 | 0..1 | 4316 | reference | 7.19.4 | 0..1 | 4317 | status | 7.19.2 | 0..1 | 4318 +--------------+---------+-------------+ 4320 7.16.2. The base Statement 4322 The "base" statement, which is optional, takes as an argument a 4323 string that is the name of an existing identity, from which the new 4324 identity is derived. If no "base" statement is present, the identity 4325 is defined from scratch. 4327 If a prefix is present on the base name, it refers to an identity 4328 defined in the module that was imported with that prefix, or the 4329 local module if the prefix matches the local module's prefix. 4330 Otherwise, an identity with the matching name MUST be defined in the 4331 current module or an included submodule. 4333 Since submodules cannot include the parent module, any identities in 4334 the module that need to be exposed to submodules MUST be defined in a 4335 submodule. Submodules can then include this submodule to find the 4336 definition of the identity. 4338 An identity MUST NOT reference itself, neither directly nor 4339 indirectly through a chain of other identities. 4341 The derivation of identities has the following properties: 4343 o It is irreflexive, which means that an identity is not derived 4344 from itself. 4346 o It is transitive, which means that if identity B is derived from A 4347 and C is derived from B, then C is also derived from A. 4349 7.16.3. Usage Example 4350 module crypto-base { 4351 yang-version 1.1; 4352 namespace "http://example.com/crypto-base"; 4353 prefix "crypto"; 4355 identity crypto-alg { 4356 description 4357 "Base identity from which all crypto algorithms 4358 are derived."; 4359 } 4360 } 4362 module des { 4363 yang-version 1.1; 4364 namespace "http://example.com/des"; 4365 prefix "des"; 4367 import "crypto-base" { 4368 prefix "crypto"; 4369 } 4371 identity des { 4372 base "crypto:crypto-alg"; 4373 description "DES crypto algorithm"; 4374 } 4376 identity des3 { 4377 base "crypto:crypto-alg"; 4378 description "Triple DES crypto algorithm"; 4379 } 4380 } 4382 7.17. The extension Statement 4384 The "extension" statement allows the definition of new statements 4385 within the YANG language. This new statement definition can be 4386 imported and used by other modules. 4388 The statement's argument is an identifier that is the new keyword for 4389 the extension and must be followed by a block of substatements that 4390 holds detailed extension information. The purpose of the "extension" 4391 statement is to define a keyword, so that it can be imported and used 4392 by other modules. 4394 The extension can be used like a normal YANG statement, with the 4395 statement name followed by an argument if one is defined by the 4396 "extension" statement, and an optional block of substatements. The 4397 statement's name is created by combining the prefix of the module in 4398 which the extension was defined, a colon (":"), and the extension's 4399 keyword, with no interleaving whitespace. The substatements of an 4400 extension are defined by the "extension" statement, using some 4401 mechanism outside the scope of this specification. Syntactically, 4402 the substatements MUST be YANG statements, or also extensions defined 4403 using "extension" statements. YANG statements in extensions MUST 4404 follow the syntactical rules in Section 13. 4406 7.17.1. The extension's Substatements 4408 +--------------+---------+-------------+ 4409 | substatement | section | cardinality | 4410 +--------------+---------+-------------+ 4411 | argument | 7.17.2 | 0..1 | 4412 | description | 7.19.3 | 0..1 | 4413 | reference | 7.19.4 | 0..1 | 4414 | status | 7.19.2 | 0..1 | 4415 +--------------+---------+-------------+ 4417 7.17.2. The argument Statement 4419 The "argument" statement, which is optional, takes as an argument a 4420 string that is the name of the argument to the keyword. If no 4421 argument statement is present, the keyword expects no argument when 4422 it is used. 4424 The argument's name is used in the YIN mapping, where it is used as 4425 an XML attribute or element name, depending on the argument's 4426 "yin-element" statement. 4428 7.17.2.1. The argument's Substatements 4430 +--------------+----------+-------------+ 4431 | substatement | section | cardinality | 4432 +--------------+----------+-------------+ 4433 | yin-element | 7.17.2.2 | 0..1 | 4434 +--------------+----------+-------------+ 4436 7.17.2.2. The yin-element Statement 4438 The "yin-element" statement, which is optional, takes as an argument 4439 the string "true" or "false". This statement indicates if the 4440 argument is mapped to an XML element in YIN or to an XML attribute 4441 (see Section 12). 4443 If no "yin-element" statement is present, it defaults to "false". 4445 7.17.3. Usage Example 4447 To define an extension: 4449 module my-extensions { 4450 ... 4452 extension c-define { 4453 description 4454 "Takes as argument a name string. 4455 Makes the code generator use the given name in the 4456 #define."; 4457 argument "name"; 4458 } 4459 } 4461 To use the extension: 4463 module my-interfaces { 4464 ... 4465 import my-extensions { 4466 prefix "myext"; 4467 } 4468 ... 4470 container interfaces { 4471 ... 4472 myext:c-define "MY_INTERFACES"; 4473 } 4474 } 4476 7.18. Conformance-Related Statements 4478 This section defines statements related to conformance, as described 4479 in Section 5.6. 4481 7.18.1. The feature Statement 4483 The "feature" statement is used to define a mechanism by which 4484 portions of the schema are marked as conditional. A feature name is 4485 defined that can later be referenced using the "if-feature" statement 4486 (see Section 7.18.2). Schema nodes tagged with an "if-feature" 4487 statement are ignored by the device unless the device supports the 4488 given feature expression. This allows portions of the YANG module to 4489 be conditional based on conditions on the device. The model can 4490 represent the abilities of the device within the model, giving a 4491 richer model that allows for differing device abilities and roles. 4493 The argument to the "feature" statement is the name of the new 4494 feature, and follows the rules for identifiers in Section 6.2. This 4495 name is used by the "if-feature" statement to tie the schema nodes to 4496 the feature. 4498 In this example, a feature called "local-storage" represents the 4499 ability for a device to store syslog messages on local storage of 4500 some sort. This feature is used to make the "local-storage-limit" 4501 leaf conditional on the presence of some sort of local storage. If 4502 the device does not report that it supports this feature, the 4503 "local-storage-limit" node is not supported. 4505 module syslog { 4506 ... 4507 feature local-storage { 4508 description 4509 "This feature means the device supports local 4510 storage (memory, flash or disk) that can be used to 4511 store syslog messages."; 4512 } 4514 container syslog { 4515 leaf local-storage-limit { 4516 if-feature local-storage; 4517 type uint64; 4518 units "kilobyte"; 4519 config false; 4520 description 4521 "The amount of local storage that can be 4522 used to hold syslog messages."; 4523 } 4524 } 4525 } 4527 The "if-feature" statement can be used in many places within the YANG 4528 syntax. Definitions tagged with "if-feature" are ignored when the 4529 device does not support that feature. 4531 A feature MUST NOT reference itself, neither directly nor indirectly 4532 through a chain of other features. 4534 In order for a device to implement a feature that is dependent on any 4535 other features (i.e., the feature has one or more "if-feature" 4536 substatements), the device MUST also implement all the dependant 4537 features. 4539 7.18.1.1. The feature's Substatements 4541 +--------------+---------+-------------+ 4542 | substatement | section | cardinality | 4543 +--------------+---------+-------------+ 4544 | description | 7.19.3 | 0..1 | 4545 | if-feature | 7.18.2 | 0..n | 4546 | status | 7.19.2 | 0..1 | 4547 | reference | 7.19.4 | 0..1 | 4548 +--------------+---------+-------------+ 4550 7.18.2. The if-feature Statement 4552 The "if-feature" statement makes its parent statement conditional. 4553 The argument is a boolean expression over feature names. In this 4554 expression, a feature name evaluates to "true" if and only if the 4555 feature is implemented by the server. The parent statement is 4556 implemented by servers where the boolean expression evaluates to 4557 "true". 4559 The if-feature boolean expression syntax is formally defined by the 4560 rule "if-feature-expr" in Section 13. When this boolean expression 4561 is evaluated, the operator order of precedence is (highest precedence 4562 first): "not", "and", "or". 4564 If a prefix is present on a feature name in the boolean expression, 4565 the prefixed name refers to a feature defined in the module that was 4566 imported with that prefix, or the local module if the prefix matches 4567 the local module's prefix. Otherwise, a feature with the matching 4568 name MUST be defined in the current module or an included submodule. 4570 Since submodules cannot include the parent module, any features in 4571 the module that need to be exposed to submodules MUST be defined in a 4572 submodule. Submodules can then include this submodule to find the 4573 definition of the feature. 4575 A leaf that is a list key MUST NOT have any "if-feature" statements, 4576 unless the conditions specified in the "if-feature" statements are 4577 the same as the "if-feature" conditions in effect on the leaf's 4578 parent node. 4580 7.18.2.1. Usage Example 4582 In this example, the container "target" is implemented if any of the 4583 features "outbound-tls" or "outbound-ssh" is implemented by the 4584 server. 4586 container target { 4587 if-feature "outbound-tls or outbound-ssh"; 4588 ... 4589 } 4591 7.18.3. The deviation Statement 4593 The "deviation" statement defines a hierarchy of a module that the 4594 device does not implement faithfully. The argument is a string that 4595 identifies the node in the schema tree where a deviation from the 4596 module occurs. This node is called the deviation's target node. The 4597 contents of the "deviation" statement give details about the 4598 deviation. 4600 The argument string is an absolute schema node identifier (see 4601 Section 6.5). 4603 Deviations define the way a device or class of devices deviate from a 4604 standard. This means that deviations MUST never be part of a 4605 published standard, since they are the mechanism for learning how 4606 implementations vary from the standards. 4608 Device deviations are strongly discouraged and MUST only be used as a 4609 last resort. Telling the application how a device fails to follow a 4610 standard is no substitute for implementing the standard correctly. A 4611 device that deviates from a module is not fully compliant with the 4612 module. 4614 However, in some cases, a particular device may not have the hardware 4615 or software ability to support parts of a standard module. When this 4616 occurs, the device makes a choice either to treat attempts to 4617 configure unsupported parts of the module as an error that is 4618 reported back to the unsuspecting application or ignore those 4619 incoming requests. Neither choice is acceptable. 4621 Instead, YANG allows devices to document portions of a base module 4622 that are not supported or supported but with different syntax, by 4623 using the "deviation" statement. 4625 7.18.3.1. The deviation's Substatements 4627 +--------------+----------+-------------+ 4628 | substatement | section | cardinality | 4629 +--------------+----------+-------------+ 4630 | description | 7.19.3 | 0..1 | 4631 | deviate | 7.18.3.2 | 1..n | 4632 | reference | 7.19.4 | 0..1 | 4633 +--------------+----------+-------------+ 4635 7.18.3.2. The deviate Statement 4637 The "deviate" statement defines how the device's implementation of 4638 the target node deviates from its original definition. The argument 4639 is one of the strings "not-supported", "add", "replace", or "delete". 4641 The argument "not-supported" indicates that the target node is not 4642 implemented by this device. 4644 The argument "add" adds properties to the target node. The 4645 properties to add are identified by substatements to the "deviate" 4646 statement. If a property can only appear once, the property MUST NOT 4647 exist in the target node. 4649 The argument "replace" replaces properties of the target node. The 4650 properties to replace are identified by substatements to the 4651 "deviate" statement. The properties to replace MUST exist in the 4652 target node. 4654 The argument "delete" deletes properties from the target node. The 4655 properties to delete are identified by substatements to the "delete" 4656 statement. The substatement's keyword MUST match a corresponding 4657 keyword in the target node, and the argument's string MUST be equal 4658 to the corresponding keyword's argument string in the target node. 4660 +--------------+---------+-------------+ 4661 | substatement | section | cardinality | 4662 +--------------+---------+-------------+ 4663 | config | 7.19.1 | 0..1 | 4664 | default | 7.6.4 | 0..1 | 4665 | mandatory | 7.6.5 | 0..1 | 4666 | max-elements | 7.7.4 | 0..1 | 4667 | min-elements | 7.7.3 | 0..1 | 4668 | must | 7.5.3 | 0..n | 4669 | type | 7.4 | 0..1 | 4670 | unique | 7.8.3 | 0..n | 4671 | units | 7.3.3 | 0..1 | 4672 +--------------+---------+-------------+ 4674 The deviate's Substatements 4676 7.18.3.3. Usage Example 4678 In this example, the device is informing client applications that it 4679 does not support the "daytime" service in the style of RFC 867. 4681 deviation /base:system/base:daytime { 4682 deviate not-supported; 4683 } 4685 The following example sets a device-specific default value to a leaf 4686 that does not have a default value defined: 4688 deviation /base:system/base:user/base:type { 4689 deviate add { 4690 default "admin"; // new users are 'admin' by default 4691 } 4692 } 4694 In this example, the device limits the number of name servers to 3: 4696 deviation /base:system/base:name-server { 4697 deviate replace { 4698 max-elements 3; 4699 } 4700 } 4702 If the original definition is: 4704 container system { 4705 must "daytime or time"; 4706 ... 4707 } 4709 a device might remove this must constraint by doing: 4711 deviation "/base:system" { 4712 deviate delete { 4713 must "daytime or time"; 4714 } 4715 } 4717 7.19. Common Statements 4719 This section defines substatements common to several other 4720 statements. 4722 7.19.1. The config Statement 4724 The "config" statement takes as an argument the string "true" or 4725 "false". If "config" is "true", the definition represents 4726 configuration. Data nodes representing configuration will be part of 4727 the reply to a request, and can be sent in a 4728 or request. 4730 If "config" is "false", the definition represents state data. Data 4731 nodes representing state data will be part of the reply to a , 4732 but not to a request, and cannot be sent in a 4733 or request. 4735 If "config" is not specified, the default is the same as the parent 4736 schema node's "config" value. If the parent node is a "case" node, 4737 the value is the same as the "case" node's parent "choice" node. 4739 If the top node does not specify a "config" statement, the default is 4740 "true". 4742 If a node has "config" set to "false", no node underneath it can have 4743 "config" set to "true". 4745 7.19.2. The status Statement 4747 The "status" statement takes as an argument one of the strings 4748 "current", "deprecated", or "obsolete". 4750 o "current" means that the definition is current and valid. 4752 o "deprecated" indicates an obsolete definition, but it permits new/ 4753 continued implementation in order to foster interoperability with 4754 older/existing implementations. 4756 o "obsolete" means the definition is obsolete and SHOULD NOT be 4757 implemented and/or can be removed from implementations. 4759 If no status is specified, the default is "current". 4761 If a definition is "current", it MUST NOT reference a "deprecated" or 4762 "obsolete" definition within the same module. 4764 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4765 definition within the same module. 4767 For example, the following is illegal: 4769 typedef my-type { 4770 status deprecated; 4771 type int32; 4772 } 4774 leaf my-leaf { 4775 status current; 4776 type my-type; // illegal, since my-type is deprecated 4777 } 4779 7.19.3. The description Statement 4781 The "description" statement takes as an argument a string that 4782 contains a human-readable textual description of this definition. 4783 The text is provided in a language (or languages) chosen by the 4784 module developer; for the sake of interoperability, it is RECOMMENDED 4785 to choose a language that is widely understood among the community of 4786 network administrators who will use the module. 4788 7.19.4. The reference Statement 4790 The "reference" statement takes as an argument a string that is used 4791 to specify a textual cross-reference to an external document, either 4792 another module that defines related management information, or a 4793 document that provides additional information relevant to this 4794 definition. 4796 For example, a typedef for a "uri" data type could look like: 4798 typedef uri { 4799 type string; 4800 reference 4801 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 4802 ... 4803 } 4805 7.19.5. The when Statement 4807 The "when" statement makes its parent data definition statement 4808 conditional. The node defined by the parent data definition 4809 statement is only valid when the condition specified by the "when" 4810 statement is satisfied. The statement's argument is an XPath 4811 expression (see Section 6.4), which is used to formally specify this 4812 condition. If the XPath expression conceptually evaluates to "true" 4813 for a particular instance, then the node defined by the parent data 4814 definition statement is valid; otherwise, it is not. 4816 A leaf that is a list key MUST NOT have a "when" statement, unless 4817 the condition specified in the "when" statement is the same as the 4818 "when" condition in effect on the leaf's parent node. 4820 See Section 8.3.2 for additional information. 4822 The XPath expression is conceptually evaluated in the following 4823 context, in addition to the definition in Section 6.4.1: 4825 o If the "when" statement is a child of an "augment" statement, then 4826 the context node is the augment's target node in the data tree, if 4827 the target node is a data node. Otherwise, the context node is 4828 the closest ancestor node to the target node that is also a data 4829 node. 4831 o If the "when" statement is a child of a "uses", "choice", or 4832 "case" statement, then the context node is the closest ancestor 4833 node to the "uses", "choice", or "case" node that is also a data 4834 node. 4836 o If the "when" statement is a child of any other data definition 4837 statement, the context node is the data definition's node in the 4838 data tree. 4840 o The accessible tree is made up of all nodes in the data tree, and 4841 all leafs with default values in use (see Section 7.6.1). 4843 The accessible tree depends on the context node: 4845 o If the context node represents configuration, the tree is the data 4846 in the NETCONF datastore where the context node exists. The XPath 4847 root node has all top-level configuration data nodes in all 4848 modules as children. 4850 o If the context node represents state data, the tree is all state 4851 data on the device, and the "running" datastore. The XPath root 4852 node has all top-level data nodes in all modules as children. 4854 o If the context node represents notification content, the tree is 4855 the notification XML instance document. The XPath root node has 4856 the element representing the notification being defined as the 4857 only child. 4859 o If the context node represents RPC input parameters, the tree is 4860 the RPC XML instance document. The XPath root node has the 4861 element representing the RPC operation being defined as the only 4862 child. 4864 o If the context node represents RPC output parameters, the tree is 4865 the RPC reply instance document. The XPath root node has the 4866 elements representing the RPC output parameters as children. 4868 The result of the XPath expression is converted to a boolean value 4869 using the standard XPath rules. 4871 Note that the XPath expression is conceptually evaluated. This means 4872 that an implementation does not have to use an XPath evaluator on the 4873 device. The "when" statement can very well be implemented with 4874 specially written code. 4876 8. Constraints 4878 8.1. Constraints on Data 4880 Several YANG statements define constraints on valid data. These 4881 constraints are enforced in different ways, depending on what type of 4882 data the statement defines. 4884 o If the constraint is defined on configuration data, it MUST be 4885 true in a valid configuration data tree. 4887 o If the constraint is defined on state data, it MUST be true in a 4888 reply to a operation without a filter. 4890 o If the constraint is defined on notification content, it MUST be 4891 true in any notification instance. 4893 o If the constraint is defined on RPC input parameters, it MUST be 4894 true in an invocation of the RPC operation. 4896 o If the constraint is defined on RPC output parameters, it MUST be 4897 true in the RPC reply. 4899 8.2. Hierarchy of Constraints 4901 Conditions on parent nodes affect constraints on child nodes as a 4902 natural consequence of the hierarchy of nodes. "must", "mandatory", 4903 "min-elements", and "max-elements" constraints are not enforced if 4904 the parent node has a "when" or "if-feature" property that is not 4905 satisfied on the current device. 4907 In this example, the "mandatory" constraint on the "longitude" leaf 4908 is not enforced on devices that lack the "has-gps" feature: 4910 container location { 4911 if-feature has-gps; 4912 leaf longitude { 4913 mandatory true; 4914 ... 4915 } 4916 } 4918 8.3. Constraint Enforcement Model 4920 For configuration data, there are three windows when constraints MUST 4921 be enforced: 4923 o during parsing of RPC payloads 4924 o during processing of NETCONF operations 4926 o during validation 4928 Each of these scenarios is considered in the following sections. 4930 8.3.1. Payload Parsing 4932 When content arrives in RPC payloads, it MUST be well-formed XML, 4933 following the hierarchy and content rules defined by the set of 4934 models the device implements. 4936 o If a leaf data value does not match the type constraints for the 4937 leaf, including those defined in the type's "range", "length", and 4938 "pattern" properties, the server MUST reply with an 4939 "invalid-value" error-tag in the rpc-error, and with the error- 4940 app-tag and error-message associated with the constraint, if any 4941 exist. 4943 o If all keys of a list entry are not present, the server MUST reply 4944 with a "missing-element" error-tag in the rpc-error. 4946 o If data for more than one case branch of a choice is present, the 4947 server MUST reply with a "bad-element" in the rpc-error. 4949 o If data for a node tagged with "if-feature" is present, and the 4950 if-feature expression evaluates to "false" on the device, the 4951 server MUST reply with an "unknown-element" error-tag in the rpc- 4952 error. 4954 o If data for a node tagged with "when" is present, and the "when" 4955 condition evaluates to "false", the server MUST reply with an 4956 "unknown-element" error-tag in the rpc-error. 4958 o For insert handling, if the value for the attributes "before" and 4959 "after" are not valid for the type of the appropriate key leafs, 4960 the server MUST reply with a "bad-attribute" error-tag in the rpc- 4961 error. 4963 o If the attributes "before" and "after" appears in any element that 4964 is not a list whose "ordered-by" property is "user", the server 4965 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 4967 8.3.2. NETCONF Processing 4969 After the incoming data is parsed, the NETCONF server performs the 4970 operation by applying the data to the configuration 4971 datastore. During this processing, the following errors MUST be 4972 detected: 4974 o Delete requests for non-existent data. 4976 o Create requests for existent data. 4978 o Insert requests with "before" or "after" parameters that do not 4979 exist. 4981 During processing: 4983 o If the NETCONF operation creates data nodes under a "choice", any 4984 existing nodes from other "case" branches are deleted by the 4985 server. 4987 o If the NETCONF operation modifies a data node such that any node's 4988 "when" expression becomes false, then the node with the "when" 4989 expression is deleted by the server. 4991 8.3.3. Validation 4993 When datastore processing is complete, the final contents MUST obey 4994 all validation constraints. This validation processing is performed 4995 at differing times according to the datastore. If the datastore is 4996 "running" or "startup", these constraints MUST be enforced at the end 4997 of the or operation. If the datastore is 4998 "candidate", the constraint enforcement is delayed until a 4999 or operation. 5001 o Any "must" constraints MUST evaluate to "true". 5003 o Any referential integrity constraints defined via the "path" 5004 statement MUST be satisfied. 5006 o Any "unique" constraints on lists MUST be satisfied. 5008 o The "min-elements" and "max-elements" constraints are enforced for 5009 lists and leaf-lists. 5011 9. Built-In Types 5013 YANG has a set of built-in types, similar to those of many 5014 programming languages, but with some differences due to special 5015 requirements from the management information model. 5017 Additional types may be defined, derived from those built-in types or 5018 from other derived types. Derived types may use subtyping to 5019 formally restrict the set of possible values. 5021 The different built-in types and their derived types allow different 5022 kinds of subtyping, namely length and regular expression restrictions 5023 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 5024 numeric types (Section 9.2.4). 5026 The lexical representation of a value of a certain type is used in 5027 the NETCONF messages and when specifying default values and numerical 5028 ranges in YANG modules. 5030 9.1. Canonical Representation 5032 For most types, there is a single canonical representation of the 5033 type's values. Some types allow multiple lexical representations of 5034 the same value, for example, the positive integer "17" can be 5035 represented as "+17" or "17". Implementations MUST support all 5036 lexical representations specified in this document. 5038 When a NETCONF server sends data, it MUST be in the canonical form. 5040 Some types have a lexical representation that depends on the XML 5041 context in which they occur. These types do not have a canonical 5042 form. 5044 9.2. The Integer Built-In Types 5046 The integer built-in types are int8, int16, int32, int64, uint8, 5047 uint16, uint32, and uint64. They represent signed and unsigned 5048 integers of different sizes: 5050 int8 represents integer values between -128 and 127, inclusively. 5052 int16 represents integer values between -32768 and 32767, 5053 inclusively. 5055 int32 represents integer values between -2147483648 and 2147483647, 5056 inclusively. 5058 int64 represents integer values between -9223372036854775808 and 5059 9223372036854775807, inclusively. 5061 uint8 represents integer values between 0 and 255, inclusively. 5063 uint16 represents integer values between 0 and 65535, inclusively. 5065 uint32 represents integer values between 0 and 4294967295, 5066 inclusively. 5068 uint64 represents integer values between 0 and 18446744073709551615, 5069 inclusively. 5071 9.2.1. Lexical Representation 5073 An integer value is lexically represented as an optional sign ("+" or 5074 "-"), followed by a sequence of decimal digits. If no sign is 5075 specified, "+" is assumed. 5077 For convenience, when specifying a default value for an integer in a 5078 YANG module, an alternative lexical representation can be used, which 5079 represents the value in a hexadecimal or octal notation. The 5080 hexadecimal notation consists of an optional sign ("+" or "-"), the 5081 characters "0x" followed a number of hexadecimal digits, where 5082 letters may be uppercase or lowercase. The octal notation consists 5083 of an optional sign ("+" or "-"), the character "0" followed a number 5084 of octal digits. 5086 Note that if a default value in a YANG module has a leading zero 5087 ("0"), it is interpreted as an octal number. In the XML instance 5088 documents, an integer is always interpreted as a decimal number, and 5089 leading zeros are allowed. 5091 Examples: 5093 // legal values 5094 +4711 // legal positive value 5095 4711 // legal positive value 5096 -123 // legal negative value 5097 0xf00f // legal positive hexadecimal value 5098 -0xf // legal negative hexadecimal value 5099 052 // legal positive octal value 5101 // illegal values 5102 - 1 // illegal intermediate space 5104 9.2.2. Canonical Form 5106 The canonical form of a positive integer does not include the sign 5107 "+". Leading zeros are prohibited. The value zero is represented as 5108 "0". 5110 9.2.3. Restrictions 5112 All integer types can be restricted with the "range" statement 5113 (Section 9.2.4). 5115 9.2.4. The range Statement 5117 The "range" statement, which is an optional substatement to the 5118 "type" statement, takes as an argument a range expression string. It 5119 is used to restrict integer and decimal built-in types, or types 5120 derived from those. 5122 A range consists of an explicit value, or a lower-inclusive bound, 5123 two consecutive dots "..", and an upper-inclusive bound. Multiple 5124 values or ranges can be given, separated by "|". If multiple values 5125 or ranges are given, they all MUST be disjoint and MUST be in 5126 ascending order. If a range restriction is applied to an already 5127 range-restricted type, the new restriction MUST be equal or more 5128 limiting, that is raising the lower bounds, reducing the upper 5129 bounds, removing explicit values or ranges, or splitting ranges into 5130 multiple ranges with intermediate gaps. Each explicit value and 5131 range boundary value given in the range expression MUST match the 5132 type being restricted, or be one of the special values "min" or 5133 "max". "min" and "max" mean the minimum and maximum value accepted 5134 for the type being restricted, respectively. 5136 The range expression syntax is formally defined by the rule 5137 "range-arg" in Section 13. 5139 9.2.4.1. The range's Substatements 5141 +---------------+---------+-------------+ 5142 | substatement | section | cardinality | 5143 +---------------+---------+-------------+ 5144 | description | 7.19.3 | 0..1 | 5145 | error-app-tag | 7.5.4.2 | 0..1 | 5146 | error-message | 7.5.4.1 | 0..1 | 5147 | reference | 7.19.4 | 0..1 | 5148 +---------------+---------+-------------+ 5150 9.2.5. Usage Example 5151 typedef my-base-int32-type { 5152 type int32 { 5153 range "1..4 | 10..20"; 5154 } 5155 } 5157 typedef my-type1 { 5158 type my-base-int32-type { 5159 // legal range restriction 5160 range "11..max"; // 11..20 5161 } 5162 } 5164 typedef my-type2 { 5165 type my-base-int32-type { 5166 // illegal range restriction 5167 range "11..100"; 5168 } 5169 } 5171 9.3. The decimal64 Built-In Type 5173 The decimal64 type represents a subset of the real numbers, which can 5174 be represented by decimal numerals. The value space of decimal64 is 5175 the set of numbers that can be obtained by multiplying a 64-bit 5176 signed integer by a negative power of ten, i.e., expressible as 5177 "i x 10^-n" where i is an integer64 and n is an integer between 1 and 5178 18, inclusively. 5180 9.3.1. Lexical Representation 5182 A decimal64 value is lexically represented as an optional sign ("+" 5183 or "-"), followed by a sequence of decimal digits, optionally 5184 followed by a period ('.') as a decimal indicator and a sequence of 5185 decimal digits. If no sign is specified, "+" is assumed. 5187 9.3.2. Canonical Form 5189 The canonical form of a positive decimal64 does not include the sign 5190 "+". The decimal point is required. Leading and trailing zeros are 5191 prohibited, subject to the rule that there MUST be at least one digit 5192 before and after the decimal point. The value zero is represented as 5193 "0.0". 5195 9.3.3. Restrictions 5197 A decimal64 type can be restricted with the "range" statement 5198 (Section 9.2.4). 5200 9.3.4. The fraction-digits Statement 5202 The "fraction-digits" statement, which is a substatement to the 5203 "type" statement, MUST be present if the type is "decimal64". It 5204 takes as an argument an integer between 1 and 18, inclusively. It 5205 controls the size of the minimum difference between values of a 5206 decimal64 type, by restricting the value space to numbers that are 5207 expressible as "i x 10^-n" where n is the fraction-digits argument. 5209 The following table lists the minimum and maximum value for each 5210 fraction-digit value: 5212 +----------------+-----------------------+----------------------+ 5213 | fraction-digit | min | max | 5214 +----------------+-----------------------+----------------------+ 5215 | 1 | -922337203685477580.8 | 922337203685477580.7 | 5216 | 2 | -92233720368547758.08 | 92233720368547758.07 | 5217 | 3 | -9223372036854775.808 | 9223372036854775.807 | 5218 | 4 | -922337203685477.5808 | 922337203685477.5807 | 5219 | 5 | -92233720368547.75808 | 92233720368547.75807 | 5220 | 6 | -9223372036854.775808 | 9223372036854.775807 | 5221 | 7 | -922337203685.4775808 | 922337203685.4775807 | 5222 | 8 | -92233720368.54775808 | 92233720368.54775807 | 5223 | 9 | -9223372036.854775808 | 9223372036.854775807 | 5224 | 10 | -922337203.6854775808 | 922337203.6854775807 | 5225 | 11 | -92233720.36854775808 | 92233720.36854775807 | 5226 | 12 | -9223372.036854775808 | 9223372.036854775807 | 5227 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5228 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5229 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5230 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5231 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5232 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5233 +----------------+-----------------------+----------------------+ 5235 9.3.5. Usage Example 5237 typedef my-decimal { 5238 type decimal64 { 5239 fraction-digits 2; 5240 range "1 .. 3.14 | 10 | 20..max"; 5241 } 5242 } 5244 9.4. The string Built-In Type 5246 The string built-in type represents human-readable strings in YANG. 5247 Legal characters are tab, carriage return, line feed, and the legal 5248 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 5250 ;; any Unicode character, excluding the surrogate blocks, 5251 ;; FFFE, and FFFF. 5252 string = *char 5253 char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD / 5254 %x10000-10FFFF 5256 9.4.1. Lexical Representation 5258 A string value is lexically represented as character data in the XML 5259 instance documents. 5261 9.4.2. Canonical Form 5263 The canonical form is the same as the lexical representation. No 5264 Unicode normalization is performed of string values. 5266 9.4.3. Restrictions 5268 A string can be restricted with the "length" (Section 9.4.4) and 5269 "pattern" (Section 9.4.5) statements. 5271 9.4.4. The length Statement 5273 The "length" statement, which is an optional substatement to the 5274 "type" statement, takes as an argument a length expression string. 5275 It is used to restrict the built-in types "string" and "binary" or 5276 types derived from them. 5278 A "length" statement restricts the number of Unicode characters in 5279 the string. 5281 A length range consists of an explicit value, or a lower bound, two 5282 consecutive dots "..", and an upper bound. Multiple values or ranges 5283 can be given, separated by "|". Length-restricting values MUST NOT 5284 be negative. If multiple values or ranges are given, they all MUST 5285 be disjoint and MUST be in ascending order. If a length restriction 5286 is applied to an already length-restricted type, the new restriction 5287 MUST be equal or more limiting, that is, raising the lower bounds, 5288 reducing the upper bounds, removing explicit length values or ranges, 5289 or splitting ranges into multiple ranges with intermediate gaps. A 5290 length value is a non-negative integer, or one of the special values 5291 "min" or "max". "min" and "max" mean the minimum and maximum length 5292 accepted for the type being restricted, respectively. An 5293 implementation is not required to support a length value larger than 5294 18446744073709551615. 5296 The length expression syntax is formally defined by the rule 5297 "length-arg" in Section 13. 5299 9.4.4.1. The length's Substatements 5301 +---------------+---------+-------------+ 5302 | substatement | section | cardinality | 5303 +---------------+---------+-------------+ 5304 | description | 7.19.3 | 0..1 | 5305 | error-app-tag | 7.5.4.2 | 0..1 | 5306 | error-message | 7.5.4.1 | 0..1 | 5307 | reference | 7.19.4 | 0..1 | 5308 +---------------+---------+-------------+ 5310 9.4.5. The pattern Statement 5312 The "pattern" statement, which is an optional substatement to the 5313 "type" statement, takes as an argument a regular expression string, 5314 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5315 "string", or types derived from "string", to values that match the 5316 pattern. 5318 If the type has multiple "pattern" statements, the expressions are 5319 ANDed together, i.e., all such expressions have to match. 5321 If a pattern restriction is applied to an already pattern-restricted 5322 type, values must match all patterns in the base type, in addition to 5323 the new patterns. 5325 9.4.5.1. The pattern's Substatements 5327 +---------------+---------+-------------+ 5328 | substatement | section | cardinality | 5329 +---------------+---------+-------------+ 5330 | description | 7.19.3 | 0..1 | 5331 | error-app-tag | 7.5.4.2 | 0..1 | 5332 | error-message | 7.5.4.1 | 0..1 | 5333 | modifier | 9.4.6 | 0..1 | 5334 | reference | 7.19.4 | 0..1 | 5335 +---------------+---------+-------------+ 5337 9.4.6. The modifier Statement 5339 9.4.7. Usage Example 5341 With the following typedef: 5343 typedef my-base-str-type { 5344 type string { 5345 length "1..255"; 5346 } 5347 } 5349 the following refinement is legal: 5351 type my-base-str-type { 5352 // legal length refinement 5353 length "11 | 42..max"; // 11 | 42..255 5354 } 5356 and the following refinement is illegal: 5358 type my-base-str-type { 5359 // illegal length refinement 5360 length "1..999"; 5361 } 5363 With the following type: 5365 type string { 5366 length "0..4"; 5367 pattern "[0-9a-fA-F]*"; 5368 } 5370 the following strings match: 5372 AB // legal 5373 9A00 // legal 5375 and the following strings do not match: 5377 00ABAB // illegal, too long 5378 xx00 // illegal, bad characters 5380 With the following type: 5382 typedef yang-identifier { 5383 type string { 5384 length "1..max"; 5385 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 5386 pattern '[xX][mM][lL].*' { 5387 modifier invert-match; 5388 } 5389 } 5390 } 5392 the following string match: 5394 enabled // legal 5396 and the following strings do not match: 5398 10-mbit // illegal, starts with a number 5399 xml-element // illegal, starts with illegal sequence 5401 9.5. The boolean Built-In Type 5403 The boolean built-in type represents a boolean value. 5405 9.5.1. Lexical Representation 5407 The lexical representation of a boolean value is a string with a 5408 value of "true" or "false". These values MUST be in lowercase. 5410 9.5.2. Canonical Form 5412 The canonical form is the same as the lexical representation. 5414 9.5.3. Restrictions 5416 A boolean cannot be restricted. 5418 9.6. The enumeration Built-In Type 5420 The enumeration built-in type represents values from a set of 5421 assigned names. 5423 9.6.1. Lexical Representation 5425 The lexical representation of an enumeration value is the assigned 5426 name string. 5428 9.6.2. Canonical Form 5430 The canonical form is the assigned name string. 5432 9.6.3. Restrictions 5434 An enumeration cannot be restricted. 5436 9.6.4. The enum Statement 5438 The "enum" statement, which is a substatement to the "type" 5439 statement, MUST be present if the type is "enumeration". It is 5440 repeatedly used to specify each assigned name of an enumeration type. 5441 It takes as an argument a string which is the assigned name. The 5442 string MUST NOT be empty and MUST NOT have any leading or trailing 5443 whitespace characters. The use of Unicode control codes SHOULD be 5444 avoided. 5446 The statement is optionally followed by a block of substatements that 5447 holds detailed enum information. 5449 All assigned names in an enumeration MUST be unique. 5451 9.6.4.1. The enum's Substatements 5453 +--------------+---------+-------------+ 5454 | substatement | section | cardinality | 5455 +--------------+---------+-------------+ 5456 | description | 7.19.3 | 0..1 | 5457 | reference | 7.19.4 | 0..1 | 5458 | status | 7.19.2 | 0..1 | 5459 | value | 9.6.4.2 | 0..1 | 5460 +--------------+---------+-------------+ 5462 9.6.4.2. The value Statement 5464 The "value" statement, which is optional, is used to associate an 5465 integer value with the assigned name for the enum. This integer 5466 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5467 unique within the enumeration type. The value is unused by YANG and 5468 the XML encoding, but is carried as a convenience to implementors. 5470 If a value is not specified, then one will be automatically assigned. 5471 If the "enum" substatement is the first one defined, the assigned 5472 value is zero (0); otherwise, the assigned value is one greater than 5473 the current highest enum value (i.e., the highest enum value, 5474 implicit or explicit, prior to the current "enum" substatement in the 5475 parent "type" statement). 5477 If the current highest value is equal to 2147483647, then an enum 5478 value MUST be specified for "enum" substatements following the one 5479 with the current highest value. 5481 9.6.5. Usage Example 5483 leaf myenum { 5484 type enumeration { 5485 enum zero; 5486 enum one; 5487 enum seven { 5488 value 7; 5489 } 5490 } 5491 } 5493 The lexical representation of the leaf "myenum" with value "seven" 5494 is: 5496 seven 5498 9.7. The bits Built-In Type 5500 The bits built-in type represents a bit set. That is, a bits value 5501 is a set of flags identified by small integer position numbers 5502 starting at 0. Each bit number has an assigned name. 5504 9.7.1. Restrictions 5506 A bits type cannot be restricted. 5508 9.7.2. Lexical Representation 5510 The lexical representation of the bits type is a space-separated list 5511 of the individual bit values that are set. An empty string thus 5512 represents a value where no bits are set. 5514 9.7.3. Canonical Form 5516 In the canonical form, the bit values are separated by a single space 5517 character and they appear ordered by their position (see 5518 Section 9.7.4.2). 5520 9.7.4. The bit Statement 5522 The "bit" statement, which is a substatement to the "type" statement, 5523 MUST be present if the type is "bits". It is repeatedly used to 5524 specify each assigned named bit of a bits type. It takes as an 5525 argument a string that is the assigned name of the bit. It is 5526 followed by a block of substatements that holds detailed bit 5527 information. The assigned name follows the same syntax rules as an 5528 identifier (see Section 6.2). 5530 All assigned names in a bits type MUST be unique. 5532 9.7.4.1. The bit's Substatements 5534 +--------------+---------+-------------+ 5535 | substatement | section | cardinality | 5536 +--------------+---------+-------------+ 5537 | description | 7.19.3 | 0..1 | 5538 | reference | 7.19.4 | 0..1 | 5539 | status | 7.19.2 | 0..1 | 5540 | position | 9.7.4.2 | 0..1 | 5541 +--------------+---------+-------------+ 5543 9.7.4.2. The position Statement 5545 The "position" statement, which is optional, takes as an argument a 5546 non-negative integer value that specifies the bit's position within a 5547 hypothetical bit field. The position value MUST be in the range 0 to 5548 4294967295, and it MUST be unique within the bits type. The value is 5549 unused by YANG and the NETCONF messages, but is carried as a 5550 convenience to implementors. 5552 If a bit position is not specified, then one will be automatically 5553 assigned. If the "bit" substatement is the first one defined, the 5554 assigned value is zero (0); otherwise, the assigned value is one 5555 greater than the current highest bit position (i.e., the highest bit 5556 position, implicit or explicit, prior to the current "bit" 5557 substatement in the parent "type" statement). 5559 If the current highest bit position value is equal to 4294967295, 5560 then a position value MUST be specified for "bit" substatements 5561 following the one with the current highest position value. 5563 9.7.5. Usage Example 5565 Given the following leaf: 5567 leaf mybits { 5568 type bits { 5569 bit disable-nagle { 5570 position 0; 5571 } 5572 bit auto-sense-speed { 5573 position 1; 5574 } 5575 bit ten-Mb-only { 5576 position 2; 5577 } 5578 } 5579 default "auto-sense-speed"; 5580 } 5582 The lexical representation of this leaf with bit values disable-nagle 5583 and ten-Mb-only set would be: 5585 disable-nagle ten-Mb-only 5587 9.8. The binary Built-In Type 5589 The binary built-in type represents any binary data, i.e., a sequence 5590 of octets. 5592 9.8.1. Restrictions 5594 A binary can be restricted with the "length" (Section 9.4.4) 5595 statement. The length of a binary value is the number of octets it 5596 contains. 5598 9.8.2. Lexical Representation 5600 Binary values are encoded with the base64 encoding scheme (see 5601 [RFC4648], Section 4). 5603 9.8.3. Canonical Form 5605 The canonical form of a binary value follows the rules in [RFC4648]. 5607 9.9. The leafref Built-In Type 5609 The leafref type is used to declare a constraint on the value space 5610 of a leaf, based on a reference to a set of leaf instances in the 5611 data tree. The "path" substatement (Section 9.9.2) selects a set of 5612 leaf instances, and the leafref value space is the set of values of 5613 these leaf instances. 5615 If the leaf with the leafref type represents configuration data, and 5616 the "require-instance" property (Section 9.9.3) is "true", the leaf 5617 it refers to MUST also represent configuration. Such a leaf puts a 5618 constraint on valid data. All such nodes MUST reference existing 5619 leaf instances or leafs with default values in use (see 5620 Section 7.6.1) for the data to be valid. This constraint is enforced 5621 according to the rules in Section 8. 5623 There MUST NOT be any circular chains of leafrefs. 5625 If the leaf that the leafref refers to is conditional based on one or 5626 more features (see Section 7.18.2), then the leaf with the leafref 5627 type MUST also be conditional based on at least the same set of 5628 features. 5630 9.9.1. Restrictions 5632 A leafref can be restricted with the "require-instance" statement 5633 (Section 9.9.3). 5635 9.9.2. The path Statement 5637 The "path" statement, which is a substatement to the "type" 5638 statement, MUST be present if the type is "leafref". It takes as an 5639 argument a string that MUST refer to a leaf or leaf-list node. 5641 The syntax for a path argument is a subset of the XPath abbreviated 5642 syntax. Predicates are used only for constraining the values for the 5643 key nodes for list entries. Each predicate consists of exactly one 5644 equality test per key, and multiple adjacent predicates MAY be 5645 present if a list has multiple keys. The syntax is formally defined 5646 by the rule "path-arg" in Section 13. 5648 The predicates are only used when more than one key reference is 5649 needed to uniquely identify a leaf instance. This occurs if a list 5650 has multiple keys, or a reference to a leaf other than the key in a 5651 list is needed. In these cases, multiple leafrefs are typically 5652 specified, and predicates are used to tie them together. 5654 The "path" expression evaluates to a node set consisting of zero, 5655 one, or more nodes. If the leaf with the leafref type represents 5656 configuration data, this node set MUST be non-empty. 5658 The "path" XPath expression is conceptually evaluated in the 5659 following context, in addition to the definition in Section 6.4.1: 5661 o The context node is the node in the data tree for which the "path" 5662 statement is defined. 5664 The accessible tree depends on the context node: 5666 o If the context node represents configuration data, the tree is the 5667 data in the NETCONF datastore where the context node exists. The 5668 XPath root node has all top-level configuration data nodes in all 5669 modules as children. 5671 o Otherwise, the tree is all state data on the device, and the 5672 "running" datastore. The XPath root node has all top-level data 5673 nodes in all modules as children. 5675 9.9.3. The require-instance Statement 5677 The "require-instance" statement, which is a substatement to the 5678 "type" statement, MAY be present if the type is "instance-identifier" 5679 or "leafref". It takes as an argument the string "true" or "false". 5680 If this statement is not present, it defaults to "true". 5682 If "require-instance" is "true", it means that the instance being 5683 referred MUST exist for the data to be valid. This constraint is 5684 enforced according to the rules in Section 8. 5686 If "require-instance" is "false", it means that the instance being 5687 referred MAY exist in valid data. 5689 9.9.4. Lexical Representation 5691 A leafref value is encoded the same way as the leaf it references. 5693 9.9.5. Canonical Form 5695 The canonical form of a leafref is the same as the canonical form of 5696 the leaf it references. 5698 9.9.6. Usage Example 5700 With the following list: 5702 list interface { 5703 key "name"; 5704 leaf name { 5705 type string; 5706 } 5707 leaf admin-status { 5708 type admin-status; 5709 } 5710 list address { 5711 key "ip"; 5712 leaf ip { 5713 type yang:ip-address; 5714 } 5715 } 5716 } 5718 The following leafref refers to an existing interface: 5720 leaf mgmt-interface { 5721 type leafref { 5722 path "../interface/name"; 5723 } 5724 } 5726 An example of a corresponding XML snippet: 5728 5729 eth0 5730 5731 5732 lo 5733 5735 eth0 5737 The following leafrefs refer to an existing address of an interface: 5739 container default-address { 5740 leaf ifname { 5741 type leafref { 5742 path "../../interface/name"; 5743 } 5744 } 5745 leaf address { 5746 type leafref { 5747 path "../../interface[name = current()/../ifname]" 5748 + "/address/ip"; 5749 } 5750 } 5751 } 5753 An example of a corresponding XML snippet: 5755 5756 eth0 5757 up 5758
5759 192.0.2.1 5760
5761
5762 192.0.2.2 5763
5764 5765 5766 lo 5767 up 5768
5769 127.0.0.1 5770
5771 5773 5774 eth0 5775
192.0.2.2
5776 5778 The following list uses a leafref for one of its keys. This is 5779 similar to a foreign key in a relational database. 5781 list packet-filter { 5782 key "if-name filter-id"; 5783 leaf if-name { 5784 type leafref { 5785 path "/interface/name"; 5786 } 5787 } 5788 leaf filter-id { 5789 type uint32; 5790 } 5791 ... 5792 } 5794 An example of a corresponding XML snippet: 5796 5797 eth0 5798 up 5799
5800 192.0.2.1 5801
5802
5803 192.0.2.2 5804
5805 5807 5808 eth0 5809 1 5810 ... 5811 5812 5813 eth0 5814 2 5815 ... 5816 5818 The following notification defines two leafrefs to refer to an 5819 existing admin-status: 5821 notification link-failure { 5822 leaf if-name { 5823 type leafref { 5824 path "/interface/name"; 5825 } 5826 } 5827 leaf admin-status { 5828 type leafref { 5829 path 5830 "/interface[name = current()/../if-name]" 5831 + "/admin-status"; 5832 } 5833 } 5834 } 5836 An example of a corresponding XML notification: 5838 5840 2008-04-01T00:01:00Z 5841 5842 eth0 5843 up 5844 5845 5847 9.10. The identityref Built-In Type 5849 The identityref type is used to reference an existing identity (see 5850 Section 7.16). 5852 9.10.1. Restrictions 5854 An identityref cannot be restricted. 5856 9.10.2. The identityref's base Statement 5858 The "base" statement, which is a substatement to the "type" 5859 statement, MUST be present if the type is "identityref". The 5860 argument is the name of an identity, as defined by an "identity" 5861 statement. If a prefix is present on the identity name, it refers to 5862 an identity defined in the module that was imported with that prefix. 5863 Otherwise, an identity with the matching name MUST be defined in the 5864 current module or an included submodule. 5866 Valid values for an identityref are any identities derived from the 5867 identityref's base identity. On a particular server, the valid 5868 values are further restricted to the set of identities defined in the 5869 modules supported by the server. 5871 9.10.3. Lexical Representation 5873 An identityref is encoded as the referred identity's qualified name 5874 as defined in [XML-NAMES]. If the prefix is not present, the 5875 namespace of the identityref is the default namespace in effect on 5876 the element that contains the identityref value. 5878 When an identityref is given a default value using the "default" 5879 statement, the identity name in the default value MAY have a prefix. 5880 If a prefix is present on the identity name, it refers to an identity 5881 defined in the module that was imported with that prefix. Otherwise, 5882 an identity with the matching name MUST be defined in the current 5883 module or an included submodule. 5885 The string value of a node of type identityref in a "must" or "when" 5886 XPath expression is the referred identity's qualified name with the 5887 prefix always present. 5889 9.10.4. Canonical Form 5891 Since the lexical form depends on the XML context in which the value 5892 occurs, this type does not have a canonical form. 5894 9.10.5. Usage Example 5896 With the identity definitions in Section 7.16.3 and the following 5897 module: 5899 module my-crypto { 5900 yang-version 1.1; 5901 namespace "http://example.com/my-crypto"; 5902 prefix mc; 5904 import "crypto-base" { 5905 prefix "crypto"; 5906 } 5908 identity aes { 5909 base "crypto:crypto-alg"; 5910 } 5912 leaf crypto { 5913 type identityref { 5914 base "crypto:crypto-alg"; 5915 } 5916 } 5918 container aes-parameters { 5919 when "../crypto = 'mc:aes'; 5920 ... 5921 } 5922 } 5924 the following is an example how the leaf "crypto" can be encoded, if 5925 the value is the "des3" identity defined in the "des" module: 5927 des:des3 5929 Any prefixes used in the encoding are local to each instance 5930 encoding. This means that the same identityref may be encoded 5931 differently by different implementations. For example, the following 5932 example encodes the same leaf as above: 5934 x:des3 5936 If the "crypto" leaf's value instead is "aes" defined in the 5937 "my-crypto" module, it can be encoded as: 5939 mc:aes 5941 or, using the default namespace: 5943 aes 5945 9.11. The empty Built-In Type 5947 The empty built-in type represents a leaf that does not have any 5948 value, it conveys information by its presence or absence. 5950 An empty type cannot have a default value. 5952 9.11.1. Restrictions 5954 An empty type cannot be restricted. 5956 9.11.2. Lexical Representation 5958 Not applicable. 5960 9.11.3. Canonical Form 5962 Not applicable. 5964 9.11.4. Usage Example 5966 With the following leaf 5968 leaf enable-qos { 5969 type empty; 5970 } 5972 the following is an example of a valid encoding 5974 5976 if the leaf exists. 5978 9.12. The union Built-In Type 5980 The union built-in type represents a value that corresponds to one of 5981 its member types. 5983 When the type is "union", the "type" statement (Section 7.4) MUST be 5984 present. It is used to repeatedly specify each member type of the 5985 union. It takes as an argument a string that is the name of a member 5986 type. 5988 A member type can be of any built-in or derived type. 5990 When a string representing a union data type is validated, the string 5991 is validated against each member type, in the order they are 5992 specified in the "type" statement, until a match is found. The type 5993 that matched will be the type of the value for the node that was 5994 validated. 5996 Any default value or "units" property defined in the member types is 5997 not inherited by the union type. 5999 9.12.1. Restrictions 6001 A union cannot be restricted. However, each member type can be 6002 restricted, based on the rules defined in Section 9. 6004 9.12.2. Lexical Representation 6006 The lexical representation of a union is a value that corresponds to 6007 the representation of any one of the member types. 6009 9.12.3. Canonical Form 6011 The canonical form of a union value is the same as the canonical form 6012 of the member type of the value. 6014 9.12.4. Usage Example 6016 The following is a union of an int32 an enumeration: 6018 type union { 6019 type int32; 6020 type enumeration { 6021 enum "unbounded"; 6022 } 6023 } 6025 Care must be taken when a member type is a leafref where the 6026 "require-instance" property (Section 9.9.3) is "true". If a leaf of 6027 such a type refers to an existing instance, the leaf's value must be 6028 re-validated if the target instance is deleted. For example, with 6029 the following definitions: 6031 list filter { 6032 key name; 6033 leaf name { 6034 type string; 6035 } 6036 ... 6037 } 6039 leaf outbound-filter { 6040 type union { 6041 type leafref { 6042 path "/filter/name"; 6043 } 6044 type enumeration { 6045 enum default-filter; 6046 } 6047 } 6048 } 6050 assume that there exists an entry in the filter list with the name 6051 "http", and that the outbound-filter leaf has this value: 6053 6054 http 6055 6056 http 6058 If the filter entry "http" is removed, the outbound-filter leaf's 6059 value doesn't match the leafref, and the next member type is checked. 6060 The current value ("http") doesn't match the enumeration, so the 6061 resulting configuration is invalid. 6063 If the second member type in the union had been of type "string" 6064 instead of an enumeration, the current value would have matched, and 6065 the resulting configuration would have been valid. 6067 9.13. The instance-identifier Built-In Type 6069 The instance-identifier built-in type is used to uniquely identify a 6070 particular instance node in the data tree. 6072 The syntax for an instance-identifier is a subset of the XPath 6073 abbreviated syntax, formally defined by the rule 6074 "instance-identifier" in Section 13. It is used to uniquely identify 6075 a node in the data tree. Predicates are used only for specifying the 6076 values for the key nodes for list entries, a value of a leaf-list 6077 entry, or a positional index for a list without keys. For 6078 identifying list entries with keys, each predicate consists of one 6079 equality test per key, and each key MUST have a corresponding 6080 predicate. 6082 If the leaf with the instance-identifier type represents 6083 configuration data, and the "require-instance" property 6084 (Section 9.9.3) is "true", the node it refers to MUST also represent 6085 configuration. Such a leaf puts a constraint on valid data. All 6086 such leaf nodes MUST reference existing nodes or leaf nodes with 6087 their default value in use (see Section 7.6.1) for the data to be 6088 valid. This constraint is enforced according to the rules in 6089 Section 8. 6091 The "instance-identifier" XPath expression is conceptually evaluated 6092 in the following context, in addition to the definition in 6093 Section 6.4.1: 6095 o The context node is the root node in the accessible tree. 6097 The accessible tree depends on the leaf with the instance-identifier 6098 type: 6100 o If this leaf represents configuration data, the tree is the data 6101 in the NETCONF datastore where the leaf exists. The XPath root 6102 node has all top-level configuration data nodes in all modules as 6103 children. 6105 o Otherwise, the tree is all state data on the device, and the 6106 "running" datastore. The XPath root node has all top-level data 6107 nodes in all modules as children. 6109 9.13.1. Restrictions 6111 An instance-identifier can be restricted with the "require-instance" 6112 statement (Section 9.9.3). 6114 9.13.2. Lexical Representation 6116 An instance-identifier value is lexically represented as a string. 6117 All node names in an instance-identifier value MUST be qualified with 6118 explicit namespace prefixes, and these prefixes MUST be declared in 6119 the XML namespace scope in the instance-identifier's XML element. 6121 Any prefixes used in the encoding are local to each instance 6122 encoding. This means that the same instance-identifier may be 6123 encoded differently by different implementations. 6125 9.13.3. Canonical Form 6127 Since the lexical form depends on the XML context in which the value 6128 occurs, this type does not have a canonical form. 6130 9.13.4. Usage Example 6132 The following are examples of instance identifiers: 6134 /* instance-identifier for a container */ 6135 /ex:system/ex:services/ex:ssh 6137 /* instance-identifier for a leaf */ 6138 /ex:system/ex:services/ex:ssh/ex:port 6140 /* instance-identifier for a list entry */ 6141 /ex:system/ex:user[ex:name='fred'] 6143 /* instance-identifier for a leaf in a list entry */ 6144 /ex:system/ex:user[ex:name='fred']/ex:type 6146 /* instance-identifier for a list entry with two keys */ 6147 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 6149 /* instance-identifier for a leaf-list entry */ 6150 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 6152 /* instance-identifier for a list entry without keys */ 6153 /ex:stats/ex:port[3] 6155 10. XPath Functions 6157 This document defines two generic XPath functions and four YANG type- 6158 specific XPath functions. 6160 10.1. Functions for Node Sets 6162 10.1.1. current() 6164 node-set current() 6166 The function current() takes no input parameters, and returns a node 6167 set with the initial context node. 6169 10.2. Functions for Strings 6171 10.2.1. re-match() 6173 boolean re-match(string subject, string pattern) 6175 The re-match() function returns true if the "subject" string matches 6176 the regular expression "pattern"; otherwise it returns false. 6178 The function "re-match" checks if a string matches a given regular 6179 expression. The regular expressions used are the XML Schema regular 6180 expressions [XSD-TYPES]. Note that this includes implicit anchoring 6181 of the regular expression at the head and tail. 6183 10.2.1.1. Usage Example 6185 The expression: 6187 re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') 6189 returns true. 6191 To count all logical interfaces called eth0., do: 6193 count(/interface[re-match(name, 'eth0\.\d+')]) 6195 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 6197 10.3.1. deref() 6199 node-set deref(node-set nodes) 6201 The deref() function follows the reference defined by the first node 6202 in document order in the argument "nodes", and returns the nodes it 6203 refers to. 6205 If the first argument node is of type instance-identifier, the 6206 function returns a node set that contains the single node that the 6207 instance identifier refers to, if it exists. If no such node exists, 6208 an empty node-set is returned. 6210 If the first argument node is of type leafref, the function returns a 6211 node set that contains the nodes that the leafref refers to. 6213 If the first argument node is of any other type, an empty node set is 6214 returned. 6216 10.3.1.1. Usage Example 6218 list interface { 6219 key name; 6220 leaf name { ... } 6221 leaf enabled { 6222 type boolean; 6223 } 6224 ... 6225 } 6227 leaf mgmt-interface { 6228 type leafref { 6229 path "/interface/name"; 6230 } 6231 must 'deref(.)/../enabled = "true"' { 6232 error-message 6233 "The management interface cannot be disabled."; 6234 } 6235 } 6237 10.4. Functions for the YANG Type "identityref" 6239 10.4.1. derived-from() 6241 boolean derived-from(node-set nodes, 6242 string module-name, 6243 string identity-name) 6245 The derived-from() function returns true if the first node in 6246 document order in the argument "nodes" is a node of type identityref, 6247 and its value is an identity that is derived from the identity 6248 "identity-name" defined in the YANG module "module-name"; otherwise 6249 it returns false. 6251 10.4.1.1. Usage Example 6252 module example-interface { 6253 ... 6255 identity interface-type; 6257 identity ethernet { 6258 base interface-type; 6259 } 6261 identity fast-ethernet { 6262 base ethernet; 6263 } 6265 identity gigabit-ethernet { 6266 base ethernet; 6267 } 6269 list interface { 6270 key name; 6271 ... 6272 leaf type { 6273 type identityref { 6274 base interface-type; 6275 } 6276 } 6277 ... 6278 } 6280 augment "/interface" { 6281 when 'derived-from(type, 6282 "example-interface", 6283 "ethernet")'; 6284 // ethernet-specific definitions here 6285 } 6286 } 6288 10.5. Functions for the YANG Type "enumeration" 6290 10.5.1. enum-value() 6292 number enum-value(node-set nodes) 6294 The enum-value() function checks if the first node in document order 6295 in the argument "nodes" is a node of type enumeration, and returns 6296 the enum's integer value. If the "nodes" node set is empty, or if 6297 the first node in "nodes" is not of type enumeration, it returns NaN. 6299 10.5.1.1. Usage Example 6301 With this data model: 6303 list alarm { 6304 ... 6305 leaf severity { 6306 type enumeration { 6307 enum cleared { 6308 value 1; 6309 } 6310 enum indeterminate { 6311 value 2; 6312 } 6313 enum minor { 6314 value 3; 6315 } 6316 enum warning { 6317 value 4; 6318 } 6319 enum major { 6320 value 5; 6321 } 6322 enum critical { 6323 value 6; 6324 } 6325 } 6326 } 6327 } 6329 the following XPath expression selects only alarms that are of 6330 severity "major" or higher: 6332 /alarm[enum-value(severity) >= 5] 6334 10.6. Functions for the YANG Type "bits" 6336 10.6.1. bit-is-set() 6338 boolean bit-is-set(node-set nodes, string bit-name) 6340 The bit-is-set() function returns true if the first node in document 6341 order in the argument "nodes" is a node of type bits, and its value 6342 has the bit "'bit-name" set; otherwise it returns false. 6344 10.6.1.1. Usage Example 6346 If an interface has this leaf: 6348 leaf flags { 6349 type bits { 6350 bit UP; 6351 bit PROMISCUOUS 6352 bit DISABLED; 6353 } 6354 } 6356 the following XPath expression can be used to select all interfaces 6357 with the UP flag set: 6359 /interface[bit-is-set(flags, "UP")] 6361 11. Updating a Module 6363 As experience is gained with a module, it may be desirable to revise 6364 that module. However, changes are not allowed if they have any 6365 potential to cause interoperability problems between a client using 6366 an original specification and a server using an updated 6367 specification. 6369 For any published change, a new "revision" statement (Section 7.1.9) 6370 MUST be included in front of the existing "revision" statements. If 6371 there are no existing "revision" statements, then one MUST be added 6372 to identify the new revision. Furthermore, any necessary changes 6373 MUST be applied to any meta-data statements, including the 6374 "organization" and "contact" statements (Section 7.1.7, 6375 Section 7.1.8). 6377 Note that definitions contained in a module are available to be 6378 imported by any other module, and are referenced in "import" 6379 statements via the module name. Thus, a module name MUST NOT be 6380 changed. Furthermore, the "namespace" statement MUST NOT be changed, 6381 since all XML elements are qualified by the namespace. 6383 Obsolete definitions MUST NOT be removed from modules since their 6384 identifiers may still be referenced by other modules. 6386 A definition may be revised in any of the following ways: 6388 o An "enumeration" type may have new enums added, provided the old 6389 enums's values do not change. 6391 o A "bits" type may have new bits added, provided the old bit 6392 positions do not change. 6394 o A "range", "length", or "pattern" statement may expand the allowed 6395 value space. 6397 o A "default" statement may be added to a leaf that does not have a 6398 default value (either directly or indirectly through its type). 6400 o A "units" statement may be added. 6402 o A "reference" statement may be added or updated. 6404 o A "must" statement may be removed or its constraint relaxed. 6406 o A "mandatory" statement may be removed or changed from "true" to 6407 "false". 6409 o A "min-elements" statement may be removed, or changed to require 6410 fewer elements. 6412 o A "max-elements" statement may be removed, or changed to allow 6413 more elements. 6415 o A "description" statement may be added or clarified without 6416 changing the semantics of the definition. 6418 o New typedefs, groupings, rpcs, notifications, extensions, 6419 features, and identities may be added. 6421 o New data definition statements may be added if they do not add 6422 mandatory nodes (Section 3.1) to existing nodes or at the top 6423 level in a module or submodule, or if they are conditionally 6424 dependent on a new feature (i.e., have an "if-feature" statement 6425 that refers to a new feature). 6427 o A new "case" statement may be added. 6429 o A node that represented state data may be changed to represent 6430 configuration, provided it is not mandatory (Section 3.1). 6432 o An "if-feature" statement may be removed, provided its node is not 6433 mandatory (Section 3.1). 6435 o A "status" statement may be added, or changed from "current" to 6436 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 6438 o A "type" statement may be replaced with another "type" statement 6439 that does not change the syntax or semantics of the type. For 6440 example, an inline type definition may be replaced with a typedef, 6441 but an int8 type cannot be replaced by an int16, since the syntax 6442 would change. 6444 o Any set of data definition nodes may be replaced with another set 6445 of syntactically and semantically equivalent nodes. For example, 6446 a set of leafs may be replaced by a uses of a grouping with the 6447 same leafs. 6449 o A module may be split into a set of submodules, or a submodule may 6450 be removed, provided the definitions in the module do not change 6451 in any other way than allowed here. 6453 o The "prefix" statement may be changed, provided all local uses of 6454 the prefix also are changed. 6456 Otherwise, if the semantics of any previous definition are changed 6457 (i.e., if a non-editorial change is made to any definition other than 6458 those specifically allowed above), then this MUST be achieved by a 6459 new definition with a new identifier. 6461 In statements that have any data definition statements as 6462 substatements, those data definition substatements MUST NOT be 6463 reordered. 6465 12. YIN 6467 A YANG module can be translated into an alternative XML-based syntax 6468 called YIN. The translated module is called a YIN module. This 6469 section describes symmetric mapping rules between the two formats. 6471 The YANG and YIN formats contain equivalent information using 6472 different notations. The YIN notation enables developers to 6473 represent YANG data models in XML and therefore use the rich set of 6474 XML-based tools for data filtering and validation, automated 6475 generation of code and documentation, and other tasks. Tools like 6476 XSLT or XML validators can be utilized. 6478 The mapping between YANG and YIN does not modify the information 6479 content of the model. Comments and whitespace are not preserved. 6481 12.1. Formal YIN Definition 6483 There is a one-to-one correspondence between YANG keywords and YIN 6484 elements. The local name of a YIN element is identical to the 6485 corresponding YANG keyword. This means, in particular, that the 6486 document element (root) of a YIN document is always or 6487 . 6489 YIN elements corresponding to the YANG keywords belong to the 6490 namespace whose associated URI is 6491 "urn:ietf:params:xml:ns:yang:yin:1". 6493 YIN elements corresponding to extension keywords belong to the 6494 namespace of the YANG module where the extension keyword is declared 6495 via the "extension" statement. 6497 The names of all YIN elements MUST be properly qualified with their 6498 namespaces specified above using the standard mechanisms of 6499 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 6501 The argument of a YANG statement is represented in YIN either as an 6502 XML attribute or a subelement of the keyword element. Table 1 6503 defines the mapping for the set of YANG keywords. For extensions, 6504 the argument mapping is specified within the "extension" statement 6505 (see Section 7.17). The following rules hold for arguments: 6507 o If the argument is represented as an attribute, this attribute has 6508 no namespace. 6510 o If the argument is represented as an element, it is qualified by 6511 the same namespace as its parent keyword element. 6513 o If the argument is represented as an element, it MUST be the first 6514 child of the keyword element. 6516 Substatements of a YANG statement are represented as (additional) 6517 children of the keyword element and their relative order MUST be the 6518 same as the order of substatements in YANG. 6520 Comments in YANG MAY be mapped to XML comments. 6522 +------------------+---------------+-------------+ 6523 | keyword | argument name | yin-element | 6524 +------------------+---------------+-------------+ 6525 | anyxml | name | false | 6526 | argument | name | false | 6527 | augment | target-node | false | 6528 | base | name | false | 6529 | belongs-to | module | false | 6530 | bit | name | false | 6531 | case | name | false | 6532 | choice | name | false | 6533 | config | value | false | 6534 | contact | text | true | 6535 | container | name | false | 6536 | default | value | false | 6537 | description | text | true | 6538 | deviate | value | false | 6539 | deviation | target-node | false | 6540 | enum | name | false | 6541 | error-app-tag | value | false | 6542 | error-message | value | true | 6543 | extension | name | false | 6544 | feature | name | false | 6545 | fraction-digits | value | false | 6546 | grouping | name | false | 6547 | identity | name | false | 6548 | if-feature | name | false | 6549 | import | module | false | 6550 | include | module | false | 6551 | input | | n/a | 6552 | key | value | false | 6553 | leaf | name | false | 6554 | leaf-list | name | false | 6555 | length | value | false | 6556 | list | name | false | 6557 | mandatory | value | false | 6558 | max-elements | value | false | 6559 | min-elements | value | false | 6560 | module | name | false | 6561 | must | condition | false | 6562 | namespace | uri | false | 6563 | notification | name | false | 6564 | ordered-by | value | false | 6565 | organization | text | true | 6566 | output | | n/a | 6567 | path | value | false | 6568 | pattern | value | false | 6569 | position | value | false | 6570 | prefix | value | false | 6571 | presence | value | false | 6572 | range | value | false | 6573 | reference | text | true | 6574 | refine | target-node | false | 6575 | require-instance | value | false | 6576 | revision | date | false | 6577 | revision-date | date | false | 6578 | rpc | name | false | 6579 | status | value | false | 6580 | submodule | name | false | 6581 | type | name | false | 6582 | typedef | name | false | 6583 | unique | tag | false | 6584 | units | name | false | 6585 | uses | name | false | 6586 | value | value | false | 6587 | when | condition | false | 6588 | yang-version | value | false | 6589 | yin-element | value | false | 6590 +------------------+---------------+-------------+ 6592 Table 1: Mapping of arguments of the YANG statements. 6594 12.1.1. Usage Example 6596 The following YANG module: 6598 module acme-foo { 6599 yang-version 1.1; 6600 namespace "http://acme.example.com/foo"; 6601 prefix "acfoo"; 6603 import my-extensions { 6604 prefix "myext"; 6605 } 6607 list interface { 6608 key "name"; 6609 leaf name { 6610 type string; 6611 } 6613 leaf mtu { 6614 type uint32; 6615 description "The MTU of the interface."; 6616 myext:c-define "MY_MTU"; 6617 } 6618 } 6619 } 6621 where the extension "c-define" is defined in Section 7.17.3, is 6622 translated into the following YIN: 6624 6629 6630 6632 6633 6634 6636 6637 6638 6639 6640 6641 6642 6643 6644 The MTU of the interface. 6645 6646 6647 6648 6649 6651 13. YANG ABNF Grammar 6653 In YANG, almost all statements are unordered. The ABNF grammar 6654 [RFC5234] defines the canonical order. To improve module 6655 readability, it is RECOMMENDED that clauses be entered in this order. 6657 Within the ABNF grammar, unordered statements are marked with 6658 comments. 6660 This grammar assumes that the scanner replaces YANG comments with a 6661 single space character. 6663 file "yang.abnf" 6665 module-stmt = optsep module-keyword sep identifier-arg-str 6666 optsep 6667 "{" stmtsep 6668 module-header-stmts 6669 linkage-stmts 6670 meta-stmts 6671 revision-stmts 6672 body-stmts 6673 "}" optsep 6675 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 6676 optsep 6677 "{" stmtsep 6678 submodule-header-stmts 6679 linkage-stmts 6680 meta-stmts 6681 revision-stmts 6682 body-stmts 6683 "}" optsep 6685 module-header-stmts = ;; these stmts can appear in any order 6686 yang-version-stmt stmtsep 6687 namespace-stmt stmtsep 6688 prefix-stmt stmtsep 6690 submodule-header-stmts = 6691 ;; these stmts can appear in any order 6692 yang-version-stmt stmtsep 6693 belongs-to-stmt stmtsep 6695 meta-stmts = ;; these stmts can appear in any order 6696 [organization-stmt stmtsep] 6697 [contact-stmt stmtsep] 6698 [description-stmt stmtsep] 6699 [reference-stmt stmtsep] 6701 linkage-stmts = ;; these stmts can appear in any order 6702 *(import-stmt stmtsep) 6703 *(include-stmt stmtsep) 6705 revision-stmts = *(revision-stmt stmtsep) 6707 body-stmts = *((extension-stmt / 6708 feature-stmt / 6709 identity-stmt / 6710 typedef-stmt / 6711 grouping-stmt / 6712 data-def-stmt / 6713 augment-stmt / 6714 rpc-stmt / 6715 notification-stmt / 6716 deviation-stmt) stmtsep) 6718 data-def-stmt = container-stmt / 6719 leaf-stmt / 6720 leaf-list-stmt / 6721 list-stmt / 6722 choice-stmt / 6723 anyxml-stmt / 6724 uses-stmt 6726 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 6727 optsep stmtend 6729 yang-version-arg-str = < a string that matches the rule 6730 yang-version-arg > 6732 yang-version-arg = "1.1" 6734 import-stmt = import-keyword sep identifier-arg-str optsep 6735 "{" stmtsep 6736 prefix-stmt stmtsep 6737 [revision-date-stmt stmtsep] 6738 "}" 6740 include-stmt = include-keyword sep identifier-arg-str optsep 6741 (";" / 6742 "{" stmtsep 6743 [revision-date-stmt stmtsep] 6744 "}") 6746 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 6748 uri-str = < a string that matches the rule 6749 URI in RFC 3986 > 6751 prefix-stmt = prefix-keyword sep prefix-arg-str 6752 optsep stmtend 6754 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6755 optsep 6756 "{" stmtsep 6757 prefix-stmt stmtsep 6758 "}" 6760 organization-stmt = organization-keyword sep string 6761 optsep stmtend 6763 contact-stmt = contact-keyword sep string optsep stmtend 6765 description-stmt = description-keyword sep string optsep 6766 stmtend 6768 reference-stmt = reference-keyword sep string optsep stmtend 6770 units-stmt = units-keyword sep string optsep stmtend 6772 revision-stmt = revision-keyword sep revision-date optsep 6773 (";" / 6774 "{" stmtsep 6775 ;; these stmts can appear in any order 6776 [description-stmt stmtsep] 6777 [reference-stmt stmtsep] 6778 "}") 6780 revision-date = date-arg-str 6782 revision-date-stmt = revision-date-keyword sep revision-date stmtend 6784 extension-stmt = extension-keyword sep identifier-arg-str optsep 6785 (";" / 6786 "{" stmtsep 6787 ;; these stmts can appear in any order 6788 [argument-stmt stmtsep] 6789 [status-stmt stmtsep] 6790 [description-stmt stmtsep] 6791 [reference-stmt stmtsep] 6792 "}") 6794 argument-stmt = argument-keyword sep identifier-arg-str optsep 6795 (";" / 6796 "{" stmtsep 6797 [yin-element-stmt stmtsep] 6798 "}") 6800 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 6801 stmtend 6803 yin-element-arg-str = < a string that matches the rule 6804 yin-element-arg > 6806 yin-element-arg = true-keyword / false-keyword 6808 identity-stmt = identity-keyword sep identifier-arg-str optsep 6809 (";" / 6810 "{" stmtsep 6811 ;; these stmts can appear in any order 6812 [base-stmt stmtsep] 6813 [status-stmt stmtsep] 6814 [description-stmt stmtsep] 6815 [reference-stmt stmtsep] 6817 "}") 6819 base-stmt = base-keyword sep identifier-ref-arg-str 6820 optsep stmtend 6822 feature-stmt = feature-keyword sep identifier-arg-str optsep 6823 (";" / 6824 "{" stmtsep 6825 ;; these stmts can appear in any order 6826 *(if-feature-stmt stmtsep) 6827 [status-stmt stmtsep] 6828 [description-stmt stmtsep] 6829 [reference-stmt stmtsep] 6830 "}") 6832 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 6833 optsep stmtend 6835 if-feature-expr-str = < a string that matches the rule 6836 if-feature-expr > 6838 if-feature-expr = '(' if-fature-expr ')' / 6839 if-feature-expr sep boolean-operator sep 6840 if-feature-expr / 6841 'not' sep if-feature-expr / 6842 identifier-ref-arg 6844 boolean-operator = 'and' / 'or' 6846 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 6847 "{" stmtsep 6848 ;; these stmts can appear in any order 6849 type-stmt stmtsep 6850 [units-stmt stmtsep] 6851 [default-stmt stmtsep] 6852 [status-stmt stmtsep] 6853 [description-stmt stmtsep] 6854 [reference-stmt stmtsep] 6855 "}" 6857 type-stmt = type-keyword sep identifier-ref-arg-str optsep 6858 (";" / 6859 "{" stmtsep 6860 type-body-stmts 6861 "}") 6863 type-body-stmts = numerical-restrictions / 6864 decimal64-specification / 6865 string-restrictions / 6866 enum-specification / 6867 leafref-specification / 6868 identityref-specification / 6869 instance-identifier-specification / 6870 bits-specification / 6871 union-specification / 6872 binary-specification 6874 numerical-restrictions = range-stmt stmtsep 6876 range-stmt = range-keyword sep range-arg-str optsep 6877 (";" / 6878 "{" stmtsep 6879 ;; these stmts can appear in any order 6880 [error-message-stmt stmtsep] 6881 [error-app-tag-stmt stmtsep] 6882 [description-stmt stmtsep] 6883 [reference-stmt stmtsep] 6884 "}") 6886 decimal64-specification = ;; these stmts can appear in any order 6887 fraction-digits-stmt 6888 [range-stmt stmtsep] 6890 fraction-digits-stmt = fraction-digits-keyword sep 6891 fraction-digits-arg-str stmtend 6893 fraction-digits-arg-str = < a string that matches the rule 6894 fraction-digits-arg > 6896 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 6897 "5" / "6" / "7" / "8"]) 6898 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 6900 string-restrictions = ;; these stmts can appear in any order 6901 [length-stmt stmtsep] 6902 *(pattern-stmt stmtsep) 6904 length-stmt = length-keyword sep length-arg-str optsep 6905 (";" / 6906 "{" stmtsep 6907 ;; these stmts can appear in any order 6908 [error-message-stmt stmtsep] 6909 [error-app-tag-stmt stmtsep] 6910 [description-stmt stmtsep] 6911 [reference-stmt stmtsep] 6912 "}") 6914 pattern-stmt = pattern-keyword sep string optsep 6915 (";" / 6916 "{" stmtsep 6917 ;; these stmts can appear in any order 6918 [modifier-stmt stmtsep] 6919 [error-message-stmt stmtsep] 6920 [error-app-tag-stmt stmtsep] 6921 [description-stmt stmtsep] 6922 [reference-stmt stmtsep] 6923 "}") 6925 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 6927 modifier-arg-str = < a string that matches the rule 6928 modifier-arg > 6930 modifier-arg = invert-match-keyword 6932 default-stmt = default-keyword sep string stmtend 6934 enum-specification = 1*(enum-stmt stmtsep) 6936 enum-stmt = enum-keyword sep string optsep 6937 (";" / 6938 "{" stmtsep 6939 ;; these stmts can appear in any order 6940 [value-stmt stmtsep] 6941 [status-stmt stmtsep] 6942 [description-stmt stmtsep] 6943 [reference-stmt stmtsep] 6944 "}") 6946 leafref-specification = 6947 ;; these stmts can appear in any order 6948 path-stmt stmtsep 6949 [require-instance-stmt stmtsep] 6951 path-stmt = path-keyword sep path-arg-str stmtend 6953 require-instance-stmt = require-instance-keyword sep 6954 require-instance-arg-str stmtend 6956 require-instance-arg-str = < a string that matches the rule 6957 require-instance-arg > 6959 require-instance-arg = true-keyword / false-keyword 6960 instance-identifier-specification = 6961 [require-instance-stmt stmtsep] 6963 identityref-specification = 6964 base-stmt stmtsep 6966 union-specification = 1*(type-stmt stmtsep) 6968 binary-specification = [length-stmt stmtsep] 6970 bits-specification = 1*(bit-stmt stmtsep) 6972 bit-stmt = bit-keyword sep identifier-arg-str optsep 6973 (";" / 6974 "{" stmtsep 6975 ;; these stmts can appear in any order 6976 [position-stmt stmtsep] 6977 [status-stmt stmtsep] 6978 [description-stmt stmtsep] 6979 [reference-stmt stmtsep] 6980 "}") 6982 position-stmt = position-keyword sep 6983 position-value-arg-str stmtend 6985 position-value-arg-str = < a string that matches the rule 6986 position-value-arg > 6988 position-value-arg = non-negative-integer-value 6990 status-stmt = status-keyword sep status-arg-str stmtend 6992 status-arg-str = < a string that matches the rule 6993 status-arg > 6995 status-arg = current-keyword / 6996 obsolete-keyword / 6997 deprecated-keyword 6999 config-stmt = config-keyword sep 7000 config-arg-str stmtend 7002 config-arg-str = < a string that matches the rule 7003 config-arg > 7005 config-arg = true-keyword / false-keyword 7007 mandatory-stmt = mandatory-keyword sep 7008 mandatory-arg-str stmtend 7010 mandatory-arg-str = < a string that matches the rule 7011 mandatory-arg > 7013 mandatory-arg = true-keyword / false-keyword 7015 presence-stmt = presence-keyword sep string stmtend 7017 ordered-by-stmt = ordered-by-keyword sep 7018 ordered-by-arg-str stmtend 7020 ordered-by-arg-str = < a string that matches the rule 7021 ordered-by-arg > 7023 ordered-by-arg = user-keyword / system-keyword 7025 must-stmt = must-keyword sep string optsep 7026 (";" / 7027 "{" stmtsep 7028 ;; these stmts can appear in any order 7029 [error-message-stmt stmtsep] 7030 [error-app-tag-stmt stmtsep] 7031 [description-stmt stmtsep] 7032 [reference-stmt stmtsep] 7033 "}") 7035 error-message-stmt = error-message-keyword sep string stmtend 7037 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 7039 min-elements-stmt = min-elements-keyword sep 7040 min-value-arg-str stmtend 7042 min-value-arg-str = < a string that matches the rule 7043 min-value-arg > 7045 min-value-arg = non-negative-integer-value 7047 max-elements-stmt = max-elements-keyword sep 7048 max-value-arg-str stmtend 7050 max-value-arg-str = < a string that matches the rule 7051 max-value-arg > 7053 max-value-arg = unbounded-keyword / 7054 positive-integer-value 7056 value-stmt = value-keyword sep integer-value-str stmtend 7058 integer-value-str = < a string that matches the rule 7059 integer-value > 7061 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 7062 (";" / 7063 "{" stmtsep 7064 ;; these stmts can appear in any order 7065 [status-stmt stmtsep] 7066 [description-stmt stmtsep] 7067 [reference-stmt stmtsep] 7068 *((typedef-stmt / 7069 grouping-stmt) stmtsep) 7070 *(data-def-stmt stmtsep) 7071 "}") 7073 container-stmt = container-keyword sep identifier-arg-str optsep 7074 (";" / 7075 "{" stmtsep 7076 ;; these stmts can appear in any order 7077 [when-stmt stmtsep] 7078 *(if-feature-stmt stmtsep) 7079 *(must-stmt stmtsep) 7080 [presence-stmt stmtsep] 7081 [config-stmt stmtsep] 7082 [status-stmt stmtsep] 7083 [description-stmt stmtsep] 7084 [reference-stmt stmtsep] 7085 *((typedef-stmt / 7086 grouping-stmt) stmtsep) 7087 *(data-def-stmt stmtsep) 7088 "}") 7090 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 7091 "{" stmtsep 7092 ;; these stmts can appear in any order 7093 [when-stmt stmtsep] 7094 *(if-feature-stmt stmtsep) 7095 type-stmt stmtsep 7096 [units-stmt stmtsep] 7097 *(must-stmt stmtsep) 7098 [default-stmt stmtsep] 7099 [config-stmt stmtsep] 7100 [mandatory-stmt stmtsep] 7101 [status-stmt stmtsep] 7102 [description-stmt stmtsep] 7103 [reference-stmt stmtsep] 7105 "}" 7107 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 7108 "{" stmtsep 7109 ;; these stmts can appear in any order 7110 [when-stmt stmtsep] 7111 *(if-feature-stmt stmtsep) 7112 type-stmt stmtsep 7113 [units-stmt stmtsep] 7114 *(must-stmt stmtsep) 7115 [config-stmt stmtsep] 7116 [min-elements-stmt stmtsep] 7117 [max-elements-stmt stmtsep] 7118 [ordered-by-stmt stmtsep] 7119 [status-stmt stmtsep] 7120 [description-stmt stmtsep] 7121 [reference-stmt stmtsep] 7122 "}" 7124 list-stmt = list-keyword sep identifier-arg-str optsep 7125 "{" stmtsep 7126 ;; these stmts can appear in any order 7127 [when-stmt stmtsep] 7128 *(if-feature-stmt stmtsep) 7129 *(must-stmt stmtsep) 7130 [key-stmt stmtsep] 7131 *(unique-stmt stmtsep) 7132 [config-stmt stmtsep] 7133 [min-elements-stmt stmtsep] 7134 [max-elements-stmt stmtsep] 7135 [ordered-by-stmt stmtsep] 7136 [status-stmt stmtsep] 7137 [description-stmt stmtsep] 7138 [reference-stmt stmtsep] 7139 *((typedef-stmt / 7140 grouping-stmt) stmtsep) 7141 1*(data-def-stmt stmtsep) 7142 "}" 7144 key-stmt = key-keyword sep key-arg-str stmtend 7146 key-arg-str = < a string that matches the rule 7147 key-arg > 7149 key-arg = node-identifier *(sep node-identifier) 7151 unique-stmt = unique-keyword sep unique-arg-str stmtend 7152 unique-arg-str = < a string that matches the rule 7153 unique-arg > 7155 unique-arg = descendant-schema-nodeid 7156 *(sep descendant-schema-nodeid) 7158 choice-stmt = choice-keyword sep identifier-arg-str optsep 7159 (";" / 7160 "{" stmtsep 7161 ;; these stmts can appear in any order 7162 [when-stmt stmtsep] 7163 *(if-feature-stmt stmtsep) 7164 [default-stmt stmtsep] 7165 [config-stmt stmtsep] 7166 [mandatory-stmt stmtsep] 7167 [status-stmt stmtsep] 7168 [description-stmt stmtsep] 7169 [reference-stmt stmtsep] 7170 *((short-case-stmt / case-stmt) stmtsep) 7171 "}") 7173 short-case-stmt = choice-stmt / 7174 container-stmt / 7175 leaf-stmt / 7176 leaf-list-stmt / 7177 list-stmt / 7178 anyxml-stmt 7180 case-stmt = case-keyword sep identifier-arg-str optsep 7181 (";" / 7182 "{" stmtsep 7183 ;; these stmts can appear in any order 7184 [when-stmt stmtsep] 7185 *(if-feature-stmt stmtsep) 7186 [status-stmt stmtsep] 7187 [description-stmt stmtsep] 7188 [reference-stmt stmtsep] 7189 *(data-def-stmt stmtsep) 7190 "}") 7192 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 7193 (";" / 7194 "{" stmtsep 7195 ;; these stmts can appear in any order 7196 [when-stmt stmtsep] 7197 *(if-feature-stmt stmtsep) 7198 *(must-stmt stmtsep) 7199 [config-stmt stmtsep] 7201 [mandatory-stmt stmtsep] 7202 [status-stmt stmtsep] 7203 [description-stmt stmtsep] 7204 [reference-stmt stmtsep] 7205 "}") 7207 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 7208 (";" / 7209 "{" stmtsep 7210 ;; these stmts can appear in any order 7211 [when-stmt stmtsep] 7212 *(if-feature-stmt stmtsep) 7213 [status-stmt stmtsep] 7214 [description-stmt stmtsep] 7215 [reference-stmt stmtsep] 7216 *(refine-stmt stmtsep) 7217 *(uses-augment-stmt stmtsep) 7218 "}") 7220 refine-stmt = refine-keyword sep refine-arg-str optsep 7221 "{" stmtsep 7222 ;; these stmts can appear in any order 7223 *(if-feature-stmt stmtsep) 7224 *(must-stmt stmtsep) 7225 [presence-stmt stmtsep] 7226 [default-stmt stmtsep] 7227 [config-stmt stmtsep] 7228 [mandatory-stmt stmtsep] 7229 [min-elements-stmt stmtsep] 7230 [max-elements-stmt stmtsep] 7231 [description-stmt stmtsep] 7232 [reference-stmt stmtsep] 7233 "}" 7235 refine-arg-str = < a string that matches the rule 7236 refine-arg > 7238 refine-arg = descendant-schema-nodeid 7240 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 7241 "{" stmtsep 7242 ;; these stmts can appear in any order 7243 [when-stmt stmtsep] 7244 *(if-feature-stmt stmtsep) 7245 [status-stmt stmtsep] 7246 [description-stmt stmtsep] 7247 [reference-stmt stmtsep] 7248 1*((data-def-stmt stmtsep) / 7249 (case-stmt stmtsep)) 7250 "}" 7252 uses-augment-arg-str = < a string that matches the rule 7253 uses-augment-arg > 7255 uses-augment-arg = descendant-schema-nodeid 7257 augment-stmt = augment-keyword sep augment-arg-str optsep 7258 "{" stmtsep 7259 ;; these stmts can appear in any order 7260 [when-stmt stmtsep] 7261 *(if-feature-stmt stmtsep) 7262 [status-stmt stmtsep] 7263 [description-stmt stmtsep] 7264 [reference-stmt stmtsep] 7265 1*((data-def-stmt stmtsep) / 7266 (case-stmt stmtsep)) 7267 "}" 7269 augment-arg-str = < a string that matches the rule 7270 augment-arg > 7272 augment-arg = absolute-schema-nodeid 7274 when-stmt = when-keyword sep string optsep 7275 (";" / 7276 "{" stmtsep 7277 ;; these stmts can appear in any order 7278 [description-stmt stmtsep] 7279 [reference-stmt stmtsep] 7280 "}") 7282 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 7283 (";" / 7284 "{" stmtsep 7285 ;; these stmts can appear in any order 7286 *(if-feature-stmt stmtsep) 7287 [status-stmt stmtsep] 7288 [description-stmt stmtsep] 7289 [reference-stmt stmtsep] 7290 *((typedef-stmt / 7291 grouping-stmt) stmtsep) 7292 [input-stmt stmtsep] 7293 [output-stmt stmtsep] 7294 "}") 7296 input-stmt = input-keyword optsep 7297 "{" stmtsep 7298 ;; these stmts can appear in any order 7299 *((typedef-stmt / 7300 grouping-stmt) stmtsep) 7301 1*(data-def-stmt stmtsep) 7302 "}" 7304 output-stmt = output-keyword optsep 7305 "{" stmtsep 7306 ;; these stmts can appear in any order 7307 *((typedef-stmt / 7308 grouping-stmt) stmtsep) 7309 1*(data-def-stmt stmtsep) 7310 "}" 7312 notification-stmt = notification-keyword sep 7313 identifier-arg-str optsep 7314 (";" / 7315 "{" stmtsep 7316 ;; these stmts can appear in any order 7317 *(if-feature-stmt stmtsep) 7318 [status-stmt stmtsep] 7319 [description-stmt stmtsep] 7320 [reference-stmt stmtsep] 7321 *((typedef-stmt / 7322 grouping-stmt) stmtsep) 7323 *(data-def-stmt stmtsep) 7324 "}") 7326 deviation-stmt = deviation-keyword sep 7327 deviation-arg-str optsep 7328 "{" stmtsep 7329 ;; these stmts can appear in any order 7330 [description-stmt stmtsep] 7331 [reference-stmt stmtsep] 7332 (deviate-not-supported-stmt / 7333 1*(deviate-add-stmt / 7334 deviate-replace-stmt / 7335 deviate-delete-stmt)) 7336 "}" 7338 deviation-arg-str = < a string that matches the rule 7339 deviation-arg > 7341 deviation-arg = absolute-schema-nodeid 7343 deviate-not-supported-stmt = 7344 deviate-keyword sep 7345 not-supported-keyword-str optsep 7346 (";" / 7347 "{" stmtsep 7348 "}") 7350 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 7351 (";" / 7352 "{" stmtsep 7353 ;; these stmts can appear in any order 7354 [units-stmt stmtsep] 7355 *(must-stmt stmtsep) 7356 *(unique-stmt stmtsep) 7357 [default-stmt stmtsep] 7358 [config-stmt stmtsep] 7359 [mandatory-stmt stmtsep] 7360 [min-elements-stmt stmtsep] 7361 [max-elements-stmt stmtsep] 7362 "}") 7364 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 7365 (";" / 7366 "{" stmtsep 7367 ;; these stmts can appear in any order 7368 [units-stmt stmtsep] 7369 *(must-stmt stmtsep) 7370 *(unique-stmt stmtsep) 7371 [default-stmt stmtsep] 7372 "}") 7374 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 7375 (";" / 7376 "{" stmtsep 7377 ;; these stmts can appear in any order 7378 [type-stmt stmtsep] 7379 [units-stmt stmtsep] 7380 [default-stmt stmtsep] 7381 [config-stmt stmtsep] 7382 [mandatory-stmt stmtsep] 7383 [min-elements-stmt stmtsep] 7384 [max-elements-stmt stmtsep] 7385 "}") 7387 not-supported-keyword-str = < a string that matches the rule 7388 not-supported-keyword> 7390 add-keyword-str = < a string that matches the rule 7391 add-keyword> 7393 delete-keyword-str = < a string that matches the rule 7394 delete-keyword> 7396 replace-keyword-str = < a string that matches the rule 7397 replace-keyword> 7399 unknown-statement = prefix ":" identifier [sep string] optsep 7400 (";" / "{" *(yang-stmt stmtsep) "}") 7402 yang-stmt = (anyxml-stmt / 7403 argument-stmt / 7404 augment-stmt / 7405 base-stmt / 7406 belongs-to-stmt / 7407 bit-stmt / 7408 case-stmt / 7409 choice-stmt / 7410 config-stmt / 7411 contact-stmt / 7412 container-stmt / 7413 default-stmt / 7414 description-stmt / 7415 deviate-add-stmt / 7416 deviate-delete-stmt / 7417 deviate-not-supported-stmt / 7418 deviate-replace-stmt / 7419 deviation-stmt / 7420 enum-stmt / 7421 error-app-tag-stmt / 7422 error-message-stmt / 7423 extension-stmt / 7424 feature-stmt / 7425 fraction-digits-stmt / 7426 grouping-stmt / 7427 identity-stmt / 7428 if-feature-stmt / 7429 import-stmt / 7430 include-stmt / 7431 input-stmt / 7432 key-stmt / 7433 leaf-list-stmt / 7434 leaf-stmt / 7435 length-stmt / 7436 list-stmt / 7437 mandatory-stmt / 7438 max-elements-stmt / 7439 min-elements-stmt / 7440 module-stmt / 7441 must-stmt / 7442 namespace-stmt / 7443 notification-stmt / 7444 ordered-by-stmt / 7445 organization-stmt / 7446 output-stmt / 7447 path-stmt / 7448 pattern-stmt / 7449 position-stmt / 7450 prefix-stmt / 7451 presence-stmt / 7452 range-stmt / 7453 reference-stmt / 7454 refine-stmt / 7455 require-instance-stmt / 7456 revision-date-stmt / 7457 revision-stmt / 7458 rpc-stmt / 7459 status-stmt / 7460 submodule-stmt / 7461 typedef-stmt / 7462 type-stmt / 7463 unique-stmt / 7464 units-stmt / 7465 uses-augment-stmt / 7466 uses-stmt / 7467 value-stmt / 7468 when-stmt / 7469 yang-version-stmt / 7470 yin-element-stmt) 7472 ;; Ranges 7474 range-arg-str = < a string that matches the rule 7475 range-arg > 7477 range-arg = range-part *(optsep "|" optsep range-part) 7479 range-part = range-boundary 7480 [optsep ".." optsep range-boundary] 7482 range-boundary = min-keyword / max-keyword / 7483 integer-value / decimal-value 7485 ;; Lengths 7487 length-arg-str = < a string that matches the rule 7488 length-arg > 7490 length-arg = length-part *(optsep "|" optsep length-part) 7492 length-part = length-boundary 7493 [optsep ".." optsep length-boundary] 7495 length-boundary = min-keyword / max-keyword / 7496 non-negative-integer-value 7498 ;; Date 7500 date-arg-str = < a string that matches the rule 7501 date-arg > 7503 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 7505 ;; Schema Node Identifiers 7507 schema-nodeid = absolute-schema-nodeid / 7508 descendant-schema-nodeid 7510 absolute-schema-nodeid = 1*("/" node-identifier) 7512 descendant-schema-nodeid = 7513 node-identifier 7514 [absolute-schema-nodeid] 7516 node-identifier = [prefix ":"] identifier 7518 ;; Instance Identifiers 7520 instance-identifier = 1*("/" (node-identifier *predicate)) 7522 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 7524 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 7525 ((DQUOTE string DQUOTE) / 7526 (SQUOTE string SQUOTE)) 7528 pos = non-negative-integer-value 7530 ;; leafref path 7532 path-arg-str = < a string that matches the rule 7533 path-arg > 7535 path-arg = absolute-path / relative-path 7536 absolute-path = 1*("/" (node-identifier *path-predicate)) 7538 relative-path = 1*(".." "/") descendant-path 7540 descendant-path = node-identifier 7541 [*path-predicate absolute-path] 7543 path-predicate = "[" *WSP path-equality-expr *WSP "]" 7545 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 7547 path-key-expr = current-function-invocation *WSP "/" *WSP 7548 rel-path-keyexpr 7550 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 7551 *(node-identifier *WSP "/" *WSP) 7552 node-identifier 7554 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 7556 ;; statement keywords 7557 anyxml-keyword = 'anyxml' 7558 argument-keyword = 'argument' 7559 augment-keyword = 'augment' 7560 base-keyword = 'base' 7561 belongs-to-keyword = 'belongs-to' 7562 bit-keyword = 'bit' 7563 case-keyword = 'case' 7564 choice-keyword = 'choice' 7565 config-keyword = 'config' 7566 contact-keyword = 'contact' 7567 container-keyword = 'container' 7568 default-keyword = 'default' 7569 description-keyword = 'description' 7570 enum-keyword = 'enum' 7571 error-app-tag-keyword = 'error-app-tag' 7572 error-message-keyword = 'error-message' 7573 extension-keyword = 'extension' 7574 deviation-keyword = 'deviation' 7575 deviate-keyword = 'deviate' 7576 feature-keyword = 'feature' 7577 fraction-digits-keyword = 'fraction-digits' 7578 grouping-keyword = 'grouping' 7579 identity-keyword = 'identity' 7580 if-feature-keyword = 'if-feature' 7581 import-keyword = 'import' 7582 include-keyword = 'include' 7583 input-keyword = 'input' 7584 key-keyword = 'key' 7585 leaf-keyword = 'leaf' 7586 leaf-list-keyword = 'leaf-list' 7587 length-keyword = 'length' 7588 list-keyword = 'list' 7589 mandatory-keyword = 'mandatory' 7590 max-elements-keyword = 'max-elements' 7591 min-elements-keyword = 'min-elements' 7592 modifier-keyword = 'modifier' 7593 module-keyword = 'module' 7594 must-keyword = 'must' 7595 namespace-keyword = 'namespace' 7596 notification-keyword= 'notification' 7597 ordered-by-keyword = 'ordered-by' 7598 organization-keyword= 'organization' 7599 output-keyword = 'output' 7600 path-keyword = 'path' 7601 pattern-keyword = 'pattern' 7602 position-keyword = 'position' 7603 prefix-keyword = 'prefix' 7604 presence-keyword = 'presence' 7605 range-keyword = 'range' 7606 reference-keyword = 'reference' 7607 refine-keyword = 'refine' 7608 require-instance-keyword = 'require-instance' 7609 revision-keyword = 'revision' 7610 revision-date-keyword = 'revision-date' 7611 rpc-keyword = 'rpc' 7612 status-keyword = 'status' 7613 submodule-keyword = 'submodule' 7614 type-keyword = 'type' 7615 typedef-keyword = 'typedef' 7616 unique-keyword = 'unique' 7617 units-keyword = 'units' 7618 uses-keyword = 'uses' 7619 value-keyword = 'value' 7620 when-keyword = 'when' 7621 yang-version-keyword= 'yang-version' 7622 yin-element-keyword = 'yin-element' 7624 ;; other keywords 7626 add-keyword = 'add' 7627 current-keyword = 'current' 7628 delete-keyword = 'delete' 7629 deprecated-keyword = 'deprecated' 7630 false-keyword = 'false' 7631 invert-match-keyword = 'invert-match' 7632 max-keyword = 'max' 7633 min-keyword = 'min' 7634 not-supported-keyword = 'not-supported' 7635 obsolete-keyword = 'obsolete' 7636 replace-keyword = 'replace' 7637 system-keyword = 'system' 7638 true-keyword = 'true' 7639 unbounded-keyword = 'unbounded' 7640 user-keyword = 'user' 7642 current-function-invocation = current-keyword *WSP "(" *WSP ")" 7644 ;; Basic Rules 7646 prefix-arg-str = < a string that matches the rule 7647 prefix-arg > 7649 prefix-arg = prefix 7651 prefix = identifier 7653 identifier-arg-str = < a string that matches the rule 7654 identifier-arg > 7656 identifier-arg = identifier 7658 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 7659 identifier = (ALPHA / "_") 7660 *(ALPHA / DIGIT / "_" / "-" / ".") 7662 identifier-ref-arg-str = < a string that matches the rule 7663 identifier-ref-arg > 7665 identifier-ref-arg = [prefix ":"] identifier 7667 string = < an unquoted string as returned by 7668 the scanner > 7670 integer-value = ("-" non-negative-integer-value) / 7671 non-negative-integer-value 7673 non-negative-integer-value = "0" / positive-integer-value 7675 positive-integer-value = (non-zero-digit *DIGIT) 7677 zero-integer-value = 1*DIGIT 7679 stmtend = ";" / "{" *unknown-statement "}" 7680 sep = 1*(WSP / line-break) 7681 ; unconditional separator 7683 optsep = *(WSP / line-break) 7685 stmtsep = *(WSP / line-break / unknown-statement) 7687 line-break = CRLF / LF 7689 non-zero-digit = %x31-39 7691 decimal-value = integer-value ("." zero-integer-value) 7693 SQUOTE = %x27 7694 ; ' (Single Quote) 7696 ;; 7697 ;; RFC 5234 core rules. 7698 ;; 7700 ALPHA = %x41-5A / %x61-7A 7701 ; A-Z / a-z 7703 CR = %x0D 7704 ; carriage return 7706 CRLF = CR LF 7707 ; Internet standard new line 7709 DIGIT = %x30-39 7710 ; 0-9 7712 DQUOTE = %x22 7713 ; double quote 7715 HEXDIG = DIGIT / 7716 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 7717 ; only lower-case a..f 7719 HTAB = %x09 7720 ; horizontal tab 7722 LF = %x0A 7723 ; linefeed 7725 SP = %x20 7726 ; space 7728 VCHAR = %x21-7E 7729 ; visible (printing) characters 7731 WSP = SP / HTAB 7732 ; whitespace 7734 7736 14. Error Responses for YANG Related Errors 7738 A number of NETCONF error responses are defined for error cases 7739 related to the data-model handling. If the relevant YANG statement 7740 has an "error-app-tag" substatement, that overrides the default value 7741 specified below. 7743 14.1. Error Message for Data That Violates a unique Statement 7745 If a NETCONF operation would result in configuration data where a 7746 unique constraint is invalidated, the following error is returned: 7748 error-tag: operation-failed 7749 error-app-tag: data-not-unique 7750 error-info: : Contains an instance identifier that 7751 points to a leaf that invalidates the unique 7752 constraint. This element is present once for each 7753 non-unique leaf. 7755 The element is in the YANG 7756 namespace ("urn:ietf:params:xml:ns:yang:1"). 7758 14.2. Error Message for Data That Violates a max-elements Statement 7760 If a NETCONF operation would result in configuration data where a 7761 list or a leaf-list would have too many entries the following error 7762 is returned: 7764 error-tag: operation-failed 7765 error-app-tag: too-many-elements 7767 This error is returned once, with the error-path identifying the list 7768 node, even if there are more than one extra child present. 7770 14.3. Error Message for Data That Violates a min-elements Statement 7772 If a NETCONF operation would result in configuration data where a 7773 list or a leaf-list would have too few entries the following error is 7774 returned: 7776 error-tag: operation-failed 7777 error-app-tag: too-few-elements 7779 This error is returned once, with the error-path identifying the list 7780 node, even if there are more than one child missing. 7782 14.4. Error Message for Data That Violates a must Statement 7784 If a NETCONF operation would result in configuration data where the 7785 restrictions imposed by a "must" statement is violated the following 7786 error is returned, unless a specific "error-app-tag" substatement is 7787 present for the "must" statement. 7789 error-tag: operation-failed 7790 error-app-tag: must-violation 7792 14.5. Error Message for Data That Violates a require-instance Statement 7794 If a NETCONF operation would result in configuration data where a 7795 leaf of type "instance-identifier" marked with require-instance 7796 "true" refers to a non-existing instance, the following error is 7797 returned: 7799 error-tag: data-missing 7800 error-app-tag: instance-required 7801 error-path: Path to the instance-identifier leaf. 7803 14.6. Error Message for Data That Does Not Match a leafref Type 7805 If a NETCONF operation would result in configuration data where a 7806 leaf of type "leafref" refers to a non-existing instance, the 7807 following error is returned: 7809 error-tag: data-missing 7810 error-app-tag: instance-required 7811 error-path: Path to the leafref leaf. 7813 14.7. Error Message for Data That Violates a mandatory choice Statement 7815 If a NETCONF operation would result in configuration data where no 7816 nodes exists in a mandatory choice, the following error is returned: 7818 error-tag: data-missing 7819 error-app-tag: missing-choice 7820 error-path: Path to the element with the missing choice. 7821 error-info: : Contains the name of the missing 7822 mandatory choice. 7824 The element is in the YANG 7825 namespace ("urn:ietf:params:xml:ns:yang:1"). 7827 14.8. Error Message for the "insert" Operation 7829 If the "insert" and "key" or "value" attributes are used in an 7830 for a list or leaf-list node, and the "key" or "value" 7831 refers to a non-existing instance, the following error is returned: 7833 error-tag: bad-attribute 7834 error-app-tag: missing-instance 7836 15. IANA Considerations 7838 This document defines a registry for YANG module and submodule names. 7839 The name of the registry is "YANG Module Names". 7841 The registry shall record for each entry: 7843 o the name of the module or submodule 7845 o for modules, the assigned XML namespace 7847 o for modules, the prefix of the module 7849 o for submodules, the name of the module it belongs to 7851 o a reference to the (sub)module's documentation (e.g., the RFC 7852 number) 7854 There are no initial assignments. 7856 For allocation, RFC publication is required as per RFC 5226 7857 [RFC5226]. All registered YANG module names MUST comply with the 7858 rules for identifiers stated in Section 6.2, and MUST have a module 7859 name prefix. 7861 The module name prefix 'ietf-' is reserved for IETF stream documents 7862 [RFC4844], while the module name prefix 'irtf-' is reserved for IRTF 7863 stream documents. Modules published in other RFC streams MUST have a 7864 similar suitable prefix. 7866 All module and submodule names in the registry MUST be unique. 7868 All XML namespaces in the registry MUST be unique. 7870 This document registers two URIs for the YANG and YIN XML namespaces 7871 in the IETF XML registry [RFC3688]. Following the format in RFC 7872 3688, the following have been registered. 7874 URI: urn:ietf:params:xml:ns:yang:yin:1 7875 URI: urn:ietf:params:xml:ns:yang:1 7877 Registrant Contact: The IESG. 7879 XML: N/A, the requested URIs are XML namespaces. 7881 This document registers two new media types as defined in the 7882 following sections. 7884 15.1. Media type application/yang 7885 MIME media type name: application 7887 MIME subtype name: yang 7889 Mandatory parameters: none 7891 Optional parameters: none 7893 Encoding considerations: 8-bit 7895 Security considerations: See Section 15 in RFC XXXX 7897 Interoperability considerations: None 7899 Published specification: RFC XXXX 7901 Applications that use this media type: 7903 YANG module validators, web servers used for downloading YANG 7904 modules, email clients, etc. 7906 Additional information: 7908 Magic Number: None 7910 File Extension: .yang 7912 Macintosh file type code: 'TEXT' 7914 Personal and email address for further information: 7915 Martin Bjorklund 7917 Intended usage: COMMON 7919 Author: 7920 This specification is a work item of the IETF NETMOD working 7921 group, with mailing list address . 7923 Change controller: 7924 The IESG 7926 15.2. Media type application/yin+xml 7927 MIME media type name: application 7929 MIME subtype name: yin+xml 7931 Mandatory parameters: none 7933 Optional parameters: 7935 "charset": This parameter has identical semantics to the 7936 charset parameter of the "application/xml" media type as 7937 specified in [RFC3023]. 7939 Encoding considerations: 7941 Identical to those of "application/xml" as 7942 described in [RFC3023], Section 3.2. 7944 Security considerations: See Section 15 in RFC XXXX 7946 Interoperability considerations: None 7948 Published specification: RFC XXXX 7950 Applications that use this media type: 7952 YANG module validators, web servers used for downloading YANG 7953 modules, email clients, etc. 7955 Additional information: 7957 Magic Number: As specified for "application/xml" in [RFC3023], 7958 Section 3.2. 7960 File Extension: .yin 7962 Macintosh file type code: 'TEXT' 7964 Personal and email address for further information: 7965 Martin Bjorklund 7967 Intended usage: COMMON 7969 Author: 7970 This specification is a work item of the IETF NETMOD working 7971 group, with mailing list address . 7973 Change controller: 7974 The IESG 7976 16. Security Considerations 7978 This document defines a language with which to write and read 7979 descriptions of management information. The language itself has no 7980 security impact on the Internet. 7982 The same considerations are relevant as for the base NETCONF protocol 7983 (see [RFC6241], Section 9). 7985 Data modeled in YANG might contain sensitive information. RPCs or 7986 notifications defined in YANG might transfer sensitive information. 7988 Security issues are related to the usage of data modeled in YANG. 7989 Such issues shall be dealt with in documents describing the data 7990 models and documents about the interfaces used to manipulate the data 7991 e.g., the NETCONF documents. 7993 Data modeled in YANG is dependent upon: 7995 o the security of the transmission infrastructure used to send 7996 sensitive information. 7998 o the security of applications that store or release such sensitive 7999 information. 8001 o adequate authentication and access control mechanisms to restrict 8002 the usage of sensitive data. 8004 YANG parsers need to be robust with respect to malformed documents. 8005 Reading malformed documents from unknown or untrusted sources could 8006 result in an attacker gaining privileges of the user running the YANG 8007 parser. In an extreme situation, the entire machine could be 8008 compromised. 8010 17. Contributors 8012 The following people all contributed significantly to the initial 8013 YANG document: 8015 - Andy Bierman (Brocade) 8016 - Balazs Lengyel (Ericsson) 8017 - David Partain (Ericsson) 8018 - Juergen Schoenwaelder (Jacobs University Bremen) 8019 - Phil Shafer (Juniper Networks) 8021 18. Acknowledgements 8023 The editor wishes to thank the following individuals, who all 8024 provided helpful comments on various versions of this document: 8025 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 8026 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 8027 Wijnen. 8029 19. ChangeLog 8031 RFC Editor: remove this section upon publication as an RFC. 8033 19.1. Version -01 8035 o Included solution Y01-01. 8037 o Included solution Y03-01. 8039 o Included solution Y06-02. 8041 o Included solution Y07-01. 8043 o Included solution Y14-01. 8045 o Included solution Y20-01. 8047 o Included solution Y23-01. 8049 o Included solution Y29-01. 8051 o Included solution Y30-01. 8053 o Included solution Y31-01. 8055 o Included solution Y35-01. 8057 19.2. Version -00 8059 o Applied all reported errata for RFC 6020. 8061 o Updated YANG version to 1.1, and made the "yang-version" statement 8062 mandatory. 8064 20. References 8065 20.1. Normative References 8067 [ISO.10646] 8068 International Organization for Standardization, 8069 "Information Technology - Universal Multiple-Octet Coded 8070 Character Set (UCS)", ISO Standard 10646:2003, 2003. 8072 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8073 Requirement Levels", BCP 14, RFC 2119, March 1997. 8075 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 8076 Types", RFC 3023, January 2001. 8078 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 8079 10646", STD 63, RFC 3629, November 2003. 8081 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 8082 January 2004. 8084 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8085 Resource Identifier (URI): Generic Syntax", STD 66, RFC 8086 3986, January 2005. 8088 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8089 Encodings", RFC 4648, October 2006. 8091 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 8092 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 8093 May 2008. 8095 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 8096 Specifications: ABNF", STD 68, RFC 5234, January 2008. 8098 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 8099 Notifications", RFC 5277, July 2008. 8101 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 8102 Bierman, "Network Configuration Protocol (NETCONF)", RFC 8103 6241, June 2011. 8105 [XML-NAMES] 8106 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 8107 Layman, "Namespaces in XML 1.0 (Third Edition)", World 8108 Wide Web Consortium Recommendation REC-xml-names-20091208, 8109 December 2009, 8110 . 8112 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 8113 Version 1.0", World Wide Web Consortium Recommendation 8114 REC-xpath-19991116, November 1999, 8115 . 8117 [XSD-TYPES] 8118 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 8119 Second Edition", World Wide Web Consortium Recommendation 8120 REC-xmlschema-2-20041028, October 2004, 8121 . 8123 20.2. Informative References 8125 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8126 Schoenwaelder, Ed., "Structure of Management Information 8127 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 8129 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8130 Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 8131 58, RFC 2579, April 1999. 8133 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 8134 Structure of Management Information", RFC 3780, May 2004. 8136 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 8137 Series and RFC Editor", RFC 4844, July 2007. 8139 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 8140 Network Configuration Protocol (NETCONF)", RFC 6020, 8141 October 2010. 8143 [XPATH2.0] 8144 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 8145 Kay, M., Robie, J., and J. Simeon, "XML Path Language 8146 (XPath) 2.0", World Wide Web Consortium Recommendation 8147 REC-xpath20-20070123, January 2007, 8148 . 8150 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 8151 Wide Web Consortium Recommendation REC-xslt-19991116, 8152 November 1999, 8153 . 8155 Author's Address 8156 Martin Bjorklund (editor) 8157 Tail-f Systems 8159 Email: mbj@tail-f.com