idnits 2.17.1 draft-ietf-netmod-yang-12.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 contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, 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 (April 14, 2010) is 5119 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 5906 ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** 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 (~~), 2 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track April 14, 2010 5 Expires: October 16, 2010 7 YANG - A data modeling language for NETCONF 8 draft-ietf-netmod-yang-12 10 Abstract 12 YANG is a data modeling language used to model configuration and 13 state data manipulated by the Network Configuration Protocol 14 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 15 notifications. 17 Status of this Memo 19 This Internet-Draft is submitted to IETF in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on October 16, 2010. 40 Copyright Notice 42 Copyright (c) 2010 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 This document may contain material from IETF Documents or IETF 56 Contributions published or made publicly available before November 57 10, 2008. The person(s) controlling the copyright in some of this 58 material may not have granted the IETF Trust the right to allow 59 modifications of such material outside the IETF Standards Process. 60 Without obtaining an adequate license from the person(s) controlling 61 the copyright in such materials, this document may not be modified 62 outside the IETF Standards Process, and derivative works of it may 63 not be created outside the IETF Standards Process, except to format 64 it for publication as an RFC or to translate it into languages other 65 than English. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 70 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 13 73 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 14 75 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 76 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 77 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 78 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 79 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 20 80 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 81 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 82 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 83 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 84 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 25 85 4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 86 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 87 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 88 5.1.1. Import and Include by Revision . . . . . . . . . . . 29 89 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 90 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 91 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 92 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 93 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 94 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 95 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 96 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 97 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 98 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 99 5.6.4. Announcing Conformance Information in the 100 Message . . . . . . . . . . . . . . . . . . . . . . . 34 101 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 36 102 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 37 103 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 37 104 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 37 105 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 37 106 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 37 107 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 39 108 6.2.1. Identifiers and their namespaces . . . . . . . . . . 39 109 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 40 110 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 40 111 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 40 112 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 41 113 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 41 114 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 43 115 7.1. The module Statement . . . . . . . . . . . . . . . . . . 43 116 7.1.1. The module's Substatements . . . . . . . . . . . . . 44 117 7.1.2. The yang-version Statement . . . . . . . . . . . . . 45 118 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 45 119 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 46 120 7.1.5. The import Statement . . . . . . . . . . . . . . . . 46 121 7.1.6. The include Statement . . . . . . . . . . . . . . . . 47 122 7.1.7. The organization Statement . . . . . . . . . . . . . 48 123 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 48 124 7.1.9. The revision Statement . . . . . . . . . . . . . . . 48 125 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 49 126 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 49 127 7.2.1. The submodule's Substatements . . . . . . . . . . . . 50 128 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 51 129 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 52 130 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 52 131 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 53 132 7.3.2. The typedef's type Statement . . . . . . . . . . . . 53 133 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 53 134 7.3.4. The typedef's default Statement . . . . . . . . . . . 53 135 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 54 136 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 54 137 7.4.1. The type's Substatements . . . . . . . . . . . . . . 54 138 7.5. The container Statement . . . . . . . . . . . . . . . . . 54 139 7.5.1. Containers with Presence . . . . . . . . . . . . . . 55 140 7.5.2. The container's Substatements . . . . . . . . . . . . 56 141 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 56 142 7.5.4. The must's Substatements . . . . . . . . . . . . . . 58 143 7.5.5. The presence Statement . . . . . . . . . . . . . . . 59 144 7.5.6. The container's Child Node Statements . . . . . . . . 59 145 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 59 146 7.5.8. NETCONF Operations . . . . . . . . . . 59 147 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 60 148 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 61 149 7.6.1. The leaf's default value . . . . . . . . . . . . . . 61 150 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 62 151 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 62 152 7.6.4. The leaf's default Statement . . . . . . . . . . . . 62 153 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 63 154 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 63 155 7.6.7. NETCONF Operations . . . . . . . . . . 63 156 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 64 157 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 65 158 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 65 159 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 66 160 7.7.3. The min-elements Statement . . . . . . . . . . . . . 66 161 7.7.4. The max-elements Statement . . . . . . . . . . . . . 66 162 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 67 163 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 67 164 7.7.7. NETCONF Operations . . . . . . . . . . 68 165 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 69 166 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 70 167 7.8.1. The list's Substatements . . . . . . . . . . . . . . 71 168 7.8.2. The list's key Statement . . . . . . . . . . . . . . 71 169 7.8.3. The list's unique Statement . . . . . . . . . . . . . 72 170 7.8.4. The list's Child Node Statements . . . . . . . . . . 73 171 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 73 172 7.8.6. NETCONF Operations . . . . . . . . . . 74 173 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 75 174 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 78 175 7.9.1. The choice's Substatements . . . . . . . . . . . . . 79 176 7.9.2. The choice's case Statement . . . . . . . . . . . . . 79 177 7.9.3. The choice's default Statement . . . . . . . . . . . 80 178 7.9.4. The choice's mandatory Statement . . . . . . . . . . 82 179 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 180 7.9.6. NETCONF Operations . . . . . . . . . . 82 181 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 82 182 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 83 183 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 84 184 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 84 185 7.10.3. NETCONF Operations . . . . . . . . . . 84 186 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 187 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 85 188 7.11.1. The grouping's Substatements . . . . . . . . . . . . 86 189 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 87 190 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 87 191 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 88 192 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 88 193 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 89 194 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 89 195 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 90 196 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 91 197 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 91 198 7.13.3. The output Statement . . . . . . . . . . . . . . . . 92 199 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 200 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 93 201 7.14. The notification Statement . . . . . . . . . . . . . . . 94 202 7.14.1. The notification's Substatements . . . . . . . . . . 95 203 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 95 204 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 205 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 96 206 7.15.1. The augment's Substatements . . . . . . . . . . . . . 97 207 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 97 208 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 97 209 7.16. The identity Statement . . . . . . . . . . . . . . . . . 99 210 7.16.1. The identity's Substatements . . . . . . . . . . . . 100 211 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 100 212 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 213 7.17. The extension Statement . . . . . . . . . . . . . . . . . 101 214 7.17.1. The extension's Substatements . . . . . . . . . . . . 102 215 7.17.2. The argument Statement . . . . . . . . . . . . . . . 102 216 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 217 7.18. Conformance-related Statements . . . . . . . . . . . . . 103 218 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 103 219 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 105 220 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 105 221 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 108 222 7.19.1. The config Statement . . . . . . . . . . . . . . . . 108 223 7.19.2. The status Statement . . . . . . . . . . . . . . . . 108 224 7.19.3. The description Statement . . . . . . . . . . . . . . 109 225 7.19.4. The reference Statement . . . . . . . . . . . . . . . 109 226 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 109 227 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 111 228 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 111 229 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 111 230 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 111 231 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 112 232 8.3.2. NETCONF Processing . . . . . . . . . . 112 233 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 113 234 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 114 235 9.1. Canonical representation . . . . . . . . . . . . . . . . 114 236 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 114 237 9.2.1. Lexicographic Representation . . . . . . . . . . . . 115 238 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 239 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 240 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 116 241 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 242 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 117 243 9.3.1. Lexicographic Representation . . . . . . . . . . . . 117 244 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 245 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 246 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 118 247 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 248 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 119 249 9.4.1. Lexicographic Representation . . . . . . . . . . . . 119 250 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 251 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 252 9.4.4. The length Statement . . . . . . . . . . . . . . . . 119 253 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 254 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 121 255 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 121 256 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 122 257 9.5.1. Lexicographic Representation . . . . . . . . . . . . 122 258 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 259 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 260 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 122 261 9.6.1. Lexicographic Representation . . . . . . . . . . . . 122 262 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 263 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 264 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 122 265 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 266 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 124 267 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 268 9.7.2. Lexicographic Representation . . . . . . . . . . . . 124 269 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 124 270 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 124 271 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 125 272 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 125 273 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126 274 9.8.2. Lexicographic Representation . . . . . . . . . . . . 126 275 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 126 276 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 126 277 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126 278 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 126 279 9.9.3. Lexicographic Representation . . . . . . . . . . . . 127 280 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 127 281 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 127 282 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 131 283 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 284 9.10.2. The identityref's base Statement . . . . . . . . . . 131 285 9.10.3. Lexicographic Representation . . . . . . . . . . . . 132 286 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 132 287 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 132 288 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 133 289 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 133 290 9.11.2. Lexicographic Representation . . . . . . . . . . . . 133 291 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 133 292 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 133 293 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 134 294 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 295 9.12.2. Lexicographic Representation . . . . . . . . . . . . 134 296 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 297 9.13. The instance-identifier Built-in Type . . . . . . . . . . 135 298 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 299 9.13.2. The require-instance Statement . . . . . . . . . . . 136 300 9.13.3. Lexicographic Representation . . . . . . . . . . . . 136 301 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 136 302 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 303 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 138 304 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 305 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 141 306 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 143 308 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 146 309 13. Error Responses for YANG Related Errors . . . . . . . . . . . 168 310 13.1. Error Message for Data that Violates a unique Statement . 168 311 13.2. Error Message for Data that Violates a max-elements 312 Statement . . . . . . . . . . . . . . . . . . . . . . . . 168 313 13.3. Error Message for Data that Violates a min-elements 314 Statement . . . . . . . . . . . . . . . . . . . . . . . . 168 315 13.4. Error Message for Data that Violates a must Statement . . 169 316 13.5. Error Message for Data that Violates a 317 require-instance Statement . . . . . . . . . . . . . . . 169 318 13.6. Error Message for Data that does not Match a leafref 319 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 169 320 13.7. Error Message for Data that Violates a mandatory 321 choice Statement . . . . . . . . . . . . . . . . . . . . 169 322 13.8. Error Message for the "insert" Operation . . . . . . . . 170 323 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 171 324 15. Security Considerations . . . . . . . . . . . . . . . . . . . 172 325 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 173 326 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 174 327 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 175 328 18.1. Normative References . . . . . . . . . . . . . . . . . . 175 329 18.2. Non-Normative References . . . . . . . . . . . . . . . . 176 330 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 177 331 A.1. Version -12 . . . . . . . . . . . . . . . . . . . . . . . 177 332 A.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 177 333 A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 177 334 A.4. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 177 335 A.5. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 178 336 A.6. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 178 337 A.7. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 178 338 A.8. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 178 339 A.9. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 179 340 A.10. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 179 341 A.11. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 180 342 A.12. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 180 343 A.13. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 181 344 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 182 346 1. Introduction 348 YANG is a data modeling language used to model configuration and 349 state data manipulated by the Network Configuration Protocol 350 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 351 notifications. YANG is used to model the operations and content 352 layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], 353 section 1.1). 355 This document describes the syntax and semantics of the YANG 356 language, how the data model defined in a YANG module is represented 357 in XML, and how NETCONF operations are used to manipulate the data. 359 2. Key Words 361 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 362 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 363 "OPTIONAL" in this document are to be interpreted as described in BCP 364 14, [RFC2119]. 366 3. Terminology 368 o anyxml: A data node which can contain an unknown chunk of XML 369 data. 371 o augment: Adds new schema nodes to a previously defined schema 372 node. 374 o base type: The type from which a derived type was derived, which 375 may be either a built-in type or another derived type. 377 o built-in type: A YANG data type defined in the YANG language, such 378 as uint32 or string. 380 o choice: A schema node where only one of a number of identified 381 alternatives is valid. 383 o configuration data: The set of writable data that is required to 384 transform a system from its initial default state into its current 385 state [RFC4741]. 387 o conformance: A measure of how accurately a device follows a data 388 model. 390 o container: An interior data node which exists in at most one 391 instance in the data tree. A container has no value, but rather a 392 set of child nodes. 394 o data definition statement: A statement that defines new data 395 nodes. One of container, leaf, leaf-list, list, choice, case, 396 augment, uses, and anyxml. 398 o data model: A data model describes how data is represented and 399 accessed. 401 o data node: A node in the schema tree that can be instantiated in a 402 data tree. One of container, leaf, leaf-list, list, and anyxml. 404 o data tree: The instantiated tree of configuration and state data 405 on a device. 407 o derived type: A type which is derived from a built-in type (such 408 as uint32), or another derived type. 410 o device deviation: A failure of the device to implement the module 411 faithfully. 413 o extension: An extension attaches non-YANG semantics to statements. 414 The extension statement defines new statements to express these 415 semantics. 417 o feature: A mechanism for marking a portion of the model as 418 optional. Definitions can be tagged with a feature name and are 419 only valid on devices which support that feature. 421 o grouping: A reusable set of schema nodes, which may be used 422 locally in the module, in modules which include it, and by other 423 modules which import from it. The grouping statement is not a 424 data definition statement and, as such, does not define any nodes 425 in the schema tree. 427 o identifier: Used to identify different kinds of YANG items by 428 name. 430 o instance identifier: A mechanism for identifying a particular node 431 in a data tree. 433 o interior node: Nodes within a hierarchy that are not leaf nodes. 435 o leaf: A data node which exists in at most one instance in the data 436 tree. A leaf has a value but no child nodes. 438 o leaf-list: Like the leaf node but defines a set of uniquely 439 identifiable nodes rather than a single node. Each node has a 440 value but no child nodes. 442 o list: An interior data node which may exist in multiple instances 443 in the data tree. A list has no value, but rather a set of child 444 nodes. 446 o module: A YANG module defines a hierarchy of nodes which can be 447 used for NETCONF-based operations. With its definitions and the 448 definitions it imports or includes from elsewhere, a module is 449 self-contained and "compilable". 451 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 453 o RPC operation: A specific Remote Procedure Call, as used within 454 the NETCONF protocol. Also called a protocol operation. 456 o schema node: A node in the schema tree. One of container, leaf, 457 leaf-list, list, choice, case, rpc, input, output, notification, 458 and anyxml. 460 o schema node identifier: A mechanism for identifying a particular 461 node in the schema tree. 463 o schema tree: The definition hierarchy specified within a module. 465 o state data: The additional data on a system that is not 466 configuration data such as read-only status information and 467 collected statistics [RFC4741]. 469 o submodule: A partial module definition which contributes derived 470 types, groupings, data nodes, RPCs, and notifications to a module. 471 A YANG module can be constructed from a number of submodules. 473 o top-level data node: A data node where there is no other data node 474 between it and a module or submodule statement. 476 o uses: The "uses" statement is used to instantiate the set of 477 schema nodes defined in a grouping statement. The instantiated 478 nodes may be refined and augmented to tailor them to any specific 479 needs. 481 3.1. Mandatory nodes 483 A mandatory node is one of: 485 o A leaf, choice, or anyxml node with a "mandatory" statement with 486 the value "true". 488 o A list or leaf-list node with a "min-elements" statement with a 489 value greater than zero. 491 o A container node without a "presence" statement, which has at 492 least one mandatory node as a child. 494 4. YANG Overview 496 4.1. Functional Overview 498 YANG is a language used to model data for the NETCONF protocol. A 499 YANG module defines a hierarchy of data which can be used for 500 NETCONF-based operations, including configuration, state data, remote 501 procedure calls (RPCs), and notifications. This allows a complete 502 description of all data sent between a NETCONF client and server. 504 YANG models the hierarchical organization of data as a tree in which 505 each node has a name, and either a value or a set of child nodes. 506 YANG provides clear and concise descriptions of the nodes, as well as 507 the interaction between those nodes. 509 YANG structures data models into modules and submodules. A module 510 can import data from other external modules, and include data from 511 submodules. The hierarchy can be augmented, allowing one module to 512 add data nodes to the hierarchy defined in another module. This 513 augmentation can be conditional, with new nodes appearing only if 514 certain conditions are met. 516 YANG models can describe constraints to be enforced on the data, 517 restricting the appearance or value of nodes based on the presence or 518 value of other nodes in the hierarchy. These constraints are 519 enforceable by either the client or the server, and valid content 520 must abide by them. 522 YANG defines a set of built-in types, and has a type mechanism 523 through which additional types may be defined. Derived types can 524 restrict their base type's set of valid values using mechanisms like 525 range or pattern restrictions that can be enforced by clients or 526 servers. They can also define usage conventions for use of the 527 derived type, such as a string-based type that contains a host name. 529 YANG permits the definition of reusable grouping of nodes. The 530 instantiation of these groupings can refine or augment the nodes, 531 allowing it to tailor the nodes to its particular needs. Derived 532 types and groupings can be defined in one module or submodule and 533 used in either that location or in another module or submodule that 534 imports or includes it. 536 YANG data hierarchy constructs include defining lists where list 537 entries are identified by keys which distinguish them from each 538 other. Such lists may be defined as either sorted by user or 539 automatically sorted by the system. For user-sorted lists, 540 operations are defined for manipulating the order of the list 541 entries. 543 YANG modules can be translated into an equivalent XML syntax called 544 YANG Independent Notation (YIN) (Section 11), allowing applications 545 using XML parsers and XSLT scripts to operate on the models. The 546 conversion from YANG to YIN is loss-less, so content in YIN can be 547 round-tripped back into YANG. 549 YANG strikes a balance between high-level data modeling and low-level 550 bits-on-the-wire encoding. The reader of a YANG module can see the 551 high-level view of the data model while understanding how the data 552 will be encoded in NETCONF operations. 554 YANG is an extensible language, allowing extension statements to be 555 defined by standards bodies, vendors, and individuals. The statement 556 syntax allows these extensions to coexist with standard YANG 557 statements in a natural way, while extensions in a YANG module stand 558 out sufficiently for the reader to notice them. 560 YANG resists the tendency to solve all possible problems, limiting 561 the problem space to allow expression of NETCONF data models, not 562 arbitrary XML documents or arbitrary data models. The data models 563 described by YANG are designed to be easily operated upon by NETCONF 564 operations. 566 To the extent possible, YANG maintains compatibility with SNMP's 567 SMIv2 (Structure of Management Information version 2 [RFC2578], 568 [RFC2579]). SMIv2-based MIB modules can be automatically translated 569 into YANG modules for read-only access. However, YANG is not 570 concerned with reverse translation from YANG to SMIv2. 572 Like NETCONF, YANG targets smooth integration with the device's 573 native management infrastructure. This allows implementations to 574 leverage their existing access control mechanisms to protect or 575 expose elements of the data model. 577 4.2. Language Overview 579 This section introduces some important constructs used in YANG that 580 will aid in the understanding of the language specifics in later 581 sections. This progressive approach handles the inter-related nature 582 of YANG concepts and statements. A detailed description of YANG 583 statements and syntax begins in Section 7. 585 4.2.1. Modules and Submodules 587 A module contains three types of statements: module-header 588 statements, revision statements, and definition statements. The 589 module header statements describe the module and give information 590 about the module itself, the revision statements give information 591 about the history of the module, and the definition statements are 592 the body of the module where the data model is defined. 594 A NETCONF server may implement a number of modules, allowing multiple 595 views of the same data, or multiple views of disjoint subsections of 596 the device's data. Alternatively, the server may implement only one 597 module that defines all available data. 599 A module may be divided into submodules, based on the needs of the 600 module owner. The external view remains that of a single module, 601 regardless of the presence or size of its submodules. 603 The "include" statement allows a module or submodule to reference 604 material in submodules, and the "import" statement allows references 605 to material defined in other modules. 607 4.2.2. Data Modeling Basics 609 YANG defines four types of nodes for data modeling. In each of the 610 following subsections, the example shows the YANG syntax as well as a 611 corresponding NETCONF XML representation. 613 4.2.2.1. Leaf Nodes 615 A leaf node contains simple data like an integer or a string. It has 616 exactly one value of a particular type, and no child nodes. 618 YANG Example: 620 leaf host-name { 621 type string; 622 description "Hostname for this system"; 623 } 625 NETCONF XML Example: 627 my.example.com 629 The "leaf" statement is covered in Section 7.6. 631 4.2.2.2. Leaf-list Nodes 633 A leaf-list is a sequence of leaf nodes with exactly one value of a 634 particular type per leaf. 636 YANG Example: 638 leaf-list domain-search { 639 type string; 640 description "List of domain names to search"; 641 } 643 NETCONF XML Example: 645 high.example.com 646 low.example.com 647 everywhere.example.com 649 The "leaf-list" statement is covered in Section 7.7. 651 4.2.2.3. Container Nodes 653 A container node is used to group related nodes in a subtree. A 654 container has only child nodes and no value. A container may contain 655 any number of child nodes of any type (including leafs, lists, 656 containers, and leaf-lists). 658 YANG Example: 660 container system { 661 container login { 662 leaf message { 663 type string; 664 description 665 "Message given at start of login session"; 666 } 667 } 668 } 670 NETCONF XML Example: 672 673 674 Good morning 675 676 678 The "container" statement is covered in Section 7.5. 680 4.2.2.4. List Nodes 682 A list defines a sequence of list entries. Each entry is like a 683 structure or a record instance, and is uniquely identified by the 684 values of its key leafs. A list can define multiple key leafs and 685 may contain any number of child nodes of any type (including leafs, 686 lists, containers etc.). 688 YANG Example: 690 list user { 691 key "name"; 692 leaf name { 693 type string; 694 } 695 leaf full-name { 696 type string; 697 } 698 leaf class { 699 type string; 700 } 701 } 703 NETCONF XML Example: 705 706 glocks 707 Goldie Locks 708 intruder 709 710 711 snowey 712 Snow White 713 free-loader 714 715 716 rzell 717 Rapun Zell 718 tower 719 721 The "list" statement is covered in Section 7.8. 723 4.2.2.5. Example Module 725 These statements are combined to define the module: 727 // Contents of "acme-system.yang" 728 module acme-system { 729 namespace "http://acme.example.com/system"; 730 prefix "acme"; 732 organization "ACME Inc."; 733 contact "joe@acme.example.com"; 734 description 735 "The module for entities implementing the ACME system."; 737 revision 2007-06-09 { 738 description "Initial revision."; 739 } 741 container system { 742 leaf host-name { 743 type string; 744 description "Hostname for this system"; 745 } 747 leaf-list domain-search { 748 type string; 749 description "List of domain names to search"; 750 } 752 container login { 753 leaf message { 754 type string; 755 description 756 "Message given at start of login session"; 757 } 759 list user { 760 key "name"; 761 leaf name { 762 type string; 763 } 764 leaf full-name { 765 type string; 766 } 767 leaf class { 768 type string; 769 } 770 } 771 } 772 } 773 } 775 4.2.3. State Data 777 YANG can model state data, as well as configuration data, based on 778 the "config" statement. When a node is tagged with "config false", 779 its subhierarchy is flagged as state data, to be reported using 780 NETCONF's operation, not the operation. Parent 781 containers, lists, and key leafs are reported also, giving the 782 context for the state data. 784 In this example, two leafs are defined for each interface, a 785 configured speed and an observed speed. The observed speed is not 786 configuration, so it can be returned with NETCONF operations, 787 but not with operations. The observed speed is not 788 configuration data, and cannot be manipulated using . 790 list interface { 791 key "name"; 793 leaf name { 794 type string; 795 } 796 leaf speed { 797 type enumeration { 798 enum 10m; 799 enum 100m; 800 enum auto; 801 } 802 } 803 leaf observed-speed { 804 type uint32; 805 config false; 806 } 807 } 809 4.2.4. Built-in Types 811 YANG has a set of built-in types, similar to those of many 812 programming languages, but with some differences due to special 813 requirements from the management domain. The following table 814 summarizes the built-in types discussed in Section 9: 816 +---------------------+-------------------------------------+ 817 | Name | Description | 818 +---------------------+-------------------------------------+ 819 | binary | Any binary data | 820 | bits | A set of bits or flags | 821 | boolean | "true" or "false" | 822 | decimal64 | 64-bit signed decimal number | 823 | empty | A leaf that does not have any value | 824 | enumeration | Enumerated strings | 825 | identityref | A reference to an abstract identity | 826 | instance-identifier | References a data tree node | 827 | int8 | 8-bit signed integer | 828 | int16 | 16-bit signed integer | 829 | int32 | 32-bit signed integer | 830 | int64 | 64-bit signed integer | 831 | leafref | A reference to a leaf instance | 832 | string | Human readable string | 833 | uint8 | 8-bit unsigned integer | 834 | uint16 | 16-bit unsigned integer | 835 | uint32 | 32-bit unsigned integer | 836 | uint64 | 64-bit unsigned integer | 837 | union | Choice of member types | 838 +---------------------+-------------------------------------+ 840 The "type" statement is covered in Section 7.4. 842 4.2.5. Derived Types (typedef) 844 YANG can define derived types from base types using the "typedef" 845 statement. A base type can be either a built-in type or a derived 846 type, allowing a hierarchy of derived types. 848 A derived type can be used as the argument for the "type" statement. 850 YANG Example: 852 typedef percent { 853 type uint8 { 854 range "0 .. 100"; 855 } 856 description "Percentage"; 857 } 859 leaf completed { 860 type percent; 861 } 863 NETCONF XML Example: 865 20 867 The "typedef" statement is covered in Section 7.3. 869 4.2.6. Reusable Node Groups (grouping) 871 Groups of nodes can be assembled into reusable collections using the 872 "grouping" statement. A grouping defines a set of nodes that are 873 instantiated with the "uses" statement: 875 grouping target { 876 leaf address { 877 type inet:ip-address; 878 description "Target IP address"; 879 } 880 leaf port { 881 type inet:port-number; 882 description "Target port number"; 883 } 884 } 886 container peer { 887 container destination { 888 uses target; 889 } 890 } 892 NETCONF XML Example: 894 895 896
192.0.2.1
897 830 898 899 901 The grouping can be refined as it is used, allowing certain 902 statements to be overridden. In this example, the description is 903 refined: 905 container connection { 906 container source { 907 uses target { 908 refine "address" { 909 description "Source IP address"; 910 } 911 refine "port" { 912 description "Source port number"; 913 } 914 } 915 } 916 container destination { 917 uses target { 918 refine "address" { 919 description "Destination IP address"; 920 } 921 refine "port" { 922 description "Destination port number"; 923 } 924 } 925 } 926 } 928 The "grouping" statement is covered in Section 7.11. 930 4.2.7. Choices 932 YANG allows the data model to segregate incompatible nodes into 933 distinct choices using the "choice" and "case" statements. The 934 "choice" statement contains a set of "case" statements which define 935 sets of schema nodes that cannot appear together. Each "case" may 936 contain multiple nodes, but each node may appear in only one "case" 937 under a "choice". 939 When an element from one case is created, all elements from all other 940 cases are implicitly deleted. The device handles the enforcement of 941 the constraint, preventing incompatibilities from existing in the 942 configuration. 944 The choice and case nodes appear only in the schema tree, not in the 945 data tree or NETCONF PDUs. The additional levels of hierarchy are 946 not needed beyond the conceptual schema. 948 YANG Example: 950 container food { 951 choice snack { 952 case sports-arena { 953 leaf pretzel { 954 type empty; 955 } 956 leaf beer { 957 type empty; 958 } 959 } 960 case late-night { 961 leaf chocolate { 962 type enumeration { 963 enum dark; 964 enum milk; 965 enum first-available; 966 } 967 } 968 } 969 } 970 } 972 NETCONF XML Example: 974 975 976 977 979 The "choice" statement is covered in Section 7.9. 981 4.2.8. Extending Data Models (augment) 983 YANG allows a module to insert additional nodes into data models, 984 including both the current module (and its submodules) or an external 985 module. This is useful for example for vendors to add vendor- 986 specific parameters to standard data models in an interoperable way. 988 The "augment" statement defines the location in the data model 989 hierarchy where new nodes are inserted, and the "when" statement 990 defines the conditions when the new nodes are valid. 992 YANG Example: 994 augment /system/login/user { 995 when "class != 'wheel'"; 996 leaf uid { 997 type uint16 { 998 range "1000 .. 30000"; 999 } 1000 } 1001 } 1003 This example defines a "uid" node that only is valid when the user's 1004 "class" is not "wheel". 1006 If a module augments another module, the XML representation of the 1007 data will reflect the prefix of the augmenting module. For example, 1008 if the above augmentation were in a module with prefix "other", the 1009 XML would look like: 1011 NETCONF XML Example: 1013 1014 alicew 1015 Alice N. Wonderland 1016 drop-out 1017 1024 1018 1020 The "augment" statement is covered in Section 7.15. 1022 4.2.9. RPC Definitions 1024 YANG allows the definition of NETCONF RPCs. The operation names, 1025 input parameters and output parameters are modeled using YANG data 1026 definition statements. 1028 YANG Example: 1030 rpc activate-software-image { 1031 input { 1032 leaf image-name { 1033 type string; 1034 } 1035 } 1036 output { 1037 leaf status { 1038 type string; 1039 } 1040 } 1041 } 1043 NETCONF XML Example: 1045 1047 1048 acmefw-2.3 1049 1050 1052 1054 1055 The image acmefw-2.3 is being installed. 1056 1057 1059 The "rpc" statement is covered in Section 7.13. 1061 4.2.10. Notification Definitions 1063 YANG allows the definition of notifications suitable for NETCONF. 1064 YANG data definition statements are used to model the content of the 1065 notification. 1067 YANG Example: 1069 notification link-failure { 1070 description "A link failure has been detected"; 1071 leaf if-name { 1072 type leafref { 1073 path "/interface/name"; 1074 } 1075 } 1076 leaf if-admin-status { 1077 type admin-status; 1078 } 1079 leaf if-oper-status { 1080 type oper-status; 1081 } 1082 } 1084 NETCONF XML Example: 1086 1088 2007-09-01T10:00:00Z 1089 1090 so-1/2/3.0 1091 up 1092 down 1093 1094 1096 The "notification" statement is covered in Section 7.14. 1098 5. Language Concepts 1100 5.1. Modules and Submodules 1102 The module is the base unit of definition in YANG. A module defines 1103 a single data model. A module can define a complete, cohesive model, 1104 or augment an existing data model with additional nodes. 1106 Submodules are partial modules that contribute definitions to a 1107 module. A module may include any number of submodules, but each 1108 submodule may belong to only one module. 1110 The names of all standard modules and submodules MUST be unique. 1111 Developers of enterprise modules are RECOMMENDED to choose names for 1112 their modules that will have a low probability of colliding with 1113 standard or other enterprise modules, e.g., by using the enterprise 1114 or organization name as a prefix for the module name. 1116 A module uses the "include" statement to include its submodules, and 1117 the "import" statement to reference external modules. Similarly, a 1118 submodule uses the "import" statement to reference other modules, and 1119 uses the "include" statement to reference other submodules within its 1120 module. A module or submodule MUST NOT include submodules from other 1121 modules, and a submodule MUST NOT import its own module. 1123 The import and include statements are used to make definitions 1124 available to other modules and submodules: 1126 o For a module or submodule to reference definitions in an external 1127 module, the external module MUST be imported. 1129 o For a module to reference definitions in one of its submodules, 1130 the module MUST include the submodule. 1132 o For a submodule to reference definitions in a second submodule of 1133 the same module, the first submodule MUST include the second 1134 submodule. 1136 There MUST NOT be any circular chains of imports or includes. For 1137 example, if submodule "a" includes submodule "b", "b" cannot include 1138 "a". 1140 When a definition in an external module is referenced, a locally 1141 defined prefix MUST be used, followed by ":", and then the external 1142 identifier. References to definitions in the local module MAY use 1143 the prefix notation. Since built-in data types do not belong to any 1144 module and have no prefix, references to built-in data types (e.g., 1145 int32) cannot use the prefix notation. 1147 5.1.1. Import and Include by Revision 1149 Published modules evolve independently over time. In order to allow 1150 for this evolution, modules need to be imported using specific 1151 revisions. When a module is written, it uses the current revisions 1152 of other modules, based on what is available at the time. As future 1153 revisions of the imported modules are published, the importing module 1154 is unaffected and its contents are unchanged. When the author of the 1155 module is prepared to move to the most recently published revision of 1156 an imported module, the module is republished with an updated import 1157 statement. By republishing with the new revision, the authors 1158 explicitly indicate their acceptance of any changes in the imported 1159 module. 1161 For submodules, the issue is related but simpler. A module or 1162 submodule that includes submodules need to specify the revision of 1163 the included submodules. If a submodule changes, any module or 1164 submodule that includes it needs to be updated. 1166 For example, module "b" imports module "a". 1168 module a { 1169 revision 2008-01-01 { ... } 1170 grouping a { 1171 leaf eh { .... } 1172 } 1173 } 1175 module b { 1176 import a { 1177 prefix p; 1178 revision-date 2008-01-01; 1179 } 1181 container bee { 1182 uses p:a; 1183 } 1184 } 1186 When the author of "a" publishes a new revision, the changes may not 1187 be acceptable to the author of "b". If the new revision is 1188 acceptable, the author of "b" can republish with an updated revision 1189 in the import statement. 1191 5.1.2. Module Hierarchies 1193 YANG allows modeling of data in multiple hierarchies, where data may 1194 have more than one top-level node. Models that have multiple top- 1195 level nodes are sometimes convenient, and are supported by YANG. 1197 NETCONF is capable of carrying any XML content as the payload in the 1198 and elements. The top-level nodes of YANG modules 1199 are encoded as child elements, in any order, within these elements. 1200 This encapsulation guarantees that the corresponding NETCONF PDUs are 1201 always well-formed XML documents. 1203 For example: 1205 module my-config { 1206 namespace "http://example.com/schema/config"; 1207 prefix "co"; 1209 container system { ... } 1210 container routing { ... } 1211 } 1213 could be encoded in NETCONF as: 1215 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1233 5.2. File Layout 1235 YANG modules and submodules are typically stored in files, one module 1236 or submodule per file. The name of the file SHOULD be of the form: 1238 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1240 YANG compilers can find imported modules and included submodules via 1241 this convention. While the YANG language defines modules, tools may 1242 compile submodules independently for performance and manageability 1243 reasons. Errors and warnings that cannot be detected during 1244 submodule compilation may be delayed until the submodules are linked 1245 into a cohesive module. 1247 5.3. XML Namespaces 1249 All YANG definitions are specified within a module that is bound to a 1250 particular XML Namespace [XML-NAMES], which is a globally unique URI 1251 [RFC3986]. A NETCONF client or server uses the namespace during XML 1252 encoding of data. 1254 Namespaces for modules published in RFC streams [RFC4844] MUST be 1255 assigned by IANA, see Section 14. 1257 Namespaces for private modules are assigned by the organization 1258 owning the module without a central registry. Namespace URIs MUST be 1259 chosen so they cannot collide with standard or other enterprise 1260 namespaces, for example by using the enterprise or organization name 1261 in the namespace. 1263 The "namespace" statement is covered in Section 7.1.3. 1265 5.3.1. YANG XML Namespace 1267 YANG defines an XML namespace for NETCONF operations 1268 and content. The name of this namespace is 1269 "urn:ietf:params:xml:ns:yang:1". 1271 5.4. Resolving Grouping, Type, and Identity Names 1273 Grouping, type, and identity names are resolved in the context in 1274 which they are defined, rather than the context in which they are 1275 used. Users of groupings, typedefs, and identities are not required 1276 to import modules or include submodules to satisfy all references 1277 made by the original definition. This behaves like static scoping in 1278 a conventional programming language. 1280 For example, if a module defines a grouping in which a type is 1281 referenced, when the grouping is used in a second module, the type is 1282 resolved in the context of the original module, not the second 1283 module. There is no worry over conflicts if both modules define the 1284 type, since there is no ambiguity. 1286 5.5. Nested Typedefs and Groupings 1288 Typedefs and groupings may appear nested under many YANG statements, 1289 allowing these to be lexically scoped by the hierarchy under which 1290 they appear. This allows types and groupings to be defined near 1291 where they are used, rather than placing them at the top level of the 1292 hierarchy. The close proximity increases readability. 1294 Scoping also allows types to be defined without concern for naming 1295 conflicts between types in different submodules. Type names can be 1296 specified without adding leading strings designed to prevent name 1297 collisions within large modules. 1299 Finally, scoping allows the module author to keep types and groupings 1300 private to their module or submodule, preventing their reuse. Since 1301 only top-level types and groupings (i.e., those appearing as 1302 substatements to a module or submodule statement) can be used outside 1303 the module or submodule, the developer has more control over what 1304 pieces of their module are presented to the outside world, supporting 1305 the need to hide internal information and maintaining a boundary 1306 between what is shared with the outside world and what is kept 1307 private. 1309 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1310 type or grouping cannot be defined if a higher level in the schema 1311 hierarchy has a definition with a matching identifier. 1313 A reference to an unprefixed type or grouping, or one which uses the 1314 prefix of the current module, is resolved by locating the closest 1315 matching "typedef" or "grouping" statement among the immediate 1316 substatements of each ancestor statement. 1318 5.6. Conformance 1320 Conformance is a measure of how accurately a device follows the 1321 model. Generally speaking, devices are responsible for implementing 1322 the model faithfully, allowing applications to treat devices which 1323 implement the model identically. Deviations from the model can 1324 reduce the utility of the model and increase fragility of 1325 applications that use it. 1327 YANG modelers have three mechanisms for conformance: 1329 o the basic behavior of the model 1331 o optional features that are part of the model 1333 o deviations from the model 1335 We will consider each of these in sequence. 1337 5.6.1. Basic Behavior 1339 The model defines a contract between the NETCONF client and server, 1340 which allows both parties to have faith the other knows the syntax 1341 and semantics behind the modeled data. The strength of YANG lies in 1342 the strength of this contract. 1344 5.6.2. Optional Features 1346 In many models, the modeler will allow sections of the model to be 1347 conditional. The device controls whether these conditional portions 1348 of the model are supported or valid for that particular device. 1350 For example, a syslog data model may choose to include the ability to 1351 save logs locally, but the modeler will realize that this is only 1352 possible if the device has local storage. If there is no local 1353 storage, an application should not tell the device to save logs. 1355 YANG supports this conditional mechanism using a construct called 1356 "feature". Features give the modeler a mechanism for making portions 1357 of the module conditional in a manner that is controlled by the 1358 device. The model can express constructs which are not universally 1359 present in all devices. These features are included in the model 1360 definition, allowing a consistent view and allowing applications to 1361 learn which features are supported and tailor their behavior to the 1362 device. 1364 A module may declare any number of features, identified by simple 1365 strings, and may make portions of the module optional based on those 1366 features. If the device supports a feature, then the corresponding 1367 portions of the module are valid for that device. If the device 1368 doesn't support the feature, those parts of the module are not valid, 1369 and applications should behave accordingly. 1371 Features are defined using the "feature" statement. Definitions in 1372 the module that are conditional to the feature are noted by the 1373 "if-feature" statement with the name of the feature as its argument. 1375 Further details are available in Section 7.18.1. 1377 5.6.3. Deviations 1379 In an ideal world, all devices would be required to implement the 1380 model exactly as defined, and deviations from the model would not be 1381 allowed. But in the real world, devices are often not able or 1382 designed to implement the model as written. For YANG-based 1383 automation to deal with these device deviations, a mechanism must 1384 exist for devices to inform applications of the specifics of such 1385 deviations. 1387 For example, a BGP module may allow any number of BGP peers, but a 1388 particular device may only support 16 BGP peers. Any application 1389 configuring the 17th peer will receive an error. While an error may 1390 suffice to let the application know it cannot add another peer, it 1391 would be far better if the application had prior knowledge of this 1392 limitation and could prevent the user from starting down the path 1393 that could not succeed. 1395 Device deviations are declared using the "deviation" statement, which 1396 takes as its argument a string which identifies a node in the schema 1397 tree. The contents of the statement details the manner in which the 1398 device implementation deviates from the contract as defined in the 1399 module. 1401 Further details are available in Section 7.18.3. 1403 5.6.4. Announcing Conformance Information in the Message 1405 The namespace URI MUST be advertised as a capability in the NETCONF 1406 message to indicate support for the YANG module by a NETCONF 1407 server. The capability URI advertised MUST be on the form: 1409 capability-string = namespace-uri [ parameter-list ] 1410 parameter-list = "?" parameter *( "&" parameter ) 1411 parameter = revision-parameter / 1412 module-parameter / 1413 feature-parameter / 1414 deviation-parameter 1415 revision-parameter = "revision=" revision-date 1416 module-parameter = "module=" module-name 1417 feature-parameter = "features=" feature *( "," feature ) 1418 deviation-parameter = "deviations=" deviation *( "," deviation ) 1420 Where "revision-date" is the revision of the module (see 1421 Section 7.1.9) that the NETCONF server implements, "module-name" is 1422 the name of module as it appears in the "module" statement (see 1423 Section 7.1), "namespace-uri" is the namespace URI for the module as 1424 it appears in the "namespace" statement (see Section 7.1.3), 1425 "feature" is the name of an optional feature implemented by the 1426 device (see Section 7.18.1), and "deviation" is the name of a module 1427 defining device deviations (see Section 7.18.3). 1429 In the parameter list, each named parameter MUST occur at most once. 1431 5.6.4.1. Modules 1433 Servers indicate the names of supported modules via the 1434 message. Module namespaces are encoded as the base URI in the 1435 capability string, and the module name is encoded as the "module" 1436 parameter to the base URI. 1438 A server MUST advertise all revisions of all modules it implements. 1440 For example, this message advertises one module "syslog". 1442 1443 1444 http://example.com/syslog?module=syslog&revision=2008-04-01 1445 1446 1448 5.6.4.2. Features 1450 Servers indicate the names of supported features via the 1451 message. In hello messages, the features are encoded in the 1452 "features" parameter within the URI. The value of this parameter is 1453 a comma-separated list of feature names which the device supports for 1454 the specific module. 1456 For example, this message advertises one module, informing 1457 the client that it supports the "local-storage" feature of module 1458 "syslog". 1460 1461 1462 http://example.com/syslog?module=syslog&features=local-storage 1463 1464 1466 5.6.4.3. Deviations 1468 Device deviations are announced via the "deviations" parameter. The 1469 value of the deviations parameter is a comma-separated list of 1470 modules containing deviations from the capability's module. 1472 For example, this message advertises two modules, informing 1473 the client that it deviates from module "syslog" according to the 1474 deviations listed in the module "my-devs". 1476 1477 1478 http://example.com/syslog?module=syslog&deviations=my-devs 1479 1480 1481 http://example.com/my-deviations?module=my-devs 1482 1483 1485 5.7. Data Store Modification 1487 Data models may allow the server to alter the configuration data 1488 store in ways not explicitly directed via NETCONF protocol messages. 1489 For example, a data model may define leafs that are assigned system- 1490 generated values when the client does not provide one. A formal 1491 mechanism for specifying the circumstances where these changes are 1492 allowed is out of scope for this specification. 1494 6. YANG syntax 1496 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1497 languages like C and C++. This C-like syntax was chosen specifically 1498 for its readability, since YANG values the time and effort of the 1499 readers of models above those of modules writers and YANG tool-chain 1500 developers. This section introduces the YANG syntax. 1502 YANG modules use the UTF-8 [RFC3629] character encoding. 1504 6.1. Lexicographical Tokenization 1506 YANG modules are parsed as a series of tokens. This section details 1507 the rules for recognizing tokens from an input stream. YANG 1508 tokenization rules are both simple and powerful. The simplicity is 1509 driven by a need to keep the parsers easy to implement, while the 1510 power is driven by the fact that modelers need to express their 1511 models in readable formats. 1513 6.1.1. Comments 1515 Comments are C++ style. A single line comment starts with "//" and 1516 ends at the end of the line. A block comment is enclosed within "/*" 1517 and "*/". 1519 6.1.2. Tokens 1521 A token in YANG is either a keyword, a string, ";", "{", or "}". A 1522 string can be quoted or unquoted. A keyword is either one of the 1523 YANG keywords defined in this document, or a prefix identifier, 1524 followed by ":", followed by a language extension keyword. Keywords 1525 are case sensitive. See Section 6.2 for a formal definition of 1526 identifiers. 1528 6.1.3. Quoting 1530 If a string contains any space or tab characters, a semicolon (";"), 1531 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1532 it MUST be enclosed within double or single quotes. 1534 If the double quoted string contains a line break followed by space 1535 or tab characters which are used to indent the text according to the 1536 layout in the YANG file, this leading whitespace is stripped from the 1537 string, up to and including the column of the double quote character, 1538 or to the first non-whitespace character, whichever occurs first. 1540 If the double quoted string contains space or tab characters before a 1541 line break, this trailing whitespace is stripped from the string. 1543 A single quoted string (enclosed within ' ') preserves each character 1544 within the quotes. A single quote character cannot occur in a single 1545 quoted string, even when preceded by a backslash. 1547 Within a double quoted string (enclosed within " "), a backslash 1548 character introduces a special character, which depends on the 1549 character that immediately follows the backslash: 1551 \n new line 1552 \t a tab character 1553 \" a double quote 1554 \\ a single backslash 1556 If a quoted string is followed by a plus character ("+"), followed by 1557 another quoted string, the two strings are concatenated into one 1558 string, allowing multiple concatenations to build one string. 1559 Whitespace trimming and substition of backslash-escaped characters in 1560 double quoted strings is done before concatenation. 1562 6.1.3.1. Quoting Examples 1564 The following strings are equivalent: 1566 hello 1567 "hello" 1568 'hello' 1569 "hel" + "lo" 1570 'hel' + "lo" 1572 The following examples show some special strings: 1574 "\"" - string containing a double quote 1575 '"' - string containing a double quote 1576 "\n" - string containing a newline character 1577 '\n' - string containing a backslash followed 1578 by the character n 1580 The following examples show some illegal strings: 1582 '''' - a single-quoted string cannot contain single quotes 1583 """ - a double quote must be escaped in a double quoted string 1585 The following strings are equivalent: 1587 "first line 1588 second line" 1590 "first line\n" + " second line" 1592 6.2. Identifiers 1594 Identifiers are used to identify different kinds of YANG items by 1595 name. Each identifier starts with an upper-case or lower-case ASCII 1596 letter or an underscore character, followed by zero or more ASCII 1597 letters, digits, underscore characters, hyphens, and dots. 1598 Implementations MUST support identifiers up to 64 characters in 1599 length. Identifiers are case sensitive. The identifier syntax is 1600 formally defined by the rule "identifier" in Section 12. Identifiers 1601 can be specified as quoted or unquoted strings. 1603 6.2.1. Identifiers and their namespaces 1605 Each identifier is valid in a namespace which depends on the type of 1606 the YANG item being defined. All identifiers defined in a namespace 1607 MUST be unique. 1609 o All module and submodule names share the same global module 1610 identifier namespace. 1612 o All extension names defined in a module and its submodules share 1613 the same extension identifier namespace. 1615 o All feature names defined in a module and its submodules share the 1616 same feature identifier namespace. 1618 o All identity names defined in a module and its submodules share 1619 the same identity identifier namespace. 1621 o All derived type names defined within a parent node or at the top- 1622 level of the module or its submodules share the same type 1623 identifier namespace. This namespace is scoped to all descendant 1624 nodes of the parent node or module. This means that any 1625 descendent node may use that typedef, and it MUST NOT define a 1626 typedef with the same name. 1628 o All grouping names defined within a parent node or at the top- 1629 level of the module or its submodules share the same grouping 1630 identifier namespace. This namespace is scoped to all descendant 1631 nodes of the parent node or module. This means that any 1632 descendent node may use that grouping, and it MUST NOT define a 1633 grouping with the same name. 1635 o All leafs, leaf-lists, lists, containers, choices, rpcs, 1636 notifications, and anyxmls defined (directly or through a uses 1637 statement) within a parent node or at the top-level of the module 1638 or its submodules share the same identifier namespace. This 1639 namespace is scoped to the parent node or module, unless the 1640 parent node is a case node. In that case, the namespace is scoped 1641 to the closest ancestor node which is not a case or choice node. 1643 o All cases within a choice share the same case identifier 1644 namespace. This namespace is scoped to the parent choice node. 1646 Forward references are allowed in YANG. 1648 6.3. Statements 1650 A YANG module contains a sequence of statements. Each statement 1651 starts with a keyword, followed by zero or one argument, followed 1652 either by a semicolon (";") or a block of substatements enclosed 1653 within braces ("{ }"): 1655 statement = keyword [argument] (";" / "{" *statement "}") 1657 The argument is a string, as defined in Section 6.1.2. 1659 6.3.1. Language Extensions 1661 A module can introduce YANG extensions by using the "extension" 1662 keyword (see Section 7.17). The extensions can be imported by other 1663 modules with the "import" statement (see Section 7.1.5). When an 1664 imported extension is used, the extension's keyword MUST be qualified 1665 using the prefix with which the extension's module was imported. If 1666 an extension is used in the module where it is defined, the 1667 extension's keyword MUST be qualified with the module's prefix. 1669 Since submodules cannot include the parent module, any extensions in 1670 the module which need to be exposed to submodules MUST be defined in 1671 a submodule. Submodules can then include this submodule to find the 1672 definition of the extension. 1674 If a YANG compiler does not support a particular extension, which 1675 appears in a YANG module as an unknown-statement (see Section 12), 1676 the entire unknown statement MAY be ignored by the compiler. 1678 6.4. XPath Evaluations 1680 YANG relies on XPath 1.0 [XPATH] as a notation for specifying many 1681 inter-node references and dependencies. NETCONF clients and servers 1682 are not required to implement an XPath interpreter, but MUST ensure 1683 that the requirements encoded in the data model are enforced. The 1684 manner of enforcement is an implementation decision. The XPath 1685 expressions MUST be syntactically correct, and all prefixes used MUST 1686 be present in the XPath context (see Section 6.4.1). An 1687 implementation may choose to implement them by hand, rather than 1688 using the XPath expression directly. 1690 The data model used in the XPath expressions is the same as that used 1691 in XPath 1.0 [XPATH], with the same extension for root node children 1692 as used by XSLT 1.0 [XSLT] (section 3.1). Specifically, it means 1693 that the root node may have any number of element nodes as its 1694 children. 1696 6.4.1. XPath Context 1698 All YANG XPath expressions share the following XPath context 1699 definition: 1701 o The set of namespace declarations is the set of all "import" 1702 statements' prefix and namespace pairs in the module where the 1703 XPath expression is specified, and the "prefix" statement's prefix 1704 for the "namespace" statement's URI. 1706 o Names without a namespace prefix belong to the same namespace as 1707 the identifier of the current node. Inside a grouping, that 1708 namespace is affected by where the grouping is used (see 1709 Section 7.12). 1711 o The function library is the core function library defined in 1712 [XPATH], and a function "current()" which returns a node set with 1713 the initial context node. 1715 o The set of variable bindings is empty. 1717 The mechanism for handling unprefixed names is adopted from XPath 2.0 1718 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1719 ambiguity may ever arise because YANG node identifiers are always 1720 qualified names with a non-null namespace URI. 1722 The context node varies with the YANG XPath expression, and is 1723 specified where the YANG statement with the XPath expression is 1724 defined. 1726 6.5. Schema Node Identifier 1728 A schema node identifier is a string that identifies a node in the 1729 schema tree. It has two forms, "absolute" and "descendant", defined 1730 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1731 in Section 12, respectively. A schema node identifier consists of a 1732 path of identifiers, separated by slashes ("/"). In an absolute 1733 schema node identifier, the first identifier after the leading slash 1734 is any top-level schema node in local module or all imported modules. 1736 References to identifiers defined in external modules MUST be 1737 qualified with appropriate prefixes, and references to identifiers 1738 defined in the current module and its submodules MAY use a prefix. 1740 For example, to identify the child node "b" of top-level node "a", 1741 the string "/a/b" can be used. 1743 7. YANG Statements 1745 The following sections describe all of the YANG statements. 1747 Note that even a statement which does not have any substatements 1748 defined in YANG can have vendor-specific extensions as substatements. 1749 For example, the "description" statement does not have any 1750 substatements defined in YANG, but the following is legal: 1752 description "some text" { 1753 acme:documentation-flag 5; 1754 } 1756 7.1. The module Statement 1758 The "module" statement defines the module's name, and groups all 1759 statements which belong to the module together. The "module" 1760 statement's argument is the name of the module, followed by a block 1761 of substatements that hold detailed module information. The module 1762 name follows the rules for identifiers in Section 6.2. 1764 Names of modules published in RFC streams [RFC4844] MUST be assigned 1765 by IANA, see Section 14. 1767 Private module names are assigned by the organization owning the 1768 module without a central registry. It is RECOMMENDED to choose 1769 module names that will have a low probability of colliding with 1770 standard or other enterprise modules and submodules, e.g., by using 1771 the enterprise or organization name as a prefix for the module name. 1773 A module SHOULD have the following layout: 1775 module { 1777 // header information 1778 1779 1780 1782 // linkage statements 1783 1784 1786 // meta information 1787 1788 1789 1790 1792 // revision history 1793 1795 // module definitions 1796 1797 } 1799 7.1.1. The module's Substatements 1800 +--------------+---------+-------------+ 1801 | substatement | section | cardinality | 1802 +--------------+---------+-------------+ 1803 | anyxml | 7.10 | 0..n | 1804 | augment | 7.15 | 0..n | 1805 | choice | 7.9 | 0..n | 1806 | contact | 7.1.8 | 0..1 | 1807 | container | 7.5 | 0..n | 1808 | description | 7.19.3 | 0..1 | 1809 | deviation | 7.18.3 | 0..n | 1810 | extension | 7.17 | 0..n | 1811 | feature | 7.18.1 | 0..n | 1812 | grouping | 7.11 | 0..n | 1813 | identity | 7.16 | 0..n | 1814 | import | 7.1.5 | 0..n | 1815 | include | 7.1.6 | 0..n | 1816 | leaf | 7.6 | 0..n | 1817 | leaf-list | 7.7 | 0..n | 1818 | list | 7.8 | 0..n | 1819 | namespace | 7.1.3 | 1 | 1820 | notification | 7.14 | 0..n | 1821 | organization | 7.1.7 | 0..1 | 1822 | prefix | 7.1.4 | 1 | 1823 | reference | 7.19.4 | 0..1 | 1824 | revision | 7.1.9 | 0..n | 1825 | rpc | 7.13 | 0..n | 1826 | typedef | 7.3 | 0..n | 1827 | uses | 7.12 | 0..n | 1828 | yang-version | 7.1.2 | 0..1 | 1829 +--------------+---------+-------------+ 1831 7.1.2. The yang-version Statement 1833 The optional "yang-version" statement specifies which version of the 1834 YANG language was used in developing the module. The statement's 1835 argument is a string. If present, it MUST contain the value "1", 1836 which is the current YANG version and the default value. 1838 7.1.3. The namespace Statement 1840 The "namespace" statement defines the XML namespace to which all 1841 identifiers defined by the module belong, with the exception of data 1842 node identifiers defined inside a grouping (see Section 7.12 for 1843 details). The argument to the "namespace" statement is the URI of 1844 the namespace. 1846 See also Section 5.3. 1848 7.1.4. The prefix Statement 1850 The "prefix" statement is used to define the prefix associated with 1851 the module and its namespace. The "prefix" statement's argument is 1852 the prefix string which is used as a prefix to access a module. The 1853 prefix string MAY be used to refer to definitions contained in the 1854 module, e.g., "if:ifName". A prefix follows the same rules as an 1855 identifier (see Section 6.2). 1857 When used inside the "module" statement, the "prefix" statement 1858 defines the prefix to be used when this module is imported. To 1859 improve readability of the NETCONF XML, a NETCONF client or server 1860 which generates XML or XPath that use prefixes SHOULD use the prefix 1861 defined by the module, unless there is a conflict. 1863 When used inside the "import" statement, the "prefix" statement 1864 defines the prefix to be used when accessing definitions inside the 1865 imported module. When a reference to an identifier from the imported 1866 module is used, the prefix string for the imported module is used in 1867 combination with a colon (":") and the identifier, e.g., "if: 1868 ifIndex". To improve readability of YANG modules, the prefix defined 1869 by a module SHOULD be used when the module is imported, unless there 1870 is a conflict. 1872 All prefixes, including the prefix for the module itself MUST be 1873 unique within the module or submodule. 1875 7.1.5. The import Statement 1877 The "import" statement makes definitions from one module available 1878 inside another module or submodule. The argument is the name of the 1879 module to import, and the statement is followed by a block of 1880 substatements that holds detailed import information. When a module 1881 is imported, the importing module may: 1883 o use any grouping and typedef defined at the top-level in the 1884 imported module or its submodules 1886 o use any extension, feature, and identity defined in the imported 1887 module or its submodules 1889 o use any node in the imported module's schema tree in "must", 1890 "path", and "when" statements, or as the target node in an 1891 "augment" statement 1893 The mandatory "prefix" substatement assigns a prefix for the imported 1894 module which is scoped to the importing module or submodule. 1895 Multiple "import" statements may be specified to import from 1896 different modules. 1898 When the optional "revision-date" substatement is present, any 1899 typedef, grouping, extension, feature, and identity referenced by 1900 definitions in the local module are taken from the specified revision 1901 of the imported module. Otherwise, it is undefined from which 1902 revision of the module they are taken. 1904 Multiple revisions of the same module MUST NOT be imported. 1906 The import's Substatements 1908 +---------------+---------+-------------+ 1909 | substatement | section | cardinality | 1910 +---------------+---------+-------------+ 1911 | prefix | 7.1.4 | 1 | 1912 | revision-date | 7.1.5.1 | 0..1 | 1913 +---------------+---------+-------------+ 1915 7.1.5.1. The import's revision-date Statement 1917 The import's "revision-date" statement is used to specify the exact 1918 version of the module to import. The "revision-date" statement MUST 1919 match the most recent "revision" statement in the imported module. 1921 7.1.6. The include Statement 1923 The "include" statement is used to make content from a submodule 1924 available to that submodule's parent module, or to another submodule 1925 of that parent module. The argument is an identifier which is the 1926 name of the submodule to include. Modules are only allowed to 1927 include submodules that belong to that module, as defined by the 1928 "belongs-to" statement (see Section 7.2.2). Submodules are only 1929 allowed to include other submodules belonging to the same module. 1931 When a module includes a submodule, it incorporates the contents of 1932 the submodule into the node hierarchy of the module. When a 1933 submodule includes another submodule, the target submodule's 1934 definitions are made available to the current submodule. 1936 When the optional "revision-date" is present, the specified revision 1937 of the submodule is included in the module. Otherwise, it is 1938 undefined which revision of the submodule is included. 1940 Multiple revisions of the same submodule MUST NOT be included. 1942 The includes's Substatements 1944 +---------------+---------+-------------+ 1945 | substatement | section | cardinality | 1946 +---------------+---------+-------------+ 1947 | revision-date | 7.1.5.1 | 0..1 | 1948 +---------------+---------+-------------+ 1950 7.1.7. The organization Statement 1952 The "organization" statement defines the party responsible for this 1953 module. The argument is a string which is used to specify a textual 1954 description of the organization(s) under whose auspices this module 1955 was developed. 1957 7.1.8. The contact Statement 1959 The "contact" statement provides contact information for the module. 1960 The argument is a string which is used to specify contact information 1961 for the person or persons to whom technical queries concerning this 1962 module should be sent, such as their name, postal address, telephone 1963 number, and electronic mail address. 1965 7.1.9. The revision Statement 1967 The "revision" statement specifies the editorial revision history of 1968 the module, including the initial revision. A series of revision 1969 statements detail the changes in the module's definition. The 1970 argument is a date string in the format "YYYY-MM-DD", followed by a 1971 block of substatements that holds detailed revision information. A 1972 module SHOULD have at least one initial "revision" statement. For 1973 every published editorial change, a new one SHOULD be added in front 1974 of the revisions sequence, so that all revisions are in reverse 1975 chronological order. 1977 7.1.9.1. The revision's Substatement 1979 +--------------+---------+-------------+ 1980 | substatement | section | cardinality | 1981 +--------------+---------+-------------+ 1982 | description | 7.19.3 | 0..1 | 1983 | reference | 7.19.4 | 0..1 | 1984 +--------------+---------+-------------+ 1986 7.1.10. Usage Example 1988 module acme-system { 1989 namespace "http://acme.example.com/system"; 1990 prefix "acme"; 1992 import ietf-yang-types { 1993 prefix "yang"; 1994 } 1996 include acme-types; 1998 organization "ACME Inc."; 1999 contact 2000 "Joe L. User 2002 ACME, Inc. 2003 42 Anywhere Drive 2004 Nowhere, CA 95134 2005 USA 2007 Phone: +1 800 555 0100 2008 EMail: joe@acme.example.com"; 2010 description 2011 "The module for entities implementing the ACME protocol."; 2013 revision "2007-06-09" { 2014 description "Initial revision."; 2015 } 2017 // definitions follow... 2018 } 2020 7.2. The submodule Statement 2022 While the primary unit in YANG is a module, a YANG module can itself 2023 be constructed out of several submodules. Submodules allow a module 2024 designer to split a complex model into several pieces where all the 2025 submodules contribute to a single namespace, which is defined by the 2026 module that includes the submodules. 2028 The "submodule" statement defines the submodule's name, and groups 2029 all statements which belong to the submodule together. The 2030 "submodule" statement's argument is the name of the submodule, 2031 followed by a block of substatements that hold detailed submodule 2032 information. The submodule name follows the rules for identifiers in 2033 Section 6.2. 2035 Names of submodules published in RFC streams [RFC4844] MUST be 2036 assigned by IANA, see Section 14. 2038 Private submodule names are assigned by the organization owning the 2039 submodule without a central registry. It is RECOMMENDED to choose 2040 submodule names that will have a low probability of colliding with 2041 standard or other enterprise modules and submodules, e.g., by using 2042 the enterprise or organization name as a prefix for the submodule 2043 name. 2045 A submodule SHOULD have the following layout: 2047 submodule { 2049 2051 // module identification 2052 2054 // linkage statements 2055 2056 2058 // meta information 2059 2060 2061 2062 2064 // revision history 2065 2067 // module definitions 2068 2069 } 2071 7.2.1. The submodule's Substatements 2072 +--------------+---------+-------------+ 2073 | substatement | section | cardinality | 2074 +--------------+---------+-------------+ 2075 | anyxml | 7.10 | 0..n | 2076 | augment | 7.15 | 0..n | 2077 | belongs-to | 7.2.2 | 1 | 2078 | choice | 7.9 | 0..n | 2079 | contact | 7.1.8 | 0..1 | 2080 | container | 7.5 | 0..n | 2081 | description | 7.19.3 | 0..1 | 2082 | deviation | 7.18.3 | 0..n | 2083 | extension | 7.17 | 0..n | 2084 | feature | 7.18.1 | 0..n | 2085 | grouping | 7.11 | 0..n | 2086 | identity | 7.16 | 0..n | 2087 | import | 7.1.5 | 0..n | 2088 | include | 7.1.6 | 0..n | 2089 | leaf | 7.6 | 0..n | 2090 | leaf-list | 7.7 | 0..n | 2091 | list | 7.8 | 0..n | 2092 | notification | 7.14 | 0..n | 2093 | organization | 7.1.7 | 0..1 | 2094 | reference | 7.19.4 | 0..1 | 2095 | revision | 7.1.9 | 0..n | 2096 | rpc | 7.13 | 0..n | 2097 | typedef | 7.3 | 0..n | 2098 | uses | 7.12 | 0..n | 2099 | yang-version | 7.1.2 | 0..1 | 2100 +--------------+---------+-------------+ 2102 7.2.2. The belongs-to Statement 2104 The "belongs-to" statement specifies the module to which the 2105 submodule belongs. The argument is an identifier which is the name 2106 of the module. 2108 A submodule MUST only be included by the module to which it belongs, 2109 or by another submodule which belongs to that module. 2111 The mandatory "prefix" substatement assigns a prefix for the module 2112 to which the submodule belongs. All definitions in the local 2113 submodule and any included submodules can be accessed by using the 2114 prefix. 2116 The belongs-to's Substatements 2118 +--------------+---------+-------------+ 2119 | substatement | section | cardinality | 2120 +--------------+---------+-------------+ 2121 | prefix | 7.1.4 | 1 | 2122 +--------------+---------+-------------+ 2124 7.2.3. Usage Example 2126 submodule acme-types { 2128 belongs-to "acme-system" { 2129 prefix "acme"; 2130 } 2132 import ietf-yang-types { 2133 prefix "yang"; 2134 } 2136 organization "ACME Inc."; 2137 contact 2138 "Joe L. User 2140 ACME, Inc. 2141 42 Anywhere Drive 2142 Nowhere, CA 95134 2143 USA 2145 Phone: +1 800 555 0100 2146 EMail: joe@acme.example.com"; 2148 description 2149 "This submodule defines common ACME types."; 2151 revision "2007-06-09" { 2152 description "Initial revision."; 2153 } 2155 // definitions follows... 2156 } 2158 7.3. The typedef Statement 2160 The "typedef" statement defines a new type which may be used locally 2161 in the module, in modules or submodules which include it, and by 2162 other modules which import from it, according to the rules in 2163 Section 5.5. The new type is called the "derived type", and the type 2164 from which it was derived is called the "base type". All derived 2165 types can be traced back to a YANG built-in type. 2167 The "typedef" statement's argument is an identifier which is the name 2168 of the type to be defined, and MUST be followed by a block of 2169 substatements that holds detailed typedef information. 2171 The name of the type MUST NOT be one of the YANG built-in types. If 2172 the typedef is defined at the top level of a YANG module or 2173 submodule, the name of the type to be defined MUST be unique within 2174 the module. 2176 7.3.1. The typedef's Substatements 2178 +--------------+---------+-------------+ 2179 | substatement | section | cardinality | 2180 +--------------+---------+-------------+ 2181 | default | 7.3.4 | 0..1 | 2182 | description | 7.19.3 | 0..1 | 2183 | reference | 7.19.4 | 0..1 | 2184 | status | 7.19.2 | 0..1 | 2185 | type | 7.3.2 | 1 | 2186 | units | 7.3.3 | 0..1 | 2187 +--------------+---------+-------------+ 2189 7.3.2. The typedef's type Statement 2191 The "type" statement, which MUST be present, defines the base type 2192 from which this type is derived. See Section 7.4 for details. 2194 7.3.3. The units Statement 2196 The "units" statement, which is optional, takes as an argument a 2197 string which contains a textual definition of the units associated 2198 with the type. 2200 7.3.4. The typedef's default Statement 2202 The "default" statement takes as an argument a string which contains 2203 a default value for the new type. 2205 The value of the "default" statement MUST be valid according to the 2206 type specified in the "type" statement. 2208 If the base type has a default value, and the new derived type does 2209 not specify a new default value, the base type's default value is 2210 also the default value of the new derived type. 2212 If the type's default value is not valid according to the new 2213 restrictions specified in a derived type or leaf definition, the 2214 derived type or leaf definition MUST specify a new default value 2215 compatible with the restrictions. 2217 7.3.5. Usage Example 2219 typedef listen-ipv4-address { 2220 type inet:ipv4-address; 2221 default "0.0.0.0"; 2222 } 2224 7.4. The type Statement 2226 The "type" statement takes as an argument a string which is the name 2227 of a YANG built-in type (see Section 9) or a derived type (see 2228 Section 7.3), followed by an optional block of substatements that are 2229 used to put further restrictions on the type. 2231 The restrictions that can be applied depend on the type being 2232 restricted. The restriction statements for all built-in types are 2233 described in the subsections of Section 9. 2235 7.4.1. The type's Substatements 2237 +------------------+---------+-------------+ 2238 | substatement | section | cardinality | 2239 +------------------+---------+-------------+ 2240 | bit | 9.7.4 | 0..n | 2241 | enum | 9.6.4 | 0..n | 2242 | length | 9.4.4 | 0..1 | 2243 | path | 9.9.2 | 0..1 | 2244 | pattern | 9.4.6 | 0..n | 2245 | range | 9.2.4 | 0..1 | 2246 | require-instance | 9.13.2 | 0..1 | 2247 | type | 7.4 | 0..n | 2248 +------------------+---------+-------------+ 2250 7.5. The container Statement 2252 The "container" statement is used to define an interior data node in 2253 the schema tree. It takes one argument, which is an identifier, 2254 followed by a block of substatements that holds detailed container 2255 information. 2257 A container node does not have a value, but it has a list of child 2258 nodes in the data tree. The child nodes are defined in the 2259 container's substatements. 2261 7.5.1. Containers with Presence 2263 YANG supports two styles of containers, those which exist only for 2264 organizing the hierarchy of data nodes, and those whose presence in 2265 the configuration has an explicit meaning. 2267 In the first style, the container has no meaning of its own, existing 2268 only to contain child nodes. This is the default style. 2270 For example, the set of scrambling options for SONET interfaces may 2271 be placed inside a "scrambling" container to enhance the organization 2272 of the configuration hierarchy, and to keep these nodes together. 2273 The "scrambling" node itself has no meaning, so removing the node 2274 when it becomes empty relieves the user from performing this task. 2276 In the second style, the presence of the container itself is 2277 configuration data, representing a single bit of configuration data. 2278 The container acts as both a configuration knob and a means of 2279 organizing related configuration. These containers are explicitly 2280 created and deleted. 2282 YANG calls this style a "presence container" and it is indicated 2283 using the "presence" statement, which takes as its argument a text 2284 string indicating what the presence of the node means. 2286 For example, an "ssh" container may turn on the ability to log into 2287 the device using ssh, but can also contain any ssh-related 2288 configuration knobs, such as connection rates or retry limits. 2290 The "presence" statement (see Section 7.5.5) is used to give 2291 semantics to the existence of the container in the data tree. 2293 7.5.2. The container's Substatements 2295 +--------------+---------+-------------+ 2296 | substatement | section | cardinality | 2297 +--------------+---------+-------------+ 2298 | anyxml | 7.10 | 0..n | 2299 | choice | 7.9 | 0..n | 2300 | config | 7.19.1 | 0..1 | 2301 | container | 7.5 | 0..n | 2302 | description | 7.19.3 | 0..1 | 2303 | grouping | 7.11 | 0..n | 2304 | if-feature | 7.18.2 | 0..n | 2305 | leaf | 7.6 | 0..n | 2306 | leaf-list | 7.7 | 0..n | 2307 | list | 7.8 | 0..n | 2308 | must | 7.5.3 | 0..n | 2309 | presence | 7.5.5 | 0..1 | 2310 | reference | 7.19.4 | 0..1 | 2311 | status | 7.19.2 | 0..1 | 2312 | typedef | 7.3 | 0..n | 2313 | uses | 7.12 | 0..n | 2314 | when | 7.19.5 | 0..1 | 2315 +--------------+---------+-------------+ 2317 7.5.3. The must Statement 2319 The "must" statement, which is optional, takes as an argument a 2320 string which contains an XPath expression. It is used to formally 2321 declare a constraint on valid data. The constraint is enforced 2322 according to the rules in Section 8. 2324 When a datastore is validated, all "must" constraints are 2325 conceptually evaluated once for each data node in the data tree, and 2326 for all leafs with default values in use (see Section 7.6.1). If a 2327 data node does not exist in the data tree, and it does not have a 2328 default value, its "must" statements are not evaluated. 2330 All such constraints MUST evaluate to true for the data to be valid. 2332 The XPath expression is conceptually evaluated in the following 2333 context, in addition to the definition in Section 6.4.1: 2335 o The context node is the node in the data tree for which the "must" 2336 statement is defined. 2338 o The accessible tree is made up of all nodes in the data tree, and 2339 all leafs with default values in use (see Section 7.6.1). 2341 The accessible tree depends on the context node: 2343 o If the context node represents configuration, the tree is the data 2344 in the NETCONF datastore where the context node exists. The XPath 2345 root node has all top-level configuration data nodes in all 2346 modules as children. 2348 o If the context node represents state data, the tree is all state 2349 data on the device, and the datastore. The XPath root 2350 node has all top-level data nodes in all modules as children. 2352 o If the context node represents notification content, the tree is 2353 the notification XML instance document. The XPath root node has 2354 the element representing the notification being defined as the 2355 only child. 2357 o If the context node represents RPC input parameters, the tree is 2358 the RPC XML instance document. The XPath root node has the 2359 element representing the RPC operation being defined as the only 2360 child. 2362 o If the context node represents RPC output parameters, the tree is 2363 the RPC reply instance document. The XPath root node has the 2364 elements representing the RPC output parameters as children. 2366 The result of the XPath expression is converted to a boolean value 2367 using the standard XPath rules. 2369 Note that since all leaf values in the data tree are conceptually 2370 stored in their canonical form (see Section 7.6 and Section 7.7), any 2371 XPath comparisons are done on the canonical value. 2373 Also note that the XPath expression is conceptually evaluated. This 2374 means that an implementation does not have to use an XPath evaluator 2375 on the device. How the evaluation is done in practice is an 2376 implementation decision. 2378 7.5.4. The must's Substatements 2380 +---------------+---------+-------------+ 2381 | substatement | section | cardinality | 2382 +---------------+---------+-------------+ 2383 | description | 7.19.3 | 0..1 | 2384 | error-app-tag | 7.5.4.2 | 0..1 | 2385 | error-message | 7.5.4.1 | 0..1 | 2386 | reference | 7.19.4 | 0..1 | 2387 +---------------+---------+-------------+ 2389 7.5.4.1. The error-message Statement 2391 The "error-message" statement, which is optional, takes a string as 2392 an argument. If the constraint evaluates to false, the string is 2393 passed as in the . 2395 7.5.4.2. The error-app-tag Statement 2397 The "error-app-tag" statement, which is optional, takes a string as 2398 an argument. If the constraint evaluates to false, the string is 2399 passed as in the . 2401 7.5.4.3. Usage Example of must and error-message 2403 container interface { 2404 leaf ifType { 2405 type enumeration { 2406 enum ethernet; 2407 enum atm; 2408 } 2409 } 2410 leaf ifMTU { 2411 type uint32; 2412 } 2413 must "ifType != 'ethernet' or " + 2414 "(ifType = 'ethernet' and ifMTU = 1500)" { 2415 error-message "An ethernet MTU must be 1500"; 2416 } 2417 must "ifType != 'atm' or " + 2418 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2419 error-message "An atm MTU must be 64 .. 17966"; 2420 } 2421 } 2423 7.5.5. The presence Statement 2425 The "presence" statement assigns a meaning to the presence of a 2426 container in the data tree. It takes as an argument a string which 2427 contains a textual description of what the node's presence means. 2429 If a container has the "presence" statement, the container's 2430 existence in the data tree carries some meaning. Otherwise, the 2431 container is used to give some structure to the data, and it carries 2432 no meaning by itself. 2434 See Section 7.5.1 for additional information. 2436 7.5.6. The container's Child Node Statements 2438 Within a container, the "container", "leaf", "list", "leaf-list", 2439 "uses", "choice", and "anyxml" statements can be used to define child 2440 nodes to the container. 2442 7.5.7. XML Mapping Rules 2444 A container node is encoded as an XML element. The element's local 2445 name is the container's identifier, and its namespace is the module's 2446 XML namespace (see Section 7.1.3). 2448 The container's child nodes are encoded as subelements to the 2449 container element. If the container defines RPC input or output 2450 parameters, these subelements are encoded in the same order as they 2451 are defined within the container statement. Otherwise, the 2452 subelements are encoded in any order. 2454 A NETCONF server that replies to a or request MAY 2455 choose not to send a container element if the container node does not 2456 have the "presence" statement and no child nodes exist. Thus, a 2457 client that receives an for a or 2458 request, must be prepared to handle the case that a container node 2459 without a presence statement is not present in the XML. 2461 7.5.8. NETCONF Operations 2463 Containers can be created, deleted, replaced and modified through 2464 , by using the "operation" attribute (See [RFC4741], 2465 section 7.2) in the container's XML element. 2467 If a container does not have a "presence" statement and the last 2468 child node is deleted, the NETCONF server MAY delete the container. 2470 When a NETCONF server processes an request, the 2471 elements of procedure for the container node are: 2473 If the operation is "merge" or "replace", the node is created if 2474 it does not exist. 2476 If the operation is "create" the node is created if it does not 2477 exist. If the node already exists, a "data-exists" error is 2478 returned. 2480 If the operation is "delete" the node is deleted if it exists. If 2481 the node does not exist, a "data-missing" error is returned. 2483 7.5.9. Usage Example 2485 Given the following container definition: 2487 container system { 2488 description "Contains various system parameters"; 2489 container services { 2490 description "Configure externally available services"; 2491 container "ssh" { 2492 presence "Enables SSH"; 2493 description "SSH service specific configuration"; 2494 // more leafs, containers and stuff here... 2495 } 2496 } 2497 } 2499 A corresponding XML instance example: 2501 2502 2503 2504 2505 2507 Since the element is present, ssh is enabled. 2509 To delete a container with an : 2511 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2528 7.6. The leaf Statement 2530 The "leaf" statement is used to define a leaf node in the schema 2531 tree. It takes one argument, which is an identifier, followed by a 2532 block of substatements that holds detailed leaf information. 2534 A leaf node has a value, but no child nodes in the data tree. 2535 Conceptually, the value in the data tree is always in the canonical 2536 form (see Section 9.1). 2538 A leaf node exists in zero or one instances in the data tree, 2539 depending on the value of the "mandatory" statement. 2541 The "leaf" statement is used to define a scalar variable of a 2542 particular built-in or derived type. 2544 7.6.1. The leaf's default value 2546 The default value of a leaf is the value that the server uses if the 2547 leaf does not exist in the data tree. The usage of the default value 2548 depends on the leaf's closest ancestor node in the schema tree which 2549 is not a non-presence container: 2551 o If no such ancestor exists in the schema tree, the default value 2552 MUST be used. 2554 o Otherwise, if this ancestor is a case node, the default value MUST 2555 be used if any node from the case exists in the data tree, or if 2556 the case node is the choice's default case, and no nodes from any 2557 other case exist in the data tree. 2559 o Otherwise, the default value MUST be used if the ancestor node 2560 exists in the data tree. 2562 In these cases, the default value is said to be in use. 2564 When the default value is in use, the server MUST operationally 2565 behave as is if the leaf was present in the data tree with the 2566 default value as its value. 2568 If a leaf has a "default" statement, the leaf's default value is the 2569 value of the "default" statement. Otherwise, if the leaf's type has 2570 a default value, and the leaf is not mandatory, then the leaf's 2571 default value is the type's default value. In all other cases, the 2572 leaf does not have a default value. 2574 7.6.2. The leaf's Substatements 2576 +--------------+---------+-------------+ 2577 | substatement | section | cardinality | 2578 +--------------+---------+-------------+ 2579 | config | 7.19.1 | 0..1 | 2580 | default | 7.6.4 | 0..1 | 2581 | description | 7.19.3 | 0..1 | 2582 | if-feature | 7.18.2 | 0..n | 2583 | mandatory | 7.6.5 | 0..1 | 2584 | must | 7.5.3 | 0..n | 2585 | reference | 7.19.4 | 0..1 | 2586 | status | 7.19.2 | 0..1 | 2587 | type | 7.6.3 | 1 | 2588 | units | 7.3.3 | 0..1 | 2589 | when | 7.19.5 | 0..1 | 2590 +--------------+---------+-------------+ 2592 7.6.3. The leaf's type Statement 2594 The "type" statement, which MUST be present, takes as an argument the 2595 name of an existing built-in or derived type. The optional 2596 substatements specify restrictions on this type. See Section 7.4 for 2597 details. 2599 7.6.4. The leaf's default Statement 2601 The "default" statement, which is optional, takes as an argument a 2602 string which contains a default value for the leaf. 2604 The value of the "default" statement MUST be valid according to the 2605 type specified in the leaf's "type" statement. 2607 The "default" statement MUST NOT be present on nodes where 2608 "mandatory" is true. 2610 7.6.5. The leaf's mandatory Statement 2612 The "mandatory" statement, which is optional, takes as an argument 2613 the string "true" or "false", and puts a constraint on valid data. 2614 If not specified, the default is "false". 2616 If "mandatory" is "true", the behavior of the constraint depends on 2617 the type of the leaf's closest ancestor node in the schema tree which 2618 is not a non-presence container (see Section 7.5.1): 2620 o If no such ancestor exists in the schema tree, the leaf MUST 2621 exist. 2623 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2624 any node from the case exists in the data tree. 2626 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2627 data tree. 2629 This constraint is enforced according to the rules in Section 8. 2631 7.6.6. XML Mapping Rules 2633 A leaf node is encoded as an XML element. The element's local name 2634 is the leaf's identifier, and its namespace is the module's XML 2635 namespace (see Section 7.1.3). 2637 The value of the leaf node is encoded to XML according to the type, 2638 and sent as character data in the element. 2640 A NETCONF server that replies to a or request MAY 2641 choose not to send the leaf element if its value is the default 2642 value. Thus, a client that receives an for a or 2643 request, MUST be prepared to handle the case that a leaf 2644 node with a default value is not present in the XML. In this case, 2645 the value used by the server is known to be the default value. 2647 See Section 7.6.8 for an example. 2649 7.6.7. NETCONF Operations 2651 When a NETCONF server processes an request, the 2652 elements of procedure for the leaf node are: 2654 If the operation is "merge" or "replace", the node is created if 2655 it does not exist, and its value is set to the value found in the 2656 XML RPC data. 2658 If the operation is "create" the node is created if it does not 2659 exist. If the node already exists, a "data-exists" error is 2660 returned. 2662 If the operation is "delete" the node is deleted if it exists. If 2663 the node does not exist, a "data-missing" error is returned. 2665 7.6.8. Usage Example 2667 Given the following leaf statement, placed in the previously defined 2668 "ssh" container (See Section 7.5.9): 2670 leaf port { 2671 type inet:port-number; 2672 default 22; 2673 description "The port which the SSH server listens to" 2674 } 2676 A corresponding XML instance example: 2678 2022 2680 To set the value of a leaf with an : 2682 2685 2686 2687 2688 2689 2690 2691 2692 2693 2022 2694 2695 2696 2697 2698 2699 2701 7.7. The leaf-list Statement 2703 Where the "leaf" statement is used to define a simple scalar variable 2704 of a particular type, the "leaf-list" statement is used to define an 2705 array of a particular type. The "leaf-list" statement takes one 2706 argument, which is an identifier, followed by a block of 2707 substatements that holds detailed leaf-list information. 2709 The values in a leaf-list MUST be unique. 2711 Conceptually, the values in the data tree are always in the canonical 2712 form (see Section 9.1). 2714 If the type referenced by the leaf-list has a default value, it has 2715 no effect in the leaf-list. 2717 7.7.1. Ordering 2719 YANG supports two styles for ordering the entries within lists and 2720 leaf-lists. In many lists, the order of list entries does not impact 2721 the implementation of the list's configuration, and the device is 2722 free to sort the list entries in any reasonable order. The 2723 "description" string for the list may suggest an order. YANG calls 2724 this style of list "system ordered" and they are indicated with the 2725 statement "ordered-by system". 2727 For example, a list of valid users would typically be sorted 2728 alphabetically, since the order in which the users appeared in the 2729 configuration would not impact the creation of those users' accounts. 2731 In the other style of lists, the order of list entries matters for 2732 the implementation of the list's configuration and the user is 2733 responsible for ordering the entries, while the device maintains that 2734 order. YANG calls this style of list "user ordered" and they are 2735 indicated with the statement "ordered-by user". 2737 For example, the order in which firewall filters entries are applied 2738 to incoming traffic may affect how that traffic is filtered. The 2739 user would need to decide if the filter entry that discards all TCP 2740 traffic should be applied before or after the filter entry that 2741 allows all traffic from trusted interfaces. The choice of order 2742 would be crucial. 2744 YANG provides a rich set of facilities within NETCONF's 2745 operation which allow the order of list entries in user-ordered lists 2746 to be controlled. List entries may be inserted or rearranged, 2747 positioned as the first or last entry in the list, or positioned 2748 before or after another specific entry. 2750 The "ordered-by" statement is covered in Section 7.7.5. 2752 7.7.2. The leaf-list's Substatements 2754 +--------------+---------+-------------+ 2755 | substatement | section | cardinality | 2756 +--------------+---------+-------------+ 2757 | config | 7.19.1 | 0..1 | 2758 | description | 7.19.3 | 0..1 | 2759 | if-feature | 7.18.2 | 0..n | 2760 | max-elements | 7.7.4 | 0..1 | 2761 | min-elements | 7.7.3 | 0..1 | 2762 | must | 7.5.3 | 0..n | 2763 | ordered-by | 7.7.5 | 0..1 | 2764 | reference | 7.19.4 | 0..1 | 2765 | status | 7.19.2 | 0..1 | 2766 | type | 7.4 | 1 | 2767 | units | 7.3.3 | 0..1 | 2768 | when | 7.19.5 | 0..1 | 2769 +--------------+---------+-------------+ 2771 7.7.3. The min-elements Statement 2773 The "min-elements" statement, which is optional, takes as an argument 2774 a non-negative integer which puts a constraint on valid list entries. 2775 A valid leaf-list or list MUST have at least min-elements entries. 2777 If no "min-elements" statement is present, it defaults to zero. 2779 The behavior of the constraint depends on the type of the leaf-list's 2780 or list's closest ancestor node in the schema tree which is not a 2781 non-presence container (see Section 7.5.1): 2783 o If this ancestor is a case node, the constraint is enforced if any 2784 other node from the case exists. 2786 o Otherwise, it is enforced if the ancestor node exists. 2788 The constraint is further enforced according to the rules in 2789 Section 8. 2791 7.7.4. The max-elements Statement 2793 The "max-elements" statement, which is optional, takes as an argument 2794 a positive integer or the string "unbounded", which puts a constraint 2795 on valid list entries. A valid leaf-list or list always has at most 2796 max-elements entries. 2798 If no "max-elements" statement is present, it defaults to 2799 "unbounded". 2801 The "max-elements" constraint is enforced according to the rules in 2802 Section 8. 2804 7.7.5. The ordered-by Statement 2806 The "ordered-by" statement defines whether the order of entries 2807 within a list are determined by the user or the system. The argument 2808 is one of the strings "system" or "user". If not present, order 2809 defaults to "system". 2811 This statement is ignored if the list represents state data, RPC 2812 output parameters, or notification content. 2814 See Section 7.7.1 for additional information. 2816 7.7.5.1. ordered-by system 2818 The entries in the list are sorted according to an unspecified order. 2819 Thus an implementation is free to sort the entries in the most 2820 appropriate order. An implementation SHOULD use the same order for 2821 the same data, regardless of how the data were created. Using a 2822 deterministic order will make comparisons possible using simple tools 2823 like "diff". 2825 This is the default order. 2827 7.7.5.2. ordered-by user 2829 The entries in the list are sorted according to an order defined by 2830 the user. This order is controlled by using special XML attributes 2831 in the request. See Section 7.7.7 for details. 2833 7.7.6. XML Mapping Rules 2835 A leaf-list node is encoded as a series of XML elements. Each 2836 element's local name is the leaf-list's identifier, and its namespace 2837 is the module's XML namespace (see Section 7.1.3). 2839 The value of each leaf-list entry is encoded to XML according to the 2840 type, and sent as character data in the element. 2842 The XML elements representing leaf-list entries MUST appear in the 2843 order specified by the user if the leaf-list is "ordered-by user", 2844 otherwise the order is implementation-dependent. The XML elements 2845 representing leaf-list entries MAY be interleaved with other sibling 2846 elements, unless the leaf-list defines RPC input or output 2847 parameters. 2849 See Section 7.7.8 for an example. 2851 7.7.7. NETCONF Operations 2853 Leaf-list entries can be created and deleted, but not modified, 2854 through , by using the "operation" attribute in the 2855 leaf-list entry's XML element. 2857 In an "ordered-by user" leaf-list, the attributes "insert" and 2858 "value" in the YANG XML namespace (Section 5.3.1) can be used to 2859 control where in the leaf-list the entry is inserted. These can be 2860 used during "create" operations to insert a new leaf-list entry, or 2861 during "merge" or "replace" operations to insert a new leaf-list 2862 entry or move an existing one. 2864 The "insert" attribute can take the values "first", "last", "before", 2865 and "after". If the value is "before" or "after", the "value" 2866 attribute MUST also be used to specify an existing entry in the leaf- 2867 list. 2869 If no "insert" attribute is present in the "create" operation, it 2870 defaults to "last". 2872 If several entries in an "ordered-by user" leaf-list are modified in 2873 the same request, the entries are modified one at the 2874 time, in the order of the XML elements in the request. 2876 In a , or an with a "replace" operation 2877 which covers the entire leaf-list, the leaf-list order is the same as 2878 the order of the XML elements in the request. 2880 When a NETCONF server processes an request, the 2881 elements of procedure for a leaf-list node are: 2883 If the operation is "merge" or "replace" the leaf-list entry is 2884 created if it does not exist. 2886 If the operation is "create" the leaf-list entry is created if it 2887 does not exist. If the leaf-list entry already exists, a 2888 "data-exists" error is returned. 2890 If the operation is "delete" the entry is deleted from the leaf- 2891 list if it exists. If the leaf-list entry does not exist, a 2892 "data-missing" error is returned. 2894 7.7.8. Usage Example 2896 leaf-list allow-user { 2897 type string; 2898 description "A list of user name patterns to allow"; 2899 } 2901 A corresponding XML instance example: 2903 alice 2904 bob 2906 To create a new element in this list, using the default 2907 operation "merge": 2909 2912 2913 2914 2915 2916 2917 2918 2919 2920 eric 2921 2922 2923 2924 2925 2926 2928 Given the following ordered-by user leaf-list: 2930 leaf-list cipher { 2931 type string; 2932 ordered-by user; 2933 description "A list of ciphers"; 2934 } 2936 The following would be used to insert a new cipher "blowfish-cbc" 2937 after "3des-cbc": 2939 2943 2944 2945 2946 2947 2948 2949 2950 2951 blowfish-cbc 2954 2955 2956 2957 2958 2959 2961 7.8. The list Statement 2963 The "list" statement is used to define an interior data node in the 2964 schema tree. A list node may exist in multiple instances in the data 2965 tree. Each such instance is known as a list entry. The "list" 2966 statement takes one argument which is an identifier, followed by a 2967 block of substatements that holds detailed list information. 2969 A list entry is uniquely identified by the values of the list's keys, 2970 if defined. 2972 A list is similar to a table where each list entry is a row in the 2973 table. 2975 7.8.1. The list's Substatements 2977 +--------------+---------+-------------+ 2978 | substatement | section | cardinality | 2979 +--------------+---------+-------------+ 2980 | anyxml | 7.10 | 0..n | 2981 | choice | 7.9 | 0..n | 2982 | config | 7.19.1 | 0..1 | 2983 | container | 7.5 | 0..n | 2984 | description | 7.19.3 | 0..1 | 2985 | grouping | 7.11 | 0..n | 2986 | if-feature | 7.18.2 | 0..n | 2987 | key | 7.8.2 | 0..1 | 2988 | leaf | 7.6 | 0..n | 2989 | leaf-list | 7.7 | 0..n | 2990 | list | 7.8 | 0..n | 2991 | max-elements | 7.7.4 | 0..1 | 2992 | min-elements | 7.7.3 | 0..1 | 2993 | must | 7.5.3 | 0..n | 2994 | ordered-by | 7.7.5 | 0..1 | 2995 | reference | 7.19.4 | 0..1 | 2996 | status | 7.19.2 | 0..1 | 2997 | typedef | 7.3 | 0..n | 2998 | unique | 7.8.3 | 0..n | 2999 | uses | 7.12 | 0..n | 3000 | when | 7.19.5 | 0..1 | 3001 +--------------+---------+-------------+ 3003 7.8.2. The list's key Statement 3005 The "key" statement, which MUST be present if the list represents 3006 configuration, and MAY be present otherwise, takes as an argument a 3007 string which specifies a space separated list of leaf identifiers of 3008 this list. A leaf identifier MUST NOT appear more than once in the 3009 key. Each such leaf identifier MUST refer to a child leaf of the 3010 list. The leafs can be defined directly in substatements to the 3011 list, or in groupings used in the list. 3013 The combined values of all the leafs specified in the key are used to 3014 uniquely identify a list entry. All key leafs MUST be given values 3015 when a list entry is created. Thus, any default values in the key 3016 leafs or their types are ignored. It also implies that any mandatory 3017 statement in the key leafs are ignored. 3019 A leaf that is part of the key can be of any built-in or derived 3020 type, except it MUST NOT be the built-in type "empty". 3022 All key leafs in a list MUST have the same value for their "config" 3023 as the list itself. 3025 The key string syntax is formally defined by the rule "key-arg" in 3026 Section 12. 3028 7.8.3. The list's unique Statement 3030 The "unique" statement is used to put constraints on valid list 3031 entries. It takes as an argument a string which contains a space 3032 separated list of schema node identifiers, which MUST be given in the 3033 descendant form (see the rule "descendant-schema-nodeid" in 3034 Section 12). Each such schema node identifier MUST refer to a leaf. 3036 If one of the referenced leafs represents configuration data, then 3037 all of the referenced leafs MUST represent configuration data. 3039 The "unique" constraint specifies that the combined values of all the 3040 leaf instances specified in the argument string, including leafs with 3041 default values, MUST be unique within all list entry instances in 3042 which all referenced leafs exist. The constraint is enforced 3043 according to the rules in Section 8. 3045 The unique string syntax is formally defined by the rule "unique-arg" 3046 in Section 12. 3048 7.8.3.1. Usage Example 3050 With the following list: 3052 list server { 3053 key "name"; 3054 unique "ip port"; 3055 leaf name { 3056 type string; 3057 } 3058 leaf ip { 3059 type inet:ip-address; 3060 } 3061 leaf port { 3062 type inet:port-number; 3063 } 3064 } 3066 The following configuration is not valid: 3068 3069 smtp 3070 192.0.2.1 3071 25 3072 3074 3075 http 3076 192.0.2.1 3077 25 3078 3080 The following configuration is valid, since the "http" and "ftp" list 3081 entries do not have a value for all referenced leafs, and are thus 3082 not taken into account when the "unique" constraint is enforced: 3084 3085 smtp 3086 192.0.2.1 3087 25 3088 3090 3091 http 3092 192.0.2.1 3093 3095 3096 ftp 3097 192.0.2.1 3098 3100 7.8.4. The list's Child Node Statements 3102 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3103 "choice", and "anyxml" statements can be used to define child nodes 3104 to the list. 3106 7.8.5. XML Mapping Rules 3108 A list is encoded as a series of XML elements, one for each entry in 3109 the list. Each element's local name is the list's identifier, and 3110 its namespace is the module's XML namespace (see Section 7.1.3). 3112 The list's key nodes are encoded as subelements to the list's 3113 identifier element, in the same order as they are defined within the 3114 key statement. 3116 The rest of the list's child nodes are encoded as subelements to the 3117 list element, after the keys. If the list defines RPC input or 3118 output parameters, the subelements are encoded in the same order as 3119 they are defined within the list statement. Otherwise, the 3120 subelements are encoded in any order. 3122 The XML elements representing list entries MUST appear in the order 3123 specified by the user if the list is "ordered-by user", otherwise the 3124 order is implementation-dependent. The XML elements representing 3125 list entries MAY be interleaved with other sibling elements, unless 3126 the list defines RPC input or output parameters. 3128 7.8.6. NETCONF Operations 3130 List entries can be created, deleted, replaced and modified through 3131 , by using the "operation" attribute in the list's XML 3132 element. In each case, the values of all keys are used to uniquely 3133 identify a list entry. If all keys are not specified for a list 3134 entry, a "missing-element" error is returned. 3136 In an "ordered-by user" list, the attributes "insert" and "key" in 3137 the YANG XML namespace (Section 5.3.1) can be used to control where 3138 in the list the entry is inserted. These can be used during "create" 3139 operations to insert a new list entry, or during "merge" or "replace" 3140 operations to insert a new list entry or move an existing one. 3142 The "insert" attribute can take the values "first", "last", "before", 3143 and "after". If the value is "before" or "after", the "key" 3144 attribute MUST also be used, to specify an existing element in the 3145 list. The value of the "key" attribute is the key predicates of the 3146 full instance identifier (see Section 9.13) for the list entry. 3148 If no "insert" attribute is present in the "create" operation, it 3149 defaults to "last". 3151 If several entries in an "ordered-by user" list are modified in the 3152 same request, the entries are modified one at the time, 3153 in the order of the XML elements in the request. 3155 In a , or an with a "replace" operation 3156 which covers the entire list, the list entry order is the same as the 3157 order of the XML elements in the request. 3159 When a NETCONF server processes an request, the 3160 elements of procedure for a list node are: 3162 If the operation is "merge" or "replace" the list entry is created 3163 if it does not exist. 3165 If the operation is "create" the list entry is created if it does 3166 not exist. If the list entry already exists, a "data-exists" 3167 error is returned. 3169 If the operation is "delete" the entry is deleted from the list if 3170 it exists. If the list entry does not exist, a "data-missing" 3171 error is returned. 3173 7.8.7. Usage Example 3175 Given the following list: 3177 list user { 3178 key "name"; 3179 config true; 3180 description "This is a list of users in the system."; 3182 leaf name { 3183 type string; 3184 } 3185 leaf type { 3186 type string; 3187 } 3188 leaf full-name { 3189 type string; 3190 } 3191 } 3193 A corresponding XML instance example: 3195 3196 fred 3197 admin 3198 Fred Flintstone 3199 3201 To create a new user "barney": 3203 3206 3207 3208 3209 3210 3211 3212 3213 barney 3214 admin 3215 Barney Rubble 3216 3217 3218 3219 3220 3222 To change the type of "fred" to "superuser": 3224 3227 3228 3229 3230 3231 3232 3233 3234 fred 3235 superuser 3236 3237 3238 3239 3240 3242 Given the following ordered-by user list: 3244 list user { 3245 description "This is a list of users in the system."; 3246 ordered-by user; 3247 config true; 3249 key "name"; 3251 leaf name { 3252 type string; 3253 } 3254 leaf type { 3255 type string; 3256 } 3257 leaf full-name { 3258 type string; 3259 } 3260 } 3262 The following would be used to insert a new user "barney" after the 3263 user "fred": 3265 3269 3270 3271 3272 3273 3274 3276 3279 barney 3280 admin 3281 Barney Rubble 3282 3283 3284 3285 3286 3288 The following would be used to move the user "barney" before the user 3289 "fred": 3291 3295 3296 3297 3298 3299 3300 3302 3305 barney 3306 3307 3308 3309 3310 3312 7.9. The choice Statement 3314 The "choice" statement defines a set of alternatives, only one of 3315 which may exist at any one time. The argument is an identifier, 3316 followed by a block of substatements that holds detailed choice 3317 information. The identifier is used to identify the choice node in 3318 the schema tree. A choice node does not exist in the data tree. 3320 A choice consists of a number of branches, defined with the "case" 3321 substatement. Each branch contains a number of child nodes. The 3322 nodes from at most one of the choice's branches exist at the same 3323 time. 3325 See Section 8.3.2 for additional information. 3327 7.9.1. The choice's Substatements 3329 +--------------+---------+-------------+ 3330 | substatement | section | cardinality | 3331 +--------------+---------+-------------+ 3332 | anyxml | 7.10 | 0..n | 3333 | case | 7.9.2 | 0..n | 3334 | config | 7.19.1 | 0..1 | 3335 | container | 7.5 | 0..n | 3336 | default | 7.9.3 | 0..1 | 3337 | description | 7.19.3 | 0..1 | 3338 | if-feature | 7.18.2 | 0..n | 3339 | leaf | 7.6 | 0..n | 3340 | leaf-list | 7.7 | 0..n | 3341 | list | 7.8 | 0..n | 3342 | mandatory | 7.9.4 | 0..1 | 3343 | reference | 7.19.4 | 0..1 | 3344 | status | 7.19.2 | 0..1 | 3345 | when | 7.19.5 | 0..1 | 3346 +--------------+---------+-------------+ 3348 7.9.2. The choice's case Statement 3350 The "case" statement is used to define branches of the choice. It 3351 takes as an argument an identifier, followed by a block of 3352 substatements that holds detailed case information. 3354 The identifier is used to identify the case node in the schema tree. 3355 A case node does not exist in the data tree. 3357 Within a "case" statement, the "anyxml", "choice", "container", 3358 "leaf", "list", "leaf-list", and "uses" statements can be used to 3359 define child nodes to the case node. The identifiers of all these 3360 child nodes MUST be unique within all cases in a choice. For 3361 example, the following is illegal: 3363 choice interface-type { // This example is illegal YANG 3364 case a { 3365 leaf ethernet { ... } 3366 } 3367 case b { 3368 container ethernet { ...} 3369 } 3370 } 3372 As a shorthand, the "case" statement can be omitted if the branch 3373 contains a single "anyxml", "container", "leaf", "list", or 3374 "leaf-list" statement. In this case, the identifier of the case node 3375 is the same as the identifier in the branch statement. The following 3376 example: 3378 choice interface-type { 3379 container ethernet { ... } 3380 } 3382 is equivalent to: 3384 choice interface-type { 3385 case ethernet { 3386 container ethernet { ... } 3387 } 3388 } 3390 The case identifier MUST be unique within a choice. 3392 7.9.2.1. The case's Substatements 3394 +--------------+---------+-------------+ 3395 | substatement | section | cardinality | 3396 +--------------+---------+-------------+ 3397 | anyxml | 7.10 | 0..n | 3398 | choice | 7.9 | 0..n | 3399 | container | 7.5 | 0..n | 3400 | description | 7.19.3 | 0..1 | 3401 | if-feature | 7.18.2 | 0..n | 3402 | leaf | 7.6 | 0..n | 3403 | leaf-list | 7.7 | 0..n | 3404 | list | 7.8 | 0..n | 3405 | reference | 7.19.4 | 0..1 | 3406 | status | 7.19.2 | 0..1 | 3407 | uses | 7.12 | 0..n | 3408 | when | 7.19.5 | 0..1 | 3409 +--------------+---------+-------------+ 3411 7.9.3. The choice's default Statement 3413 The "default" statement indicates if a case should be considered as 3414 the default if no child nodes from any of the choice's cases exist. 3415 The argument is the identifier of the "case" statement. If the 3416 "default" statement is missing, there is no default case. 3418 The "default" statement MUST NOT be present on choices where 3419 "mandatory" is true. 3421 The default case is only important when considering the default 3422 values of nodes under the cases. The default values for nodes under 3423 the default case are used if none of the nodes under any of the cases 3424 are present. 3426 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3427 the default case. 3429 Default values for child nodes under a case are only used if one of 3430 the nodes under that case is present, or if that case is the default 3431 case. If none of the nodes under a case are present and the case is 3432 not the default case, the default values of the cases' child nodes 3433 are ignored. 3435 In this example, the choice defaults to "interval", and the default 3436 value will be used if none of "daily", "time-of-day", or "manual" are 3437 present. If "daily" is present, the default value for "time-of-day" 3438 will be used. 3440 container transfer { 3441 choice how { 3442 default interval; 3443 case interval { 3444 leaf interval { 3445 type uint16; 3446 default 30; 3447 units minutes; 3448 } 3449 } 3450 case daily { 3451 leaf daily { 3452 type empty; 3453 } 3454 leaf time-of-day { 3455 type string; 3456 units 24-hour-clock; 3457 default 1am; 3458 } 3459 } 3460 case manual { 3461 leaf manual { 3462 type empty; 3463 } 3464 } 3465 } 3466 } 3468 7.9.4. The choice's mandatory Statement 3470 The "mandatory" statement, which is optional, takes as an argument 3471 the string "true" or "false", and puts a constraint on valid data. 3472 If "mandatory" is "true", at least one node from exactly one of the 3473 choice's case branches MUST exist. 3475 If not specified, the default is "false". 3477 The behavior of the constraint depends on the type of the choice's 3478 closest ancestor node in the schema tree which is not a non-presence 3479 container (see Section 7.5.1): 3481 o If this ancestor is a case node, the constraint is enforced if any 3482 other node from the case exists. 3484 o Otherwise, it is enforced if the ancestor node exists. 3486 The constraint is further enforced according to the rules in 3487 Section 8. 3489 7.9.5. XML Mapping Rules 3491 The choice and case nodes are not visible in XML. 3493 The child nodes of the selected "case" statement MUST be encoded in 3494 the same order as they are defined in the "case" statement if they 3495 are part of a RPC input or output parameter definition. Otherwise, 3496 the subelements are encoded in any order. 3498 7.9.6. NETCONF Operations 3500 Since only one of the choice's cases can be valid at any time, the 3501 creation of a node from one case implicitly deletes all nodes from 3502 all other cases. If an operation creates a node from a 3503 case, the NETCONF server will delete any existing nodes that are 3504 defined in other cases inside the choice. 3506 7.9.7. Usage Example 3508 Given the following choice: 3510 container protocol { 3511 choice name { 3512 case a { 3513 leaf udp { 3514 type empty; 3515 } 3516 } 3517 case b { 3518 leaf tcp { 3519 type empty; 3520 } 3521 } 3522 } 3523 } 3525 A corresponding XML instance example: 3527 3528 3529 3531 To change the protocol from tcp to udp: 3533 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3550 7.10. The anyxml Statement 3552 The "anyxml" statement defines an interior node in the schema tree. 3553 It takes one argument, which is an identifier, followed by a block of 3554 substatements that holds detailed anyxml information. 3556 The anyxml statement is used to represent an unknown chunk of XML. 3557 No restrictions are placed on the XML. This can be useful, for 3558 example, in RPC replies. An example is the parameter in the 3559 operation. 3561 An anyxml node cannot be augmented. 3563 Since the use of anyxml limits the manipulation of the content, it is 3564 RECOMMENDED that the anyxml statement not be used to represent 3565 configuration data. 3567 An anyxml node exists in zero or one instances in the data tree. 3569 7.10.1. The anyxml's Substatements 3571 +--------------+---------+-------------+ 3572 | substatement | section | cardinality | 3573 +--------------+---------+-------------+ 3574 | config | 7.19.1 | 0..1 | 3575 | description | 7.19.3 | 0..1 | 3576 | if-feature | 7.18.2 | 0..n | 3577 | mandatory | 7.6.5 | 0..1 | 3578 | must | 7.5.3 | 0..n | 3579 | reference | 7.19.4 | 0..1 | 3580 | status | 7.19.2 | 0..1 | 3581 | when | 7.19.5 | 0..1 | 3582 +--------------+---------+-------------+ 3584 7.10.2. XML Mapping Rules 3586 An anyxml node is encoded as an XML element. The element's local 3587 name is the anyxml's identifier, and its namespace is the module's 3588 XML namespace (see Section 7.1.3). The value of the anyxml node is 3589 encoded as XML content of this element. 3591 Note that any prefixes used in the encoding are local to each 3592 instance encoding. This means that the same XML may be encoded 3593 differently by different implementations. 3595 7.10.3. NETCONF Operations 3597 An anyxml node is treated as an opaque chunk of data. This data can 3598 be modified in its entirety only. 3600 Any "operation" attributes present on subelements of an anyxml node 3601 are ignored by the NETCONF server. 3603 When a NETCONF server processes an request, the 3604 elements of procedure for the anyxml node are: 3606 If the operation is "merge" or "replace", the node is created if 3607 it does not exist, and its value is set to the XML content of the 3608 anyxml node found in the XML RPC data. 3610 If the operation is "create" the node is created if it does not 3611 exist, and its value is set to the XML content of the anyxml node 3612 found in the XML RPC data. If the node already exists, a 3613 "data-exists" error is returned. 3615 If the operation is "delete" the node is deleted if it exists. If 3616 the node does not exist, a "data-missing" error is returned. 3618 7.10.4. Usage Example 3620 Given the following anyxml statement: 3622 anyxml data; 3624 The following are two valid encodings of the same anyxml value: 3626 3627 3628 1 3629 3630 3632 3633 3634 1 3635 3636 3638 7.11. The grouping Statement 3640 The "grouping" statement is used to define a reusable block of nodes, 3641 which may be used locally in the module, in modules which include it, 3642 and by other modules which import from it, according to the rules in 3643 Section 5.5. It takes one argument which is an identifier, followed 3644 by a block of substatements that holds detailed grouping information. 3646 The grouping statement is not a data definition statement and, as 3647 such, does not define any nodes in the schema tree. 3649 A grouping is like a "structure" or a "record" in conventional 3650 programming languages. 3652 Once a grouping is defined, it can be referenced in a "uses" 3653 statement (see Section 7.12). A grouping MUST NOT reference itself, 3654 neither directly nor indirectly through a chain of other groupings. 3656 If the grouping is defined at the top level of a YANG module or 3657 submodule, the grouping's identifier MUST be unique within the 3658 module. 3660 A grouping is more than just a mechanism for textual substitution, 3661 but defines a collection of nodes. Identifiers appearing inside the 3662 grouping are resolved relative to the scope in which the grouping is 3663 defined, not where it is used. Prefix mappings, type names, grouping 3664 names, and extension usage are evaluated in the hierarchy where the 3665 grouping statement appears. For extensions, this means that 3666 extensions are applied to the grouping node, not the uses node. 3668 7.11.1. The grouping's Substatements 3670 +--------------+---------+-------------+ 3671 | substatement | section | cardinality | 3672 +--------------+---------+-------------+ 3673 | anyxml | 7.10 | 0..n | 3674 | choice | 7.9 | 0..n | 3675 | container | 7.5 | 0..n | 3676 | description | 7.19.3 | 0..1 | 3677 | grouping | 7.11 | 0..n | 3678 | leaf | 7.6 | 0..n | 3679 | leaf-list | 7.7 | 0..n | 3680 | list | 7.8 | 0..n | 3681 | reference | 7.19.4 | 0..1 | 3682 | status | 7.19.2 | 0..1 | 3683 | typedef | 7.3 | 0..n | 3684 | uses | 7.12 | 0..n | 3685 +--------------+---------+-------------+ 3687 7.11.2. Usage Example 3689 import ietf-inet-types { 3690 prefix "inet"; 3691 } 3693 grouping endpoint { 3694 description "A reusable endpoint group."; 3695 leaf ip { 3696 type inet:ip-address; 3697 } 3698 leaf port { 3699 type inet:port-number; 3700 } 3701 } 3703 7.12. The uses Statement 3705 The "uses" statement is used to reference a "grouping" definition. 3706 It takes one argument, which is the name of the grouping. 3708 The effect of a "uses" reference to a grouping is that the nodes 3709 defined by the grouping are copied into the current schema tree, and 3710 then updated according to the refinement and augment statements. 3712 The identifiers defined in the grouping are not bound to a namespace 3713 until the contents of the grouping are added to the schema tree via a 3714 "uses" statement that does not appear inside a "grouping" statement, 3715 at which point they are bound to the namespace of the current module. 3717 7.12.1. The uses's Substatements 3719 +--------------+---------+-------------+ 3720 | substatement | section | cardinality | 3721 +--------------+---------+-------------+ 3722 | augment | 7.15 | 0..1 | 3723 | description | 7.19.3 | 0..1 | 3724 | if-feature | 7.18.2 | 0..n | 3725 | refine | 7.12.2 | 0..1 | 3726 | reference | 7.19.4 | 0..1 | 3727 | status | 7.19.2 | 0..1 | 3728 | when | 7.19.5 | 0..1 | 3729 +--------------+---------+-------------+ 3731 7.12.2. The refine Statement 3733 Some of the properties of each node in the grouping can be refined 3734 with the "refine" statement. The argument is a string which 3735 identifies a node in the grouping. This node is called the refine's 3736 target node. If a node in the grouping is not present as a target 3737 node of a refine statement, it is not refined, and thus used exactly 3738 as it was defined in the grouping. 3740 The argument string is a descendant schema node identifier (see 3741 Section 6.5). 3743 The following refinements can be done: 3745 o A leaf or choice node may get a default value, or a new default 3746 value if it already had one. 3748 o Any node may get a specialized "description" string. 3750 o Any node may get a specialized "reference" string. 3752 o Any node may get a different "config" statement. 3754 o A leaf, anyxml, or choice node may get a different "mandatory" 3755 statement. 3757 o A container node may get a "presence" statement. 3759 o A leaf, leaf-list, list, container, or anyxml node may get 3760 additional "must" expressions. 3762 o A leaf-list or list node may get a different "min-elements" or 3763 "max-elements" statement. 3765 7.12.3. XML Mapping Rules 3767 Each node in the grouping is encoded as if it was defined inline, 3768 even if it is imported from another module with another XML 3769 namespace. 3771 7.12.4. Usage Example 3773 To use the "endpoint" grouping defined in Section 7.11.2 in a 3774 definition of an HTTP server in some other module, we can do: 3776 import acme-system { 3777 prefix "acme"; 3778 } 3780 container http-server { 3781 leaf name { 3782 type string; 3783 } 3784 uses acme:endpoint; 3785 } 3787 A corresponding XML instance example: 3789 3790 extern-web 3791 192.0.2.1 3792 80 3793 3795 If port 80 should be the default for the HTTP server, default can be 3796 added: 3798 container http-server { 3799 leaf name { 3800 type string; 3801 } 3802 uses acme:endpoint { 3803 refine port { 3804 default 80; 3805 } 3806 } 3807 } 3809 If we want to define a list of servers, and each server has the ip 3810 and port as keys, we can do: 3812 list server { 3813 key "ip port"; 3814 leaf name { 3815 type string; 3816 } 3817 uses acme:endpoint; 3818 } 3820 The following is an error: 3822 container http-server { 3823 uses acme:endpoint; 3824 leaf ip { // illegal - same identifier "ip" used twice 3825 type string; 3826 } 3827 } 3829 7.13. The rpc Statement 3831 The "rpc" statement is used to define a NETCONF RPC operation. It 3832 takes one argument, which is an identifier, followed by a block of 3833 substatements that holds detailed rpc information. This argument is 3834 the name of the RPC, and is used as the element name directly under 3835 the element, as designated by the substitution group 3836 "rpcOperation" in [RFC4741]. 3838 The "rpc" statement defines an rpc node in the schema tree. Under 3839 the rpc node, a schema node with the name "input", and a schema node 3840 with the name "output" are also defined. The nodes "input" and 3841 "output" are defined in the module's namespace. 3843 7.13.1. The rpc's Substatements 3845 +--------------+---------+-------------+ 3846 | substatement | section | cardinality | 3847 +--------------+---------+-------------+ 3848 | description | 7.19.3 | 0..1 | 3849 | grouping | 7.11 | 0..n | 3850 | if-feature | 7.18.2 | 0..n | 3851 | input | 7.13.2 | 0..1 | 3852 | output | 7.13.3 | 0..1 | 3853 | reference | 7.19.4 | 0..1 | 3854 | status | 7.19.2 | 0..1 | 3855 | typedef | 7.3 | 0..n | 3856 +--------------+---------+-------------+ 3858 7.13.2. The input Statement 3860 The "input" statement, which is optional, is used to define input 3861 parameters to the RPC operation. It does not take an argument. The 3862 substatements to "input" define nodes under the RPC's input node. 3864 If a leaf in the input tree has a "mandatory" statement with the 3865 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3866 Otherwise, the server MUST return a "missing-element" error. 3868 If a leaf in the input tree has a default value, the NETCONF server 3869 MUST use this value in the same cases as described in Section 7.6.1. 3870 In these cases, the server MUST operationally behave as if the leaf 3871 was present in the NETCONF RPC invocation with the default value as 3872 its value. 3874 If a "config" statement is present for any node in the input tree, 3875 the "config" statement is ignored. 3877 If any node has a "when" statement which would evaluate to false, 3878 then this node MUST NOT be present in the input tree. 3880 7.13.2.1. The input's Substatements 3882 +--------------+---------+-------------+ 3883 | substatement | section | cardinality | 3884 +--------------+---------+-------------+ 3885 | anyxml | 7.10 | 0..n | 3886 | choice | 7.9 | 0..n | 3887 | container | 7.5 | 0..n | 3888 | grouping | 7.11 | 0..n | 3889 | leaf | 7.6 | 0..n | 3890 | leaf-list | 7.7 | 0..n | 3891 | list | 7.8 | 0..n | 3892 | typedef | 7.3 | 0..n | 3893 | uses | 7.12 | 0..n | 3894 +--------------+---------+-------------+ 3896 7.13.3. The output Statement 3898 The "output" statement, which is optional, is used to define output 3899 parameters to the RPC operation. It does not take an argument. The 3900 substatements to "output" define nodes under the RPC's output node. 3902 If a leaf in the output tree has a "mandatory" statement with the 3903 value "true", the leaf MUST be present in a NETCONF RPC reply. 3905 If a leaf in the output tree has a default value, the NETCONF client 3906 MUST use this value in the same cases as described in Section 7.6.1. 3907 In these cases, the client MUST operationally behave as if the leaf 3908 was present in the NETCONF RPC reply with the default value as its 3909 value. 3911 If a "config" statement is present for any node in the output tree, 3912 the "config" statement is ignored. 3914 If any node has a "when" statement which would evaluate to false, 3915 then this node MUST NOT be present in the output tree. 3917 7.13.3.1. The output's Substatements 3919 +--------------+---------+-------------+ 3920 | substatement | section | cardinality | 3921 +--------------+---------+-------------+ 3922 | anyxml | 7.10 | 0..n | 3923 | choice | 7.9 | 0..n | 3924 | container | 7.5 | 0..n | 3925 | grouping | 7.11 | 0..n | 3926 | leaf | 7.6 | 0..n | 3927 | leaf-list | 7.7 | 0..n | 3928 | list | 7.8 | 0..n | 3929 | typedef | 7.3 | 0..n | 3930 | uses | 7.12 | 0..n | 3931 +--------------+---------+-------------+ 3933 7.13.4. XML Mapping Rules 3935 An rpc node is encoded as a child XML element to the element 3936 defined in [RFC4741]. The element's local name is the rpc's 3937 identifier, and its namespace is the module's XML namespace (see 3938 Section 7.1.3). 3940 Input parameters are encoded as child XML elements to the rpc node's 3941 XML element, in the same order as they are defined within the input 3942 statement. 3944 If the RPC operation invocation succeeded, and no output parameters 3945 are returned, the contains a single element defined 3946 in [RFC4741]. If output parameters are returned, they are encoded as 3947 child elements to the element defined in [RFC4741], in 3948 the same order as they are defined within the output statement. 3950 7.13.5. Usage Example 3952 The following example defines an RPC operation: 3954 module rock { 3955 namespace "http://example.net/rock"; 3956 prefix "rock"; 3958 rpc rock-the-house { 3959 input { 3960 leaf zip-code { 3961 type string; 3962 } 3963 } 3964 } 3966 } 3968 A corresponding XML instance example of the complete rpc and rpc- 3969 reply: 3971 3973 3974 27606-0100 3975 3976 3978 3980 3981 3983 7.14. The notification Statement 3985 The "notification" statement is used to define a NETCONF 3986 notification. It takes one argument, which is an identifier, 3987 followed by a block of substatements that holds detailed notification 3988 information. The "notification" statement defines a notification 3989 node in the schema tree. 3991 If a leaf in the notification tree has a "mandatory" statement with 3992 the value "true", the leaf MUST be present in a NETCONF notification. 3994 If a leaf in the notification tree has a default value, the NETCONF 3995 client MUST use this value in the same cases as described in 3996 Section 7.6.1. In these cases, the client MUST operationally behave 3997 as if the leaf was present in the NETCONF notification with the 3998 default value as its value. 4000 If a "config" statement is present for any node in the notification 4001 tree, the "config" statement is ignored. 4003 7.14.1. The notification's Substatements 4005 +--------------+---------+-------------+ 4006 | substatement | section | cardinality | 4007 +--------------+---------+-------------+ 4008 | anyxml | 7.10 | 0..n | 4009 | choice | 7.9 | 0..n | 4010 | container | 7.5 | 0..n | 4011 | description | 7.19.3 | 0..1 | 4012 | grouping | 7.11 | 0..n | 4013 | if-feature | 7.18.2 | 0..n | 4014 | leaf | 7.6 | 0..n | 4015 | leaf-list | 7.7 | 0..n | 4016 | list | 7.8 | 0..n | 4017 | reference | 7.19.4 | 0..1 | 4018 | status | 7.19.2 | 0..1 | 4019 | typedef | 7.3 | 0..n | 4020 | uses | 7.12 | 0..n | 4021 +--------------+---------+-------------+ 4023 7.14.2. XML Mapping Rules 4025 A notification node is encoded as a child XML element to the 4026 element defined in NETCONF Event Notifications 4027 [RFC5277]. The element's local name is the notification's 4028 identifier, and its namespace is the module's XML namespace (see 4029 Section 7.1.3). 4031 7.14.3. Usage Example 4033 The following example defines a notification: 4035 module event { 4037 namespace "http://example.com/event"; 4038 prefix "ev"; 4040 notification event { 4041 leaf event-class { 4042 type string; 4043 } 4044 anyxml reporting-entity; 4045 leaf severity { 4046 type string; 4047 } 4048 } 4049 } 4051 A corresponding XML instance example of the complete notification: 4053 4055 2008-07-08T00:01:00Z 4056 4057 fault 4058 4059 Ethernet0 4060 4061 major 4062 4063 4065 7.15. The augment Statement 4067 The "augment" statement allows a module or submodule to add to the 4068 schema tree defined in an external module, or the current module and 4069 its submodules, and to add to the nodes from a grouping in a "uses" 4070 statement. The argument is a string which identifies a node in the 4071 schema tree. This node is called the augment's target node. The 4072 target node MUST be either a container, list, choice, case, input, 4073 output, or notification node. It is augmented with the nodes defined 4074 in the substatements that follow the "augment" statement. 4076 The argument string is a schema node identifier (see Section 6.5). 4077 If the "augment" statement is on the top-level in a module or 4078 submodule, the absolute form (defined by the rule 4079 "absolute-schema-nodeid" in Section 12) of a schema node identifier 4080 MUST be used. If the "augment" statement is a substatement to the 4081 "uses" statement, the descendant form (defined by the rule 4082 "descendant-schema-nodeid" in Section 12) MUST be used. 4084 If the target node is a container, list, case, input, output, or 4085 notification node, the "container", "leaf", "list", "leaf-list", 4086 "uses", and "choice" statements can be used within the "augment" 4087 statement. 4089 If the target node is a choice node, the "case" statement, or a case 4090 shorthand statement (see Section 7.9.2) can be used within the 4091 "augment" statement. 4093 If the target node is in another module, then nodes added by the 4094 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4096 The augment statement MUST NOT add multiple nodes with the same name 4097 from the same module to the target node. 4099 7.15.1. The augment's Substatements 4101 +--------------+---------+-------------+ 4102 | substatement | section | cardinality | 4103 +--------------+---------+-------------+ 4104 | anyxml | 7.10 | 0..n | 4105 | case | 7.9.2 | 0..n | 4106 | choice | 7.9 | 0..n | 4107 | container | 7.5 | 0..n | 4108 | description | 7.19.3 | 0..1 | 4109 | if-feature | 7.18.2 | 0..n | 4110 | leaf | 7.6 | 0..n | 4111 | leaf-list | 7.7 | 0..n | 4112 | list | 7.8 | 0..n | 4113 | reference | 7.19.4 | 0..1 | 4114 | status | 7.19.2 | 0..1 | 4115 | uses | 7.12 | 0..n | 4116 | when | 7.19.5 | 0..1 | 4117 +--------------+---------+-------------+ 4119 7.15.2. XML Mapping Rules 4121 All data nodes defined in the "augment" statement are defined as XML 4122 elements in the XML namespace of the module where the "augment" is 4123 specified. 4125 When a node is augmented, the augmenting child nodes are encoded as 4126 subelements to the augmented node, in any order. 4128 7.15.3. Usage Example 4130 In namespace http://example.com/schema/interfaces, we have: 4132 container interfaces { 4133 list ifEntry { 4134 key "ifIndex"; 4136 leaf ifIndex { 4137 type uint32; 4138 } 4139 leaf ifDescr { 4140 type string; 4141 } 4142 leaf ifType { 4143 type iana:IfType; 4144 } 4145 leaf ifMtu { 4146 type int32; 4147 } 4148 } 4149 } 4151 Then in namespace http://example.com/schema/ds0, we have: 4153 import interface-module { 4154 prefix "if"; 4155 } 4156 augment "/if:interfaces/if:ifEntry" { 4157 when "if:ifType='ds0'"; 4158 leaf ds0ChannelNumber { 4159 type ChannelNumber; 4160 } 4161 } 4163 A corresponding XML instance example: 4165 4167 4168 1 4169 Flintstone Inc Ethernet A562 4170 ethernetCsmacd 4171 1500 4172 4173 4174 2 4175 Flintstone Inc DS0 4176 ds0 4177 1 4178 4179 4181 As another example, suppose we have the choice defined in 4182 Section 7.9.7. The following construct can be used to extend the 4183 protocol definition: 4185 augment /ex:system/ex:protocol/ex:name { 4186 case c { 4187 leaf smtp { 4188 type empty; 4189 } 4190 } 4191 } 4193 A corresponding XML instance example: 4195 4196 4197 4198 4199 4201 or 4203 4204 4205 4206 4207 4209 7.16. The identity Statement 4211 The "identity" statement is used to define a new globally unique, 4212 abstract and untyped identity. Its only purpose is to denote its 4213 name, semantics, and existence. An identity can be defined either 4214 from scratch or derived from a base identity. The identity's 4215 argument is an identifier that is the name of the identity. It is 4216 followed by a block of substatements that holds detailed identity 4217 information. 4219 The built-in datatype "identityref" (see Section 9.10) can be used to 4220 reference identities within a data model. 4222 7.16.1. The identity's Substatements 4224 +--------------+---------+-------------+ 4225 | substatement | section | cardinality | 4226 +--------------+---------+-------------+ 4227 | base | 7.16.2 | 0..1 | 4228 | description | 7.19.3 | 0..1 | 4229 | reference | 7.19.4 | 0..1 | 4230 | status | 7.19.2 | 0..1 | 4231 +--------------+---------+-------------+ 4233 7.16.2. The base Statement 4235 The base statement, which is optional, takes as an argument a string 4236 which is the name of an existing identity, from which the new 4237 identity is derived. If no base statement is present, the identity 4238 is defined from scratch. 4240 If a prefix is present on the base name, it refers to an identity 4241 defined in the module which was imported with that prefix, or the 4242 local module if the prefix matches the local module's prefix. 4243 Otherwise an identity with the matching name MUST be defined in the 4244 current module or an included submodule. 4246 Since submodules cannot include the parent module, any identities in 4247 the module which need to be exposed to submodules MUST be defined in 4248 a submodule. Submodules can then include this submodule to find the 4249 definition of the identity. 4251 An identity MUST NOT reference itself, neither directly nor 4252 indirectly through a chain of other identities. 4254 7.16.3. Usage Example 4256 module crypto-base { 4257 namespace "http://example.com/crypto-base"; 4258 prefix "crypto"; 4260 identity crypto-alg { 4261 description 4262 "Base identity from which all crypto algorithms 4263 are derived."; 4264 } 4265 } 4267 module des { 4268 namespace "http://example.com/des"; 4269 prefix "des"; 4271 import "crypto-base" { 4272 prefix "crypto"; 4273 } 4275 identity des { 4276 base "crypto:crypto-alg"; 4277 description "DES crypto algorithm"; 4278 } 4280 identity des3 { 4281 base "crypto:crypto-alg"; 4282 description "Triple DES crypto algorithm"; 4283 } 4284 } 4286 7.17. The extension Statement 4288 The "extension" statement allows the definition of new statements 4289 within the YANG language. This new statement definition can be 4290 imported and used by other modules. 4292 The statement's argument is an identifier that is the new keyword for 4293 the extension and must be followed by a block of substatements that 4294 holds detailed extension information. The purpose of the extension 4295 statement is to define a keyword, so that it can be imported and used 4296 by other modules. 4298 The extension can be used like a normal YANG statement, with the 4299 statement name followed by an argument if one is defined by the 4300 extension, and an optional block of substatements. The statement's 4301 name is created by combining the prefix of the module in which the 4302 extension was defined, a colon (":"), and the extension's keyword, 4303 with no interleaving whitespace. The substatements of an extension 4304 are defined by the extension, using some mechanism outside the scope 4305 of this specification. Syntactically, the substatements MUST be YANG 4306 statements, or also defined using "extension" statements. YANG 4307 statements in extensions MUST follow the syntactical rules in 4308 Section 12. 4310 7.17.1. The extension's Substatements 4312 +--------------+---------+-------------+ 4313 | substatement | section | cardinality | 4314 +--------------+---------+-------------+ 4315 | argument | 7.17.2 | 0..1 | 4316 | description | 7.19.3 | 0..1 | 4317 | reference | 7.19.4 | 0..1 | 4318 | status | 7.19.2 | 0..1 | 4319 +--------------+---------+-------------+ 4321 7.17.2. The argument Statement 4323 The "argument" statement, which is optional, takes as an argument a 4324 string which is the name of the argument to the keyword. If no 4325 argument statement is present, the keyword expects no argument when 4326 it is used. 4328 The argument's name is used in the YIN mapping, where it is used as 4329 an XML attribute or element name, depending on the argument's text 4330 statement. 4332 7.17.2.1. The argument's Substatements 4334 +--------------+----------+-------------+ 4335 | substatement | section | cardinality | 4336 +--------------+----------+-------------+ 4337 | yin-element | 7.17.2.2 | 0..1 | 4338 +--------------+----------+-------------+ 4340 7.17.2.2. The yin-element Statement 4342 The "yin-element" statement, which is optional, takes as an argument 4343 the string "true" or "false". This statement indicates if the 4344 argument is mapped to an XML element in YIN or to an XML attribute. 4345 (see Section 11). 4347 If no "yin-element" statement is present, it defaults to "false". 4349 7.17.3. Usage Example 4351 To define an extension: 4353 module my-extensions { 4354 ... 4356 extension c-define { 4357 description 4358 "Takes as argument a name string. 4359 Makes the code generator use the given name in the 4360 #define."; 4361 argument "name"; 4362 } 4363 } 4365 To use the extension: 4367 module my-interfaces { 4368 ... 4369 import my-extensions { 4370 prefix "myext"; 4371 } 4372 ... 4374 container interfaces { 4375 ... 4376 myext:c-define "MY_INTERFACES"; 4377 } 4378 } 4380 7.18. Conformance-related Statements 4382 This section defines statements related to conformance, as described 4383 in Section 5.6. 4385 7.18.1. The feature Statement 4387 The "feature" statement is used to define a mechanism by which 4388 portions of the schema are marked as conditional. A feature name is 4389 defined that can later be referenced using the "if-feature" statement 4390 (see Section 7.18.2). Schema nodes tagged with a feature are ignored 4391 unless the device supports the given feature. This allows portions 4392 of the YANG module to be conditional based on conditions on the 4393 device. The model can represent the abilities of the device within 4394 the model, giving a richer model that allows for differing device 4395 abilities and roles. 4397 The argument to the "feature" statement is the name of the new 4398 feature, and follows the rules for identifiers in Section 6.2. This 4399 name is used by the "if-feature" statement to tie the schema nodes to 4400 the feature. 4402 In this example, a feature called "local-storage" represents the 4403 ability for a device to store syslog messages on local storage of 4404 some sort. This feature is used to make the "local-storage-limit" 4405 leaf conditional on the presence of some sort of local storage. If 4406 the device does not report that it supports this feature, the 4407 "local-storage-limit" node is not supported. 4409 module syslog { 4410 ... 4411 feature local-storage { 4412 description 4413 "This feature means the device supports local 4414 storage (memory, flash or disk) that can be used to 4415 store syslog messages."; 4416 } 4418 container syslog { 4419 leaf local-storage-limit { 4420 if-feature local-storage; 4421 type uint64; 4422 units "kilobyte"; 4423 config false; 4424 description 4425 "The amount of local storage that can be 4426 used to hold syslog messages."; 4427 } 4428 } 4429 } 4431 The "if-feature" statement can be used in many places within the YANG 4432 syntax. Definitions tagged with "if-feature" are ignored when the 4433 device does not support that feature. 4435 A feature MUST NOT reference itself, neither directly nor indirectly 4436 through a chain of other features. 4438 If a feature is dependent on any other features (i.e., the feature 4439 has one or more "if-feature" sub-statements), then all of features it 4440 depends on MUST also be implemented by the device. 4442 7.18.1.1. The feature's Substatements 4444 +--------------+---------+-------------+ 4445 | substatement | section | cardinality | 4446 +--------------+---------+-------------+ 4447 | description | 7.19.3 | 0..1 | 4448 | if-feature | 7.18.2 | 0..n | 4449 | status | 7.19.2 | 0..1 | 4450 | reference | 7.19.4 | 0..1 | 4451 +--------------+---------+-------------+ 4453 7.18.2. The if-feature Statement 4455 The "if-feature" statement makes its parent statement conditional. 4456 The argument is the name of a feature, as defined by a "feature" 4457 statement. The parent statement is implemented by servers that 4458 support this feature. If a prefix is present on the feature name, it 4459 refers to a feature defined in the module which was imported with 4460 that prefix, or the local module if the prefix matches the local 4461 module's prefix. Otherwise a feature with the matching name MUST be 4462 defined in the current module or an included submodule. 4464 Since submodules cannot include the parent module, any features in 4465 the module which need to be exposed to submodules MUST be defined in 4466 a submodule. Submodules can then include this submodule to find the 4467 definition of the feature. 4469 7.18.3. The deviation Statement 4471 The deviation statement defines a hierarchy of a module which the 4472 device does not implement faithfully. The argument is a string that 4473 identifies the node in the schema tree where a deviation from the 4474 module occurs. This node is called the deviation's target node. The 4475 contents of the deviation statement give details about the deviation. 4477 The argument string is an absolute schema node identifier (see 4478 Section 6.5). 4480 Deviations define the way a device or class of devices deviate from a 4481 standard. This means that deviations MUST never be part of a 4482 published standard, since they are the mechanism for learning how 4483 implementations vary from the standards. 4485 Device deviations are strongly discouraged and SHOULD only be used as 4486 a last resort. Telling the application how a device fails to follow 4487 a standard is no substitute for implementing the standard correctly. 4489 However in some cases a particular device may not have the hardware 4490 or software ability to support parts of a standard module. When this 4491 occurs, the device makes a choice to treat attempts to configure 4492 unsupported parts of the module as either an error that is reported 4493 back to the unsuspecting application, or ignore those incoming 4494 requests. Neither choice is acceptable. 4496 Instead, YANG allows devices to document portions of a base module 4497 which are not supported or supported but with different syntax, by 4498 using the "deviation" statement. 4500 7.18.3.1. The deviation's Substatements 4502 +--------------+----------+-------------+ 4503 | substatement | section | cardinality | 4504 +--------------+----------+-------------+ 4505 | description | 7.19.3 | 0..1 | 4506 | deviate | 7.18.3.2 | 1..n | 4507 | reference | 7.19.4 | 0..1 | 4508 +--------------+----------+-------------+ 4510 7.18.3.2. The deviate Statement 4512 The "deviate" statement defines how the device's implementation of 4513 the target node deviates from its original definition. The argument 4514 is one of the strings "not-supported", "add", "replace", or "delete". 4516 The argument "not-supported" indicates that the target node is not 4517 implemented by this device. 4519 The argument "add" adds properties to the target node. The 4520 properties to add are identified as a substatement to the "deviate" 4521 statement. If the property can only appear once, the property MUST 4522 NOT exist in the target node. 4524 The argument "replace" replaces properties of the target node. The 4525 properties to replace are identified by substatements to the 4526 "deviate" statement. The property to replace MUST exist in the 4527 target node. 4529 The argument "delete" deletes properties from the target node. The 4530 properties to delete are identified by substatement to the "delete" 4531 statement. The substatement's keyword MUST match a corresponding 4532 keyword in the target node, and the argument's string MUST be equal 4533 to the corresponding keyword's argument string in the target node. 4535 The deviates's Substatements 4537 +--------------+---------+-------------+ 4538 | substatement | section | cardinality | 4539 +--------------+---------+-------------+ 4540 | config | 7.19.1 | 0..1 | 4541 | default | 7.6.4 | 0..1 | 4542 | mandatory | 7.6.5 | 0..1 | 4543 | max-elements | 7.7.4 | 0..1 | 4544 | min-elements | 7.7.3 | 0..1 | 4545 | must | 7.5.3 | 0..n | 4546 | type | 7.4 | 0..1 | 4547 | unique | 7.8.3 | 0..n | 4548 | units | 7.3.3 | 0..1 | 4549 +--------------+---------+-------------+ 4551 7.18.3.3. Usage Example 4553 In this example, the device is informing client applications that it 4554 does not support the old RFC867-style "daytime" service. 4556 deviation /base:system/base:daytime { 4557 deviate not-supported; 4558 } 4560 The following example sets a device-specific default value to a leaf 4561 that does not have a default value defined: 4563 deviation /base:system/base:user/base:type { 4564 deviate add { 4565 default "admin"; // new users are 'admin' by default 4566 } 4567 } 4569 In this example, the device limits the number of name servers to 3: 4571 deviation /base:system/base:name-server { 4572 deviate replace { 4573 max-elements 3; 4574 } 4575 } 4577 If the original definition is: 4579 container system { 4580 must "daytime or time"; 4581 ... 4582 } 4584 a device might remove this must constraint by doing: 4586 deviation "/base:system" { 4587 deviate delete { 4588 must "daytime or time"; 4589 } 4590 } 4592 7.19. Common Statements 4594 This section defines sub-statements common to several other 4595 statements. 4597 7.19.1. The config Statement 4599 The "config" statement takes as an argument the string "true" or 4600 "false". If "config" is "true", the definition represents 4601 configuration. Data nodes representing configuration will be part of 4602 the reply to a request, and can be sent in a 4603 or request. 4605 If "config" is "false", the definition represents state data. Data 4606 nodes representing state data will be part of the reply to a , 4607 but not to a request. 4609 If "config" is not specified, the default is the same as the parent 4610 schema node's "config" value. If the parent node is a "case" node, 4611 the value is the same as the "case" node's parent "choice" node. 4613 If the top node does not specify a "config" statement, the default is 4614 "true". 4616 If a node has "config" "false", no node underneath it can have 4617 "config" set to "true". 4619 7.19.2. The status Statement 4621 The "status" statement takes as an argument one of the strings 4622 "current", "deprecated", or "obsolete". 4624 o "current" means that the definition is current and valid. 4626 o "deprecated" indicates an obsolete definition, but it permits new/ 4627 continued implementation in order to foster interoperability with 4628 older/existing implementations. 4630 o "obsolete" means the definition is obsolete and SHOULD NOT be 4631 implemented and/or can be removed from implementations. 4633 If no status is specified, the default is "current". 4635 If a definition is "current", it MUST NOT reference a "deprecated" or 4636 "obsolete" definition within the same module. 4638 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4639 definition within the same module. 4641 7.19.3. The description Statement 4643 The "description" statement takes as an argument a string which 4644 contains a high-level textual description of this definition. 4646 7.19.4. The reference Statement 4648 The "reference" statement takes as an argument a string which is used 4649 to specify a textual cross-reference to an external document, either 4650 another module which defines related management information, or a 4651 document which provides additional information relevant to this 4652 definition. 4654 7.19.5. The when Statement 4656 The "when" statement makes its parent data definition statement 4657 conditional. The node defined by the parent data definition 4658 statement is only valid when the condition specified by the "when" 4659 statement is satisfied. The statement's argument is an XPath 4660 expression, which is used to formally specify this condition. If the 4661 XPath expression conceptually evaluates to "true" for a particular 4662 instance, then the node defined by the parent data definition 4663 statement is valid, otherwise it is not. 4665 See Section 8.3.2 for additional information. 4667 The XPath expression is conceptually evaluated in the following 4668 context, in addition to the definition in Section 6.4.1: 4670 o If the "when" statement is a child of an "augment" statement, then 4671 the context node is the augment's target node in the data tree, if 4672 the target node is a data node. Otherwise, the context node is 4673 the closest ancestor node to the target node which is also a data 4674 node. 4676 o If the "when" statement is a child of a "uses", "choice", or 4677 "case" statement, then the context node is the closest ancestor 4678 node to the "uses", "choice", or "case" node which is also a data 4679 node. 4681 o If the "when" statement is a child of any other data definition 4682 statement, the context node is the data definition's node in the 4683 data tree. 4685 o The accessible tree is made up of all nodes in the data tree, and 4686 all leafs with default values in use (see Section 7.6.1). 4688 The accessible tree depends on the context node: 4690 o If the context node represents configuration, the tree is the data 4691 in the NETCONF datastore where the context node exists. The XPath 4692 root node has all top-level configuration data nodes in all 4693 modules as children. 4695 o If the context node represents state data, the tree is all state 4696 data on the device, and the datastore. The XPath root 4697 node has all top-level data nodes in all modules as children. 4699 o If the context node represents notification content, the tree is 4700 the notification XML instance document. The XPath root node has 4701 the element representing the notification being defined as the 4702 only child. 4704 o If the context node represents RPC input parameters, the tree is 4705 the RPC XML instance document. The XPath root node has the 4706 element representing the RPC operation being defined as the only 4707 child. 4709 o If the context node represents RPC output parameters, the tree is 4710 the RPC reply instance document. The XPath root node has the 4711 elements representing the RPC output parameters as children. 4713 The result of the XPath expression is converted to a boolean value 4714 using the standard XPath rules. 4716 Note that the XPath expression is conceptually evaluated. This means 4717 that an implementation does not have to use an XPath evaluator on the 4718 device. The "when" statement can very well be implemented with 4719 specially written code. 4721 8. Constraints 4723 8.1. Constraints on Data 4725 Several YANG statements define constraints on valid data. These 4726 constraints are enforced in different ways, depending on what type of 4727 data the statement defines. 4729 o If the constraint is defined on configuration data, it MUST be 4730 true in a valid configuration data tree. 4732 o If the constraint is defined on state data, it MUST be true in a 4733 reply to a operation without a filter. 4735 o If the constraint is defined on notification content, it MUST be 4736 true in any notification instance. 4738 o If the constraint is defined on RPC input parameters, it MUST be 4739 true in an invocation of the RPC operation. 4741 o If the constraint is defined on RPC output parameters, it MUST be 4742 true in the RPC reply. 4744 8.2. Hierarchy of Constraints 4746 Conditions on parent nodes affect constraints on child nodes as a 4747 natural consequence of the hierarchy of nodes. "must", "mandatory", 4748 "min-elements", and "max-elements" constraints are not enforced if 4749 the parent node has a "when" or "if-feature" property that is not 4750 satisfied on the current device. 4752 In this example, the mandatory constraints on the "longitude" leaf is 4753 not enforced on devices that lack the "has-gps" feature: 4755 container location { 4756 if-feature has-gps; 4757 leaf longitude { 4758 mandatory true; 4759 ... 4760 } 4761 } 4763 8.3. Constraint Enforcement Model 4765 For configuration data, there are three windows when constraints can 4766 be enforced: 4768 o during parsing of RPC payloads 4770 o during processing of NETCONF operations 4772 o during validation 4774 Each of these scenarios are considered in the following sections. 4776 8.3.1. Payload Parsing 4778 When content arrives in RPC payloads, it MUST be well-formed XML, 4779 following the hierarchy and content rules defined by the set of 4780 models the device implements. 4782 o If a leaf data value does not match the type constraints for the 4783 leaf, including those defined in the type's range, length, and 4784 pattern properties, the server MUST reply with an "invalid-value" 4785 error-tag in the rpc-error, and with the error-app-tag and error- 4786 message associated with the constraint, if any exist. 4788 o If all keys of a list entry are not present, the server MUST reply 4789 with a "missing-element" error-tag in the rpc-error. 4791 o If data for more than one case branch of a choice is present, the 4792 server MUST reply with a "bad-element" in the rpc-error. 4794 o If data for a node tagged with "if-feature" is present, and the 4795 feature is not supported by the device, the server MUST reply with 4796 an "unknown-element" error-tag in the rpc-error. 4798 o If data for a node tagged with "when" is present, and the "when" 4799 condition evaluates to "false", the server MUST reply with an 4800 "unknown-element" error-tag in the rpc-error. 4802 o For insert handling, if the value for the attributes "before" and 4803 "after" are not valid for the type of the appropriate key leafs, 4804 the server MUST reply with a "bad-attribute" error-tag in the rpc- 4805 error. 4807 o If the attributes "before" and "after" appears in any element that 4808 is not a list whose "ordered-by" property is "user", the server 4809 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 4811 8.3.2. NETCONF Processing 4813 After the incoming data is parsed, the NETCONF server performs the 4814 operation by applying the data to the configuration 4815 datastore. During this processing the following errors MUST be 4816 detected: 4818 o Delete requests for non-existent data. 4820 o Create requests for existent data. 4822 o Insert requests with "before" or "after" parameters which do not 4823 exist. 4825 During processing: 4827 o If the NETCONF operation creates data nodes under a "choice", any 4828 existing nodes from other "case" branches are deleted by the 4829 server. 4831 o If the NETCONF operation modifies a data node such that any node's 4832 "when" expression becomes false, then the node with the "when" 4833 expression is deleted by the server. 4835 8.3.3. Validation 4837 When datastore processing is complete, the final contents MUST obey 4838 all validation constraints. This validation processing is performed 4839 at differing time according to the datastore. If the datastore is 4840 or , these constraints MUST be enforced at the 4841 end of the or operation. If the 4842 datastore is , the constraint enforcement is delayed 4843 until a or operation. 4845 o Any "must" constraints MUST evaluate to "true". 4847 o Any referential integrity constraints defined via the "path" 4848 statement MUST be satisfied. 4850 o Any "unique" constraints on lists MUST be satisfied. 4852 o The "min-elements" and "max-elements" constraints are enforced for 4853 lists and leaf-lists. 4855 9. Built-in Types 4857 YANG has a set of built-in types, similar to those of many 4858 programming languages, but with some differences due to special 4859 requirements from the management information model. 4861 Additional types may be defined, derived from those built-in types or 4862 from other derived types. Derived types may use subtyping to 4863 formally restrict the set of possible values. 4865 The different built-in types and their derived types allow different 4866 kinds of subtyping, namely length and regular expression restrictions 4867 of strings (Section 9.4.4, Section 9.4.6) and range restrictions of 4868 numeric types (Section 9.2.4). 4870 The lexicographic representation of a value of a certain type is used 4871 in the NETCONF PDUs, and when specifying default values and numerical 4872 ranges in YANG modules. 4874 9.1. Canonical representation 4876 For most types, there is a single canonical representation of the 4877 type's values. Some types allow multiple lexicographic 4878 representations of the same value, for example the positive integer 4879 "17" can be represented as "+17" or "17". 4881 When a NETCONF server sends data, it MUST be in the canonical form. 4883 Some types have a lexical representation that depends on the XML 4884 context in which they occur. These types do not have a canonical 4885 form. 4887 9.2. The Integer Built-in Types 4889 The integer built-in types are int8, int16, int32, int64, uint8, 4890 uint16, uint32, and uint64. They represent signed and unsigned 4891 integers of different sizes: 4893 int8 represents integer values between -128 and 127, inclusively. 4895 int16 represents integer values between -32768 and 32767, 4896 inclusively. 4898 int32 represents integer values between -2147483648 and 2147483647, 4899 inclusively. 4901 int64 represents integer values between -9223372036854775808 and 4902 9223372036854775807, inclusively. 4904 uint8 represents integer values between 0 and 255, inclusively. 4906 uint16 represents integer values between 0 and 65535, inclusively. 4908 uint32 represents integer values between 0 and 4294967295, 4909 inclusively. 4911 uint64 represents integer values between 0 and 18446744073709551615, 4912 inclusively. 4914 9.2.1. Lexicographic Representation 4916 An integer value is lexicographically represented as an optional sign 4917 ("+" or "-"), followed by a sequence of decimal digits. If no sign 4918 is specified, "+" is assumed. 4920 For convenience, when specifying a default value for an integer in a 4921 YANG module, an alternative lexicographic representation can be used, 4922 which represents the value in a hexadecimal or octal notation. The 4923 hexadecimal notation consists of an optional sign ("+" or "-"), the 4924 characters "0x" followed a number of hexadecimal digits, where 4925 letters may be upper- or lowercase. The octal notation consists of 4926 an optional sign ("+" or "-"), the character "0" followed a number of 4927 octal digits. 4929 Note that if a default value in a YANG module has a leading zero 4930 ("0"), it is interpreted as an octal number. In the XML instance 4931 documents, an integer is always interpreted as a decimal number, and 4932 leading zeros are allowed. 4934 Examples: 4936 // legal values 4937 +4711 // legal positive value 4938 4711 // legal positive value 4939 -123 // legal negative value 4940 0xf00f // legal positive hexadecimal value 4941 -0xf // legal negative hexadecimal value 4942 052 // legal positive octal value 4944 // illegal values 4945 - 1 // illegal intermediate space 4947 9.2.2. Canonical Form 4949 The canonical form of a positive integer does not include the sign 4950 "+". Leading zeros are prohibited. The value zero is represented as 4951 "0". 4953 9.2.3. Restrictions 4955 All integer types can be restricted with the "range" statement 4956 (Section 9.2.4). 4958 9.2.4. The range Statement 4960 The "range" statement, which is an optional substatement to the 4961 "type" statement, takes as an argument a range expression string. It 4962 is used to restrict integer and decimal built-in types, or types 4963 derived from those. 4965 A range consists of an explicit value, or a lower inclusive bound, 4966 two consecutive dots "..", and an upper inclusive bound. Multiple 4967 values or ranges can be given, separated by "|". If multiple values 4968 or ranges are given they all MUST be disjoint and MUST be in 4969 ascending order. If a range restriction is applied to an already 4970 range restricted type, the new restriction MUST be equal or more 4971 limiting, that is raising the lower bounds, reducing the upper 4972 bounds, removing explicit values or ranges, or splitting ranges into 4973 multiple ranges with intermediate gaps. Each explicit value and 4974 range boundary value given in the range expression MUST match the 4975 type being restricted, or be one of the special values "min" or 4976 "max". "min" and "max" means the minimum and maximum value accepted 4977 for the type being restricted, respectively. 4979 The range expression syntax is formally defined by the rule 4980 "range-arg" in Section 12. 4982 9.2.4.1. The range's Substatements 4984 +---------------+---------+-------------+ 4985 | substatement | section | cardinality | 4986 +---------------+---------+-------------+ 4987 | description | 7.19.3 | 0..1 | 4988 | error-app-tag | 7.5.4.2 | 0..1 | 4989 | error-message | 7.5.4.1 | 0..1 | 4990 | reference | 7.19.4 | 0..1 | 4991 +---------------+---------+-------------+ 4993 9.2.5. Usage Example 4995 typedef my-base-int32-type { 4996 type int32 { 4997 range "1..4 | 10..20"; 4998 } 4999 } 5001 typedef my-type1 { 5002 type my-base-int32-type { 5003 // legal range restriction 5004 range "11..max"; // 11..20 5005 } 5006 } 5008 typedef my-type2 { 5009 type my-base-int32-type { 5010 // illegal range restriction 5011 range "11..100"; 5012 } 5013 } 5015 9.3. The decimal64 Built-in Type 5017 The decimal64 type represents a subset of the real numbers, which can 5018 be represented by decimal numerals. The value space of decimal64 is 5019 the set of numbers that can be obtained by multiplying a 64 bit 5020 signed integer by a negative power of ten, i.e., expressible as 5021 "i x 10^-n" where i is an integer64 and n is an integer between 1 and 5022 18, inclusively. 5024 9.3.1. Lexicographic Representation 5026 A decimal64 value is lexicographically represented as an optional 5027 sign ("+" or "-"), followed by a sequence of decimal digits, 5028 optionally followed by a period ('.') as a decimal indicator and a 5029 sequence of decimal digits. If no sign is specified, "+" is assumed. 5031 9.3.2. Canonical Form 5033 The canonical form of a positive decimal64 does not include the sign 5034 "+". The decimal point is required. Leading and trailing zeros are 5035 prohibited, subject to the rule that there MUST be at least one digit 5036 before and after the decimal point. The value zero is represented as 5037 "0.0". 5039 9.3.3. Restrictions 5041 A decimal64 type can be restricted with the "range" statement 5042 (Section 9.2.4). 5044 9.3.4. The fraction-digits Statement 5046 The "fraction-digits" statement, which is a substatement to the 5047 "type" statement, MUST be present if the type is "decimal64". It 5048 takes as an argument an integer between 1 and 18, inclusively. It 5049 controls the size of the minimum difference between values of a 5050 decimal64 type, by restricting the value space to numbers that are 5051 expressible as "i x 10^-n" where n is the fraction-digits argument. 5053 The following table lists the minimum and maximum value for each 5054 fraction-digit value: 5056 +----------------+-----------------------+----------------------+ 5057 | fraction-digit | min | max | 5058 +----------------+-----------------------+----------------------+ 5059 | 1 | -922337203685477580.8 | 922337203685477580.7 | 5060 | 2 | -92233720368547758.08 | 92233720368547758.07 | 5061 | 3 | -9223372036854775.808 | 9223372036854775.807 | 5062 | 4 | -922337203685477.5808 | 922337203685477.5807 | 5063 | 5 | -92233720368547.75808 | 92233720368547.75807 | 5064 | 6 | -9223372036854.775808 | 9223372036854.775807 | 5065 | 7 | -922337203685.4775808 | 922337203685.4775807 | 5066 | 8 | -92233720368.54775808 | 92233720368.54775807 | 5067 | 9 | -9223372036.854775808 | 9223372036.854775807 | 5068 | 10 | -922337203.6854775808 | 922337203.6854775807 | 5069 | 11 | -92233720.36854775808 | 92233720.36854775807 | 5070 | 12 | -9223372.036854775808 | 9223372.036854775807 | 5071 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5072 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5073 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5074 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5075 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5076 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5077 +----------------+-----------------------+----------------------+ 5079 9.3.5. Usage Example 5081 typedef my-decimal { 5082 type decimal64 { 5083 fraction-digits 2; 5084 range "1 .. 3.14 | 10 | 20..max"; 5085 } 5086 } 5088 9.4. The string Built-in Type 5090 The string built-in type represents human readable strings in YANG. 5091 Legal characters are tab, carriage return, line feed, and the legal 5092 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 5094 ;; any Unicode character, excluding the surrogate blocks, 5095 ;; FFFE, and FFFF. 5096 string = *char 5097 char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / 5098 %x10000-10FFFF 5100 9.4.1. Lexicographic Representation 5102 A string value is lexicographically represented as character data in 5103 the XML instance documents. 5105 9.4.2. Canonical Form 5107 The canonical form is the same as the lexicographical representation. 5108 No Unicode normalization is performed of string values. 5110 9.4.3. Restrictions 5112 A string can be restricted with the "length" (Section 9.4.4) and 5113 "pattern" (Section 9.4.6) statements. 5115 9.4.4. The length Statement 5117 The "length" statement, which is an optional substatement to the 5118 "type" statement, takes as an argument a length expression string. 5119 It is used to restrict the built-in type "string", or types derived 5120 from "string". 5122 A "length" statement restricts the number of characters in the 5123 string. 5125 A length range consists of an explicit value, or a lower bound, two 5126 consecutive dots "..", and an upper bound. Multiple values or ranges 5127 can be given, separated by "|". Length restricting values MUST NOT 5128 be negative. If multiple values or ranges are given, they all MUST 5129 be disjoint and MUST be in ascending order. If a length restriction 5130 is applied to an already length restricted type, the new restriction 5131 MUST be equal or more limiting, that is, raising the lower bounds, 5132 reducing the upper bounds, removing explicit length values or ranges, 5133 or splitting ranges into multiple ranges with intermediate gaps. A 5134 length value is a non-negative integer, or one of the special values 5135 "min" or "max". "min" and "max" means the minimum and maximum length 5136 accepted for the type being restricted, respectively. An 5137 implementation is not required to support a length value larger than 5138 18446744073709551615. 5140 The length expression syntax is formally defined by the rule 5141 "length-arg" in Section 12. 5143 9.4.4.1. The length's Substatements 5145 +---------------+---------+-------------+ 5146 | substatement | section | cardinality | 5147 +---------------+---------+-------------+ 5148 | description | 7.19.3 | 0..1 | 5149 | error-app-tag | 7.5.4.2 | 0..1 | 5150 | error-message | 7.5.4.1 | 0..1 | 5151 | reference | 7.19.4 | 0..1 | 5152 +---------------+---------+-------------+ 5154 9.4.5. Usage Example 5156 typedef my-base-str-type { 5157 type string { 5158 length "1..255"; 5159 } 5160 } 5162 type my-base-str-type { 5163 // legal length refinement 5164 length "11 | 42..max"; // 11 | 42..255 5165 } 5167 type my-base-str-type { 5168 // illegal length refinement 5169 length "1..999"; 5170 } 5172 9.4.6. The pattern Statement 5174 The "pattern" statement, which is an optional substatement to the 5175 "type" statement, takes as an argument a regular expression string, 5176 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5177 "string", or types derived from "string", to values that matches the 5178 pattern. 5180 If the type has multiple "pattern" statements, the expressions are 5181 ANDed together, i.e., all such expressions have to match. 5183 If a pattern restriction is applied to an already pattern restricted 5184 type, values must match all patterns in the base type, in addition to 5185 the new patterns. 5187 9.4.6.1. The pattern's Substatements 5189 +---------------+---------+-------------+ 5190 | substatement | section | cardinality | 5191 +---------------+---------+-------------+ 5192 | description | 7.19.3 | 0..1 | 5193 | error-app-tag | 7.5.4.2 | 0..1 | 5194 | error-message | 7.5.4.1 | 0..1 | 5195 | reference | 7.19.4 | 0..1 | 5196 +---------------+---------+-------------+ 5198 9.4.7. Usage Example 5200 With the following type: 5202 type string { 5203 length "0..4"; 5204 pattern "[0-9a-fA-F]*"; 5205 } 5207 the following strings match: 5209 AB // legal 5210 9A00 // legal 5212 and the following strings do not match: 5214 00ABAB // illegal, too long 5215 xx00 // illegal, bad characters 5217 9.5. The boolean Built-in Type 5219 The boolean built-in type represents a boolean value. 5221 9.5.1. Lexicographic Representation 5223 The lexicographical representation of a boolean value is a string 5224 with a value of "true" or "false". 5226 9.5.2. Canonical Form 5228 The canonical form is the same as the lexicographical representation. 5230 9.5.3. Restrictions 5232 A boolean cannot be restricted. 5234 9.6. The enumeration Built-in Type 5236 The enumeration built-in type represents values from a set of 5237 assigned names. 5239 9.6.1. Lexicographic Representation 5241 The lexicographical representation of an enumeration value is the 5242 assigned name string. 5244 9.6.2. Canonical Form 5246 The canonical form is the assigned name string. 5248 9.6.3. Restrictions 5250 An enumeration cannot be restricted. 5252 9.6.4. The enum Statement 5254 The "enum" statement, which is a substatement to the "type" 5255 statement, MUST be present if the type is "enumeration". It is 5256 repeatedly used to specify each assigned name of an enumeration type. 5257 It takes as an argument a string which is the assigned name. The 5258 string MUST NOT be empty and MUST NOT have any leading or trailing 5259 whitespace characters. The use of control codes SHOULD be avoided. 5261 The statement is optionally followed by a block of substatements 5262 which holds detailed enum information. 5264 All assigned names in an enumeration MUST be unique. 5266 9.6.4.1. The enum's Substatements 5268 +--------------+---------+-------------+ 5269 | substatement | section | cardinality | 5270 +--------------+---------+-------------+ 5271 | description | 7.19.3 | 0..1 | 5272 | reference | 7.19.4 | 0..1 | 5273 | status | 7.19.2 | 0..1 | 5274 | value | 9.6.4.2 | 0..1 | 5275 +--------------+---------+-------------+ 5277 9.6.4.2. The value Statement 5279 The "value" statement, which is optional, is used to associate an 5280 integer value with the assigned name for the enum. This integer 5281 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5282 unique within the enumeration type. The value is unused by YANG and 5283 the XML encoding, but is carried as a convenience to implementors. 5285 If a value is not specified, then one will be automatically assigned. 5286 If the enum sub-statement is the first one defined, the assigned 5287 value is zero (0), otherwise the assigned value is one greater than 5288 the current highest enum value. 5290 If the current highest value is equal to 2147483647, then an enum 5291 value MUST be specified for enum sub-statements following the one 5292 with the current highest value. 5294 9.6.5. Usage Example 5296 leaf myenum { 5297 type enumeration { 5298 enum zero; 5299 enum one; 5300 enum seven { 5301 value 7; 5302 } 5303 } 5304 } 5306 The lexicographic representation of the leaf "myenum" with value 5307 "seven" is: 5309 seven 5311 9.7. The bits Built-in Type 5313 The bits built-in type represents a bit set. That is, a bits value 5314 is a set of flags identified by small integer position numbers 5315 starting at 0. Each bit number has an assigned name. 5317 9.7.1. Restrictions 5319 A bits type cannot be restricted. 5321 9.7.2. Lexicographic Representation 5323 The lexicographical representation of the bits type is a space 5324 separated list of the individual bit values that are set. An empty 5325 string thus represents a value where no bits are set. 5327 9.7.3. Canonical Form 5329 In the canonical form, the bit values are separated by a single space 5330 character and they appear ordered by their position (see 5331 Section 9.7.4.2). 5333 9.7.4. The bit Statement 5335 The "bit" statement, which is a substatement to the "type" statement, 5336 MUST be present if the type is "bits". It is repeatedly used to 5337 specify each assigned named bit of a bits type. It takes as an 5338 argument a string which is the assigned name of the bit. It is 5339 followed by a block of substatements which holds detailed bit 5340 information. The assigned name follows the same syntax rules as an 5341 identifier (see Section 6.2). 5343 All assigned names in a bits type MUST be unique. 5345 9.7.4.1. The bit's Substatements 5347 +--------------+---------+-------------+ 5348 | substatement | section | cardinality | 5349 +--------------+---------+-------------+ 5350 | description | 7.19.3 | 0..1 | 5351 | reference | 7.19.4 | 0..1 | 5352 | status | 7.19.2 | 0..1 | 5353 | position | 9.7.4.2 | 0..1 | 5354 +--------------+---------+-------------+ 5356 9.7.4.2. The position Statement 5358 The "position" statement, which is optional, takes as an argument a 5359 non-negative integer value which specifies the bit's position within 5360 a hypothetical bit field. The position value MUST be in the range 0 5361 to 4294967295, and it MUST be unique within the bits type. The value 5362 is unused by YANG and the NETCONF PDUs, but is carried as a 5363 convenience to implementors. 5365 If a bit position is not specified, then one will be automatically 5366 assigned. If the bit sub-statement is the first one defined, the 5367 assigned value is zero (0), otherwise the assigned value is one 5368 greater than the current highest bit position. 5370 If the current highest bit position value is equal to 4294967295, 5371 then a position value MUST be specified for bit sub-statements 5372 following the one with the current highest position value. 5374 9.7.5. Usage Example 5376 Given the following leaf: 5378 leaf mybits { 5379 type bits { 5380 bit disable-nagle { 5381 position 0; 5382 } 5383 bit auto-sense-speed { 5384 position 1; 5385 } 5386 bit 10-Mb-only { 5387 position 2; 5388 } 5389 } 5390 default "auto-sense-speed"; 5391 } 5393 The lexicographic representation of this leaf with bit values 5394 disable-nagle and 10-Mb-only set would be: 5396 disable-nagle 10-Mb-only 5398 9.8. The binary Built-in Type 5400 The binary built-in type represents any binary data, i.e., a sequence 5401 of octets. 5403 9.8.1. Restrictions 5405 A binary can be restricted with the "length" (Section 9.4.4) 5406 statement. The length of a binary value is the number of octets it 5407 contains. 5409 9.8.2. Lexicographic Representation 5411 Binary values are encoded with the base64 encoding scheme [RFC4648]. 5413 9.8.3. Canonical Form 5415 The canonical form of a binary value follow the rules in [RFC4648]. 5417 9.9. The leafref Built-in Type 5419 The leafref type is used to reference a particular leaf instance in 5420 the data tree. The "path" substatement (Section 9.9.2) selects a set 5421 of leaf instances, and the leafref value space is the set of values 5422 of these leaf instances. 5424 If the leaf with the leafref type represents configuration data, the 5425 leaf it refers to MUST also represent configuration. Such a leaf 5426 puts a constraint on valid data. All leafref nodes MUST reference 5427 existing leaf instances or leafs with default values in use (see 5428 Section 7.6.1) for the data to be valid. This constraint is enforced 5429 according to the rules in Section 8. 5431 There MUST NOT be any circular chains of leafrefs. 5433 If the leaf that the leafref refers to is conditional based on one or 5434 more feature (see Section 7.18.2), then the leaf with the leafref 5435 type MUST also be conditional based on at least the same set of 5436 features. 5438 9.9.1. Restrictions 5440 A leafref cannot be restricted. 5442 9.9.2. The path Statement 5444 The "path" statement, which is a substatement to the "type" 5445 statement, MUST be present if the type is "leafref". It takes as an 5446 argument a string which MUST refer to a leaf or leaf-list node. 5448 The syntax for a path argument is a subset of the XPath abbreviated 5449 syntax. Predicates are used only for constraining the values for the 5450 key nodes for list entries. Each predicate consists of exactly one 5451 equality test per key, and multiple adjacent predicates MAY be 5452 present if a list has multiple keys. The syntax is formally defined 5453 by the rule "path-arg" in Section 12. 5455 The predicates are only used when more than one key reference is 5456 needed to uniquely identify a leaf instance. This occurs if a list 5457 has multiple keys, or a reference to a leaf other than the key in a 5458 list is needed. In these cases, multiple leafrefs are typically 5459 specified, and predicates are used to tie them together. 5461 The "path" expression evaluates to a node set consisting of zero, one 5462 or more nodes. If the leaf with the leafref type represents 5463 configuration data, this node set MUST be non-empty. 5465 The "path" XPath expression is conceptually evaluated in the 5466 following context, in addition to the definition in Section 6.4.1: 5468 o The context node is the node in the data tree for which the "path" 5469 statement is defined. 5471 The accessible tree depends on the context node: 5473 o If the context node represents configuration data, the tree is the 5474 data in the NETCONF datastore where the context node exists. The 5475 XPath root node has all top-level configuration data nodes in all 5476 modules as children. 5478 o Otherwise the tree is all state data on the device, and the 5479 datastore. The XPath root node has all top-level data 5480 nodes in all modules as children. 5482 9.9.3. Lexicographic Representation 5484 A leafref value is encoded the same way as the leaf it references. 5486 9.9.4. Canonical Form 5488 The canonical form of a leafref is the same as the canonical form of 5489 the leaf it references. 5491 9.9.5. Usage Example 5493 With the following list: 5495 list interface { 5496 key "name"; 5497 leaf name { 5498 type string; 5499 } 5500 leaf admin-status { 5501 type admin-status; 5502 } 5503 list address { 5504 key "ip"; 5505 leaf ip { 5506 type yang:ip-address; 5507 } 5508 } 5509 } 5511 The following leafref refers to an existing interface: 5513 leaf mgmt-interface { 5514 type leafref { 5515 path "../interface/name"; 5516 } 5517 } 5519 An example of a corresponding XML snippet: 5521 5522 eth0 5523 5524 5525 lo 5526 5528 eth0 5530 The following leafrefs refer to an existing address of an interface: 5532 container default-address { 5533 leaf ifname { 5534 type leafref { 5535 path "../../interface/name"; 5536 } 5537 } 5538 leaf address { 5539 type leafref { 5540 path "../../interface[name = current()/../ifname]" 5541 + "/address/ip"; 5542 } 5543 } 5544 } 5546 An example of a corresponding XML snippet: 5548 5549 eth0 5550 up 5551
5552 192.0.2.1 5553
5554
5555 192.0.2.2 5556
5557 5558 5559 lo 5560 up 5561
5562 127.0.0.1 5563
5564 5566 5567 eth0 5568
192.0.2.2
5569 5571 The following list uses a leafref for one of its keys. This is 5572 similar to a foreign key in a relational database. 5574 list packet-filter { 5575 key "if-name filter-id"; 5576 leaf if-name { 5577 type leafref { 5578 path "/interface/name"; 5579 } 5580 } 5581 leaf filter-id { 5582 type uint32; 5583 } 5584 ... 5585 } 5587 An example of a corresponding XML snippet: 5589 5590 eth0 5591 up 5592
5593 192.0.2.1 5594
5595
5596 192.0.2.2 5597
5598 5600 5601 eth0 5602 1 5603 ... 5604 5605 5606 eth0 5607 2 5608 ... 5609 5611 The following notification defines two leafrefs to refer to an 5612 existing admin-status: 5614 notification link-failure { 5615 leaf if-name { 5616 type leafref { 5617 path "/interface/name"; 5618 } 5619 } 5620 leaf admin-status { 5621 type leafref { 5622 path 5623 "/interface[name = current()/../if-name]" 5624 + "/admin-status"; 5625 } 5626 } 5627 } 5629 An example of a corresponding XML notification: 5631 5633 2008-04-01T00:01:00Z 5634 5635 eth0 5636 up 5637 5638 5640 9.10. The identityref Built-in Type 5642 The identityref type is used to reference an existing identity (see 5643 Section 7.16). 5645 9.10.1. Restrictions 5647 An identityref cannot be restricted. 5649 9.10.2. The identityref's base Statement 5651 The "base" statement, which is a substatement to the "type" 5652 statement, MUST be present if the type is "identityref". The 5653 argument is the name of an identity, as defined by an "identity" 5654 statement. If a prefix is present on the identity name, it refers to 5655 an identity defined in the module which was imported with that 5656 prefix. Otherwise an identity with the matching name MUST be defined 5657 in the current module or an included submodule. 5659 Valid values for an identityref are any identities derived from the 5660 identityref's base identity. On a particular server, the valid 5661 values are further restricted to the set of identities defined in the 5662 modules supported by the server. 5664 9.10.3. Lexicographic Representation 5666 An identityref is encoded as the referred identity's Qualified Name 5667 as defined in [XML-NAMES]. If the Prefix is not present, the 5668 namespace of the identityref is the default namespace in effect on 5669 the element which contains the identityref value. 5671 When an identityref is given a default value using the "default" 5672 statement, the identity name in the default value MAY have a prefix. 5673 If a prefix is present on the identity name, it refers to an identity 5674 defined in the module which was imported with that prefix. Otherwise 5675 an identity with the matching name MUST be defined in the current 5676 module or an included submodule. 5678 9.10.4. Canonical Form 5680 Since the lexicographic form depends on the XML context in which the 5681 value occurs, this type does not have a canonical form. 5683 9.10.5. Usage Example 5685 With the identity definitions in Section 7.16.3, and the following 5686 module: 5688 module my-crypto { 5690 namespace "http://example.com/my-crypto"; 5691 prefix mc; 5693 import "crypto-base" { 5694 prefix "crypto"; 5695 } 5697 identity aes { 5698 base "crypto:crypto-alg"; 5699 } 5701 leaf crypto { 5702 type identityref { 5703 base "crypto:crypto-alg"; 5704 } 5705 } 5706 } 5708 The leaf "crypto" will be encoded as follows, if the value is the 5709 "des3" identity defined in the "des" module: 5711 des:des3 5713 Any prefixes used in the encoding are local to each instance 5714 encoding. This means that the same identityref may be encoded 5715 differently by different implementations. For example, the following 5716 example encodes the same leaf as above: 5718 x:des3 5720 If the "crypto" leaf's value instead is "aes" defined in the 5721 "my-crypto" module it can be encoded as: 5723 mc:aes 5725 or, using the default namespace: 5727 aes 5729 9.11. The empty Built-in Type 5731 The empty built-in type represents a leaf that does not have any 5732 value, it conveys information by its presence or absence. 5734 An empty type cannot have a default value. 5736 9.11.1. Restrictions 5738 An empty type cannot be restricted. 5740 9.11.2. Lexicographic Representation 5742 Not applicable. 5744 9.11.3. Canonical Form 5746 Not applicable. 5748 9.11.4. Usage Example 5750 The following leaf 5752 leaf enable-qos { 5753 type empty; 5754 } 5756 will be encoded as 5758 5760 if it exists. 5762 9.12. The union Built-in Type 5764 The union built-in type represents a value that corresponds to one of 5765 its member types. 5767 When the type is "union", the "type" statement (Section 7.4) MUST be 5768 present. It is used to repeatedly specify each member type of the 5769 union. It takes as an argument a string which is the name of a 5770 member type. 5772 A member type can be of any built-in or derived type, except it MUST 5773 NOT be one of the built-in types "empty" or "leafref". 5775 When a string representing a union data type is validated, the string 5776 is validated against each member type, in the order they are 5777 specified in the type statement, until a match is found. 5779 Any default values or units properties defined in the member types 5780 are not inherited by the union type. 5782 Example: 5784 type union { 5785 type int32; 5786 type enumeration { 5787 enum "unbounded"; 5788 } 5789 } 5791 9.12.1. Restrictions 5793 A union cannot be restricted. However, each member type can be 5794 restricted, based on the rules defined in Section 9. 5796 9.12.2. Lexicographic Representation 5798 The lexicographical representation of an union is a value that 5799 corresponds to the representation of any one of the member types. 5801 9.12.3. Canonical Form 5803 The canonical form of a union value is the same as the canonical form 5804 of the member type of the value. 5806 9.13. The instance-identifier Built-in Type 5808 The instance-identifier built-in type is used to uniquely identify a 5809 particular instance node in the data tree. 5811 The syntax for an instance-identifier is a subset of the XPath 5812 abbreviated syntax, formally defined by the rule 5813 "instance-identifier" in Section 12. It is used to uniquely identify 5814 a node in the data tree. Predicates are used only for specifying the 5815 values for the key nodes for list entries, a value of a leaf-list 5816 entry, or a positional index for list without keys. For identifying 5817 list entries with keys, each predicate consists of one equality test 5818 per key, and each key MUST have a corresponding predicate. 5820 If the leaf with the instance-identifier type represents 5821 configuration data, and the "require-instance" property 5822 (Section 9.13.2) is "true", the node it refers to MUST also represent 5823 configuration. Such a leaf puts a constraint on valid data. All 5824 such leaf nodes MUST reference existing nodes or leaf nodes with 5825 their default value in use (see Section 7.6.1) for the data to be 5826 valid. This constraint is enforced according to the rules in 5827 Section 8. 5829 The "instance-identifier" XPath expression is conceptually evaluated 5830 in the following context, in addition to the definition in 5831 Section 6.4.1: 5833 o The context node is the root node in the accessible tree. 5835 The accessible tree depends on the leaf with the instance-identifier 5836 type: 5838 o If this leaf represents configuration data, the tree is the data 5839 in the NETCONF datastore where the leaf exists. The XPath root 5840 node has all top-level configuration data nodes in all modules as 5841 children. 5843 o Otherwise the tree is all state data on the device, and the 5844 datastore. The XPath root node has all top-level data 5845 nodes in all modules as children. 5847 9.13.1. Restrictions 5849 An instance-identifier can be restricted with the "require-instance" 5850 statement (Section 9.13.2). 5852 9.13.2. The require-instance Statement 5854 The "require-instance" statement, which is a substatement to the 5855 "type" statement, MAY be present if the type is 5856 "instance-identifier". It takes as an argument the string "true" or 5857 "false". If this statement is not present, it defaults to "true". 5859 If "require-instance" is "true", it means that the instance being 5860 referred MUST exist for the data to be valid. This constraint is 5861 enforced according to the rules in Section 8. 5863 If "require-instance" is "false", it means that the instance being 5864 referred MAY exist in valid data. 5866 9.13.3. Lexicographic Representation 5868 An instance-identifier value is lexicographically represented as a 5869 string. All node names in an instance-identifier value MUST be 5870 qualified with explicit namespace prefixes and these prefixes MUST be 5871 declared in the XML namespace scope in the instance-identifier's XML 5872 element. 5874 Any prefixes used in the encoding are local to each instance 5875 encoding. This means that the same instance-identifier may be 5876 encoded differently by different implementations. 5878 9.13.4. Canonical Form 5880 Since the lexicographic form depends on the XML context in which the 5881 value occurs, this type does not have a canonical form. 5883 9.13.5. Usage Example 5885 The following are examples of instance identifiers: 5887 /* instance-identifier for a container */ 5888 /ex:system/ex:services/ex:ssh 5890 /* instance-identifier for a leaf */ 5891 /ex:system/ex:services/ex:ssh/ex:port 5893 /* instance-identifier for a list entry */ 5894 /ex:system/ex:user[ex:name='fred'] 5896 /* instance-identifier for a leaf in a list entry */ 5897 /ex:system/ex:user[ex:name='fred']/ex:type 5899 /* instance-identifier for a list entry with two keys */ 5900 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 5902 /* instance-identifier for a leaf-list entry */ 5903 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 5905 /* instance-identifier for a list entry without keys */ 5906 /ex:stats/ex:port[3] 5908 10. Updating a Module 5910 As experience is gained with a module, it may be desirable to revise 5911 that module. However, changes are not allowed if they have any 5912 potential to cause interoperability problems between a client using 5913 an original specification and a server using an updated 5914 specification. 5916 For any published change, a new "revision" statement (Section 7.1.9) 5917 MUST be included in front of the existing revision statements. If 5918 there are no existing revision statements, then one MUST be added to 5919 identify the new revision. Furthermore, any necessary changes MUST 5920 be applied to any meta data statements, including the "organization" 5921 and "contact" statements (Section 7.1.7, Section 7.1.8). 5923 Note that definitions contained in a module are available to be 5924 imported by any other module, and are referenced in "import" 5925 statements via the module name. Thus, a module name MUST NOT be 5926 changed. Furthermore, the "namespace" statement MUST NOT be changed, 5927 since all XML elements are encoded in the namespace. 5929 Obsolete definitions MUST NOT be removed from modules since their 5930 identifiers may still be referenced by other modules. 5932 A definition may be revised in any of the following ways: 5934 o An "enumeration" type may have new enums added, provided the old 5935 enums's values do not change. 5937 o A "bits" type may have new bits added, provided the old bit 5938 positions do not change. 5940 o A "range", "length", or "pattern" statement may expand the allowed 5941 value space. 5943 o A "default" statement may be added to a leaf that does not have a 5944 default value (either directly or indirectly through its type). 5946 o A "units" statement may be added. 5948 o A "reference" statement may be added or updated. 5950 o A "must" statement may be removed or its constraint relaxed. 5952 o A "mandatory" statement may be removed or changed from "true" to 5953 "false". 5955 o A "min-elements" statement may be removed, or changed to require 5956 less elements. 5958 o A "max-elements" statement may be removed, or changed to allow 5959 more elements. 5961 o A "description" statement may be added or clarified without 5962 changing the semantics of the definition. 5964 o New typedefs, groupings, rpc, notifications, extensions, features, 5965 and identities may be added. 5967 o New data definition statements may be added if they do not add 5968 mandatory nodes (Section 3.1) to existing nodes or at the top- 5969 level in a module or submodule, or if they are conditionally 5970 dependent on a new feature (i.e., have a "if-feature" statement 5971 which refers to a new feature). 5973 o A new "case" statement may be added. 5975 o A node that represented state data may be changed to represent 5976 configuration, provided it is not mandatory (Section 3.1). 5978 o An "if-feature" statement may be removed, provided its node is not 5979 mandatory (Section 3.1). 5981 o A "status" statement may be added, or changed from "current" to 5982 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 5984 o A "type" statement may be replaced with another "type" statement 5985 which does not change the syntax or semantics of the type. For 5986 example, an inline type definition may be replaced with a typedef, 5987 but a int8 type cannot be replaced by a int16, since the syntax 5988 would change. 5990 o Any set of data definition nodes may be replaced with another set 5991 of syntactically and semantically equivalent nodes. For example, 5992 a set of leafs may be replaced by a uses of a grouping with the 5993 same leafs. 5995 o A module may be split into a set of submodules, or submodule may 5996 be removed, provided the definitions in the module do not change 5997 in any other way than allowed here. 5999 o The "prefix" statement may be changed, provided all local uses of 6000 the prefix also are changed. 6002 Otherwise, if the semantics of any previous definition are changed 6003 (i.e., if a non-editorial change is made to any definition other than 6004 those specifically allowed above), then this MUST be achieved by a 6005 new definition with a new identifier. 6007 In statements which have any data definition statements as 6008 substatements, those data definition substatements MUST NOT be 6009 reordered. 6011 11. YIN 6013 A YANG module can be translated into an alternative XML-based syntax 6014 called YIN. The translated module is called a YIN module. This 6015 section describes symmetric mapping rules between the two formats. 6017 The YANG and YIN formats contain equivalent information using 6018 different notations. The purpose of the YIN notation is to allow the 6019 user to translate YANG into YIN, use the rich set of XML based tools 6020 on the YIN format to transform, or filter the model information. 6021 Tools like XSLT or XML validators can be utilized. After this the 6022 model can be transformed back to the YANG format if needed, which 6023 provides a more concise and readable format. 6025 The mapping between YANG and YIN does not modify the information 6026 content of the model. Comments and whitespace are not preserved. 6028 11.1. Formal YIN Definition 6030 There is a one-to-one correspondence between YANG keywords and YIN 6031 elements. The local name of a YIN element is identical to the 6032 corresponding YANG keyword. This means in particular that the 6033 document element (root) of a YIN document is always or 6034 . 6036 YIN elements corresponding to the YANG keywords belong to the 6037 namespace whose associated URI is 6038 "urn:ietf:params:xml:ns:yang:yin:1". 6040 YIN elements corresponding to extension keywords belong to the 6041 namespace of the YANG module where the extension keyword is declared 6042 via the "extension" statement. 6044 The names of all YIN elements MUST be properly qualified with their 6045 namespaces specified above using the standard mechanisms of 6046 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 6048 The argument of a YANG statement is encoded in YIN either as an XML 6049 attribute or a subelement of the keyword element. Table 1 defines 6050 the encoding for the set of YANG keywords. For extensions, the 6051 argument encoding is specified within the "extension" statement (see 6052 Section 7.17). The following rules hold for arguments: 6054 o If the argument is encoded as an attribute, this attribute has no 6055 namespace. 6057 o If the argument is encoded as an element, it is placed to the same 6058 namespace as its parent keyword element. 6060 o If the argument is encoded as an element, it MUST be the first 6061 child of the keyword element. 6063 Substatements of a YANG statement are encoded as (additional) 6064 children of the keyword element and their relative order MUST be the 6065 same as the order of substatements in YANG. 6067 Comments in YANG MAY be mapped to XML comments. 6069 Mapping of arguments of the YANG statements. 6071 +------------------+---------------+-------------+ 6072 | keyword | argument name | yin-element | 6073 +------------------+---------------+-------------+ 6074 | anyxml | name | false | 6075 | argument | name | false | 6076 | augment | target-node | false | 6077 | base | name | false | 6078 | belongs-to | module | false | 6079 | bit | name | false | 6080 | case | name | false | 6081 | choice | name | false | 6082 | config | value | false | 6083 | contact | text | true | 6084 | container | name | false | 6085 | default | value | false | 6086 | description | text | true | 6087 | deviate | value | false | 6088 | deviation | target-node | false | 6089 | enum | name | false | 6090 | error-app-tag | value | false | 6091 | error-message | value | true | 6092 | extension | name | false | 6093 | feature | name | false | 6094 | fraction-digits | value | false | 6095 | grouping | name | false | 6096 | identity | name | false | 6097 | if-feature | name | false | 6098 | import | module | false | 6099 | include | module | false | 6100 | input | | n/a | 6101 | key | value | false | 6102 | leaf | name | false | 6103 | leaf-list | name | false | 6104 | length | value | false | 6105 | list | name | false | 6106 | mandatory | value | false | 6107 | max-elements | value | false | 6108 | min-elements | value | false | 6109 | module | name | false | 6110 | must | condition | false | 6111 | namespace | uri | false | 6112 | notification | name | false | 6113 | ordered-by | value | false | 6114 | organization | text | true | 6115 | output | | n/a | 6116 | path | value | false | 6117 | pattern | value | false | 6118 | position | value | false | 6119 | prefix | value | false | 6120 | presence | value | false | 6121 | range | value | false | 6122 | reference | text | true | 6123 | refine | target-node | false | 6124 | require-instance | value | false | 6125 | revision | date | false | 6126 | revision-date | date | false | 6127 | rpc | name | false | 6128 | status | value | false | 6129 | submodule | name | false | 6130 | type | name | false | 6131 | typedef | name | false | 6132 | unique | tag | false | 6133 | units | name | false | 6134 | uses | name | false | 6135 | value | value | false | 6136 | when | condition | false | 6137 | yang-version | value | false | 6138 | yin-element | value | false | 6139 +------------------+---------------+-------------+ 6141 Table 1 6143 11.1.1. Usage Example 6145 The following YANG module: 6147 module acme-foo { 6148 namespace "http://acme.example.com/foo"; 6149 prefix "acfoo"; 6151 import my-extensions { 6152 prefix "myext"; 6153 } 6155 list interface { 6156 key "name"; 6157 leaf name { 6158 type string; 6159 } 6161 leaf mtu { 6162 type uint32; 6163 description "The MTU of the interface."; 6164 myext:c-define "MY_MTU"; 6165 } 6166 } 6167 } 6169 where the extension "c-define" is defined in Section 7.17.3, is 6170 translated into the following YIN: 6172 6177 6178 6180 6181 6182 6184 6185 6186 6187 6188 6189 6190 6191 6192 The MTU of the interface. 6193 6194 6195 6196 6197 6199 12. YANG ABNF Grammar 6201 In YANG, almost all statements are unordered. The ABNF grammar 6202 [RFC5234] defines the canonical order. To improve module 6203 readability, it is RECOMMENDED that clauses be entered in this order. 6205 Within the ABNF grammar, unordered statements are marked with 6206 comments. 6208 This grammar assumes that the scanner replaces YANG comments with a 6209 single space character. 6211 file "yang.abnf" 6213 module-stmt = optsep module-keyword sep identifier-arg-str 6214 optsep 6215 "{" stmtsep 6216 module-header-stmts 6217 linkage-stmts 6218 meta-stmts 6219 revision-stmts 6220 body-stmts 6221 "}" optsep 6223 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 6224 optsep 6225 "{" stmtsep 6226 submodule-header-stmts 6227 linkage-stmts 6228 meta-stmts 6229 revision-stmts 6230 body-stmts 6231 "}" optsep 6233 module-header-stmts = ;; these stmts can appear in any order 6234 [yang-version-stmt stmtsep] 6235 namespace-stmt stmtsep 6236 prefix-stmt stmtsep 6238 submodule-header-stmts = 6239 ;; these stmts can appear in any order 6240 [yang-version-stmt stmtsep] 6241 belongs-to-stmt stmtsep 6243 meta-stmts = ;; these stmts can appear in any order 6244 [organization-stmt stmtsep] 6245 [contact-stmt stmtsep] 6246 [description-stmt stmtsep] 6248 [reference-stmt stmtsep] 6250 linkage-stmts = ;; these stmts can appear in any order 6251 *(import-stmt stmtsep) 6252 *(include-stmt stmtsep) 6254 revision-stmts = *(revision-stmt stmtsep) 6256 body-stmts = *((extension-stmt / 6257 feature-stmt / 6258 identity-stmt / 6259 typedef-stmt / 6260 grouping-stmt / 6261 data-def-stmt / 6262 augment-stmt / 6263 rpc-stmt / 6264 notification-stmt / 6265 deviation-stmt) stmtsep) 6267 data-def-stmt = container-stmt / 6268 leaf-stmt / 6269 leaf-list-stmt / 6270 list-stmt / 6271 choice-stmt / 6272 anyxml-stmt / 6273 uses-stmt 6275 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 6276 optsep stmtend 6278 yang-version-arg-str = < a string which matches the rule 6279 yang-version-arg > 6281 yang-version-arg = "1" 6283 import-stmt = import-keyword sep identifier-arg-str optsep 6284 "{" stmtsep 6285 prefix-stmt stmtsep 6286 [revision-date-stmt stmtsep] 6287 "}" 6289 include-stmt = include-keyword sep identifier-arg-str optsep 6290 (";" / 6291 "{" stmtsep 6292 [revision-date-stmt stmtsep] 6293 "}") 6295 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 6296 uri-str = < a string which matches the rule 6297 URI in RFC 3986 > 6299 prefix-stmt = prefix-keyword sep prefix-arg-str 6300 optsep stmtend 6302 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6303 optsep 6304 "{" stmtsep 6305 prefix-stmt stmtsep 6306 "}" 6308 organization-stmt = organization-keyword sep string 6309 optsep stmtend 6311 contact-stmt = contact-keyword sep string optsep stmtend 6313 description-stmt = description-keyword sep string optsep 6314 stmtend 6316 reference-stmt = reference-keyword sep string optsep stmtend 6318 units-stmt = units-keyword sep string optsep stmtend 6320 revision-stmt = revision-keyword sep revision-date optsep 6321 (";" / 6322 "{" stmtsep 6323 [description-stmt stmtsep] 6324 [reference-stmt stmtsep] 6325 "}") 6327 revision-date = date-arg-str 6329 revision-date-stmt = revision-date-keyword sep revision-date stmtend 6331 extension-stmt = extension-keyword sep identifier-arg-str optsep 6332 (";" / 6333 "{" stmtsep 6334 ;; these stmts can appear in any order 6335 [argument-stmt stmtsep] 6336 [status-stmt stmtsep] 6337 [description-stmt stmtsep] 6338 [reference-stmt stmtsep] 6339 "}") 6341 argument-stmt = argument-keyword sep identifier-arg-str optsep 6342 (";" / 6343 "{" stmtsep 6345 [yin-element-stmt stmtsep] 6346 "}") 6348 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 6349 stmtend 6351 yin-element-arg-str = < a string which matches the rule 6352 yin-element-arg > 6354 yin-element-arg = true-keyword / false-keyword 6356 identity-stmt = identity-keyword sep identifier-arg-str optsep 6357 (";" / 6358 "{" stmtsep 6359 ;; these stmts can appear in any order 6360 [base-stmt stmtsep] 6361 [status-stmt stmtsep] 6362 [description-stmt stmtsep] 6363 [reference-stmt stmtsep] 6364 "}") 6366 base-stmt = base-keyword sep identifier-ref-arg-str 6367 optsep stmtend 6369 feature-stmt = feature-keyword sep identifier-arg-str optsep 6370 (";" / 6371 "{" stmtsep 6372 ;; these stmts can appear in any order 6373 *(if-feature-stmt stmtsep) 6374 [status-stmt stmtsep] 6375 [description-stmt stmtsep] 6376 [reference-stmt stmtsep] 6377 "}") 6379 if-feature-stmt = if-feature-keyword sep identifier-ref-arg-str 6380 optsep stmtend 6382 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 6383 "{" stmtsep 6384 ;; these stmts can appear in any order 6385 type-stmt stmtsep 6386 [units-stmt stmtsep] 6387 [default-stmt stmtsep] 6388 [status-stmt stmtsep] 6389 [description-stmt stmtsep] 6390 [reference-stmt stmtsep] 6391 "}" 6393 type-stmt = type-keyword sep identifier-ref-arg-str optsep 6394 (";" / 6395 "{" stmtsep 6396 type-body-stmts 6397 "}") 6399 type-body-stmts = numerical-restrictions / 6400 decimal64-specification / 6401 string-restrictions / 6402 enum-specification / 6403 leafref-specification / 6404 identityref-specification / 6405 instance-identifier-specification / 6406 bits-specification / 6407 union-specification 6409 numerical-restrictions = range-stmt stmtsep 6411 range-stmt = range-keyword sep range-arg-str optsep 6412 (";" / 6413 "{" stmtsep 6414 ;; these stmts can appear in any order 6415 [error-message-stmt stmtsep] 6416 [error-app-tag-stmt stmtsep] 6417 [description-stmt stmtsep] 6418 [reference-stmt stmtsep] 6419 "}") 6421 decimal64-specification = fraction-digits-stmt 6423 fraction-digits-stmt = fraction-digits-keyword sep 6424 fraction-digits-arg-str stmtend 6426 fraction-digits-arg-str = < a string which matches the rule 6427 fraction-digits-arg > 6429 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 6430 "5" / "6" / "7" / "8"]) 6431 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 6433 string-restrictions = ;; these stmts can appear in any order 6434 [length-stmt stmtsep] 6435 *(pattern-stmt stmtsep) 6437 length-stmt = length-keyword sep length-arg-str optsep 6438 (";" / 6439 "{" stmtsep 6440 ;; these stmts can appear in any order 6442 [error-message-stmt stmtsep] 6443 [error-app-tag-stmt stmtsep] 6444 [description-stmt stmtsep] 6445 [reference-stmt stmtsep] 6446 "}") 6448 pattern-stmt = pattern-keyword sep string optsep 6449 (";" / 6450 "{" stmtsep 6451 ;; these stmts can appear in any order 6452 [error-message-stmt stmtsep] 6453 [error-app-tag-stmt stmtsep] 6454 [description-stmt stmtsep] 6455 [reference-stmt stmtsep] 6456 "}") 6458 default-stmt = default-keyword sep string stmtend 6460 enum-specification = 1*(enum-stmt stmtsep) 6462 enum-stmt = enum-keyword sep string optsep 6463 (";" / 6464 "{" stmtsep 6465 ;; these stmts can appear in any order 6466 [value-stmt stmtsep] 6467 [status-stmt stmtsep] 6468 [description-stmt stmtsep] 6469 [reference-stmt stmtsep] 6470 "}") 6472 leafref-specification = 6473 ;; these stmts can appear in any order 6474 path-stmt stmtsep 6475 [require-instance-stmt stmtsep] 6477 path-stmt = path-keyword sep path-arg-str stmtend 6479 require-instance-stmt = require-instance-keyword sep 6480 require-instance-arg-str stmtend 6482 require-instance-arg-str = < a string which matches the rule 6483 require-instance-arg > 6485 require-instance-arg = true-keyword / false-keyword 6487 instance-identifier-specification = 6488 [require-instance-stmt stmtsep] 6490 identityref-specification = 6491 base-stmt stmtsep 6493 union-specification = 1*(type-stmt stmtsep) 6495 bits-specification = 1*(bit-stmt stmtsep) 6497 bit-stmt = bit-keyword sep identifier-arg-str optsep 6498 (";" / 6499 "{" stmtsep 6500 ;; these stmts can appear in any order 6501 [position-stmt stmtsep] 6502 [status-stmt stmtsep] 6503 [description-stmt stmtsep] 6504 [reference-stmt stmtsep] 6505 "}" 6506 "}") 6508 position-stmt = position-keyword sep 6509 position-value-arg-str stmtend 6511 position-value-arg-str = < a string which matches the rule 6512 position-value-arg > 6514 position-value-arg = non-negative-integer-value 6516 status-stmt = status-keyword sep status-arg-str stmtend 6518 status-arg-str = < a string which matches the rule 6519 status-arg > 6521 status-arg = current-keyword / 6522 obsolete-keyword / 6523 deprecated-keyword 6525 config-stmt = config-keyword sep 6526 config-arg-str stmtend 6528 config-arg-str = < a string which matches the rule 6529 config-arg > 6531 config-arg = true-keyword / false-keyword 6533 mandatory-stmt = mandatory-keyword sep 6534 mandatory-arg-str stmtend 6536 mandatory-arg-str = < a string which matches the rule 6537 mandatory-arg > 6539 mandatory-arg = true-keyword / false-keyword 6541 presence-stmt = presence-keyword sep string stmtend 6543 ordered-by-stmt = ordered-by-keyword sep 6544 ordered-by-arg-str stmtend 6546 ordered-by-arg-str = < a string which matches the rule 6547 ordered-by-arg > 6549 ordered-by-arg = user-keyword / system-keyword 6551 must-stmt = must-keyword sep string optsep 6552 (";" / 6553 "{" stmtsep 6554 ;; these stmts can appear in any order 6555 [error-message-stmt stmtsep] 6556 [error-app-tag-stmt stmtsep] 6557 [description-stmt stmtsep] 6558 [reference-stmt stmtsep] 6559 "}") 6561 error-message-stmt = error-message-keyword sep string stmtend 6563 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 6565 min-elements-stmt = min-elements-keyword sep 6566 min-value-arg-str stmtend 6568 min-value-arg-str = < a string which matches the rule 6569 min-value-arg > 6571 min-value-arg = non-negative-integer-value 6573 max-elements-stmt = max-elements-keyword sep 6574 max-value-arg-str stmtend 6576 max-value-arg-str = < a string which matches the rule 6577 max-value-arg > 6579 max-value-arg = unbounded-keyword / 6580 positive-integer-value 6582 value-stmt = value-keyword sep integer-value stmtend 6584 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 6585 (";" / 6586 "{" stmtsep 6587 ;; these stmts can appear in any order 6588 [status-stmt stmtsep] 6589 [description-stmt stmtsep] 6590 [reference-stmt stmtsep] 6591 *((typedef-stmt / 6592 grouping-stmt) stmtsep) 6593 *(data-def-stmt stmtsep) 6594 "}") 6596 container-stmt = container-keyword sep identifier-arg-str optsep 6597 (";" / 6598 "{" stmtsep 6599 ;; these stmts can appear in any order 6600 [when-stmt stmtsep] 6601 *(if-feature-stmt stmtsep) 6602 *(must-stmt stmtsep) 6603 [presence-stmt stmtsep] 6604 [config-stmt stmtsep] 6605 [status-stmt stmtsep] 6606 [description-stmt stmtsep] 6607 [reference-stmt stmtsep] 6608 *((typedef-stmt / 6609 grouping-stmt) stmtsep) 6610 *(data-def-stmt stmtsep) 6611 "}") 6613 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 6614 "{" stmtsep 6615 ;; these stmts can appear in any order 6616 [when-stmt stmtsep] 6617 *(if-feature-stmt stmtsep) 6618 type-stmt stmtsep 6619 [units-stmt stmtsep] 6620 *(must-stmt stmtsep) 6621 [default-stmt stmtsep] 6622 [config-stmt stmtsep] 6623 [mandatory-stmt stmtsep] 6624 [status-stmt stmtsep] 6625 [description-stmt stmtsep] 6626 [reference-stmt stmtsep] 6627 "}" 6629 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 6630 "{" stmtsep 6631 ;; these stmts can appear in any order 6632 [when-stmt stmtsep] 6633 *(if-feature-stmt stmtsep) 6634 type-stmt stmtsep 6636 [units-stmt stmtsep] 6637 *(must-stmt stmtsep) 6638 [config-stmt stmtsep] 6639 [min-elements-stmt stmtsep] 6640 [max-elements-stmt stmtsep] 6641 [ordered-by-stmt stmtsep] 6642 [status-stmt stmtsep] 6643 [description-stmt stmtsep] 6644 [reference-stmt stmtsep] 6645 "}" 6647 list-stmt = list-keyword sep identifier-arg-str optsep 6648 "{" stmtsep 6649 ;; these stmts can appear in any order 6650 [when-stmt stmtsep] 6651 *(if-feature-stmt stmtsep) 6652 *(must-stmt stmtsep) 6653 [key-stmt stmtsep] 6654 *(unique-stmt stmtsep) 6655 [config-stmt stmtsep] 6656 [min-elements-stmt stmtsep] 6657 [max-elements-stmt stmtsep] 6658 [ordered-by-stmt stmtsep] 6659 [status-stmt stmtsep] 6660 [description-stmt stmtsep] 6661 [reference-stmt stmtsep] 6662 *((typedef-stmt / 6663 grouping-stmt) stmtsep) 6664 1*(data-def-stmt stmtsep) 6665 "}" 6667 key-stmt = key-keyword sep key-arg-str stmtend 6669 key-arg-str = < a string which matches the rule 6670 key-arg > 6672 key-arg = node-identifier *(sep node-identifier) 6674 unique-stmt = unique-keyword sep unique-arg-str stmtend 6676 unique-arg-str = < a string which matches the rule 6677 unique-arg > 6679 unique-arg = descendant-schema-nodeid 6680 *(sep descendant-schema-nodeid) 6682 choice-stmt = choice-keyword sep identifier-arg-str optsep 6683 (";" / 6684 "{" stmtsep 6685 ;; these stmts can appear in any order 6686 [when-stmt stmtsep] 6687 *(if-feature-stmt stmtsep) 6688 [default-stmt stmtsep] 6689 [config-stmt stmtsep] 6690 [mandatory-stmt stmtsep] 6691 [status-stmt stmtsep] 6692 [description-stmt stmtsep] 6693 [reference-stmt stmtsep] 6694 *((short-case-stmt / case-stmt) stmtsep) 6695 "}") 6697 short-case-stmt = container-stmt / 6698 leaf-stmt / 6699 leaf-list-stmt / 6700 list-stmt / 6701 anyxml-stmt 6703 case-stmt = case-keyword sep identifier-arg-str optsep 6704 (";" / 6705 "{" stmtsep 6706 ;; these stmts can appear in any order 6707 [when-stmt stmtsep] 6708 *(if-feature-stmt stmtsep) 6709 [status-stmt stmtsep] 6710 [description-stmt stmtsep] 6711 [reference-stmt stmtsep] 6712 *(data-def-stmt stmtsep) 6713 "}") 6715 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 6716 (";" / 6717 "{" stmtsep 6718 ;; these stmts can appear in any order 6719 [when-stmt stmtsep] 6720 *(if-feature-stmt stmtsep) 6721 *(must-stmt stmtsep) 6722 [config-stmt stmtsep] 6723 [mandatory-stmt stmtsep] 6724 [status-stmt stmtsep] 6725 [description-stmt stmtsep] 6726 [reference-stmt stmtsep] 6727 "}") 6729 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 6730 (";" / 6731 "{" stmtsep 6732 ;; these stmts can appear in any order 6733 [when-stmt stmtsep] 6734 *(if-feature-stmt stmtsep) 6735 [status-stmt stmtsep] 6736 [description-stmt stmtsep] 6737 [reference-stmt stmtsep] 6738 *(refine-stmt stmtsep) 6739 *(uses-augment-stmt stmtsep) 6740 "}") 6742 refine-stmt = refine-keyword sep refine-arg-str optsep 6743 (";" / 6744 "{" stmtsep 6745 (refine-container-stmts / 6746 refine-leaf-stmts / 6747 refine-leaf-list-stmts / 6748 refine-list-stmts / 6749 refine-choice-stmts / 6750 refine-case-stmts / 6751 refine-anyxml-stmts) 6752 "}") 6754 refine-arg-str = < a string which matches the rule 6755 refine-arg > 6757 refine-arg = descendant-schema-nodeid 6759 refine-container-stmts = 6760 ;; these stmts can appear in any order 6761 *(must-stmt stmtsep) 6762 [presence-stmt stmtsep] 6763 [config-stmt stmtsep] 6764 [description-stmt stmtsep] 6765 [reference-stmt stmtsep] 6767 refine-leaf-stmts = ;; these stmts can appear in any order 6768 *(must-stmt stmtsep) 6769 [default-stmt stmtsep] 6770 [config-stmt stmtsep] 6771 [mandatory-stmt stmtsep] 6772 [description-stmt stmtsep] 6773 [reference-stmt stmtsep] 6775 refine-leaf-list-stmts = 6776 ;; these stmts can appear in any order 6777 *(must-stmt stmtsep) 6778 [config-stmt stmtsep] 6779 [min-elements-stmt stmtsep] 6781 [max-elements-stmt stmtsep] 6782 [description-stmt stmtsep] 6783 [reference-stmt stmtsep] 6785 refine-list-stmts = ;; these stmts can appear in any order 6786 *(must-stmt stmtsep) 6787 [config-stmt stmtsep] 6788 [min-elements-stmt stmtsep] 6789 [max-elements-stmt stmtsep] 6790 [description-stmt stmtsep] 6791 [reference-stmt stmtsep] 6793 refine-choice-stmts = ;; these stmts can appear in any order 6794 [default-stmt stmtsep] 6795 [config-stmt stmtsep] 6796 [mandatory-stmt stmtsep] 6797 [description-stmt stmtsep] 6798 [reference-stmt stmtsep] 6800 refine-case-stmts = ;; these stmts can appear in any order 6801 [description-stmt stmtsep] 6802 [reference-stmt stmtsep] 6804 refine-anyxml-stmts = ;; these stmts can appear in any order 6805 *(must-stmt stmtsep) 6806 [config-stmt stmtsep] 6807 [mandatory-stmt stmtsep] 6808 [description-stmt stmtsep] 6809 [reference-stmt stmtsep] 6811 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 6812 "{" stmtsep 6813 ;; these stmts can appear in any order 6814 [when-stmt stmtsep] 6815 *(if-feature-stmt stmtsep) 6816 [status-stmt stmtsep] 6817 [description-stmt stmtsep] 6818 [reference-stmt stmtsep] 6819 1*((data-def-stmt stmtsep) / 6820 (case-stmt stmtsep)) 6821 "}" 6823 uses-augment-arg-str = < a string which matches the rule 6824 uses-augment-arg > 6826 uses-augment-arg = descendant-schema-nodeid 6827 augment-stmt = augment-keyword sep augment-arg-str optsep 6828 "{" stmtsep 6829 ;; these stmts can appear in any order 6830 [when-stmt stmtsep] 6831 *(if-feature-stmt stmtsep) 6832 [status-stmt stmtsep] 6833 [description-stmt stmtsep] 6834 [reference-stmt stmtsep] 6835 1*((data-def-stmt stmtsep) / 6836 (case-stmt stmtsep)) 6837 "}" 6839 augment-arg-str = < a string which matches the rule 6840 augment-arg > 6842 augment-arg = absolute-schema-nodeid 6844 unknown-statement = prefix ":" identifier [sep string] optsep 6845 (";" / "{" *unknown-statement2 "}") 6847 unknown-statement2 = [prefix ":"] identifier [sep string] optsep 6848 (";" / "{" *unknown-statement2 "}") 6850 when-stmt = when-keyword sep string optsep 6851 (";" / 6852 "{" stmtsep 6853 ;; these stmts can appear in any order 6854 [description-stmt stmtsep] 6855 [reference-stmt stmtsep] 6856 "}") 6858 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 6859 (";" / 6860 "{" stmtsep 6861 ;; these stmts can appear in any order 6862 *(if-feature-stmt stmtsep) 6863 [status-stmt stmtsep] 6864 [description-stmt stmtsep] 6865 [reference-stmt stmtsep] 6866 *((typedef-stmt / 6867 grouping-stmt) stmtsep) 6868 [input-stmt stmtsep] 6869 [output-stmt stmtsep] 6870 "}") 6872 input-stmt = input-keyword optsep 6873 "{" stmtsep 6874 ;; these stmts can appear in any order 6875 *((typedef-stmt / 6876 grouping-stmt) stmtsep) 6877 1*(data-def-stmt stmtsep) 6878 "}" 6880 output-stmt = output-keyword optsep 6881 "{" stmtsep 6882 ;; these stmts can appear in any order 6883 *((typedef-stmt / 6884 grouping-stmt) stmtsep) 6885 1*(data-def-stmt stmtsep) 6886 "}" 6888 notification-stmt = notification-keyword sep 6889 identifier-arg-str optsep 6890 (";" / 6891 "{" stmtsep 6892 ;; these stmts can appear in any order 6893 *(if-feature-stmt stmtsep) 6894 [status-stmt stmtsep] 6895 [description-stmt stmtsep] 6896 [reference-stmt stmtsep] 6897 *((typedef-stmt / 6898 grouping-stmt) stmtsep) 6899 *(data-def-stmt stmtsep) 6900 "}") 6902 deviation-stmt = deviation-keyword sep 6903 deviation-arg-str optsep 6904 "{" stmtsep 6905 ;; these stmts can appear in any order 6906 [description-stmt stmtsep] 6907 [reference-stmt stmtsep] 6908 (deviate-not-supported-stmt / 6909 1*(deviate-add-stmt / 6910 deviate-replace-stmt / 6911 deviate-delete-stmt)) 6912 "}" 6914 deviation-arg-str = < a string which matches the rule 6915 deviation-arg > 6917 deviation-arg = absolute-schema-nodeid 6919 deviate-not-supported-stmt = 6920 deviate-keyword sep 6921 not-supported-keyword optsep 6922 (";" / 6923 "{" stmtsep 6924 "}") 6926 deviate-add-stmt = deviate-keyword sep add-keyword optsep 6927 (";" / 6928 "{" stmtsep 6929 [units-stmt stmtsep] 6930 *(must-stmt stmtsep) 6931 *(unique-stmt stmtsep) 6932 [default-stmt stmtsep] 6933 [config-stmt stmtsep] 6934 [mandatory-stmt stmtsep] 6935 [min-elements-stmt stmtsep] 6936 [max-elements-stmt stmtsep] 6937 "}") 6939 deviate-delete-stmt = deviate-keyword sep delete-keyword optsep 6940 (";" / 6941 "{" stmtsep 6942 [units-stmt stmtsep] 6943 *(must-stmt stmtsep) 6944 *(unique-stmt stmtsep) 6945 [default-stmt stmtsep] 6946 "}") 6948 deviate-replace-stmt = deviate-keyword sep replace-keyword optsep 6949 (";" / 6950 "{" stmtsep 6951 [type-stmt stmtsep] 6952 [units-stmt stmtsep] 6953 [default-stmt stmtsep] 6954 [config-stmt stmtsep] 6955 [mandatory-stmt stmtsep] 6956 [min-elements-stmt stmtsep] 6957 [max-elements-stmt stmtsep] 6958 "}") 6960 ;; Ranges 6962 range-arg-str = < a string which matches the rule 6963 range-arg > 6965 range-arg = range-part *(optsep "|" optsep range-part) 6967 range-part = range-boundary 6968 [optsep ".." optsep range-boundary] 6970 range-boundary = min-keyword / max-keyword / 6971 integer-value / decimal-value 6973 ;; Lengths 6975 length-arg-str = < a string which matches the rule 6976 length-arg > 6978 length-arg = length-part *(optsep "|" optsep length-part) 6980 length-part = length-boundary 6981 [optsep ".." optsep length-boundary] 6983 length-boundary = min-keyword / max-keyword / 6984 non-negative-integer-value 6986 ;; Date 6988 date-arg-str = < a string which matches the rule 6989 date-arg > 6991 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 6993 ;; Schema Node Identifiers 6995 schema-nodeid = absolute-schema-nodeid / 6996 descendant-schema-nodeid 6998 absolute-schema-nodeid = 1*("/" node-identifier) 7000 descendant-schema-nodeid = 7001 node-identifier 7002 absolute-schema-nodeid 7004 node-identifier = [prefix ":"] identifier 7006 ;; Instance Identifiers 7008 instance-identifier = 1*("/" (node-identifier *predicate)) 7010 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 7012 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 7013 ((DQUOTE string DQUOTE) / 7014 (SQUOTE string SQUOTE)) 7016 pos = non-negative-integer-value 7017 ;; leafref path 7019 path-arg-str = < a string which matches the rule 7020 path-arg > 7022 path-arg = absolute-path / relative-path 7024 absolute-path = 1*("/" (node-identifier *path-predicate)) 7026 relative-path = 1*(".." "/") descendant-path 7028 descendant-path = node-identifier 7029 [*path-predicate absolute-path] 7031 path-predicate = "[" *WSP path-equality-expr *WSP "]" 7033 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 7035 path-key-expr = current-function-invocation *WSP "/" *WSP 7036 rel-path-keyexpr 7038 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 7039 *(node-identifier *WSP "/" *WSP) 7040 node-identifier 7042 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 7044 ;; statment keywords 7045 anyxml-keyword = 'anyxml' 7046 argument-keyword = 'argument' 7047 augment-keyword = 'augment' 7048 base-keyword = 'base' 7049 belongs-to-keyword = 'belongs-to' 7050 bit-keyword = 'bit' 7051 case-keyword = 'case' 7052 choice-keyword = 'choice' 7053 config-keyword = 'config' 7054 contact-keyword = 'contact' 7055 container-keyword = 'container' 7056 default-keyword = 'default' 7057 description-keyword = 'description' 7058 enum-keyword = 'enum' 7059 error-app-tag-keyword = 'error-app-tag' 7060 error-message-keyword = 'error-message' 7061 extension-keyword = 'extension' 7062 deviation-keyword = 'deviation' 7063 deviate-keyword = 'deviate' 7064 feature-keyword = 'feature' 7065 fraction-digits-keyword = 'fraction-digits' 7066 grouping-keyword = 'grouping' 7067 identity-keyword = 'identity' 7068 if-feature-keyword = 'if-feature' 7069 import-keyword = 'import' 7070 include-keyword = 'include' 7071 input-keyword = 'input' 7072 key-keyword = 'key' 7073 leaf-keyword = 'leaf' 7074 leaf-list-keyword = 'leaf-list' 7075 length-keyword = 'length' 7076 list-keyword = 'list' 7077 mandatory-keyword = 'mandatory' 7078 max-elements-keyword = 'max-elements' 7079 min-elements-keyword = 'min-elements' 7080 module-keyword = 'module' 7081 must-keyword = 'must' 7082 namespace-keyword = 'namespace' 7083 notification-keyword= 'notification' 7084 ordered-by-keyword = 'ordered-by' 7085 organization-keyword= 'organization' 7086 output-keyword = 'output' 7087 path-keyword = 'path' 7088 pattern-keyword = 'pattern' 7089 position-keyword = 'position' 7090 prefix-keyword = 'prefix' 7091 presence-keyword = 'presence' 7092 range-keyword = 'range' 7093 reference-keyword = 'reference' 7094 refine-keyword = 'refine' 7095 require-instance-keyword = 'require-instance' 7096 revision-keyword = 'revision' 7097 revision-date-keyword = 'revision-date' 7098 rpc-keyword = 'rpc' 7099 status-keyword = 'status' 7100 submodule-keyword = 'submodule' 7101 type-keyword = 'type' 7102 typedef-keyword = 'typedef' 7103 unique-keyword = 'unique' 7104 units-keyword = 'units' 7105 uses-keyword = 'uses' 7106 value-keyword = 'value' 7107 when-keyword = 'when' 7108 yang-version-keyword= 'yang-version' 7109 yin-element-keyword = 'yin-element' 7111 ;; other keywords 7112 add-keyword = 'add' 7113 current-keyword = 'current' 7114 delete-keyword = 'delete' 7115 deprecated-keyword = 'deprecated' 7116 false-keyword = 'false' 7117 max-keyword = 'max' 7118 min-keyword = 'min' 7119 not-supported-keyword = 'not-supported' 7120 obsolete-keyword = 'obsolete' 7121 replace-keyword = 'replace' 7122 system-keyword = 'system' 7123 true-keyword = 'true' 7124 unbounded-keyword = 'unbounded' 7125 user-keyword = 'user' 7127 current-function-invocation = current-keyword *WSP "(" *WSP ")" 7129 ;; Basic Rules 7131 prefix-arg-str = < a string which matches the rule 7132 prefix-arg > 7134 prefix-arg = prefix 7136 prefix = identifier 7138 identifier-arg-str = < a string which matches the rule 7139 identifier-arg > 7141 identifier-arg = identifier 7143 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 7144 identifier = (ALPHA / "_") 7145 *(ALPHA / DIGIT / "_" / "-" / ".") 7147 identifier-ref-arg-str = < a string which matches the rule 7148 identifier-ref-arg > 7150 identifier-ref-arg = [prefix ":"] identifier 7152 string = < an unquoted string as returned by 7153 the scanner > 7155 integer-value = ("-" non-negative-integer-value) / 7156 non-negative-integer-value 7158 non-negative-integer-value = "0" / positive-integer-value 7159 positive-integer-value = (non-zero-digit *DIGIT) 7161 zero-integer-value = 1*DIGIT 7163 stmtend = ";" / "{" *unknown-statement "}" 7165 sep = 1*(WSP / line-break) 7166 ; unconditional separator 7168 optsep = *(WSP / line-break) 7170 stmtsep = *(WSP / line-break / unknown-statement) 7172 line-break = CRLF / LF 7174 non-zero-digit = %x31-39 7176 decimal-value = integer-value ("." zero-integer-value) 7178 SQUOTE = %x27 7179 ; ' (Single Quote) 7181 ;; 7182 ;; RFC 4234 core rules. 7183 ;; 7185 ALPHA = %x41-5A / %x61-7A 7186 ; A-Z / a-z 7188 CR = %x0D 7189 ; carriage return 7191 CRLF = CR LF 7192 ; Internet standard newline 7194 DIGIT = %x30-39 7195 ; 0-9 7197 DQUOTE = %x22 7198 ; " (Double Quote) 7200 HEXDIG = DIGIT / 7201 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 7202 ; only lower-case a..f 7204 HTAB = %x09 7205 ; horizontal tab 7207 LF = %x0A 7208 ; linefeed 7210 SP = %x20 7211 ; space 7213 VCHAR = %x21-7E 7214 ; visible (printing) characters 7216 WSP = SP / HTAB 7217 ; whitespace 7219 7221 13. Error Responses for YANG Related Errors 7223 A number of NETCONF error responses are defined for error cases 7224 related to the data-model handling. If the relevant YANG statement 7225 has an "error-app-tag" substatement, that overrides the default value 7226 specified below. 7228 13.1. Error Message for Data that Violates a unique Statement 7230 If a NETCONF operation would result in configuration data where a 7231 unique constraint is invalidated, the following error is returned: 7233 Tag: operation-failed 7234 Error-app-tag: data-not-unique 7235 Error-info: : Contains an instance identifier which 7236 points to a leaf which invalidates the unique 7237 constraint. This element is present once for each 7238 non-unique leaf. 7240 The element is in the YANG 7241 namespace ("urn:ietf:params:xml:ns:yang:1"). 7243 13.2. Error Message for Data that Violates a max-elements Statement 7245 If a NETCONF operation would result in configuration data where a 7246 list or a leaf-list would have too many entries the following error 7247 is returned: 7249 Tag: operation-failed 7250 Error-app-tag: too-many-elements 7252 This error is returned once, with the error-path identifying the list 7253 node, even if there are more than one extra child present. 7255 13.3. Error Message for Data that Violates a min-elements Statement 7257 If a NETCONF operation would result in configuration data where a 7258 list or a leaf-list would have too few entries the following error is 7259 returned: 7261 Tag: operation-failed 7262 Error-app-tag: too-few-elements 7264 This error is returned once, with the error-path identifying the list 7265 node, even if there are more than one child missing. 7267 13.4. Error Message for Data that Violates a must Statement 7269 If a NETCONF operation would result in configuration data where the 7270 restrictions imposed by a "must" statement is violated the following 7271 error is returned, unless a specific "error-app-tag" substatement is 7272 present for the "must" statement. 7274 Tag: operation-failed 7275 Error-app-tag: must-violation 7277 13.5. Error Message for Data that Violates a require-instance Statement 7279 If a NETCONF operation would result in configuration data where a 7280 leaf of type "instance-identifier" marked with require-instance 7281 "true" refers to a non-existing instance, the following error is 7282 returned: 7284 Tag: data-missing 7285 Error-app-tag: instance-required 7286 Error-path: Path to the instance-identifier leaf. 7288 13.6. Error Message for Data that does not Match a leafref Type 7290 If a NETCONF operation would result in configuration data where a 7291 leaf of type "leafref" refers to a non-existing instance, the 7292 following error is returned: 7294 Tag: data-missing 7295 Error-app-tag: instance-required 7296 Error-path: Path to the leafref leaf. 7298 13.7. Error Message for Data that Violates a mandatory choice Statement 7300 If a NETCONF operation would result in configuration data where no 7301 nodes exists in a mandatory choice, the following error is returned: 7303 Tag: data-missing 7304 Error-app-tag: missing-choice 7305 Error-path: Path to the element with the missing choice. 7306 Error-info: : Contains the name of the missing 7307 mandatory choice. 7309 The element is in the YANG 7310 namespace ("urn:ietf:params:xml:ns:yang:1"). 7312 13.8. Error Message for the "insert" Operation 7314 If the "insert" and "key" or "value" attributes are used in an 7315 for a list or leaf-list node, and the "key" or "value" 7316 refers to a non-existing instance, the following error is returned: 7318 Tag: bad-attribute 7319 Error-app-tag: missing-instance 7321 14. IANA Considerations 7323 This document defines a registry for YANG module and submodule names. 7324 The name of the registry is "YANG Module Names". 7326 The registry shall record for each entry: 7328 o the name of the module or submodule 7330 o for modules, the assigned XML namespace 7332 o for modules, the prefix of the module 7334 o for submodules, the name of the module it belongs to 7336 o a reference to the (sub)module's documentation (the RFC number) 7338 For allocation, RFC publication is required as per RFC 5226 7339 [RFC5226]. All registered YANG module names must comply with the 7340 rules for identifiers stated in Section 6.2. There are no initial 7341 assignments. 7343 The module name prefix 'ietf-' is reserved for IETF stream documents 7344 [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF 7345 stream documents. Modules published in other RFC streams must have a 7346 similar suitable prefix. The prefix 'iana-' is reserved for modules 7347 maintained by IANA. 7349 All module and submodule names in the registry MUST be unique. 7351 All XML namespaces in the registry MUST be unique. 7353 This document registers two URIs for the YANG and YIN XML namespaces 7354 in the IETF XML registry [RFC3688]. Following the format in RFC 7355 3688, the following registration is requested. 7357 URI: urn:ietf:params:xml:ns:yang:yin:1 7358 URI: urn:ietf:params:xml:ns:yang:1 7360 Registrant Contact: The IESG. 7362 XML: N/A, the requested URIs are XML namespaces. 7364 15. Security Considerations 7366 This document defines a language with which to write and read 7367 descriptions of management information. The language itself has no 7368 security impact on the Internet. 7370 The same considerations are relevant as for the base NETCONF protocol 7371 (See [RFC4741], section 9). 7373 Data modeled in YANG might contain sensitive information. RPCs or 7374 notifications defined in YANG might transfer sensitive information. 7376 Security issues are related to the usage of data modeled in YANG. 7377 Such issues shall be dealt with in documents describing the data 7378 models and documents about the interfaces used to manipulate the data 7379 e.g., the NETCONF documents. 7381 Data modeled in YANG is dependent upon: 7383 o the security of the transmission infrastructure used to send 7384 sensitive information 7386 o the security of applications which store or release such sensitive 7387 information. 7389 o adequate authentication and access control mechanisms to restrict 7390 the usage of sensitive data. 7392 16. Contributors 7394 The following people all contributed significantly to the initial 7395 YANG draft: 7397 - Andy Bierman (Netconf Central) 7398 - Balazs Lengyel (Ericsson) 7399 - David Partain (Ericsson) 7400 - Juergen Schoenwaelder (Jacobs University Bremen) 7401 - Phil Shafer (Juniper Networks) 7403 17. Acknowledgements 7405 The editor wishes to thank the following individuals, who all 7406 provided helpful comments on various versions of this document: 7407 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 7408 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 7409 Wijnen. 7411 18. References 7413 18.1. Normative References 7415 [ISO.10646] 7416 International Organization for Standardization, 7417 "Information Technology - Universal Multiple-octet coded 7418 Character Set (UCS) - Part 1: Architecture and Basic 7419 Multilingual Plane", ISO Standard 10646-1, May 1993. 7421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7422 Requirement Levels", BCP 14, RFC 2119, March 1997. 7424 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 7425 10646", STD 63, RFC 3629, November 2003. 7427 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 7428 January 2004. 7430 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 7431 Resource Identifier (URI): Generic Syntax", STD 66, 7432 RFC 3986, January 2005. 7434 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 7435 Encodings", RFC 4648, October 2006. 7437 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 7438 December 2006. 7440 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 7441 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 7442 May 2008. 7444 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 7445 Specifications: ABNF", STD 68, RFC 5234, January 2008. 7447 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 7448 Notifications", RFC 5277, July 2008. 7450 [XML-NAMES] 7451 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 7452 Layman, "Namespaces in XML 1.0 (Third Edition)", World 7453 Wide Web Consortium Recommendation REC-xml-names-20091208, 7454 December 2009, 7455 . 7457 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 7458 Version 1.0", World Wide Web Consortium 7459 Recommendation REC-xpath-19991116, November 1999, 7460 . 7462 [XSD-TYPES] 7463 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 7464 Second Edition", World Wide Web Consortium 7465 Recommendation REC-xmlschema-2-20041028, October 2004, 7466 . 7468 18.2. Non-Normative References 7470 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7471 Schoenwaelder, Ed., "Structure of Management Information 7472 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 7474 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7475 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 7476 STD 58, RFC 2579, April 1999. 7478 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 7479 Structure of Management Information", RFC 3780, May 2004. 7481 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 7482 Series and RFC Editor", RFC 4844, July 2007. 7484 [XPATH2.0] 7485 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 7486 Kay, M., Robie, J., and J. Simeon, "XML Path Language 7487 (XPath) 2.0", World Wide Web Consortium 7488 Recommendation REC-xpath20-20070123, January 2007, 7489 . 7491 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 7492 Wide Web Consortium Recommendation REC-xslt-19991116, 7493 November 1999, 7494 . 7496 Appendix A. ChangeLog 7498 RFC Editor: remove this section upon publication as an RFC. 7500 A.1. Version -12 7502 o Editorial fixes after IETF Last Call. 7504 A.2. Version -11 7506 o New Copyright text and some editorial fixes. 7508 A.3. Version -10 7510 o Added "description" and "reference" as substatements to "when". 7512 o Make sure identifiers are XML compatible, i.e. do not start with 7513 "xml". 7515 o Use the terms "data node" and "schema node" instead of "node" in 7516 the Terminology section. 7518 o Use the character "@" as separator in recommended file names. 7520 o Require a new "revision" statement in new versions of published 7521 modules. 7523 o Specified which error codes processing should 7524 generate. 7526 o Various editorial fixes and enhancements. 7528 A.4. Version -09 7530 o Specified that we do not specify formal rules for how the server 7531 may modify configuration data stores. 7533 o Added rule to allow defaults to be added to leafs in an updated 7534 module. 7536 o Clarified how ordered-by user lists and leaf-lists entries are 7537 encoded in XML. 7539 o Clarified how child nodes to "case" are encoded in the XML. 7541 A.5. Version -08 7543 o Clarified text on leaf deafults. 7545 o Added the term "top-level data node" to the terminology section. 7547 o Clarified how prefixes are mapped to namespaces in XPath 7548 expressions. 7550 o Added "reference" as a substatement to "revision". 7552 o Added "choice" as a substatement to "case". 7554 o Clarified that a leafreaf must be conditional if the leaf it 7555 refers to is conditional. 7557 o Clarified how identityref default values are represented. 7559 o Various bug fixes, clarifications and editorial fixes. 7561 A.6. Version -07 7563 o The argument string of "augment", "refine", and "deviation" is 7564 described not as an XPath but as a "schema node identifier". 7566 o Clarified that there must be no circular references in a leafref. 7568 A.7. Version -06 7570 o Various bug fixes, clarifications and editorial fixes after WGLC. 7572 o Removed "require-instance" for leafref. 7574 o Allow leafrefs to refer to leaf-lists. 7576 o Clarified the XPath context in Section 6.4.1, and for "must", 7577 "when", "augment", "path" and "instance-identifier". 7579 A.8. Version -05 7581 o Replaced the data types "float32" and "float64" with "decimal64". 7583 o Specified that the elements in the XML encoding of configuration 7584 data can occur in any order. 7586 o Clarified that "augment" cannot add multiple nodes with the same 7587 name. 7589 o Clarified what "when" means in RPC input / output. 7591 o Wrote the IANA Considerations section. 7593 o Changed requirement for minimum identifier length to 64 7594 characters. 7596 A.9. Version -04 7598 o Using "revision-date" substatement to "import" and "include". 7600 o Corrected grammar and text for instance-identifier. 7602 o Fixed bugs in some examples. 7604 o Rewrote the YIN description to use a declarative style. 7606 o Added two error codes in Section 13. 7608 o Clarified that YANG uses the same XPath data model as XSLT. 7610 o Specified which errors are generated in Section 8.3.1. 7612 o Corrected grammar for key-arg; now allowing optional prefix on 7613 each leaf identifier. 7615 o Clarified that "unique" constraints only check instances with 7616 values for all referenced leafs. 7618 o Clarified how mandatory and min-elements constraints are enforced. 7620 o Editorial fixes. 7622 A.10. Version -03 7624 o Added import by revision (yang-00413) 7626 o Changed type "keyref" to "leafref", and added the statement 7627 "require-instance" (yang-01253) 7629 o Clarified that data sent from the server must be in the canonical 7630 form. 7632 o Clarified when and how constraints in the models are enforced. 7634 o Many editorial fixes 7635 o Added more strict grammar for the "deviate" statement. 7637 A.11. Version -02 7639 o Added module update rules. (yang-00000) 7641 o Added "refine" statement as a substatement to "uses". (yang-00088) 7643 o Allow "augment" on top-level and in "uses" only. (yang-00088) 7645 o Allow "when" on all data defintion statements. (yang-00088) 7647 o Added section "Constraints" and clarified when constraints are 7648 enforced. (yang-00172) 7650 o Added "feature" and "if-feature" statements. (yang-00750) 7652 o Added "prefix" as a substatement to "belongs-to". (yang-00755) 7654 o Added section on Conformance. (yang-01281) 7656 o Added "deviation" statement. (yang-01281) 7658 o Added "identity" statement and "identityref" type. (yang-01339) 7660 o Aligned grammar for "enum" with text. 7662 A.12. Version -01 7664 o Removed "Appendix A. Derived YANG Types". 7666 o Removed "Appendix C. XML Schema Considerations". 7668 o Removed "Appendix F. Why We Need a New Modeling Language". 7670 o Moved "Appendix B. YIN" to its own section. 7672 o Moved "Appendix D. YANG ABNF Grammar" to its own section. 7674 o Moved "Appendix E. Error Responses for YANG Related Errors" into 7675 its own section. 7677 o The "input" and "output" nodes are now implicitly created by the 7678 "rpc" statement, in order for augmentation of these nodes to work 7679 correctly. 7681 o Allow "config" in "choice". 7683 o Added reference to XPath 1.0. 7685 o Using an XPath function "current()" instead of the variable 7686 "$this". 7688 o Clarified that a "must" expression in a configuration node must 7689 not reference non-configuration nodes. 7691 o Added XML encoding rules and usage examples for rpc and 7692 notification. 7694 o Removed requirement that refinements are specified in the same 7695 order as in the original grouping's definition. 7697 o Fixed whitespace issues in the ABNF grammar. 7699 o Added the term "mandatory node", and refer to it in the 7700 description of augment (see Section 7.15), and choice (see 7701 Section 7.9.3). 7703 o Added support for multiple "pattern" statements in "type". 7705 o Several clarifications and fixed typos. 7707 A.13. Version -00 7709 Changes from draft-bjorklund-netconf-yang-02.txt 7711 o Fixed bug in grammar for bit-stmt 7713 o Fixed bugs in example XPath expressions 7715 o Added keyword 'presence' to the YIN mapping table 7717 Author's Address 7719 Martin Bjorklund (editor) 7720 Tail-f Systems 7722 Email: mbj@tail-f.com