idnits 2.17.1 draft-ietf-netmod-yang-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 22, 2009) is 5290 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 5841 ** 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' Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track October 22, 2009 5 Expires: April 25, 2010 7 YANG - A data modeling language for NETCONF 8 draft-ietf-netmod-yang-08 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on April 25, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 YANG is a data modeling language used to model configuration and 47 state data manipulated by the Network Configuration Protocol 48 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 49 notifications. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 54 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9 55 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 56 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12 57 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 58 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 59 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 60 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 61 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 62 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19 63 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19 64 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 65 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 66 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 67 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23 68 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 24 69 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25 70 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 71 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 72 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 73 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28 74 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29 75 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30 76 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30 77 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30 78 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30 79 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31 80 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 32 81 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32 82 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 83 5.6.4. Announcing Conformance Information in the 84 Message . . . . . . . . . . . . . . . . . . . . . . . 33 85 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36 86 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36 87 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36 88 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 89 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36 90 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38 91 6.2.1. Identifiers and their namespaces . . . . . . . . . . 38 92 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39 93 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39 94 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39 95 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 40 96 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 40 97 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 42 98 7.1. The module Statement . . . . . . . . . . . . . . . . . . 42 99 7.1.1. The module's Substatements . . . . . . . . . . . . . 43 100 7.1.2. The yang-version Statement . . . . . . . . . . . . . 44 101 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 44 102 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 45 103 7.1.5. The import Statement . . . . . . . . . . . . . . . . 45 104 7.1.6. The include Statement . . . . . . . . . . . . . . . . 46 105 7.1.7. The organization Statement . . . . . . . . . . . . . 47 106 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 47 107 7.1.9. The revision Statement . . . . . . . . . . . . . . . 47 108 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 48 109 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 48 110 7.2.1. The submodule's Substatements . . . . . . . . . . . . 49 111 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 50 112 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 51 113 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 51 114 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 52 115 7.3.2. The typedef's type Statement . . . . . . . . . . . . 52 116 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 52 117 7.3.4. The typedef's default Statement . . . . . . . . . . . 52 118 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 53 119 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 53 120 7.4.1. The type's Substatements . . . . . . . . . . . . . . 53 121 7.5. The container Statement . . . . . . . . . . . . . . . . . 53 122 7.5.1. Containers with Presence . . . . . . . . . . . . . . 54 123 7.5.2. The container's Substatements . . . . . . . . . . . . 55 124 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 55 125 7.5.4. The must's Substatements . . . . . . . . . . . . . . 57 126 7.5.5. The presence Statement . . . . . . . . . . . . . . . 58 127 7.5.6. The container's Child Node Statements . . . . . . . . 58 128 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 58 129 7.5.8. NETCONF Operations . . . . . . . . . . 58 130 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 59 131 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 60 132 7.6.1. The leaf's default value . . . . . . . . . . . . . . 60 133 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 61 134 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 61 135 7.6.4. The leaf's default Statement . . . . . . . . . . . . 61 136 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 61 137 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 62 138 7.6.7. NETCONF Operations . . . . . . . . . . 62 139 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 63 140 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 63 141 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 64 142 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 65 143 7.7.3. The min-elements Statement . . . . . . . . . . . . . 65 144 7.7.4. The max-elements Statement . . . . . . . . . . . . . 65 145 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 66 146 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 66 147 7.7.7. NETCONF operations . . . . . . . . . . 66 148 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 67 149 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 69 150 7.8.1. The list's Substatements . . . . . . . . . . . . . . 70 151 7.8.2. The list's key Statement . . . . . . . . . . . . . . 70 152 7.8.3. The list's unique Statement . . . . . . . . . . . . . 71 153 7.8.4. The list's Child Node Statements . . . . . . . . . . 72 154 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 72 155 7.8.6. NETCONF operations . . . . . . . . . . 73 156 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 73 157 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 77 158 7.9.1. The choice's Substatements . . . . . . . . . . . . . 77 159 7.9.2. The choice's case Statement . . . . . . . . . . . . . 77 160 7.9.3. The choice's default Statement . . . . . . . . . . . 79 161 7.9.4. The choice's mandatory Statement . . . . . . . . . . 80 162 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 81 163 7.9.6. NETCONF operations . . . . . . . . . . 81 164 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 81 165 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 82 166 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 83 167 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 83 168 7.10.3. NETCONF operations . . . . . . . . . . 83 169 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 84 170 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 84 171 7.11.1. The grouping's Substatements . . . . . . . . . . . . 85 172 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 85 173 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 85 174 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 86 175 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 86 176 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 87 177 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 87 178 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 88 179 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 89 180 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 89 181 7.13.3. The output Statement . . . . . . . . . . . . . . . . 90 182 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 91 183 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 91 184 7.14. The notification Statement . . . . . . . . . . . . . . . 92 185 7.14.1. The notification's Substatements . . . . . . . . . . 93 186 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 187 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 93 188 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 94 189 7.15.1. The augment's Substatements . . . . . . . . . . . . . 95 190 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 95 191 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 192 7.16. The identity Statement . . . . . . . . . . . . . . . . . 97 193 7.16.1. The identity's Substatements . . . . . . . . . . . . 98 194 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 98 195 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 99 196 7.17. The extension Statement . . . . . . . . . . . . . . . . . 99 197 7.17.1. The extension's Substatements . . . . . . . . . . . . 100 198 7.17.2. The argument Statement . . . . . . . . . . . . . . . 100 199 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 200 7.18. Conformance-related Statements . . . . . . . . . . . . . 101 201 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 101 202 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 103 203 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 103 204 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 106 205 7.19.1. The config Statement . . . . . . . . . . . . . . . . 106 206 7.19.2. The status Statement . . . . . . . . . . . . . . . . 106 207 7.19.3. The description Statement . . . . . . . . . . . . . . 107 208 7.19.4. The reference Statement . . . . . . . . . . . . . . . 107 209 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 107 210 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 109 211 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 109 212 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 109 213 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 109 214 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 110 215 8.3.2. NETCONF Processing . . . . . . . . . . 110 216 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 111 217 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 112 218 9.1. Canonical representation . . . . . . . . . . . . . . . . 112 219 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 112 220 9.2.1. Lexicographic Representation . . . . . . . . . . . . 113 221 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 114 222 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 114 223 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 114 224 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 115 225 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 115 226 9.3.1. Lexicographic Representation . . . . . . . . . . . . 115 227 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 115 228 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 229 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 116 230 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 116 231 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 117 232 9.4.1. Lexicographic Representation . . . . . . . . . . . . 117 233 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 234 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 235 9.4.4. The length Statement . . . . . . . . . . . . . . . . 117 236 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 118 237 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 118 238 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 119 239 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 119 240 9.5.1. Lexicographic Representation . . . . . . . . . . . . 119 241 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 242 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 243 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 120 244 9.6.1. Lexicographic Representation . . . . . . . . . . . . 120 245 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 246 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 247 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 120 248 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 249 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 122 250 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 122 251 9.7.2. Lexicographic Representation . . . . . . . . . . . . 122 252 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 122 253 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 122 254 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 255 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 124 256 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 257 9.8.2. Lexicographic Representation . . . . . . . . . . . . 124 258 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 124 259 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 124 260 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 261 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 125 262 9.9.3. Lexicographic Representation . . . . . . . . . . . . 126 263 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 126 264 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 265 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 129 266 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 129 267 9.10.2. The identityref's base Statement . . . . . . . . . . 129 268 9.10.3. Lexicographic Representation . . . . . . . . . . . . 130 269 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 130 270 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130 271 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 131 272 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 273 9.11.2. Lexicographic Representation . . . . . . . . . . . . 131 274 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 131 275 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 131 276 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 132 277 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 278 9.12.2. Lexicographic Representation . . . . . . . . . . . . 132 279 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 280 9.13. The instance-identifier Built-in Type . . . . . . . . . . 133 281 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 133 282 9.13.2. The require-instance Statement . . . . . . . . . . . 134 283 9.13.3. Lexicographic Representation . . . . . . . . . . . . 134 284 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 134 285 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 134 286 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 136 287 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 288 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 139 289 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 141 290 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 143 291 13. Error Responses for YANG Related Errors . . . . . . . . . . . 165 292 13.1. Error Message for Data that Violates a unique Statement . 165 293 13.2. Error Message for Data that Violates a max-elements 294 Statement . . . . . . . . . . . . . . . . . . . . . . . . 165 295 13.3. Error Message for Data that Violates a min-elements 296 Statement . . . . . . . . . . . . . . . . . . . . . . . . 165 297 13.4. Error Message for Data that Violates a must Statement . . 166 298 13.5. Error Message for Data that Violates a 299 require-instance Statement . . . . . . . . . . . . . . . 166 300 13.6. Error Message for Data that does not Match a leafref 301 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 166 302 13.7. Error Message for Data that Violates a mandatory 303 choice Statement . . . . . . . . . . . . . . . . . . . . 166 304 13.8. Error Message for the "insert" Operation . . . . . . . . 167 305 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 168 306 15. Security Considerations . . . . . . . . . . . . . . . . . . . 169 307 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 170 308 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 171 309 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 172 310 18.1. Normative References . . . . . . . . . . . . . . . . . . 172 311 18.2. Non-Normative References . . . . . . . . . . . . . . . . 173 312 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 174 313 A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 174 314 A.2. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 174 315 A.3. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 174 316 A.4. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 174 317 A.5. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 175 318 A.6. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 175 319 A.7. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 176 320 A.8. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 176 321 A.9. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 177 322 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 178 324 1. Introduction 326 YANG is a data modeling language used to model configuration and 327 state data manipulated by the Network Configuration Protocol 328 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 329 notifications. YANG is used to model the operations and content 330 layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], 331 section 1.1). 333 This document describes the syntax and semantics of the YANG 334 language, how the data model defined in a YANG module is represented 335 in XML, and how NETCONF operations are used to manipulate the data. 337 2. Key Words 339 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 340 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 341 "OPTIONAL" in this document are to be interpreted as described in BCP 342 14, [RFC2119]. 344 3. Terminology 346 o anyxml: A node which can contain an unknown chunk of XML data. 348 o augment: Adds new nodes to a previously defined node. 350 o base type: The type from which a derived type was derived, which 351 may be either a built-in type or another derived type. 353 o built-in type: A YANG data type defined in the YANG language, such 354 as uint32 or string. 356 o choice: A node where only one of a number of identified 357 alternative nodes is valid. 359 o configuration data: The set of writable data that is required to 360 transform a system from its initial default state into its current 361 state [RFC4741]. 363 o conformance: A measure of how accurately a device follows the 364 model. 366 o container: An interior node in the data tree which exist in at 367 most one instance. A container node has no value, but rather a 368 set of child nodes. 370 o data definition statement: A statement that defines new data 371 nodes. One of container, leaf, leaf-list, list, choice, case, 372 augment, uses, and anyxml. 374 o data model: A data model describes how data is represented and 375 accessed. 377 o data node: A node in the schema tree that can be instantiated in a 378 data tree. One of container, leaf, leaf-list, list, and anyxml. 380 o data tree: The instantiated tree of configuration and state data 381 on a device. 383 o derived type: A type which is derived from a built-in type (such 384 as uint32), or another derived type. 386 o device deviation: A failure of the device to implement the module 387 faithfully. 389 o extension: An extension attaches non-YANG semantics to nodes. The 390 extension statement defines new statements to express these 391 semantics. 393 o feature: A mechanism for marking a portion of the model as 394 optional. Definitions can be tagged with a feature name and are 395 only valid on devices which support that feature. 397 o grouping: A reusable set of nodes, which may be used locally in 398 the module, in modules which include it, and by other modules 399 which import from it. The grouping statement is not a data 400 definition statement and, as such, does not define any nodes in 401 the schema tree. 403 o identifier: Used to identify different kinds of YANG items by 404 name. 406 o instance identifier: A mechanism for identifying a particular node 407 in a data tree. 409 o interior node: Nodes within a hierarchy that are not leaf nodes. 411 o leaf: A node in the data tree with a value but no child nodes. 413 o leaf-list: Like the leaf node but defines a set of uniquely 414 identifiable nodes rather than a single node. Each node has a 415 value but no child nodes. 417 o list: Interior nodes in the data tree which may exist in multiple 418 instances. A list node has no value, but rather a set of child 419 nodes. 421 o module: A YANG module defines a hierarchy of nodes which can be 422 used for NETCONF-based operations. With its definitions and the 423 definitions it imports or includes from elsewhere, a module is 424 self-contained and "compilable". 426 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 428 o RPC method: A specific Remote Procedure Call, as used within the 429 NETCONF protocol. Also called a protocol operation. 431 o schema node: A node in the schema tree. One of container, leaf, 432 leaf-list, list, choice, case, rpc, input, output, notification, 433 and anyxml. 435 o schema node identifier: A mechanism for identifying a particular 436 node in the schema tree. 438 o schema tree: The definition hierarchy specified within a module. 440 o state data: The additional data on a system that is not 441 configuration data such as read-only status information and 442 collected statistics [RFC4741]. 444 o submodule: A partial module definition which contributes derived 445 types, groupings, data nodes, RPCs, and notifications to a module. 446 A YANG module can be constructed from a number of submodules. 448 o top-level data node: A data node where there is no other data node 449 between it and a module or submodule statement. 451 o uses: The "uses" statement is used to instantiate the set of nodes 452 defined in a grouping statement. The instantiated nodes may be 453 refined and augmented to tailor them to any specific needs. 455 3.1. Mandatory nodes 457 A mandatory node is one of: 459 o A leaf, choice, or anyxml node with a "mandatory" statement with 460 the value "true". 462 o A list or leaf-list node with a "min-elements" statement with a 463 value greater than zero. 465 o A container node without a "presence" statement, which has at 466 least one mandatory node as a child. 468 4. YANG Overview 470 4.1. Functional Overview 472 YANG is a language used to model data for the NETCONF protocol. A 473 YANG module defines a hierarchy of data which can be used for 474 NETCONF-based operations, including configuration, state data, remote 475 procedure calls (RPCs), and notifications. This allows a complete 476 description of all data sent between a NETCONF client and server. 478 YANG models the hierarchical organization of data as a tree in which 479 each node has a name, and either a value or a set of child nodes. 480 YANG provides clear and concise descriptions of the nodes, as well as 481 the interaction between those nodes. 483 YANG structures data models into modules and submodules. A module 484 can import data from other external modules, and include data from 485 submodules. The hierarchy can be augmented, allowing one module to 486 add data nodes to the hierarchy defined in another module. This 487 augmentation can be conditional, with new nodes appearing only if 488 certain conditions are met. 490 YANG models can describe constraints to be enforced on the data, 491 restricting the appearance or value of nodes based on the presence or 492 value of other nodes in the hierarchy. These constraints are 493 enforceable by either the client or the server, and valid content 494 must abide by them. 496 YANG defines a set of built-in types, and has a type mechanism 497 through which additional types may be defined. Derived types can 498 restrict their base type's set of valid values using mechanisms like 499 range or pattern restrictions that can be enforced by clients or 500 servers. They can also define usage conventions for use of the 501 derived type, such as a string-based type that contains a host name. 503 YANG permits the definition of complex types using reusable grouping 504 of nodes. The instantiation of these groupings can refine or augment 505 the nodes, allowing it to tailor the nodes to its particular needs. 506 Derived types and groupings can be defined in one module or submodule 507 and used in either that location or in another module or submodule 508 that imports or includes it. 510 YANG organizational constructs include defining lists where list 511 entries are identified by keys which distinguish them from each 512 other. Such lists may be defined as either sorted by user or 513 automatically sorted by the system. For user-sorted lists, 514 operations are defined for manipulating the order of the list 515 entries. 517 YANG modules can be translated into an XML format called YANG 518 Independent Notation (YIN) (Section 11), allowing applications using 519 XML parsers and XSLT scripts to operate on the models. The 520 conversion from YANG to YIN is loss-less, so content in YIN can be 521 round-tripped back into YANG. 523 YANG strikes a balance between high-level data modeling and low-level 524 bits-on-the-wire encoding. The reader of a YANG module can see the 525 high-level view of the data model while understanding how the data 526 will be encoded in NETCONF operations. 528 YANG is an extensible language, allowing extension statements to be 529 defined by standards bodies, vendors, and individuals. The statement 530 syntax allows these extensions to coexist with standard YANG 531 statements in a natural way, while making extensions stand out 532 sufficiently for the reader to notice them. 534 YANG resists the tendency to solve all possible problems, limiting 535 the problem space to allow expression of NETCONF data models, not 536 arbitrary XML documents or arbitrary data models. The data models 537 described by YANG are designed to be easily operated upon by NETCONF 538 operations. 540 To the extent possible, YANG maintains compatibility with SNMP's 541 SMIv2 (Structure of Management Information version 2 [RFC2578], 542 [RFC2579]). SMIv2-based MIB modules can be automatically translated 543 into YANG modules for read-only access. However YANG is not 544 concerned with reverse translation from YANG to SMIv2. 546 Like NETCONF, YANG targets smooth integration with device's native 547 management infrastructure. This allows implementations to leverage 548 their existing access control mechanisms to protect or expose 549 elements of the data model. 551 4.2. Language Overview 553 This section introduces some important constructs used in YANG that 554 will aid in the understanding of the language specifics in later 555 sections. This progressive approach handles the inter-related nature 556 of YANG concepts and statements. A detailed description of YANG 557 statements and syntax begins in Section 7. 559 4.2.1. Modules and Submodules 561 A module contains three types of statements: module-header 562 statements, revision statements, and definition statements. The 563 module header statements describe the module and give information 564 about the module itself, the revision statements give information 565 about the history of the module, and the definition statements are 566 the body of the module where the data model is defined. 568 A NETCONF server may implement a number of modules, allowing multiple 569 views of the same data, or multiple views of disjoint subsections of 570 the device's data. Alternatively, the server may implement only one 571 module that defines all available data. 573 A module may be divided into submodules, based on the needs of the 574 module owner. The external view remains that of a single module, 575 regardless of the presence or size of its submodules. 577 The "include" statement allows a module or submodule to reference 578 material in submodules, and the "import" statement allows references 579 to material defined in other modules. 581 4.2.2. Data Modeling Basics 583 YANG defines four types of nodes for data modeling. In each of the 584 following subsections, the example shows the YANG syntax as well as a 585 corresponding NETCONF XML representation. 587 4.2.2.1. Leaf Nodes 589 A leaf node contains simple data like an integer or a string. It has 590 exactly one value of a particular type, and no child nodes. 592 YANG Example: 594 leaf host-name { 595 type string; 596 description "Hostname for this system"; 597 } 599 NETCONF XML Example: 601 my.example.com 603 The "leaf" statement is covered in Section 7.6. 605 4.2.2.2. Leaf-list Nodes 607 A leaf-list is a sequence of leaf nodes with exactly one value of a 608 particular type per leaf. 610 YANG Example: 612 leaf-list domain-search { 613 type string; 614 description "List of domain names to search"; 615 } 617 NETCONF XML Example: 619 high.example.com 620 low.example.com 621 everywhere.example.com 623 The "leaf-list" statement is covered in Section 7.7. 625 4.2.2.3. Container Nodes 627 A container node is used to group related nodes in a subtree. A 628 container has only child nodes and no value. A container may contain 629 any number of child nodes of any type (including leafs, lists, 630 containers, and leaf-lists). 632 YANG Example: 634 container system { 635 container login { 636 leaf message { 637 type string; 638 description 639 "Message given at start of login session"; 640 } 641 } 642 } 644 NETCONF XML Example: 646 647 648 Good morning, Dave 649 650 652 The "container" statement is covered in Section 7.5. 654 4.2.2.4. List Nodes 656 A list defines a sequence of list entries. Each entry is like a 657 structure or a record instance, and is uniquely identified by the 658 values of its key leafs. A list can define multiple keys and may 659 contain any number of child nodes of any type (including leafs, 660 lists, containers etc.). 662 YANG Example: 664 list user { 665 key "name"; 666 leaf name { 667 type string; 668 } 669 leaf full-name { 670 type string; 671 } 672 leaf class { 673 type string; 674 } 675 } 677 NETCONF XML Example: 679 680 glocks 681 Goldie Locks 682 intruder 683 684 685 snowey 686 Snow White 687 free-loader 688 689 690 rzull 691 Repun Zell 692 tower 693 695 The "list" statement is covered in Section 7.8. 697 4.2.2.5. Example Module 699 These statements are combined to define the module: 701 // Contents of "acme-system.yang" 702 module acme-system { 703 namespace "http://acme.example.com/system"; 704 prefix "acme"; 706 organization "ACME Inc."; 707 contact "joe@acme.example.com"; 708 description 709 "The module for entities implementing the ACME system."; 711 revision 2007-06-09 { 712 description "Initial revision."; 713 } 715 container system { 716 leaf host-name { 717 type string; 718 description "Hostname for this system"; 719 } 721 leaf-list domain-search { 722 type string; 723 description "List of domain names to search"; 724 } 726 container login { 727 leaf message { 728 type string; 729 description 730 "Message given at start of login session"; 731 } 733 list user { 734 key "name"; 735 leaf name { 736 type string; 737 } 738 leaf full-name { 739 type string; 740 } 741 leaf class { 742 type string; 743 } 744 } 745 } 746 } 747 } 749 4.2.3. State Data 751 YANG can model state data, as well as configuration data, based on 752 the "config" statement. When a node is tagged with "config false", 753 its subhierarchy is flagged as state data, to be reported using 754 NETCONF's operation, not the operation. Parent 755 containers, lists, and key leafs are reported also, giving the 756 context for the state data. 758 In this example, two leafs are defined for each interface, a 759 configured speed and an observed speed. The observed speed is not 760 configuration, so it can be returned with NETCONF operations, 761 but not with operations. The observed speed is not 762 configuration data, and cannot be manipulated using . 764 list interface { 765 key "name"; 767 leaf name { 768 type string; 769 } 770 leaf speed { 771 type enumeration { 772 enum 10m; 773 enum 100m; 774 enum auto; 775 } 776 } 777 leaf observed-speed { 778 type uint32; 779 config false; 780 } 781 } 783 4.2.4. Built-in Types 785 YANG has a set of built-in types, similar to those of many 786 programming languages, but with some differences due to special 787 requirements from the management domain. The following table 788 summarizes the built-in types discussed in Section 9: 790 +---------------------+-------------+-------------------------------+ 791 | Name | Type | Description | 792 +---------------------+-------------+-------------------------------+ 793 | binary | Text | Any binary data | 794 | bits | Text/Number | A set of bits or flags | 795 | boolean | Text | "true" or "false" | 796 | decimal64 | Number | 64-bit signed decimal number | 797 | empty | Empty | A leaf that does not have any | 798 | | | value | 799 | enumeration | Text/Number | Enumerated strings with | 800 | | | associated numeric values | 801 | identityref | Text | A reference to an abstract | 802 | | | identity | 803 | instance-identifier | Text | References a data tree node | 804 | int8 | Number | 8-bit signed integer | 805 | int16 | Number | 16-bit signed integer | 806 | int32 | Number | 32-bit signed integer | 807 | int64 | Number | 64-bit signed integer | 808 | leafref | Text/Number | A reference to a leaf | 809 | | | instance | 810 | string | Text | Human readable string | 811 | uint8 | Number | 8-bit unsigned integer | 812 | uint16 | Number | 16-bit unsigned integer | 813 | uint32 | Number | 32-bit unsigned integer | 814 | uint64 | Number | 64-bit unsigned integer | 815 | union | Text/Number | Choice of member types | 816 +---------------------+-------------+-------------------------------+ 818 The "type" statement is covered in Section 7.4. 820 4.2.5. Derived Types (typedef) 822 YANG can define derived types from base types using the "typedef" 823 statement. A base type can be either a built-in type or a derived 824 type, allowing a hierarchy of derived types. 826 A derived type can be used as the argument for the "type" statement. 828 YANG Example: 830 typedef percent { 831 type uint8 { 832 range "0 .. 100"; 833 } 834 description "Percentage"; 835 } 837 leaf completed { 838 type percent; 839 } 841 NETCONF XML Example: 843 20 845 The "typedef" statement is covered in Section 7.3. 847 4.2.6. Reusable Node Groups (grouping) 849 Groups of nodes can be assembled into the equivalent of complex types 850 using the "grouping" statement. "grouping" defines a set of nodes 851 that are instantiated with the "uses" statement: 853 grouping target { 854 leaf address { 855 type inet:ip-address; 856 description "Target IP address"; 857 } 858 leaf port { 859 type inet:port-number; 860 description "Target port number"; 861 } 862 } 864 container peer { 865 container destination { 866 uses target; 867 } 868 } 870 NETCONF XML Example: 872 873 874
192.0.2.1
875 830 876 877 879 The grouping can be refined as it is used, allowing certain 880 statements to be overridden. In this example, the description is 881 refined: 883 container connection { 884 container source { 885 uses target { 886 refine "address" { 887 description "Source IP address"; 888 } 889 refine "port" { 890 description "Source port number"; 891 } 892 } 893 } 894 container destination { 895 uses target { 896 refine "address" { 897 description "Destination IP address"; 898 } 899 refine "port" { 900 description "Destination port number"; 901 } 902 } 903 } 904 } 906 The "grouping" statement is covered in Section 7.11. 908 4.2.7. Choices 910 YANG allows the data model to segregate incompatible nodes into 911 distinct choices using the "choice" and "case" statements. The 912 "choice" statement contains a set of "case" statements which define 913 sets of schema nodes that cannot appear together. Each "case" may 914 contain multiple nodes, but each node may appear in only one "case" 915 under a "choice". 917 When an element from one case is created, all elements from all other 918 cases are implicitly deleted. The device handles the enforcement of 919 the constraint, preventing incompatibilities from existing in the 920 configuration. 922 The choice and case nodes appear only in the schema tree, not in the 923 data tree or NETCONF PDUs. The additional levels of hierarchy are 924 not needed beyond the conceptual schema. 926 YANG Example: 928 container food { 929 choice snack { 930 case sports-arena { 931 leaf pretzel { 932 type empty; 933 } 934 leaf beer { 935 type empty; 936 } 937 } 938 case late-night { 939 leaf chocolate { 940 type enumeration { 941 enum dark; 942 enum milk; 943 enum first-available; 944 } 945 } 946 } 947 } 948 } 950 NETCONF XML Example: 952 953 954 955 957 The "choice" statement is covered in Section 7.9. 959 4.2.8. Extending Data Models (augment) 961 YANG allows a module to insert additional nodes into data models, 962 including both the current module (and its submodules) or an external 963 module. This is useful for example for vendors to add vendor- 964 specific parameters to standard data models in an interoperable way. 966 The "augment" statement defines the location in the data model 967 hierarchy where new nodes are inserted, and the "when" statement 968 defines the conditions when the new nodes are valid. 970 YANG Example: 972 augment /system/login/user { 973 when "class != 'wheel'"; 974 leaf uid { 975 type uint16 { 976 range "1000 .. 30000"; 977 } 978 } 979 } 981 This example defines a "uid" node that only is valid when the user's 982 "class" is not "wheel". 984 If a module augments another module, the XML representation of the 985 data will reflect the prefix of the augmenting module. For example, 986 if the above augmentation were in a module with prefix "other", the 987 XML would look like: 989 NETCONF XML Example: 991 992 alicew 993 Alice N. Wonderland 994 drop-out 995 1024 996 998 The "augment" statement is covered in Section 7.15. 1000 4.2.9. RPC Definitions 1002 YANG allows the definition of NETCONF RPCs. The method names, input 1003 parameters and output parameters are modeled using YANG data 1004 definition statements. 1006 YANG Example: 1008 rpc activate-software-image { 1009 input { 1010 leaf image-name { 1011 type string; 1012 } 1013 } 1014 output { 1015 leaf status { 1016 type string; 1017 } 1018 } 1019 } 1021 NETCONF XML Example: 1023 1025 1026 acmefw-2.3 1027 1028 1030 1032 1033 The image acmefw-2.3 is being installed. 1034 1035 1037 The "rpc" statement is covered in Section 7.13. 1039 4.2.10. Notification Definitions 1041 YANG allows the definition of notifications suitable for NETCONF. 1042 YANG data definition statements are used to model the content of the 1043 notification. 1045 YANG Example: 1047 notification link-failure { 1048 description "A link failure has been detected"; 1049 leaf if-name { 1050 type leafref { 1051 path "/interfaces/interface/name"; 1052 } 1053 } 1054 leaf if-admin-status { 1055 type admin-status; 1056 } 1057 leaf if-oper-status { 1058 type oper-status; 1059 } 1060 } 1062 NETCONF XML Example: 1064 1066 2007-09-01T10:00:00Z 1067 1068 so-1/2/3.0 1069 up 1070 down 1071 1072 1074 The "notification" statement is covered in Section 7.14. 1076 5. Language Concepts 1078 5.1. Modules and Submodules 1080 The module is the base unit of definition in YANG. A module defines 1081 a single data model. A module can define a complete, cohesive model, 1082 or augment an existing data model with additional nodes. 1084 Submodules are partial modules that contribute definitions to a 1085 module. A module may include any number of submodules, but each 1086 submodule may belong to only one module. 1088 The names of all standard modules and submodules MUST be unique. 1089 Developers of enterprise modules are RECOMMENDED to choose names for 1090 their modules that will have a low probability of colliding with 1091 standard or other enterprise modules, e.g., by using the enterprise 1092 or organization name as a prefix for the module name. 1094 A module uses the "include" statement to include its submodules, and 1095 the "import" statement to reference external modules. Similarly, a 1096 submodule uses the "import" statement to reference other modules, and 1097 uses the "include" statement to reference other submodules within its 1098 module. A module or submodule MUST NOT include submodules from other 1099 modules, and a submodule MUST NOT import its own module. 1101 The import and include statements are used to make definitions 1102 available to other modules and submodules: 1104 o For a module or submodule to reference definitions in an external 1105 module, the external module MUST be imported. 1107 o For a module to reference definitions in one of its submodules, 1108 the module MUST include the submodule. 1110 o For a submodule to reference definitions in a second submodule of 1111 the same module, the first submodule MUST include the second 1112 submodule. 1114 There MUST NOT be any circular chains of imports or includes. For 1115 example, if submodule "a" includes submodule "b", "b" cannot include 1116 "a". 1118 When a definition in an external module is referenced, a locally 1119 defined prefix MUST be used, followed by ":", and then the external 1120 identifier. References to definitions in the local module MAY use 1121 the prefix notation. Since built-in data types do not belong to any 1122 module and have no prefix, references to built-in data types (e.g., 1123 int32) cannot use the prefix notation. 1125 5.1.1. Import and Include by Revision 1127 Published modules evolve independently over time. In order to allow 1128 for this evolution, modules need to be imported using specific 1129 revisions. When a module is written, it uses the current revisions 1130 of other modules, based on what is available at the time. As future 1131 revisions of the imported modules are published, the importing module 1132 is unaffected and its contents are unchanged. When the author of the 1133 module is prepared to move to the most recently published revision of 1134 an imported module, the module is republished with an updated import 1135 statement. By republishing with the new revision, the authors 1136 explicitly indicate their acceptance of any changes in the imported 1137 module. 1139 For submodules, the issue is related but simpler. A module or 1140 submodule that includes submodules need to specify the revision of 1141 the included submodules. If a submodule changes, any module or 1142 submodule that includes it needs to be updated. 1144 For example, module "b" imports module "a". 1146 module a { 1147 revision 2008-01-01 { ... } 1148 grouping a { 1149 leaf eh { .... } 1150 } 1151 } 1153 module b { 1154 import a { 1155 prefix p; 1156 revision-date 2008-01-01; 1157 } 1159 container bee { 1160 uses p:a; 1161 } 1162 } 1164 When the author of "a" publishes a new revision, the changes may not 1165 be acceptable to the author of "b". If the new revision is 1166 acceptable, the author of "b" can republish with an updated revision 1167 in the import statement. 1169 5.1.2. Module Hierarchies 1171 YANG allows modeling of data in multiple hierarchies, where data may 1172 have more than one top-level node. Models that have multiple top- 1173 level nodes are sometimes convenient, and are supported by YANG. 1175 NETCONF is capable of carrying any XML content as the payload in the 1176 and elements. The top-level nodes of YANG modules 1177 are encoded as child elements within these elements. This 1178 encapsulation guarantees that the corresponding NETCONF PDUs are 1179 always well-formed XML documents. 1181 For example: 1183 module my-config { 1184 namespace "http://example.com/schema/config"; 1185 prefix "co"; 1187 container system { ... } 1188 container routing { ... } 1189 } 1191 could be encoded in NETCONF as: 1193 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1211 5.2. File Layout 1213 YANG modules and submodules are typically stored in files, one module 1214 or submodule per file. The name of the file SHOULD be of the form: 1216 module-or-submodule-name ['.' revision-date] ( '.yang' / '.yin' ) 1218 YANG compilers can find imported modules and included submodules via 1219 this convention. While the YANG language defines modules, tools may 1220 compile submodules independently for performance and manageability 1221 reasons. Many errors and warnings that cannot be detected during 1222 submodule compilation may be delayed until the submodules are linked 1223 into a cohesive module. 1225 5.3. XML Namespaces 1227 All YANG definitions are specified within a module that is bound to a 1228 particular XML Namespace [XML-NAMES], which is a globally unique URI 1229 [RFC3986]. A NETCONF client or server uses the namespace during XML 1230 encoding of data. 1232 Namespaces for modules published in RFC streams MUST be assigned by 1233 IANA, see Section 14. 1235 Namespaces for private modules are assigned by the organization 1236 owning the module without a central registry. Namespace URIs MUST be 1237 choosen so they cannot collide with standard or other enterprise 1238 namespaces, for example by using the enterprise or organization name 1239 in the namespace. 1241 The "namespace" statement is covered in Section 7.1.3. 1243 5.3.1. YANG XML Namespace 1245 YANG defines an XML namespace for NETCONF operations 1246 and content. This namespace is 1247 "urn:ietf:params:xml:ns:yang:1". 1249 5.4. Resolving Grouping, Type, and Identity Names 1251 Grouping, type, and identity names are resolved in the context in 1252 which they are defined, rather than the context in which they are 1253 used. Users of groupings, typedefs, and identities are not required 1254 to import modules or include submodules to satisfy all references 1255 made by the original definition. This behaves like static scoping in 1256 a conventional programming language. 1258 For example, if a module defines a grouping in which a type is 1259 referenced, when the grouping is used in a second module, the type is 1260 resolved in the context of the original module, not the second 1261 module. There is no worry over conflicts if both modules define the 1262 type, since there is no ambiguity. 1264 5.5. Nested Typedefs and Groupings 1266 Typedefs and groupings may appear nested under many YANG statements, 1267 allowing these to be lexically scoped by the hierarchy under which 1268 they appear. This allows types and groupings to be defined near 1269 where they are used, rather than placing them at the top level of the 1270 hierarchy. The close proximity increases readability. 1272 Scoping also allows types to be defined without concern for naming 1273 conflicts between types in different submodules. Type names can be 1274 specified without adding leading strings designed to prevent name 1275 collisions within large modules. 1277 Finally, scoping allows the module author to keep types and groupings 1278 private to their module or submodule, preventing their reuse. Since 1279 only top-level types and groupings (i.e., those appearing as 1280 substatements to a module or submodule statement) can be used outside 1281 the module or submodule, the developer has more control over what 1282 pieces of their module are presented to the outside world, supporting 1283 the need to hide internal information and maintaining a boundary 1284 between what is shared with the outside world and what is kept 1285 private. 1287 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1288 type or grouping cannot be defined if a higher level in the schema 1289 hierarchy has a definition with a matching identifier. 1291 A reference to an unprefixed type or grouping, or one which uses the 1292 prefix of the current module, is resolved by locating the closest 1293 matching "typedef" or "grouping" statement among the immediate 1294 substatements of each ancestor statement. 1296 5.6. Conformance 1298 Conformance is a measure of how accurately a device follows the 1299 model. Generally speaking, devices are responsible for implementing 1300 the model faithfully, allowing applications to treat devices which 1301 implement the model identically. Deviations from the model can 1302 reduce the utility of the model and increase fragility of 1303 applications that use it. 1305 YANG modelers have three mechanisms for conformance: 1307 o the basic behavior of the model 1309 o optional features that are part of the model 1311 o deviations from the model 1313 We will consider each of these in sequence. 1315 5.6.1. Basic Behavior 1317 The model defines a contract between the NETCONF client and server, 1318 which allows both parties to have faith the other knows the syntax 1319 and semantics behind the modeled data. The strength of YANG lies in 1320 the strength of this contract and the mindless devotion with which 1321 implementers follow it. 1323 5.6.2. Optional Features 1325 In many models, the modeler will allow sections of the model to be 1326 conditional, based on the device. The device controls whether these 1327 conditional portions of the model are supported or valid for that 1328 particular device. 1330 For example, a syslog data model may choose to include the ability to 1331 save logs locally, but the modeler will realize that this is only 1332 possible if the device has local storage. If there is no local 1333 storage, an application should not tell the device to save logs. 1335 YANG supports this conditional mechanism using a construct called 1336 "feature". Features give the modeler a mechanism for making portions 1337 of the module conditional in a manner that is controlled by the 1338 device. The model can express constructs which are not universally 1339 present in all devices. These features are included in the model 1340 definition, allowing a consistent view and allowing applications to 1341 learn which features are supported and tailor their behavior to the 1342 device. 1344 A module may declare any number of features, identified by simple 1345 strings, and may make portions of the module optional based on those 1346 features. If the device supports a feature, then the corresponding 1347 portions of the module are valid for that device. If the device 1348 doesn't support the feature, those parts of the module are not valid, 1349 and applications should behave accordingly. 1351 Features are defined using the "feature" statement. Definitions in 1352 the module that are conditional to the feature are noted by the 1353 "if-feature" statement with the name of the feature as its argument. 1355 Further details are available in Section 7.18.1. 1357 5.6.3. Deviations 1359 In an ideal world, all devices would be required to implement the 1360 model exactly as defined, and deviations from the model would not be 1361 allowed. But in the real world, devices are often not able or 1362 willing to implement the model as written. For YANG-based automation 1363 to deal with these device deviations, a mechanism must exist for 1364 devices to inform applications of the specifics of such deviations. 1366 For example, a BGP module may allow any number of BGP peers, but a 1367 particular device may only support 16 BGP peers. Any application 1368 configuring the 17th peer will receive an error. While an error may 1369 suffice to let the application know it cannot add another peer, it 1370 would be far better if the application had prior knowledge of this 1371 limitation and could prevent the user from starting down the path 1372 that could not succeed. 1374 Device deviations are declared using the "deviation" statement, which 1375 takes as its argument a string which identifies a node in the schema 1376 tree. The contents of the statement details the manner in which the 1377 device implementation deviates from the contract as defined in the 1378 module. 1380 5.6.4. Announcing Conformance Information in the Message 1382 The namespace URI MUST be advertised as a capability in the NETCONF 1383 message to indicate support for the YANG module by a NETCONF 1384 server. The capability URI advertised MUST be on the form: 1386 capability-string = namespace-uri [ parameter-list ] 1387 parameter-list = "?" parameter *( "&" parameter ) 1388 parameter = revision-parameter / 1389 module-parameter / 1390 feature-parameter / 1391 deviation-parameter 1392 revision-parameter = "revision=" revision-date 1393 module-parameter = "module=" module-name 1394 feature-parameter = "features=" feature *( "," feature ) 1395 deviation-parameter = "deviations=" deviation *( "," deviation ) 1397 Where "revision-date" is the revision of the module (see 1398 Section 7.1.9) that the NETCONF server implements, "module-name" is 1399 the name of module as it appears in the "module" statement (see 1400 Section 7.1), "namespace-uri" is the namespace for the module as it 1401 appears in the "namespace" statement, "feature" is the name of an 1402 optional feature implemented by the device (see Section 7.18.1), and 1403 "deviation" is the name of a module defining device deviations (see 1404 Section 7.18.3). 1406 In the parameter list, each named parameter MUST occur at most once. 1408 5.6.4.1. Modules 1410 Servers indicate the names of supported modules via the 1411 message. Module namespaces are encoded as the base URI in the 1412 capability string, and the module name is encoded as the "module" 1413 parameter to the base URI. 1415 A server MUST advertise all revisions of all modules it implements. 1417 For example, this message advertises one module "syslog". 1419 1420 1421 http://example.com/syslog?module=syslog&revision=2008-04-01 1422 1423 1425 5.6.4.2. Features 1427 Servers indicate the names of supported features via the 1428 message. In hello messages, the features are encoded in the 1429 "features" parameter within the URI. The value of this parameter is 1430 a comma-separated list of feature names which the device supports for 1431 the specific module. 1433 For example, this message advertises one module, informing 1434 the client that it supports the "local-storage" feature of module 1435 "syslog". 1437 1438 1439 http://example.com/syslog?module=syslog&features=local-storage 1440 1441 1443 5.6.4.3. Deviations 1445 Device deviations are announced via the "deviations" parameter. The 1446 value of the deviations parameter is a comma-separated list of 1447 modules containing deviations from the capability's module. 1449 For example, this message advertises two modules, informing 1450 the client that it deviates from module "syslog" according to the 1451 deviations listed in the module "my-devs". 1453 1454 1455 http://example.com/syslog?module=syslog&deviations=my-devs 1456 1457 1458 http://example.com/my-deviations?module=my-devs 1459 1460 1462 6. YANG syntax 1464 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1465 languages like C and C++. This C-like syntax was chosen specifically 1466 for its readability, since YANG values the time and effort of the 1467 readers of models above those of modules writers and YANG tool-chain 1468 developers. This section introduces the YANG syntax. 1470 YANG modules use the UTF-8 [RFC3629] character encoding. 1472 6.1. Lexicographical Tokenization 1474 YANG modules are parsed as a series of tokens. This section details 1475 the rules for recognizing tokens from an input stream. YANG 1476 tokenization rules are both simple and powerful. The simplicity is 1477 driven by a need to keep the parsers easy to implement, while the 1478 power is driven by the fact that modelers need to express their 1479 models in readable formats. 1481 6.1.1. Comments 1483 Comments are C++ style. A single line comment starts with "//" and 1484 ends at the end of the line. A block comment is enclosed within "/*" 1485 and "*/". 1487 6.1.2. Tokens 1489 A token in YANG is either a keyword, a string, ";", "{", or "}". A 1490 string can be quoted or unquoted. A keyword is either one of the 1491 core YANG keywords defined in this document, or a prefix identifier, 1492 followed by ":", followed by a language extension keyword. Keywords 1493 are case sensitive. See Section 6.2 for a formal definition of 1494 identifiers. 1496 6.1.3. Quoting 1498 If a string contains any space or tab characters, a semicolon (";"), 1499 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1500 it MUST be enclosed within double or single quotes. 1502 If the double quoted string contains a line break followed by space 1503 or tab characters which are used to indent the text according to the 1504 layout in the YANG file, this leading whitespace is stripped from the 1505 string, up to the column of the double quote character, or to the 1506 first non-whitespace character, whichever occurs first. 1508 If the double quoted string contains space or tab characters before a 1509 line break, this trailing whitespace is stripped from the string. 1511 A single quoted string (enclosed within ' ') preserves each character 1512 within the quotes. A single quote character cannot occur in a single 1513 quoted string, even when preceded by a backslash. 1515 Within a double quoted string (enclosed within " "), a backslash 1516 character introduces a special character, which depends on the 1517 character that immediately follows the backslash: 1519 \n new line 1520 \t a tab character 1521 \" a double quote 1522 \\ a single backslash 1524 If a quoted string is followed by a plus character ("+"), followed by 1525 another quoted string, the two strings are concatenated into one 1526 string, allowing multiple concatenations to build one string. 1527 Whitespace trimming and substition of backslash-escaped characters in 1528 double quoted strings is done before concatenation. 1530 6.1.3.1. Quoting Examples 1532 The following strings are equivalent: 1534 hello 1535 "hello" 1536 'hello' 1537 "hel" + "lo" 1538 'hel' + "lo" 1540 The following examples show some special strings: 1542 "\"" - string containing a double quote 1543 '"' - string containing a double quote 1544 "\n" - string containing a newline character 1545 '\n' - string containing a backslash followed 1546 by the character n 1548 The following examples show some illegal strings: 1550 '''' - a single-quoted string cannot contain single quotes 1551 """ - a double quote must be escaped in a double quoted string 1553 The following strings are equivalent: 1555 "first line 1556 second line" 1558 "first line\n" + " second line" 1560 6.2. Identifiers 1562 Identifiers are used to identify different kinds of YANG items by 1563 name. Each identifier starts with an upper-case or lower-case ASCII 1564 letter or an underscore character, followed by zero or more ASCII 1565 letters, digits, underscore characters, hyphens, and dots. 1566 Implementations MUST support identifiers up to 64 characters in 1567 length. Identifiers are case sensitive. The identifier syntax is 1568 formally defined by the rule "identifier" in Section 12. Identifiers 1569 can be specified as quoted or unquoted strings. 1571 6.2.1. Identifiers and their namespaces 1573 Each identifier is valid in a namespace which depends on the type of 1574 the YANG item being defined. All identifiers defined in a namespace 1575 MUST be unique. 1577 o All module and submodule names share the same global module 1578 identifier namespace. 1580 o All extension names defined in a module and its submodules share 1581 the same extension identifier namespace. 1583 o All feature names defined in a module and its submodules share the 1584 same feature identifier namespace. 1586 o All identity names defined in a module and its submodules share 1587 the same identity identifier namespace. 1589 o All derived type names defined within a parent node or at the top- 1590 level of the module or its submodules share the same type 1591 identifier namespace. This namespace is scoped to all descendant 1592 nodes of the parent node or module. This means that any 1593 descendent node may use that typedef, and it MUST NOT define a 1594 typedef with the same name. 1596 o All grouping names defined within a parent node or at the top- 1597 level of the module or its submodules share the same grouping 1598 identifier namespace. This namespace is scoped to all descendant 1599 nodes of the parent node or module. This means that any 1600 descendent node may use that grouping, and it MUST NOT define a 1601 grouping with the same name. 1603 o All leafs, leaf-lists, lists, containers, choices, rpcs, 1604 notifications, and anyxmls defined (directly or through a uses 1605 statement) within a parent node or at the top-level of the module 1606 or its submodules share the same identifier namespace. This 1607 namespace is scoped to the parent node or module, unless the 1608 parent node is a case node. In that case, the namespace is scoped 1609 to the closest ancestor node which is not a case or choice node. 1611 o All cases within a choice share the same case identifier 1612 namespace. This namespace is scoped to the parent choice node. 1614 Forward references are allowed in YANG. 1616 6.3. Statements 1618 A YANG module contains a sequence of statements. Each statement 1619 starts with a keyword, followed by zero or one argument, followed 1620 either by a semicolon (";") or a block of substatements enclosed 1621 within braces ("{ }"): 1623 statement = keyword [argument] (";" / "{" *statement "}") 1625 The argument is a string, as defined in Section 6.1.2. 1627 6.3.1. Language Extensions 1629 A module can introduce YANG extensions by using the "extension" 1630 keyword (see Section 7.17). The extensions can be imported by other 1631 modules with the "import" statement (see Section 7.1.5). When an 1632 imported extension is used, the extension's keyword MUST be qualified 1633 using the prefix with which the extension's module was imported. If 1634 an extension is used in the module where it is defined, the 1635 extension's keyword MUST be qualified with the module's prefix. 1637 Since submodules cannot include the parent module, any extensions in 1638 the module which need to be exposed to submodules MUST be defined in 1639 a submodule. Submodules can then include this submodule to find the 1640 definition of the extension. 1642 If a YANG compiler does not support a particular extension, which 1643 appears in a YANG module as an unknown-statement (see Section 12), 1644 the entire unknown statement MAY be ignored by the compiler. 1646 6.4. XPath Evaluations 1648 YANG relies on XPath 1.0 [XPATH] as a notation for specifying many 1649 inter-node references and dependencies. NETCONF clients and servers 1650 are not required to implement an XPath interpreter, but MUST ensure 1651 that the requirements encoded in the data model are enforced. The 1652 manner of enforcement is an implementation decision. The XPath 1653 expressions MUST be syntactically correct, and all prefixes used MUST 1654 be present in the XPath context (see Section 6.4.1). An 1655 implementation may choose to implement them by hand, rather than 1656 using the XPath expression directly. 1658 The data model used in the XPath expressions is the same as that used 1659 in XPath 1.0 [XPATH], with the same extension for root node children 1660 as used by XSLT 1.0 [XSLT] (section 3.1). Specifically, it means 1661 that the root node may have any number of element nodes as its 1662 children. 1664 6.4.1. XPath Context 1666 All YANG XPath expressions share the following XPath context 1667 definition: 1669 o The set of namespace declarations is the set of all "import" 1670 statements' prefix and namespace pairs in the module where the 1671 XPath expression is specified, and the "prefix" statement's prefix 1672 for the "namespace" statement's URI. 1674 o Names without a namespace prefix belong to the same namespace as 1675 the identifier of the current node. Inside a grouping, that 1676 namespace is affected by where the grouping is used (see 1677 Section 7.12). 1679 o The function library is the core function library defined in 1680 [XPATH], and a function "current()" which returns a node set with 1681 the initial context node. 1683 o The set of variable bindings is empty. 1685 The mechanism for handling unprefixed names is adopted from XPath 2.0 1686 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1687 ambiguity may ever arise because YANG node identifiers are always 1688 qualified names with a non-null namespace URI. 1690 The context node varies with the YANG XPath expression, and is 1691 specified where the YANG statement with the XPath expression is 1692 defined. 1694 6.5. Schema Node Identifier 1696 A schema node identifier is a string that identifies a node in the 1697 schema tree. It has two forms, "absolute" and "descendant", defined 1698 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1699 in Section 12, respectively. A schema node identifier consists of a 1700 path of identifiers, separated by slashes ("/"). In an absolute 1701 schema node identifier, the first identifier after the leading slash 1702 is any top-level schema node in local module or all imported modules. 1704 References to identifiers defined in external modules MUST be 1705 qualified with appropriate prefixes, and references to identifiers 1706 defined in the current module and its submodules MAY use a prefix. 1708 For example, to identify the child node "b" of top-level node "a", 1709 the string "/a/b" can be used. 1711 7. YANG Statements 1713 The following sections describe all of the YANG core statements. 1715 Note that even a statement which does not have any substatements 1716 defined in core YANG can have vendor-specific extensions as 1717 substatements. For example, the "description" statement does not 1718 have any substatements defined in core YANG, but the following is 1719 legal: 1721 description "some text" { 1722 acme:documentation-flag 5; 1723 } 1725 7.1. The module Statement 1727 The "module" statement defines the module's name, and groups all 1728 statements which belong to the module together. The "module" 1729 statement's argument is the name of the module, followed by a block 1730 of substatements that hold detailed module information. The module 1731 name follows the rules for identifiers in Section 6.2. 1733 Names of modules published in RFC streams MUST be assigned by IANA, 1734 see Section 14. 1736 Private module names are assigned by the organization owning the 1737 module without a central registry. It is RECOMMENDED to choose 1738 module names that will have a low probability of colliding with 1739 standard or other enterprise modules and submodules, e.g., by using 1740 the enterprise or organization name as a prefix. 1742 A module SHOULD have the following layout: 1744 module { 1746 // header information 1747 1748 1749 1751 // linkage statements 1752 1753 1755 // meta information 1756 1757 1758 1759 1761 // revision history 1762 1764 // module definitions 1765 1766 } 1768 7.1.1. The module's Substatements 1769 +--------------+---------+-------------+ 1770 | substatement | section | cardinality | 1771 +--------------+---------+-------------+ 1772 | anyxml | 7.10 | 0..n | 1773 | augment | 7.15 | 0..n | 1774 | choice | 7.9 | 0..n | 1775 | contact | 7.1.8 | 0..1 | 1776 | container | 7.5 | 0..n | 1777 | description | 7.19.3 | 0..1 | 1778 | deviation | 7.18.3 | 0..n | 1779 | extension | 7.17 | 0..n | 1780 | feature | 7.18.1 | 0..n | 1781 | grouping | 7.11 | 0..n | 1782 | identity | 7.16 | 0..n | 1783 | import | 7.1.5 | 0..n | 1784 | include | 7.1.6 | 0..n | 1785 | leaf | 7.6 | 0..n | 1786 | leaf-list | 7.7 | 0..n | 1787 | list | 7.8 | 0..n | 1788 | namespace | 7.1.3 | 1 | 1789 | notification | 7.14 | 0..n | 1790 | organization | 7.1.7 | 0..1 | 1791 | prefix | 7.1.4 | 1 | 1792 | reference | 7.19.4 | 0..1 | 1793 | revision | 7.1.9 | 0..n | 1794 | rpc | 7.13 | 0..n | 1795 | typedef | 7.3 | 0..n | 1796 | uses | 7.12 | 0..n | 1797 | yang-version | 7.1.2 | 0..1 | 1798 +--------------+---------+-------------+ 1800 7.1.2. The yang-version Statement 1802 The optional "yang-version" statement specifies which version of the 1803 YANG language was used in developing the module. The statement's 1804 argument is a string. If present, it MUST contain the value "1", 1805 which is the current yang version and the default value. 1807 7.1.3. The namespace Statement 1809 The "namespace" statement defines the XML namespace to which all 1810 identifiers defined by the module belong, with the exception of data 1811 node identifiers defined inside a grouping (see Section 7.12 for 1812 details). The argument to the "namespace" statement is the URI of 1813 the namespace. 1815 See also Section 5.3. 1817 7.1.4. The prefix Statement 1819 The "prefix" statement is used to define the prefix associated with 1820 the module and its namespace. The "prefix" statement's argument is 1821 the prefix string which is used as a prefix to access a module. The 1822 prefix string MAY be used to refer to definitions contained in the 1823 module, e.g., "if:ifName". A prefix follows the same rules as an 1824 identifier (see Section 6.2). 1826 When used inside the "module" statement, the "prefix" statement 1827 defines the prefix to be used when this module is imported. To 1828 improve readability of the NETCONF XML, a NETCONF client or server 1829 which generates XML or XPath that use prefixes, the prefix defined by 1830 a module SHOULD be used, unless there is a conflict. 1832 When used inside the "import" statement, the "prefix" statement 1833 defines the prefix to be used when accessing definitions inside the 1834 imported module. When a reference to an identifier from the imported 1835 module is used, the prefix string for the imported module is used in 1836 combination with a colon (":") and the identifier, e.g., "if: 1837 ifIndex". To improve readability of YANG modules, the prefix defined 1838 by a module SHOULD be used when the module is imported, unless there 1839 is a conflict. 1841 All prefixes, including the prefix for the module itself MUST be 1842 unique within the module or submodule. 1844 7.1.5. The import Statement 1846 The "import" statement makes definitions from one module available 1847 inside another module or submodule. The argument is the name of the 1848 module to import, and the statement is followed by a block of 1849 substatements that holds detailed import information. When a module 1850 is imported, the importing module may: 1852 o use any grouping and typedef defined at the top-level in the 1853 imported module or its submodules 1855 o use any extension, feature, and identity defined in the imported 1856 module or its submodules 1858 o use any node in the imported module's schema tree in augment, 1859 must, path, and when statements 1861 The mandatory "prefix" substatement assigns a prefix for the imported 1862 module which is scoped to the importing module or submodule. 1863 Multiple "import" statements may be specified to import from 1864 different modules. 1866 When the optional "revision-date" substatement is present, any 1867 typedef, grouping, extension, feature, and identity referenced by 1868 definitions in the local module are taken from the specified revision 1869 of the imported module. Otherwise, it is undefined from which 1870 revision of the module they are taken. 1872 Multiple revisions of the same module MUST NOT be imported. 1874 The import's Substatements 1876 +---------------+---------+-------------+ 1877 | substatement | section | cardinality | 1878 +---------------+---------+-------------+ 1879 | prefix | 7.1.4 | 1 | 1880 | revision-date | 7.1.5.1 | 0..1 | 1881 +---------------+---------+-------------+ 1883 7.1.5.1. The import's revision-date Statement 1885 The import's "revision-date" statement is used to specify the exact 1886 version of the module to import. The "revision-date" statement MUST 1887 match the most recent "revision" statement in the imported module. 1889 7.1.6. The include Statement 1891 The "include" statement is used to make content from a submodule 1892 available to that submodule's parent module, or to another submodule 1893 of that parent module. The argument is an identifier which is the 1894 name of the submodule to include. Modules are only allowed to 1895 include submodules that belong to that module, as defined by the 1896 "belongs-to" statement (see Section 7.2.2). Submodules are only 1897 allowed to include other submodules belonging to the same module. 1899 When a module includes a submodule, it incorporates the contents of 1900 the submodule into the node hierarchy of the module. When a 1901 submodule includes another submodule, the target submodule's 1902 definitions are made available to the current submodule. 1904 When the optional "revision-date" is present, the specified revision 1905 of the submodule is included in the module. Otherwise, it is 1906 undefined which revision of the submodule is included. 1908 Multiple revisions of the same submodule MUST NOT be included. 1910 The includes's Substatements 1912 +---------------+---------+-------------+ 1913 | substatement | section | cardinality | 1914 +---------------+---------+-------------+ 1915 | revision-date | 7.1.5.1 | 0..1 | 1916 +---------------+---------+-------------+ 1918 7.1.7. The organization Statement 1920 The "organization" statement defines the party responsible for this 1921 module. The argument is a string which is used to specify a textual 1922 description of the organization(s) under whose auspices this module 1923 was developed. 1925 7.1.8. The contact Statement 1927 The "contact" statement provides contact information for the module. 1928 The argument is a string which is used to specify the name, postal 1929 address, telephone number, and electronic mail address of the person 1930 to whom technical queries concerning this module should be sent. 1932 7.1.9. The revision Statement 1934 The "revision" statement specifies the editorial revision history of 1935 the module, including the initial revision. A series of revisions 1936 statements detail the changes in the module's definition. The 1937 argument is a date string in the format "YYYY-MM-DD", followed by a 1938 block of substatements that holds detailed revision information. A 1939 module SHOULD have at least one initial "revision" statement. For 1940 every published editorial change, a new one SHOULD be added in front 1941 of the revisions sequence, so that all revisions are in reverse 1942 chronological order. 1944 7.1.9.1. The revision's Substatement 1946 +--------------+---------+-------------+ 1947 | substatement | section | cardinality | 1948 +--------------+---------+-------------+ 1949 | description | 7.19.3 | 0..1 | 1950 | reference | 7.19.4 | 0..1 | 1951 +--------------+---------+-------------+ 1953 7.1.10. Usage Example 1955 module acme-system { 1956 namespace "http://acme.example.com/system"; 1957 prefix "acme"; 1959 import ietf-yang-types { 1960 prefix "yang"; 1961 } 1963 include acme-types; 1965 organization "ACME Inc."; 1966 contact 1967 "Joe L. User 1969 ACME, Inc. 1970 42 Anywhere Drive 1971 Nowhere, CA 95134 1972 USA 1974 Phone: +1 800 555 0100 1975 EMail: joe@acme.example.com"; 1977 description 1978 "The module for entities implementing the ACME protocol."; 1980 revision "2007-06-09" { 1981 description "Initial revision."; 1982 } 1984 // definitions follows... 1985 } 1987 7.2. The submodule Statement 1989 While the primary unit in YANG is a module, a YANG module can itself 1990 be constructed out of several submodules. Submodules allow a module 1991 designer to split a complex model into several pieces where all the 1992 submodules contribute to a single namespace, which is defined by the 1993 module that includes the submodules. 1995 The "submodule" statement defines the submodule's name, and groups 1996 all statements which belong to the submodule together. The 1997 "submodule" statement's argument is the name of the submodule, 1998 followed by a block of substatements that hold detailed submodule 1999 information. The submodule name follows the rules for identifiers in 2000 Section 6.2. 2002 Names of submodules published in RFC streams MUST be assigned by 2003 IANA, see Section 14. 2005 Private submodule names are assigned by the organization owning the 2006 submodule without a central registry. It is RECOMMENDED to choose 2007 submodule names that will have a low probability of colliding with 2008 standard or other enterprise modules and submodules, e.g., by using 2009 the enterprise or organization name as a prefix. 2011 A submodule SHOULD have the following layout: 2013 submodule { 2015 2017 // module identification 2018 2020 // linkage statements 2021 2022 2024 // meta information 2025 2026 2027 2028 2030 // revision history 2031 2033 // module definitions 2034 2035 } 2037 7.2.1. The submodule's Substatements 2038 +--------------+---------+-------------+ 2039 | substatement | section | cardinality | 2040 +--------------+---------+-------------+ 2041 | anyxml | 7.10 | 0..n | 2042 | augment | 7.15 | 0..n | 2043 | belongs-to | 7.2.2 | 1 | 2044 | choice | 7.9 | 0..n | 2045 | contact | 7.1.8 | 0..1 | 2046 | container | 7.5 | 0..n | 2047 | description | 7.19.3 | 0..1 | 2048 | deviation | 7.18.3 | 0..n | 2049 | extension | 7.17 | 0..n | 2050 | feature | 7.18.1 | 0..n | 2051 | grouping | 7.11 | 0..n | 2052 | identity | 7.16 | 0..n | 2053 | import | 7.1.5 | 0..n | 2054 | include | 7.1.6 | 0..n | 2055 | leaf | 7.6 | 0..n | 2056 | leaf-list | 7.7 | 0..n | 2057 | list | 7.8 | 0..n | 2058 | notification | 7.14 | 0..n | 2059 | organization | 7.1.7 | 0..1 | 2060 | reference | 7.19.4 | 0..1 | 2061 | revision | 7.1.9 | 0..n | 2062 | rpc | 7.13 | 0..n | 2063 | typedef | 7.3 | 0..n | 2064 | uses | 7.12 | 0..n | 2065 | yang-version | 7.1.2 | 0..1 | 2066 +--------------+---------+-------------+ 2068 7.2.2. The belongs-to Statement 2070 The "belongs-to" statement specifies the module to which the 2071 submodule belongs. The argument is an identifier which is the name 2072 of the module. 2074 A submodule MUST only be included by the module to which it belongs, 2075 or by another submodule which belongs to that module. 2077 The mandatory "prefix" substatement assigns a prefix for the module 2078 to which the submodule belongs. All definitions in the local 2079 submodule and any included submodules can be accessed by using the 2080 prefix. 2082 The belongs-to's Substatements 2084 +--------------+---------+-------------+ 2085 | substatement | section | cardinality | 2086 +--------------+---------+-------------+ 2087 | prefix | 7.1.4 | 1 | 2088 +--------------+---------+-------------+ 2090 7.2.3. Usage Example 2092 submodule acme-types { 2094 belongs-to "acme-system" { 2095 prefix "acme"; 2096 } 2098 import ietf-yang-types { 2099 prefix "yang"; 2100 } 2102 organization "ACME Inc."; 2103 contact 2104 "Joe L. User 2106 ACME, Inc. 2107 42 Anywhere Drive 2108 Nowhere, CA 95134 2109 USA 2111 Phone: +1 800 555 0100 2112 EMail: joe@acme.example.com"; 2114 description 2115 "This submodule defines common ACME types."; 2117 revision "2007-06-09" { 2118 description "Initial revision."; 2119 } 2121 // definitions follows... 2122 } 2124 7.3. The typedef Statement 2126 The "typedef" statement defines a new type which may be used locally 2127 in the module, in modules or submodules which include it, and by 2128 other modules which import from it, according to the rules in 2129 Section 5.5. The new type is called the "derived type", and the type 2130 from which it was derived is called the "base type". All derived 2131 types can be traced back to a YANG built-in type. 2133 The "typedef" statement's argument is an identifier which is the name 2134 of the type to be defined, and MUST be followed by a block of 2135 substatements that holds detailed typedef information. 2137 The name of the type MUST NOT be one of the YANG built-in types. If 2138 the typedef is defined at the top level of a YANG module or 2139 submodule, the name of the type to be defined MUST be unique within 2140 the module. 2142 7.3.1. The typedef's Substatements 2144 +--------------+---------+-------------+ 2145 | substatement | section | cardinality | 2146 +--------------+---------+-------------+ 2147 | default | 7.3.4 | 0..1 | 2148 | description | 7.19.3 | 0..1 | 2149 | reference | 7.19.4 | 0..1 | 2150 | status | 7.19.2 | 0..1 | 2151 | type | 7.3.2 | 1 | 2152 | units | 7.3.3 | 0..1 | 2153 +--------------+---------+-------------+ 2155 7.3.2. The typedef's type Statement 2157 The "type" statement, which MUST be present, defines the base type 2158 from which this type is derived. See Section 7.4 for details. 2160 7.3.3. The units Statement 2162 The "units" statement, which is optional, takes as an argument a 2163 string which contains a textual definition of the units associated 2164 with the type. 2166 7.3.4. The typedef's default Statement 2168 The "default" statement takes as an argument a string which contains 2169 a default value for the new type. 2171 The value of the "default" statement MUST be valid according to the 2172 type specified in the "type" statement. 2174 If the base type has a default value, and the new derived type does 2175 not specify a new default value, the base type's default value is 2176 also the default value of the new derived type. 2178 If the type's default value is not valid according to the new 2179 restrictions specified in a derived type or leaf definition, the 2180 derived type or leaf definition MUST specify a new default value 2181 compatible with the restrictions. 2183 7.3.5. Usage Example 2185 typedef listen-ipv4-address { 2186 type inet:ipv4-address; 2187 default "0.0.0.0"; 2188 } 2190 7.4. The type Statement 2192 The "type" statement takes as an argument a string which is the name 2193 of a YANG built-in type (see Section 9) or a derived type (see 2194 Section 7.3), followed by an optional block of substatements that are 2195 used to put further restrictions on the type. 2197 The restrictions that can be applied depend on the type being 2198 restricted. The restriction statements for all built-in types are 2199 described in the subsections of Section 9. 2201 7.4.1. The type's Substatements 2203 +------------------+---------+-------------+ 2204 | substatement | section | cardinality | 2205 +------------------+---------+-------------+ 2206 | bit | 9.7.4 | 0..n | 2207 | enum | 9.6.4 | 0..n | 2208 | length | 9.4.4 | 0..1 | 2209 | path | 9.9.2 | 0..1 | 2210 | pattern | 9.4.6 | 0..n | 2211 | range | 9.2.4 | 0..1 | 2212 | require-instance | 9.13.2 | 0..1 | 2213 | type | 7.4 | 0..n | 2214 +------------------+---------+-------------+ 2216 7.5. The container Statement 2218 The "container" statement is used to define an interior node in the 2219 schema tree. It takes one argument, which is an identifier, followed 2220 by a block of substatements that holds detailed container 2221 information. 2223 A container node does not have a value, but it has a list of child 2224 nodes in the data tree. The child nodes are defined in the 2225 container's substatements. 2227 7.5.1. Containers with Presence 2229 YANG supports two styles of containers, those which exist only for 2230 organizing the hierarchy of data nodes, and those whose presence in 2231 the configuration has an explicit meaning. 2233 In the first style, the container has no meaning of its own, existing 2234 only to contain child nodes. This is the default style. 2236 For example, the set of scrambling options for SONET interfaces may 2237 be placed inside a "scrambling" container to enhance the organization 2238 of the configuration hierarchy, and to keep these nodes together. 2239 The "scrambling" node itself has no meaning, so removing the node 2240 when it becomes empty relieves the user from the task of performing 2241 this task. 2243 In the second style, the presence of the container itself is 2244 configuration data, representing a single bit of configuration data. 2245 The container acts as both a configuration knob and a means of 2246 organizing related configuration. These containers are explicitly 2247 created and deleted. 2249 YANG calls this style a "presence container" and they are indicated 2250 using the "presence" statement, which takes as its argument a text 2251 string indicating what the presence of the node means. 2253 For example, an "ssh" container may turn on the ability to log into 2254 the device using ssh, but can also contain any ssh-related 2255 configuration knobs, such as connection rates or retry limits. 2257 The "presence" statement (see Section 7.5.5) is used to give 2258 semantics to the existence of the container in the data tree. 2260 7.5.2. The container's Substatements 2262 +--------------+---------+-------------+ 2263 | substatement | section | cardinality | 2264 +--------------+---------+-------------+ 2265 | anyxml | 7.10 | 0..n | 2266 | choice | 7.9 | 0..n | 2267 | config | 7.19.1 | 0..1 | 2268 | container | 7.5 | 0..n | 2269 | description | 7.19.3 | 0..1 | 2270 | grouping | 7.11 | 0..n | 2271 | if-feature | 7.18.2 | 0..n | 2272 | leaf | 7.6 | 0..n | 2273 | leaf-list | 7.7 | 0..n | 2274 | list | 7.8 | 0..n | 2275 | must | 7.5.3 | 0..n | 2276 | presence | 7.5.5 | 0..1 | 2277 | reference | 7.19.4 | 0..1 | 2278 | status | 7.19.2 | 0..1 | 2279 | typedef | 7.3 | 0..n | 2280 | uses | 7.12 | 0..n | 2281 | when | 7.19.5 | 0..1 | 2282 +--------------+---------+-------------+ 2284 7.5.3. The must Statement 2286 The "must" statement, which is optional, takes as an argument a 2287 string which contains an XPath expression. It is used to formally 2288 declare a constraint on valid data. The constraint is enforced 2289 according to the rules in Section 8. 2291 When a data store is validated, all "must" constraints are 2292 conceptually evaluated once for each corresponding instance in the 2293 data tree, and for all leafs with default values in use (see 2294 Section 7.6.1). If an instance does not exist in the data tree, and 2295 it does not have a default value, its "must" statements are not 2296 evaluated. 2298 All such constraints MUST evaluate to true for the data to be valid. 2300 The XPath expression is conceptually evaluated in the following 2301 context, in addition to the definition in Section 6.4.1: 2303 o The context node is the node in the data tree for which the "must" 2304 statement is defined. 2306 o The accessible tree is made up of all nodes in the data tree, and 2307 all leafs with default values in use (see Section 7.6.1). 2309 The accessible tree depends on the context node: 2311 o If the context node represents configuration, the tree is the data 2312 in the NETCONF datastore where the context node exists. The XPath 2313 root node has all top-level configuration data nodes in all 2314 modules as children. 2316 o If the context node represents state data, the tree is all state 2317 data on the device, and the datastore. The XPath root 2318 node has all top-level data nodes in all modules as children. 2320 o If the context node represents notification content, the tree is 2321 the notification XML instance document. The XPath root node has 2322 the element representing the notification being defined as the 2323 only child. 2325 o If the context node represents RPC input parameters, the tree is 2326 the RPC XML instance document. The XPath root node has the 2327 element representing the RPC method being defined as the only 2328 child. 2330 o If the context node represents RPC output parameters, the tree is 2331 the RPC reply instance document. The XPath root node has the 2332 elements representing the RPC output parameters as children. 2334 The result of the XPath expression is converted to a boolean value 2335 using the standard XPath rules. 2337 Note that since all leaf values in the data tree are conceptually 2338 stored in their canonical form (see Section 7.6 and Section 7.7), any 2339 XPath comparisons are done on the canonical value. 2341 Also note that the XPath expression is conceptually evaluated. This 2342 means that an implementation does not have to use an XPath evaluator 2343 on the device. How the evaluation is done in practice is an 2344 implementation decision. 2346 7.5.4. The must's Substatements 2348 +---------------+---------+-------------+ 2349 | substatement | section | cardinality | 2350 +---------------+---------+-------------+ 2351 | description | 7.19.3 | 0..1 | 2352 | error-app-tag | 7.5.4.2 | 0..1 | 2353 | error-message | 7.5.4.1 | 0..1 | 2354 | reference | 7.19.4 | 0..1 | 2355 +---------------+---------+-------------+ 2357 7.5.4.1. The error-message Statement 2359 The "error-message" statement, which is optional, takes a string as 2360 an argument. If the constraint evaluates to false, the string is 2361 passed as in the . 2363 7.5.4.2. The error-app-tag Statement 2365 The "error-app-tag" statement, which is optional, takes a string as 2366 an argument. If the constraint evaluates to false, the string is 2367 passed as in the . 2369 7.5.4.3. Usage Example of must and error-message 2371 container interface { 2372 leaf ifType { 2373 type enumeration { 2374 enum ethernet; 2375 enum atm; 2376 } 2377 } 2378 leaf ifMTU { 2379 type uint32; 2380 } 2381 must "ifType != 'ethernet' or " + 2382 "(ifType = 'ethernet' and ifMTU = 1500)" { 2383 error-message "An ethernet MTU must be 1500"; 2384 } 2385 must "ifType != 'atm' or " + 2386 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2387 error-message "An atm MTU must be 64 .. 17966"; 2388 } 2389 } 2391 7.5.5. The presence Statement 2393 The "presence" statement assigns a meaning to the presence of a 2394 container in the data tree. It takes as an argument a string which 2395 contains a textual description of what the node's presence means. 2397 If a container has the "presence" statement, the container's 2398 existence in the data tree carries some meaning. Otherwise, the 2399 container is used to give some structure to the data, and it carries 2400 no meaning by itself. 2402 See Section 7.5.1 for additional information. 2404 7.5.6. The container's Child Node Statements 2406 Within a container, the "container", "leaf", "list", "leaf-list", 2407 "uses", "choice", and "anyxml" statements can be used to define child 2408 nodes to the container. 2410 7.5.7. XML Mapping Rules 2412 A container node is encoded as an XML element. The element's name is 2413 the container's identifier, and its XML namespace is the module's XML 2414 namespace. 2416 The container's child nodes are encoded as subelements to the 2417 container element. If the container defines RPC input or output 2418 parameters, the subelements are encoded in the same order as they are 2419 defined within the container statement. Otherwise, the subelements 2420 are encoded in any order. 2422 A NETCONF server that replies to a or request MAY 2423 choose not to send a container element if the container node does not 2424 have the "presence" statement and no child nodes exist. Thus, a 2425 client that receives an for a or 2426 request, must be prepared to handle the case that a container node 2427 without a presence statement is not present in the XML. 2429 7.5.8. NETCONF Operations 2431 Containers can be created, deleted, replaced and modified through 2432 , by using the "operation" attribute (See [RFC4741], 2433 section 7.2) in the container's XML element. 2435 If a container does not have a "presence" statement and the last 2436 child node is deleted, the NETCONF server MAY delete the container. 2438 7.5.9. Usage Example 2440 Given the following container definition: 2442 container system { 2443 description "Contains various system parameters"; 2444 container services { 2445 description "Configure externally available services"; 2446 container "ssh" { 2447 presence "Enables SSH"; 2448 description "SSH service specific configuration"; 2449 // more leafs, containers and stuff here... 2450 } 2451 } 2452 } 2454 A corresponding XML instance example: 2456 2457 2458 2459 2460 2462 Since the element is present, ssh is enabled. 2464 To delete a container with an : 2466 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2483 7.6. The leaf Statement 2485 The "leaf" statement is used to define a leaf node in the schema 2486 tree. It takes one argument, which is an identifier, followed by a 2487 block of substatements that holds detailed leaf information. 2489 A leaf node has a value, but no child nodes in the data tree. 2490 Conceptually, the value in the data tree is always in the canonical 2491 form (see Section 9.1). 2493 A leaf node exists in zero or one instances in the data tree, 2494 depending on the value of the "mandatory" statement. 2496 The "leaf" statement is used to define a scalar variable of a 2497 particular built-in or derived type. 2499 7.6.1. The leaf's default value 2501 The default value of a leaf is the value that the server uses if the 2502 leaf does not exist in the data tree. The usage of the default value 2503 depends on the leaf's closest ancestor node in the schema tree which 2504 is not a non-presence container: 2506 o If no such ancestor exists in the schema tree, the default value 2507 MUST be used. 2509 o Otherwise, if this ancestor is a case node, the default value MUST 2510 be used if any node from the case exists in the data tree, or if 2511 the case node is the choice's default case, and no nodes from any 2512 other case exist in the data tree. 2514 o Otherwise, the default value MUST be used if the ancestor node 2515 exists in the data tree. 2517 In these cases, the default value is said to be in use. 2519 When the default value is in use, the server MUST operationally 2520 behave as is if the leaf was present in the data tree with the 2521 default value as its value. 2523 If a leaf has a "default" statement, the leaf's default value is the 2524 value of the "default" statement. Otherwise, if the leaf's type has 2525 a default value, and the leaf is not mandatory, then the leaf's 2526 default value is the type's default value. In all other cases, the 2527 leaf does not have a default value. 2529 7.6.2. The leaf's Substatements 2531 +--------------+---------+-------------+ 2532 | substatement | section | cardinality | 2533 +--------------+---------+-------------+ 2534 | config | 7.19.1 | 0..1 | 2535 | default | 7.6.4 | 0..1 | 2536 | description | 7.19.3 | 0..1 | 2537 | if-feature | 7.18.2 | 0..n | 2538 | mandatory | 7.6.5 | 0..1 | 2539 | must | 7.5.3 | 0..n | 2540 | reference | 7.19.4 | 0..1 | 2541 | status | 7.19.2 | 0..1 | 2542 | type | 7.6.3 | 1 | 2543 | units | 7.3.3 | 0..1 | 2544 | when | 7.19.5 | 0..1 | 2545 +--------------+---------+-------------+ 2547 7.6.3. The leaf's type Statement 2549 The "type" statement, which MUST be present, takes as an argument the 2550 name of an existing built-in or derived type. The optional 2551 substatements specify restrictions on this type. See Section 7.4 for 2552 details. 2554 7.6.4. The leaf's default Statement 2556 The "default" statement, which is optional, takes as an argument a 2557 string which contains a default value for the leaf. 2559 The value of the "default" statement MUST be valid according to the 2560 type specified in the leaf's "type" statement. 2562 The "default" statement MUST NOT be present on nodes where 2563 "mandatory" is true. 2565 7.6.5. The leaf's mandatory Statement 2567 The "mandatory" statement, which is optional, takes as an argument 2568 the string "true" or "false", and puts a constraint on valid data. 2569 If not specified, the default is "false". 2571 If "mandatory" is "true", the behavior of the constraint depends on 2572 the type of the leaf's closest ancestor node in the schema tree which 2573 is not a non-presence container (see Section 7.5.1): 2575 o If no such ancestor exists in the schema tree, the leaf MUST 2576 exist. 2578 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2579 any node from the case exists in the data tree. 2581 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2582 data tree. 2584 This constraint is enforced according to the rules in Section 8. 2586 7.6.6. XML Mapping Rules 2588 A leaf node is encoded as an XML element. The element's name is the 2589 leaf's identifier, and its XML namespace is the module's XML 2590 namespace. 2592 The value of the leaf node is encoded to XML according to the type, 2593 and sent as character data in the element. 2595 A NETCONF server that replies to a or request MAY 2596 choose not to send the leaf element if its value is the default 2597 value. Thus, a client that receives an for a or 2598 request, MUST be prepared to handle the case that a leaf 2599 node with a default value is not present in the XML. In this case, 2600 the value used by the server is known to be the default value. 2602 See Section 7.6.8 for an example. 2604 7.6.7. NETCONF Operations 2606 When a NETCONF server processes an request, the 2607 elements of procedure for the leaf node are: 2609 If the operation is "merge", the node is created if it does not 2610 exist, and its value is set to the value found in the XML RPC 2611 data. 2613 If the operation is "replace", the node is created if it does not 2614 exist, and its value is set to the value found in the XML RPC 2615 data. 2617 If the operation is "create" the node is created if it does not 2618 exist. 2620 If the operation is "delete" the node is deleted if it exists. 2622 7.6.8. Usage Example 2624 Given the following leaf statement, placed in the previously defined 2625 "ssh" container (See Section 7.5.9): 2627 leaf port { 2628 type inet:port-number; 2629 default 22; 2630 description "The port which the SSH server listens to" 2631 } 2633 A corresponding XML instance example: 2635 2022 2637 To create a leaf with an : 2639 2642 2643 2644 2645 2646 2647 2648 2649 2650 2022 2651 2652 2653 2654 2655 2656 2658 7.7. The leaf-list Statement 2660 Where the "leaf" statement is used to define a simple scalar variable 2661 of a particular type, the "leaf-list" statement is used to define an 2662 array of a particular type. The "leaf-list" statement takes one 2663 argument, which is an identifier, followed by a block of 2664 substatements that holds detailed leaf-list information. 2666 The values in a leaf-list MUST be unique. 2668 Conceptually, the values in the data tree are always in the canonical 2669 form (see Section 9.1). 2671 If the type referenced by the leaf-list has a default value, it has 2672 no effect in the leaf-list. 2674 7.7.1. Ordering 2676 YANG supports two styles for ordering the entries within lists and 2677 leaf-lists. In many lists, the order of list entries does not impact 2678 the implementation of the list's configuration, and the device is 2679 free to sort the list entries in any reasonable order. The 2680 "description" string for the list may suggest an order. YANG calls 2681 this style of list "system ordered" and they are indicated with the 2682 statement "ordered-by system". 2684 For example, a list of valid users would typically be sorted 2685 alphabetically, since the order in which the users appeared in the 2686 configuration would not impact the creation of those users' accounts. 2688 In the other style of lists, the order of list entries matters for 2689 the implementation of the list's configuration and the user is 2690 responsible for ordering the entries, while the device maintains that 2691 order. YANG calls this style of list "user ordered" and they are 2692 indicated with the statement "ordered-by user". 2694 For example, the order in which firewall filters entries are applied 2695 to incoming traffic may affect how that traffic is filtered. The 2696 user would need to decide if the filter entry that discards all TCP 2697 traffic should be applied before or after the filter entry that 2698 allows all traffic from trusted interfaces. The choice of order 2699 would be crucial. 2701 YANG provides a rich set of facilities within NETCONF's 2702 operation which allow the order of list entries in user-ordered lists 2703 to be controlled. List entries may be inserted or rearranged, 2704 positioned as the first or last entry in the list, or positioned 2705 before or after another specific entry. 2707 The "ordered-by" statement is covered in Section 7.7.5. 2709 7.7.2. The leaf-list's Substatements 2711 +--------------+---------+-------------+ 2712 | substatement | section | cardinality | 2713 +--------------+---------+-------------+ 2714 | config | 7.19.1 | 0..1 | 2715 | description | 7.19.3 | 0..1 | 2716 | if-feature | 7.18.2 | 0..n | 2717 | max-elements | 7.7.4 | 0..1 | 2718 | min-elements | 7.7.3 | 0..1 | 2719 | must | 7.5.3 | 0..n | 2720 | ordered-by | 7.7.5 | 0..1 | 2721 | reference | 7.19.4 | 0..1 | 2722 | status | 7.19.2 | 0..1 | 2723 | type | 7.4 | 1 | 2724 | units | 7.3.3 | 0..1 | 2725 | when | 7.19.5 | 0..1 | 2726 +--------------+---------+-------------+ 2728 7.7.3. The min-elements Statement 2730 The "min-elements" statement, which is optional, takes as an argument 2731 a non-negative integer which puts a constraint on valid list entries. 2732 A valid leaf-list or list MUST have at least min-elements entries. 2734 If no "min-elements" statement is present, it defaults to zero. 2736 The behavior of the constraint depends on the type of the leaf-list's 2737 or list's closest ancestor node in the schema tree which is not a 2738 non-presence container (see Section 7.5.1): 2740 o If this ancestor is a case node, the constraint is enforced if any 2741 other node from the case exists. 2743 o Otherwise, it is enforced if the ancestor node exists. 2745 The constraint is further enforced according to the rules in 2746 Section 8. 2748 7.7.4. The max-elements Statement 2750 The "max-elements" statement, which is optional, takes as an argument 2751 a positive integer or the string "unbounded", which puts a constraint 2752 on valid list entries. A valid leaf-list or list always has at most 2753 max-elements entries. 2755 If no "max-elements" statement is present, it defaults to 2756 "unbounded". 2758 The "max-elements" constraint is enforced according to the rules in 2759 Section 8. 2761 7.7.5. The ordered-by Statement 2763 The "ordered-by" statement defines whether the order of entries 2764 within a list are determined by the user or the system. The argument 2765 is one of the strings "system" or "user". If not present, order 2766 defaults to "system". 2768 This statement is ignored if the list represents state data, RPC 2769 output parameters, or notification content. 2771 See Section 7.7.1 for additional information. 2773 7.7.5.1. ordered-by system 2775 The entries in the list are sorted according to an unspecified order. 2776 Thus an implementation is free to sort the entries in the most 2777 appropriate order. An implementation SHOULD use the same order for 2778 the same data, regardless of how the data were created. Using a 2779 deterministic order will make comparisons possible using simple tools 2780 like "diff". 2782 This is the default order. 2784 7.7.5.2. ordered-by user 2786 The entries in the list are sorted according to an order defined by 2787 the user. This order is controlled by using special XML attributes 2788 in the request. See Section 7.7.7 for details. 2790 7.7.6. XML Mapping Rules 2792 A leaf-list node is encoded as a series of XML elements. Each 2793 element's name is the leaf-list's identifier, and its XML namespace 2794 is the module's XML namespace. 2796 The value of the leaf-list node is encoded to XML according to the 2797 type, and sent as character data in the element. 2799 See Section 7.7.8 for an example. 2801 7.7.7. NETCONF operations 2803 Leaf-list entries can be created and deleted, but not modified, 2804 through , by using the "operation" attribute in the 2805 leaf-list entry's XML element. 2807 In an "ordered-by user" leaf-list, the attributes "insert" and 2808 "value" in the YANG XML namespace (Section 5.3.1) can be used to 2809 control where in the leaf-list the entry is inserted. These can be 2810 used during "create" operations to insert a new leaf-list entry, or 2811 during "merge" or "replace" operations to insert a new leaf-list 2812 entry or move an existing one. 2814 The "insert" attribute can take the values "first", "last", "before", 2815 and "after". If the value is "before" or "after", the "value" 2816 attribute MUST also be used to specify an existing entry in the leaf- 2817 list. 2819 If no "insert" attribute is present in the "create" operation, it 2820 defaults to "last". 2822 If several entries in an "ordered-by user" leaf-list are modified in 2823 the same request, the entries are modified one at the 2824 time, in the order of the XML elements in the request. 2826 In a , or an with a "replace" operation 2827 which covers the entire leaf-list, the leaf-list order is the same as 2828 the order of the XML elements in the request. 2830 When a NETCONF server processes an request, the 2831 elements of procedure for a leaf-list node are: 2833 If the operation is "merge" or "replace" the leaf-list entry is 2834 created if it does not exist. 2836 If the operation is "create" the leaf-list entry is created if it 2837 does not exist. 2839 If the operation is "delete" the entry is deleted from the leaf- 2840 list if it exists. 2842 7.7.8. Usage Example 2844 leaf-list allow-user { 2845 type string; 2846 description "A list of user name patterns to allow"; 2847 } 2849 A corresponding XML instance example: 2851 alice 2852 bob 2854 To create a new element in the list: 2856 2859 2860 2861 2862 2863 2864 2865 2866 2867 eric 2868 2869 2870 2871 2872 2873 2875 Given the following ordered-by user leaf-list: 2877 leaf-list cipher { 2878 type string; 2879 ordered-by user; 2880 description "A list of ciphers"; 2881 } 2883 The following would be used to insert a new cipher "blowfish-cbc" 2884 after "3des-cbc": 2886 2890 2891 2892 2893 2894 2895 2896 2897 2898 blowfish-cbc 2901 2902 2903 2904 2905 2906 2908 7.8. The list Statement 2910 The "list" statement is used to define interior nodes in the schema 2911 tree. A list node may exist in multiple instances in the data tree. 2912 Each such instance is known as a list entry. The "list" statement 2913 takes one argument which is an identifier, followed by a block of 2914 substatements that holds detailed list information. 2916 A list entry is uniquely identified by the values of the list's keys, 2917 if defined. 2919 A list is similar to a table where each list entry is a row in the 2920 table. 2922 7.8.1. The list's Substatements 2924 +--------------+---------+-------------+ 2925 | substatement | section | cardinality | 2926 +--------------+---------+-------------+ 2927 | anyxml | 7.10 | 0..n | 2928 | choice | 7.9 | 0..n | 2929 | config | 7.19.1 | 0..1 | 2930 | container | 7.5 | 0..n | 2931 | description | 7.19.3 | 0..1 | 2932 | grouping | 7.11 | 0..n | 2933 | if-feature | 7.18.2 | 0..n | 2934 | key | 7.8.2 | 0..1 | 2935 | leaf | 7.6 | 0..n | 2936 | leaf-list | 7.7 | 0..n | 2937 | list | 7.8 | 0..n | 2938 | max-elements | 7.7.4 | 0..1 | 2939 | min-elements | 7.7.3 | 0..1 | 2940 | must | 7.5.3 | 0..n | 2941 | ordered-by | 7.7.5 | 0..1 | 2942 | reference | 7.19.4 | 0..1 | 2943 | status | 7.19.2 | 0..1 | 2944 | typedef | 7.3 | 0..n | 2945 | unique | 7.8.3 | 0..n | 2946 | uses | 7.12 | 0..n | 2947 | when | 7.19.5 | 0..1 | 2948 +--------------+---------+-------------+ 2950 7.8.2. The list's key Statement 2952 The "key" statement, which MUST be present if the list represents 2953 configuration, and MAY be present otherwise, takes as an argument a 2954 string which specifies a space separated list of leaf identifiers of 2955 this list. A leaf identifier MUST NOT appear more than once in the 2956 key. Each such leaf identifier MUST refer to a child leaf of the 2957 list. The leafs can be defined directly in substatements to the 2958 list, or in groupings used in the list. 2960 The combined values of all the leafs specified in the key are used to 2961 uniquely identify a list entry. All key leafs MUST be given values 2962 when a list entry is created. Thus, any default values in the key 2963 leafs or their types are ignored. It also implies that any mandatory 2964 statement in the key leafs are ignored. 2966 A leaf that is part of the key can be of any built-in or derived 2967 type, except it MUST NOT be the built-in type "empty". 2969 All key leafs in a list MUST have the same value for their "config" 2970 as the list itself. 2972 The key string syntax is formally defined by the rule "key-arg" in 2973 Section 12. 2975 7.8.3. The list's unique Statement 2977 The "unique" statement is used to put constraints on valid list 2978 entries. It takes as an argument a string which contains a space 2979 separated list of schema node identifiers, which MUST be given in the 2980 descendant form (see the rule "descendant-schema-nodeid" in 2981 Section 12). Each such schema node identifier MUST refer to a leaf. 2983 If one of the referenced leafs represents configuration data, then 2984 all of the referenced leafs MUST represent configuration data. 2986 The "unique" constraint specifies that the combined values of all the 2987 leaf instances specified in the argument string, including leafs with 2988 default values, MUST be unique within all list entry instances in 2989 which all referenced leafs exist. The constraint is enforced 2990 according to the rules in Section 8. 2992 The unique string syntax is formally defined by the rule "unique-arg" 2993 in Section 12. 2995 7.8.3.1. Usage Example 2997 With the following list: 2999 list server { 3000 key "name"; 3001 unique "ip port"; 3002 leaf name { 3003 type string; 3004 } 3005 leaf ip { 3006 type inet:ip-address; 3007 } 3008 leaf port { 3009 type inet:port-number; 3010 } 3011 } 3013 The following configuration is not valid: 3015 3016 smtp 3017 192.0.2.1 3018 25 3019 3021 3022 http 3023 192.0.2.1 3024 25 3025 3027 The following configuration is valid, since the "http" and "ftp" list 3028 entries do not have a value for all referenced leafs, and are thus 3029 not taken into account when the "unique" constraint is enforced: 3031 3032 smtp 3033 192.0.2.1 3034 25 3035 3037 3038 http 3039 192.0.2.1 3040 3042 3043 ftp 3044 192.0.2.1 3045 3047 7.8.4. The list's Child Node Statements 3049 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3050 "choice", and "anyxml" statements can be used to define child nodes 3051 to the list. 3053 7.8.5. XML Mapping Rules 3055 A list is encoded as a series of XML elements, one for each entry in 3056 the list. Each element's name is the list's identifier, and its XML 3057 namespace is the module's XML namespace. 3059 The list's key nodes are encoded as subelements to the list's 3060 identifier element, in the same order as they are defined within the 3061 key statement. 3063 The rest of the list's child nodes are encoded as subelements to the 3064 list element, after the keys. If the list defines RPC input or 3065 output parameters, the subelements are encoded in the same order as 3066 they are defined within the list statement. Otherwise, the 3067 subelements are encoded in any order. 3069 7.8.6. NETCONF operations 3071 List entries can be created, deleted, replaced and modified through 3072 , by using the "operation" attribute in the list's XML 3073 element. In each case, the values of all keys are used to uniquely 3074 identify a list entry. If all keys are not specified for a list 3075 entry, a "missing-element" error is returned. 3077 In an "ordered-by user" list, the attributes "insert" and "key" in 3078 the YANG XML namespace (Section 5.3.1) can be used to control where 3079 in the list the entry is inserted. These can be used during "create" 3080 operations to insert a new list entry, or during "merge" or "replace" 3081 operations to insert a new list entry or move an existing one. 3083 The "insert" attribute can take the values "first", "last", "before", 3084 and "after". If the value is "before" or "after", the "key" 3085 attribute MUST also be used, to specify an existing element in the 3086 list. The value of the "key" attribute is the key predicates of the 3087 full instance identifier (see Section 9.13) for the list entry. 3089 If no "insert" attribute is present in the "create" operation, it 3090 defaults to "last". 3092 If several entries in an "ordered-by user" list are modified in the 3093 same request, the entries are modified one at the time, 3094 in the order of the XML elements in the request. 3096 In a , or an with a "replace" operation 3097 which covers the entire list, the list entry order is the same as the 3098 order of the XML elements in the request. 3100 7.8.7. Usage Example 3102 Given the following list: 3104 list user { 3105 key "name"; 3106 config true; 3107 description "This is a list of users in the system."; 3109 leaf name { 3110 type string; 3111 } 3112 leaf type { 3113 type string; 3114 } 3115 leaf full-name { 3116 type string; 3117 } 3118 } 3120 A corresponding XML instance example: 3122 3123 fred 3124 admin 3125 Fred Flintstone 3126 3128 To create a new user "barney": 3130 3133 3134 3135 3136 3137 3138 3139 3140 barney 3141 admin 3142 Barney Rubble 3143 3144 3145 3146 3147 3149 To change the type of "fred" to "superuser": 3151 3154 3155 3156 3157 3158 3159 3160 3161 fred 3162 superuser 3163 3164 3165 3166 3167 3169 Given the following ordered-by user list: 3171 list user { 3172 description "This is a list of users in the system."; 3173 ordered-by user; 3174 config true; 3176 key "name"; 3178 leaf name { 3179 type string; 3180 } 3181 leaf type { 3182 type string; 3183 } 3184 leaf full-name { 3185 type string; 3186 } 3187 } 3189 The following would be used to insert a new user "barney" after the 3190 user "fred": 3192 3196 3197 3198 3199 3200 3201 3203 3206 barney 3207 admin 3208 Barney Rubble 3209 3210 3211 3212 3213 3215 The following would be used to move the user "barney" before the user 3216 "fred": 3218 3222 3223 3224 3225 3226 3227 3229 3232 barney 3233 3234 3235 3236 3237 3239 7.9. The choice Statement 3241 The "choice" statement defines a set of alternatives, only one of 3242 which may exist at any one time. The argument is an identifier, 3243 followed by a block of substatements that holds detailed choice 3244 information. The identifier is used to identify the choice node in 3245 the schema tree. A choice node does not exist in the data tree. 3247 A choice consists of a number of branches, defined with the "case" 3248 substatement. Each branch contains a number of child nodes. The 3249 nodes from at most one of the choice's branches exist at the same 3250 time. 3252 See Section 8.3.2 for additional information. 3254 7.9.1. The choice's Substatements 3256 +--------------+---------+-------------+ 3257 | substatement | section | cardinality | 3258 +--------------+---------+-------------+ 3259 | anyxml | 7.10 | 0..n | 3260 | case | 7.9.2 | 0..n | 3261 | config | 7.19.1 | 0..1 | 3262 | container | 7.5 | 0..n | 3263 | default | 7.9.3 | 0..1 | 3264 | description | 7.19.3 | 0..1 | 3265 | if-feature | 7.18.2 | 0..n | 3266 | leaf | 7.6 | 0..n | 3267 | leaf-list | 7.7 | 0..n | 3268 | list | 7.8 | 0..n | 3269 | mandatory | 7.9.4 | 0..1 | 3270 | reference | 7.19.4 | 0..1 | 3271 | status | 7.19.2 | 0..1 | 3272 | when | 7.19.5 | 0..1 | 3273 +--------------+---------+-------------+ 3275 7.9.2. The choice's case Statement 3277 The "case" statement is used to define branches of the choice. It 3278 takes as an argument an identifier, followed by a block of 3279 substatements that holds detailed case information. 3281 The identifier is used to identify the case node in the schema tree. 3282 A case node does not exist in the data tree. 3284 Within a "case" statement, the "anyxml", "choice", "container", 3285 "leaf", "list", "leaf-list", and "uses" statements can be used to 3286 define child nodes to the case node. The identifiers of all these 3287 child nodes MUST be unique within all cases in a choice. For 3288 example, the following is illegal: 3290 choice interface-type { // This example is illegal YANG 3291 case a { 3292 leaf ethernet { ... } 3293 } 3294 case b { 3295 container ethernet { ...} 3296 } 3297 } 3299 As a shorthand, the "case" statement can be omitted if the branch 3300 contains a single "anyxml", "container", "leaf", "list", or 3301 "leaf-list" statement. In this case, the identifier of the case node 3302 is the same as the identifier in the branch statement. The following 3303 example: 3305 choice interface-type { 3306 container ethernet { ... } 3307 } 3309 is equivalent to: 3311 choice interface-type { 3312 case ethernet { 3313 container ethernet { ... } 3314 } 3315 } 3317 The case identifier MUST be unique within a choice. 3319 7.9.2.1. The case's Substatements 3321 +--------------+---------+-------------+ 3322 | substatement | section | cardinality | 3323 +--------------+---------+-------------+ 3324 | anyxml | 7.10 | 0..n | 3325 | choice | 7.9 | 0..n | 3326 | container | 7.5 | 0..n | 3327 | description | 7.19.3 | 0..1 | 3328 | if-feature | 7.18.2 | 0..n | 3329 | leaf | 7.6 | 0..n | 3330 | leaf-list | 7.7 | 0..n | 3331 | list | 7.8 | 0..n | 3332 | reference | 7.19.4 | 0..1 | 3333 | status | 7.19.2 | 0..1 | 3334 | uses | 7.12 | 0..n | 3335 | when | 7.19.5 | 0..1 | 3336 +--------------+---------+-------------+ 3338 7.9.3. The choice's default Statement 3340 The "default" statement indicates if a case should be considered as 3341 the default if no child nodes from any of the choice's cases exists. 3342 The argument is the identifier of the "case" statement. If the 3343 "default" statement is missing, there is no default case. 3345 The "default" statement MUST NOT be present on choices where 3346 "mandatory" is true. 3348 The default case is only important when considering the default 3349 values of nodes under the cases. The default values for nodes under 3350 the default case are used if none of the nodes under any of the cases 3351 are present. 3353 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3354 the default case. 3356 Default values for child nodes under a case are only used if one of 3357 the nodes under that case is present, or if that case is the default 3358 case. If none of the nodes under a case are present and the case is 3359 not the default case, the default values of the cases' child nodes 3360 are ignored. 3362 In this example, the choice defaults to "interval", and the default 3363 value will be used if none of "daily", "time-of-day", or "manual" are 3364 present. If "daily" is present, the default value for "time-of-day" 3365 will be used. 3367 container transfer { 3368 choice how { 3369 default interval; 3370 case interval { 3371 leaf interval { 3372 type uint16; 3373 default 30; 3374 units minutes; 3375 } 3376 } 3377 case daily { 3378 leaf daily { 3379 type empty; 3380 } 3381 leaf time-of-day { 3382 type string; 3383 units 24-hour-clock; 3384 default 1am; 3385 } 3386 } 3387 case manual { 3388 leaf manual { 3389 type empty; 3390 } 3391 } 3392 } 3393 } 3395 7.9.4. The choice's mandatory Statement 3397 The "mandatory" statement, which is optional, takes as an argument 3398 the string "true" or "false", and puts a constraint on valid data. 3399 If "mandatory" is "true", at least one node from exactly one of the 3400 choice's case branches MUST exist. 3402 If not specified, the default is "false". 3404 The behavior of the constraint depends on the type of the choice's 3405 closest ancestor node in the schema tree which is not a non-presence 3406 container (see Section 7.5.1): 3408 o If this ancestor is a case node, the constraint is enforced if any 3409 other node from the case exists. 3411 o Otherwise, it is enforced if the ancestor node exists. 3413 The constraint is further enforced according to the rules in 3414 Section 8. 3416 7.9.5. XML Mapping Rules 3418 The choice and case nodes are not visible in XML. 3420 7.9.6. NETCONF operations 3422 Since only one of the choice's cases can be valid at any time, the 3423 creation of a node from one case implicitly deletes all nodes from 3424 all other cases. If an operation creates a node, the 3425 NETCONF server will delete any existing nodes that are defined in 3426 other cases inside the choice. 3428 7.9.7. Usage Example 3430 Given the following choice: 3432 container protocol { 3433 choice name { 3434 case a { 3435 leaf udp { 3436 type empty; 3437 } 3438 } 3439 case b { 3440 leaf tcp { 3441 type empty; 3442 } 3443 } 3444 } 3445 } 3447 A corresponding XML instance example: 3449 3450 3451 3453 To change the protocol from tcp to udp: 3455 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3472 7.10. The anyxml Statement 3474 The "anyxml" statement defines an interior node in the schema tree. 3475 It takes one argument, which is an identifier, followed by a block of 3476 substatements that holds detailed anyxml information. 3478 The anyxml statement is used to represent an unknown chunk of XML. 3479 No restrictions are placed on the XML. This can be useful in for 3480 example RPC replies. An example is the parameter in the 3481 operation. 3483 An anyxml node cannot be augmented. 3485 Since the use of anyxml limits the manipulation of the content, it is 3486 RECOMMENDED that the anyxml statement not be used to represent 3487 configuration data. 3489 An anyxml node exists in zero or one instances in the data tree. 3491 7.10.1. The anyxml's Substatements 3493 +--------------+---------+-------------+ 3494 | substatement | section | cardinality | 3495 +--------------+---------+-------------+ 3496 | config | 7.19.1 | 0..1 | 3497 | description | 7.19.3 | 0..1 | 3498 | if-feature | 7.18.2 | 0..n | 3499 | mandatory | 7.6.5 | 0..1 | 3500 | must | 7.5.3 | 0..n | 3501 | reference | 7.19.4 | 0..1 | 3502 | status | 7.19.2 | 0..1 | 3503 | when | 7.19.5 | 0..1 | 3504 +--------------+---------+-------------+ 3506 7.10.2. XML Mapping Rules 3508 An anyxml node is encoded as an XML element. The element's name is 3509 the anyxml's identifier, and its XML namespace is the module's XML 3510 namespace. The value of the anyxml node is encoded as XML content of 3511 this element. 3513 Note that any prefixes used in the encoding are local to each 3514 instance encoding. This means that the same XML may be encoded 3515 differently by different implementations. 3517 7.10.3. NETCONF operations 3519 An anyxml node is treated as an opaque chunk of data. This data can 3520 be modified in its entirety only. 3522 Any "operation" attributes present on subelements of an anyxml node 3523 are ignored by the NETCONF server. 3525 When a NETCONF server processes an request, the 3526 elements of procedure for the anyxml node are: 3528 If the operation is "merge", the node is created if it does not 3529 exist, and its value is set to the XML content of the anyxml node 3530 found in the XML RPC data. 3532 If the operation is "replace", the node is created if it does not 3533 exist, and its value is set to the XML content of the anyxml node 3534 found in the XML RPC data. 3536 If the operation is "create" the node is created if it does not 3537 exist, and its value is set to the XML content of the anyxml node 3538 found in the XML RPC data. 3540 If the operation is "delete" the node is deleted if it exists. 3542 7.10.4. Usage Example 3544 Given the following anyxml statement: 3546 anyxml data; 3548 The following are two valid encodings of the same anyxml value: 3550 3551 3552 1 3553 3554 3556 3557 3558 1 3559 3560 3562 7.11. The grouping Statement 3564 The "grouping" statement is used to define a reusable block of nodes, 3565 which may be used locally in the module, in modules which include it, 3566 and by other modules which import from it, according to the rules in 3567 Section 5.5. It takes one argument which is an identifier, followed 3568 by a block of substatements that holds detailed grouping information. 3570 The grouping statement is not a data definition statement and, as 3571 such, does not define any nodes in the schema tree. 3573 A grouping is like a "structure" or a "record" in conventional 3574 programming languages. 3576 Once a grouping is defined, it can be referenced in a "uses" 3577 statement (see Section 7.12). A grouping MUST NOT reference itself, 3578 neither directly nor indirectly through a chain of other groupings. 3580 If the grouping is defined at the top level of a YANG module or 3581 submodule, the grouping's identifier MUST be unique within the 3582 module. 3584 A grouping is more than just a mechanism for textual substitution, 3585 but defines a collection of nodes. Identifiers appearing inside the 3586 grouping are resolved relative to the scope in which the grouping is 3587 defined, not where it is used. Prefix mappings, type names, grouping 3588 names, and extension usage are evaluated in the hierarchy where the 3589 grouping statement appears. For extensions, this means that 3590 extensions are applied to the grouping node, not the uses node. 3592 7.11.1. The grouping's Substatements 3594 +--------------+---------+-------------+ 3595 | substatement | section | cardinality | 3596 +--------------+---------+-------------+ 3597 | anyxml | 7.10 | 0..n | 3598 | choice | 7.9 | 0..n | 3599 | container | 7.5 | 0..n | 3600 | description | 7.19.3 | 0..1 | 3601 | grouping | 7.11 | 0..n | 3602 | leaf | 7.6 | 0..n | 3603 | leaf-list | 7.7 | 0..n | 3604 | list | 7.8 | 0..n | 3605 | reference | 7.19.4 | 0..1 | 3606 | status | 7.19.2 | 0..1 | 3607 | typedef | 7.3 | 0..n | 3608 | uses | 7.12 | 0..n | 3609 +--------------+---------+-------------+ 3611 7.11.2. Usage Example 3613 import ietf-inet-types { 3614 prefix "inet"; 3615 } 3617 grouping address { 3618 description "A reusable address group."; 3619 leaf ip { 3620 type inet:ip-address; 3621 } 3622 leaf port { 3623 type inet:port-number; 3624 } 3625 } 3627 7.12. The uses Statement 3629 The "uses" statement is used to reference a "grouping" definition. 3630 It takes one argument, which is the name of the grouping. 3632 The effect of a "uses" reference to a grouping is that the nodes 3633 defined by the grouping are copied into the current schema tree, and 3634 then updated according to the refinement and augment statements. 3636 The identifiers defined in the grouping are not bound to a namespace 3637 until the contents of the grouping are added to the schema tree via a 3638 "uses" statement that does not appear inside a "grouping" statement, 3639 at which point they are bound to the namespace of the current module. 3641 7.12.1. The uses's Substatements 3643 +--------------+---------+-------------+ 3644 | substatement | section | cardinality | 3645 +--------------+---------+-------------+ 3646 | augment | 7.15 | 0..1 | 3647 | description | 7.19.3 | 0..1 | 3648 | if-feature | 7.18.2 | 0..n | 3649 | refine | 7.12.2 | 0..1 | 3650 | reference | 7.19.4 | 0..1 | 3651 | status | 7.19.2 | 0..1 | 3652 | when | 7.19.5 | 0..1 | 3653 +--------------+---------+-------------+ 3655 7.12.2. The refine Statement 3657 Some of the properties of each node in the grouping can be refined 3658 with the "refine" statement. The argument is a a string which 3659 identifies a node in the grouping. This node is called the refine's 3660 target node. If a node in the grouping is not present as target node 3661 of a refine statement, it is not refined, and thus used exactly as it 3662 was defined in the grouping. 3664 The argument string is a descendant schema node identifier (see 3665 Section 6.5). 3667 The following refinements can be done: 3669 o A leaf or choice node may get a default value, or a new default 3670 value if it already had one. 3672 o Any node may get a specialized "description" string. 3674 o Any node may get a specialized "reference" string. 3676 o Any node may get a different "config" statement. 3678 o A leaf, anyxml, or choice node may get a different "mandatory" 3679 statement. 3681 o A container node may get a "presence" statement. 3683 o A leaf, leaf-list, list, container, or anyxml node may get 3684 additional "must" expressions. 3686 o A leaf-list or list node may get a different "min-elements" or 3687 "max-elements" statement. 3689 7.12.3. XML Mapping Rules 3691 Each node in the grouping is encoded as if it was defined inline, 3692 even if it is imported from another module with another XML 3693 namespace. 3695 7.12.4. Usage Example 3697 To use the "address" grouping defined in Section 7.11.2 in a 3698 definition of an HTTP server in some other module, we can do: 3700 import acme-system { 3701 prefix "acme"; 3702 } 3704 container http-server { 3705 leaf name { 3706 type string; 3707 } 3708 uses acme:address; 3709 } 3711 A corresponding XML instance example: 3713 3714 extern-web 3715 192.0.2.1 3716 80 3717 3719 If port 80 should be the default for the HTTP server, default can be 3720 added: 3722 container http-server { 3723 leaf name { 3724 type string; 3725 } 3726 uses acme:address { 3727 refine port { 3728 default 80; 3729 } 3730 } 3732 } 3734 If we want to define a list of servers, and each server has the ip 3735 and port as keys, we can do: 3737 list server { 3738 key "ip port"; 3739 leaf name { 3740 type string; 3741 } 3742 uses acme:address; 3743 } 3745 The following is an error: 3747 container http-server { 3748 uses acme:address; 3749 leaf ip { // illegal - same identifier "ip" used twice 3750 type string; 3751 } 3752 } 3754 7.13. The rpc Statement 3756 The "rpc" statement is used to define a NETCONF RPC method. It takes 3757 one argument, which is an identifier, followed by a block of 3758 substatements that holds detailed rpc information. This argument is 3759 the name of the RPC, and is used as the element name directly under 3760 the element, as designated by the substitution group 3761 "rpcOperation" in [RFC4741]. 3763 The "rpc" statement defines an rpc node in the schema tree. Under 3764 the rpc node, an input node with the name "input", and an output node 3765 with the name "output" are also defined. The nodes "input" and 3766 "output" are defined in the module's namespace. 3768 7.13.1. The rpc's Substatements 3770 +--------------+---------+-------------+ 3771 | substatement | section | cardinality | 3772 +--------------+---------+-------------+ 3773 | description | 7.19.3 | 0..1 | 3774 | grouping | 7.11 | 0..n | 3775 | if-feature | 7.18.2 | 0..n | 3776 | input | 7.13.2 | 0..1 | 3777 | output | 7.13.3 | 0..1 | 3778 | reference | 7.19.4 | 0..1 | 3779 | status | 7.19.2 | 0..1 | 3780 | typedef | 7.3 | 0..n | 3781 +--------------+---------+-------------+ 3783 7.13.2. The input Statement 3785 The "input" statement, which is optional, is used to define input 3786 parameters to the RPC method. It does not take an argument. The 3787 substatements to "input" define nodes under the RPC's input node. 3789 If a leaf in the input tree has a "mandatory" statement with the 3790 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3791 Otherwise, the server MUST return a "missing-element" error. 3793 If a leaf in the input tree has a default value, the NETCONF server 3794 MUST use this value in the same cases as described in Section 7.6.1. 3795 In these cases, the server MUST operationally behave as if the leaf 3796 was present in the NETCONF RPC invocation with the default value as 3797 its value. 3799 If a "config" statement is present for any node in the input tree, it 3800 is ignored. 3802 If any node has a "when" statement which would evaluate to false, 3803 then this node MUST NOT be present in the input tree. 3805 7.13.2.1. The input's Substatements 3807 +--------------+---------+-------------+ 3808 | substatement | section | cardinality | 3809 +--------------+---------+-------------+ 3810 | anyxml | 7.10 | 0..n | 3811 | choice | 7.9 | 0..n | 3812 | container | 7.5 | 0..n | 3813 | grouping | 7.11 | 0..n | 3814 | leaf | 7.6 | 0..n | 3815 | leaf-list | 7.7 | 0..n | 3816 | list | 7.8 | 0..n | 3817 | typedef | 7.3 | 0..n | 3818 | uses | 7.12 | 0..n | 3819 +--------------+---------+-------------+ 3821 7.13.3. The output Statement 3823 The "output" statement, which is optional, is used to define output 3824 parameters to the RPC method. It does not take an argument. The 3825 substatements to "output" define nodes under the RPC's output node. 3827 If a leaf in the output tree has a "mandatory" statement with the 3828 value "true", the leaf MUST be present in a NETCONF RPC reply. 3830 If a leaf in the output tree has a default value, the NETCONF client 3831 MUST use this value in the same cases as described in Section 7.6.1. 3832 In these cases, the client MUST operationally behave as if the leaf 3833 was present in the NETCONF RPC reply with the default value as its 3834 value. 3836 If a "config" statement is present for any node in the output tree, 3837 it is ignored. 3839 If any node has a "when" statement which would evaluate to false, 3840 then this node MUST NOT be present in the output tree. 3842 7.13.3.1. The output's Substatements 3844 +--------------+---------+-------------+ 3845 | substatement | section | cardinality | 3846 +--------------+---------+-------------+ 3847 | anyxml | 7.10 | 0..n | 3848 | choice | 7.9 | 0..n | 3849 | container | 7.5 | 0..n | 3850 | grouping | 7.11 | 0..n | 3851 | leaf | 7.6 | 0..n | 3852 | leaf-list | 7.7 | 0..n | 3853 | list | 7.8 | 0..n | 3854 | typedef | 7.3 | 0..n | 3855 | uses | 7.12 | 0..n | 3856 +--------------+---------+-------------+ 3858 7.13.4. XML Mapping Rules 3860 An rpc node is encoded as a child XML element to the element 3861 defined in [RFC4741]. The element's name is the rpc's identifier, 3862 and its XML namespace is the module's XML namespace. 3864 Input parameters are encoded as child XML elements to the rpc node's 3865 XML element, in the same order as they are defined within the input 3866 statement. 3868 If the RPC method invocation succeeded, and no output parameters are 3869 returned, the contains a single element defined in 3870 [RFC4741]. If output parameters are returned, they are encoded as 3871 child elements to the element defined in [RFC4741], in 3872 the same order as they are defined within the output statement. 3874 7.13.5. Usage Example 3876 The following example defines an RPC method: 3878 module rock { 3879 namespace "http://example.net/rock"; 3880 prefix "rock"; 3882 rpc rock-the-house { 3883 input { 3884 leaf zip-code { 3885 type string; 3886 } 3887 } 3888 } 3889 } 3891 A corresponding XML instance example of the complete rpc and rpc- 3892 reply: 3894 3896 3897 27606-0100 3898 3899 3901 3903 3904 3906 7.14. The notification Statement 3908 The "notification" statement is used to define a NETCONF 3909 notification. It takes one argument, which is an identifier, 3910 followed by a block of substatements that holds detailed notification 3911 information. The "notification" statement defines a notification 3912 node in the schema tree. 3914 If a container in the notification tree has a "presence" statement, 3915 the container need not be present in a NETCONF notification. 3917 If a leaf in the notification tree has a "mandatory" statement with 3918 the value "true", the leaf MUST be present in a NETCONF notification. 3920 If a leaf in the notification tree has a default value, the NETCONF 3921 client MUST use this value in the same cases as described in 3922 Section 7.6.1. In these cases, the client MUST operationally behave 3923 as if the leaf was present in the NETCONF notification with the 3924 default value as its value. 3926 If a "config" statement is present for any node in the notification 3927 tree, it is ignored. 3929 7.14.1. The notification's Substatements 3931 +--------------+---------+-------------+ 3932 | substatement | section | cardinality | 3933 +--------------+---------+-------------+ 3934 | anyxml | 7.10 | 0..n | 3935 | choice | 7.9 | 0..n | 3936 | container | 7.5 | 0..n | 3937 | description | 7.19.3 | 0..1 | 3938 | grouping | 7.11 | 0..n | 3939 | if-feature | 7.18.2 | 0..n | 3940 | leaf | 7.6 | 0..n | 3941 | leaf-list | 7.7 | 0..n | 3942 | list | 7.8 | 0..n | 3943 | reference | 7.19.4 | 0..1 | 3944 | status | 7.19.2 | 0..1 | 3945 | typedef | 7.3 | 0..n | 3946 | uses | 7.12 | 0..n | 3947 +--------------+---------+-------------+ 3949 7.14.2. XML Mapping Rules 3951 A notification node is encoded as a child XML element to the 3952 element defined in NETCONF Event Notifications 3953 [RFC5277]. The element's name is the notification's identifier, and 3954 its XML namespace is the module's XML namespace. 3956 7.14.3. Usage Example 3958 The following example defines a notification: 3960 module event { 3962 namespace "http://example.com/event"; 3963 prefix "ev"; 3965 notification event { 3966 leaf event-class { 3967 type string; 3968 } 3969 anyxml reporting-entity; 3970 leaf severity { 3971 type string; 3972 } 3973 } 3974 } 3976 A corresponding XML instance example of the complete notification: 3978 3980 2008-07-08T00:01:00Z 3981 3982 fault 3983 3984 Ethernet0 3985 3986 major 3987 3988 3990 7.15. The augment Statement 3992 The "augment" statement allows a module or submodule to add to the 3993 schema tree defined in an external module, or the current module and 3994 its submodules, and to add to the nodes from a grouping in a "uses" 3995 statement. The argument is a string which identifies a node in the 3996 schema tree. This node is called the augment's target node. The 3997 target node MUST be either a container, list, choice, case, input, 3998 output, or notification node. It is augmented with the nodes defined 3999 in the substatements that follow the "augment" statement. 4001 The argument string is a schema node identifier (see Section 6.5). 4002 If the "augment" statement is on the top-level in a module or 4003 submodule, the absolute form (defined by the rule 4004 "absolute-schema-nodeid" in Section 12) of a schema node identifier 4005 MUST be used. If the "augment" statement is a substatement to the 4006 "uses" statement, the descendant form (defined by the rule 4007 "descendant-schema-nodeid" in Section 12) MUST be used. 4009 If the target node is a container, list, case, input, output, or 4010 notification node, the "container", "leaf", "list", "leaf-list", 4011 "uses", and "choice" statements can be used within the "augment" 4012 statement. 4014 If the target node is a choice node, the "case" statement, or a case 4015 shorthand statement (see Section 7.9.2) can be used within the 4016 "augment" statement. 4018 If the target node is in another module, then nodes added by the 4019 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4021 The augment statement MUST NOT add multiple nodes with the same name 4022 from the same module to the target node. 4024 7.15.1. The augment's Substatements 4026 +--------------+---------+-------------+ 4027 | substatement | section | cardinality | 4028 +--------------+---------+-------------+ 4029 | anyxml | 7.10 | 0..n | 4030 | case | 7.9.2 | 0..n | 4031 | choice | 7.9 | 0..n | 4032 | container | 7.5 | 0..n | 4033 | description | 7.19.3 | 0..1 | 4034 | if-feature | 7.18.2 | 0..n | 4035 | leaf | 7.6 | 0..n | 4036 | leaf-list | 7.7 | 0..n | 4037 | list | 7.8 | 0..n | 4038 | reference | 7.19.4 | 0..1 | 4039 | status | 7.19.2 | 0..1 | 4040 | uses | 7.12 | 0..n | 4041 | when | 7.19.5 | 0..1 | 4042 +--------------+---------+-------------+ 4044 7.15.2. XML Mapping Rules 4046 All data nodes defined in the "augment" statement are defined as XML 4047 elements in the XML namespace of the module where the "augment" is 4048 specified. 4050 When a node is augmented, the augmenting child nodes are encoded as 4051 subelements to the augmented node, in any order. 4053 7.15.3. Usage Example 4055 In namespace http://example.com/schema/interfaces, we have: 4057 container interfaces { 4058 list ifEntry { 4059 key "ifIndex"; 4061 leaf ifIndex { 4062 type uint32; 4063 } 4064 leaf ifDescr { 4065 type string; 4066 } 4067 leaf ifType { 4068 type iana:IfType; 4069 } 4070 leaf ifMtu { 4071 type int32; 4072 } 4073 } 4074 } 4076 Then in namespace http://example.com/schema/ds0, we have: 4078 import interface-module { 4079 prefix "if"; 4080 } 4081 augment "/if:interfaces/if:ifEntry" { 4082 when "if:ifType='ds0'"; 4083 leaf ds0ChannelNumber { 4084 type ChannelNumber; 4085 } 4086 } 4088 A corresponding XML instance example: 4090 4093 1 4094 Flintstone Inc Ethernet A562 4095 ethernetCsmacd 4096 1500 4097 4098 4099 2 4100 Flintstone Inc DS0 4101 ds0 4102 1 4103 4104 4106 As another example, suppose we have the choice defined in 4107 Section 7.9.7. The following construct can be used to extend the 4108 protocol definition: 4110 augment /ex:system/ex:protocol/ex:name { 4111 case c { 4112 leaf smtp { 4113 type empty; 4114 } 4115 } 4116 } 4118 A corresponding XML instance example: 4120 4121 4122 4123 4124 4126 or 4128 4129 4130 4131 4132 4134 7.16. The identity Statement 4136 The "identity" statement is used to define a new globally unique, 4137 abstract and untyped identity. Its only purpose is to denote its 4138 name, semantics, and existence. An identity can be defined either 4139 from scratch or derived from a base identity. The identity's 4140 argument is an identifier that is the name of the identity. It is 4141 followed by a block of substatements that holds detailed identity 4142 information. 4144 The built-in datatype "identityref" (see Section 9.10) can be used to 4145 reference identities within a data model. 4147 7.16.1. The identity's Substatements 4149 +--------------+---------+-------------+ 4150 | substatement | section | cardinality | 4151 +--------------+---------+-------------+ 4152 | base | 7.16.2 | 0..1 | 4153 | description | 7.19.3 | 0..1 | 4154 | reference | 7.19.4 | 0..1 | 4155 | status | 7.19.2 | 0..1 | 4156 +--------------+---------+-------------+ 4158 7.16.2. The base Statement 4160 The base statement, which is optional, takes as an argument a string 4161 which is the name of an existing identity, from which the new 4162 identity is derived. If no base statement is present, the identity 4163 is defined from scratch. 4165 If a prefix is present on the base name, it refers to an identity 4166 defined in the module which was imported with that prefix, or the 4167 local module if the prefix matches the local module's prefix. 4168 Otherwise an identity with the matching name MUST be defined in the 4169 current module or an included submodule. 4171 Since submodules cannot include the parent module, any identities in 4172 the module which need to be exposed to submodules MUST be defined in 4173 a submodule. Submodules can then include this submodule to find the 4174 definition of the identity. 4176 An identity MUST NOT reference itself, neither directly nor 4177 indirectly through a chain of other identities. 4179 7.16.3. Usage Example 4181 module crypto-base { 4182 namespace "http://example.com/crypto-base"; 4183 prefix "crypto"; 4185 identity crypto-alg { 4186 description 4187 "Base identity from which all crypto algorithms 4188 are derived."; 4189 } 4190 } 4192 module des { 4193 namespace "http://example.com/des"; 4194 prefix "des"; 4196 import "crypto-base" { 4197 prefix "crypto"; 4198 } 4200 identity des { 4201 base "crypto:crypto-alg"; 4202 description "DES crypto algorithm"; 4203 } 4205 identity des3 { 4206 base "crypto:crypto-alg"; 4207 description "Triple DES crypto algorithm"; 4208 } 4209 } 4211 7.17. The extension Statement 4213 The "extension" statement allows the definition of new statements 4214 within the YANG language. This new statement definition can be 4215 imported and used by other modules. 4217 The statement's argument is an identifier that is the new keyword for 4218 the extension and must be followed by a block of substatements that 4219 holds detailed extension information. The purpose of the extension 4220 statement is to define a keyword, so that it can be imported and used 4221 by other modules. 4223 The extension can be used like a normal YANG statement, with the 4224 statement name followed by an argument if one is defined by the 4225 extension, and an optional block of substatements. The statement's 4226 name is created by combining the the prefix of the module in which 4227 the extension was defined, a colon (":"), and the extension's 4228 keyword, with no interleaving whitespace. The substatements of an 4229 extension are defined by the extension, using some mechanism outside 4230 the scope of this specification. Syntactically, the substatements 4231 MUST be core YANG statements, or also defined using "extension" 4232 statements. Core YANG statements in extensions MUST follow the 4233 syntactical rules in Section 12. 4235 7.17.1. The extension's Substatements 4237 +--------------+---------+-------------+ 4238 | substatement | section | cardinality | 4239 +--------------+---------+-------------+ 4240 | argument | 7.17.2 | 0..1 | 4241 | description | 7.19.3 | 0..1 | 4242 | reference | 7.19.4 | 0..1 | 4243 | status | 7.19.2 | 0..1 | 4244 +--------------+---------+-------------+ 4246 7.17.2. The argument Statement 4248 The "argument" statement, which is optional, takes as an argument a 4249 string which is the name of the argument to the keyword. If no 4250 argument statement is present, the keyword expects no argument when 4251 it is used. 4253 The argument's name is used in the YIN mapping, where it is used as 4254 an XML attribute or element name, depending on the argument's text 4255 statement. 4257 7.17.2.1. The argument's Substatements 4259 +--------------+----------+-------------+ 4260 | substatement | section | cardinality | 4261 +--------------+----------+-------------+ 4262 | yin-element | 7.17.2.2 | 0..1 | 4263 +--------------+----------+-------------+ 4265 7.17.2.2. The yin-element Statement 4267 The "yin-element" statement, which is optional, takes as an argument 4268 the string "true" or "false". This statement indicates if the 4269 argument is mapped to an XML element in YIN or to an XML attribute. 4270 (see Section 11). 4272 If no "yin-element" statement is present, it defaults to "false". 4274 7.17.3. Usage Example 4276 To define an extension: 4278 module my-extensions { 4279 ... 4281 extension c-define { 4282 description 4283 "Takes as argument a name string. 4284 Makes the code generator use the given name in the 4285 #define."; 4286 argument "name"; 4287 } 4288 } 4290 To use the extension: 4292 module my-interfaces { 4293 ... 4294 import my-extensions { 4295 prefix "myext"; 4296 } 4297 ... 4299 container interfaces { 4300 ... 4301 myext:c-define "MY_INTERFACES"; 4302 } 4303 } 4305 7.18. Conformance-related Statements 4307 This section defines statements related to conformance, as described 4308 in Section 5.6. 4310 7.18.1. The feature Statement 4312 The "feature" statement is used to define a mechanism by which 4313 portions of the schema are marked as conditional. A feature name is 4314 defined that can later be referenced using the "if-feature" statement 4315 (see Section 7.18.2). Schema nodes tagged with a feature are ignored 4316 unless the device supports the given feature. This allows portions 4317 of the YANG module to be conditional based on conditions on the 4318 device. The model can represent the abilities of the device within 4319 the model, giving a richer model that allows for differing device 4320 abilities and roles. 4322 The argument to the "feature" statement is the name of the new 4323 feature, and follows the rules for identifiers in Section 6.2. This 4324 name is used by the "if-feature" statement to tie the schema nodes to 4325 the feature. 4327 In this example, a feature called "local-storage" represents the 4328 ability for a device to store syslog messages on local storage of 4329 some sort. This feature is used to make the "local-storage-limit" 4330 leaf conditional on the presence of some sort of local storage. If 4331 the device does not report that it supports this feature, the 4332 "local-storage-limit" node is not supported. 4334 module syslog { 4335 ... 4336 feature local-storage { 4337 description 4338 "This feature means the device supports local 4339 storage (memory, flash or disk) that can be used to 4340 store syslog messages."; 4341 } 4343 container syslog { 4344 leaf local-storage-limit { 4345 if-feature local-storage; 4346 type uint64; 4347 units "kilobyte"; 4348 config false; 4349 description 4350 "The amount of local storage that can be 4351 used to hold syslog messages."; 4352 } 4353 } 4354 } 4356 The "if-feature" statement can be used in many places within the YANG 4357 syntax. Definitions tagged with "if-feature" are ignored when the 4358 device does not support that feature. 4360 A feature MUST NOT reference itself, neither directly nor indirectly 4361 through a chain of other features. 4363 If a feature is dependent on any other features (i.e., the feature 4364 has one or more "if-feature" sub-statements), then all of features it 4365 depends on MUST also be implemented by the device. 4367 7.18.1.1. The feature's Substatements 4369 +--------------+---------+-------------+ 4370 | substatement | section | cardinality | 4371 +--------------+---------+-------------+ 4372 | description | 7.19.3 | 0..1 | 4373 | if-feature | 7.18.2 | 0..n | 4374 | status | 7.19.2 | 0..1 | 4375 | reference | 7.19.4 | 0..1 | 4376 +--------------+---------+-------------+ 4378 7.18.2. The if-feature Statement 4380 The "if-feature" statement makes its parent statement conditional. 4381 The argument is the name of a feature, as defined by a "feature" 4382 statement. The parent statement is implemented by servers that 4383 support this feature. If a prefix is present on the feature name, it 4384 refers to a feature defined in the module which was imported with 4385 that prefix, or the local module if the prefix matches the local 4386 module's prefix. Otherwise a feature with the matching name MUST be 4387 defined in the current module or an included submodule. 4389 Since submodules cannot include the parent module, any features in 4390 the module which need to be exposed to submodules MUST be defined in 4391 a submodule. Submodules can then include this submodule to find the 4392 definition of the feature. 4394 7.18.3. The deviation Statement 4396 The deviation statement defines a hierarchy of the module which the 4397 device does not implement faithfully. The argument is a string that 4398 identifies the node in the schema tree where a deviation from the 4399 module occurs. This node is called the deviation's target node. The 4400 contents of the deviation statement give details about the deviation. 4402 The argument string is an absolute schema node identifier (see 4403 Section 6.5). 4405 Deviations define the way a device or class of devices deviate from 4406 the standard. This means that deviations MUST never be part of a 4407 published standard, since they are the mechanism for learning how 4408 implementations vary from the standards. 4410 Device deviations are strongly discouraged and SHOULD only be used as 4411 a last resort. Telling the application how a device fails to follow 4412 the standard is no substitute for implementing the standard 4413 correctly. 4415 However in some cases a particular device may not have the hardware 4416 or software ability to support parts of a standard module. When this 4417 occurs, the device makes a choice to treat attempts to configure 4418 unsupported parts of the module as either an error that is reported 4419 back to the unsuspecting application, or ignore that incoming 4420 requests. Neither choice is acceptable. 4422 Instead, YANG allows devices to document portions of the base module 4423 which are not supported or supported but with different syntax, by 4424 using the "deviation" statement. 4426 7.18.3.1. The deviation's Substatements 4428 +--------------+----------+-------------+ 4429 | substatement | section | cardinality | 4430 +--------------+----------+-------------+ 4431 | description | 7.19.3 | 0..1 | 4432 | deviate | 7.18.3.2 | 1..n | 4433 | reference | 7.19.4 | 0..1 | 4434 +--------------+----------+-------------+ 4436 7.18.3.2. The deviate Statement 4438 The "deviate" statement defines how the device's implementation of 4439 the target node deviates from its original definition. The argument 4440 is one of the strings "not-supported", "add", "replace", or "delete". 4442 The argument "not-supported" indicates that the target node is not 4443 implemented by this device. 4445 The argument "add" adds properties to the target node. The 4446 properties to add are identified as a substatement to the "deviate" 4447 statement. If the property can only appear once, the property MUST 4448 NOT exist in the target node. 4450 The argument "replace" replaces properties of the target node. The 4451 properties to replace are identified by substatements to the 4452 "deviate" statement. The property to replace MUST exist in the 4453 target node. 4455 The argument "delete" deletes properties from the target node. The 4456 properties to delete are identified by substatement to "delete". The 4457 substatement's keyword MUST match a corresponding keyword in the 4458 target node, and the argument's string MUST be equal to the 4459 corresponding keyword's argument string in the target node. 4461 The deviates's Substatements 4463 +--------------+---------+-------------+ 4464 | substatement | section | cardinality | 4465 +--------------+---------+-------------+ 4466 | config | 7.19.1 | 0..1 | 4467 | default | 7.6.4 | 0..1 | 4468 | mandatory | 7.6.5 | 0..1 | 4469 | max-elements | 7.7.4 | 0..1 | 4470 | min-elements | 7.7.3 | 0..1 | 4471 | must | 7.5.3 | 0..n | 4472 | type | 7.4 | 0..1 | 4473 | unique | 7.8.3 | 0..n | 4474 | units | 7.3.3 | 0..1 | 4475 +--------------+---------+-------------+ 4477 7.18.3.3. Usage Example 4479 In this example, the device is informing client applications that it 4480 does not support the old RFC867-style "daytime" service. 4482 deviation /base:system/base:daytime { 4483 deviate not-supported; 4484 } 4486 The following example sets a device-specific default value to a leaf 4487 that does not have a default value defined: 4489 deviation /base:system/base:user/base:type { 4490 deviate add { 4491 default "admin"; // new users are 'admin' by default 4492 } 4493 } 4495 In this example, the device limits the number of name servers to 3: 4497 deviation /base:system/base:name-server { 4498 deviate replace { 4499 max-elements 3; 4500 } 4501 } 4503 If the original definition is: 4505 container system { 4506 must "daytime or time"; 4507 ... 4508 } 4510 a device might remove this must constraint by doing: 4512 deviation "/base:system" { 4513 deviate delete { 4514 must "daytime or time"; 4515 } 4516 } 4518 7.19. Common Statements 4520 This section defines sub-statements common to several other 4521 statements. 4523 7.19.1. The config Statement 4525 The "config" statement takes as an argument the string "true" or 4526 "false". If "config" is "true", the definition represents 4527 configuration. Data nodes representing configuration will be part of 4528 the reply to a request, and can be sent in a 4529 or request. 4531 If "config" is "false", the definition represents state data. Data 4532 nodes representing state data will be part of the reply to a , 4533 but not to a request. 4535 If "config" is not specified, the default is the same as the parent 4536 schema node's "config" value. If the parent node is a "case" node, 4537 the value is the same as the "case" node's parent "choice" node. 4539 If the top node does not specify a "config" statement, the default is 4540 "true". 4542 If a node has "config" "false", no node underneath it can have 4543 "config" set to "true". 4545 7.19.2. The status Statement 4547 The "status" statement takes as an argument one of the strings 4548 "current", "deprecated", or "obsolete". 4550 o "current" means that the definition is current and valid. 4552 o "deprecated" indicates an obsolete definition, but it permits new/ 4553 continued implementation in order to foster interoperability with 4554 older/existing implementations. 4556 o "obsolete" means the definition is obsolete and SHOULD NOT be 4557 implemented and/or can be removed from implementations. 4559 If no status is specified, the default is "current". 4561 If a definition is "current", it MUST NOT reference a "deprecated" or 4562 "obsolete" definition within the same module. 4564 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4565 definition within the same module. 4567 7.19.3. The description Statement 4569 The "description" statement takes as an argument a string which 4570 contains a high-level textual description of this definition. 4572 7.19.4. The reference Statement 4574 The "reference" statement takes as an argument a string which is used 4575 to specify a textual cross-reference to an external document, either 4576 another module which defines related management information, or a 4577 document which provides additional information relevant to this 4578 definition. 4580 7.19.5. The when Statement 4582 The "when" statement makes its parent data definition statement 4583 conditional. The node defined by the parent data definition 4584 statement is only valid when the condition specified by the "when" 4585 statement is satisfied. The statement's argument is an XPath 4586 expression, which is used to formally specify this condition. If the 4587 XPath expression conceptually evaluates to "true" for a particular 4588 instance, then the node defined by the parent data definition 4589 statement is valid, otherwise it is not. 4591 See Section 8.3.2 for additional information. 4593 The XPath expression is conceptually evaluated in the following 4594 context, in addition to the definition in Section 6.4.1: 4596 o If the "when" statement is a child of an "augment" statement, then 4597 the context node is the augment's target node in the data tree, if 4598 the target node is a data node. Otherwise, the context node is 4599 the closest ancestor node to the target node which is also a data 4600 node. 4602 o If the "when" statement is a child of a "choice" or "case" 4603 statement, then the context node is the closest ancestor node to 4604 the "choice" or "case" node which is also a data node. 4606 o If the "when" statement is a child of any other data definition 4607 statement, the context node is the data definition's node in the 4608 data tree. 4610 o The accessible tree is made up of all nodes in the data tree, and 4611 all leafs with default values in use (see Section 7.6.1). 4613 The accessible tree depends on the context node: 4615 o If the context node represents configuration, the tree is the data 4616 in the NETCONF datastore where the context node exists. The XPath 4617 root node has all top-level configuration data nodes in all 4618 modules as children. 4620 o If the context node represents state data, the tree is all state 4621 data on the device, and the datastore. The XPath root 4622 node has all top-level data nodes in all modules as children. 4624 o If the context node represents notification content, the tree is 4625 the notification XML instance document. The XPath root node has 4626 the element representing the notification being defined as the 4627 only child. 4629 o If the context node represents RPC input parameters, the tree is 4630 the RPC XML instance document. The XPath root node has the 4631 element representing the RPC method being defined as the only 4632 child. 4634 o If the context node represents RPC output parameters, the tree is 4635 the RPC reply instance document. The XPath root node has the 4636 elements representing the RPC output parameters as children. 4638 The result of the XPath expression is converted to a boolean value 4639 using the standard XPath rules. 4641 The XPath expression MUST NOT include any references to the context 4642 node or any descendants of the context node. 4644 Note that the XPath expression is conceptually evaluated. This means 4645 that an implementation does not have to use an XPath evaluator on the 4646 device. The augment can very well be implemented with specially 4647 written code. 4649 8. Constraints 4651 8.1. Constraints on Data 4653 Several YANG statements define constraints on valid data. These 4654 constraints are enforced in different ways, depending on what type of 4655 data the statement defines. 4657 o If the constraint is defined on configuration data, it MUST be 4658 true in a valid configuration data tree. 4660 o If the constraint is defined on state data, it MUST be true in a 4661 reply to the command. 4663 o If the constraint is defined on notification content, it MUST be 4664 true in any notification instance. 4666 o If the constraint is defined on RPC input parameters, it MUST be 4667 true in an invocation of the RPC method. 4669 o If the constraint is defined on RPC output parameters, it MUST be 4670 true in the RPC reply. 4672 8.2. Hierarchy of Constraints 4674 Conditions on parent nodes affect constraints on child nodes as a 4675 natural consequence of the hierarchy of nodes. "must", "mandatory", 4676 "min-elements", and "max-elements" constraints are not enforced if 4677 the parent node has a "when" or "if-feature" property that is not 4678 satisfied on the current device. 4680 In this example, the mandatory constraints on the "longitude" leaf is 4681 not enforced on devices that lack the "has-gps" feature: 4683 container location { 4684 if-feature has-gps; 4685 leaf longitude { 4686 mandatory true; 4687 ... 4688 } 4689 } 4691 8.3. Constraint Enforcement Model 4693 For configuration data, there are three windows when constraints can 4694 be enforced: 4696 o during parsing of RPC payloads 4698 o during processing of NETCONF operations 4700 o during validation 4702 Each of these scenarios are considered in the following sections. 4704 8.3.1. Payload Parsing 4706 When content arrives in RPC payloads, it MUST be well-formed XML, 4707 following the hierarchy and content rules defined by the set of 4708 models the device implements. 4710 o If a leaf data value does not match the type constraints for the 4711 leaf, including those defined in the type's range, length, and 4712 pattern properties, the server MUST reply with an "invalid-value" 4713 error-tag in the rpc-error, and with the error-app-tag and error- 4714 message associated with the constraint, if any exist. 4716 o If all keys of a list entry are not present, the server MUST reply 4717 with a "missing-element" error-tag in the rpc-error. 4719 o If data for more than one case branch of a choice is present, the 4720 server MUST reply with a "bad-element" in the rpc-error. 4722 o If data for a node tagged with "if-feature" is present, and the 4723 feature is not supported by the device, the server MUST reply with 4724 an "unknown-element" error-tag in the rpc-error. 4726 o If data for a node tagged with "when" is present, and the "when" 4727 condition evaluates to "false", the server MUST reply with an 4728 "unknown-element" error-tag in the rpc-error. 4730 o For insert handling, if the value for the attributes "before" and 4731 "after" are not valid for the type of the appropriate key leafs, 4732 the server MUST reply with a "bad-attribute" error-tag in the rpc- 4733 error. 4735 o If the attributes "before" and "after" appears in any element that 4736 is not a list whose "ordered-by" property is "user", the server 4737 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 4739 8.3.2. NETCONF Processing 4741 After the incoming data is parsed, the NETCONF server performs the 4742 operation by applying the data to the configuration 4743 datastore. During this processing the following errors MUST be 4744 detected: 4746 o Delete requests for non-existent data. 4748 o Create requests for existent data. 4750 o Insert requests with "before" or "after" parameters which do not 4751 exist. 4753 During processing: 4755 o If the NETCONF operation creates data nodes under a "choice", any 4756 existing nodes from other "case" branches are deleted by the 4757 server. 4759 o If the NETCONF operation modifies a data node such that any node's 4760 "when" expression becomes false, then that node is deleted by the 4761 server. 4763 8.3.3. Validation 4765 When datastore processing is complete, the final contents MUST obey 4766 all validation constraints. This validation processing is performed 4767 at differing time according to the datastore. If the datastore is 4768 or , these constraints MUST be enforced at the 4769 end of the or operation. If the 4770 datastore is , the constraint enforcement is delayed 4771 until a or operation. 4773 o Any "must" constraints MUST evaluate to "true". 4775 o Any referential integrity constraints defined via the "path" 4776 statement MUST be satisfied. 4778 o Any "unique" constraints on lists MUST be satisfied. 4780 o The "min-elements" and "max-elements" constraints are enforced for 4781 lists and leaf-lists. 4783 9. Built-in Types 4785 YANG has a set of built-in types, similar to those of many 4786 programming languages, but with some differences due to special 4787 requirements from the management information model. 4789 Additional types may be defined, derived from those built-in types or 4790 from other derived types. Derived types may use subtyping to 4791 formally restrict the set of possible values. 4793 The different built-in types and their derived types allow different 4794 kinds of subtyping, namely length and regular expression restrictions 4795 of strings (Section 9.4.4, Section 9.4.6) and range restrictions of 4796 numeric types (Section 9.2.4). 4798 The lexicographic representation of a value of a certain type is used 4799 in the NETCONF PDUs, and when specifying default values and numerical 4800 ranges in YANG modules. 4802 9.1. Canonical representation 4804 For most types, there is a single canonical representation of the 4805 type's values. Some types allow multiple lexicographic 4806 representations of the same value, for example the positive integer 4807 "17" can be represented as "+17" or "17". 4809 When a NETCONF server sends data, it MUST be in the canonical form. 4811 Some types have a lexical representation that depends on the XML 4812 context in which they occur. These types do not have a canonical 4813 form. 4815 9.2. The Integer Built-in Types 4817 The integer built-in types are int8, int16, int32, int64, uint8, 4818 uint16, uint32, and uint64. They represent signed and unsigned 4819 integers of different sizes: 4821 int8 represents integer values between -128 and 127, inclusively. 4823 int16 represents integer values between -32768 and 32767, 4824 inclusively. 4826 int32 represents integer values between -2147483648 and 2147483647, 4827 inclusively. 4829 int64 represents integer values between -9223372036854775808 and 4830 9223372036854775807, inclusively. 4832 uint8 represents integer values between 0 and 255, inclusively. 4834 uint16 represents integer values between 0 and 65535, inclusively. 4836 uint32 represents integer values between 0 and 4294967295, 4837 inclusively. 4839 uint64 represents integer values between 0 and 18446744073709551615, 4840 inclusively. 4842 9.2.1. Lexicographic Representation 4844 An integer value is lexicographically represented as an optional sign 4845 ("+" or "-"), followed by a sequence of decimal digits. If no sign 4846 is specified, "+" is assumed. 4848 For convenience, when specifying a default value for an integer in a 4849 YANG module, an alternative lexicographic representation can be used, 4850 which represents the value in a hexadecimal or octal notation. The 4851 hexadecimal notation consists of an optional sign ("+" or "-"), the 4852 characters "0x" followed a number of hexadecimal digits, where 4853 letters may be upper- or lowercase. The octal notation consists of 4854 an optional sign ("+" or "-"), the character "0" followed a number of 4855 octal digits. 4857 Note that if a default value in a YANG module has a leading zero 4858 ("0"), it is interpreted as an octal number. In the XML instance 4859 documents, an integer is always interpreted as a decimal number, and 4860 leading zeros are allowed. 4862 Examples: 4864 // legal values 4865 +4711 // legal positive value 4866 4711 // legal positive value 4867 -123 // legal negative value 4868 0xf00f // legal positive hexadecimal value 4869 -0xf // legal negative hexadecimal value 4870 052 // legal positive octal value 4872 // illegal values 4873 - 1 // illegal intermediate space 4875 9.2.2. Canonical Form 4877 The canonical form of a positive integer does not include the sign 4878 "+". Leading zeros are prohibited. The value zero is represented as 4879 "0". 4881 9.2.3. Restrictions 4883 All integer types can be restricted with the "range" statement 4884 (Section 9.2.4). 4886 9.2.4. The range Statement 4888 The "range" statement, which is an optional substatement to the 4889 "type" statement, takes as an argument a range expression string. It 4890 is used to restrict integer and decimal built-in types, or types 4891 derived from those. 4893 A range consists of an explicit value, or a lower inclusive bound, 4894 two consecutive dots "..", and an upper inclusive bound. Multiple 4895 values or ranges can be given, separated by "|". If multiple values 4896 or ranges are given they all MUST be disjoint and MUST be in 4897 ascending order. If a range restriction is applied to an already 4898 range restricted type, the new restriction MUST be equal or more 4899 limiting, that is raising the lower bounds, reducing the upper 4900 bounds, removing explicit values or ranges, or splitting ranges into 4901 multiple ranges with intermediate gaps. Each explicit value and 4902 range boundary value given in the range expression MUST match the 4903 type being restricted, or be one of the special values "min" or 4904 "max". "min" and "max" means the minimum and maximum value accepted 4905 for the type being restricted, respectively. 4907 The range expression syntax is formally defined by the rule 4908 "range-arg" in Section 12. 4910 9.2.4.1. The range's Substatements 4912 +---------------+---------+-------------+ 4913 | substatement | section | cardinality | 4914 +---------------+---------+-------------+ 4915 | description | 7.19.3 | 0..1 | 4916 | error-app-tag | 7.5.4.2 | 0..1 | 4917 | error-message | 7.5.4.1 | 0..1 | 4918 | reference | 7.19.4 | 0..1 | 4919 +---------------+---------+-------------+ 4921 9.2.5. Usage Example 4923 typedef my-base-int32-type { 4924 type int32 { 4925 range "1..4 | 10..20"; 4926 } 4927 } 4929 typedef my-type1 { 4930 type my-base-int32-type { 4931 // legal range restriction 4932 range "11..max"; // 11..20 4933 } 4934 } 4936 typedef my-type2 { 4937 type my-base-int32-type { 4938 // illegal range restriction 4939 range "11..100"; 4940 } 4941 } 4943 9.3. The decimal64 Built-in Type 4945 The decimal64 type represents a subset of the real numbers, which can 4946 be represented by decimal numerals. The value space of decimal64 is 4947 the set of numbers that can be obtained by multiplying a 64 bit 4948 signed integer by a negative power of ten, i.e., expressible as 4949 "i x 10^-n" where i is an integer64 and n is an integer between 1 and 4950 18, inclusively. 4952 9.3.1. Lexicographic Representation 4954 A decimal64 value is lexicographically represented as an optional 4955 sign ("+" or "-"), followed by a sequence of decimal digits, 4956 optionally followed by a period ('.') as a decimal indicator and a 4957 sequence of decimal digits. If no sign is specified, "+" is assumed. 4959 9.3.2. Canonical Form 4961 The canonical form of a positive decimal64 does not include the sign 4962 "+". The decimal point is required. Leading and trailing zeros are 4963 prohibited, subject to the rule that there MUST be at least one digit 4964 before and after the decimal point. The value zero is represented as 4965 "0.0". 4967 9.3.3. Restrictions 4969 A decimal64 type can be restricted with the "range" statement 4970 (Section 9.2.4). 4972 9.3.4. The fraction-digits Statement 4974 The "fraction-digits" statement, which is a substatement to the 4975 "type" statement, MUST be present if the type is "decimal64". It 4976 takes as an argument an integer between 1 and 18, inclusively. It 4977 controls the size of the minimum difference between values of a 4978 decimal64 type, by restricting the value space to numbers that are 4979 expressible as "i x 10^-n" where n is the fraction-digits argument. 4981 The following table lists the minimum and maximum value for each 4982 fraction-digit value: 4984 +----------------+-----------------------+----------------------+ 4985 | fraction-digit | min | max | 4986 +----------------+-----------------------+----------------------+ 4987 | 1 | -922337203685477580.8 | 922337203685477580.7 | 4988 | 2 | -92233720368547758.08 | 92233720368547758.07 | 4989 | 3 | -9223372036854775.808 | 9223372036854775.807 | 4990 | 4 | -922337203685477.5808 | 922337203685477.5807 | 4991 | 5 | -92233720368547.75808 | 92233720368547.75807 | 4992 | 6 | -9223372036854.775808 | 9223372036854.775807 | 4993 | 7 | -922337203685.4775808 | 922337203685.4775807 | 4994 | 8 | -92233720368.54775808 | 92233720368.54775807 | 4995 | 9 | -9223372036.854775808 | 9223372036.854775807 | 4996 | 10 | -922337203.6854775808 | 922337203.6854775807 | 4997 | 11 | -92233720.36854775808 | 92233720.36854775807 | 4998 | 12 | -9223372.036854775808 | 9223372.036854775807 | 4999 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5000 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5001 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5002 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5003 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5004 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5005 +----------------+-----------------------+----------------------+ 5007 9.3.5. Usage Example 5009 type decimal64 { 5010 fraction-digits 2; 5011 range "1 .. 3.14 | 10 | 20..max"; 5012 } 5014 9.4. The string Built-in Type 5016 The string built-in type represents human readable strings in YANG. 5017 Legal characters are tab, carriage return, line feed, and the legal 5018 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 5020 // any Unicode character, excluding the surrogate blocks, 5021 // FFFE, and FFFF. 5022 string = *char 5023 char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / 5024 %x10000-10FFFF 5026 9.4.1. Lexicographic Representation 5028 A string value is lexicographically represented as character data in 5029 the XML instance documents. 5031 9.4.2. Canonical Form 5033 The canonical form is the same as the lexicographical representation. 5034 No Unicode normalization is performed of string values. 5036 9.4.3. Restrictions 5038 A string can be restricted with the "length" (Section 9.4.4) and 5039 "pattern" (Section 9.4.6) statements. 5041 9.4.4. The length Statement 5043 The "length" statement, which is an optional substatement to the 5044 "type" statement, takes as an argument a length expression string. 5045 It is used to restrict the built-in type "string", or types derived 5046 from "string". 5048 A "length" statement restricts the number of characters in the 5049 string. 5051 A length range consists of an explicit value, or a lower bound, two 5052 consecutive dots "..", and an upper bound. Multiple values or ranges 5053 can be given, separated by "|". Length restricting values MUST NOT 5054 be negative. If multiple values or ranges are given, they all MUST 5055 be disjoint and MUST be in ascending order. If a length restriction 5056 is applied to an already length restricted type, the new restriction 5057 MUST be equal or more limiting, that is, raising the lower bounds, 5058 reducing the upper bounds, removing explicit length values or ranges, 5059 or splitting ranges into multiple ranges with intermediate gaps. A 5060 length value is a non-negative integer, or one of the special values 5061 "min" or "max". "min" and "max" means the minimum and maximum length 5062 accepted for the type being restricted, respectively. An 5063 implementation is not required to support a length value larger than 5064 18446744073709551615. 5066 The length expression syntax is formally defined by the rule 5067 "length-arg" in Section 12. 5069 9.4.4.1. The length's Substatements 5071 +---------------+---------+-------------+ 5072 | substatement | section | cardinality | 5073 +---------------+---------+-------------+ 5074 | description | 7.19.3 | 0..1 | 5075 | error-app-tag | 7.5.4.2 | 0..1 | 5076 | error-message | 7.5.4.1 | 0..1 | 5077 | reference | 7.19.4 | 0..1 | 5078 +---------------+---------+-------------+ 5080 9.4.5. Usage Example 5082 typedef my-base-str-type { 5083 type string { 5084 length "1..255"; 5085 } 5086 } 5088 type my-base-str-type { 5089 // legal length refinement 5090 length "11 | 42..max"; // 11 | 42..255 5091 } 5093 type my-base-str-type { 5094 // illegal length refinement 5095 length "1..999"; 5096 } 5098 9.4.6. The pattern Statement 5100 The "pattern" statement, which is an optional substatement to the 5101 "type" statement, takes as an argument a regular expression string, 5102 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5103 "string", or types derived from "string", to values that completely 5104 matches the pattern. 5106 If the type has multiple "pattern" statements, the expressions are 5107 ANDed together, i.e., all such expressions have to match. 5109 If a pattern restriction is applied to an already pattern restricted 5110 type, values must match all patterns in the base type, in addition to 5111 the new patterns. 5113 9.4.6.1. The pattern's Substatements 5115 +---------------+---------+-------------+ 5116 | substatement | section | cardinality | 5117 +---------------+---------+-------------+ 5118 | description | 7.19.3 | 0..1 | 5119 | error-app-tag | 7.5.4.2 | 0..1 | 5120 | error-message | 7.5.4.1 | 0..1 | 5121 | reference | 7.19.4 | 0..1 | 5122 +---------------+---------+-------------+ 5124 9.4.7. Usage Example 5126 With the following type: 5128 type string { 5129 length "0..4"; 5130 pattern "[0-9a-fA-F]*"; 5131 } 5133 the following strings match: 5135 AB // legal 5136 9A00 // legal 5138 and the following strings do not match: 5140 00ABAB // illegal, too long 5141 xx00 // illegal, bad characters 5143 9.5. The boolean Built-in Type 5145 The boolean built-in type represents a boolean value. 5147 9.5.1. Lexicographic Representation 5149 The lexicographical representation of a boolean value is the strings 5150 "true" and "false". 5152 9.5.2. Canonical Form 5154 The canonical form is the same as the lexicographical representation. 5156 9.5.3. Restrictions 5158 A boolean cannot be restricted. 5160 9.6. The enumeration Built-in Type 5162 The enumeration built-in type represents values from a set of 5163 assigned names. 5165 9.6.1. Lexicographic Representation 5167 The lexicographical representation of an enumeration value is the 5168 assigned name string. 5170 9.6.2. Canonical Form 5172 The canonical form is the assigned name string. 5174 9.6.3. Restrictions 5176 An enumeration cannot be restricted. 5178 9.6.4. The enum Statement 5180 The "enum" statement, which is a substatement to the "type" 5181 statement, MUST be present if the type is "enumeration". It is 5182 repeatedly used to specify each assigned name of an enumeration type. 5183 It takes as an argument a string which is the assigned name. The 5184 string MUST NOT be empty and MUST NOT have any leading or trailing 5185 whitespace characters. The use of control codes SHOULD be avoided. 5187 The statement is optionally followed by a block of substatements 5188 which holds detailed enum information. 5190 All assigned names in an enumeration MUST be unique. 5192 9.6.4.1. The enum's Substatements 5194 +--------------+---------+-------------+ 5195 | substatement | section | cardinality | 5196 +--------------+---------+-------------+ 5197 | description | 7.19.3 | 0..1 | 5198 | reference | 7.19.4 | 0..1 | 5199 | status | 7.19.2 | 0..1 | 5200 | value | 9.6.4.2 | 0..1 | 5201 +--------------+---------+-------------+ 5203 9.6.4.2. The value Statement 5205 The "value" statement, which is optional, is used to associate an 5206 integer value with the assigned name for the enum. This integer 5207 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5208 unique within the enumeration type. The value is unused by YANG and 5209 the XML encoding, but is carried as a convenience to implementors. 5211 If a value is not specified, then one will be automatically assigned. 5212 If the enum sub-statement is the first one defined, the assigned 5213 value is zero (0), otherwise the assigned value is one greater than 5214 the current highest enum value. 5216 If the current highest value is equal to 2147483647, then an enum 5217 value MUST be specified for enum sub-statements following the one 5218 with the current highest value. 5220 9.6.5. Usage Example 5222 type enumeration { 5223 enum enabled { 5224 value 1; 5225 } 5226 enum disabled { 5227 value 2; 5228 } 5229 } 5231 leaf myenum { 5232 type enumeration { 5233 enum zero; 5234 enum one; 5235 enum seven { 5236 value 7; 5237 } 5238 } 5239 } 5241 The lexicographic representation of the leaf "myenum" with value 5242 "seven" is: 5244 seven 5246 9.7. The bits Built-in Type 5248 The bits built-in type represents a bit set. That is, a bits value 5249 is a set of flags identified by small integer position numbers 5250 starting at 0. Each bit number has an assigned name. 5252 9.7.1. Restrictions 5254 A bits type cannot be restricted. 5256 9.7.2. Lexicographic Representation 5258 The lexicographical representation of the bits type is a space 5259 separated list of the individual bit values that are set. An empty 5260 string thus represents a value where no bits are set. 5262 9.7.3. Canonical Form 5264 In the canonical form, the bit values are separated by a single space 5265 character and they appear ordered by their position (see 5266 Section 9.7.4.2). 5268 9.7.4. The bit Statement 5270 The "bit" statement, which is a substatement to the "type" statement, 5271 MUST be present if the type is "bits". It is repeatedly used to 5272 specify each assigned named bit of a bits type. It takes as an 5273 argument a string which is the assigned name of the bit. It is 5274 followed by a block of substatements which holds detailed bit 5275 information. The assigned name follows the same syntax rules as an 5276 identifier (see Section 6.2). 5278 All assigned names in a bits type MUST be unique. 5280 9.7.4.1. The bit's Substatements 5282 +--------------+---------+-------------+ 5283 | substatement | section | cardinality | 5284 +--------------+---------+-------------+ 5285 | description | 7.19.3 | 0..1 | 5286 | reference | 7.19.4 | 0..1 | 5287 | status | 7.19.2 | 0..1 | 5288 | position | 9.7.4.2 | 0..1 | 5289 +--------------+---------+-------------+ 5291 9.7.4.2. The position Statement 5293 The "position" statement, which is optional, takes as an argument a 5294 non-negative integer value which specifies the bit's position within 5295 a hypothetical bit field. The position value MUST be in the range 0 5296 to 4294967295, and it MUST be unique within the bits type. The value 5297 is unused by YANG and the NETCONF PDUs, but is carried as a 5298 convenience to implementors. 5300 If a bit position is not specified, then one will be automatically 5301 assigned. If the bit sub-statement is the first one defined, the 5302 assigned value is zero (0), otherwise the assigned value is one 5303 greater than the current highest bit position. 5305 If the current highest bit position value is equal to 4294967295, 5306 then a position value MUST be specified for bit sub-statements 5307 following the one with the current highest position value. 5309 9.7.5. Usage Example 5311 Given the following type: 5313 leaf mybits { 5314 type bits { 5315 bit disable-nagle { 5316 position 0; 5317 } 5318 bit auto-sense-speed { 5319 position 1; 5320 } 5321 bit 10-Mb-only { 5322 position 2; 5323 } 5324 } 5325 default "auto-sense-speed"; 5326 } 5328 The lexicographic representation of this leaf with bit values 5329 disable-nagle and 10-Mb-only set would be: 5331 disable-nagle 10-Mb-only 5333 9.8. The binary Built-in Type 5335 The binary built-in type represents any binary data, i.e., a sequence 5336 of octets. 5338 9.8.1. Restrictions 5340 A binary can be restricted with the "length" (Section 9.4.4) 5341 statement. The length of a binary value is the number of octets it 5342 contains. 5344 9.8.2. Lexicographic Representation 5346 Binary values are encoded with the base64 encoding scheme [RFC4648]. 5348 9.8.3. Canonical Form 5350 The canonical form of a binary value follow the rules in [RFC4648]. 5352 9.9. The leafref Built-in Type 5354 The leafref type is used to reference a particular leaf instance in 5355 the data tree. The "path" substatement (Section 9.9.2) selects a set 5356 of leaf instances, and the leafref value space is the set of values 5357 of these leaf instances. 5359 If the leaf with the leafref type represents configuration data, the 5360 leaf it refers to MUST also represent configuration. Such a leaf 5361 puts a constraint on valid data. All leafref nodes MUST reference 5362 existing leaf instances or leafs with default values in use (see 5363 Section 7.6.1) for the data to be valid. This constraint is enforced 5364 according to the rules in Section 8. 5366 There MUST NOT be any circular chains of leafrefs. 5368 If the leaf that the leafref refers to is conditional based on one or 5369 more feature (see Section 7.18.2), then the leaf with the leafref 5370 type MUST also be conditional based on at least the same set of 5371 features. 5373 9.9.1. Restrictions 5375 A leafref cannot be restricted. 5377 9.9.2. The path Statement 5379 The "path" statement, which is a substatement to the "type" 5380 statement, MUST be present if the type is "leafref". It takes as an 5381 argument a string which MUST refer to a leaf or leaf-list node. 5383 The syntax for a path argument is a subset of the XPath abbreviated 5384 syntax. Predicates are used only for constraining the values for the 5385 key nodes for list entries. Each predicate consists of exactly one 5386 equality test per key, and multiple adjacent predicates MAY be 5387 present if a list has multiple keys. The syntax is formally defined 5388 by the rule "path-arg" in Section 12. 5390 The predicates are only used when more than one key reference is 5391 needed to uniquely identify a leaf instance. This occurs if a list 5392 has multiple keys, or a reference to a leaf other than the key in a 5393 list is needed. In these cases, multiple leafrefs are typically 5394 specified, and predicates are used to tie them together. 5396 The "path" expression evaluates to a node set consisting of zero, one 5397 or more nodes. If the leaf with the leafref type represents 5398 configuration data, this node set MUST be non-empty. 5400 The "path" XPath expression is conceptually evaluated in the 5401 following context, in addition to the definition in Section 6.4.1: 5403 o The context node is the node in the data tree for which the "path" 5404 statement is defined. 5406 The accessible tree depends on the context node: 5408 o If the context node represents configuration data, the tree is the 5409 data in the NETCONF datastore where the context node exists. The 5410 XPath root node has all top-level configuration data nodes in all 5411 modules as children. 5413 o Otherwise the tree is all state data on the device, and the 5414 datastore. The XPath root node has all top-level data 5415 nodes in all modules as children. 5417 9.9.3. Lexicographic Representation 5419 A leafref value is encoded the same way as the leaf it references. 5421 9.9.4. Canonical Form 5423 The canonical form of a leafref is the same as the canonical form of 5424 the leaf it references. 5426 9.9.5. Usage Example 5428 With the following list: 5430 list interface { 5431 key "name"; 5432 leaf name { 5433 type string; 5434 } 5435 leaf admin-status { 5436 type admin-status; 5437 } 5438 list address { 5439 key "ip"; 5440 leaf ip { 5441 type yang:ip-address; 5442 } 5443 } 5444 } 5446 The following leafref refers to an existing interface: 5448 leaf mgmt-interface { 5449 type leafref { 5450 path "../interface/name"; 5451 } 5452 } 5454 An example of a corresponding XML snippet: 5456 5457 eth0 5458 5459 5460 lo 5461 5463 eth0 5465 The following leafrefs refer to an existing address of an interface: 5467 container default-address { 5468 leaf ifname { 5469 type leafref { 5470 path "../../interface/name"; 5471 } 5472 } 5473 leaf address { 5474 type leafref { 5475 path "../../interface[name = current()/../ifname]" 5476 + "/address/ip"; 5477 } 5478 } 5479 } 5481 An example of a corresponding XML snippet: 5483 5484 eth0 5485 up 5486
5487 192.0.2.1 5488
5489
5490 192.0.2.2 5491
5492 5493 5494 lo 5495 up 5496
5497 127.0.0.1 5498
5499 5501 5502 eth0 5503
192.0.2.2
5504 5506 The following list uses a leafref for one of its keys. This is 5507 similar to a foreign key in a relational database. 5509 list packet-filter { 5510 key "if-name filter-id"; 5511 leaf if-name { 5512 type leafref { 5513 path "/interfaces/interface/name"; 5514 } 5515 } 5516 leaf filter-id { 5517 type uint32; 5518 } 5519 ... 5520 } 5522 An example of a corresponding XML anippet: 5524 5525 eth0 5526 up 5527
5528 192.0.2.1 5529
5530
5531 192.0.2.2 5532
5533 5535 5536 eth0 5537 1 5538 ... 5539 5540 5541 eth0 5542 2 5543 ... 5544 5546 The following notification defines two leafrefs to refer to an 5547 existing admin-status: 5549 notification link-failure { 5550 leaf if-name { 5551 type leafref { 5552 path "/interfaces/interface/name"; 5553 } 5554 } 5555 leaf admin-status { 5556 type leafref { 5557 path 5558 "/interfaces/interface[name = current()/../if-name]" 5559 + "/admin-status"; 5560 } 5561 } 5562 } 5564 An example of a corresponding XML notification: 5566 5568 2008-04-01T00:01:00Z 5569 5570 eth0 5571 up 5572 5573 5575 9.10. The identityref Built-in Type 5577 The identityref type is used to reference an existing identity (see 5578 Section 7.16). 5580 9.10.1. Restrictions 5582 An identityref cannot be restricted. 5584 9.10.2. The identityref's base Statement 5586 The "base" statement, which is a substatement to the "type" 5587 statement, MUST be present if the type is "identityref". The 5588 argument is the name of an identity, as defined by an "identity" 5589 statement. If a prefix is present on the identity name, it refers to 5590 an identity defined in the module which was imported with that 5591 prefix. Otherwise an identity with the matching name MUST be defined 5592 in the current module or an included submodule. 5594 Valid values for an identityref are any identities derived from the 5595 identityref's base identity. On a particular server, the valid 5596 values are further restricted to the set of identities defined in the 5597 modules supported by the server. 5599 9.10.3. Lexicographic Representation 5601 An identityref is encoded as the referred identity's Qualified Name 5602 as defined in [XML-NAMES]. If the Prefix is not present, the 5603 namespace of the identityref is the default namespace in effect on 5604 the element which contains the identityref value. 5606 When an identityref is given a default value using the "default" 5607 statement, the identity name in the default value MAY have a prefix. 5608 If a prefix is present on the identity name, it refers to an identity 5609 defined in the module which was imported with that prefix. Otherwise 5610 an identity with the matching name MUST be defined in the current 5611 module or an included submodule. 5613 9.10.4. Canonical Form 5615 Since the lexicographic form depends on the XML context in which the 5616 value occurs, this type does not have a canonical form. 5618 9.10.5. Usage Example 5620 With the identity definitions in Section 7.16.3, and the following 5621 module: 5623 module my-crypto { 5625 namespace "http://example.com/my-crypto"; 5626 prefix mc; 5628 import "crypto-base" { 5629 prefix "crypto"; 5630 } 5632 identity aes { 5633 base "crypto:crypto-alg"; 5634 } 5636 leaf crypto { 5637 type identityref { 5638 base "crypto:crypto-alg"; 5639 } 5640 } 5641 } 5643 The leaf "crypto" will be encoded as follows, if the value is the 5644 "des3" identity defined in the "des" module: 5646 des:des3 5648 Any prefixes used in the encoding are local to each instance 5649 encoding. This means that the same identityref may be encoded 5650 differently by different implementations. For example, the following 5651 example encodes the same leaf as above: 5653 x:des3 5655 If the "crypto" leaf's value instead is "aes" defined in the 5656 "my-crypto" module it can be encoded as: 5658 mc:aes 5660 or, using the default namespace: 5662 aes 5664 9.11. The empty Built-in Type 5666 The empty built-in type represents a leaf that does not have any 5667 value, it conveys information by its presence or absence. 5669 An empty type cannot have a default value. 5671 9.11.1. Restrictions 5673 An empty type cannot be restricted. 5675 9.11.2. Lexicographic Representation 5677 Not applicable. 5679 9.11.3. Canonical Form 5681 Not applicable. 5683 9.11.4. Usage Example 5685 The following leaf 5687 leaf enable-qos { 5688 type empty; 5689 } 5691 will be encoded as 5693 5695 if it exists. 5697 9.12. The union Built-in Type 5699 The union built-in type represents a value that corresponds to one of 5700 its member types. 5702 When the type is "union", the "type" statement (Section 7.4) MUST be 5703 present. It is used to repeatedly specify each member type of the 5704 union. It takes as an argument a string which is the name of a 5705 member type. 5707 A member type can be of any built-in or derived type, except it MUST 5708 NOT be one of the built-in types "empty" or "leafref". 5710 When a string representing a union data type is validated, the string 5711 is validated against each member type, in the order they are 5712 specified in the type statement, until a match is found. 5714 Any default values or units properties defined in the member types 5715 are not inherited by the union type. 5717 Example: 5719 type union { 5720 type int32; 5721 type enumeration { 5722 enum "unbounded"; 5723 } 5724 } 5726 9.12.1. Restrictions 5728 A union cannot be restricted. However, each member type can be 5729 restricted, based on the rules defined in Section 9 chapter. 5731 9.12.2. Lexicographic Representation 5733 The lexicographical representation of an union is a value that 5734 corresponds to the representation of any one of the member types. 5736 9.12.3. Canonical Form 5738 The canonical form of a union value is the same as the canonical form 5739 of the member type of the value. 5741 9.13. The instance-identifier Built-in Type 5743 The instance-identifier built-in type is used to uniquely identify a 5744 particular instance node in the data tree. 5746 The syntax for an instance-identifier is a subset of the XPath 5747 abbreviated syntax, formally defined by the rule 5748 "instance-identifier" in Section 12. It is used to uniquely identify 5749 a node in the data tree. Predicates are used only for specifying the 5750 values for the key nodes for list entries, a value of a leaf-list 5751 entry, or a positional index for list without keys. For identifying 5752 list entries with keys, each predicate consists of one equality test 5753 per key, and each key MUST have a corresponding predicate. 5755 If the leaf with the instance-identifier type represents 5756 configuration data, and the "require-instance" property 5757 (Section 9.13.2) is "true", the node it refers to MUST also represent 5758 configuration. Such a leaf puts a constraint on valid data. All 5759 such leaf nodes MUST reference existing nodes or leaf nodes with 5760 their default value in use (see Section 7.6.1) for the data to be 5761 valid. This constraint is enforced according to the rules in 5762 Section 8. 5764 The "instance-identifier" XPath expression is conceptually evaluated 5765 in the following context, in addition to the definition in 5766 Section 6.4.1: 5768 o The context node is the root node in the accessible tree. 5770 The accessible tree depends on the leaf with the instance-identifier 5771 type: 5773 o If this leaf represents configuration data, the tree is the data 5774 in the NETCONF datastore where the leaf exists. The XPath root 5775 node has all top-level configuration data nodes in all modules as 5776 children. 5778 o Otherwise the tree is all state data on the device, and the 5779 datastore. The XPath root node has all top-level data 5780 nodes in all modules as children. 5782 9.13.1. Restrictions 5784 An instance-identifier can be restricted with the "require-instance" 5785 statement (Section 9.13.2). 5787 9.13.2. The require-instance Statement 5789 The "require-instance" statement, which is a substatement to the 5790 "type" statement, MAY be present if the type is 5791 "instance-identifier". It takes as an argument the string "true" or 5792 "false". If this statement is not present, it defaults to "true". 5794 If "require-instance" is "true", it means that the instance being 5795 referred MUST exist for the data to be valid. This constraint is 5796 enforced according to the rules in Section 8. 5798 If "require-instance" is "false", it means that the instance being 5799 referred MAY exist in valid data. 5801 9.13.3. Lexicographic Representation 5803 An instance-identifier value is lexicographically represented as a 5804 string. All node names in an instance-identifier value MUST be 5805 qualified with explicit namespace prefixes and these prefixes MUST be 5806 declared in the XML namespace scope in the instance-identifier's XML 5807 element. 5809 Any prefixes used in the encoding are local to each instance 5810 encoding. This means that the same instance-identifier may be 5811 encoded differently by different implementations. 5813 9.13.4. Canonical Form 5815 Since the lexicographic form depends on the XML context in which the 5816 value occurs, this type does not have a canonical form. 5818 9.13.5. Usage Example 5820 The following are examples of instance identifiers: 5822 /* instance-identifier for a container */ 5823 /ex:system/ex:services/ex:ssh 5825 /* instance-identifier for a leaf */ 5826 /ex:system/ex:services/ex:ssh/ex:port 5828 /* instance-identifier for a list entry */ 5829 /ex:system/ex:user[ex:name='fred'] 5831 /* instance-identifier for a leaf in a list entry */ 5832 /ex:system/ex:user[ex:name='fred']/ex:type 5834 /* instance-identifier for a list entry with two keys */ 5835 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 5837 /* instance-identifier for a leaf-list entry */ 5838 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 5840 /* instance-identifier for a list entry without keys */ 5841 /ex:stats/ex:port[3] 5843 10. Updating a Module 5845 As experience is gained with a module, it may be desirable to revise 5846 that module. However, changes are not allowed if they have any 5847 potential to cause interoperability problems between a client using 5848 an original specification and a server using an updated 5849 specification. 5851 For any published change, a new "revision" statement (Section 7.1.9) 5852 SHOULD be included in front of the existing revision statements. 5853 Furthermore, any necessary changes MUST be applied to any meta data 5854 statements, including the "organization" and "contact" statements 5855 (Section 7.1.7, Section 7.1.8). 5857 Note that definitions contained in a module are available to be 5858 imported by any other module, and are referenced in "import" 5859 statements via the module name. Thus, a module name MUST NOT be 5860 changed. Furthermore, the "namespace" statement MUST NOT be changed, 5861 since all XML elements are encoded in the namespace. 5863 Obsolete definitions MUST NOT be removed from modules since their 5864 identifiers may still be referenced by other modules. 5866 A definition may be revised in any of the following ways: 5868 o An "enumeration" type may have new enums added, provided the old 5869 enums's values do not change. 5871 o A "bits" type may have new bits added, provided the old bit 5872 positions do not change. 5874 o A "range", "length", or "pattern" statement may expand the allowed 5875 value space. 5877 o A "units" statement may be added. 5879 o A "reference" statement may be added or updated. 5881 o A "must" statement may be removed or its constraint relaxed. 5883 o A "mandatory" statement may be removed or changed from "true" to 5884 "false". 5886 o A "min-elements" statement may be removed, or changed to require 5887 less elements. 5889 o A "max-elements" statement may be removed, or changed to allow 5890 more elements. 5892 o A "description" statement may be added or clarified without 5893 changing the semantics of the definition. 5895 o New typedefs, groupings, rpc, notifications, extensions, features, 5896 and identities may be added. 5898 o New data definition statements may be added if they do not add 5899 mandatory nodes (Section 3.1) to existing nodes or at the top- 5900 level in a module or submodule, or if they are conditionally 5901 dependent on a new feature (i.e., have a "if-feature" statement 5902 which refers to a new feature). 5904 o A new "case" statement may be added. 5906 o A node that represented state data may be changed to represent 5907 configuration, provided it is not mandatory (Section 3.1). 5909 o An "if-feature" statement may be removed, provided its node is not 5910 mandatory (Section 3.1). 5912 o A "status" statement may be added, or changed from "current" to 5913 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 5915 o A "type" statement may be replaced with another "type" statement 5916 which does not change the syntax or semantics of the type. For 5917 example, an inline type definition may be replaced with a typedef, 5918 but a int8 type cannot be replaced by a int16, since the syntax 5919 would change. 5921 o Any set of data definition nodes may be replaced with another set 5922 of syntactically and semantically equivalent nodes. For example, 5923 a set of leafs may be replaced by a uses of a grouping with the 5924 same leafs. 5926 o A module may be split into a set of submodules, or submodule may 5927 be removed, provided the definitions in the module do not change 5928 in any other way than allowed here. 5930 o The "prefix" statement may be changed, provided all local uses of 5931 the prefix also are changed. 5933 Otherwise, if the semantics of any previous definition are changed 5934 (i.e., if a non-editorial change is made to any definition other than 5935 those specifically allowed above), then this MUST be achieved by a 5936 new definition with a new identifier. 5938 In statements which have any data definition statements as 5939 substatements, those data definition substatements MUST NOT be 5940 reordered. 5942 11. YIN 5944 A YANG module can be specified in an alternative XML-based syntax 5945 called YIN. This section describes symmetric mapping rules between 5946 the two formats. 5948 The YANG and YIN formats contain equivalent information using 5949 different notations. The purpose of the YIN notation is to allow the 5950 user to translate YANG into YIN, use the rich set of XML based tools 5951 on the YIN format to transform, or filter the model information. 5952 Tools like XSLT or XML validators can be utilized. After this the 5953 model can be transformed back to the YANG format if needed, which 5954 provides a more concise and readable format. 5956 The mapping between YANG and YIN does not modify the information 5957 content of the model. Comments and whitespace are not preserved. 5959 11.1. Formal YIN Definition 5961 There is a one-to-one correspondence between YANG keywords and YIN 5962 elements. The local name of a YIN element is identical to the 5963 corresponding YANG keyword. This means in particular that the 5964 document element (root) of a YIN document is always or 5965 . 5967 YIN elements corresponding to the core YANG keywords belong to the 5968 namespace whose associated URI is 5969 "urn:ietf:params:xml:ns:yang:yin:1". 5971 YIN elements corresponding to extension keywords belong to the 5972 namespace of the YANG module where the extension keyword is declared 5973 via the "extension" statement. 5975 The names of all YIN elements MUST be properly qualified with their 5976 namespaces specified above using the standard mechanisms of 5977 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 5979 The argument of a YANG statement is encoded in YIN either as an XML 5980 attribute or a subelement of the keyword element. Table 1 defines 5981 the encoding for the set of core YANG keywords. For extensions, the 5982 argument encoding is specified within the "extension" statement (see 5983 Section 7.17). The following rules hold for arguments of both core 5984 and extension statements: 5986 o If the argument is encoded as an attribute, this attribute has no 5987 namespace. 5989 o If the argument is encoded as an element, it is placed to the same 5990 namespace as its parent keyword element. 5992 o If the argument is encoded as an element, it MUST be the first 5993 child of the keyword element. 5995 Substatements of a YANG statement are encoded as (additional) 5996 children of the keyword element and their relative order MUST be the 5997 same as the order of substatements in YANG. 5999 Comments in YANG MAY be mapped to XML comments. 6001 Mapping of arguments of the core YANG statements. 6003 +------------------+---------------+-------------+ 6004 | keyword | argument name | yin-element | 6005 +------------------+---------------+-------------+ 6006 | anyxml | name | false | 6007 | argument | name | false | 6008 | augment | target-node | false | 6009 | base | name | false | 6010 | belongs-to | module | false | 6011 | bit | name | false | 6012 | case | name | false | 6013 | choice | name | false | 6014 | config | value | false | 6015 | contact | info | true | 6016 | container | name | false | 6017 | default | value | false | 6018 | description | text | true | 6019 | deviate | value | false | 6020 | deviation | target-node | false | 6021 | enum | name | false | 6022 | error-app-tag | value | false | 6023 | error-message | value | true | 6024 | extension | name | false | 6025 | feature | name | false | 6026 | fraction-digits | value | false | 6027 | grouping | name | false | 6028 | identity | name | false | 6029 | if-feature | name | false | 6030 | import | module | false | 6031 | include | module | false | 6032 | input | | n/a | 6033 | key | value | false | 6034 | leaf | name | false | 6035 | leaf-list | name | false | 6036 | length | value | false | 6037 | list | name | false | 6038 | mandatory | value | false | 6039 | max-elements | value | false | 6040 | min-elements | value | false | 6041 | module | name | false | 6042 | must | condition | false | 6043 | namespace | uri | false | 6044 | notification | name | false | 6045 | ordered-by | value | false | 6046 | organization | info | true | 6047 | output | | n/a | 6048 | path | value | false | 6049 | pattern | value | false | 6050 | position | value | false | 6051 | prefix | value | false | 6052 | presence | value | false | 6053 | range | value | false | 6054 | reference | info | false | 6055 | refine | target-node | false | 6056 | require-instance | value | false | 6057 | revision | date | false | 6058 | revision-date | date | false | 6059 | rpc | name | false | 6060 | status | value | false | 6061 | submodule | name | false | 6062 | type | name | false | 6063 | typedef | name | false | 6064 | unique | tag | false | 6065 | units | name | false | 6066 | uses | name | false | 6067 | value | value | false | 6068 | when | condition | false | 6069 | yang-version | value | false | 6070 | yin-element | value | false | 6071 +------------------+---------------+-------------+ 6073 Table 1 6075 11.1.1. Usage Example 6077 The following YANG snippet: 6079 leaf mtu { 6080 type uint32; 6081 description "The MTU of the interface."; 6082 myext:c-define "MY_MTU"; 6083 } 6085 where the extension "c-define" is defined in Section 7.17.3, is 6086 translated into the following YIN snippet: 6088 6089 6090 6091 The MTU of the interface. 6092 6093 6094 6096 12. YANG ABNF Grammar 6098 In YANG, almost all statements are unordered. The ABNF grammar 6099 [RFC5234] defines the canonical order. To improve module 6100 readability, it is RECOMMENDED that clauses be entered in this order. 6102 Within the ABNF grammar, unordered statements are marked with 6103 comments. 6105 This grammar assumes that the scanner replaces YANG comments with a 6106 single space character. 6108 == begin "yang.abnf" 6110 module-stmt = optsep module-keyword sep identifier-arg-str 6111 optsep 6112 "{" stmtsep 6113 module-header-stmts 6114 linkage-stmts 6115 meta-stmts 6116 revision-stmts 6117 body-stmts 6118 "}" optsep 6120 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 6121 optsep 6122 "{" stmtsep 6123 submodule-header-stmts 6124 linkage-stmts 6125 meta-stmts 6126 revision-stmts 6127 body-stmts 6128 "}" optsep 6130 module-header-stmts = ;; these stmts can appear in any order 6131 [yang-version-stmt stmtsep] 6132 namespace-stmt stmtsep 6133 prefix-stmt stmtsep 6135 submodule-header-stmts = 6136 ;; these stmts can appear in any order 6137 [yang-version-stmt stmtsep] 6138 belongs-to-stmt stmtsep 6140 meta-stmts = ;; these stmts can appear in any order 6141 [organization-stmt stmtsep] 6142 [contact-stmt stmtsep] 6143 [description-stmt stmtsep] 6145 [reference-stmt stmtsep] 6147 linkage-stmts = ;; these stmts can appear in any order 6148 *(import-stmt stmtsep) 6149 *(include-stmt stmtsep) 6151 revision-stmts = *(revision-stmt stmtsep) 6153 body-stmts = *((extension-stmt / 6154 feature-stmt / 6155 identity-stmt / 6156 typedef-stmt / 6157 grouping-stmt / 6158 data-def-stmt / 6159 augment-stmt / 6160 rpc-stmt / 6161 notification-stmt / 6162 deviation-stmt) stmtsep) 6164 data-def-stmt = container-stmt / 6165 leaf-stmt / 6166 leaf-list-stmt / 6167 list-stmt / 6168 choice-stmt / 6169 anyxml-stmt / 6170 uses-stmt 6172 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 6173 optsep stmtend 6175 yang-version-arg-str = < a string which matches the rule 6176 yang-version-arg > 6178 yang-version-arg = "1" 6180 import-stmt = import-keyword sep identifier-arg-str optsep 6181 "{" stmtsep 6182 prefix-stmt stmtsep 6183 [revision-date-stmt stmtsep] 6184 "}" 6186 include-stmt = include-keyword sep identifier-arg-str optsep 6187 (";" / 6188 "{" stmtsep 6189 [revision-date-stmt stmtsep] 6190 "}") 6192 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 6193 uri-str = < a string which matches the rule 6194 URI in RFC 3986 > 6196 prefix-stmt = prefix-keyword sep prefix-arg-str 6197 optsep stmtend 6199 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6200 optsep 6201 "{" stmtsep 6202 prefix-stmt stmtsep 6203 "}" 6205 organization-stmt = organization-keyword sep string 6206 optsep stmtend 6208 contact-stmt = contact-keyword sep string optsep stmtend 6210 description-stmt = description-keyword sep string optsep 6211 stmtend 6213 reference-stmt = reference-keyword sep string optsep stmtend 6215 units-stmt = units-keyword sep string optsep stmtend 6217 revision-stmt = revision-keyword sep revision-date optsep 6218 (";" / 6219 "{" stmtsep 6220 [description-stmt stmtsep] 6221 [reference-stmt stmtsep] 6222 "}") 6224 revision-date = date-arg-str 6226 revision-date-stmt = revision-date-keyword sep revision-date stmtend 6228 extension-stmt = extension-keyword sep identifier-arg-str optsep 6229 (";" / 6230 "{" stmtsep 6231 ;; these stmts can appear in any order 6232 [argument-stmt stmtsep] 6233 [status-stmt stmtsep] 6234 [description-stmt stmtsep] 6235 [reference-stmt stmtsep] 6236 "}") 6238 argument-stmt = argument-keyword sep identifier-arg-str optsep 6239 (";" / 6240 "{" stmtsep 6242 [yin-element-stmt stmtsep] 6243 "}") 6245 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 6246 stmtend 6248 yin-element-arg-str = < a string which matches the rule 6249 yin-element-arg > 6251 yin-element-arg = true-keyword / false-keyword 6253 identity-stmt = identity-keyword sep identifier-arg-str optsep 6254 (";" / 6255 "{" stmtsep 6256 ;; these stmts can appear in any order 6257 [base-stmt stmtsep] 6258 [status-stmt stmtsep] 6259 [description-stmt stmtsep] 6260 [reference-stmt stmtsep] 6261 "}") 6263 base-stmt = base-keyword sep identifier-ref-arg-str 6264 optsep stmtend 6266 feature-stmt = feature-keyword sep identifier-arg-str optsep 6267 (";" / 6268 "{" stmtsep 6269 ;; these stmts can appear in any order 6270 *(if-feature-stmt stmtsep) 6271 [status-stmt stmtsep] 6272 [description-stmt stmtsep] 6273 [reference-stmt stmtsep] 6274 "}") 6276 if-feature-stmt = if-feature-keyword sep identifier-ref-arg-str 6277 optsep stmtend 6279 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 6280 "{" stmtsep 6281 ;; these stmts can appear in any order 6282 type-stmt stmtsep 6283 [units-stmt stmtsep] 6284 [default-stmt stmtsep] 6285 [status-stmt stmtsep] 6286 [description-stmt stmtsep] 6287 [reference-stmt stmtsep] 6288 "}" 6290 type-stmt = type-keyword sep identifier-ref-arg-str optsep 6291 (";" / 6292 "{" stmtsep 6293 type-body-stmts 6294 "}") 6296 type-body-stmts = numerical-restrictions / 6297 decimal64-specification / 6298 string-restrictions / 6299 enum-specification / 6300 leafref-specification / 6301 identityref-specification / 6302 instance-identifier-specification / 6303 bits-specification / 6304 union-specification 6306 numerical-restrictions = range-stmt stmtsep 6308 range-stmt = range-keyword sep range-arg-str optsep 6309 (";" / 6310 "{" stmtsep 6311 ;; these stmts can appear in any order 6312 [error-message-stmt stmtsep] 6313 [error-app-tag-stmt stmtsep] 6314 [description-stmt stmtsep] 6315 [reference-stmt stmtsep] 6316 "}") 6318 decimal64-specification = fraction-digits-stmt 6320 fraction-digits-stmt = fraction-digits-keyword sep 6321 fraction-digits-arg-str stmtend 6323 fraction-digits-arg-str = < a string which matches the rule 6324 fraction-digits-arg > 6326 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 6327 "5" / "6" / "7" / "8"]) 6328 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 6330 string-restrictions = ;; these stmts can appear in any order 6331 [length-stmt stmtsep] 6332 *(pattern-stmt stmtsep) 6334 length-stmt = length-keyword sep length-arg-str optsep 6335 (";" / 6336 "{" stmtsep 6337 ;; these stmts can appear in any order 6339 [error-message-stmt stmtsep] 6340 [error-app-tag-stmt stmtsep] 6341 [description-stmt stmtsep] 6342 [reference-stmt stmtsep] 6343 "}") 6345 pattern-stmt = pattern-keyword sep string optsep 6346 (";" / 6347 "{" stmtsep 6348 ;; these stmts can appear in any order 6349 [error-message-stmt stmtsep] 6350 [error-app-tag-stmt stmtsep] 6351 [description-stmt stmtsep] 6352 [reference-stmt stmtsep] 6353 "}") 6355 default-stmt = default-keyword sep string stmtend 6357 enum-specification = 1*(enum-stmt stmtsep) 6359 enum-stmt = enum-keyword sep string optsep 6360 (";" / 6361 "{" stmtsep 6362 ;; these stmts can appear in any order 6363 [value-stmt stmtsep] 6364 [status-stmt stmtsep] 6365 [description-stmt stmtsep] 6366 [reference-stmt stmtsep] 6367 "}") 6369 leafref-specification = 6370 ;; these stmts can appear in any order 6371 path-stmt stmtsep 6372 [require-instance-stmt stmtsep] 6374 path-stmt = path-keyword sep path-arg-str stmtend 6376 require-instance-stmt = require-instance-keyword sep 6377 require-instance-arg-str stmtend 6379 require-instance-arg-str = < a string which matches the rule 6380 require-instance-arg > 6382 require-instance-arg = true-keyword / false-keyword 6384 instance-identifier-specification = 6385 [require-instance-stmt stmtsep] 6387 identityref-specification = 6388 base-stmt stmtsep 6390 union-specification = 1*(type-stmt stmtsep) 6392 bits-specification = 1*(bit-stmt stmtsep) 6394 bit-stmt = bit-keyword sep identifier-arg-str optsep 6395 (";" / 6396 "{" stmtsep 6397 ;; these stmts can appear in any order 6398 [position-stmt stmtsep] 6399 [status-stmt stmtsep] 6400 [description-stmt stmtsep] 6401 [reference-stmt stmtsep] 6402 "}" 6403 "}") 6405 position-stmt = position-keyword sep 6406 position-value-arg-str stmtend 6408 position-value-arg-str = < a string which matches the rule 6409 position-value-arg > 6411 position-value-arg = non-negative-integer-value 6413 status-stmt = status-keyword sep status-arg-str stmtend 6415 status-arg-str = < a string which matches the rule 6416 status-arg > 6418 status-arg = current-keyword / 6419 obsolete-keyword / 6420 deprecated-keyword 6422 config-stmt = config-keyword sep 6423 config-arg-str stmtend 6425 config-arg-str = < a string which matches the rule 6426 config-arg > 6428 config-arg = true-keyword / false-keyword 6430 mandatory-stmt = mandatory-keyword sep 6431 mandatory-arg-str stmtend 6433 mandatory-arg-str = < a string which matches the rule 6434 mandatory-arg > 6436 mandatory-arg = true-keyword / false-keyword 6438 presence-stmt = presence-keyword sep string stmtend 6440 ordered-by-stmt = ordered-by-keyword sep 6441 ordered-by-arg-str stmtend 6443 ordered-by-arg-str = < a string which matches the rule 6444 ordered-by-arg > 6446 ordered-by-arg = user-keyword / system-keyword 6448 must-stmt = must-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 error-message-stmt = error-message-keyword sep string stmtend 6460 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 6462 min-elements-stmt = min-elements-keyword sep 6463 min-value-arg-str stmtend 6465 min-value-arg-str = < a string which matches the rule 6466 min-value-arg > 6468 min-value-arg = non-negative-integer-value 6470 max-elements-stmt = max-elements-keyword sep 6471 max-value-arg-str stmtend 6473 max-value-arg-str = < a string which matches the rule 6474 max-value-arg > 6476 max-value-arg = unbounded-keyword / 6477 positive-integer-value 6479 value-stmt = value-keyword sep integer-value stmtend 6481 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 6482 (";" / 6483 "{" stmtsep 6484 ;; these stmts can appear in any order 6485 [status-stmt stmtsep] 6486 [description-stmt stmtsep] 6487 [reference-stmt stmtsep] 6488 *((typedef-stmt / 6489 grouping-stmt) stmtsep) 6490 *(data-def-stmt stmtsep) 6491 "}") 6493 container-stmt = container-keyword sep identifier-arg-str optsep 6494 (";" / 6495 "{" stmtsep 6496 ;; these stmts can appear in any order 6497 [when-stmt stmtsep] 6498 *(if-feature-stmt stmtsep) 6499 *(must-stmt stmtsep) 6500 [presence-stmt stmtsep] 6501 [config-stmt stmtsep] 6502 [status-stmt stmtsep] 6503 [description-stmt stmtsep] 6504 [reference-stmt stmtsep] 6505 *((typedef-stmt / 6506 grouping-stmt) stmtsep) 6507 *(data-def-stmt stmtsep) 6508 "}") 6510 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 6511 "{" stmtsep 6512 ;; these stmts can appear in any order 6513 [when-stmt stmtsep] 6514 *(if-feature-stmt stmtsep) 6515 type-stmt stmtsep 6516 [units-stmt stmtsep] 6517 *(must-stmt stmtsep) 6518 [default-stmt stmtsep] 6519 [config-stmt stmtsep] 6520 [mandatory-stmt stmtsep] 6521 [status-stmt stmtsep] 6522 [description-stmt stmtsep] 6523 [reference-stmt stmtsep] 6524 "}" 6526 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 6527 "{" stmtsep 6528 ;; these stmts can appear in any order 6529 [when-stmt stmtsep] 6530 *(if-feature-stmt stmtsep) 6531 type-stmt stmtsep 6533 [units-stmt stmtsep] 6534 *(must-stmt stmtsep) 6535 [config-stmt stmtsep] 6536 [min-elements-stmt stmtsep] 6537 [max-elements-stmt stmtsep] 6538 [ordered-by-stmt stmtsep] 6539 [status-stmt stmtsep] 6540 [description-stmt stmtsep] 6541 [reference-stmt stmtsep] 6542 "}" 6544 list-stmt = list-keyword sep identifier-arg-str optsep 6545 "{" stmtsep 6546 ;; these stmts can appear in any order 6547 [when-stmt stmtsep] 6548 *(if-feature-stmt stmtsep) 6549 *(must-stmt stmtsep) 6550 [key-stmt stmtsep] 6551 *(unique-stmt stmtsep) 6552 [config-stmt stmtsep] 6553 [min-elements-stmt stmtsep] 6554 [max-elements-stmt stmtsep] 6555 [ordered-by-stmt stmtsep] 6556 [status-stmt stmtsep] 6557 [description-stmt stmtsep] 6558 [reference-stmt stmtsep] 6559 *((typedef-stmt / 6560 grouping-stmt) stmtsep) 6561 1*(data-def-stmt stmtsep) 6562 "}" 6564 key-stmt = key-keyword sep key-arg-str stmtend 6566 key-arg-str = < a string which matches the rule 6567 key-arg > 6569 key-arg = node-identifier *(sep node-identifier) 6571 unique-stmt = unique-keyword sep unique-arg-str stmtend 6573 unique-arg-str = < a string which matches the rule 6574 unique-arg > 6576 unique-arg = descendant-schema-nodeid 6577 *(sep descendant-schema-nodeid) 6579 choice-stmt = choice-keyword sep identifier-arg-str optsep 6580 (";" / 6581 "{" stmtsep 6582 ;; these stmts can appear in any order 6583 [when-stmt stmtsep] 6584 *(if-feature-stmt stmtsep) 6585 [default-stmt stmtsep] 6586 [config-stmt stmtsep] 6587 [mandatory-stmt stmtsep] 6588 [status-stmt stmtsep] 6589 [description-stmt stmtsep] 6590 [reference-stmt stmtsep] 6591 *((short-case-stmt / case-stmt) stmtsep) 6592 "}") 6594 short-case-stmt = container-stmt / 6595 leaf-stmt / 6596 leaf-list-stmt / 6597 list-stmt / 6598 anyxml-stmt 6600 case-stmt = case-keyword sep identifier-arg-str optsep 6601 (";" / 6602 "{" stmtsep 6603 ;; these stmts can appear in any order 6604 [when-stmt stmtsep] 6605 *(if-feature-stmt stmtsep) 6606 [status-stmt stmtsep] 6607 [description-stmt stmtsep] 6608 [reference-stmt stmtsep] 6609 *(data-def-stmt stmtsep) 6610 "}") 6612 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 6613 (";" / 6614 "{" stmtsep 6615 ;; these stmts can appear in any order 6616 [when-stmt stmtsep] 6617 *(if-feature-stmt stmtsep) 6618 *(must-stmt stmtsep) 6619 [config-stmt stmtsep] 6620 [mandatory-stmt stmtsep] 6621 [status-stmt stmtsep] 6622 [description-stmt stmtsep] 6623 [reference-stmt stmtsep] 6624 "}") 6626 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 6627 (";" / 6628 "{" stmtsep 6629 ;; these stmts can appear in any order 6630 [when-stmt stmtsep] 6631 *(if-feature-stmt stmtsep) 6632 [status-stmt stmtsep] 6633 [description-stmt stmtsep] 6634 [reference-stmt stmtsep] 6635 *(refine-stmt stmtsep) 6636 *(uses-augment-stmt stmtsep) 6637 "}") 6639 refine-stmt = refine-keyword sep refine-arg-str optsep 6640 (";" / 6641 "{" stmtsep 6642 (refine-container-stmts / 6643 refine-leaf-stmts / 6644 refine-leaf-list-stmts / 6645 refine-list-stmts / 6646 refine-choice-stmts / 6647 refine-case-stmts / 6648 refine-anyxml-stmts) 6649 "}") 6651 refine-arg-str = < a string which matches the rule 6652 refine-arg > 6654 refine-arg = descendant-schema-nodeid 6656 refine-container-stmts = 6657 ;; these stmts can appear in any order 6658 *(must-stmt stmtsep) 6659 [presence-stmt stmtsep] 6660 [config-stmt stmtsep] 6661 [description-stmt stmtsep] 6662 [reference-stmt stmtsep] 6664 refine-leaf-stmts = ;; these stmts can appear in any order 6665 *(must-stmt stmtsep) 6666 [default-stmt stmtsep] 6667 [config-stmt stmtsep] 6668 [mandatory-stmt stmtsep] 6669 [description-stmt stmtsep] 6670 [reference-stmt stmtsep] 6672 refine-leaf-list-stmts = 6673 ;; these stmts can appear in any order 6674 *(must-stmt stmtsep) 6675 [config-stmt stmtsep] 6676 [min-elements-stmt stmtsep] 6678 [max-elements-stmt stmtsep] 6679 [description-stmt stmtsep] 6680 [reference-stmt stmtsep] 6682 refine-list-stmts = ;; these stmts can appear in any order 6683 *(must-stmt stmtsep) 6684 [config-stmt stmtsep] 6685 [min-elements-stmt stmtsep] 6686 [max-elements-stmt stmtsep] 6687 [description-stmt stmtsep] 6688 [reference-stmt stmtsep] 6690 refine-choice-stmts = ;; these stmts can appear in any order 6691 [default-stmt stmtsep] 6692 [config-stmt stmtsep] 6693 [mandatory-stmt stmtsep] 6694 [description-stmt stmtsep] 6695 [reference-stmt stmtsep] 6697 refine-case-stmts = ;; these stmts can appear in any order 6698 [description-stmt stmtsep] 6699 [reference-stmt stmtsep] 6701 refine-anyxml-stmts = ;; these stmts can appear in any order 6702 *(must-stmt stmtsep) 6703 [config-stmt stmtsep] 6704 [mandatory-stmt stmtsep] 6705 [description-stmt stmtsep] 6706 [reference-stmt stmtsep] 6708 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 6709 "{" stmtsep 6710 ;; these stmts can appear in any order 6711 [when-stmt stmtsep] 6712 *(if-feature-stmt stmtsep) 6713 [status-stmt stmtsep] 6714 [description-stmt stmtsep] 6715 [reference-stmt stmtsep] 6716 1*((data-def-stmt stmtsep) / 6717 (case-stmt stmtsep)) 6718 "}" 6720 uses-augment-arg-str = < a string which matches the rule 6721 uses-augment-arg > 6723 uses-augment-arg = descendant-schema-nodeid 6724 augment-stmt = augment-keyword sep augment-arg-str optsep 6725 "{" stmtsep 6726 ;; these stmts can appear in any order 6727 [when-stmt stmtsep] 6728 *(if-feature-stmt stmtsep) 6729 [status-stmt stmtsep] 6730 [description-stmt stmtsep] 6731 [reference-stmt stmtsep] 6732 1*((data-def-stmt stmtsep) / 6733 (case-stmt stmtsep)) 6734 "}" 6736 augment-arg-str = < a string which matches the rule 6737 augment-arg > 6739 augment-arg = absolute-schema-nodeid 6741 unknown-statement = prefix ":" identifier [sep string] optsep 6742 (";" / "{" *unknown-statement2 "}") 6744 unknown-statement2 = [prefix ":"] identifier [sep string] optsep 6745 (";" / "{" *unknown-statement2 "}") 6747 when-stmt = when-keyword sep string stmtend 6749 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 6750 (";" / 6751 "{" stmtsep 6752 ;; these stmts can appear in any order 6753 *(if-feature-stmt stmtsep) 6754 [status-stmt stmtsep] 6755 [description-stmt stmtsep] 6756 [reference-stmt stmtsep] 6757 *((typedef-stmt / 6758 grouping-stmt) stmtsep) 6759 [input-stmt stmtsep] 6760 [output-stmt stmtsep] 6761 "}") 6763 input-stmt = input-keyword optsep 6764 "{" stmtsep 6765 ;; these stmts can appear in any order 6766 *((typedef-stmt / 6767 grouping-stmt) stmtsep) 6768 1*(data-def-stmt stmtsep) 6769 "}" 6771 output-stmt = output-keyword optsep 6772 "{" stmtsep 6773 ;; these stmts can appear in any order 6774 *((typedef-stmt / 6775 grouping-stmt) stmtsep) 6776 1*(data-def-stmt stmtsep) 6777 "}" 6779 notification-stmt = notification-keyword sep 6780 identifier-arg-str optsep 6781 (";" / 6782 "{" stmtsep 6783 ;; these stmts can appear in any order 6784 *(if-feature-stmt stmtsep) 6785 [status-stmt stmtsep] 6786 [description-stmt stmtsep] 6787 [reference-stmt stmtsep] 6788 *((typedef-stmt / 6789 grouping-stmt) stmtsep) 6790 *(data-def-stmt stmtsep) 6791 "}") 6793 deviation-stmt = deviation-keyword sep 6794 deviation-arg-str optsep 6795 "{" stmtsep 6796 ;; these stmts can appear in any order 6797 [description-stmt stmtsep] 6798 [reference-stmt stmtsep] 6799 (deviate-not-supported-stmt / 6800 1*(deviate-add-stmt / 6801 deviate-replace-stmt / 6802 deviate-delete-stmt)) 6803 "}" 6805 deviation-arg-str = < a string which matches the rule 6806 deviation-arg > 6808 deviation-arg = absolute-schema-nodeid 6810 deviate-not-supported-stmt = 6811 deviate-keyword sep 6812 not-supported-keyword optsep 6813 (";" / 6814 "{" stmtsep 6815 "}") 6817 deviate-add-stmt = deviate-keyword sep add-keyword optsep 6818 (";" / 6819 "{" stmtsep 6821 [units-stmt stmtsep] 6822 *(must-stmt stmtsep) 6823 *(unique-stmt stmtsep) 6824 [default-stmt stmtsep] 6825 [config-stmt stmtsep] 6826 [mandatory-stmt stmtsep] 6827 [min-elements-stmt stmtsep] 6828 [max-elements-stmt stmtsep] 6829 "}") 6831 deviate-delete-stmt = deviate-keyword sep delete-keyword optsep 6832 (";" / 6833 "{" stmtsep 6834 [units-stmt stmtsep] 6835 *(must-stmt stmtsep) 6836 *(unique-stmt stmtsep) 6837 [default-stmt stmtsep] 6838 "}") 6840 deviate-replace-stmt = deviate-keyword sep replace-keyword optsep 6841 (";" / 6842 "{" stmtsep 6843 [type-stmt stmtsep] 6844 [units-stmt stmtsep] 6845 [default-stmt stmtsep] 6846 [config-stmt stmtsep] 6847 [mandatory-stmt stmtsep] 6848 [min-elements-stmt stmtsep] 6849 [max-elements-stmt stmtsep] 6850 "}") 6852 ;; Ranges 6854 range-arg-str = < a string which matches the rule 6855 range-arg > 6857 range-arg = range-part *(optsep "|" optsep range-part) 6859 range-part = range-boundary 6860 [optsep ".." optsep range-boundary] 6862 range-boundary = min-keyword / max-keyword / 6863 integer-value / decimal-value 6865 ;; Lengths 6867 length-arg-str = < a string which matches the rule 6868 length-arg > 6870 length-arg = length-part *(optsep "|" optsep length-part) 6872 length-part = length-boundary 6873 [optsep ".." optsep length-boundary] 6875 length-boundary = min-keyword / max-keyword / 6876 non-negative-integer-value 6878 ;; Date 6880 date-arg-str = < a string which matches the rule 6881 date-arg > 6883 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 6885 ;; Schema Node Identifiers 6887 schema-nodeid = absolute-schema-nodeid / 6888 descendant-schema-nodeid 6890 absolute-schema-nodeid = 1*("/" node-identifier) 6892 descendant-schema-nodeid = 6893 node-identifier 6894 absolute-schema-nodeid 6896 node-identifier = [prefix ":"] identifier 6898 ;; Instance Identifiers 6900 instance-identifier = 1*("/" (node-identifier *predicate)) 6902 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 6904 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 6905 ((DQUOTE string DQUOTE) / 6906 (SQUOTE string SQUOTE)) 6908 pos = non-negative-integer-value 6910 ;; leafref path 6912 path-arg-str = < a string which matches the rule 6913 path-arg > 6915 path-arg = absolute-path / relative-path 6916 absolute-path = 1*("/" (node-identifier *path-predicate)) 6918 relative-path = 1*(".." "/") descendant-path 6920 descendant-path = node-identifier 6921 [*path-predicate absolute-path] 6923 path-predicate = "[" *WSP path-equality-expr *WSP "]" 6925 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 6927 path-key-expr = current-function-invocation *WSP "/" *WSP 6928 rel-path-keyexpr 6930 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 6931 *(node-identifier *WSP "/" *WSP) 6932 node-identifier 6934 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 6936 ;; statment keywords 6937 anyxml-keyword = 'anyxml' 6938 argument-keyword = 'argument' 6939 augment-keyword = 'augment' 6940 base-keyword = 'base' 6941 belongs-to-keyword = 'belongs-to' 6942 bit-keyword = 'bit' 6943 case-keyword = 'case' 6944 choice-keyword = 'choice' 6945 config-keyword = 'config' 6946 contact-keyword = 'contact' 6947 container-keyword = 'container' 6948 default-keyword = 'default' 6949 description-keyword = 'description' 6950 enum-keyword = 'enum' 6951 error-app-tag-keyword = 'error-app-tag' 6952 error-message-keyword = 'error-message' 6953 extension-keyword = 'extension' 6954 deviation-keyword = 'deviation' 6955 deviate-keyword = 'deviate' 6956 feature-keyword = 'feature' 6957 fraction-digits-keyword = 'fraction-digits' 6958 grouping-keyword = 'grouping' 6959 identity-keyword = 'identity' 6960 if-feature-keyword = 'if-feature' 6961 import-keyword = 'import' 6962 include-keyword = 'include' 6963 input-keyword = 'input' 6964 key-keyword = 'key' 6965 leaf-keyword = 'leaf' 6966 leaf-list-keyword = 'leaf-list' 6967 length-keyword = 'length' 6968 list-keyword = 'list' 6969 mandatory-keyword = 'mandatory' 6970 max-elements-keyword = 'max-elements' 6971 min-elements-keyword = 'min-elements' 6972 module-keyword = 'module' 6973 must-keyword = 'must' 6974 namespace-keyword = 'namespace' 6975 notification-keyword= 'notification' 6976 ordered-by-keyword = 'ordered-by' 6977 organization-keyword= 'organization' 6978 output-keyword = 'output' 6979 path-keyword = 'path' 6980 pattern-keyword = 'pattern' 6981 position-keyword = 'position' 6982 prefix-keyword = 'prefix' 6983 presence-keyword = 'presence' 6984 range-keyword = 'range' 6985 reference-keyword = 'reference' 6986 refine-keyword = 'refine' 6987 require-instance-keyword = 'require-instance' 6988 revision-keyword = 'revision' 6989 revision-date-keyword = 'revision-date' 6990 rpc-keyword = 'rpc' 6991 status-keyword = 'status' 6992 submodule-keyword = 'submodule' 6993 type-keyword = 'type' 6994 typedef-keyword = 'typedef' 6995 unique-keyword = 'unique' 6996 units-keyword = 'units' 6997 uses-keyword = 'uses' 6998 value-keyword = 'value' 6999 when-keyword = 'when' 7000 yang-version-keyword= 'yang-version' 7001 yin-element-keyword = 'yin-element' 7003 ;; other keywords 7005 add-keyword = 'add' 7006 current-keyword = 'current' 7007 delete-keyword = 'delete' 7008 deprecated-keyword = 'deprecated' 7009 false-keyword = 'false' 7010 max-keyword = 'max' 7011 min-keyword = 'min' 7012 not-supported-keyword = 'not-supported' 7013 obsolete-keyword = 'obsolete' 7014 replace-keyword = 'replace' 7015 system-keyword = 'system' 7016 true-keyword = 'true' 7017 unbounded-keyword = 'unbounded' 7018 user-keyword = 'user' 7020 current-function-invocation = current-keyword *WSP "(" *WSP ")" 7022 ;; Basic Rules 7024 prefix-arg-str = < a string which matches the rule 7025 prefix-arg > 7027 prefix-arg = prefix 7029 prefix = identifier 7031 identifier-arg-str = < a string which matches the rule 7032 identifier-arg > 7034 identifier-arg = identifier 7036 identifier = (ALPHA / "_") 7037 *(ALPHA / DIGIT / "_" / "-" / ".") 7039 identifier-ref-arg-str = < a string which matches the rule 7040 identifier-ref-arg > 7042 identifier-ref-arg = [prefix ":"] identifier 7044 string = < an unquoted string as returned by 7045 the scanner > 7047 integer-value = ("-" non-negative-integer-value) / 7048 non-negative-integer-value 7050 non-negative-integer-value = "0" / positive-integer-value 7052 positive-integer-value = (non-zero-digit *DIGIT) 7054 zero-integer-value = 1*DIGIT 7056 stmtend = ";" / "{" *unknown-statement "}" 7058 sep = 1*(WSP / line-break) 7059 ; unconditional separator 7061 optsep = *(WSP / line-break) 7063 stmtsep = *(WSP / line-break / unknown-statement) 7065 line-break = CRLF / LF 7067 non-zero-digit = %x31-39 7069 decimal-value = integer-value ("." zero-integer-value) 7071 SQUOTE = %x27 7072 ; ' (Single Quote) 7074 ;; 7075 ;; RFC 4234 core rules. 7076 ;; 7078 ALPHA = %x41-5A / %x61-7A 7079 ; A-Z / a-z 7081 CR = %x0D 7082 ; carriage return 7084 CRLF = CR LF 7085 ; Internet standard newline 7087 DIGIT = %x30-39 7088 ; 0-9 7090 DQUOTE = %x22 7091 ; " (Double Quote) 7093 HEXDIG = DIGIT / 7094 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 7095 ; only lower-case a..f 7097 HTAB = %x09 7098 ; horizontal tab 7100 LF = %x0A 7101 ; linefeed 7103 SP = %x20 7104 ; space 7106 VCHAR = %x21-7E 7107 ; visible (printing) characters 7109 WSP = SP / HTAB 7110 ; whitespace 7112 == end "yang.abnf" 7114 13. Error Responses for YANG Related Errors 7116 A number of NETCONF error responses are defined for error cases 7117 related to the data-model handling. If the relevant YANG statement 7118 has an "error-app-tag" substatement, that overrides the default value 7119 specified below. 7121 13.1. Error Message for Data that Violates a unique Statement 7123 If a NETCONF operation would result in configuration data where a 7124 unique constraint is invalidated, the following error is returned: 7126 Tag: operation-failed 7127 Error-app-tag: data-not-unique 7128 Error-info: : Contains an instance identifier which 7129 points to a leaf which invalidates the unique 7130 constraint. This element is present once for each 7131 leaf invalidating the unique constraint. 7133 The element is in the YANG 7134 namespace ("urn:ietf:params:xml:ns:yang:1"). 7136 13.2. Error Message for Data that Violates a max-elements Statement 7138 If a NETCONF operation would result in configuration data where a 7139 list or a leaf-list would have too many entries the following error 7140 is returned: 7142 Tag: operation-failed 7143 Error-app-tag: too-many-elements 7145 This error is returned once, with the error-path identifying the list 7146 node, even if there are more than one extra child present. 7148 13.3. Error Message for Data that Violates a min-elements Statement 7150 If a NETCONF operation would result in configuration data where a 7151 list or a leaf-list would have too few entries the following error is 7152 returned: 7154 Tag: operation-failed 7155 Error-app-tag: too-few-elements 7157 This error is returned once, with the error-path identifying the list 7158 node, even if there are more than one child missing. 7160 13.4. Error Message for Data that Violates a must Statement 7162 If a NETCONF operation would result in configuration data where the 7163 restrictions imposed by a "must" statement is violated the following 7164 error is returned, unless a specific "error-app-tag" substatement is 7165 present for the "must" statement. 7167 Tag: operation-failed 7168 Error-app-tag: must-violation 7170 13.5. Error Message for Data that Violates a require-instance Statement 7172 If a NETCONF operation would result in configuration data where a 7173 leaf of type "instance-identifier" marked with require-instance 7174 "true" refers to a non-existing instance, the following error is 7175 returned: 7177 Tag: data-missing 7178 Error-app-tag: instance-required 7179 Error-path: Path to the instance-identifier leaf. 7181 13.6. Error Message for Data that does not Match a leafref Type 7183 If a NETCONF operation would result in configuration data where a 7184 leaf of type "leafref" refers to a non-existing instance, the 7185 following error is returned: 7187 Tag: data-missing 7188 Error-app-tag: instance-required 7189 Error-path: Path to the leafref leaf. 7191 13.7. Error Message for Data that Violates a mandatory choice Statement 7193 If a NETCONF operation would result in configuration data where no 7194 nodes exists in a mandatory choice, the following error is returned: 7196 Tag: data-missing 7197 Error-app-tag: missing-choice 7198 Error-path: Path to the element with the missing choice. 7199 Error-info: : Contains the name of the missing 7200 mandatory choice. 7202 The element is in the YANG 7203 namespace ("urn:ietf:params:xml:ns:yang:1"). 7205 13.8. Error Message for the "insert" Operation 7207 If the "insert" and "key" or "value" attributes are used in an 7208 for a list or leaf-list node, and the "key" or "value" 7209 refers to a non-existing instance, the following error is returned: 7211 Tag: bad-attribute 7212 Error-app-tag: missing-instance 7214 14. IANA Considerations 7216 This document defines a registry for YANG module and submodule names. 7217 The name of the registry is "YANG Module Names". 7219 The registry shall record for each entry: 7221 o the name of the module or submodule 7223 o for modules, the assigned XML namespace 7225 o for modules, the prefix of the module 7227 o for submodules, the name of the module it belongs to 7229 o a reference to the (sub)module's documentation (the RFC number) 7231 For allocation, RFC publication is required as per RFC 5226 7232 [RFC5226]. All registered YANG module names must comply with the 7233 rules for identifiers stated in Section 6.2. There are no initial 7234 assignments. 7236 The module name prefix 'ietf-' is reserved for IETF stream documents 7237 while the module name prefix 'irtf-' is reserved for IRTF stream 7238 documents. Modules published in other RFC streams must have a 7239 similar suitable prefix. The prefix 'iana-' is reserved for modules 7240 maintained by IANA. 7242 All module and submodule names in the registry MUST be unique. 7244 All XML namespaces in the registry MUST be unique. 7246 This document registers two URIs for the YANG and YIN XML namespaces 7247 in the IETF XML registry [RFC3688]. Following the format in RFC 7248 3688, the following registration is requested. 7250 URI: urn:ietf:params:xml:ns:yang:yin:1 7251 URI: urn:ietf:params:xml:ns:yang:1 7253 Registrant Contact: The IESG. 7255 XML: N/A, the requested URIs are XML namespaces. 7257 15. Security Considerations 7259 This document defines a language with which to write and read 7260 descriptions of management information. The language itself has no 7261 security impact on the Internet. 7263 Data modeled in YANG might contain sensitive information. RPCs or 7264 notifications defined in YANG might transfer sensitive information. 7266 Security issues are related to the usage of data modeled in YANG. 7267 Such issues shall be dealt with in documents describing the data 7268 models and documents about the interfaces used to manipulate the data 7269 e.g., the NETCONF documents. 7271 Data modeled in YANG is dependent upon: 7273 o the security of the transmission infrastructure used to send 7274 sensitive information 7276 o the security of applications which store or release such sensitive 7277 information. 7279 o adequate authentication and access control mechanisms to restrict 7280 the usage of sensitive data. 7282 16. Contributors 7284 The following people all contributed significantly to the initial 7285 YANG draft: 7287 - Andy Bierman (Netconf Central) 7288 - Balazs Lengyel (Ericsson) 7289 - David Partain (Ericsson) 7290 - Juergen Schoenwaelder (Jacobs University Bremen) 7291 - Phil Shafer (Juniper Networks) 7293 17. Acknowledgements 7295 The editor wishes to thank the following individuals, who all 7296 provided helpful comments on various versions of this document: 7297 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 7298 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 7299 Wijnen. 7301 18. References 7303 18.1. Normative References 7305 [ISO.10646] 7306 International Organization for Standardization, 7307 "Information Technology - Universal Multiple-octet coded 7308 Character Set (UCS) - Part 1: Architecture and Basic 7309 Multilingual Plane", ISO Standard 10646-1, May 1993. 7311 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7312 Requirement Levels", BCP 14, RFC 2119, March 1997. 7314 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 7315 10646", STD 63, RFC 3629, November 2003. 7317 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 7318 January 2004. 7320 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 7321 Resource Identifier (URI): Generic Syntax", STD 66, 7322 RFC 3986, January 2005. 7324 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 7325 Encodings", RFC 4648, October 2006. 7327 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 7328 December 2006. 7330 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 7331 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 7332 May 2008. 7334 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 7335 Specifications: ABNF", STD 68, RFC 5234, January 2008. 7337 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 7338 Notifications", RFC 5277, July 2008. 7340 [XML-NAMES] 7341 Tobin, R., Bray, T., Hollander, D., and A. Layman, 7342 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 7343 Consortium Recommendation REC-xml-names-20060816, 7344 August 2006, 7345 . 7347 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 7348 Version 1.0", World Wide Web Consortium 7349 Recommendation REC-xpath-19991116, November 1999, 7350 . 7352 [XSD-TYPES] 7353 Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes 7354 Second Edition", W3C REC REC-xmlschema-2-20041028, 7355 October 2004. 7357 18.2. Non-Normative References 7359 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7360 Schoenwaelder, Ed., "Structure of Management Information 7361 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 7363 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7364 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 7365 STD 58, RFC 2579, April 1999. 7367 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 7368 Structure of Management Information", RFC 3780, May 2004. 7370 [XPATH2.0] 7371 Chamberlin, D., Boag, S., Berglund, A., Robie, J., Simeon, 7372 J., Fernandez, M., and M. Kay, "XML Path Language (XPath) 7373 2.0", World Wide Web Consortium Recommendation REC- 7374 xpath20-20070123, January 2007, 7375 . 7377 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 7378 Wide Web Consortium Recommendation REC-xslt-19991116, 7379 November 1999, 7380 . 7382 Appendix A. ChangeLog 7384 RFC Editor: remove this section upon publication as an RFC. 7386 A.1. Version -08 7388 o Clarified text on leaf deafults. 7390 o Added the term "top-level data node" to the terminology section. 7392 o Clarified how prefixes are mapped to namespaces in XPath 7393 expressions. 7395 o Added "reference" as a substatement to "revision". 7397 o Added "choice" as a substatement to "case". 7399 o Clarified that a leafreaf must be conditional if the leaf it 7400 refers to is conditional. 7402 o Clarified how identityref default values are represented. 7404 o Various bug fixes, clarifications and editorial fixes. 7406 A.2. Version -07 7408 o The argument string of "augment", "refine", and "deviation" is 7409 described not as an XPath but as a "schema node identifier". 7411 o Clarified that there must be no circular references in a leafref. 7413 A.3. Version -06 7415 o Various bug fixes, clarifications and editorial fixes after WGLC. 7417 o Removed "require-instance" for leafref. 7419 o Allow leafrefs to refer to leaf-lists. 7421 o Clarified the XPath context in Section 6.4.1, and for "must", 7422 "when", "augment", "path" and "instance-identifier". 7424 A.4. Version -05 7426 o Replaced the data types "float32" and "float64" with "decimal64". 7428 o Specified that the elements in the XML encoding of configuration 7429 data can occur in any order. 7431 o Clarified that "augment" cannot add multiple nodes with the same 7432 name. 7434 o Clarified what "when" means in RPC input / output. 7436 o Wrote the IANA Considerations section. 7438 o Changed requirement for minimum identifier length to 64 7439 characters. 7441 A.5. Version -04 7443 o Using "revision-date" substatement to "import" and "include". 7445 o Corrected grammar and text for instance-identifier. 7447 o Fixed bugs in some examples. 7449 o Rewrote the YIN description to use a declarative style. 7451 o Added two error codes in Section 13. 7453 o Clarified that YANG uses the same XPath data model as XSLT. 7455 o Specified which errors are generated in Section 8.3.1. 7457 o Corrected grammar for key-arg; now allowing optional prefix on 7458 each leaf identifier. 7460 o Clarified that "unique" constraints only check instances with 7461 values for all referenced leafs. 7463 o Clarified how mandatory and min-elements constraints are enforced. 7465 o Editorial fixes. 7467 A.6. Version -03 7469 o Added import by revision (yang-00413) 7471 o Changed type "keyref" to "leafref", and added the statement 7472 "require-instance" (yang-01253) 7474 o Clarified that data sent from the server must be in the canonical 7475 form. 7477 o Clarified when and how constraints in the models are enforced. 7479 o Many editorial fixes 7481 o Added more strict grammar for the "deviate" statement. 7483 A.7. Version -02 7485 o Added module update rules. (yang-00000) 7487 o Added "refine" statement as a substatement to "uses". (yang-00088) 7489 o Allow "augment" on top-level and in "uses" only. (yang-00088) 7491 o Allow "when" on all data defintion statements. (yang-00088) 7493 o Added section "Constraints" and clarified when constraints are 7494 enforced. (yang-00172) 7496 o Added "feature" and "if-feature" statements. (yang-00750) 7498 o Added "prefix" as a substatement to "belongs-to". (yang-00755) 7500 o Added section on Conformance. (yang-01281) 7502 o Added "deviation" statement. (yang-01281) 7504 o Added "identity" statement and "identityref" type. (yang-01339) 7506 o Aligned grammar for "enum" with text. 7508 A.8. Version -01 7510 o Removed "Appendix A. Derived YANG Types". 7512 o Removed "Appendix C. XML Schema Considerations". 7514 o Removed "Appendix F. Why We Need a New Modeling Language". 7516 o Moved "Appendix B. YIN" to its own section. 7518 o Moved "Appendix D. YANG ABNF Grammar" to its own section. 7520 o Moved "Appendix E. Error Responses for YANG Related Errors" into 7521 its own section. 7523 o The "input" and "output" nodes are now implicitly created by the 7524 "rpc" statement, in order for augmentation of these nodes to work 7525 correctly. 7527 o Allow "config" in "choice". 7529 o Added reference to XPath 1.0. 7531 o Using an XPath function "current()" instead of the variable 7532 "$this". 7534 o Clarified that a "must" expression in a configuration node must 7535 not reference non-configuration nodes. 7537 o Added XML encoding rules and usage examples for rpc and 7538 notification. 7540 o Removed requirement that refinements are specified in the same 7541 order as in the original grouping's definition. 7543 o Fixed whitespace issues in the ABNF grammar. 7545 o Added the term "mandatory node", and refer to it in the 7546 description of augment (see Section 7.15), and choice (see 7547 Section 7.9.3). 7549 o Added support for multiple "pattern" statements in "type". 7551 o Several clarifications and fixed typos. 7553 A.9. Version -00 7555 Changes from draft-bjorklund-netconf-yang-02.txt 7557 o Fixed bug in grammar for bit-stmt 7559 o Fixed bugs in example XPath expressions 7561 o Added keyword 'presence' to the YIN mapping table 7563 Author's Address 7565 Martin Bjorklund (editor) 7566 Tail-f Systems 7568 Email: mbj@tail-f.com