idnits 2.17.1 draft-ietf-netmod-yang-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 1, 2010) is 5040 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 5951 == Missing Reference: 'RFC3023' is mentioned on line 7487, but not defined ** Obsolete undefined reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track June 1, 2010 5 Expires: December 3, 2010 7 YANG - A data modeling language for the Network Configuration Protocol 8 (NETCONF) 9 draft-ietf-netmod-yang-13 11 Abstract 13 YANG is a data modeling language used to model configuration and 14 state data manipulated by the Network Configuration Protocol 15 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 16 notifications. 18 Status of this Memo 20 This Internet-Draft is submitted to IETF in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt. 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 This Internet-Draft will expire on December 3, 2010. 41 Copyright Notice 43 Copyright (c) 2010 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 This document may contain material from IETF Documents or IETF 57 Contributions published or made publicly available before November 58 10, 2008. The person(s) controlling the copyright in some of this 59 material may not have granted the IETF Trust the right to allow 60 modifications of such material outside the IETF Standards Process. 61 Without obtaining an adequate license from the person(s) controlling 62 the copyright in such materials, this document may not be modified 63 outside the IETF Standards Process, and derivative works of it may 64 not be created outside the IETF Standards Process, except to format 65 it for publication as an RFC or to translate it into languages other 66 than English. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 71 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 13 74 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 75 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 14 76 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 77 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 78 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 79 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 80 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 20 81 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 82 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 83 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 84 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 85 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 25 86 4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 87 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 88 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 89 5.1.1. Import and Include by Revision . . . . . . . . . . . 29 90 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 91 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 92 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 93 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 94 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 95 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 96 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 97 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 98 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 99 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 100 5.6.4. Announcing Conformance Information in the 101 Message . . . . . . . . . . . . . . . . . . . . . . . 34 102 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 36 103 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 37 104 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 37 105 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 37 106 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 37 107 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 37 108 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 39 109 6.2.1. Identifiers and their namespaces . . . . . . . . . . 39 110 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 40 111 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 40 112 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 40 113 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 41 114 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 41 115 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 43 116 7.1. The module Statement . . . . . . . . . . . . . . . . . . 43 117 7.1.1. The module's Substatements . . . . . . . . . . . . . 44 118 7.1.2. The yang-version Statement . . . . . . . . . . . . . 45 119 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 45 120 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 46 121 7.1.5. The import Statement . . . . . . . . . . . . . . . . 46 122 7.1.6. The include Statement . . . . . . . . . . . . . . . . 47 123 7.1.7. The organization Statement . . . . . . . . . . . . . 48 124 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 48 125 7.1.9. The revision Statement . . . . . . . . . . . . . . . 48 126 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 49 127 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 49 128 7.2.1. The submodule's Substatements . . . . . . . . . . . . 51 129 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 51 130 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 52 131 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 52 132 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 53 133 7.3.2. The typedef's type Statement . . . . . . . . . . . . 53 134 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 53 135 7.3.4. The typedef's default Statement . . . . . . . . . . . 53 136 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 54 137 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 54 138 7.4.1. The type's Substatements . . . . . . . . . . . . . . 54 139 7.5. The container Statement . . . . . . . . . . . . . . . . . 54 140 7.5.1. Containers with Presence . . . . . . . . . . . . . . 55 141 7.5.2. The container's Substatements . . . . . . . . . . . . 56 142 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 56 143 7.5.4. The must's Substatements . . . . . . . . . . . . . . 58 144 7.5.5. The presence Statement . . . . . . . . . . . . . . . 59 145 7.5.6. The container's Child Node Statements . . . . . . . . 59 146 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 59 147 7.5.8. NETCONF Operations . . . . . . . . . . 59 148 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 60 149 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 61 150 7.6.1. The leaf's default value . . . . . . . . . . . . . . 61 151 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 62 152 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 62 153 7.6.4. The leaf's default Statement . . . . . . . . . . . . 62 154 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 63 155 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 63 156 7.6.7. NETCONF Operations . . . . . . . . . . 63 157 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 64 158 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 65 159 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 65 160 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 66 161 7.7.3. The min-elements Statement . . . . . . . . . . . . . 66 162 7.7.4. The max-elements Statement . . . . . . . . . . . . . 66 163 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 67 164 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 67 165 7.7.7. NETCONF Operations . . . . . . . . . . 68 166 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 69 167 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 70 168 7.8.1. The list's Substatements . . . . . . . . . . . . . . 71 169 7.8.2. The list's key Statement . . . . . . . . . . . . . . 71 170 7.8.3. The list's unique Statement . . . . . . . . . . . . . 72 171 7.8.4. The list's Child Node Statements . . . . . . . . . . 73 172 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 73 173 7.8.6. NETCONF Operations . . . . . . . . . . 74 174 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 75 175 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 78 176 7.9.1. The choice's Substatements . . . . . . . . . . . . . 79 177 7.9.2. The choice's case Statement . . . . . . . . . . . . . 79 178 7.9.3. The choice's default Statement . . . . . . . . . . . 80 179 7.9.4. The choice's mandatory Statement . . . . . . . . . . 82 180 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 181 7.9.6. NETCONF Operations . . . . . . . . . . 82 182 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 82 183 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 83 184 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 84 185 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 84 186 7.10.3. NETCONF Operations . . . . . . . . . . 84 187 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 188 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 85 189 7.11.1. The grouping's Substatements . . . . . . . . . . . . 86 190 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 87 191 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 87 192 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 88 193 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 88 194 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 89 195 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 89 196 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 90 197 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 91 198 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 91 199 7.13.3. The output Statement . . . . . . . . . . . . . . . . 92 200 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 201 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 93 202 7.14. The notification Statement . . . . . . . . . . . . . . . 94 203 7.14.1. The notification's Substatements . . . . . . . . . . 95 204 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 95 205 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 206 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 96 207 7.15.1. The augment's Substatements . . . . . . . . . . . . . 97 208 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 97 209 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 97 210 7.16. The identity Statement . . . . . . . . . . . . . . . . . 99 211 7.16.1. The identity's Substatements . . . . . . . . . . . . 100 212 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 100 213 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 214 7.17. The extension Statement . . . . . . . . . . . . . . . . . 101 215 7.17.1. The extension's Substatements . . . . . . . . . . . . 102 216 7.17.2. The argument Statement . . . . . . . . . . . . . . . 102 217 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 218 7.18. Conformance-related Statements . . . . . . . . . . . . . 103 219 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 103 220 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 105 221 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 105 222 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 108 223 7.19.1. The config Statement . . . . . . . . . . . . . . . . 108 224 7.19.2. The status Statement . . . . . . . . . . . . . . . . 108 225 7.19.3. The description Statement . . . . . . . . . . . . . . 109 226 7.19.4. The reference Statement . . . . . . . . . . . . . . . 109 227 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 110 228 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 112 229 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 112 230 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 112 231 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 112 232 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 113 233 8.3.2. NETCONF Processing . . . . . . . . . . 113 234 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 114 235 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 115 236 9.1. Canonical representation . . . . . . . . . . . . . . . . 115 237 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 115 238 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 116 239 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 240 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 241 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 117 242 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 118 243 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 118 244 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 118 245 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 246 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 247 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 119 248 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 249 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 120 250 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 120 251 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 252 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 253 9.4.4. The length Statement . . . . . . . . . . . . . . . . 120 254 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 255 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 122 256 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 122 257 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 123 258 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 123 259 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 260 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 261 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 123 262 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 123 263 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 264 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 265 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 123 266 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124 267 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 125 268 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 269 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 125 270 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 125 271 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 125 272 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 273 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 126 274 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 275 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 127 276 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 127 277 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 127 278 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 279 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 127 280 9.9.3. Lexical Representation . . . . . . . . . . . . . . . 128 281 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 128 282 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 283 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 132 284 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 285 9.10.2. The identityref's base Statement . . . . . . . . . . 132 286 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 133 287 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 133 288 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 289 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 134 290 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 291 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 134 292 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 293 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 134 294 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 135 295 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 296 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 135 297 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 298 9.13. The instance-identifier Built-in Type . . . . . . . . . . 136 299 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 300 9.13.2. The require-instance Statement . . . . . . . . . . . 137 301 9.13.3. Lexical Representation . . . . . . . . . . . . . . . 137 302 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 137 303 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 304 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 139 305 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 306 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 142 307 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 144 309 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 147 310 13. Error Responses for YANG Related Errors . . . . . . . . . . . 169 311 13.1. Error Message for Data that Violates a unique Statement . 169 312 13.2. Error Message for Data that Violates a max-elements 313 Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 314 13.3. Error Message for Data that Violates a min-elements 315 Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 316 13.4. Error Message for Data that Violates a must Statement . . 170 317 13.5. Error Message for Data that Violates a 318 require-instance Statement . . . . . . . . . . . . . . . 170 319 13.6. Error Message for Data that does not Match a leafref 320 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 170 321 13.7. Error Message for Data that Violates a mandatory 322 choice Statement . . . . . . . . . . . . . . . . . . . . 170 323 13.8. Error Message for the "insert" Operation . . . . . . . . 171 324 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 172 325 14.1. Media type application/yang . . . . . . . . . . . . . . . 173 326 14.2. Media type application/yin+xml . . . . . . . . . . . . . 173 327 15. Security Considerations . . . . . . . . . . . . . . . . . . . 175 328 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 176 329 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 177 330 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 178 331 18.1. Normative References . . . . . . . . . . . . . . . . . . 178 332 18.2. Non-Normative References . . . . . . . . . . . . . . . . 179 333 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 180 334 A.1. Version -12 . . . . . . . . . . . . . . . . . . . . . . . 180 335 A.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 180 336 A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 180 337 A.4. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 180 338 A.5. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 181 339 A.6. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 181 340 A.7. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 181 341 A.8. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 181 342 A.9. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 182 343 A.10. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 182 344 A.11. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 183 345 A.12. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 183 346 A.13. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 184 347 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 185 349 1. Introduction 351 YANG is a data modeling language used to model configuration and 352 state data manipulated by the Network Configuration Protocol 353 (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF 354 notifications. YANG is used to model the operations and content 355 layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], 356 section 1.1). 358 This document describes the syntax and semantics of the YANG 359 language, how the data model defined in a YANG module is represented 360 in the Extensible Markup Language (XML), and how NETCONF operations 361 are used to manipulate the data. 363 2. Key Words 365 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 366 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 367 "OPTIONAL" in this document are to be interpreted as described in BCP 368 14, [RFC2119]. 370 3. Terminology 372 o anyxml: A data node which can contain an unknown chunk of XML 373 data. 375 o augment: Adds new schema nodes to a previously defined schema 376 node. 378 o base type: The type from which a derived type was derived, which 379 may be either a built-in type or another derived type. 381 o built-in type: A YANG data type defined in the YANG language, such 382 as uint32 or string. 384 o choice: A schema node where only one of a number of identified 385 alternatives is valid. 387 o configuration data: The set of writable data that is required to 388 transform a system from its initial default state into its current 389 state [RFC4741]. 391 o conformance: A measure of how accurately a device follows a data 392 model. 394 o container: An interior data node which exists in at most one 395 instance in the data tree. A container has no value, but rather a 396 set of child nodes. 398 o data definition statement: A statement that defines new data 399 nodes. One of container, leaf, leaf-list, list, choice, case, 400 augment, uses, and anyxml. 402 o data model: A data model describes how data is represented and 403 accessed. 405 o data node: A node in the schema tree that can be instantiated in a 406 data tree. One of container, leaf, leaf-list, list, and anyxml. 408 o data tree: The instantiated tree of configuration and state data 409 on a device. 411 o derived type: A type which is derived from a built-in type (such 412 as uint32), or another derived type. 414 o device deviation: A failure of the device to implement the module 415 faithfully. 417 o extension: An extension attaches non-YANG semantics to statements. 418 The extension statement defines new statements to express these 419 semantics. 421 o feature: A mechanism for marking a portion of the model as 422 optional. Definitions can be tagged with a feature name and are 423 only valid on devices which support that feature. 425 o grouping: A reusable set of schema nodes, which may be used 426 locally in the module, in modules which include it, and by other 427 modules which import from it. The grouping statement is not a 428 data definition statement and, as such, does not define any nodes 429 in the schema tree. 431 o identifier: Used to identify different kinds of YANG items by 432 name. 434 o instance identifier: A mechanism for identifying a particular node 435 in a data tree. 437 o interior node: Nodes within a hierarchy that are not leaf nodes. 439 o leaf: A data node which exists in at most one instance in the data 440 tree. A leaf has a value but no child nodes. 442 o leaf-list: Like the leaf node but defines a set of uniquely 443 identifiable nodes rather than a single node. Each node has a 444 value but no child nodes. 446 o list: An interior data node which may exist in multiple instances 447 in the data tree. A list has no value, but rather a set of child 448 nodes. 450 o module: A YANG module defines a hierarchy of nodes which can be 451 used for NETCONF-based operations. With its definitions and the 452 definitions it imports or includes from elsewhere, a module is 453 self-contained and "compilable". 455 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 457 o RPC operation: A specific Remote Procedure Call, as used within 458 the NETCONF protocol. Also called a protocol operation. 460 o schema node: A node in the schema tree. One of container, leaf, 461 leaf-list, list, choice, case, rpc, input, output, notification, 462 and anyxml. 464 o schema node identifier: A mechanism for identifying a particular 465 node in the schema tree. 467 o schema tree: The definition hierarchy specified within a module. 469 o state data: The additional data on a system that is not 470 configuration data such as read-only status information and 471 collected statistics [RFC4741]. 473 o submodule: A partial module definition which contributes derived 474 types, groupings, data nodes, RPCs, and notifications to a module. 475 A YANG module can be constructed from a number of submodules. 477 o top-level data node: A data node where there is no other data node 478 between it and a module or submodule statement. 480 o uses: The "uses" statement is used to instantiate the set of 481 schema nodes defined in a grouping statement. The instantiated 482 nodes may be refined and augmented to tailor them to any specific 483 needs. 485 3.1. Mandatory nodes 487 A mandatory node is one of: 489 o A leaf, choice, or anyxml node with a "mandatory" statement with 490 the value "true". 492 o A list or leaf-list node with a "min-elements" statement with a 493 value greater than zero. 495 o A container node without a "presence" statement, which has at 496 least one mandatory node as a child. 498 4. YANG Overview 500 4.1. Functional Overview 502 YANG is a language used to model data for the NETCONF protocol. A 503 YANG module defines a hierarchy of data which can be used for 504 NETCONF-based operations, including configuration, state data, remote 505 procedure calls (RPCs), and notifications. This allows a complete 506 description of all data sent between a NETCONF client and server. 508 YANG models the hierarchical organization of data as a tree in which 509 each node has a name, and either a value or a set of child nodes. 510 YANG provides clear and concise descriptions of the nodes, as well as 511 the interaction between those nodes. 513 YANG structures data models into modules and submodules. A module 514 can import data from other external modules, and include data from 515 submodules. The hierarchy can be augmented, allowing one module to 516 add data nodes to the hierarchy defined in another module. This 517 augmentation can be conditional, with new nodes appearing only if 518 certain conditions are met. 520 YANG models can describe constraints to be enforced on the data, 521 restricting the appearance or value of nodes based on the presence or 522 value of other nodes in the hierarchy. These constraints are 523 enforceable by either the client or the server, and valid content 524 MUST abide by them. 526 YANG defines a set of built-in types, and has a type mechanism 527 through which additional types may be defined. Derived types can 528 restrict their base type's set of valid values using mechanisms like 529 range or pattern restrictions that can be enforced by clients or 530 servers. They can also define usage conventions for use of the 531 derived type, such as a string-based type that contains a host name. 533 YANG permits the definition of reusable grouping of nodes. The 534 instantiation of these groupings can refine or augment the nodes, 535 allowing it to tailor the nodes to its particular needs. Derived 536 types and groupings can be defined in one module or submodule and 537 used in either that location or in another module or submodule that 538 imports or includes it. 540 YANG data hierarchy constructs include defining lists where list 541 entries are identified by keys which distinguish them from each 542 other. Such lists may be defined as either sorted by user or 543 automatically sorted by the system. For user-sorted lists, 544 operations are defined for manipulating the order of the list 545 entries. 547 YANG modules can be translated into an equivalent XML syntax called 548 YANG Independent Notation (YIN) (Section 11), allowing applications 549 using XML parsers and XSLT scripts to operate on the models. The 550 conversion from YANG to YIN is loss-less, so content in YIN can be 551 round-tripped back into YANG. 553 YANG strikes a balance between high-level data modeling and low-level 554 bits-on-the-wire encoding. The reader of a YANG module can see the 555 high-level view of the data model while understanding how the data 556 will be encoded in NETCONF operations. 558 YANG is an extensible language, allowing extension statements to be 559 defined by standards bodies, vendors, and individuals. The statement 560 syntax allows these extensions to coexist with standard YANG 561 statements in a natural way, while extensions in a YANG module stand 562 out sufficiently for the reader to notice them. 564 YANG resists the tendency to solve all possible problems, limiting 565 the problem space to allow expression of NETCONF data models, not 566 arbitrary XML documents or arbitrary data models. The data models 567 described by YANG are designed to be easily operated upon by NETCONF 568 operations. 570 To the extent possible, YANG maintains compatibility with SNMP's 571 SMIv2 (Structure of Management Information version 2 [RFC2578], 572 [RFC2579]). SMIv2-based MIB modules can be automatically translated 573 into YANG modules for read-only access. However, YANG is not 574 concerned with reverse translation from YANG to SMIv2. 576 Like NETCONF, YANG targets smooth integration with the device's 577 native management infrastructure. This allows implementations to 578 leverage their existing access control mechanisms to protect or 579 expose elements of the data model. 581 4.2. Language Overview 583 This section introduces some important constructs used in YANG that 584 will aid in the understanding of the language specifics in later 585 sections. This progressive approach handles the inter-related nature 586 of YANG concepts and statements. A detailed description of YANG 587 statements and syntax begins in Section 7. 589 4.2.1. Modules and Submodules 591 A module contains three types of statements: module-header 592 statements, revision statements, and definition statements. The 593 module header statements describe the module and give information 594 about the module itself, the revision statements give information 595 about the history of the module, and the definition statements are 596 the body of the module where the data model is defined. 598 A NETCONF server may implement a number of modules, allowing multiple 599 views of the same data, or multiple views of disjoint subsections of 600 the device's data. Alternatively, the server may implement only one 601 module that defines all available data. 603 A module may be divided into submodules, based on the needs of the 604 module owner. The external view remains that of a single module, 605 regardless of the presence or size of its submodules. 607 The "include" statement allows a module or submodule to reference 608 material in submodules, and the "import" statement allows references 609 to material defined in other modules. 611 4.2.2. Data Modeling Basics 613 YANG defines four types of nodes for data modeling. In each of the 614 following subsections, the example shows the YANG syntax as well as a 615 corresponding NETCONF XML representation. 617 4.2.2.1. Leaf Nodes 619 A leaf node contains simple data like an integer or a string. It has 620 exactly one value of a particular type, and no child nodes. 622 YANG Example: 624 leaf host-name { 625 type string; 626 description "Hostname for this system"; 627 } 629 NETCONF XML Example: 631 my.example.com 633 The "leaf" statement is covered in Section 7.6. 635 4.2.2.2. Leaf-list Nodes 637 A leaf-list is a sequence of leaf nodes with exactly one value of a 638 particular type per leaf. 640 YANG Example: 642 leaf-list domain-search { 643 type string; 644 description "List of domain names to search"; 645 } 647 NETCONF XML Example: 649 high.example.com 650 low.example.com 651 everywhere.example.com 653 The "leaf-list" statement is covered in Section 7.7. 655 4.2.2.3. Container Nodes 657 A container node is used to group related nodes in a subtree. A 658 container has only child nodes and no value. A container may contain 659 any number of child nodes of any type (including leafs, lists, 660 containers, and leaf-lists). 662 YANG Example: 664 container system { 665 container login { 666 leaf message { 667 type string; 668 description 669 "Message given at start of login session"; 670 } 671 } 672 } 674 NETCONF XML Example: 676 677 678 Good morning 679 680 682 The "container" statement is covered in Section 7.5. 684 4.2.2.4. List Nodes 686 A list defines a sequence of list entries. Each entry is like a 687 structure or a record instance, and is uniquely identified by the 688 values of its key leafs. A list can define multiple key leafs and 689 may contain any number of child nodes of any type (including leafs, 690 lists, containers etc.). 692 YANG Example: 694 list user { 695 key "name"; 696 leaf name { 697 type string; 698 } 699 leaf full-name { 700 type string; 701 } 702 leaf class { 703 type string; 704 } 705 } 707 NETCONF XML Example: 709 710 glocks 711 Goldie Locks 712 intruder 713 714 715 snowey 716 Snow White 717 free-loader 718 719 720 rzell 721 Rapun Zell 722 tower 723 725 The "list" statement is covered in Section 7.8. 727 4.2.2.5. Example Module 729 These statements are combined to define the module: 731 // Contents of "acme-system.yang" 732 module acme-system { 733 namespace "http://acme.example.com/system"; 734 prefix "acme"; 736 organization "ACME Inc."; 737 contact "joe@acme.example.com"; 738 description 739 "The module for entities implementing the ACME system."; 741 revision 2007-06-09 { 742 description "Initial revision."; 743 } 745 container system { 746 leaf host-name { 747 type string; 748 description "Hostname for this system"; 749 } 751 leaf-list domain-search { 752 type string; 753 description "List of domain names to search"; 754 } 756 container login { 757 leaf message { 758 type string; 759 description 760 "Message given at start of login session"; 761 } 763 list user { 764 key "name"; 765 leaf name { 766 type string; 767 } 768 leaf full-name { 769 type string; 770 } 771 leaf class { 772 type string; 773 } 774 } 775 } 776 } 777 } 779 4.2.3. State Data 781 YANG can model state data, as well as configuration data, based on 782 the "config" statement. When a node is tagged with "config false", 783 its subhierarchy is flagged as state data, to be reported using 784 NETCONF's operation, not the operation. Parent 785 containers, lists, and key leafs are reported also, giving the 786 context for the state data. 788 In this example, two leafs are defined for each interface, a 789 configured speed and an observed speed. The observed speed is not 790 configuration, so it can be returned with NETCONF operations, 791 but not with operations. The observed speed is not 792 configuration data, and cannot be manipulated using . 794 list interface { 795 key "name"; 797 leaf name { 798 type string; 799 } 800 leaf speed { 801 type enumeration { 802 enum 10m; 803 enum 100m; 804 enum auto; 805 } 806 } 807 leaf observed-speed { 808 type uint32; 809 config false; 810 } 811 } 813 4.2.4. Built-in Types 815 YANG has a set of built-in types, similar to those of many 816 programming languages, but with some differences due to special 817 requirements from the management domain. The following table 818 summarizes the built-in types discussed in Section 9: 820 +---------------------+-------------------------------------+ 821 | Name | Description | 822 +---------------------+-------------------------------------+ 823 | binary | Any binary data | 824 | bits | A set of bits or flags | 825 | boolean | "true" or "false" | 826 | decimal64 | 64-bit signed decimal number | 827 | empty | A leaf that does not have any value | 828 | enumeration | Enumerated strings | 829 | identityref | A reference to an abstract identity | 830 | instance-identifier | References a data tree node | 831 | int8 | 8-bit signed integer | 832 | int16 | 16-bit signed integer | 833 | int32 | 32-bit signed integer | 834 | int64 | 64-bit signed integer | 835 | leafref | A reference to a leaf instance | 836 | string | Human readable string | 837 | uint8 | 8-bit unsigned integer | 838 | uint16 | 16-bit unsigned integer | 839 | uint32 | 32-bit unsigned integer | 840 | uint64 | 64-bit unsigned integer | 841 | union | Choice of member types | 842 +---------------------+-------------------------------------+ 844 The "type" statement is covered in Section 7.4. 846 4.2.5. Derived Types (typedef) 848 YANG can define derived types from base types using the "typedef" 849 statement. A base type can be either a built-in type or a derived 850 type, allowing a hierarchy of derived types. 852 A derived type can be used as the argument for the "type" statement. 854 YANG Example: 856 typedef percent { 857 type uint8 { 858 range "0 .. 100"; 859 } 860 description "Percentage"; 861 } 863 leaf completed { 864 type percent; 865 } 867 NETCONF XML Example: 869 20 871 The "typedef" statement is covered in Section 7.3. 873 4.2.6. Reusable Node Groups (grouping) 875 Groups of nodes can be assembled into reusable collections using the 876 "grouping" statement. A grouping defines a set of nodes that are 877 instantiated with the "uses" statement: 879 grouping target { 880 leaf address { 881 type inet:ip-address; 882 description "Target IP address"; 883 } 884 leaf port { 885 type inet:port-number; 886 description "Target port number"; 887 } 888 } 890 container peer { 891 container destination { 892 uses target; 893 } 894 } 896 NETCONF XML Example: 898 899 900
192.0.2.1
901 830 902
903
905 The grouping can be refined as it is used, allowing certain 906 statements to be overridden. In this example, the description is 907 refined: 909 container connection { 910 container source { 911 uses target { 912 refine "address" { 913 description "Source IP address"; 914 } 915 refine "port" { 916 description "Source port number"; 917 } 918 } 919 } 920 container destination { 921 uses target { 922 refine "address" { 923 description "Destination IP address"; 924 } 925 refine "port" { 926 description "Destination port number"; 927 } 928 } 929 } 930 } 932 The "grouping" statement is covered in Section 7.11. 934 4.2.7. Choices 936 YANG allows the data model to segregate incompatible nodes into 937 distinct choices using the "choice" and "case" statements. The 938 "choice" statement contains a set of "case" statements which define 939 sets of schema nodes that cannot appear together. Each "case" may 940 contain multiple nodes, but each node may appear in only one "case" 941 under a "choice". 943 When an element from one case is created, all elements from all other 944 cases are implicitly deleted. The device handles the enforcement of 945 the constraint, preventing incompatibilities from existing in the 946 configuration. 948 The choice and case nodes appear only in the schema tree, not in the 949 data tree or NETCONF messages. The additional levels of hierarchy 950 are not needed beyond the conceptual schema. 952 YANG Example: 954 container food { 955 choice snack { 956 case sports-arena { 957 leaf pretzel { 958 type empty; 959 } 960 leaf beer { 961 type empty; 962 } 963 } 964 case late-night { 965 leaf chocolate { 966 type enumeration { 967 enum dark; 968 enum milk; 969 enum first-available; 970 } 971 } 972 } 973 } 974 } 976 NETCONF XML Example: 978 979 980 981 983 The "choice" statement is covered in Section 7.9. 985 4.2.8. Extending Data Models (augment) 987 YANG allows a module to insert additional nodes into data models, 988 including both the current module (and its submodules) or an external 989 module. This is useful for example for vendors to add vendor- 990 specific parameters to standard data models in an interoperable way. 992 The "augment" statement defines the location in the data model 993 hierarchy where new nodes are inserted, and the "when" statement 994 defines the conditions when the new nodes are valid. 996 YANG Example: 998 augment /system/login/user { 999 when "class != 'wheel'"; 1000 leaf uid { 1001 type uint16 { 1002 range "1000 .. 30000"; 1003 } 1004 } 1005 } 1007 This example defines a "uid" node that only is valid when the user's 1008 "class" is not "wheel". 1010 If a module augments another module, the XML representation of the 1011 data will reflect the prefix of the augmenting module. For example, 1012 if the above augmentation were in a module with prefix "other", the 1013 XML would look like: 1015 NETCONF XML Example: 1017 1018 alicew 1019 Alice N. Wonderland 1020 drop-out 1021 1024 1022 1024 The "augment" statement is covered in Section 7.15. 1026 4.2.9. RPC Definitions 1028 YANG allows the definition of NETCONF RPCs. The operation names, 1029 input parameters and output parameters are modeled using YANG data 1030 definition statements. 1032 YANG Example: 1034 rpc activate-software-image { 1035 input { 1036 leaf image-name { 1037 type string; 1038 } 1039 } 1040 output { 1041 leaf status { 1042 type string; 1043 } 1044 } 1045 } 1047 NETCONF XML Example: 1049 1051 1052 acmefw-2.3 1053 1054 1056 1058 1059 The image acmefw-2.3 is being installed. 1060 1061 1063 The "rpc" statement is covered in Section 7.13. 1065 4.2.10. Notification Definitions 1067 YANG allows the definition of notifications suitable for NETCONF. 1068 YANG data definition statements are used to model the content of the 1069 notification. 1071 YANG Example: 1073 notification link-failure { 1074 description "A link failure has been detected"; 1075 leaf if-name { 1076 type leafref { 1077 path "/interface/name"; 1078 } 1079 } 1080 leaf if-admin-status { 1081 type admin-status; 1082 } 1083 leaf if-oper-status { 1084 type oper-status; 1085 } 1086 } 1088 NETCONF XML Example: 1090 1092 2007-09-01T10:00:00Z 1093 1094 so-1/2/3.0 1095 up 1096 down 1097 1098 1100 The "notification" statement is covered in Section 7.14. 1102 5. Language Concepts 1104 5.1. Modules and Submodules 1106 The module is the base unit of definition in YANG. A module defines 1107 a single data model. A module can define a complete, cohesive model, 1108 or augment an existing data model with additional nodes. 1110 Submodules are partial modules that contribute definitions to a 1111 module. A module may include any number of submodules, but each 1112 submodule may belong to only one module. 1114 The names of all standard modules and submodules MUST be unique. 1115 Developers of enterprise modules are RECOMMENDED to choose names for 1116 their modules that will have a low probability of colliding with 1117 standard or other enterprise modules, e.g., by using the enterprise 1118 or organization name as a prefix for the module name. 1120 A module uses the "include" statement to include its submodules, and 1121 the "import" statement to reference external modules. Similarly, a 1122 submodule uses the "import" statement to reference other modules, and 1123 uses the "include" statement to reference other submodules within its 1124 module. A module or submodule MUST NOT include submodules from other 1125 modules, and a submodule MUST NOT import its own module. 1127 The import and include statements are used to make definitions 1128 available to other modules and submodules: 1130 o For a module or submodule to reference definitions in an external 1131 module, the external module MUST be imported. 1133 o For a module to reference definitions in one of its submodules, 1134 the module MUST include the submodule. 1136 o For a submodule to reference definitions in a second submodule of 1137 the same module, the first submodule MUST include the second 1138 submodule. 1140 There MUST NOT be any circular chains of imports or includes. For 1141 example, if submodule "a" includes submodule "b", "b" cannot include 1142 "a". 1144 When a definition in an external module is referenced, a locally 1145 defined prefix MUST be used, followed by ":", and then the external 1146 identifier. References to definitions in the local module MAY use 1147 the prefix notation. Since built-in data types do not belong to any 1148 module and have no prefix, references to built-in data types (e.g., 1149 int32) cannot use the prefix notation. 1151 5.1.1. Import and Include by Revision 1153 Published modules evolve independently over time. In order to allow 1154 for this evolution, modules need to be imported using specific 1155 revisions. When a module is written, it uses the current revisions 1156 of other modules, based on what is available at the time. As future 1157 revisions of the imported modules are published, the importing module 1158 is unaffected and its contents are unchanged. When the author of the 1159 module is prepared to move to the most recently published revision of 1160 an imported module, the module is republished with an updated import 1161 statement. By republishing with the new revision, the authors 1162 explicitly indicate their acceptance of any changes in the imported 1163 module. 1165 For submodules, the issue is related but simpler. A module or 1166 submodule that includes submodules need to specify the revision of 1167 the included submodules. If a submodule changes, any module or 1168 submodule that includes it needs to be updated. 1170 For example, module "b" imports module "a". 1172 module a { 1173 revision 2008-01-01 { ... } 1174 grouping a { 1175 leaf eh { .... } 1176 } 1177 } 1179 module b { 1180 import a { 1181 prefix p; 1182 revision-date 2008-01-01; 1183 } 1185 container bee { 1186 uses p:a; 1187 } 1188 } 1190 When the author of "a" publishes a new revision, the changes may not 1191 be acceptable to the author of "b". If the new revision is 1192 acceptable, the author of "b" can republish with an updated revision 1193 in the import statement. 1195 5.1.2. Module Hierarchies 1197 YANG allows modeling of data in multiple hierarchies, where data may 1198 have more than one top-level node. Models that have multiple top- 1199 level nodes are sometimes convenient, and are supported by YANG. 1201 NETCONF is capable of carrying any XML content as the payload in the 1202 and elements. The top-level nodes of YANG modules 1203 are encoded as child elements, in any order, within these elements. 1204 This encapsulation guarantees that the corresponding NETCONF messages 1205 are always well-formed XML documents. 1207 For example: 1209 module my-config { 1210 namespace "http://example.com/schema/config"; 1211 prefix "co"; 1213 container system { ... } 1214 container routing { ... } 1215 } 1217 could be encoded in NETCONF as: 1219 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1237 5.2. File Layout 1239 YANG modules and submodules are typically stored in files, one module 1240 or submodule per file. The name of the file SHOULD be of the form: 1242 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1244 YANG compilers can find imported modules and included submodules via 1245 this convention. While the YANG language defines modules, tools may 1246 compile submodules independently for performance and manageability 1247 reasons. Errors and warnings that cannot be detected during 1248 submodule compilation may be delayed until the submodules are linked 1249 into a cohesive module. 1251 5.3. XML Namespaces 1253 All YANG definitions are specified within a module that is bound to a 1254 particular XML Namespace [XML-NAMES], which is a globally unique URI 1255 [RFC3986]. A NETCONF client or server uses the namespace during XML 1256 encoding of data. 1258 Namespaces for modules published in RFC streams [RFC4844] MUST be 1259 assigned by IANA, see Section 14. 1261 Namespaces for private modules are assigned by the organization 1262 owning the module without a central registry. Namespace URIs MUST be 1263 chosen so they cannot collide with standard or other enterprise 1264 namespaces, for example by using the enterprise or organization name 1265 in the namespace. 1267 The "namespace" statement is covered in Section 7.1.3. 1269 5.3.1. YANG XML Namespace 1271 YANG defines an XML namespace for NETCONF operations 1272 and content. The name of this namespace is 1273 "urn:ietf:params:xml:ns:yang:1". 1275 5.4. Resolving Grouping, Type, and Identity Names 1277 Grouping, type, and identity names are resolved in the context in 1278 which they are defined, rather than the context in which they are 1279 used. Users of groupings, typedefs, and identities are not required 1280 to import modules or include submodules to satisfy all references 1281 made by the original definition. This behaves like static scoping in 1282 a conventional programming language. 1284 For example, if a module defines a grouping in which a type is 1285 referenced, when the grouping is used in a second module, the type is 1286 resolved in the context of the original module, not the second 1287 module. There is no worry over conflicts if both modules define the 1288 type, since there is no ambiguity. 1290 5.5. Nested Typedefs and Groupings 1292 Typedefs and groupings may appear nested under many YANG statements, 1293 allowing these to be lexically scoped by the hierarchy under which 1294 they appear. This allows types and groupings to be defined near 1295 where they are used, rather than placing them at the top level of the 1296 hierarchy. The close proximity increases readability. 1298 Scoping also allows types to be defined without concern for naming 1299 conflicts between types in different submodules. Type names can be 1300 specified without adding leading strings designed to prevent name 1301 collisions within large modules. 1303 Finally, scoping allows the module author to keep types and groupings 1304 private to their module or submodule, preventing their reuse. Since 1305 only top-level types and groupings (i.e., those appearing as 1306 substatements to a module or submodule statement) can be used outside 1307 the module or submodule, the developer has more control over what 1308 pieces of their module are presented to the outside world, supporting 1309 the need to hide internal information and maintaining a boundary 1310 between what is shared with the outside world and what is kept 1311 private. 1313 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1314 type or grouping cannot be defined if a higher level in the schema 1315 hierarchy has a definition with a matching identifier. 1317 A reference to an unprefixed type or grouping, or one which uses the 1318 prefix of the current module, is resolved by locating the closest 1319 matching "typedef" or "grouping" statement among the immediate 1320 substatements of each ancestor statement. 1322 5.6. Conformance 1324 Conformance is a measure of how accurately a device follows the 1325 model. Generally speaking, devices are responsible for implementing 1326 the model faithfully, allowing applications to treat devices which 1327 implement the model identically. Deviations from the model can 1328 reduce the utility of the model and increase fragility of 1329 applications that use it. 1331 YANG modelers have three mechanisms for conformance: 1333 o the basic behavior of the model 1335 o optional features that are part of the model 1337 o deviations from the model 1339 We will consider each of these in sequence. 1341 5.6.1. Basic Behavior 1343 The model defines a contract between the NETCONF client and server, 1344 which allows both parties to have faith the other knows the syntax 1345 and semantics behind the modeled data. The strength of YANG lies in 1346 the strength of this contract. 1348 5.6.2. Optional Features 1350 In many models, the modeler will allow sections of the model to be 1351 conditional. The device controls whether these conditional portions 1352 of the model are supported or valid for that particular device. 1354 For example, a syslog data model may choose to include the ability to 1355 save logs locally, but the modeler will realize that this is only 1356 possible if the device has local storage. If there is no local 1357 storage, an application should not tell the device to save logs. 1359 YANG supports this conditional mechanism using a construct called 1360 "feature". Features give the modeler a mechanism for making portions 1361 of the module conditional in a manner that is controlled by the 1362 device. The model can express constructs which are not universally 1363 present in all devices. These features are included in the model 1364 definition, allowing a consistent view and allowing applications to 1365 learn which features are supported and tailor their behavior to the 1366 device. 1368 A module may declare any number of features, identified by simple 1369 strings, and may make portions of the module optional based on those 1370 features. If the device supports a feature, then the corresponding 1371 portions of the module are valid for that device. If the device 1372 doesn't support the feature, those parts of the module are not valid, 1373 and applications should behave accordingly. 1375 Features are defined using the "feature" statement. Definitions in 1376 the module that are conditional to the feature are noted by the 1377 "if-feature" statement with the name of the feature as its argument. 1379 Further details are available in Section 7.18.1. 1381 5.6.3. Deviations 1383 In an ideal world, all devices would be required to implement the 1384 model exactly as defined, and deviations from the model would not be 1385 allowed. But in the real world, devices are often not able or 1386 designed to implement the model as written. For YANG-based 1387 automation to deal with these device deviations, a mechanism must 1388 exist for devices to inform applications of the specifics of such 1389 deviations. 1391 For example, a BGP module may allow any number of BGP peers, but a 1392 particular device may only support 16 BGP peers. Any application 1393 configuring the 17th peer will receive an error. While an error may 1394 suffice to let the application know it cannot add another peer, it 1395 would be far better if the application had prior knowledge of this 1396 limitation and could prevent the user from starting down the path 1397 that could not succeed. 1399 Device deviations are declared using the "deviation" statement, which 1400 takes as its argument a string which identifies a node in the schema 1401 tree. The contents of the statement details the manner in which the 1402 device implementation deviates from the contract as defined in the 1403 module. 1405 Further details are available in Section 7.18.3. 1407 5.6.4. Announcing Conformance Information in the Message 1409 The namespace URI MUST be advertised as a capability in the NETCONF 1410 message to indicate support for the YANG module by a NETCONF 1411 server. The capability URI advertised MUST be on the form: 1413 capability-string = namespace-uri [ parameter-list ] 1414 parameter-list = "?" parameter *( "&" parameter ) 1415 parameter = revision-parameter / 1416 module-parameter / 1417 feature-parameter / 1418 deviation-parameter 1419 revision-parameter = "revision=" revision-date 1420 module-parameter = "module=" module-name 1421 feature-parameter = "features=" feature *( "," feature ) 1422 deviation-parameter = "deviations=" deviation *( "," deviation ) 1424 Where "revision-date" is the revision of the module (see 1425 Section 7.1.9) that the NETCONF server implements, "module-name" is 1426 the name of module as it appears in the "module" statement (see 1427 Section 7.1), "namespace-uri" is the namespace URI for the module as 1428 it appears in the "namespace" statement (see Section 7.1.3), 1429 "feature" is the name of an optional feature implemented by the 1430 device (see Section 7.18.1), and "deviation" is the name of a module 1431 defining device deviations (see Section 7.18.3). 1433 In the parameter list, each named parameter MUST occur at most once. 1435 5.6.4.1. Modules 1437 Servers indicate the names of supported modules via the 1438 message. Module namespaces are encoded as the base URI in the 1439 capability string, and the module name is encoded as the "module" 1440 parameter to the base URI. 1442 A server MUST advertise all revisions of all modules it implements. 1444 For example, this message advertises one module "syslog". 1446 1447 1448 http://example.com/syslog?module=syslog&revision=2008-04-01 1449 1450 1452 5.6.4.2. Features 1454 Servers indicate the names of supported features via the 1455 message. In hello messages, the features are encoded in the 1456 "features" parameter within the URI. The value of this parameter is 1457 a comma-separated list of feature names which the device supports for 1458 the specific module. 1460 For example, this message advertises one module, informing 1461 the client that it supports the "local-storage" feature of module 1462 "syslog". 1464 1465 1466 http://example.com/syslog?module=syslog&features=local-storage 1467 1468 1470 5.6.4.3. Deviations 1472 Device deviations are announced via the "deviations" parameter. The 1473 value of the deviations parameter is a comma-separated list of 1474 modules containing deviations from the capability's module. 1476 For example, this message advertises two modules, informing 1477 the client that it deviates from module "syslog" according to the 1478 deviations listed in the module "my-devs". 1480 1481 1482 http://example.com/syslog?module=syslog&deviations=my-devs 1483 1484 1485 http://example.com/my-deviations?module=my-devs 1486 1487 1489 5.7. Data Store Modification 1491 Data models may allow the server to alter the configuration data 1492 store in ways not explicitly directed via NETCONF protocol messages. 1493 For example, a data model may define leafs that are assigned system- 1494 generated values when the client does not provide one. A formal 1495 mechanism for specifying the circumstances where these changes are 1496 allowed is out of scope for this specification. 1498 6. YANG syntax 1500 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1501 languages like C and C++. This C-like syntax was chosen specifically 1502 for its readability, since YANG values the time and effort of the 1503 readers of models above those of modules writers and YANG tool-chain 1504 developers. This section introduces the YANG syntax. 1506 YANG modules use the UTF-8 [RFC3629] character encoding. 1508 6.1. Lexical Tokenization 1510 YANG modules are parsed as a series of tokens. This section details 1511 the rules for recognizing tokens from an input stream. YANG 1512 tokenization rules are both simple and powerful. The simplicity is 1513 driven by a need to keep the parsers easy to implement, while the 1514 power is driven by the fact that modelers need to express their 1515 models in readable formats. 1517 6.1.1. Comments 1519 Comments are C++ style. A single line comment starts with "//" and 1520 ends at the end of the line. A block comment is enclosed within "/*" 1521 and "*/". 1523 6.1.2. Tokens 1525 A token in YANG is either a keyword, a string, ";", "{", or "}". A 1526 string can be quoted or unquoted. A keyword is either one of the 1527 YANG keywords defined in this document, or a prefix identifier, 1528 followed by ":", followed by a language extension keyword. Keywords 1529 are case sensitive. See Section 6.2 for a formal definition of 1530 identifiers. 1532 6.1.3. Quoting 1534 If a string contains any space or tab characters, a semicolon (";"), 1535 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1536 it MUST be enclosed within double or single quotes. 1538 If the double quoted string contains a line break followed by space 1539 or tab characters which are used to indent the text according to the 1540 layout in the YANG file, this leading whitespace is stripped from the 1541 string, up to and including the column of the double quote character, 1542 or to the first non-whitespace character, whichever occurs first. In 1543 this process, a tab character is treated as 8 space characters. 1545 If the double quoted string contains space or tab characters before a 1546 line break, this trailing whitespace is stripped from the string. 1548 A single quoted string (enclosed within ' ') preserves each character 1549 within the quotes. A single quote character cannot occur in a single 1550 quoted string, even when preceded by a backslash. 1552 Within a double quoted string (enclosed within " "), a backslash 1553 character introduces a special character, which depends on the 1554 character that immediately follows the backslash: 1556 \n new line 1557 \t a tab character 1558 \" a double quote 1559 \\ a single backslash 1561 If a quoted string is followed by a plus character ("+"), followed by 1562 another quoted string, the two strings are concatenated into one 1563 string, allowing multiple concatenations to build one string. 1564 Whitespace trimming and substition of backslash-escaped characters in 1565 double quoted strings is done before concatenation. 1567 6.1.3.1. Quoting Examples 1569 The following strings are equivalent: 1571 hello 1572 "hello" 1573 'hello' 1574 "hel" + "lo" 1575 'hel' + "lo" 1577 The following examples show some special strings: 1579 "\"" - string containing a double quote 1580 '"' - string containing a double quote 1581 "\n" - string containing a newline character 1582 '\n' - string containing a backslash followed 1583 by the character n 1585 The following examples show some illegal strings: 1587 '''' - a single-quoted string cannot contain single quotes 1588 """ - a double quote must be escaped in a double quoted string 1590 The following strings are equivalent: 1592 "first line 1593 second line" 1595 "first line\n" + " second line" 1597 6.2. Identifiers 1599 Identifiers are used to identify different kinds of YANG items by 1600 name. Each identifier starts with an upper-case or lower-case ASCII 1601 letter or an underscore character, followed by zero or more ASCII 1602 letters, digits, underscore characters, hyphens, and dots. 1603 Implementations MUST support identifiers up to 64 characters in 1604 length. Identifiers are case sensitive. The identifier syntax is 1605 formally defined by the rule "identifier" in Section 12. Identifiers 1606 can be specified as quoted or unquoted strings. 1608 6.2.1. Identifiers and their namespaces 1610 Each identifier is valid in a namespace which depends on the type of 1611 the YANG item being defined. All identifiers defined in a namespace 1612 MUST be unique. 1614 o All module and submodule names share the same global module 1615 identifier namespace. 1617 o All extension names defined in a module and its submodules share 1618 the same extension identifier namespace. 1620 o All feature names defined in a module and its submodules share the 1621 same feature identifier namespace. 1623 o All identity names defined in a module and its submodules share 1624 the same identity identifier namespace. 1626 o All derived type names defined within a parent node or at the top- 1627 level of the module or its submodules share the same type 1628 identifier namespace. This namespace is scoped to all descendant 1629 nodes of the parent node or module. This means that any 1630 descendent node may use that typedef, and it MUST NOT define a 1631 typedef with the same name. 1633 o All grouping names defined within a parent node or at the top- 1634 level of the module or its submodules share the same grouping 1635 identifier namespace. This namespace is scoped to all descendant 1636 nodes of the parent node or module. This means that any 1637 descendent node may use that grouping, and it MUST NOT define a 1638 grouping with the same name. 1640 o All leafs, leaf-lists, lists, containers, choices, rpcs, 1641 notifications, and anyxmls defined (directly or through a uses 1642 statement) within a parent node or at the top-level of the module 1643 or its submodules share the same identifier namespace. This 1644 namespace is scoped to the parent node or module, unless the 1645 parent node is a case node. In that case, the namespace is scoped 1646 to the closest ancestor node which is not a case or choice node. 1648 o All cases within a choice share the same case identifier 1649 namespace. This namespace is scoped to the parent choice node. 1651 Forward references are allowed in YANG. 1653 6.3. Statements 1655 A YANG module contains a sequence of statements. Each statement 1656 starts with a keyword, followed by zero or one argument, followed 1657 either by a semicolon (";") or a block of substatements enclosed 1658 within braces ("{ }"): 1660 statement = keyword [argument] (";" / "{" *statement "}") 1662 The argument is a string, as defined in Section 6.1.2. 1664 6.3.1. Language Extensions 1666 A module can introduce YANG extensions by using the "extension" 1667 keyword (see Section 7.17). The extensions can be imported by other 1668 modules with the "import" statement (see Section 7.1.5). When an 1669 imported extension is used, the extension's keyword MUST be qualified 1670 using the prefix with which the extension's module was imported. If 1671 an extension is used in the module where it is defined, the 1672 extension's keyword MUST be qualified with the module's prefix. 1674 Since submodules cannot include the parent module, any extensions in 1675 the module which need to be exposed to submodules MUST be defined in 1676 a submodule. Submodules can then include this submodule to find the 1677 definition of the extension. 1679 If a YANG compiler does not support a particular extension, which 1680 appears in a YANG module as an unknown-statement (see Section 12), 1681 the entire unknown statement MAY be ignored by the compiler. 1683 6.4. XPath Evaluations 1685 YANG relies on XPath 1.0 [XPATH] as a notation for specifying many 1686 inter-node references and dependencies. NETCONF clients and servers 1687 are not required to implement an XPath interpreter, but MUST ensure 1688 that the requirements encoded in the data model are enforced. The 1689 manner of enforcement is an implementation decision. The XPath 1690 expressions MUST be syntactically correct, and all prefixes used MUST 1691 be present in the XPath context (see Section 6.4.1). An 1692 implementation may choose to implement them by hand, rather than 1693 using the XPath expression directly. 1695 The data model used in the XPath expressions is the same as that used 1696 in XPath 1.0 [XPATH], with the same extension for root node children 1697 as used by XSLT 1.0 [XSLT] (section 3.1). Specifically, it means 1698 that the root node may have any number of element nodes as its 1699 children. 1701 6.4.1. XPath Context 1703 All YANG XPath expressions share the following XPath context 1704 definition: 1706 o The set of namespace declarations is the set of all "import" 1707 statements' prefix and namespace pairs in the module where the 1708 XPath expression is specified, and the "prefix" statement's prefix 1709 for the "namespace" statement's URI. 1711 o Names without a namespace prefix belong to the same namespace as 1712 the identifier of the current node. Inside a grouping, that 1713 namespace is affected by where the grouping is used (see 1714 Section 7.12). 1716 o The function library is the core function library defined in 1717 [XPATH], and a function "current()" which returns a node set with 1718 the initial context node. 1720 o The set of variable bindings is empty. 1722 The mechanism for handling unprefixed names is adopted from XPath 2.0 1723 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1724 ambiguity may ever arise because YANG node identifiers are always 1725 qualified names with a non-null namespace URI. 1727 The context node varies with the YANG XPath expression, and is 1728 specified where the YANG statement with the XPath expression is 1729 defined. 1731 6.5. Schema Node Identifier 1733 A schema node identifier is a string that identifies a node in the 1734 schema tree. It has two forms, "absolute" and "descendant", defined 1735 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1736 in Section 12, respectively. A schema node identifier consists of a 1737 path of identifiers, separated by slashes ("/"). In an absolute 1738 schema node identifier, the first identifier after the leading slash 1739 is any top-level schema node in local module or all imported modules. 1741 References to identifiers defined in external modules MUST be 1742 qualified with appropriate prefixes, and references to identifiers 1743 defined in the current module and its submodules MAY use a prefix. 1745 For example, to identify the child node "b" of top-level node "a", 1746 the string "/a/b" can be used. 1748 7. YANG Statements 1750 The following sections describe all of the YANG statements. 1752 Note that even a statement which does not have any substatements 1753 defined in YANG can have vendor-specific extensions as substatements. 1754 For example, the "description" statement does not have any 1755 substatements defined in YANG, but the following is legal: 1757 description "some text" { 1758 acme:documentation-flag 5; 1759 } 1761 7.1. The module Statement 1763 The "module" statement defines the module's name, and groups all 1764 statements which belong to the module together. The "module" 1765 statement's argument is the name of the module, followed by a block 1766 of substatements that hold detailed module information. The module 1767 name follows the rules for identifiers in Section 6.2. 1769 Names of modules published in RFC streams [RFC4844] MUST be assigned 1770 by IANA, see Section 14. 1772 Private module names are assigned by the organization owning the 1773 module without a central registry. It is RECOMMENDED to choose 1774 module names that will have a low probability of colliding with 1775 standard or other enterprise modules and submodules, e.g., by using 1776 the enterprise or organization name as a prefix for the module name. 1778 A module typically has the following layout: 1780 module { 1782 // header information 1783 1784 1785 1787 // linkage statements 1788 1789 1791 // meta information 1792 1793 1794 1795 1797 // revision history 1798 1800 // module definitions 1801 1802 } 1804 7.1.1. The module's Substatements 1805 +--------------+---------+-------------+ 1806 | substatement | section | cardinality | 1807 +--------------+---------+-------------+ 1808 | anyxml | 7.10 | 0..n | 1809 | augment | 7.15 | 0..n | 1810 | choice | 7.9 | 0..n | 1811 | contact | 7.1.8 | 0..1 | 1812 | container | 7.5 | 0..n | 1813 | description | 7.19.3 | 0..1 | 1814 | deviation | 7.18.3 | 0..n | 1815 | extension | 7.17 | 0..n | 1816 | feature | 7.18.1 | 0..n | 1817 | grouping | 7.11 | 0..n | 1818 | identity | 7.16 | 0..n | 1819 | import | 7.1.5 | 0..n | 1820 | include | 7.1.6 | 0..n | 1821 | leaf | 7.6 | 0..n | 1822 | leaf-list | 7.7 | 0..n | 1823 | list | 7.8 | 0..n | 1824 | namespace | 7.1.3 | 1 | 1825 | notification | 7.14 | 0..n | 1826 | organization | 7.1.7 | 0..1 | 1827 | prefix | 7.1.4 | 1 | 1828 | reference | 7.19.4 | 0..1 | 1829 | revision | 7.1.9 | 0..n | 1830 | rpc | 7.13 | 0..n | 1831 | typedef | 7.3 | 0..n | 1832 | uses | 7.12 | 0..n | 1833 | yang-version | 7.1.2 | 0..1 | 1834 +--------------+---------+-------------+ 1836 7.1.2. The yang-version Statement 1838 The optional "yang-version" statement specifies which version of the 1839 YANG language was used in developing the module. The statement's 1840 argument is a string. If present, it MUST contain the value "1", 1841 which is the current YANG version and the default value. 1843 Handling of the "yang-version" statement for versions other than "1" 1844 (the version defined here) is out of scope for this specification. 1845 Any document that defines a higher version will need to define the 1846 backward compatibility of such a higher version. 1848 7.1.3. The namespace Statement 1850 The "namespace" statement defines the XML namespace which all 1851 identifiers defined by the module are qualified by, with the 1852 exception of data node identifiers defined inside a grouping (see 1853 Section 7.12 for details). The argument to the "namespace" statement 1854 is the URI of the namespace. 1856 See also Section 5.3. 1858 7.1.4. The prefix Statement 1860 The "prefix" statement is used to define the prefix associated with 1861 the module and its namespace. The "prefix" statement's argument is 1862 the prefix string which is used as a prefix to access a module. The 1863 prefix string MAY be used to refer to definitions contained in the 1864 module, e.g., "if:ifName". A prefix follows the same rules as an 1865 identifier (see Section 6.2). 1867 When used inside the "module" statement, the "prefix" statement 1868 defines the prefix to be used when this module is imported. To 1869 improve readability of the NETCONF XML, a NETCONF client or server 1870 which generates XML or XPath that use prefixes SHOULD use the prefix 1871 defined by the module, unless there is a conflict. 1873 When used inside the "import" statement, the "prefix" statement 1874 defines the prefix to be used when accessing definitions inside the 1875 imported module. When a reference to an identifier from the imported 1876 module is used, the prefix string for the imported module is used in 1877 combination with a colon (":") and the identifier, e.g., "if: 1878 ifIndex". To improve readability of YANG modules, the prefix defined 1879 by a module SHOULD be used when the module is imported, unless there 1880 is a conflict. If there is a conflict, i.e., two different modules 1881 which both have defined the same prefix are imported, at least one of 1882 them MUST be imported with a different prefix. 1884 All prefixes, including the prefix for the module itself MUST be 1885 unique within the module or submodule. 1887 7.1.5. The import Statement 1889 The "import" statement makes definitions from one module available 1890 inside another module or submodule. The argument is the name of the 1891 module to import, and the statement is followed by a block of 1892 substatements that holds detailed import information. When a module 1893 is imported, the importing module may: 1895 o use any grouping and typedef defined at the top-level in the 1896 imported module or its submodules 1898 o use any extension, feature, and identity defined in the imported 1899 module or its submodules 1901 o use any node in the imported module's schema tree in "must", 1902 "path", and "when" statements, or as the target node in an 1903 "augment" statement 1905 The mandatory "prefix" substatement assigns a prefix for the imported 1906 module which is scoped to the importing module or submodule. 1907 Multiple "import" statements may be specified to import from 1908 different modules. 1910 When the optional "revision-date" substatement is present, any 1911 typedef, grouping, extension, feature, and identity referenced by 1912 definitions in the local module are taken from the specified revision 1913 of the imported module. It is an error if the specified revision of 1914 the imported module does not exist. If no "revision-date" 1915 substatement is present, it is undefined from which revision of the 1916 module they are taken. 1918 Multiple revisions of the same module MUST NOT be imported. 1920 The import's Substatements 1922 +---------------+---------+-------------+ 1923 | substatement | section | cardinality | 1924 +---------------+---------+-------------+ 1925 | prefix | 7.1.4 | 1 | 1926 | revision-date | 7.1.5.1 | 0..1 | 1927 +---------------+---------+-------------+ 1929 7.1.5.1. The import's revision-date Statement 1931 The import's "revision-date" statement is used to specify the exact 1932 version of the module to import. The "revision-date" statement MUST 1933 match the most recent "revision" statement in the imported module. 1935 7.1.6. The include Statement 1937 The "include" statement is used to make content from a submodule 1938 available to that submodule's parent module, or to another submodule 1939 of that parent module. The argument is an identifier which is the 1940 name of the submodule to include. Modules are only allowed to 1941 include submodules that belong to that module, as defined by the 1942 "belongs-to" statement (see Section 7.2.2). Submodules are only 1943 allowed to include other submodules belonging to the same module. 1945 When a module includes a submodule, it incorporates the contents of 1946 the submodule into the node hierarchy of the module. When a 1947 submodule includes another submodule, the target submodule's 1948 definitions are made available to the current submodule. 1950 When the optional "revision-date" substatement is present, the 1951 specified revision of the submodule is included in the module. It is 1952 an error if the specified revision of the submodule does not exist. 1953 If no "revision-date" substatement is present, it is undefined which 1954 revision of the submodule is included. 1956 Multiple revisions of the same submodule MUST NOT be included. 1958 The includes's Substatements 1960 +---------------+---------+-------------+ 1961 | substatement | section | cardinality | 1962 +---------------+---------+-------------+ 1963 | revision-date | 7.1.5.1 | 0..1 | 1964 +---------------+---------+-------------+ 1966 7.1.7. The organization Statement 1968 The "organization" statement defines the party responsible for this 1969 module. The argument is a string which is used to specify a textual 1970 description of the organization(s) under whose auspices this module 1971 was developed. 1973 7.1.8. The contact Statement 1975 The "contact" statement provides contact information for the module. 1976 The argument is a string which is used to specify contact information 1977 for the person or persons to whom technical queries concerning this 1978 module should be sent, such as their name, postal address, telephone 1979 number, and electronic mail address. 1981 7.1.9. The revision Statement 1983 The "revision" statement specifies the editorial revision history of 1984 the module, including the initial revision. A series of revision 1985 statements detail the changes in the module's definition. The 1986 argument is a date string in the format "YYYY-MM-DD", followed by a 1987 block of substatements that holds detailed revision information. A 1988 module SHOULD have at least one initial "revision" statement. For 1989 every published editorial change, a new one SHOULD be added in front 1990 of the revisions sequence, so that all revisions are in reverse 1991 chronological order. 1993 7.1.9.1. The revision's Substatement 1995 +--------------+---------+-------------+ 1996 | substatement | section | cardinality | 1997 +--------------+---------+-------------+ 1998 | description | 7.19.3 | 0..1 | 1999 | reference | 7.19.4 | 0..1 | 2000 +--------------+---------+-------------+ 2002 7.1.10. Usage Example 2004 module acme-system { 2005 namespace "http://acme.example.com/system"; 2006 prefix "acme"; 2008 import ietf-yang-types { 2009 prefix "yang"; 2010 } 2012 include acme-types; 2014 organization "ACME Inc."; 2015 contact 2016 "Joe L. User 2018 ACME, Inc. 2019 42 Anywhere Drive 2020 Nowhere, CA 95134 2021 USA 2023 Phone: +1 800 555 0100 2024 EMail: joe@acme.example.com"; 2026 description 2027 "The module for entities implementing the ACME protocol."; 2029 revision "2007-06-09" { 2030 description "Initial revision."; 2031 } 2033 // definitions follow... 2034 } 2036 7.2. The submodule Statement 2038 While the primary unit in YANG is a module, a YANG module can itself 2039 be constructed out of several submodules. Submodules allow a module 2040 designer to split a complex model into several pieces where all the 2041 submodules contribute to a single namespace, which is defined by the 2042 module that includes the submodules. 2044 The "submodule" statement defines the submodule's name, and groups 2045 all statements which belong to the submodule together. The 2046 "submodule" statement's argument is the name of the submodule, 2047 followed by a block of substatements that hold detailed submodule 2048 information. The submodule name follows the rules for identifiers in 2049 Section 6.2. 2051 Names of submodules published in RFC streams [RFC4844] MUST be 2052 assigned by IANA, see Section 14. 2054 Private submodule names are assigned by the organization owning the 2055 submodule without a central registry. It is RECOMMENDED to choose 2056 submodule names that will have a low probability of colliding with 2057 standard or other enterprise modules and submodules, e.g., by using 2058 the enterprise or organization name as a prefix for the submodule 2059 name. 2061 A submodule typically has the following layout: 2063 submodule { 2065 2067 // module identification 2068 2070 // linkage statements 2071 2072 2074 // meta information 2075 2076 2077 2078 2080 // revision history 2081 2083 // module definitions 2084 2085 } 2087 7.2.1. The submodule's Substatements 2089 +--------------+---------+-------------+ 2090 | substatement | section | cardinality | 2091 +--------------+---------+-------------+ 2092 | anyxml | 7.10 | 0..n | 2093 | augment | 7.15 | 0..n | 2094 | belongs-to | 7.2.2 | 1 | 2095 | choice | 7.9 | 0..n | 2096 | contact | 7.1.8 | 0..1 | 2097 | container | 7.5 | 0..n | 2098 | description | 7.19.3 | 0..1 | 2099 | deviation | 7.18.3 | 0..n | 2100 | extension | 7.17 | 0..n | 2101 | feature | 7.18.1 | 0..n | 2102 | grouping | 7.11 | 0..n | 2103 | identity | 7.16 | 0..n | 2104 | import | 7.1.5 | 0..n | 2105 | include | 7.1.6 | 0..n | 2106 | leaf | 7.6 | 0..n | 2107 | leaf-list | 7.7 | 0..n | 2108 | list | 7.8 | 0..n | 2109 | notification | 7.14 | 0..n | 2110 | organization | 7.1.7 | 0..1 | 2111 | reference | 7.19.4 | 0..1 | 2112 | revision | 7.1.9 | 0..n | 2113 | rpc | 7.13 | 0..n | 2114 | typedef | 7.3 | 0..n | 2115 | uses | 7.12 | 0..n | 2116 | yang-version | 7.1.2 | 0..1 | 2117 +--------------+---------+-------------+ 2119 7.2.2. The belongs-to Statement 2121 The "belongs-to" statement specifies the module to which the 2122 submodule belongs. The argument is an identifier which is the name 2123 of the module. 2125 A submodule MUST only be included by the module to which it belongs, 2126 or by another submodule which belongs to that module. 2128 The mandatory "prefix" substatement assigns a prefix for the module 2129 to which the submodule belongs. All definitions in the local 2130 submodule and any included submodules can be accessed by using the 2131 prefix. 2133 The belongs-to's Substatements 2135 +--------------+---------+-------------+ 2136 | substatement | section | cardinality | 2137 +--------------+---------+-------------+ 2138 | prefix | 7.1.4 | 1 | 2139 +--------------+---------+-------------+ 2141 7.2.3. Usage Example 2143 submodule acme-types { 2145 belongs-to "acme-system" { 2146 prefix "acme"; 2147 } 2149 import ietf-yang-types { 2150 prefix "yang"; 2151 } 2153 organization "ACME Inc."; 2154 contact 2155 "Joe L. User 2157 ACME, Inc. 2158 42 Anywhere Drive 2159 Nowhere, CA 95134 2160 USA 2162 Phone: +1 800 555 0100 2163 EMail: joe@acme.example.com"; 2165 description 2166 "This submodule defines common ACME types."; 2168 revision "2007-06-09" { 2169 description "Initial revision."; 2170 } 2172 // definitions follows... 2173 } 2175 7.3. The typedef Statement 2177 The "typedef" statement defines a new type which may be used locally 2178 in the module, in modules or submodules which include it, and by 2179 other modules which import from it, according to the rules in 2180 Section 5.5. The new type is called the "derived type", and the type 2181 from which it was derived is called the "base type". All derived 2182 types can be traced back to a YANG built-in type. 2184 The "typedef" statement's argument is an identifier which is the name 2185 of the type to be defined, and MUST be followed by a block of 2186 substatements that holds detailed typedef information. 2188 The name of the type MUST NOT be one of the YANG built-in types. If 2189 the typedef is defined at the top level of a YANG module or 2190 submodule, the name of the type to be defined MUST be unique within 2191 the module. 2193 7.3.1. The typedef's Substatements 2195 +--------------+---------+-------------+ 2196 | substatement | section | cardinality | 2197 +--------------+---------+-------------+ 2198 | default | 7.3.4 | 0..1 | 2199 | description | 7.19.3 | 0..1 | 2200 | reference | 7.19.4 | 0..1 | 2201 | status | 7.19.2 | 0..1 | 2202 | type | 7.3.2 | 1 | 2203 | units | 7.3.3 | 0..1 | 2204 +--------------+---------+-------------+ 2206 7.3.2. The typedef's type Statement 2208 The "type" statement, which MUST be present, defines the base type 2209 from which this type is derived. See Section 7.4 for details. 2211 7.3.3. The units Statement 2213 The "units" statement, which is optional, takes as an argument a 2214 string which contains a textual definition of the units associated 2215 with the type. 2217 7.3.4. The typedef's default Statement 2219 The "default" statement takes as an argument a string which contains 2220 a default value for the new type. 2222 The value of the "default" statement MUST be valid according to the 2223 type specified in the "type" statement. 2225 If the base type has a default value, and the new derived type does 2226 not specify a new default value, the base type's default value is 2227 also the default value of the new derived type. 2229 If the type's default value is not valid according to the new 2230 restrictions specified in a derived type or leaf definition, the 2231 derived type or leaf definition MUST specify a new default value 2232 compatible with the restrictions. 2234 7.3.5. Usage Example 2236 typedef listen-ipv4-address { 2237 type inet:ipv4-address; 2238 default "0.0.0.0"; 2239 } 2241 7.4. The type Statement 2243 The "type" statement takes as an argument a string which is the name 2244 of a YANG built-in type (see Section 9) or a derived type (see 2245 Section 7.3), followed by an optional block of substatements that are 2246 used to put further restrictions on the type. 2248 The restrictions that can be applied depend on the type being 2249 restricted. The restriction statements for all built-in types are 2250 described in the subsections of Section 9. 2252 7.4.1. The type's Substatements 2254 +------------------+---------+-------------+ 2255 | substatement | section | cardinality | 2256 +------------------+---------+-------------+ 2257 | bit | 9.7.4 | 0..n | 2258 | enum | 9.6.4 | 0..n | 2259 | length | 9.4.4 | 0..1 | 2260 | path | 9.9.2 | 0..1 | 2261 | pattern | 9.4.6 | 0..n | 2262 | range | 9.2.4 | 0..1 | 2263 | require-instance | 9.13.2 | 0..1 | 2264 | type | 7.4 | 0..n | 2265 +------------------+---------+-------------+ 2267 7.5. The container Statement 2269 The "container" statement is used to define an interior data node in 2270 the schema tree. It takes one argument, which is an identifier, 2271 followed by a block of substatements that holds detailed container 2272 information. 2274 A container node does not have a value, but it has a list of child 2275 nodes in the data tree. The child nodes are defined in the 2276 container's substatements. 2278 7.5.1. Containers with Presence 2280 YANG supports two styles of containers, those which exist only for 2281 organizing the hierarchy of data nodes, and those whose presence in 2282 the configuration has an explicit meaning. 2284 In the first style, the container has no meaning of its own, existing 2285 only to contain child nodes. This is the default style. 2287 For example, the set of scrambling options for SONET interfaces may 2288 be placed inside a "scrambling" container to enhance the organization 2289 of the configuration hierarchy, and to keep these nodes together. 2290 The "scrambling" node itself has no meaning, so removing the node 2291 when it becomes empty relieves the user from performing this task. 2293 In the second style, the presence of the container itself is 2294 configuration data, representing a single bit of configuration data. 2295 The container acts as both a configuration knob and a means of 2296 organizing related configuration. These containers are explicitly 2297 created and deleted. 2299 YANG calls this style a "presence container" and it is indicated 2300 using the "presence" statement, which takes as its argument a text 2301 string indicating what the presence of the node means. 2303 For example, an "ssh" container may turn on the ability to log into 2304 the device using ssh, but can also contain any ssh-related 2305 configuration knobs, such as connection rates or retry limits. 2307 The "presence" statement (see Section 7.5.5) is used to give 2308 semantics to the existence of the container in the data tree. 2310 7.5.2. The container's Substatements 2312 +--------------+---------+-------------+ 2313 | substatement | section | cardinality | 2314 +--------------+---------+-------------+ 2315 | anyxml | 7.10 | 0..n | 2316 | choice | 7.9 | 0..n | 2317 | config | 7.19.1 | 0..1 | 2318 | container | 7.5 | 0..n | 2319 | description | 7.19.3 | 0..1 | 2320 | grouping | 7.11 | 0..n | 2321 | if-feature | 7.18.2 | 0..n | 2322 | leaf | 7.6 | 0..n | 2323 | leaf-list | 7.7 | 0..n | 2324 | list | 7.8 | 0..n | 2325 | must | 7.5.3 | 0..n | 2326 | presence | 7.5.5 | 0..1 | 2327 | reference | 7.19.4 | 0..1 | 2328 | status | 7.19.2 | 0..1 | 2329 | typedef | 7.3 | 0..n | 2330 | uses | 7.12 | 0..n | 2331 | when | 7.19.5 | 0..1 | 2332 +--------------+---------+-------------+ 2334 7.5.3. The must Statement 2336 The "must" statement, which is optional, takes as an argument a 2337 string which contains an XPath expression (see Section 6.4). It is 2338 used to formally declare a constraint on valid data. The constraint 2339 is enforced according to the rules in Section 8. 2341 When a datastore is validated, all "must" constraints are 2342 conceptually evaluated once for each data node in the data tree, and 2343 for all leafs with default values in use (see Section 7.6.1). If a 2344 data node does not exist in the data tree, and it does not have a 2345 default value, its "must" statements are not evaluated. 2347 All such constraints MUST evaluate to true for the data to be valid. 2349 The XPath expression is conceptually evaluated in the following 2350 context, in addition to the definition in Section 6.4.1: 2352 o The context node is the node in the data tree for which the "must" 2353 statement is defined. 2355 o The accessible tree is made up of all nodes in the data tree, and 2356 all leafs with default values in use (see Section 7.6.1). 2358 The accessible tree depends on the context node: 2360 o If the context node represents configuration, the tree is the data 2361 in the NETCONF datastore where the context node exists. The XPath 2362 root node has all top-level configuration data nodes in all 2363 modules as children. 2365 o If the context node represents state data, the tree is all state 2366 data on the device, and the datastore. The XPath root 2367 node has all top-level data nodes in all modules as children. 2369 o If the context node represents notification content, the tree is 2370 the notification XML instance document. The XPath root node has 2371 the element representing the notification being defined as the 2372 only child. 2374 o If the context node represents RPC input parameters, the tree is 2375 the RPC XML instance document. The XPath root node has the 2376 element representing the RPC operation being defined as the only 2377 child. 2379 o If the context node represents RPC output parameters, the tree is 2380 the RPC reply instance document. The XPath root node has the 2381 elements representing the RPC output parameters as children. 2383 The result of the XPath expression is converted to a boolean value 2384 using the standard XPath rules. 2386 Note that since all leaf values in the data tree are conceptually 2387 stored in their canonical form (see Section 7.6 and Section 7.7), any 2388 XPath comparisons are done on the canonical value. 2390 Also note that the XPath expression is conceptually evaluated. This 2391 means that an implementation does not have to use an XPath evaluator 2392 on the device. How the evaluation is done in practice is an 2393 implementation decision. 2395 7.5.4. The must's Substatements 2397 +---------------+---------+-------------+ 2398 | substatement | section | cardinality | 2399 +---------------+---------+-------------+ 2400 | description | 7.19.3 | 0..1 | 2401 | error-app-tag | 7.5.4.2 | 0..1 | 2402 | error-message | 7.5.4.1 | 0..1 | 2403 | reference | 7.19.4 | 0..1 | 2404 +---------------+---------+-------------+ 2406 7.5.4.1. The error-message Statement 2408 The "error-message" statement, which is optional, takes a string as 2409 an argument. If the constraint evaluates to false, the string is 2410 passed as in the . 2412 7.5.4.2. The error-app-tag Statement 2414 The "error-app-tag" statement, which is optional, takes a string as 2415 an argument. If the constraint evaluates to false, the string is 2416 passed as in the . 2418 7.5.4.3. Usage Example of must and error-message 2420 container interface { 2421 leaf ifType { 2422 type enumeration { 2423 enum ethernet; 2424 enum atm; 2425 } 2426 } 2427 leaf ifMTU { 2428 type uint32; 2429 } 2430 must "ifType != 'ethernet' or " + 2431 "(ifType = 'ethernet' and ifMTU = 1500)" { 2432 error-message "An ethernet MTU must be 1500"; 2433 } 2434 must "ifType != 'atm' or " + 2435 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2436 error-message "An atm MTU must be 64 .. 17966"; 2437 } 2438 } 2440 7.5.5. The presence Statement 2442 The "presence" statement assigns a meaning to the presence of a 2443 container in the data tree. It takes as an argument a string which 2444 contains a textual description of what the node's presence means. 2446 If a container has the "presence" statement, the container's 2447 existence in the data tree carries some meaning. Otherwise, the 2448 container is used to give some structure to the data, and it carries 2449 no meaning by itself. 2451 See Section 7.5.1 for additional information. 2453 7.5.6. The container's Child Node Statements 2455 Within a container, the "container", "leaf", "list", "leaf-list", 2456 "uses", "choice", and "anyxml" statements can be used to define child 2457 nodes to the container. 2459 7.5.7. XML Mapping Rules 2461 A container node is encoded as an XML element. The element's local 2462 name is the container's identifier, and its namespace is the module's 2463 XML namespace (see Section 7.1.3). 2465 The container's child nodes are encoded as subelements to the 2466 container element. If the container defines RPC input or output 2467 parameters, these subelements are encoded in the same order as they 2468 are defined within the container statement. Otherwise, the 2469 subelements are encoded in any order. 2471 A NETCONF server that replies to a or request MAY 2472 choose not to send a container element if the container node does not 2473 have the "presence" statement and no child nodes exist. Thus, a 2474 client that receives an for a or 2475 request, must be prepared to handle the case that a container node 2476 without a presence statement is not present in the XML. 2478 7.5.8. NETCONF Operations 2480 Containers can be created, deleted, replaced and modified through 2481 , by using the "operation" attribute (See [RFC4741], 2482 section 7.2) in the container's XML element. 2484 If a container does not have a "presence" statement and the last 2485 child node is deleted, the NETCONF server MAY delete the container. 2487 When a NETCONF server processes an request, the 2488 elements of procedure for the container node are: 2490 If the operation is "merge" or "replace", the node is created if 2491 it does not exist. 2493 If the operation is "create" the node is created if it does not 2494 exist. If the node already exists, a "data-exists" error is 2495 returned. 2497 If the operation is "delete" the node is deleted if it exists. If 2498 the node does not exist, a "data-missing" error is returned. 2500 7.5.9. Usage Example 2502 Given the following container definition: 2504 container system { 2505 description "Contains various system parameters"; 2506 container services { 2507 description "Configure externally available services"; 2508 container "ssh" { 2509 presence "Enables SSH"; 2510 description "SSH service specific configuration"; 2511 // more leafs, containers and stuff here... 2512 } 2513 } 2514 } 2516 A corresponding XML instance example: 2518 2519 2520 2521 2522 2524 Since the element is present, ssh is enabled. 2526 To delete a container with an : 2528 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2545 7.6. The leaf Statement 2547 The "leaf" statement is used to define a leaf node in the schema 2548 tree. It takes one argument, which is an identifier, followed by a 2549 block of substatements that holds detailed leaf information. 2551 A leaf node has a value, but no child nodes in the data tree. 2552 Conceptually, the value in the data tree is always in the canonical 2553 form (see Section 9.1). 2555 A leaf node exists in zero or one instances in the data tree, 2556 depending on the value of the "mandatory" statement. 2558 The "leaf" statement is used to define a scalar variable of a 2559 particular built-in or derived type. 2561 7.6.1. The leaf's default value 2563 The default value of a leaf is the value that the server uses if the 2564 leaf does not exist in the data tree. The usage of the default value 2565 depends on the leaf's closest ancestor node in the schema tree which 2566 is not a non-presence container: 2568 o If no such ancestor exists in the schema tree, the default value 2569 MUST be used. 2571 o Otherwise, if this ancestor is a case node, the default value MUST 2572 be used if any node from the case exists in the data tree, or if 2573 the case node is the choice's default case, and no nodes from any 2574 other case exist in the data tree. 2576 o Otherwise, the default value MUST be used if the ancestor node 2577 exists in the data tree. 2579 In these cases, the default value is said to be in use. 2581 When the default value is in use, the server MUST operationally 2582 behave as if the leaf was present in the data tree with the default 2583 value as its value. 2585 If a leaf has a "default" statement, the leaf's default value is the 2586 value of the "default" statement. Otherwise, if the leaf's type has 2587 a default value, and the leaf is not mandatory, then the leaf's 2588 default value is the type's default value. In all other cases, the 2589 leaf does not have a default value. 2591 7.6.2. The leaf's Substatements 2593 +--------------+---------+-------------+ 2594 | substatement | section | cardinality | 2595 +--------------+---------+-------------+ 2596 | config | 7.19.1 | 0..1 | 2597 | default | 7.6.4 | 0..1 | 2598 | description | 7.19.3 | 0..1 | 2599 | if-feature | 7.18.2 | 0..n | 2600 | mandatory | 7.6.5 | 0..1 | 2601 | must | 7.5.3 | 0..n | 2602 | reference | 7.19.4 | 0..1 | 2603 | status | 7.19.2 | 0..1 | 2604 | type | 7.6.3 | 1 | 2605 | units | 7.3.3 | 0..1 | 2606 | when | 7.19.5 | 0..1 | 2607 +--------------+---------+-------------+ 2609 7.6.3. The leaf's type Statement 2611 The "type" statement, which MUST be present, takes as an argument the 2612 name of an existing built-in or derived type. The optional 2613 substatements specify restrictions on this type. See Section 7.4 for 2614 details. 2616 7.6.4. The leaf's default Statement 2618 The "default" statement, which is optional, takes as an argument a 2619 string which contains a default value for the leaf. 2621 The value of the "default" statement MUST be valid according to the 2622 type specified in the leaf's "type" statement. 2624 The "default" statement MUST NOT be present on nodes where 2625 "mandatory" is true. 2627 7.6.5. The leaf's mandatory Statement 2629 The "mandatory" statement, which is optional, takes as an argument 2630 the string "true" or "false", and puts a constraint on valid data. 2631 If not specified, the default is "false". 2633 If "mandatory" is "true", the behavior of the constraint depends on 2634 the type of the leaf's closest ancestor node in the schema tree which 2635 is not a non-presence container (see Section 7.5.1): 2637 o If no such ancestor exists in the schema tree, the leaf MUST 2638 exist. 2640 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2641 any node from the case exists in the data tree. 2643 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2644 data tree. 2646 This constraint is enforced according to the rules in Section 8. 2648 7.6.6. XML Mapping Rules 2650 A leaf node is encoded as an XML element. The element's local name 2651 is the leaf's identifier, and its namespace is the module's XML 2652 namespace (see Section 7.1.3). 2654 The value of the leaf node is encoded to XML according to the type, 2655 and sent as character data in the element. 2657 A NETCONF server that replies to a or request MAY 2658 choose not to send the leaf element if its value is the default 2659 value. Thus, a client that receives an for a or 2660 request, MUST be prepared to handle the case that a leaf 2661 node with a default value is not present in the XML. In this case, 2662 the value used by the server is known to be the default value. 2664 See Section 7.6.8 for an example. 2666 7.6.7. NETCONF Operations 2668 When a NETCONF server processes an request, the 2669 elements of procedure for the leaf node are: 2671 If the operation is "merge" or "replace", the node is created if 2672 it does not exist, and its value is set to the value found in the 2673 XML RPC data. 2675 If the operation is "create" the node is created if it does not 2676 exist. If the node already exists, a "data-exists" error is 2677 returned. 2679 If the operation is "delete" the node is deleted if it exists. If 2680 the node does not exist, a "data-missing" error is returned. 2682 7.6.8. Usage Example 2684 Given the following leaf statement, placed in the previously defined 2685 "ssh" container (See Section 7.5.9): 2687 leaf port { 2688 type inet:port-number; 2689 default 22; 2690 description "The port which the SSH server listens to" 2691 } 2693 A corresponding XML instance example: 2695 2022 2697 To set the value of a leaf with an : 2699 2702 2703 2704 2705 2706 2707 2708 2709 2710 2022 2711 2712 2713 2714 2715 2716 2718 7.7. The leaf-list Statement 2720 Where the "leaf" statement is used to define a simple scalar variable 2721 of a particular type, the "leaf-list" statement is used to define an 2722 array of a particular type. The "leaf-list" statement takes one 2723 argument, which is an identifier, followed by a block of 2724 substatements that holds detailed leaf-list information. 2726 The values in a leaf-list MUST be unique. 2728 Conceptually, the values in the data tree are always in the canonical 2729 form (see Section 9.1). 2731 If the type referenced by the leaf-list has a default value, it has 2732 no effect in the leaf-list. 2734 7.7.1. Ordering 2736 YANG supports two styles for ordering the entries within lists and 2737 leaf-lists. In many lists, the order of list entries does not impact 2738 the implementation of the list's configuration, and the device is 2739 free to sort the list entries in any reasonable order. The 2740 "description" string for the list may suggest an order to the device 2741 implementor. YANG calls this style of list "system ordered" and they 2742 are indicated with the statement "ordered-by system". 2744 For example, a list of valid users would typically be sorted 2745 alphabetically, since the order in which the users appeared in the 2746 configuration would not impact the creation of those users' accounts. 2748 In the other style of lists, the order of list entries matters for 2749 the implementation of the list's configuration and the user is 2750 responsible for ordering the entries, while the device maintains that 2751 order. YANG calls this style of list "user ordered" and they are 2752 indicated with the statement "ordered-by user". 2754 For example, the order in which firewall filters entries are applied 2755 to incoming traffic may affect how that traffic is filtered. The 2756 user would need to decide if the filter entry that discards all TCP 2757 traffic should be applied before or after the filter entry that 2758 allows all traffic from trusted interfaces. The choice of order 2759 would be crucial. 2761 YANG provides a rich set of facilities within NETCONF's 2762 operation which allow the order of list entries in user-ordered lists 2763 to be controlled. List entries may be inserted or rearranged, 2764 positioned as the first or last entry in the list, or positioned 2765 before or after another specific entry. 2767 The "ordered-by" statement is covered in Section 7.7.5. 2769 7.7.2. The leaf-list's Substatements 2771 +--------------+---------+-------------+ 2772 | substatement | section | cardinality | 2773 +--------------+---------+-------------+ 2774 | config | 7.19.1 | 0..1 | 2775 | description | 7.19.3 | 0..1 | 2776 | if-feature | 7.18.2 | 0..n | 2777 | max-elements | 7.7.4 | 0..1 | 2778 | min-elements | 7.7.3 | 0..1 | 2779 | must | 7.5.3 | 0..n | 2780 | ordered-by | 7.7.5 | 0..1 | 2781 | reference | 7.19.4 | 0..1 | 2782 | status | 7.19.2 | 0..1 | 2783 | type | 7.4 | 1 | 2784 | units | 7.3.3 | 0..1 | 2785 | when | 7.19.5 | 0..1 | 2786 +--------------+---------+-------------+ 2788 7.7.3. The min-elements Statement 2790 The "min-elements" statement, which is optional, takes as an argument 2791 a non-negative integer which puts a constraint on valid list entries. 2792 A valid leaf-list or list MUST have at least min-elements entries. 2794 If no "min-elements" statement is present, it defaults to zero. 2796 The behavior of the constraint depends on the type of the leaf-list's 2797 or list's closest ancestor node in the schema tree which is not a 2798 non-presence container (see Section 7.5.1): 2800 o If this ancestor is a case node, the constraint is enforced if any 2801 other node from the case exists. 2803 o Otherwise, it is enforced if the ancestor node exists. 2805 The constraint is further enforced according to the rules in 2806 Section 8. 2808 7.7.4. The max-elements Statement 2810 The "max-elements" statement, which is optional, takes as an argument 2811 a positive integer or the string "unbounded", which puts a constraint 2812 on valid list entries. A valid leaf-list or list always has at most 2813 max-elements entries. 2815 If no "max-elements" statement is present, it defaults to 2816 "unbounded". 2818 The "max-elements" constraint is enforced according to the rules in 2819 Section 8. 2821 7.7.5. The ordered-by Statement 2823 The "ordered-by" statement defines whether the order of entries 2824 within a list are determined by the user or the system. The argument 2825 is one of the strings "system" or "user". If not present, order 2826 defaults to "system". 2828 This statement is ignored if the list represents state data, RPC 2829 output parameters, or notification content. 2831 See Section 7.7.1 for additional information. 2833 7.7.5.1. ordered-by system 2835 The entries in the list are sorted according to an unspecified order. 2836 Thus an implementation is free to sort the entries in the most 2837 appropriate order. An implementation SHOULD use the same order for 2838 the same data, regardless of how the data were created. Using a 2839 deterministic order will make comparisons possible using simple tools 2840 like "diff". 2842 This is the default order. 2844 7.7.5.2. ordered-by user 2846 The entries in the list are sorted according to an order defined by 2847 the user. This order is controlled by using special XML attributes 2848 in the request. See Section 7.7.7 for details. 2850 7.7.6. XML Mapping Rules 2852 A leaf-list node is encoded as a series of XML elements. Each 2853 element's local name is the leaf-list's identifier, and its namespace 2854 is the module's XML namespace (see Section 7.1.3). 2856 The value of each leaf-list entry is encoded to XML according to the 2857 type, and sent as character data in the element. 2859 The XML elements representing leaf-list entries MUST appear in the 2860 order specified by the user if the leaf-list is "ordered-by user", 2861 otherwise the order is implementation-dependent. The XML elements 2862 representing leaf-list entries MAY be interleaved with other sibling 2863 elements, unless the leaf-list defines RPC input or output 2864 parameters. 2866 See Section 7.7.8 for an example. 2868 7.7.7. NETCONF Operations 2870 Leaf-list entries can be created and deleted, but not modified, 2871 through , by using the "operation" attribute in the 2872 leaf-list entry's XML element. 2874 In an "ordered-by user" leaf-list, the attributes "insert" and 2875 "value" in the YANG XML namespace (Section 5.3.1) can be used to 2876 control where in the leaf-list the entry is inserted. These can be 2877 used during "create" operations to insert a new leaf-list entry, or 2878 during "merge" or "replace" operations to insert a new leaf-list 2879 entry or move an existing one. 2881 The "insert" attribute can take the values "first", "last", "before", 2882 and "after". If the value is "before" or "after", the "value" 2883 attribute MUST also be used to specify an existing entry in the leaf- 2884 list. 2886 If no "insert" attribute is present in the "create" operation, it 2887 defaults to "last". 2889 If several entries in an "ordered-by user" leaf-list are modified in 2890 the same request, the entries are modified one at the 2891 time, in the order of the XML elements in the request. 2893 In a , or an with a "replace" operation 2894 which covers the entire leaf-list, the leaf-list order is the same as 2895 the order of the XML elements in the request. 2897 When a NETCONF server processes an request, the 2898 elements of procedure for a leaf-list node are: 2900 If the operation is "merge" or "replace" the leaf-list entry is 2901 created if it does not exist. 2903 If the operation is "create" the leaf-list entry is created if it 2904 does not exist. If the leaf-list entry already exists, a 2905 "data-exists" error is returned. 2907 If the operation is "delete" the entry is deleted from the leaf- 2908 list if it exists. If the leaf-list entry does not exist, a 2909 "data-missing" error is returned. 2911 7.7.8. Usage Example 2913 leaf-list allow-user { 2914 type string; 2915 description "A list of user name patterns to allow"; 2916 } 2918 A corresponding XML instance example: 2920 alice 2921 bob 2923 To create a new element in this list, using the default 2924 operation "merge": 2926 2929 2930 2931 2932 2933 2934 2935 2936 2937 eric 2938 2939 2940 2941 2942 2943 2945 Given the following ordered-by user leaf-list: 2947 leaf-list cipher { 2948 type string; 2949 ordered-by user; 2950 description "A list of ciphers"; 2951 } 2953 The following would be used to insert a new cipher "blowfish-cbc" 2954 after "3des-cbc": 2956 2960 2961 2962 2963 2964 2965 2966 2967 2968 blowfish-cbc 2971 2972 2973 2974 2975 2976 2978 7.8. The list Statement 2980 The "list" statement is used to define an interior data node in the 2981 schema tree. A list node may exist in multiple instances in the data 2982 tree. Each such instance is known as a list entry. The "list" 2983 statement takes one argument which is an identifier, followed by a 2984 block of substatements that holds detailed list information. 2986 A list entry is uniquely identified by the values of the list's keys, 2987 if defined. 2989 7.8.1. The list's Substatements 2991 +--------------+---------+-------------+ 2992 | substatement | section | cardinality | 2993 +--------------+---------+-------------+ 2994 | anyxml | 7.10 | 0..n | 2995 | choice | 7.9 | 0..n | 2996 | config | 7.19.1 | 0..1 | 2997 | container | 7.5 | 0..n | 2998 | description | 7.19.3 | 0..1 | 2999 | grouping | 7.11 | 0..n | 3000 | if-feature | 7.18.2 | 0..n | 3001 | key | 7.8.2 | 0..1 | 3002 | leaf | 7.6 | 0..n | 3003 | leaf-list | 7.7 | 0..n | 3004 | list | 7.8 | 0..n | 3005 | max-elements | 7.7.4 | 0..1 | 3006 | min-elements | 7.7.3 | 0..1 | 3007 | must | 7.5.3 | 0..n | 3008 | ordered-by | 7.7.5 | 0..1 | 3009 | reference | 7.19.4 | 0..1 | 3010 | status | 7.19.2 | 0..1 | 3011 | typedef | 7.3 | 0..n | 3012 | unique | 7.8.3 | 0..n | 3013 | uses | 7.12 | 0..n | 3014 | when | 7.19.5 | 0..1 | 3015 +--------------+---------+-------------+ 3017 7.8.2. The list's key Statement 3019 The "key" statement, which MUST be present if the list represents 3020 configuration, and MAY be present otherwise, takes as an argument a 3021 string which specifies a space separated list of leaf identifiers of 3022 this list. A leaf identifier MUST NOT appear more than once in the 3023 key. Each such leaf identifier MUST refer to a child leaf of the 3024 list. The leafs can be defined directly in substatements to the 3025 list, or in groupings used in the list. 3027 The combined values of all the leafs specified in the key are used to 3028 uniquely identify a list entry. All key leafs MUST be given values 3029 when a list entry is created. Thus, any default values in the key 3030 leafs or their types are ignored. It also implies that any mandatory 3031 statement in the key leafs are ignored. 3033 A leaf that is part of the key can be of any built-in or derived 3034 type, except it MUST NOT be the built-in type "empty". 3036 All key leafs in a list MUST have the same value for their "config" 3037 as the list itself. 3039 The key string syntax is formally defined by the rule "key-arg" in 3040 Section 12. 3042 7.8.3. The list's unique Statement 3044 The "unique" statement is used to put constraints on valid list 3045 entries. It takes as an argument a string which contains a space 3046 separated list of schema node identifiers, which MUST be given in the 3047 descendant form (see the rule "descendant-schema-nodeid" in 3048 Section 12). Each such schema node identifier MUST refer to a leaf. 3050 If one of the referenced leafs represents configuration data, then 3051 all of the referenced leafs MUST represent configuration data. 3053 The "unique" constraint specifies that the combined values of all the 3054 leaf instances specified in the argument string, including leafs with 3055 default values, MUST be unique within all list entry instances in 3056 which all referenced leafs exist. The constraint is enforced 3057 according to the rules in Section 8. 3059 The unique string syntax is formally defined by the rule "unique-arg" 3060 in Section 12. 3062 7.8.3.1. Usage Example 3064 With the following list: 3066 list server { 3067 key "name"; 3068 unique "ip port"; 3069 leaf name { 3070 type string; 3071 } 3072 leaf ip { 3073 type inet:ip-address; 3074 } 3075 leaf port { 3076 type inet:port-number; 3077 } 3078 } 3080 The following configuration is not valid: 3082 3083 smtp 3084 192.0.2.1 3085 25 3086 3088 3089 http 3090 192.0.2.1 3091 25 3092 3094 The following configuration is valid, since the "http" and "ftp" list 3095 entries do not have a value for all referenced leafs, and are thus 3096 not taken into account when the "unique" constraint is enforced: 3098 3099 smtp 3100 192.0.2.1 3101 25 3102 3104 3105 http 3106 192.0.2.1 3107 3109 3110 ftp 3111 192.0.2.1 3112 3114 7.8.4. The list's Child Node Statements 3116 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3117 "choice", and "anyxml" statements can be used to define child nodes 3118 to the list. 3120 7.8.5. XML Mapping Rules 3122 A list is encoded as a series of XML elements, one for each entry in 3123 the list. Each element's local name is the list's identifier, and 3124 its namespace is the module's XML namespace (see Section 7.1.3). 3126 The list's key nodes are encoded as subelements to the list's 3127 identifier element, in the same order as they are defined within the 3128 key statement. 3130 The rest of the list's child nodes are encoded as subelements to the 3131 list element, after the keys. If the list defines RPC input or 3132 output parameters, the subelements are encoded in the same order as 3133 they are defined within the list statement. Otherwise, the 3134 subelements are encoded in any order. 3136 The XML elements representing list entries MUST appear in the order 3137 specified by the user if the list is "ordered-by user", otherwise the 3138 order is implementation-dependent. The XML elements representing 3139 list entries MAY be interleaved with other sibling elements, unless 3140 the list defines RPC input or output parameters. 3142 7.8.6. NETCONF Operations 3144 List entries can be created, deleted, replaced and modified through 3145 , by using the "operation" attribute in the list's XML 3146 element. In each case, the values of all keys are used to uniquely 3147 identify a list entry. If all keys are not specified for a list 3148 entry, a "missing-element" error is returned. 3150 In an "ordered-by user" list, the attributes "insert" and "key" in 3151 the YANG XML namespace (Section 5.3.1) can be used to control where 3152 in the list the entry is inserted. These can be used during "create" 3153 operations to insert a new list entry, or during "merge" or "replace" 3154 operations to insert a new list entry or move an existing one. 3156 The "insert" attribute can take the values "first", "last", "before", 3157 and "after". If the value is "before" or "after", the "key" 3158 attribute MUST also be used, to specify an existing element in the 3159 list. The value of the "key" attribute is the key predicates of the 3160 full instance identifier (see Section 9.13) for the list entry. 3162 If no "insert" attribute is present in the "create" operation, it 3163 defaults to "last". 3165 If several entries in an "ordered-by user" list are modified in the 3166 same request, the entries are modified one at the time, 3167 in the order of the XML elements in the request. 3169 In a , or an with a "replace" operation 3170 which covers the entire list, the list entry order is the same as the 3171 order of the XML elements in the request. 3173 When a NETCONF server processes an request, the 3174 elements of procedure for a list node are: 3176 If the operation is "merge" or "replace", the list entry is 3177 created if it does not exist. If the list entry already exists 3178 and the "insert" and "key" attributes are present, the list entry 3179 is moved according to the values of the "insert" and "key" 3180 attributes. If the list entry exists and the "insert" and "key" 3181 attributes are not present, the list entry is not moved. 3183 If the operation is "create" the list entry is created if it does 3184 not exist. If the list entry already exists, a "data-exists" 3185 error is returned. 3187 If the operation is "delete" the entry is deleted from the list if 3188 it exists. If the list entry does not exist, a "data-missing" 3189 error is returned. 3191 7.8.7. Usage Example 3193 Given the following list: 3195 list user { 3196 key "name"; 3197 config true; 3198 description "This is a list of users in the system."; 3200 leaf name { 3201 type string; 3202 } 3203 leaf type { 3204 type string; 3205 } 3206 leaf full-name { 3207 type string; 3208 } 3209 } 3211 A corresponding XML instance example: 3213 3214 fred 3215 admin 3216 Fred Flintstone 3217 3219 To create a new user "barney": 3221 3224 3225 3226 3227 3228 3229 3230 3231 barney 3232 admin 3233 Barney Rubble 3234 3235 3236 3237 3238 3240 To change the type of "fred" to "superuser": 3242 3245 3246 3247 3248 3249 3250 3251 3252 fred 3253 superuser 3254 3255 3256 3257 3258 3260 Given the following ordered-by user list: 3262 list user { 3263 description "This is a list of users in the system."; 3264 ordered-by user; 3265 config true; 3267 key "name"; 3269 leaf name { 3270 type string; 3271 } 3272 leaf type { 3273 type string; 3274 } 3275 leaf full-name { 3276 type string; 3277 } 3278 } 3280 The following would be used to insert a new user "barney" after the 3281 user "fred": 3283 3287 3288 3289 3290 3291 3292 3294 3297 barney 3298 admin 3299 Barney Rubble 3300 3301 3302 3303 3304 3306 The following would be used to move the user "barney" before the user 3307 "fred": 3309 3313 3314 3315 3316 3317 3318 3320 3323 barney 3324 3325 3326 3327 3328 3330 7.9. The choice Statement 3332 The "choice" statement defines a set of alternatives, only one of 3333 which may exist at any one time. The argument is an identifier, 3334 followed by a block of substatements that holds detailed choice 3335 information. The identifier is used to identify the choice node in 3336 the schema tree. A choice node does not exist in the data tree. 3338 A choice consists of a number of branches, defined with the "case" 3339 substatement. Each branch contains a number of child nodes. The 3340 nodes from at most one of the choice's branches exist at the same 3341 time. 3343 See Section 8.3.2 for additional information. 3345 7.9.1. The choice's Substatements 3347 +--------------+---------+-------------+ 3348 | substatement | section | cardinality | 3349 +--------------+---------+-------------+ 3350 | anyxml | 7.10 | 0..n | 3351 | case | 7.9.2 | 0..n | 3352 | config | 7.19.1 | 0..1 | 3353 | container | 7.5 | 0..n | 3354 | default | 7.9.3 | 0..1 | 3355 | description | 7.19.3 | 0..1 | 3356 | if-feature | 7.18.2 | 0..n | 3357 | leaf | 7.6 | 0..n | 3358 | leaf-list | 7.7 | 0..n | 3359 | list | 7.8 | 0..n | 3360 | mandatory | 7.9.4 | 0..1 | 3361 | reference | 7.19.4 | 0..1 | 3362 | status | 7.19.2 | 0..1 | 3363 | when | 7.19.5 | 0..1 | 3364 +--------------+---------+-------------+ 3366 7.9.2. The choice's case Statement 3368 The "case" statement is used to define branches of the choice. It 3369 takes as an argument an identifier, followed by a block of 3370 substatements that holds detailed case information. 3372 The identifier is used to identify the case node in the schema tree. 3373 A case node does not exist in the data tree. 3375 Within a "case" statement, the "anyxml", "choice", "container", 3376 "leaf", "list", "leaf-list", and "uses" statements can be used to 3377 define child nodes to the case node. The identifiers of all these 3378 child nodes MUST be unique within all cases in a choice. For 3379 example, the following is illegal: 3381 choice interface-type { // This example is illegal YANG 3382 case a { 3383 leaf ethernet { ... } 3384 } 3385 case b { 3386 container ethernet { ...} 3387 } 3388 } 3390 As a shorthand, the "case" statement can be omitted if the branch 3391 contains a single "anyxml", "container", "leaf", "list", or 3392 "leaf-list" statement. In this case, the identifier of the case node 3393 is the same as the identifier in the branch statement. The following 3394 example: 3396 choice interface-type { 3397 container ethernet { ... } 3398 } 3400 is equivalent to: 3402 choice interface-type { 3403 case ethernet { 3404 container ethernet { ... } 3405 } 3406 } 3408 The case identifier MUST be unique within a choice. 3410 7.9.2.1. The case's Substatements 3412 +--------------+---------+-------------+ 3413 | substatement | section | cardinality | 3414 +--------------+---------+-------------+ 3415 | anyxml | 7.10 | 0..n | 3416 | choice | 7.9 | 0..n | 3417 | container | 7.5 | 0..n | 3418 | description | 7.19.3 | 0..1 | 3419 | if-feature | 7.18.2 | 0..n | 3420 | leaf | 7.6 | 0..n | 3421 | leaf-list | 7.7 | 0..n | 3422 | list | 7.8 | 0..n | 3423 | reference | 7.19.4 | 0..1 | 3424 | status | 7.19.2 | 0..1 | 3425 | uses | 7.12 | 0..n | 3426 | when | 7.19.5 | 0..1 | 3427 +--------------+---------+-------------+ 3429 7.9.3. The choice's default Statement 3431 The "default" statement indicates if a case should be considered as 3432 the default if no child nodes from any of the choice's cases exist. 3433 The argument is the identifier of the "case" statement. If the 3434 "default" statement is missing, there is no default case. 3436 The "default" statement MUST NOT be present on choices where 3437 "mandatory" is true. 3439 The default case is only important when considering the default 3440 values of nodes under the cases. The default values for nodes under 3441 the default case are used if none of the nodes under any of the cases 3442 are present. 3444 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3445 the default case. 3447 Default values for child nodes under a case are only used if one of 3448 the nodes under that case is present, or if that case is the default 3449 case. If none of the nodes under a case are present and the case is 3450 not the default case, the default values of the cases' child nodes 3451 are ignored. 3453 In this example, the choice defaults to "interval", and the default 3454 value will be used if none of "daily", "time-of-day", or "manual" are 3455 present. If "daily" is present, the default value for "time-of-day" 3456 will be used. 3458 container transfer { 3459 choice how { 3460 default interval; 3461 case interval { 3462 leaf interval { 3463 type uint16; 3464 default 30; 3465 units minutes; 3466 } 3467 } 3468 case daily { 3469 leaf daily { 3470 type empty; 3471 } 3472 leaf time-of-day { 3473 type string; 3474 units 24-hour-clock; 3475 default 1am; 3476 } 3477 } 3478 case manual { 3479 leaf manual { 3480 type empty; 3481 } 3482 } 3483 } 3484 } 3486 7.9.4. The choice's mandatory Statement 3488 The "mandatory" statement, which is optional, takes as an argument 3489 the string "true" or "false", and puts a constraint on valid data. 3490 If "mandatory" is "true", at least one node from exactly one of the 3491 choice's case branches MUST exist. 3493 If not specified, the default is "false". 3495 The behavior of the constraint depends on the type of the choice's 3496 closest ancestor node in the schema tree which is not a non-presence 3497 container (see Section 7.5.1): 3499 o If this ancestor is a case node, the constraint is enforced if any 3500 other node from the case exists. 3502 o Otherwise, it is enforced if the ancestor node exists. 3504 The constraint is further enforced according to the rules in 3505 Section 8. 3507 7.9.5. XML Mapping Rules 3509 The choice and case nodes are not visible in XML. 3511 The child nodes of the selected "case" statement MUST be encoded in 3512 the same order as they are defined in the "case" statement if they 3513 are part of a RPC input or output parameter definition. Otherwise, 3514 the subelements are encoded in any order. 3516 7.9.6. NETCONF Operations 3518 Since only one of the choice's cases can be valid at any time, the 3519 creation of a node from one case implicitly deletes all nodes from 3520 all other cases. If an operation creates a node from a 3521 case, the NETCONF server will delete any existing nodes that are 3522 defined in other cases inside the choice. 3524 7.9.7. Usage Example 3526 Given the following choice: 3528 container protocol { 3529 choice name { 3530 case a { 3531 leaf udp { 3532 type empty; 3533 } 3534 } 3535 case b { 3536 leaf tcp { 3537 type empty; 3538 } 3539 } 3540 } 3541 } 3543 A corresponding XML instance example: 3545 3546 3547 3549 To change the protocol from tcp to udp: 3551 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3568 7.10. The anyxml Statement 3570 The "anyxml" statement defines an interior node in the schema tree. 3571 It takes one argument, which is an identifier, followed by a block of 3572 substatements that holds detailed anyxml information. 3574 The anyxml statement is used to represent an unknown chunk of XML. 3575 No restrictions are placed on the XML. This can be useful, for 3576 example, in RPC replies. An example is the parameter in the 3577 operation. 3579 An anyxml node cannot be augmented (see Section 7.15). 3581 Since the use of anyxml limits the manipulation of the content, it is 3582 RECOMMENDED that the anyxml statement not be used to represent 3583 configuration data. 3585 An anyxml node exists in zero or one instances in the data tree. 3587 7.10.1. The anyxml's Substatements 3589 +--------------+---------+-------------+ 3590 | substatement | section | cardinality | 3591 +--------------+---------+-------------+ 3592 | config | 7.19.1 | 0..1 | 3593 | description | 7.19.3 | 0..1 | 3594 | if-feature | 7.18.2 | 0..n | 3595 | mandatory | 7.6.5 | 0..1 | 3596 | must | 7.5.3 | 0..n | 3597 | reference | 7.19.4 | 0..1 | 3598 | status | 7.19.2 | 0..1 | 3599 | when | 7.19.5 | 0..1 | 3600 +--------------+---------+-------------+ 3602 7.10.2. XML Mapping Rules 3604 An anyxml node is encoded as an XML element. The element's local 3605 name is the anyxml's identifier, and its namespace is the module's 3606 XML namespace (see Section 7.1.3). The value of the anyxml node is 3607 encoded as XML content of this element. 3609 Note that any prefixes used in the encoding are local to each 3610 instance encoding. This means that the same XML may be encoded 3611 differently by different implementations. 3613 7.10.3. NETCONF Operations 3615 An anyxml node is treated as an opaque chunk of data. This data can 3616 be modified in its entirety only. 3618 Any "operation" attributes present on subelements of an anyxml node 3619 are ignored by the NETCONF server. 3621 When a NETCONF server processes an request, the 3622 elements of procedure for the anyxml node are: 3624 If the operation is "merge" or "replace", the node is created if 3625 it does not exist, and its value is set to the XML content of the 3626 anyxml node found in the XML RPC data. 3628 If the operation is "create" the node is created if it does not 3629 exist, and its value is set to the XML content of the anyxml node 3630 found in the XML RPC data. If the node already exists, a 3631 "data-exists" error is returned. 3633 If the operation is "delete" the node is deleted if it exists. If 3634 the node does not exist, a "data-missing" error is returned. 3636 7.10.4. Usage Example 3638 Given the following anyxml statement: 3640 anyxml data; 3642 The following are two valid encodings of the same anyxml value: 3644 3645 3646 1 3647 3648 3650 3651 3652 1 3653 3654 3656 7.11. The grouping Statement 3658 The "grouping" statement is used to define a reusable block of nodes, 3659 which may be used locally in the module, in modules which include it, 3660 and by other modules which import from it, according to the rules in 3661 Section 5.5. It takes one argument which is an identifier, followed 3662 by a block of substatements that holds detailed grouping information. 3664 The grouping statement is not a data definition statement and, as 3665 such, does not define any nodes in the schema tree. 3667 A grouping is like a "structure" or a "record" in conventional 3668 programming languages. 3670 Once a grouping is defined, it can be referenced in a "uses" 3671 statement (see Section 7.12). A grouping MUST NOT reference itself, 3672 neither directly nor indirectly through a chain of other groupings. 3674 If the grouping is defined at the top level of a YANG module or 3675 submodule, the grouping's identifier MUST be unique within the 3676 module. 3678 A grouping is more than just a mechanism for textual substitution, 3679 but defines a collection of nodes. Identifiers appearing inside the 3680 grouping are resolved relative to the scope in which the grouping is 3681 defined, not where it is used. Prefix mappings, type names, grouping 3682 names, and extension usage are evaluated in the hierarchy where the 3683 grouping statement appears. For extensions, this means that 3684 extensions are applied to the grouping node, not the uses node. 3686 7.11.1. The grouping's Substatements 3688 +--------------+---------+-------------+ 3689 | substatement | section | cardinality | 3690 +--------------+---------+-------------+ 3691 | anyxml | 7.10 | 0..n | 3692 | choice | 7.9 | 0..n | 3693 | container | 7.5 | 0..n | 3694 | description | 7.19.3 | 0..1 | 3695 | grouping | 7.11 | 0..n | 3696 | leaf | 7.6 | 0..n | 3697 | leaf-list | 7.7 | 0..n | 3698 | list | 7.8 | 0..n | 3699 | reference | 7.19.4 | 0..1 | 3700 | status | 7.19.2 | 0..1 | 3701 | typedef | 7.3 | 0..n | 3702 | uses | 7.12 | 0..n | 3703 +--------------+---------+-------------+ 3705 7.11.2. Usage Example 3707 import ietf-inet-types { 3708 prefix "inet"; 3709 } 3711 grouping endpoint { 3712 description "A reusable endpoint group."; 3713 leaf ip { 3714 type inet:ip-address; 3715 } 3716 leaf port { 3717 type inet:port-number; 3718 } 3719 } 3721 7.12. The uses Statement 3723 The "uses" statement is used to reference a "grouping" definition. 3724 It takes one argument, which is the name of the grouping. 3726 The effect of a "uses" reference to a grouping is that the nodes 3727 defined by the grouping are copied into the current schema tree, and 3728 then updated according to the refinement and augment statements. 3730 The identifiers defined in the grouping are not bound to a namespace 3731 until the contents of the grouping are added to the schema tree via a 3732 "uses" statement that does not appear inside a "grouping" statement, 3733 at which point they are bound to the namespace of the current module. 3735 7.12.1. The uses's Substatements 3737 +--------------+---------+-------------+ 3738 | substatement | section | cardinality | 3739 +--------------+---------+-------------+ 3740 | augment | 7.15 | 0..1 | 3741 | description | 7.19.3 | 0..1 | 3742 | if-feature | 7.18.2 | 0..n | 3743 | refine | 7.12.2 | 0..1 | 3744 | reference | 7.19.4 | 0..1 | 3745 | status | 7.19.2 | 0..1 | 3746 | when | 7.19.5 | 0..1 | 3747 +--------------+---------+-------------+ 3749 7.12.2. The refine Statement 3751 Some of the properties of each node in the grouping can be refined 3752 with the "refine" statement. The argument is a string which 3753 identifies a node in the grouping. This node is called the refine's 3754 target node. If a node in the grouping is not present as a target 3755 node of a refine statement, it is not refined, and thus used exactly 3756 as it was defined in the grouping. 3758 The argument string is a descendant schema node identifier (see 3759 Section 6.5). 3761 The following refinements can be done: 3763 o A leaf or choice node may get a default value, or a new default 3764 value if it already had one. 3766 o Any node may get a specialized "description" string. 3768 o Any node may get a specialized "reference" string. 3770 o Any node may get a different "config" statement. 3772 o A leaf, anyxml, or choice node may get a different "mandatory" 3773 statement. 3775 o A container node may get a "presence" statement. 3777 o A leaf, leaf-list, list, container, or anyxml node may get 3778 additional "must" expressions. 3780 o A leaf-list or list node may get a different "min-elements" or 3781 "max-elements" statement. 3783 7.12.3. XML Mapping Rules 3785 Each node in the grouping is encoded as if it was defined inline, 3786 even if it is imported from another module with another XML 3787 namespace. 3789 7.12.4. Usage Example 3791 To use the "endpoint" grouping defined in Section 7.11.2 in a 3792 definition of an HTTP server in some other module, we can do: 3794 import acme-system { 3795 prefix "acme"; 3796 } 3798 container http-server { 3799 leaf name { 3800 type string; 3801 } 3802 uses acme:endpoint; 3803 } 3805 A corresponding XML instance example: 3807 3808 extern-web 3809 192.0.2.1 3810 80 3811 3813 If port 80 should be the default for the HTTP server, default can be 3814 added: 3816 container http-server { 3817 leaf name { 3818 type string; 3819 } 3820 uses acme:endpoint { 3821 refine port { 3822 default 80; 3823 } 3824 } 3825 } 3827 If we want to define a list of servers, and each server has the ip 3828 and port as keys, we can do: 3830 list server { 3831 key "ip port"; 3832 leaf name { 3833 type string; 3834 } 3835 uses acme:endpoint; 3836 } 3838 The following is an error: 3840 container http-server { 3841 uses acme:endpoint; 3842 leaf ip { // illegal - same identifier "ip" used twice 3843 type string; 3844 } 3845 } 3847 7.13. The rpc Statement 3849 The "rpc" statement is used to define a NETCONF RPC operation. It 3850 takes one argument, which is an identifier, followed by a block of 3851 substatements that holds detailed rpc information. This argument is 3852 the name of the RPC, and is used as the element name directly under 3853 the element, as designated by the substitution group 3854 "rpcOperation" in [RFC4741]. 3856 The "rpc" statement defines an rpc node in the schema tree. Under 3857 the rpc node, a schema node with the name "input", and a schema node 3858 with the name "output" are also defined. The nodes "input" and 3859 "output" are defined in the module's namespace. 3861 7.13.1. The rpc's Substatements 3863 +--------------+---------+-------------+ 3864 | substatement | section | cardinality | 3865 +--------------+---------+-------------+ 3866 | description | 7.19.3 | 0..1 | 3867 | grouping | 7.11 | 0..n | 3868 | if-feature | 7.18.2 | 0..n | 3869 | input | 7.13.2 | 0..1 | 3870 | output | 7.13.3 | 0..1 | 3871 | reference | 7.19.4 | 0..1 | 3872 | status | 7.19.2 | 0..1 | 3873 | typedef | 7.3 | 0..n | 3874 +--------------+---------+-------------+ 3876 7.13.2. The input Statement 3878 The "input" statement, which is optional, is used to define input 3879 parameters to the RPC operation. It does not take an argument. The 3880 substatements to "input" define nodes under the RPC's input node. 3882 If a leaf in the input tree has a "mandatory" statement with the 3883 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3884 Otherwise, the server MUST return a "missing-element" error. 3886 If a leaf in the input tree has a default value, the NETCONF server 3887 MUST use this value in the same cases as described in Section 7.6.1. 3888 In these cases, the server MUST operationally behave as if the leaf 3889 was present in the NETCONF RPC invocation with the default value as 3890 its value. 3892 If a "config" statement is present for any node in the input tree, 3893 the "config" statement is ignored. 3895 If any node has a "when" statement which would evaluate to false, 3896 then this node MUST NOT be present in the input tree. 3898 7.13.2.1. The input's Substatements 3900 +--------------+---------+-------------+ 3901 | substatement | section | cardinality | 3902 +--------------+---------+-------------+ 3903 | anyxml | 7.10 | 0..n | 3904 | choice | 7.9 | 0..n | 3905 | container | 7.5 | 0..n | 3906 | grouping | 7.11 | 0..n | 3907 | leaf | 7.6 | 0..n | 3908 | leaf-list | 7.7 | 0..n | 3909 | list | 7.8 | 0..n | 3910 | typedef | 7.3 | 0..n | 3911 | uses | 7.12 | 0..n | 3912 +--------------+---------+-------------+ 3914 7.13.3. The output Statement 3916 The "output" statement, which is optional, is used to define output 3917 parameters to the RPC operation. It does not take an argument. The 3918 substatements to "output" define nodes under the RPC's output node. 3920 If a leaf in the output tree has a "mandatory" statement with the 3921 value "true", the leaf MUST be present in a NETCONF RPC reply. 3923 If a leaf in the output tree has a default value, the NETCONF client 3924 MUST use this value in the same cases as described in Section 7.6.1. 3925 In these cases, the client MUST operationally behave as if the leaf 3926 was present in the NETCONF RPC reply with the default value as its 3927 value. 3929 If a "config" statement is present for any node in the output tree, 3930 the "config" statement is ignored. 3932 If any node has a "when" statement which would evaluate to false, 3933 then this node MUST NOT be present in the output tree. 3935 7.13.3.1. The output's Substatements 3937 +--------------+---------+-------------+ 3938 | substatement | section | cardinality | 3939 +--------------+---------+-------------+ 3940 | anyxml | 7.10 | 0..n | 3941 | choice | 7.9 | 0..n | 3942 | container | 7.5 | 0..n | 3943 | grouping | 7.11 | 0..n | 3944 | leaf | 7.6 | 0..n | 3945 | leaf-list | 7.7 | 0..n | 3946 | list | 7.8 | 0..n | 3947 | typedef | 7.3 | 0..n | 3948 | uses | 7.12 | 0..n | 3949 +--------------+---------+-------------+ 3951 7.13.4. XML Mapping Rules 3953 An rpc node is encoded as a child XML element to the element 3954 defined in [RFC4741]. The element's local name is the rpc's 3955 identifier, and its namespace is the module's XML namespace (see 3956 Section 7.1.3). 3958 Input parameters are encoded as child XML elements to the rpc node's 3959 XML element, in the same order as they are defined within the input 3960 statement. 3962 If the RPC operation invocation succeeded, and no output parameters 3963 are returned, the contains a single element defined 3964 in [RFC4741]. If output parameters are returned, they are encoded as 3965 child elements to the element defined in [RFC4741], in 3966 the same order as they are defined within the output statement. 3968 7.13.5. Usage Example 3970 The following example defines an RPC operation: 3972 module rock { 3973 namespace "http://example.net/rock"; 3974 prefix "rock"; 3976 rpc rock-the-house { 3977 input { 3978 leaf zip-code { 3979 type string; 3980 } 3981 } 3982 } 3984 } 3986 A corresponding XML instance example of the complete rpc and rpc- 3987 reply: 3989 3991 3992 27606-0100 3993 3994 3996 3998 3999 4001 7.14. The notification Statement 4003 The "notification" statement is used to define a NETCONF 4004 notification. It takes one argument, which is an identifier, 4005 followed by a block of substatements that holds detailed notification 4006 information. The "notification" statement defines a notification 4007 node in the schema tree. 4009 If a leaf in the notification tree has a "mandatory" statement with 4010 the value "true", the leaf MUST be present in a NETCONF notification. 4012 If a leaf in the notification tree has a default value, the NETCONF 4013 client MUST use this value in the same cases as described in 4014 Section 7.6.1. In these cases, the client MUST operationally behave 4015 as if the leaf was present in the NETCONF notification with the 4016 default value as its value. 4018 If a "config" statement is present for any node in the notification 4019 tree, the "config" statement is ignored. 4021 7.14.1. The notification's Substatements 4023 +--------------+---------+-------------+ 4024 | substatement | section | cardinality | 4025 +--------------+---------+-------------+ 4026 | anyxml | 7.10 | 0..n | 4027 | choice | 7.9 | 0..n | 4028 | container | 7.5 | 0..n | 4029 | description | 7.19.3 | 0..1 | 4030 | grouping | 7.11 | 0..n | 4031 | if-feature | 7.18.2 | 0..n | 4032 | leaf | 7.6 | 0..n | 4033 | leaf-list | 7.7 | 0..n | 4034 | list | 7.8 | 0..n | 4035 | reference | 7.19.4 | 0..1 | 4036 | status | 7.19.2 | 0..1 | 4037 | typedef | 7.3 | 0..n | 4038 | uses | 7.12 | 0..n | 4039 +--------------+---------+-------------+ 4041 7.14.2. XML Mapping Rules 4043 A notification node is encoded as a child XML element to the 4044 element defined in NETCONF Event Notifications 4045 [RFC5277]. The element's local name is the notification's 4046 identifier, and its namespace is the module's XML namespace (see 4047 Section 7.1.3). 4049 7.14.3. Usage Example 4051 The following example defines a notification: 4053 module event { 4055 namespace "http://example.com/event"; 4056 prefix "ev"; 4058 notification event { 4059 leaf event-class { 4060 type string; 4061 } 4062 anyxml reporting-entity; 4063 leaf severity { 4064 type string; 4065 } 4066 } 4067 } 4069 A corresponding XML instance example of the complete notification: 4071 4073 2008-07-08T00:01:00Z 4074 4075 fault 4076 4077 Ethernet0 4078 4079 major 4080 4081 4083 7.15. The augment Statement 4085 The "augment" statement allows a module or submodule to add to the 4086 schema tree defined in an external module, or the current module and 4087 its submodules, and to add to the nodes from a grouping in a "uses" 4088 statement. The argument is a string which identifies a node in the 4089 schema tree. This node is called the augment's target node. The 4090 target node MUST be either a container, list, choice, case, input, 4091 output, or notification node. It is augmented with the nodes defined 4092 in the substatements that follow the "augment" statement. 4094 The argument string is a schema node identifier (see Section 6.5). 4095 If the "augment" statement is on the top-level in a module or 4096 submodule, the absolute form (defined by the rule 4097 "absolute-schema-nodeid" in Section 12) of a schema node identifier 4098 MUST be used. If the "augment" statement is a substatement to the 4099 "uses" statement, the descendant form (defined by the rule 4100 "descendant-schema-nodeid" in Section 12) MUST be used. 4102 If the target node is a container, list, case, input, output, or 4103 notification node, the "container", "leaf", "list", "leaf-list", 4104 "uses", and "choice" statements can be used within the "augment" 4105 statement. 4107 If the target node is a choice node, the "case" statement, or a case 4108 shorthand statement (see Section 7.9.2) can be used within the 4109 "augment" statement. 4111 If the target node is in another module, then nodes added by the 4112 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4114 The augment statement MUST NOT add multiple nodes with the same name 4115 from the same module to the target node. 4117 7.15.1. The augment's Substatements 4119 +--------------+---------+-------------+ 4120 | substatement | section | cardinality | 4121 +--------------+---------+-------------+ 4122 | anyxml | 7.10 | 0..n | 4123 | case | 7.9.2 | 0..n | 4124 | choice | 7.9 | 0..n | 4125 | container | 7.5 | 0..n | 4126 | description | 7.19.3 | 0..1 | 4127 | if-feature | 7.18.2 | 0..n | 4128 | leaf | 7.6 | 0..n | 4129 | leaf-list | 7.7 | 0..n | 4130 | list | 7.8 | 0..n | 4131 | reference | 7.19.4 | 0..1 | 4132 | status | 7.19.2 | 0..1 | 4133 | uses | 7.12 | 0..n | 4134 | when | 7.19.5 | 0..1 | 4135 +--------------+---------+-------------+ 4137 7.15.2. XML Mapping Rules 4139 All data nodes defined in the "augment" statement are defined as XML 4140 elements in the XML namespace of the module where the "augment" is 4141 specified. 4143 When a node is augmented, the augmenting child nodes are encoded as 4144 subelements to the augmented node, in any order. 4146 7.15.3. Usage Example 4148 In namespace http://example.com/schema/interfaces, we have: 4150 container interfaces { 4151 list ifEntry { 4152 key "ifIndex"; 4154 leaf ifIndex { 4155 type uint32; 4156 } 4157 leaf ifDescr { 4158 type string; 4159 } 4160 leaf ifType { 4161 type iana:IfType; 4162 } 4163 leaf ifMtu { 4164 type int32; 4165 } 4166 } 4167 } 4169 Then in namespace http://example.com/schema/ds0, we have: 4171 import interface-module { 4172 prefix "if"; 4173 } 4174 augment "/if:interfaces/if:ifEntry" { 4175 when "if:ifType='ds0'"; 4176 leaf ds0ChannelNumber { 4177 type ChannelNumber; 4178 } 4179 } 4181 A corresponding XML instance example: 4183 4185 4186 1 4187 Flintstone Inc Ethernet A562 4188 ethernetCsmacd 4189 1500 4190 4191 4192 2 4193 Flintstone Inc DS0 4194 ds0 4195 1 4196 4197 4199 As another example, suppose we have the choice defined in 4200 Section 7.9.7. The following construct can be used to extend the 4201 protocol definition: 4203 augment /ex:system/ex:protocol/ex:name { 4204 case c { 4205 leaf smtp { 4206 type empty; 4207 } 4208 } 4209 } 4211 A corresponding XML instance example: 4213 4214 4215 4216 4217 4219 or 4221 4222 4223 4224 4225 4227 7.16. The identity Statement 4229 The "identity" statement is used to define a new globally unique, 4230 abstract and untyped identity. Its only purpose is to denote its 4231 name, semantics, and existence. An identity can be defined either 4232 from scratch or derived from a base identity. The identity's 4233 argument is an identifier that is the name of the identity. It is 4234 followed by a block of substatements that holds detailed identity 4235 information. 4237 The built-in datatype "identityref" (see Section 9.10) can be used to 4238 reference identities within a data model. 4240 7.16.1. The identity's Substatements 4242 +--------------+---------+-------------+ 4243 | substatement | section | cardinality | 4244 +--------------+---------+-------------+ 4245 | base | 7.16.2 | 0..1 | 4246 | description | 7.19.3 | 0..1 | 4247 | reference | 7.19.4 | 0..1 | 4248 | status | 7.19.2 | 0..1 | 4249 +--------------+---------+-------------+ 4251 7.16.2. The base Statement 4253 The base statement, which is optional, takes as an argument a string 4254 which is the name of an existing identity, from which the new 4255 identity is derived. If no base statement is present, the identity 4256 is defined from scratch. 4258 If a prefix is present on the base name, it refers to an identity 4259 defined in the module which was imported with that prefix, or the 4260 local module if the prefix matches the local module's prefix. 4261 Otherwise an identity with the matching name MUST be defined in the 4262 current module or an included submodule. 4264 Since submodules cannot include the parent module, any identities in 4265 the module which need to be exposed to submodules MUST be defined in 4266 a submodule. Submodules can then include this submodule to find the 4267 definition of the identity. 4269 An identity MUST NOT reference itself, neither directly nor 4270 indirectly through a chain of other identities. 4272 7.16.3. Usage Example 4274 module crypto-base { 4275 namespace "http://example.com/crypto-base"; 4276 prefix "crypto"; 4278 identity crypto-alg { 4279 description 4280 "Base identity from which all crypto algorithms 4281 are derived."; 4282 } 4283 } 4285 module des { 4286 namespace "http://example.com/des"; 4287 prefix "des"; 4289 import "crypto-base" { 4290 prefix "crypto"; 4291 } 4293 identity des { 4294 base "crypto:crypto-alg"; 4295 description "DES crypto algorithm"; 4296 } 4298 identity des3 { 4299 base "crypto:crypto-alg"; 4300 description "Triple DES crypto algorithm"; 4301 } 4302 } 4304 7.17. The extension Statement 4306 The "extension" statement allows the definition of new statements 4307 within the YANG language. This new statement definition can be 4308 imported and used by other modules. 4310 The statement's argument is an identifier that is the new keyword for 4311 the extension and must be followed by a block of substatements that 4312 holds detailed extension information. The purpose of the extension 4313 statement is to define a keyword, so that it can be imported and used 4314 by other modules. 4316 The extension can be used like a normal YANG statement, with the 4317 statement name followed by an argument if one is defined by the 4318 extension, and an optional block of substatements. The statement's 4319 name is created by combining the prefix of the module in which the 4320 extension was defined, a colon (":"), and the extension's keyword, 4321 with no interleaving whitespace. The substatements of an extension 4322 are defined by the extension, using some mechanism outside the scope 4323 of this specification. Syntactically, the substatements MUST be YANG 4324 statements, or also defined using "extension" statements. YANG 4325 statements in extensions MUST follow the syntactical rules in 4326 Section 12. 4328 7.17.1. The extension's Substatements 4330 +--------------+---------+-------------+ 4331 | substatement | section | cardinality | 4332 +--------------+---------+-------------+ 4333 | argument | 7.17.2 | 0..1 | 4334 | description | 7.19.3 | 0..1 | 4335 | reference | 7.19.4 | 0..1 | 4336 | status | 7.19.2 | 0..1 | 4337 +--------------+---------+-------------+ 4339 7.17.2. The argument Statement 4341 The "argument" statement, which is optional, takes as an argument a 4342 string which is the name of the argument to the keyword. If no 4343 argument statement is present, the keyword expects no argument when 4344 it is used. 4346 The argument's name is used in the YIN mapping, where it is used as 4347 an XML attribute or element name, depending on the argument's text 4348 statement. 4350 7.17.2.1. The argument's Substatements 4352 +--------------+----------+-------------+ 4353 | substatement | section | cardinality | 4354 +--------------+----------+-------------+ 4355 | yin-element | 7.17.2.2 | 0..1 | 4356 +--------------+----------+-------------+ 4358 7.17.2.2. The yin-element Statement 4360 The "yin-element" statement, which is optional, takes as an argument 4361 the string "true" or "false". This statement indicates if the 4362 argument is mapped to an XML element in YIN or to an XML attribute. 4363 (see Section 11). 4365 If no "yin-element" statement is present, it defaults to "false". 4367 7.17.3. Usage Example 4369 To define an extension: 4371 module my-extensions { 4372 ... 4374 extension c-define { 4375 description 4376 "Takes as argument a name string. 4377 Makes the code generator use the given name in the 4378 #define."; 4379 argument "name"; 4380 } 4381 } 4383 To use the extension: 4385 module my-interfaces { 4386 ... 4387 import my-extensions { 4388 prefix "myext"; 4389 } 4390 ... 4392 container interfaces { 4393 ... 4394 myext:c-define "MY_INTERFACES"; 4395 } 4396 } 4398 7.18. Conformance-related Statements 4400 This section defines statements related to conformance, as described 4401 in Section 5.6. 4403 7.18.1. The feature Statement 4405 The "feature" statement is used to define a mechanism by which 4406 portions of the schema are marked as conditional. A feature name is 4407 defined that can later be referenced using the "if-feature" statement 4408 (see Section 7.18.2). Schema nodes tagged with a feature are ignored 4409 by the device unless the device supports the given feature. This 4410 allows portions of the YANG module to be conditional based on 4411 conditions on the device. The model can represent the abilities of 4412 the device within the model, giving a richer model that allows for 4413 differing device abilities and roles. 4415 The argument to the "feature" statement is the name of the new 4416 feature, and follows the rules for identifiers in Section 6.2. This 4417 name is used by the "if-feature" statement to tie the schema nodes to 4418 the feature. 4420 In this example, a feature called "local-storage" represents the 4421 ability for a device to store syslog messages on local storage of 4422 some sort. This feature is used to make the "local-storage-limit" 4423 leaf conditional on the presence of some sort of local storage. If 4424 the device does not report that it supports this feature, the 4425 "local-storage-limit" node is not supported. 4427 module syslog { 4428 ... 4429 feature local-storage { 4430 description 4431 "This feature means the device supports local 4432 storage (memory, flash or disk) that can be used to 4433 store syslog messages."; 4434 } 4436 container syslog { 4437 leaf local-storage-limit { 4438 if-feature local-storage; 4439 type uint64; 4440 units "kilobyte"; 4441 config false; 4442 description 4443 "The amount of local storage that can be 4444 used to hold syslog messages."; 4445 } 4446 } 4447 } 4449 The "if-feature" statement can be used in many places within the YANG 4450 syntax. Definitions tagged with "if-feature" are ignored when the 4451 device does not support that feature. 4453 A feature MUST NOT reference itself, neither directly nor indirectly 4454 through a chain of other features. 4456 In order for a device to implement a feature that is dependent on any 4457 other features (i.e., the feature has one or more "if-feature" sub- 4458 statements), the device MUST also implement all the dependant 4459 features. 4461 7.18.1.1. The feature's Substatements 4463 +--------------+---------+-------------+ 4464 | substatement | section | cardinality | 4465 +--------------+---------+-------------+ 4466 | description | 7.19.3 | 0..1 | 4467 | if-feature | 7.18.2 | 0..n | 4468 | status | 7.19.2 | 0..1 | 4469 | reference | 7.19.4 | 0..1 | 4470 +--------------+---------+-------------+ 4472 7.18.2. The if-feature Statement 4474 The "if-feature" statement makes its parent statement conditional. 4475 The argument is the name of a feature, as defined by a "feature" 4476 statement. The parent statement is implemented by servers that 4477 support this feature. If a prefix is present on the feature name, it 4478 refers to a feature defined in the module which was imported with 4479 that prefix, or the local module if the prefix matches the local 4480 module's prefix. Otherwise a feature with the matching name MUST be 4481 defined in the current module or an included submodule. 4483 Since submodules cannot include the parent module, any features in 4484 the module which need to be exposed to submodules MUST be defined in 4485 a submodule. Submodules can then include this submodule to find the 4486 definition of the feature. 4488 7.18.3. The deviation Statement 4490 The deviation statement defines a hierarchy of a module which the 4491 device does not implement faithfully. The argument is a string that 4492 identifies the node in the schema tree where a deviation from the 4493 module occurs. This node is called the deviation's target node. The 4494 contents of the deviation statement give details about the deviation. 4496 The argument string is an absolute schema node identifier (see 4497 Section 6.5). 4499 Deviations define the way a device or class of devices deviate from a 4500 standard. This means that deviations MUST never be part of a 4501 published standard, since they are the mechanism for learning how 4502 implementations vary from the standards. 4504 Device deviations are strongly discouraged and MUST only be used as a 4505 last resort. Telling the application how a device fails to follow a 4506 standard is no substitute for implementing the standard correctly. A 4507 device that deviates from a module is not fully compliant with the 4508 module. 4510 However in some cases a particular device may not have the hardware 4511 or software ability to support parts of a standard module. When this 4512 occurs, the device makes a choice to treat attempts to configure 4513 unsupported parts of the module as either an error that is reported 4514 back to the unsuspecting application, or ignore those incoming 4515 requests. Neither choice is acceptable. 4517 Instead, YANG allows devices to document portions of a base module 4518 which are not supported or supported but with different syntax, by 4519 using the "deviation" statement. 4521 7.18.3.1. The deviation's Substatements 4523 +--------------+----------+-------------+ 4524 | substatement | section | cardinality | 4525 +--------------+----------+-------------+ 4526 | description | 7.19.3 | 0..1 | 4527 | deviate | 7.18.3.2 | 1..n | 4528 | reference | 7.19.4 | 0..1 | 4529 +--------------+----------+-------------+ 4531 7.18.3.2. The deviate Statement 4533 The "deviate" statement defines how the device's implementation of 4534 the target node deviates from its original definition. The argument 4535 is one of the strings "not-supported", "add", "replace", or "delete". 4537 The argument "not-supported" indicates that the target node is not 4538 implemented by this device. 4540 The argument "add" adds properties to the target node. The 4541 properties to add are identified as a substatement to the "deviate" 4542 statement. If the property can only appear once, the property MUST 4543 NOT exist in the target node. 4545 The argument "replace" replaces properties of the target node. The 4546 properties to replace are identified by substatements to the 4547 "deviate" statement. The property to replace MUST exist in the 4548 target node. 4550 The argument "delete" deletes properties from the target node. The 4551 properties to delete are identified by substatement to the "delete" 4552 statement. The substatement's keyword MUST match a corresponding 4553 keyword in the target node, and the argument's string MUST be equal 4554 to the corresponding keyword's argument string in the target node. 4556 The deviates's Substatements 4558 +--------------+---------+-------------+ 4559 | substatement | section | cardinality | 4560 +--------------+---------+-------------+ 4561 | config | 7.19.1 | 0..1 | 4562 | default | 7.6.4 | 0..1 | 4563 | mandatory | 7.6.5 | 0..1 | 4564 | max-elements | 7.7.4 | 0..1 | 4565 | min-elements | 7.7.3 | 0..1 | 4566 | must | 7.5.3 | 0..n | 4567 | type | 7.4 | 0..1 | 4568 | unique | 7.8.3 | 0..n | 4569 | units | 7.3.3 | 0..1 | 4570 +--------------+---------+-------------+ 4572 7.18.3.3. Usage Example 4574 In this example, the device is informing client applications that it 4575 does not support the old RFC867-style "daytime" service. 4577 deviation /base:system/base:daytime { 4578 deviate not-supported; 4579 } 4581 The following example sets a device-specific default value to a leaf 4582 that does not have a default value defined: 4584 deviation /base:system/base:user/base:type { 4585 deviate add { 4586 default "admin"; // new users are 'admin' by default 4587 } 4588 } 4590 In this example, the device limits the number of name servers to 3: 4592 deviation /base:system/base:name-server { 4593 deviate replace { 4594 max-elements 3; 4595 } 4596 } 4598 If the original definition is: 4600 container system { 4601 must "daytime or time"; 4602 ... 4603 } 4605 a device might remove this must constraint by doing: 4607 deviation "/base:system" { 4608 deviate delete { 4609 must "daytime or time"; 4610 } 4611 } 4613 7.19. Common Statements 4615 This section defines sub-statements common to several other 4616 statements. 4618 7.19.1. The config Statement 4620 The "config" statement takes as an argument the string "true" or 4621 "false". If "config" is "true", the definition represents 4622 configuration. Data nodes representing configuration will be part of 4623 the reply to a request, and can be sent in a 4624 or request. 4626 If "config" is "false", the definition represents state data. Data 4627 nodes representing state data will be part of the reply to a , 4628 but not to a request, and cannot be sent in a 4629 or request. 4631 If "config" is not specified, the default is the same as the parent 4632 schema node's "config" value. If the parent node is a "case" node, 4633 the value is the same as the "case" node's parent "choice" node. 4635 If the top node does not specify a "config" statement, the default is 4636 "true". 4638 If a node has "config" "false", no node underneath it can have 4639 "config" set to "true". 4641 7.19.2. The status Statement 4643 The "status" statement takes as an argument one of the strings 4644 "current", "deprecated", or "obsolete". 4646 o "current" means that the definition is current and valid. 4648 o "deprecated" indicates an obsolete definition, but it permits new/ 4649 continued implementation in order to foster interoperability with 4650 older/existing implementations. 4652 o "obsolete" means the definition is obsolete and SHOULD NOT be 4653 implemented and/or can be removed from implementations. 4655 If no status is specified, the default is "current". 4657 If a definition is "current", it MUST NOT reference a "deprecated" or 4658 "obsolete" definition within the same module. 4660 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4661 definition within the same module. 4663 For example, the following is illegal: 4665 typedef my-type { 4666 status deprecated; 4667 type int32; 4668 } 4670 leaf my-leaf { 4671 status current; 4672 type my-type; // illegal, since my-type is deprecated 4673 } 4675 7.19.3. The description Statement 4677 The "description" statement takes as an argument a string which 4678 contains a high-level textual description of this definition. 4680 7.19.4. The reference Statement 4682 The "reference" statement takes as an argument a string which is used 4683 to specify a textual cross-reference to an external document, either 4684 another module which defines related management information, or a 4685 document which provides additional information relevant to this 4686 definition. 4688 For example, a typedef for a "uri" data type could look like: 4690 typedef uri { 4691 type string; 4692 reference 4693 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 4694 ... 4695 } 4697 7.19.5. The when Statement 4699 The "when" statement makes its parent data definition statement 4700 conditional. The node defined by the parent data definition 4701 statement is only valid when the condition specified by the "when" 4702 statement is satisfied. The statement's argument is an XPath 4703 expression (see Section 6.4), which is used to formally specify this 4704 condition. If the XPath expression conceptually evaluates to "true" 4705 for a particular instance, then the node defined by the parent data 4706 definition statement is valid, otherwise it is not. 4708 See Section 8.3.2 for additional information. 4710 The XPath expression is conceptually evaluated in the following 4711 context, in addition to the definition in Section 6.4.1: 4713 o If the "when" statement is a child of an "augment" statement, then 4714 the context node is the augment's target node in the data tree, if 4715 the target node is a data node. Otherwise, the context node is 4716 the closest ancestor node to the target node which is also a data 4717 node. 4719 o If the "when" statement is a child of a "uses", "choice", or 4720 "case" statement, then the context node is the closest ancestor 4721 node to the "uses", "choice", or "case" node which is also a data 4722 node. 4724 o If the "when" statement is a child of any other data definition 4725 statement, the context node is the data definition's node in the 4726 data tree. 4728 o The accessible tree is made up of all nodes in the data tree, and 4729 all leafs with default values in use (see Section 7.6.1). 4731 The accessible tree depends on the context node: 4733 o If the context node represents configuration, the tree is the data 4734 in the NETCONF datastore where the context node exists. The XPath 4735 root node has all top-level configuration data nodes in all 4736 modules as children. 4738 o If the context node represents state data, the tree is all state 4739 data on the device, and the datastore. The XPath root 4740 node has all top-level data nodes in all modules as children. 4742 o If the context node represents notification content, the tree is 4743 the notification XML instance document. The XPath root node has 4744 the element representing the notification being defined as the 4745 only child. 4747 o If the context node represents RPC input parameters, the tree is 4748 the RPC XML instance document. The XPath root node has the 4749 element representing the RPC operation being defined as the only 4750 child. 4752 o If the context node represents RPC output parameters, the tree is 4753 the RPC reply instance document. The XPath root node has the 4754 elements representing the RPC output parameters as children. 4756 The result of the XPath expression is converted to a boolean value 4757 using the standard XPath rules. 4759 Note that the XPath expression is conceptually evaluated. This means 4760 that an implementation does not have to use an XPath evaluator on the 4761 device. The "when" statement can very well be implemented with 4762 specially written code. 4764 8. Constraints 4766 8.1. Constraints on Data 4768 Several YANG statements define constraints on valid data. These 4769 constraints are enforced in different ways, depending on what type of 4770 data the statement defines. 4772 o If the constraint is defined on configuration data, it MUST be 4773 true in a valid configuration data tree. 4775 o If the constraint is defined on state data, it MUST be true in a 4776 reply to a operation without a filter. 4778 o If the constraint is defined on notification content, it MUST be 4779 true in any notification instance. 4781 o If the constraint is defined on RPC input parameters, it MUST be 4782 true in an invocation of the RPC operation. 4784 o If the constraint is defined on RPC output parameters, it MUST be 4785 true in the RPC reply. 4787 8.2. Hierarchy of Constraints 4789 Conditions on parent nodes affect constraints on child nodes as a 4790 natural consequence of the hierarchy of nodes. "must", "mandatory", 4791 "min-elements", and "max-elements" constraints are not enforced if 4792 the parent node has a "when" or "if-feature" property that is not 4793 satisfied on the current device. 4795 In this example, the mandatory constraints on the "longitude" leaf is 4796 not enforced on devices that lack the "has-gps" feature: 4798 container location { 4799 if-feature has-gps; 4800 leaf longitude { 4801 mandatory true; 4802 ... 4803 } 4804 } 4806 8.3. Constraint Enforcement Model 4808 For configuration data, there are three windows when constraints MUST 4809 be enforced: 4811 o during parsing of RPC payloads 4813 o during processing of NETCONF operations 4815 o during validation 4817 Each of these scenarios are considered in the following sections. 4819 8.3.1. Payload Parsing 4821 When content arrives in RPC payloads, it MUST be well-formed XML, 4822 following the hierarchy and content rules defined by the set of 4823 models the device implements. 4825 o If a leaf data value does not match the type constraints for the 4826 leaf, including those defined in the type's range, length, and 4827 pattern properties, the server MUST reply with an "invalid-value" 4828 error-tag in the rpc-error, and with the error-app-tag and error- 4829 message associated with the constraint, if any exist. 4831 o If all keys of a list entry are not present, the server MUST reply 4832 with a "missing-element" error-tag in the rpc-error. 4834 o If data for more than one case branch of a choice is present, the 4835 server MUST reply with a "bad-element" in the rpc-error. 4837 o If data for a node tagged with "if-feature" is present, and the 4838 feature is not supported by the device, the server MUST reply with 4839 an "unknown-element" error-tag in the rpc-error. 4841 o If data for a node tagged with "when" is present, and the "when" 4842 condition evaluates to "false", the server MUST reply with an 4843 "unknown-element" error-tag in the rpc-error. 4845 o For insert handling, if the value for the attributes "before" and 4846 "after" are not valid for the type of the appropriate key leafs, 4847 the server MUST reply with a "bad-attribute" error-tag in the rpc- 4848 error. 4850 o If the attributes "before" and "after" appears in any element that 4851 is not a list whose "ordered-by" property is "user", the server 4852 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 4854 8.3.2. NETCONF Processing 4856 After the incoming data is parsed, the NETCONF server performs the 4857 operation by applying the data to the configuration 4858 datastore. During this processing the following errors MUST be 4859 detected: 4861 o Delete requests for non-existent data. 4863 o Create requests for existent data. 4865 o Insert requests with "before" or "after" parameters which do not 4866 exist. 4868 During processing: 4870 o If the NETCONF operation creates data nodes under a "choice", any 4871 existing nodes from other "case" branches are deleted by the 4872 server. 4874 o If the NETCONF operation modifies a data node such that any node's 4875 "when" expression becomes false, then the node with the "when" 4876 expression is deleted by the server. 4878 8.3.3. Validation 4880 When datastore processing is complete, the final contents MUST obey 4881 all validation constraints. This validation processing is performed 4882 at differing time according to the datastore. If the datastore is 4883 or , these constraints MUST be enforced at the 4884 end of the or operation. If the 4885 datastore is , the constraint enforcement is delayed 4886 until a or operation. 4888 o Any "must" constraints MUST evaluate to "true". 4890 o Any referential integrity constraints defined via the "path" 4891 statement MUST be satisfied. 4893 o Any "unique" constraints on lists MUST be satisfied. 4895 o The "min-elements" and "max-elements" constraints are enforced for 4896 lists and leaf-lists. 4898 9. Built-in Types 4900 YANG has a set of built-in types, similar to those of many 4901 programming languages, but with some differences due to special 4902 requirements from the management information model. 4904 Additional types may be defined, derived from those built-in types or 4905 from other derived types. Derived types may use subtyping to 4906 formally restrict the set of possible values. 4908 The different built-in types and their derived types allow different 4909 kinds of subtyping, namely length and regular expression restrictions 4910 of strings (Section 9.4.4, Section 9.4.6) and range restrictions of 4911 numeric types (Section 9.2.4). 4913 The lexical representation of a value of a certain type is used in 4914 the NETCONF messages, and when specifying default values and 4915 numerical ranges in YANG modules. 4917 9.1. Canonical representation 4919 For most types, there is a single canonical representation of the 4920 type's values. Some types allow multiple lexical representations of 4921 the same value, for example the positive integer "17" can be 4922 represented as "+17" or "17". Implementations MUST support all 4923 lexical representations specified in this document. 4925 When a NETCONF server sends data, it MUST be in the canonical form. 4927 Some types have a lexical representation that depends on the XML 4928 context in which they occur. These types do not have a canonical 4929 form. 4931 9.2. The Integer Built-in Types 4933 The integer built-in types are int8, int16, int32, int64, uint8, 4934 uint16, uint32, and uint64. They represent signed and unsigned 4935 integers of different sizes: 4937 int8 represents integer values between -128 and 127, inclusively. 4939 int16 represents integer values between -32768 and 32767, 4940 inclusively. 4942 int32 represents integer values between -2147483648 and 2147483647, 4943 inclusively. 4945 int64 represents integer values between -9223372036854775808 and 4946 9223372036854775807, inclusively. 4948 uint8 represents integer values between 0 and 255, inclusively. 4950 uint16 represents integer values between 0 and 65535, inclusively. 4952 uint32 represents integer values between 0 and 4294967295, 4953 inclusively. 4955 uint64 represents integer values between 0 and 18446744073709551615, 4956 inclusively. 4958 9.2.1. Lexical Representation 4960 An integer value is lexically represented as an optional sign ("+" or 4961 "-"), followed by a sequence of decimal digits. If no sign is 4962 specified, "+" is assumed. 4964 For convenience, when specifying a default value for an integer in a 4965 YANG module, an alternative lexical representation can be used, which 4966 represents the value in a hexadecimal or octal notation. The 4967 hexadecimal notation consists of an optional sign ("+" or "-"), the 4968 characters "0x" followed a number of hexadecimal digits, where 4969 letters may be upper- or lowercase. The octal notation consists of 4970 an optional sign ("+" or "-"), the character "0" followed a number of 4971 octal digits. 4973 Note that if a default value in a YANG module has a leading zero 4974 ("0"), it is interpreted as an octal number. In the XML instance 4975 documents, an integer is always interpreted as a decimal number, and 4976 leading zeros are allowed. 4978 Examples: 4980 // legal values 4981 +4711 // legal positive value 4982 4711 // legal positive value 4983 -123 // legal negative value 4984 0xf00f // legal positive hexadecimal value 4985 -0xf // legal negative hexadecimal value 4986 052 // legal positive octal value 4988 // illegal values 4989 - 1 // illegal intermediate space 4991 9.2.2. Canonical Form 4993 The canonical form of a positive integer does not include the sign 4994 "+". Leading zeros are prohibited. The value zero is represented as 4995 "0". 4997 9.2.3. Restrictions 4999 All integer types can be restricted with the "range" statement 5000 (Section 9.2.4). 5002 9.2.4. The range Statement 5004 The "range" statement, which is an optional substatement to the 5005 "type" statement, takes as an argument a range expression string. It 5006 is used to restrict integer and decimal built-in types, or types 5007 derived from those. 5009 A range consists of an explicit value, or a lower inclusive bound, 5010 two consecutive dots "..", and an upper inclusive bound. Multiple 5011 values or ranges can be given, separated by "|". If multiple values 5012 or ranges are given they all MUST be disjoint and MUST be in 5013 ascending order. If a range restriction is applied to an already 5014 range restricted type, the new restriction MUST be equal or more 5015 limiting, that is raising the lower bounds, reducing the upper 5016 bounds, removing explicit values or ranges, or splitting ranges into 5017 multiple ranges with intermediate gaps. Each explicit value and 5018 range boundary value given in the range expression MUST match the 5019 type being restricted, or be one of the special values "min" or 5020 "max". "min" and "max" means the minimum and maximum value accepted 5021 for the type being restricted, respectively. 5023 The range expression syntax is formally defined by the rule 5024 "range-arg" in Section 12. 5026 9.2.4.1. The range's Substatements 5028 +---------------+---------+-------------+ 5029 | substatement | section | cardinality | 5030 +---------------+---------+-------------+ 5031 | description | 7.19.3 | 0..1 | 5032 | error-app-tag | 7.5.4.2 | 0..1 | 5033 | error-message | 7.5.4.1 | 0..1 | 5034 | reference | 7.19.4 | 0..1 | 5035 +---------------+---------+-------------+ 5037 9.2.5. Usage Example 5039 typedef my-base-int32-type { 5040 type int32 { 5041 range "1..4 | 10..20"; 5042 } 5043 } 5045 typedef my-type1 { 5046 type my-base-int32-type { 5047 // legal range restriction 5048 range "11..max"; // 11..20 5049 } 5050 } 5052 typedef my-type2 { 5053 type my-base-int32-type { 5054 // illegal range restriction 5055 range "11..100"; 5056 } 5057 } 5059 9.3. The decimal64 Built-in Type 5061 The decimal64 type represents a subset of the real numbers, which can 5062 be represented by decimal numerals. The value space of decimal64 is 5063 the set of numbers that can be obtained by multiplying a 64 bit 5064 signed integer by a negative power of ten, i.e., expressible as 5065 "i x 10^-n" where i is an integer64 and n is an integer between 1 and 5066 18, inclusively. 5068 9.3.1. Lexical Representation 5070 A decimal64 value is lexically represented as an optional sign ("+" 5071 or "-"), followed by a sequence of decimal digits, optionally 5072 followed by a period ('.') as a decimal indicator and a sequence of 5073 decimal digits. If no sign is specified, "+" is assumed. 5075 9.3.2. Canonical Form 5077 The canonical form of a positive decimal64 does not include the sign 5078 "+". The decimal point is required. Leading and trailing zeros are 5079 prohibited, subject to the rule that there MUST be at least one digit 5080 before and after the decimal point. The value zero is represented as 5081 "0.0". 5083 9.3.3. Restrictions 5085 A decimal64 type can be restricted with the "range" statement 5086 (Section 9.2.4). 5088 9.3.4. The fraction-digits Statement 5090 The "fraction-digits" statement, which is a substatement to the 5091 "type" statement, MUST be present if the type is "decimal64". It 5092 takes as an argument an integer between 1 and 18, inclusively. It 5093 controls the size of the minimum difference between values of a 5094 decimal64 type, by restricting the value space to numbers that are 5095 expressible as "i x 10^-n" where n is the fraction-digits argument. 5097 The following table lists the minimum and maximum value for each 5098 fraction-digit value: 5100 +----------------+-----------------------+----------------------+ 5101 | fraction-digit | min | max | 5102 +----------------+-----------------------+----------------------+ 5103 | 1 | -922337203685477580.8 | 922337203685477580.7 | 5104 | 2 | -92233720368547758.08 | 92233720368547758.07 | 5105 | 3 | -9223372036854775.808 | 9223372036854775.807 | 5106 | 4 | -922337203685477.5808 | 922337203685477.5807 | 5107 | 5 | -92233720368547.75808 | 92233720368547.75807 | 5108 | 6 | -9223372036854.775808 | 9223372036854.775807 | 5109 | 7 | -922337203685.4775808 | 922337203685.4775807 | 5110 | 8 | -92233720368.54775808 | 92233720368.54775807 | 5111 | 9 | -9223372036.854775808 | 9223372036.854775807 | 5112 | 10 | -922337203.6854775808 | 922337203.6854775807 | 5113 | 11 | -92233720.36854775808 | 92233720.36854775807 | 5114 | 12 | -9223372.036854775808 | 9223372.036854775807 | 5115 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5116 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5117 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5118 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5119 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5120 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5121 +----------------+-----------------------+----------------------+ 5123 9.3.5. Usage Example 5125 typedef my-decimal { 5126 type decimal64 { 5127 fraction-digits 2; 5128 range "1 .. 3.14 | 10 | 20..max"; 5129 } 5130 } 5132 9.4. The string Built-in Type 5134 The string built-in type represents human readable strings in YANG. 5135 Legal characters are tab, carriage return, line feed, and the legal 5136 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 5138 ;; any Unicode character, excluding the surrogate blocks, 5139 ;; FFFE, and FFFF. 5140 string = *char 5141 char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD / 5142 %x10000-10FFFF 5144 9.4.1. Lexical Representation 5146 A string value is lexically represented as character data in the XML 5147 instance documents. 5149 9.4.2. Canonical Form 5151 The canonical form is the same as the lexical representation. No 5152 Unicode normalization is performed of string values. 5154 9.4.3. Restrictions 5156 A string can be restricted with the "length" (Section 9.4.4) and 5157 "pattern" (Section 9.4.6) statements. 5159 9.4.4. The length Statement 5161 The "length" statement, which is an optional substatement to the 5162 "type" statement, takes as an argument a length expression string. 5163 It is used to restrict the built-in type "string", or types derived 5164 from "string". 5166 A "length" statement restricts the number of Unicode characters in 5167 the string. 5169 A length range consists of an explicit value, or a lower bound, two 5170 consecutive dots "..", and an upper bound. Multiple values or ranges 5171 can be given, separated by "|". Length restricting values MUST NOT 5172 be negative. If multiple values or ranges are given, they all MUST 5173 be disjoint and MUST be in ascending order. If a length restriction 5174 is applied to an already length restricted type, the new restriction 5175 MUST be equal or more limiting, that is, raising the lower bounds, 5176 reducing the upper bounds, removing explicit length values or ranges, 5177 or splitting ranges into multiple ranges with intermediate gaps. A 5178 length value is a non-negative integer, or one of the special values 5179 "min" or "max". "min" and "max" means the minimum and maximum length 5180 accepted for the type being restricted, respectively. An 5181 implementation is not required to support a length value larger than 5182 18446744073709551615. 5184 The length expression syntax is formally defined by the rule 5185 "length-arg" in Section 12. 5187 9.4.4.1. The length's Substatements 5189 +---------------+---------+-------------+ 5190 | substatement | section | cardinality | 5191 +---------------+---------+-------------+ 5192 | description | 7.19.3 | 0..1 | 5193 | error-app-tag | 7.5.4.2 | 0..1 | 5194 | error-message | 7.5.4.1 | 0..1 | 5195 | reference | 7.19.4 | 0..1 | 5196 +---------------+---------+-------------+ 5198 9.4.5. Usage Example 5200 typedef my-base-str-type { 5201 type string { 5202 length "1..255"; 5203 } 5204 } 5206 type my-base-str-type { 5207 // legal length refinement 5208 length "11 | 42..max"; // 11 | 42..255 5209 } 5211 type my-base-str-type { 5212 // illegal length refinement 5213 length "1..999"; 5214 } 5216 9.4.6. The pattern Statement 5218 The "pattern" statement, which is an optional substatement to the 5219 "type" statement, takes as an argument a regular expression string, 5220 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5221 "string", or types derived from "string", to values that matches the 5222 pattern. 5224 If the type has multiple "pattern" statements, the expressions are 5225 ANDed together, i.e., all such expressions have to match. 5227 If a pattern restriction is applied to an already pattern restricted 5228 type, values must match all patterns in the base type, in addition to 5229 the new patterns. 5231 9.4.6.1. The pattern's Substatements 5233 +---------------+---------+-------------+ 5234 | substatement | section | cardinality | 5235 +---------------+---------+-------------+ 5236 | description | 7.19.3 | 0..1 | 5237 | error-app-tag | 7.5.4.2 | 0..1 | 5238 | error-message | 7.5.4.1 | 0..1 | 5239 | reference | 7.19.4 | 0..1 | 5240 +---------------+---------+-------------+ 5242 9.4.7. Usage Example 5244 With the following type: 5246 type string { 5247 length "0..4"; 5248 pattern "[0-9a-fA-F]*"; 5249 } 5251 the following strings match: 5253 AB // legal 5254 9A00 // legal 5256 and the following strings do not match: 5258 00ABAB // illegal, too long 5259 xx00 // illegal, bad characters 5261 9.5. The boolean Built-in Type 5263 The boolean built-in type represents a boolean value. 5265 9.5.1. Lexical Representation 5267 The lexical representation of a boolean value is a string with a 5268 value of "true" or "false". These values MUST be in lowercase. 5270 9.5.2. Canonical Form 5272 The canonical form is the same as the lexical representation. 5274 9.5.3. Restrictions 5276 A boolean cannot be restricted. 5278 9.6. The enumeration Built-in Type 5280 The enumeration built-in type represents values from a set of 5281 assigned names. 5283 9.6.1. Lexical Representation 5285 The lexical representation of an enumeration value is the assigned 5286 name string. 5288 9.6.2. Canonical Form 5290 The canonical form is the assigned name string. 5292 9.6.3. Restrictions 5294 An enumeration cannot be restricted. 5296 9.6.4. The enum Statement 5298 The "enum" statement, which is a substatement to the "type" 5299 statement, MUST be present if the type is "enumeration". It is 5300 repeatedly used to specify each assigned name of an enumeration type. 5301 It takes as an argument a string which is the assigned name. The 5302 string MUST NOT be empty and MUST NOT have any leading or trailing 5303 whitespace characters. The use of Unicode control codes SHOULD be 5304 avoided. 5306 The statement is optionally followed by a block of substatements 5307 which holds detailed enum information. 5309 All assigned names in an enumeration MUST be unique. 5311 9.6.4.1. The enum's Substatements 5313 +--------------+---------+-------------+ 5314 | substatement | section | cardinality | 5315 +--------------+---------+-------------+ 5316 | description | 7.19.3 | 0..1 | 5317 | reference | 7.19.4 | 0..1 | 5318 | status | 7.19.2 | 0..1 | 5319 | value | 9.6.4.2 | 0..1 | 5320 +--------------+---------+-------------+ 5322 9.6.4.2. The value Statement 5324 The "value" statement, which is optional, is used to associate an 5325 integer value with the assigned name for the enum. This integer 5326 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5327 unique within the enumeration type. The value is unused by YANG and 5328 the XML encoding, but is carried as a convenience to implementors. 5330 If a value is not specified, then one will be automatically assigned. 5331 If the enum sub-statement is the first one defined, the assigned 5332 value is zero (0), otherwise the assigned value is one greater than 5333 the current highest enum value. 5335 If the current highest value is equal to 2147483647, then an enum 5336 value MUST be specified for enum sub-statements following the one 5337 with the current highest value. 5339 9.6.5. Usage Example 5341 leaf myenum { 5342 type enumeration { 5343 enum zero; 5344 enum one; 5345 enum seven { 5346 value 7; 5347 } 5348 } 5349 } 5351 The lexical representation of the leaf "myenum" with value "seven" 5352 is: 5354 seven 5356 9.7. The bits Built-in Type 5358 The bits built-in type represents a bit set. That is, a bits value 5359 is a set of flags identified by small integer position numbers 5360 starting at 0. Each bit number has an assigned name. 5362 9.7.1. Restrictions 5364 A bits type cannot be restricted. 5366 9.7.2. Lexical Representation 5368 The lexical representation of the bits type is a space separated list 5369 of the individual bit values that are set. An empty string thus 5370 represents a value where no bits are set. 5372 9.7.3. Canonical Form 5374 In the canonical form, the bit values are separated by a single space 5375 character and they appear ordered by their position (see 5376 Section 9.7.4.2). 5378 9.7.4. The bit Statement 5380 The "bit" statement, which is a substatement to the "type" statement, 5381 MUST be present if the type is "bits". It is repeatedly used to 5382 specify each assigned named bit of a bits type. It takes as an 5383 argument a string which is the assigned name of the bit. It is 5384 followed by a block of substatements which holds detailed bit 5385 information. The assigned name follows the same syntax rules as an 5386 identifier (see Section 6.2). 5388 All assigned names in a bits type MUST be unique. 5390 9.7.4.1. The bit's Substatements 5392 +--------------+---------+-------------+ 5393 | substatement | section | cardinality | 5394 +--------------+---------+-------------+ 5395 | description | 7.19.3 | 0..1 | 5396 | reference | 7.19.4 | 0..1 | 5397 | status | 7.19.2 | 0..1 | 5398 | position | 9.7.4.2 | 0..1 | 5399 +--------------+---------+-------------+ 5401 9.7.4.2. The position Statement 5403 The "position" statement, which is optional, takes as an argument a 5404 non-negative integer value which specifies the bit's position within 5405 a hypothetical bit field. The position value MUST be in the range 0 5406 to 4294967295, and it MUST be unique within the bits type. The value 5407 is unused by YANG and the NETCONF messages, but is carried as a 5408 convenience to implementors. 5410 If a bit position is not specified, then one will be automatically 5411 assigned. If the bit sub-statement is the first one defined, the 5412 assigned value is zero (0), otherwise the assigned value is one 5413 greater than the current highest bit position. 5415 If the current highest bit position value is equal to 4294967295, 5416 then a position value MUST be specified for bit sub-statements 5417 following the one with the current highest position value. 5419 9.7.5. Usage Example 5421 Given the following leaf: 5423 leaf mybits { 5424 type bits { 5425 bit disable-nagle { 5426 position 0; 5427 } 5428 bit auto-sense-speed { 5429 position 1; 5430 } 5431 bit 10-Mb-only { 5432 position 2; 5433 } 5434 } 5435 default "auto-sense-speed"; 5436 } 5438 The lexical representation of this leaf with bit values disable-nagle 5439 and 10-Mb-only set would be: 5441 disable-nagle 10-Mb-only 5443 9.8. The binary Built-in Type 5445 The binary built-in type represents any binary data, i.e., a sequence 5446 of octets. 5448 9.8.1. Restrictions 5450 A binary can be restricted with the "length" (Section 9.4.4) 5451 statement. The length of a binary value is the number of octets it 5452 contains. 5454 9.8.2. Lexical Representation 5456 Binary values are encoded with the base64 encoding scheme (see 5457 [RFC4648], section 4). 5459 9.8.3. Canonical Form 5461 The canonical form of a binary value follow the rules in [RFC4648]. 5463 9.9. The leafref Built-in Type 5465 The leafref type is used to reference a particular leaf instance in 5466 the data tree. The "path" substatement (Section 9.9.2) selects a set 5467 of leaf instances, and the leafref value space is the set of values 5468 of these leaf instances. 5470 If the leaf with the leafref type represents configuration data, the 5471 leaf it refers to MUST also represent configuration. Such a leaf 5472 puts a constraint on valid data. All leafref nodes MUST reference 5473 existing leaf instances or leafs with default values in use (see 5474 Section 7.6.1) for the data to be valid. This constraint is enforced 5475 according to the rules in Section 8. 5477 There MUST NOT be any circular chains of leafrefs. 5479 If the leaf that the leafref refers to is conditional based on one or 5480 more feature (see Section 7.18.2), then the leaf with the leafref 5481 type MUST also be conditional based on at least the same set of 5482 features. 5484 9.9.1. Restrictions 5486 A leafref cannot be restricted. 5488 9.9.2. The path Statement 5490 The "path" statement, which is a substatement to the "type" 5491 statement, MUST be present if the type is "leafref". It takes as an 5492 argument a string which MUST refer to a leaf or leaf-list node. 5494 The syntax for a path argument is a subset of the XPath abbreviated 5495 syntax. Predicates are used only for constraining the values for the 5496 key nodes for list entries. Each predicate consists of exactly one 5497 equality test per key, and multiple adjacent predicates MAY be 5498 present if a list has multiple keys. The syntax is formally defined 5499 by the rule "path-arg" in Section 12. 5501 The predicates are only used when more than one key reference is 5502 needed to uniquely identify a leaf instance. This occurs if a list 5503 has multiple keys, or a reference to a leaf other than the key in a 5504 list is needed. In these cases, multiple leafrefs are typically 5505 specified, and predicates are used to tie them together. 5507 The "path" expression evaluates to a node set consisting of zero, one 5508 or more nodes. If the leaf with the leafref type represents 5509 configuration data, this node set MUST be non-empty. 5511 The "path" XPath expression is conceptually evaluated in the 5512 following context, in addition to the definition in Section 6.4.1: 5514 o The context node is the node in the data tree for which the "path" 5515 statement is defined. 5517 The accessible tree depends on the context node: 5519 o If the context node represents configuration data, the tree is the 5520 data in the NETCONF datastore where the context node exists. The 5521 XPath root node has all top-level configuration data nodes in all 5522 modules as children. 5524 o Otherwise the tree is all state data on the device, and the 5525 datastore. The XPath root node has all top-level data 5526 nodes in all modules as children. 5528 9.9.3. Lexical Representation 5530 A leafref value is encoded the same way as the leaf it references. 5532 9.9.4. Canonical Form 5534 The canonical form of a leafref is the same as the canonical form of 5535 the leaf it references. 5537 9.9.5. Usage Example 5539 With the following list: 5541 list interface { 5542 key "name"; 5543 leaf name { 5544 type string; 5545 } 5546 leaf admin-status { 5547 type admin-status; 5548 } 5549 list address { 5550 key "ip"; 5551 leaf ip { 5552 type yang:ip-address; 5553 } 5554 } 5555 } 5557 The following leafref refers to an existing interface: 5559 leaf mgmt-interface { 5560 type leafref { 5561 path "../interface/name"; 5562 } 5563 } 5565 An example of a corresponding XML snippet: 5567 5568 eth0 5569 5570 5571 lo 5572 5574 eth0 5576 The following leafrefs refer to an existing address of an interface: 5578 container default-address { 5579 leaf ifname { 5580 type leafref { 5581 path "../../interface/name"; 5582 } 5583 } 5584 leaf address { 5585 type leafref { 5586 path "../../interface[name = current()/../ifname]" 5587 + "/address/ip"; 5588 } 5589 } 5590 } 5592 An example of a corresponding XML snippet: 5594 5595 eth0 5596 up 5597
5598 192.0.2.1 5599
5600
5601 192.0.2.2 5602
5603
5604 5605 lo 5606 up 5607
5608 127.0.0.1 5609
5610
5612 5613 eth0 5614
192.0.2.2
5615
5617 The following list uses a leafref for one of its keys. This is 5618 similar to a foreign key in a relational database. 5620 list packet-filter { 5621 key "if-name filter-id"; 5622 leaf if-name { 5623 type leafref { 5624 path "/interface/name"; 5625 } 5626 } 5627 leaf filter-id { 5628 type uint32; 5629 } 5630 ... 5631 } 5633 An example of a corresponding XML snippet: 5635 5636 eth0 5637 up 5638
5639 192.0.2.1 5640
5641
5642 192.0.2.2 5643
5644
5646 5647 eth0 5648 1 5649 ... 5650 5651 5652 eth0 5653 2 5654 ... 5655 5657 The following notification defines two leafrefs to refer to an 5658 existing admin-status: 5660 notification link-failure { 5661 leaf if-name { 5662 type leafref { 5663 path "/interface/name"; 5664 } 5665 } 5666 leaf admin-status { 5667 type leafref { 5668 path 5669 "/interface[name = current()/../if-name]" 5670 + "/admin-status"; 5671 } 5672 } 5673 } 5675 An example of a corresponding XML notification: 5677 5679 2008-04-01T00:01:00Z 5680 5681 eth0 5682 up 5683 5684 5686 9.10. The identityref Built-in Type 5688 The identityref type is used to reference an existing identity (see 5689 Section 7.16). 5691 9.10.1. Restrictions 5693 An identityref cannot be restricted. 5695 9.10.2. The identityref's base Statement 5697 The "base" statement, which is a substatement to the "type" 5698 statement, MUST be present if the type is "identityref". The 5699 argument is the name of an identity, as defined by an "identity" 5700 statement. If a prefix is present on the identity name, it refers to 5701 an identity defined in the module which was imported with that 5702 prefix. Otherwise an identity with the matching name MUST be defined 5703 in the current module or an included submodule. 5705 Valid values for an identityref are any identities derived from the 5706 identityref's base identity. On a particular server, the valid 5707 values are further restricted to the set of identities defined in the 5708 modules supported by the server. 5710 9.10.3. Lexical Representation 5712 An identityref is encoded as the referred identity's Qualified Name 5713 as defined in [XML-NAMES]. If the Prefix is not present, the 5714 namespace of the identityref is the default namespace in effect on 5715 the element which contains the identityref value. 5717 When an identityref is given a default value using the "default" 5718 statement, the identity name in the default value MAY have a prefix. 5719 If a prefix is present on the identity name, it refers to an identity 5720 defined in the module which was imported with that prefix. Otherwise 5721 an identity with the matching name MUST be defined in the current 5722 module or an included submodule. 5724 9.10.4. Canonical Form 5726 Since the lexical form depends on the XML context in which the value 5727 occurs, this type does not have a canonical form. 5729 9.10.5. Usage Example 5731 With the identity definitions in Section 7.16.3, and the following 5732 module: 5734 module my-crypto { 5736 namespace "http://example.com/my-crypto"; 5737 prefix mc; 5739 import "crypto-base" { 5740 prefix "crypto"; 5741 } 5743 identity aes { 5744 base "crypto:crypto-alg"; 5745 } 5747 leaf crypto { 5748 type identityref { 5749 base "crypto:crypto-alg"; 5750 } 5751 } 5752 } 5754 The leaf "crypto" will be encoded as follows, if the value is the 5755 "des3" identity defined in the "des" module: 5757 des:des3 5759 Any prefixes used in the encoding are local to each instance 5760 encoding. This means that the same identityref may be encoded 5761 differently by different implementations. For example, the following 5762 example encodes the same leaf as above: 5764 x:des3 5766 If the "crypto" leaf's value instead is "aes" defined in the 5767 "my-crypto" module it can be encoded as: 5769 mc:aes 5771 or, using the default namespace: 5773 aes 5775 9.11. The empty Built-in Type 5777 The empty built-in type represents a leaf that does not have any 5778 value, it conveys information by its presence or absence. 5780 An empty type cannot have a default value. 5782 9.11.1. Restrictions 5784 An empty type cannot be restricted. 5786 9.11.2. Lexical Representation 5788 Not applicable. 5790 9.11.3. Canonical Form 5792 Not applicable. 5794 9.11.4. Usage Example 5796 The following leaf 5798 leaf enable-qos { 5799 type empty; 5800 } 5802 will be encoded as 5804 5806 if it exists. 5808 9.12. The union Built-in Type 5810 The union built-in type represents a value that corresponds to one of 5811 its member types. 5813 When the type is "union", the "type" statement (Section 7.4) MUST be 5814 present. It is used to repeatedly specify each member type of the 5815 union. It takes as an argument a string which is the name of a 5816 member type. 5818 A member type can be of any built-in or derived type, except it MUST 5819 NOT be one of the built-in types "empty" or "leafref". 5821 When a string representing a union data type is validated, the string 5822 is validated against each member type, in the order they are 5823 specified in the type statement, until a match is found. 5825 Any default values or units properties defined in the member types 5826 are not inherited by the union type. 5828 Example: 5830 type union { 5831 type int32; 5832 type enumeration { 5833 enum "unbounded"; 5834 } 5835 } 5837 9.12.1. Restrictions 5839 A union cannot be restricted. However, each member type can be 5840 restricted, based on the rules defined in Section 9. 5842 9.12.2. Lexical Representation 5844 The lexical representation of an union is a value that corresponds to 5845 the representation of any one of the member types. 5847 9.12.3. Canonical Form 5849 The canonical form of a union value is the same as the canonical form 5850 of the member type of the value. 5852 9.13. The instance-identifier Built-in Type 5854 The instance-identifier built-in type is used to uniquely identify a 5855 particular instance node in the data tree. 5857 The syntax for an instance-identifier is a subset of the XPath 5858 abbreviated syntax, formally defined by the rule 5859 "instance-identifier" in Section 12. It is used to uniquely identify 5860 a node in the data tree. Predicates are used only for specifying the 5861 values for the key nodes for list entries, a value of a leaf-list 5862 entry, or a positional index for list without keys. For identifying 5863 list entries with keys, each predicate consists of one equality test 5864 per key, and each key MUST have a corresponding predicate. 5866 If the leaf with the instance-identifier type represents 5867 configuration data, and the "require-instance" property 5868 (Section 9.13.2) is "true", the node it refers to MUST also represent 5869 configuration. Such a leaf puts a constraint on valid data. All 5870 such leaf nodes MUST reference existing nodes or leaf nodes with 5871 their default value in use (see Section 7.6.1) for the data to be 5872 valid. This constraint is enforced according to the rules in 5873 Section 8. 5875 The "instance-identifier" XPath expression is conceptually evaluated 5876 in the following context, in addition to the definition in 5877 Section 6.4.1: 5879 o The context node is the root node in the accessible tree. 5881 The accessible tree depends on the leaf with the instance-identifier 5882 type: 5884 o If this leaf represents configuration data, the tree is the data 5885 in the NETCONF datastore where the leaf exists. The XPath root 5886 node has all top-level configuration data nodes in all modules as 5887 children. 5889 o Otherwise the tree is all state data on the device, and the 5890 datastore. The XPath root node has all top-level data 5891 nodes in all modules as children. 5893 9.13.1. Restrictions 5895 An instance-identifier can be restricted with the "require-instance" 5896 statement (Section 9.13.2). 5898 9.13.2. The require-instance Statement 5900 The "require-instance" statement, which is a substatement to the 5901 "type" statement, MAY be present if the type is 5902 "instance-identifier". It takes as an argument the string "true" or 5903 "false". If this statement is not present, it defaults to "true". 5905 If "require-instance" is "true", it means that the instance being 5906 referred MUST exist for the data to be valid. This constraint is 5907 enforced according to the rules in Section 8. 5909 If "require-instance" is "false", it means that the instance being 5910 referred MAY exist in valid data. 5912 9.13.3. Lexical Representation 5914 An instance-identifier value is lexically represented as a string. 5915 All node names in an instance-identifier value MUST be qualified with 5916 explicit namespace prefixes and these prefixes MUST be declared in 5917 the XML namespace scope in the instance-identifier's XML element. 5919 Any prefixes used in the encoding are local to each instance 5920 encoding. This means that the same instance-identifier may be 5921 encoded differently by different implementations. 5923 9.13.4. Canonical Form 5925 Since the lexical form depends on the XML context in which the value 5926 occurs, this type does not have a canonical form. 5928 9.13.5. Usage Example 5930 The following are examples of instance identifiers: 5932 /* instance-identifier for a container */ 5933 /ex:system/ex:services/ex:ssh 5935 /* instance-identifier for a leaf */ 5936 /ex:system/ex:services/ex:ssh/ex:port 5938 /* instance-identifier for a list entry */ 5939 /ex:system/ex:user[ex:name='fred'] 5941 /* instance-identifier for a leaf in a list entry */ 5942 /ex:system/ex:user[ex:name='fred']/ex:type 5944 /* instance-identifier for a list entry with two keys */ 5945 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 5947 /* instance-identifier for a leaf-list entry */ 5948 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 5950 /* instance-identifier for a list entry without keys */ 5951 /ex:stats/ex:port[3] 5953 10. Updating a Module 5955 As experience is gained with a module, it may be desirable to revise 5956 that module. However, changes are not allowed if they have any 5957 potential to cause interoperability problems between a client using 5958 an original specification and a server using an updated 5959 specification. 5961 For any published change, a new "revision" statement (Section 7.1.9) 5962 MUST be included in front of the existing revision statements. If 5963 there are no existing revision statements, then one MUST be added to 5964 identify the new revision. Furthermore, any necessary changes MUST 5965 be applied to any meta data statements, including the "organization" 5966 and "contact" statements (Section 7.1.7, Section 7.1.8). 5968 Note that definitions contained in a module are available to be 5969 imported by any other module, and are referenced in "import" 5970 statements via the module name. Thus, a module name MUST NOT be 5971 changed. Furthermore, the "namespace" statement MUST NOT be changed, 5972 since all XML elements are qualified by the namespace. 5974 Obsolete definitions MUST NOT be removed from modules since their 5975 identifiers may still be referenced by other modules. 5977 A definition may be revised in any of the following ways: 5979 o An "enumeration" type may have new enums added, provided the old 5980 enums's values do not change. 5982 o A "bits" type may have new bits added, provided the old bit 5983 positions do not change. 5985 o A "range", "length", or "pattern" statement may expand the allowed 5986 value space. 5988 o A "default" statement may be added to a leaf that does not have a 5989 default value (either directly or indirectly through its type). 5991 o A "units" statement may be added. 5993 o A "reference" statement may be added or updated. 5995 o A "must" statement may be removed or its constraint relaxed. 5997 o A "mandatory" statement may be removed or changed from "true" to 5998 "false". 6000 o A "min-elements" statement may be removed, or changed to require 6001 fewer elements. 6003 o A "max-elements" statement may be removed, or changed to allow 6004 more elements. 6006 o A "description" statement may be added or clarified without 6007 changing the semantics of the definition. 6009 o New typedefs, groupings, rpc, notifications, extensions, features, 6010 and identities may be added. 6012 o New data definition statements may be added if they do not add 6013 mandatory nodes (Section 3.1) to existing nodes or at the top- 6014 level in a module or submodule, or if they are conditionally 6015 dependent on a new feature (i.e., have a "if-feature" statement 6016 which refers to a new feature). 6018 o A new "case" statement may be added. 6020 o A node that represented state data may be changed to represent 6021 configuration, provided it is not mandatory (Section 3.1). 6023 o An "if-feature" statement may be removed, provided its node is not 6024 mandatory (Section 3.1). 6026 o A "status" statement may be added, or changed from "current" to 6027 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 6029 o A "type" statement may be replaced with another "type" statement 6030 which does not change the syntax or semantics of the type. For 6031 example, an inline type definition may be replaced with a typedef, 6032 but a int8 type cannot be replaced by a int16, since the syntax 6033 would change. 6035 o Any set of data definition nodes may be replaced with another set 6036 of syntactically and semantically equivalent nodes. For example, 6037 a set of leafs may be replaced by a uses of a grouping with the 6038 same leafs. 6040 o A module may be split into a set of submodules, or submodule may 6041 be removed, provided the definitions in the module do not change 6042 in any other way than allowed here. 6044 o The "prefix" statement may be changed, provided all local uses of 6045 the prefix also are changed. 6047 Otherwise, if the semantics of any previous definition are changed 6048 (i.e., if a non-editorial change is made to any definition other than 6049 those specifically allowed above), then this MUST be achieved by a 6050 new definition with a new identifier. 6052 In statements which have any data definition statements as 6053 substatements, those data definition substatements MUST NOT be 6054 reordered. 6056 11. YIN 6058 A YANG module can be translated into an alternative XML-based syntax 6059 called YIN. The translated module is called a YIN module. This 6060 section describes symmetric mapping rules between the two formats. 6062 The YANG and YIN formats contain equivalent information using 6063 different notations. The YIN notation enables developers to 6064 represent YANG data models in XML and therefore use the rich set of 6065 XML-based tools for data filtering and validation, automated 6066 generation of code and documentation, and other tasks. Tools like 6067 XSLT or XML validators can be utilized. 6069 The mapping between YANG and YIN does not modify the information 6070 content of the model. Comments and whitespace are not preserved. 6072 11.1. Formal YIN Definition 6074 There is a one-to-one correspondence between YANG keywords and YIN 6075 elements. The local name of a YIN element is identical to the 6076 corresponding YANG keyword. This means in particular that the 6077 document element (root) of a YIN document is always or 6078 . 6080 YIN elements corresponding to the YANG keywords belong to the 6081 namespace whose associated URI is 6082 "urn:ietf:params:xml:ns:yang:yin:1". 6084 YIN elements corresponding to extension keywords belong to the 6085 namespace of the YANG module where the extension keyword is declared 6086 via the "extension" statement. 6088 The names of all YIN elements MUST be properly qualified with their 6089 namespaces specified above using the standard mechanisms of 6090 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 6092 The argument of a YANG statement is represented in YIN either as an 6093 XML attribute or a subelement of the keyword element. Table 1 6094 defines the mapping for the set of YANG keywords. For extensions, 6095 the argument mapping is specified within the "extension" statement 6096 (see Section 7.17). The following rules hold for arguments: 6098 o If the argument is represented as an attribute, this attribute has 6099 no namespace. 6101 o If the argument is represented as an element, it is qualified by 6102 the same namespace as its parent keyword element. 6104 o If the argument is represented as an element, it MUST be the first 6105 child of the keyword element. 6107 Substatements of a YANG statement are represented as (additional) 6108 children of the keyword element and their relative order MUST be the 6109 same as the order of substatements in YANG. 6111 Comments in YANG MAY be mapped to XML comments. 6113 Mapping of arguments of the YANG statements. 6115 +------------------+---------------+-------------+ 6116 | keyword | argument name | yin-element | 6117 +------------------+---------------+-------------+ 6118 | anyxml | name | false | 6119 | argument | name | false | 6120 | augment | target-node | false | 6121 | base | name | false | 6122 | belongs-to | module | false | 6123 | bit | name | false | 6124 | case | name | false | 6125 | choice | name | false | 6126 | config | value | false | 6127 | contact | text | true | 6128 | container | name | false | 6129 | default | value | false | 6130 | description | text | true | 6131 | deviate | value | false | 6132 | deviation | target-node | false | 6133 | enum | name | false | 6134 | error-app-tag | value | false | 6135 | error-message | value | true | 6136 | extension | name | false | 6137 | feature | name | false | 6138 | fraction-digits | value | false | 6139 | grouping | name | false | 6140 | identity | name | false | 6141 | if-feature | name | false | 6142 | import | module | false | 6143 | include | module | false | 6144 | input | | n/a | 6145 | key | value | false | 6146 | leaf | name | false | 6147 | leaf-list | name | false | 6148 | length | value | false | 6149 | list | name | false | 6150 | mandatory | value | false | 6151 | max-elements | value | false | 6152 | min-elements | value | false | 6153 | module | name | false | 6154 | must | condition | false | 6155 | namespace | uri | false | 6156 | notification | name | false | 6157 | ordered-by | value | false | 6158 | organization | text | true | 6159 | output | | n/a | 6160 | path | value | false | 6161 | pattern | value | false | 6162 | position | value | false | 6163 | prefix | value | false | 6164 | presence | value | false | 6165 | range | value | false | 6166 | reference | text | true | 6167 | refine | target-node | false | 6168 | require-instance | value | false | 6169 | revision | date | false | 6170 | revision-date | date | false | 6171 | rpc | name | false | 6172 | status | value | false | 6173 | submodule | name | false | 6174 | type | name | false | 6175 | typedef | name | false | 6176 | unique | tag | false | 6177 | units | name | false | 6178 | uses | name | false | 6179 | value | value | false | 6180 | when | condition | false | 6181 | yang-version | value | false | 6182 | yin-element | value | false | 6183 +------------------+---------------+-------------+ 6185 Table 1 6187 11.1.1. Usage Example 6189 The following YANG module: 6191 module acme-foo { 6192 namespace "http://acme.example.com/foo"; 6193 prefix "acfoo"; 6195 import my-extensions { 6196 prefix "myext"; 6197 } 6199 list interface { 6200 key "name"; 6201 leaf name { 6202 type string; 6203 } 6205 leaf mtu { 6206 type uint32; 6207 description "The MTU of the interface."; 6208 myext:c-define "MY_MTU"; 6209 } 6210 } 6211 } 6213 where the extension "c-define" is defined in Section 7.17.3, is 6214 translated into the following YIN: 6216 6221 6222 6224 6225 6226 6228 6229 6230 6231 6232 6233 6234 6235 6236 The MTU of the interface. 6237 6238 6239 6240 6241 6243 12. YANG ABNF Grammar 6245 In YANG, almost all statements are unordered. The ABNF grammar 6246 [RFC5234] defines the canonical order. To improve module 6247 readability, it is RECOMMENDED that clauses be entered in this order. 6249 Within the ABNF grammar, unordered statements are marked with 6250 comments. 6252 This grammar assumes that the scanner replaces YANG comments with a 6253 single space character. 6255 file "yang.abnf" 6257 module-stmt = optsep module-keyword sep identifier-arg-str 6258 optsep 6259 "{" stmtsep 6260 module-header-stmts 6261 linkage-stmts 6262 meta-stmts 6263 revision-stmts 6264 body-stmts 6265 "}" optsep 6267 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 6268 optsep 6269 "{" stmtsep 6270 submodule-header-stmts 6271 linkage-stmts 6272 meta-stmts 6273 revision-stmts 6274 body-stmts 6275 "}" optsep 6277 module-header-stmts = ;; these stmts can appear in any order 6278 [yang-version-stmt stmtsep] 6279 namespace-stmt stmtsep 6280 prefix-stmt stmtsep 6282 submodule-header-stmts = 6283 ;; these stmts can appear in any order 6284 [yang-version-stmt stmtsep] 6285 belongs-to-stmt stmtsep 6287 meta-stmts = ;; these stmts can appear in any order 6288 [organization-stmt stmtsep] 6289 [contact-stmt stmtsep] 6290 [description-stmt stmtsep] 6292 [reference-stmt stmtsep] 6294 linkage-stmts = ;; these stmts can appear in any order 6295 *(import-stmt stmtsep) 6296 *(include-stmt stmtsep) 6298 revision-stmts = *(revision-stmt stmtsep) 6300 body-stmts = *((extension-stmt / 6301 feature-stmt / 6302 identity-stmt / 6303 typedef-stmt / 6304 grouping-stmt / 6305 data-def-stmt / 6306 augment-stmt / 6307 rpc-stmt / 6308 notification-stmt / 6309 deviation-stmt) stmtsep) 6311 data-def-stmt = container-stmt / 6312 leaf-stmt / 6313 leaf-list-stmt / 6314 list-stmt / 6315 choice-stmt / 6316 anyxml-stmt / 6317 uses-stmt 6319 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 6320 optsep stmtend 6322 yang-version-arg-str = < a string which matches the rule 6323 yang-version-arg > 6325 yang-version-arg = "1" 6327 import-stmt = import-keyword sep identifier-arg-str optsep 6328 "{" stmtsep 6329 prefix-stmt stmtsep 6330 [revision-date-stmt stmtsep] 6331 "}" 6333 include-stmt = include-keyword sep identifier-arg-str optsep 6334 (";" / 6335 "{" stmtsep 6336 [revision-date-stmt stmtsep] 6337 "}") 6339 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 6340 uri-str = < a string which matches the rule 6341 URI in RFC 3986 > 6343 prefix-stmt = prefix-keyword sep prefix-arg-str 6344 optsep stmtend 6346 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6347 optsep 6348 "{" stmtsep 6349 prefix-stmt stmtsep 6350 "}" 6352 organization-stmt = organization-keyword sep string 6353 optsep stmtend 6355 contact-stmt = contact-keyword sep string optsep stmtend 6357 description-stmt = description-keyword sep string optsep 6358 stmtend 6360 reference-stmt = reference-keyword sep string optsep stmtend 6362 units-stmt = units-keyword sep string optsep stmtend 6364 revision-stmt = revision-keyword sep revision-date optsep 6365 (";" / 6366 "{" stmtsep 6367 [description-stmt stmtsep] 6368 [reference-stmt stmtsep] 6369 "}") 6371 revision-date = date-arg-str 6373 revision-date-stmt = revision-date-keyword sep revision-date stmtend 6375 extension-stmt = extension-keyword sep identifier-arg-str optsep 6376 (";" / 6377 "{" stmtsep 6378 ;; these stmts can appear in any order 6379 [argument-stmt stmtsep] 6380 [status-stmt stmtsep] 6381 [description-stmt stmtsep] 6382 [reference-stmt stmtsep] 6383 "}") 6385 argument-stmt = argument-keyword sep identifier-arg-str optsep 6386 (";" / 6387 "{" stmtsep 6389 [yin-element-stmt stmtsep] 6390 "}") 6392 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 6393 stmtend 6395 yin-element-arg-str = < a string which matches the rule 6396 yin-element-arg > 6398 yin-element-arg = true-keyword / false-keyword 6400 identity-stmt = identity-keyword sep identifier-arg-str optsep 6401 (";" / 6402 "{" stmtsep 6403 ;; these stmts can appear in any order 6404 [base-stmt stmtsep] 6405 [status-stmt stmtsep] 6406 [description-stmt stmtsep] 6407 [reference-stmt stmtsep] 6408 "}") 6410 base-stmt = base-keyword sep identifier-ref-arg-str 6411 optsep stmtend 6413 feature-stmt = feature-keyword sep identifier-arg-str optsep 6414 (";" / 6415 "{" stmtsep 6416 ;; these stmts can appear in any order 6417 *(if-feature-stmt stmtsep) 6418 [status-stmt stmtsep] 6419 [description-stmt stmtsep] 6420 [reference-stmt stmtsep] 6421 "}") 6423 if-feature-stmt = if-feature-keyword sep identifier-ref-arg-str 6424 optsep stmtend 6426 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 6427 "{" stmtsep 6428 ;; these stmts can appear in any order 6429 type-stmt stmtsep 6430 [units-stmt stmtsep] 6431 [default-stmt stmtsep] 6432 [status-stmt stmtsep] 6433 [description-stmt stmtsep] 6434 [reference-stmt stmtsep] 6435 "}" 6437 type-stmt = type-keyword sep identifier-ref-arg-str optsep 6438 (";" / 6439 "{" stmtsep 6440 type-body-stmts 6441 "}") 6443 type-body-stmts = numerical-restrictions / 6444 decimal64-specification / 6445 string-restrictions / 6446 enum-specification / 6447 leafref-specification / 6448 identityref-specification / 6449 instance-identifier-specification / 6450 bits-specification / 6451 union-specification 6453 numerical-restrictions = range-stmt stmtsep 6455 range-stmt = range-keyword sep range-arg-str optsep 6456 (";" / 6457 "{" stmtsep 6458 ;; these stmts can appear in any order 6459 [error-message-stmt stmtsep] 6460 [error-app-tag-stmt stmtsep] 6461 [description-stmt stmtsep] 6462 [reference-stmt stmtsep] 6463 "}") 6465 decimal64-specification = fraction-digits-stmt 6467 fraction-digits-stmt = fraction-digits-keyword sep 6468 fraction-digits-arg-str stmtend 6470 fraction-digits-arg-str = < a string which matches the rule 6471 fraction-digits-arg > 6473 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 6474 "5" / "6" / "7" / "8"]) 6475 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 6477 string-restrictions = ;; these stmts can appear in any order 6478 [length-stmt stmtsep] 6479 *(pattern-stmt stmtsep) 6481 length-stmt = length-keyword sep length-arg-str optsep 6482 (";" / 6483 "{" stmtsep 6484 ;; these stmts can appear in any order 6486 [error-message-stmt stmtsep] 6487 [error-app-tag-stmt stmtsep] 6488 [description-stmt stmtsep] 6489 [reference-stmt stmtsep] 6490 "}") 6492 pattern-stmt = pattern-keyword sep string optsep 6493 (";" / 6494 "{" stmtsep 6495 ;; these stmts can appear in any order 6496 [error-message-stmt stmtsep] 6497 [error-app-tag-stmt stmtsep] 6498 [description-stmt stmtsep] 6499 [reference-stmt stmtsep] 6500 "}") 6502 default-stmt = default-keyword sep string stmtend 6504 enum-specification = 1*(enum-stmt stmtsep) 6506 enum-stmt = enum-keyword sep string optsep 6507 (";" / 6508 "{" stmtsep 6509 ;; these stmts can appear in any order 6510 [value-stmt stmtsep] 6511 [status-stmt stmtsep] 6512 [description-stmt stmtsep] 6513 [reference-stmt stmtsep] 6514 "}") 6516 leafref-specification = 6517 ;; these stmts can appear in any order 6518 path-stmt stmtsep 6519 [require-instance-stmt stmtsep] 6521 path-stmt = path-keyword sep path-arg-str stmtend 6523 require-instance-stmt = require-instance-keyword sep 6524 require-instance-arg-str stmtend 6526 require-instance-arg-str = < a string which matches the rule 6527 require-instance-arg > 6529 require-instance-arg = true-keyword / false-keyword 6531 instance-identifier-specification = 6532 [require-instance-stmt stmtsep] 6534 identityref-specification = 6535 base-stmt stmtsep 6537 union-specification = 1*(type-stmt stmtsep) 6539 bits-specification = 1*(bit-stmt stmtsep) 6541 bit-stmt = bit-keyword sep identifier-arg-str optsep 6542 (";" / 6543 "{" stmtsep 6544 ;; these stmts can appear in any order 6545 [position-stmt stmtsep] 6546 [status-stmt stmtsep] 6547 [description-stmt stmtsep] 6548 [reference-stmt stmtsep] 6549 "}" 6550 "}") 6552 position-stmt = position-keyword sep 6553 position-value-arg-str stmtend 6555 position-value-arg-str = < a string which matches the rule 6556 position-value-arg > 6558 position-value-arg = non-negative-integer-value 6560 status-stmt = status-keyword sep status-arg-str stmtend 6562 status-arg-str = < a string which matches the rule 6563 status-arg > 6565 status-arg = current-keyword / 6566 obsolete-keyword / 6567 deprecated-keyword 6569 config-stmt = config-keyword sep 6570 config-arg-str stmtend 6572 config-arg-str = < a string which matches the rule 6573 config-arg > 6575 config-arg = true-keyword / false-keyword 6577 mandatory-stmt = mandatory-keyword sep 6578 mandatory-arg-str stmtend 6580 mandatory-arg-str = < a string which matches the rule 6581 mandatory-arg > 6583 mandatory-arg = true-keyword / false-keyword 6585 presence-stmt = presence-keyword sep string stmtend 6587 ordered-by-stmt = ordered-by-keyword sep 6588 ordered-by-arg-str stmtend 6590 ordered-by-arg-str = < a string which matches the rule 6591 ordered-by-arg > 6593 ordered-by-arg = user-keyword / system-keyword 6595 must-stmt = must-keyword sep string optsep 6596 (";" / 6597 "{" stmtsep 6598 ;; these stmts can appear in any order 6599 [error-message-stmt stmtsep] 6600 [error-app-tag-stmt stmtsep] 6601 [description-stmt stmtsep] 6602 [reference-stmt stmtsep] 6603 "}") 6605 error-message-stmt = error-message-keyword sep string stmtend 6607 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 6609 min-elements-stmt = min-elements-keyword sep 6610 min-value-arg-str stmtend 6612 min-value-arg-str = < a string which matches the rule 6613 min-value-arg > 6615 min-value-arg = non-negative-integer-value 6617 max-elements-stmt = max-elements-keyword sep 6618 max-value-arg-str stmtend 6620 max-value-arg-str = < a string which matches the rule 6621 max-value-arg > 6623 max-value-arg = unbounded-keyword / 6624 positive-integer-value 6626 value-stmt = value-keyword sep integer-value stmtend 6628 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 6629 (";" / 6630 "{" stmtsep 6631 ;; these stmts can appear in any order 6632 [status-stmt stmtsep] 6633 [description-stmt stmtsep] 6634 [reference-stmt stmtsep] 6635 *((typedef-stmt / 6636 grouping-stmt) stmtsep) 6637 *(data-def-stmt stmtsep) 6638 "}") 6640 container-stmt = container-keyword sep identifier-arg-str optsep 6641 (";" / 6642 "{" stmtsep 6643 ;; these stmts can appear in any order 6644 [when-stmt stmtsep] 6645 *(if-feature-stmt stmtsep) 6646 *(must-stmt stmtsep) 6647 [presence-stmt stmtsep] 6648 [config-stmt stmtsep] 6649 [status-stmt stmtsep] 6650 [description-stmt stmtsep] 6651 [reference-stmt stmtsep] 6652 *((typedef-stmt / 6653 grouping-stmt) stmtsep) 6654 *(data-def-stmt stmtsep) 6655 "}") 6657 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 6658 "{" stmtsep 6659 ;; these stmts can appear in any order 6660 [when-stmt stmtsep] 6661 *(if-feature-stmt stmtsep) 6662 type-stmt stmtsep 6663 [units-stmt stmtsep] 6664 *(must-stmt stmtsep) 6665 [default-stmt stmtsep] 6666 [config-stmt stmtsep] 6667 [mandatory-stmt stmtsep] 6668 [status-stmt stmtsep] 6669 [description-stmt stmtsep] 6670 [reference-stmt stmtsep] 6671 "}" 6673 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 6674 "{" stmtsep 6675 ;; these stmts can appear in any order 6676 [when-stmt stmtsep] 6677 *(if-feature-stmt stmtsep) 6678 type-stmt stmtsep 6680 [units-stmt stmtsep] 6681 *(must-stmt stmtsep) 6682 [config-stmt stmtsep] 6683 [min-elements-stmt stmtsep] 6684 [max-elements-stmt stmtsep] 6685 [ordered-by-stmt stmtsep] 6686 [status-stmt stmtsep] 6687 [description-stmt stmtsep] 6688 [reference-stmt stmtsep] 6689 "}" 6691 list-stmt = list-keyword sep identifier-arg-str optsep 6692 "{" stmtsep 6693 ;; these stmts can appear in any order 6694 [when-stmt stmtsep] 6695 *(if-feature-stmt stmtsep) 6696 *(must-stmt stmtsep) 6697 [key-stmt stmtsep] 6698 *(unique-stmt stmtsep) 6699 [config-stmt stmtsep] 6700 [min-elements-stmt stmtsep] 6701 [max-elements-stmt stmtsep] 6702 [ordered-by-stmt stmtsep] 6703 [status-stmt stmtsep] 6704 [description-stmt stmtsep] 6705 [reference-stmt stmtsep] 6706 *((typedef-stmt / 6707 grouping-stmt) stmtsep) 6708 1*(data-def-stmt stmtsep) 6709 "}" 6711 key-stmt = key-keyword sep key-arg-str stmtend 6713 key-arg-str = < a string which matches the rule 6714 key-arg > 6716 key-arg = node-identifier *(sep node-identifier) 6718 unique-stmt = unique-keyword sep unique-arg-str stmtend 6720 unique-arg-str = < a string which matches the rule 6721 unique-arg > 6723 unique-arg = descendant-schema-nodeid 6724 *(sep descendant-schema-nodeid) 6726 choice-stmt = choice-keyword sep identifier-arg-str optsep 6727 (";" / 6728 "{" stmtsep 6729 ;; these stmts can appear in any order 6730 [when-stmt stmtsep] 6731 *(if-feature-stmt stmtsep) 6732 [default-stmt stmtsep] 6733 [config-stmt stmtsep] 6734 [mandatory-stmt stmtsep] 6735 [status-stmt stmtsep] 6736 [description-stmt stmtsep] 6737 [reference-stmt stmtsep] 6738 *((short-case-stmt / case-stmt) stmtsep) 6739 "}") 6741 short-case-stmt = container-stmt / 6742 leaf-stmt / 6743 leaf-list-stmt / 6744 list-stmt / 6745 anyxml-stmt 6747 case-stmt = case-keyword sep identifier-arg-str optsep 6748 (";" / 6749 "{" stmtsep 6750 ;; these stmts can appear in any order 6751 [when-stmt stmtsep] 6752 *(if-feature-stmt stmtsep) 6753 [status-stmt stmtsep] 6754 [description-stmt stmtsep] 6755 [reference-stmt stmtsep] 6756 *(data-def-stmt stmtsep) 6757 "}") 6759 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 6760 (";" / 6761 "{" stmtsep 6762 ;; these stmts can appear in any order 6763 [when-stmt stmtsep] 6764 *(if-feature-stmt stmtsep) 6765 *(must-stmt stmtsep) 6766 [config-stmt stmtsep] 6767 [mandatory-stmt stmtsep] 6768 [status-stmt stmtsep] 6769 [description-stmt stmtsep] 6770 [reference-stmt stmtsep] 6771 "}") 6773 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 6774 (";" / 6775 "{" stmtsep 6776 ;; these stmts can appear in any order 6777 [when-stmt stmtsep] 6778 *(if-feature-stmt stmtsep) 6779 [status-stmt stmtsep] 6780 [description-stmt stmtsep] 6781 [reference-stmt stmtsep] 6782 *(refine-stmt stmtsep) 6783 *(uses-augment-stmt stmtsep) 6784 "}") 6786 refine-stmt = refine-keyword sep refine-arg-str optsep 6787 (";" / 6788 "{" stmtsep 6789 (refine-container-stmts / 6790 refine-leaf-stmts / 6791 refine-leaf-list-stmts / 6792 refine-list-stmts / 6793 refine-choice-stmts / 6794 refine-case-stmts / 6795 refine-anyxml-stmts) 6796 "}") 6798 refine-arg-str = < a string which matches the rule 6799 refine-arg > 6801 refine-arg = descendant-schema-nodeid 6803 refine-container-stmts = 6804 ;; these stmts can appear in any order 6805 *(must-stmt stmtsep) 6806 [presence-stmt stmtsep] 6807 [config-stmt stmtsep] 6808 [description-stmt stmtsep] 6809 [reference-stmt stmtsep] 6811 refine-leaf-stmts = ;; these stmts can appear in any order 6812 *(must-stmt stmtsep) 6813 [default-stmt stmtsep] 6814 [config-stmt stmtsep] 6815 [mandatory-stmt stmtsep] 6816 [description-stmt stmtsep] 6817 [reference-stmt stmtsep] 6819 refine-leaf-list-stmts = 6820 ;; these stmts can appear in any order 6821 *(must-stmt stmtsep) 6822 [config-stmt stmtsep] 6823 [min-elements-stmt stmtsep] 6825 [max-elements-stmt stmtsep] 6826 [description-stmt stmtsep] 6827 [reference-stmt stmtsep] 6829 refine-list-stmts = ;; these stmts can appear in any order 6830 *(must-stmt stmtsep) 6831 [config-stmt stmtsep] 6832 [min-elements-stmt stmtsep] 6833 [max-elements-stmt stmtsep] 6834 [description-stmt stmtsep] 6835 [reference-stmt stmtsep] 6837 refine-choice-stmts = ;; these stmts can appear in any order 6838 [default-stmt stmtsep] 6839 [config-stmt stmtsep] 6840 [mandatory-stmt stmtsep] 6841 [description-stmt stmtsep] 6842 [reference-stmt stmtsep] 6844 refine-case-stmts = ;; these stmts can appear in any order 6845 [description-stmt stmtsep] 6846 [reference-stmt stmtsep] 6848 refine-anyxml-stmts = ;; these stmts can appear in any order 6849 *(must-stmt stmtsep) 6850 [config-stmt stmtsep] 6851 [mandatory-stmt stmtsep] 6852 [description-stmt stmtsep] 6853 [reference-stmt stmtsep] 6855 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 6856 "{" stmtsep 6857 ;; these stmts can appear in any order 6858 [when-stmt stmtsep] 6859 *(if-feature-stmt stmtsep) 6860 [status-stmt stmtsep] 6861 [description-stmt stmtsep] 6862 [reference-stmt stmtsep] 6863 1*((data-def-stmt stmtsep) / 6864 (case-stmt stmtsep)) 6865 "}" 6867 uses-augment-arg-str = < a string which matches the rule 6868 uses-augment-arg > 6870 uses-augment-arg = descendant-schema-nodeid 6871 augment-stmt = augment-keyword sep augment-arg-str optsep 6872 "{" stmtsep 6873 ;; these stmts can appear in any order 6874 [when-stmt stmtsep] 6875 *(if-feature-stmt stmtsep) 6876 [status-stmt stmtsep] 6877 [description-stmt stmtsep] 6878 [reference-stmt stmtsep] 6879 1*((data-def-stmt stmtsep) / 6880 (case-stmt stmtsep)) 6881 "}" 6883 augment-arg-str = < a string which matches the rule 6884 augment-arg > 6886 augment-arg = absolute-schema-nodeid 6888 unknown-statement = prefix ":" identifier [sep string] optsep 6889 (";" / "{" *unknown-statement2 "}") 6891 unknown-statement2 = [prefix ":"] identifier [sep string] optsep 6892 (";" / "{" *unknown-statement2 "}") 6894 when-stmt = when-keyword sep string optsep 6895 (";" / 6896 "{" stmtsep 6897 ;; these stmts can appear in any order 6898 [description-stmt stmtsep] 6899 [reference-stmt stmtsep] 6900 "}") 6902 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 6903 (";" / 6904 "{" stmtsep 6905 ;; these stmts can appear in any order 6906 *(if-feature-stmt stmtsep) 6907 [status-stmt stmtsep] 6908 [description-stmt stmtsep] 6909 [reference-stmt stmtsep] 6910 *((typedef-stmt / 6911 grouping-stmt) stmtsep) 6912 [input-stmt stmtsep] 6913 [output-stmt stmtsep] 6914 "}") 6916 input-stmt = input-keyword optsep 6917 "{" stmtsep 6918 ;; these stmts can appear in any order 6919 *((typedef-stmt / 6920 grouping-stmt) stmtsep) 6921 1*(data-def-stmt stmtsep) 6922 "}" 6924 output-stmt = output-keyword optsep 6925 "{" stmtsep 6926 ;; these stmts can appear in any order 6927 *((typedef-stmt / 6928 grouping-stmt) stmtsep) 6929 1*(data-def-stmt stmtsep) 6930 "}" 6932 notification-stmt = notification-keyword sep 6933 identifier-arg-str optsep 6934 (";" / 6935 "{" stmtsep 6936 ;; these stmts can appear in any order 6937 *(if-feature-stmt stmtsep) 6938 [status-stmt stmtsep] 6939 [description-stmt stmtsep] 6940 [reference-stmt stmtsep] 6941 *((typedef-stmt / 6942 grouping-stmt) stmtsep) 6943 *(data-def-stmt stmtsep) 6944 "}") 6946 deviation-stmt = deviation-keyword sep 6947 deviation-arg-str optsep 6948 "{" stmtsep 6949 ;; these stmts can appear in any order 6950 [description-stmt stmtsep] 6951 [reference-stmt stmtsep] 6952 (deviate-not-supported-stmt / 6953 1*(deviate-add-stmt / 6954 deviate-replace-stmt / 6955 deviate-delete-stmt)) 6956 "}" 6958 deviation-arg-str = < a string which matches the rule 6959 deviation-arg > 6961 deviation-arg = absolute-schema-nodeid 6963 deviate-not-supported-stmt = 6964 deviate-keyword sep 6965 not-supported-keyword optsep 6966 (";" / 6967 "{" stmtsep 6968 "}") 6970 deviate-add-stmt = deviate-keyword sep add-keyword optsep 6971 (";" / 6972 "{" stmtsep 6973 [units-stmt stmtsep] 6974 *(must-stmt stmtsep) 6975 *(unique-stmt stmtsep) 6976 [default-stmt stmtsep] 6977 [config-stmt stmtsep] 6978 [mandatory-stmt stmtsep] 6979 [min-elements-stmt stmtsep] 6980 [max-elements-stmt stmtsep] 6981 "}") 6983 deviate-delete-stmt = deviate-keyword sep delete-keyword optsep 6984 (";" / 6985 "{" stmtsep 6986 [units-stmt stmtsep] 6987 *(must-stmt stmtsep) 6988 *(unique-stmt stmtsep) 6989 [default-stmt stmtsep] 6990 "}") 6992 deviate-replace-stmt = deviate-keyword sep replace-keyword optsep 6993 (";" / 6994 "{" stmtsep 6995 [type-stmt stmtsep] 6996 [units-stmt stmtsep] 6997 [default-stmt stmtsep] 6998 [config-stmt stmtsep] 6999 [mandatory-stmt stmtsep] 7000 [min-elements-stmt stmtsep] 7001 [max-elements-stmt stmtsep] 7002 "}") 7004 ;; Ranges 7006 range-arg-str = < a string which matches the rule 7007 range-arg > 7009 range-arg = range-part *(optsep "|" optsep range-part) 7011 range-part = range-boundary 7012 [optsep ".." optsep range-boundary] 7014 range-boundary = min-keyword / max-keyword / 7015 integer-value / decimal-value 7017 ;; Lengths 7019 length-arg-str = < a string which matches the rule 7020 length-arg > 7022 length-arg = length-part *(optsep "|" optsep length-part) 7024 length-part = length-boundary 7025 [optsep ".." optsep length-boundary] 7027 length-boundary = min-keyword / max-keyword / 7028 non-negative-integer-value 7030 ;; Date 7032 date-arg-str = < a string which matches the rule 7033 date-arg > 7035 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 7037 ;; Schema Node Identifiers 7039 schema-nodeid = absolute-schema-nodeid / 7040 descendant-schema-nodeid 7042 absolute-schema-nodeid = 1*("/" node-identifier) 7044 descendant-schema-nodeid = 7045 node-identifier 7046 absolute-schema-nodeid 7048 node-identifier = [prefix ":"] identifier 7050 ;; Instance Identifiers 7052 instance-identifier = 1*("/" (node-identifier *predicate)) 7054 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 7056 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 7057 ((DQUOTE string DQUOTE) / 7058 (SQUOTE string SQUOTE)) 7060 pos = non-negative-integer-value 7061 ;; leafref path 7063 path-arg-str = < a string which matches the rule 7064 path-arg > 7066 path-arg = absolute-path / relative-path 7068 absolute-path = 1*("/" (node-identifier *path-predicate)) 7070 relative-path = 1*(".." "/") descendant-path 7072 descendant-path = node-identifier 7073 [*path-predicate absolute-path] 7075 path-predicate = "[" *WSP path-equality-expr *WSP "]" 7077 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 7079 path-key-expr = current-function-invocation *WSP "/" *WSP 7080 rel-path-keyexpr 7082 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 7083 *(node-identifier *WSP "/" *WSP) 7084 node-identifier 7086 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 7088 ;; statement keywords 7089 anyxml-keyword = 'anyxml' 7090 argument-keyword = 'argument' 7091 augment-keyword = 'augment' 7092 base-keyword = 'base' 7093 belongs-to-keyword = 'belongs-to' 7094 bit-keyword = 'bit' 7095 case-keyword = 'case' 7096 choice-keyword = 'choice' 7097 config-keyword = 'config' 7098 contact-keyword = 'contact' 7099 container-keyword = 'container' 7100 default-keyword = 'default' 7101 description-keyword = 'description' 7102 enum-keyword = 'enum' 7103 error-app-tag-keyword = 'error-app-tag' 7104 error-message-keyword = 'error-message' 7105 extension-keyword = 'extension' 7106 deviation-keyword = 'deviation' 7107 deviate-keyword = 'deviate' 7108 feature-keyword = 'feature' 7109 fraction-digits-keyword = 'fraction-digits' 7110 grouping-keyword = 'grouping' 7111 identity-keyword = 'identity' 7112 if-feature-keyword = 'if-feature' 7113 import-keyword = 'import' 7114 include-keyword = 'include' 7115 input-keyword = 'input' 7116 key-keyword = 'key' 7117 leaf-keyword = 'leaf' 7118 leaf-list-keyword = 'leaf-list' 7119 length-keyword = 'length' 7120 list-keyword = 'list' 7121 mandatory-keyword = 'mandatory' 7122 max-elements-keyword = 'max-elements' 7123 min-elements-keyword = 'min-elements' 7124 module-keyword = 'module' 7125 must-keyword = 'must' 7126 namespace-keyword = 'namespace' 7127 notification-keyword= 'notification' 7128 ordered-by-keyword = 'ordered-by' 7129 organization-keyword= 'organization' 7130 output-keyword = 'output' 7131 path-keyword = 'path' 7132 pattern-keyword = 'pattern' 7133 position-keyword = 'position' 7134 prefix-keyword = 'prefix' 7135 presence-keyword = 'presence' 7136 range-keyword = 'range' 7137 reference-keyword = 'reference' 7138 refine-keyword = 'refine' 7139 require-instance-keyword = 'require-instance' 7140 revision-keyword = 'revision' 7141 revision-date-keyword = 'revision-date' 7142 rpc-keyword = 'rpc' 7143 status-keyword = 'status' 7144 submodule-keyword = 'submodule' 7145 type-keyword = 'type' 7146 typedef-keyword = 'typedef' 7147 unique-keyword = 'unique' 7148 units-keyword = 'units' 7149 uses-keyword = 'uses' 7150 value-keyword = 'value' 7151 when-keyword = 'when' 7152 yang-version-keyword= 'yang-version' 7153 yin-element-keyword = 'yin-element' 7155 ;; other keywords 7156 add-keyword = 'add' 7157 current-keyword = 'current' 7158 delete-keyword = 'delete' 7159 deprecated-keyword = 'deprecated' 7160 false-keyword = 'false' 7161 max-keyword = 'max' 7162 min-keyword = 'min' 7163 not-supported-keyword = 'not-supported' 7164 obsolete-keyword = 'obsolete' 7165 replace-keyword = 'replace' 7166 system-keyword = 'system' 7167 true-keyword = 'true' 7168 unbounded-keyword = 'unbounded' 7169 user-keyword = 'user' 7171 current-function-invocation = current-keyword *WSP "(" *WSP ")" 7173 ;; Basic Rules 7175 prefix-arg-str = < a string which matches the rule 7176 prefix-arg > 7178 prefix-arg = prefix 7180 prefix = identifier 7182 identifier-arg-str = < a string which matches the rule 7183 identifier-arg > 7185 identifier-arg = identifier 7187 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 7188 identifier = (ALPHA / "_") 7189 *(ALPHA / DIGIT / "_" / "-" / ".") 7191 identifier-ref-arg-str = < a string which matches the rule 7192 identifier-ref-arg > 7194 identifier-ref-arg = [prefix ":"] identifier 7196 string = < an unquoted string as returned by 7197 the scanner > 7199 integer-value = ("-" non-negative-integer-value) / 7200 non-negative-integer-value 7202 non-negative-integer-value = "0" / positive-integer-value 7203 positive-integer-value = (non-zero-digit *DIGIT) 7205 zero-integer-value = 1*DIGIT 7207 stmtend = ";" / "{" *unknown-statement "}" 7209 sep = 1*(WSP / line-break) 7210 ; unconditional separator 7212 optsep = *(WSP / line-break) 7214 stmtsep = *(WSP / line-break / unknown-statement) 7216 line-break = CRLF / LF 7218 non-zero-digit = %x31-39 7220 decimal-value = integer-value ("." zero-integer-value) 7222 SQUOTE = %x27 7223 ; ' (Single Quote) 7225 ;; 7226 ;; RFC 5234 core rules. 7227 ;; 7229 ALPHA = %x41-5A / %x61-7A 7230 ; A-Z / a-z 7232 CR = %x0D 7233 ; carriage return 7235 CRLF = CR LF 7236 ; Internet standard newline 7238 DIGIT = %x30-39 7239 ; 0-9 7241 DQUOTE = %x22 7242 ; " (Double Quote) 7244 HEXDIG = DIGIT / 7245 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 7246 ; only lower-case a..f 7248 HTAB = %x09 7249 ; horizontal tab 7251 LF = %x0A 7252 ; linefeed 7254 SP = %x20 7255 ; space 7257 VCHAR = %x21-7E 7258 ; visible (printing) characters 7260 WSP = SP / HTAB 7261 ; whitespace 7263 7265 13. Error Responses for YANG Related Errors 7267 A number of NETCONF error responses are defined for error cases 7268 related to the data-model handling. If the relevant YANG statement 7269 has an "error-app-tag" substatement, that overrides the default value 7270 specified below. 7272 13.1. Error Message for Data that Violates a unique Statement 7274 If a NETCONF operation would result in configuration data where a 7275 unique constraint is invalidated, the following error is returned: 7277 error-tag: operation-failed 7278 error-app-tag: data-not-unique 7279 error-info: : Contains an instance identifier which 7280 points to a leaf which invalidates the unique 7281 constraint. This element is present once for each 7282 non-unique leaf. 7284 The element is in the YANG 7285 namespace ("urn:ietf:params:xml:ns:yang:1"). 7287 13.2. Error Message for Data that Violates a max-elements Statement 7289 If a NETCONF operation would result in configuration data where a 7290 list or a leaf-list would have too many entries the following error 7291 is returned: 7293 error-tag: operation-failed 7294 error-app-tag: too-many-elements 7296 This error is returned once, with the error-path identifying the list 7297 node, even if there are more than one extra child present. 7299 13.3. Error Message for Data that Violates a min-elements Statement 7301 If a NETCONF operation would result in configuration data where a 7302 list or a leaf-list would have too few entries the following error is 7303 returned: 7305 error-tag: operation-failed 7306 error-app-tag: too-few-elements 7308 This error is returned once, with the error-path identifying the list 7309 node, even if there are more than one child missing. 7311 13.4. Error Message for Data that Violates a must Statement 7313 If a NETCONF operation would result in configuration data where the 7314 restrictions imposed by a "must" statement is violated the following 7315 error is returned, unless a specific "error-app-tag" substatement is 7316 present for the "must" statement. 7318 error-tag: operation-failed 7319 error-app-tag: must-violation 7321 13.5. Error Message for Data that Violates a require-instance Statement 7323 If a NETCONF operation would result in configuration data where a 7324 leaf of type "instance-identifier" marked with require-instance 7325 "true" refers to a non-existing instance, the following error is 7326 returned: 7328 error-tag: data-missing 7329 error-app-tag: instance-required 7330 error-path: Path to the instance-identifier leaf. 7332 13.6. Error Message for Data that does not Match a leafref Type 7334 If a NETCONF operation would result in configuration data where a 7335 leaf of type "leafref" refers to a non-existing instance, the 7336 following error is returned: 7338 error-tag: data-missing 7339 error-app-tag: instance-required 7340 error-path: Path to the leafref leaf. 7342 13.7. Error Message for Data that Violates a mandatory choice Statement 7344 If a NETCONF operation would result in configuration data where no 7345 nodes exists in a mandatory choice, the following error is returned: 7347 error-tag: data-missing 7348 error-app-tag: missing-choice 7349 error-path: Path to the element with the missing choice. 7350 error-info: : Contains the name of the missing 7351 mandatory choice. 7353 The element is in the YANG 7354 namespace ("urn:ietf:params:xml:ns:yang:1"). 7356 13.8. Error Message for the "insert" Operation 7358 If the "insert" and "key" or "value" attributes are used in an 7359 for a list or leaf-list node, and the "key" or "value" 7360 refers to a non-existing instance, the following error is returned: 7362 error-tag: bad-attribute 7363 error-app-tag: missing-instance 7365 14. IANA Considerations 7367 This document defines a registry for YANG module and submodule names. 7368 The name of the registry is "YANG Module Names". 7370 The registry shall record for each entry: 7372 o the name of the module or submodule 7374 o for modules, the assigned XML namespace 7376 o for modules, the prefix of the module 7378 o for submodules, the name of the module it belongs to 7380 o a reference to the (sub)module's documentation (e.g., the RFC 7381 number) 7383 There are no initial assignments. 7385 For allocation, RFC publication is required as per RFC 5226 7386 [RFC5226]. All registered YANG module names MUST comply with the 7387 rules for identifiers stated in Section 6.2, and MUST have a module 7388 name prefix. 7390 The module name prefix 'ietf-' is reserved for IETF stream documents 7391 [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF 7392 stream documents. Modules published in other RFC streams MUST have a 7393 similar suitable prefix. 7395 All module and submodule names in the registry MUST be unique. 7397 All XML namespaces in the registry MUST be unique. 7399 This document registers two URIs for the YANG and YIN XML namespaces 7400 in the IETF XML registry [RFC3688]. Following the format in RFC 7401 3688, the following registration is requested. 7403 URI: urn:ietf:params:xml:ns:yang:yin:1 7404 URI: urn:ietf:params:xml:ns:yang:1 7406 Registrant Contact: The IESG. 7408 XML: N/A, the requested URIs are XML namespaces. 7410 This document registers two new media types as defined in the 7411 following sections. 7413 14.1. Media type application/yang 7415 MIME media type name: application 7417 MIME subtype name: yang 7419 Mandatory parameters: none 7421 Optional parameters: none 7423 Encoding considerations: 8bit 7425 Security considerations: See section 15 in RFC XXXX 7427 Interoperability considerations: None 7429 Published specification: RFC XXXX (currently draft-ietf-netmod-yang) 7431 Applications that use this media type: 7433 YANG module validators, web servers used for downloading YANG 7434 modules, email clients etc. 7436 Additional information: 7438 Magic Number: None 7440 File Extension: .yang 7442 Macintosh file type code: 'TEXT' 7444 Personal and email address for further information: 7445 Martin Bjorklund 7447 Intended usage: COMMON 7449 Author: 7450 This specification is a work item of the IETF NETMOD working group, 7451 with mailing list address . 7453 Change controller: 7454 The IESG 7456 14.2. Media type application/yin+xml 7457 MIME media type name: application 7459 MIME subtype name: yin+xml 7461 Mandatory parameters: none 7463 Optional parameters: 7465 "charset": This parameter has identical semantics to the charset 7466 parameter of the "application/xml" media type as specified in 7467 [RFC3023]. 7469 Encoding considerations: 7471 Identical to those of "application/xml" as 7472 described in [RFC3023], Section 3.2. 7474 Security considerations: See section 15 in RFC XXXX 7476 Interoperability considerations: None 7478 Published specification: RFC XXXX (currently draft-ietf-netmod-yang) 7480 Applications that use this media type: 7482 YANG module validators, web servers used for downloading YANG 7483 modules, email clients etc. 7485 Additional information: 7487 Magic Number: As specified for "application/xml" in [RFC3023], 7488 Section 3.2. 7490 File Extension: .yin 7492 Macintosh file type code: 'TEXT' 7494 Personal and email address for further information: 7495 Martin Bjorklund 7497 Intended usage: COMMON 7499 Author: 7500 This specification is a work item of the IETF NETMOD working group, 7501 with mailing list address . 7503 Change controller: 7504 The IESG 7506 15. Security Considerations 7508 This document defines a language with which to write and read 7509 descriptions of management information. The language itself has no 7510 security impact on the Internet. 7512 The same considerations are relevant as for the base NETCONF protocol 7513 (see [RFC4741], section 9). 7515 Data modeled in YANG might contain sensitive information. RPCs or 7516 notifications defined in YANG might transfer sensitive information. 7518 Security issues are related to the usage of data modeled in YANG. 7519 Such issues shall be dealt with in documents describing the data 7520 models and documents about the interfaces used to manipulate the data 7521 e.g., the NETCONF documents. 7523 Data modeled in YANG is dependent upon: 7525 o the security of the transmission infrastructure used to send 7526 sensitive information 7528 o the security of applications which store or release such sensitive 7529 information. 7531 o adequate authentication and access control mechanisms to restrict 7532 the usage of sensitive data. 7534 YANG parsers need to be robust with respect to malformed documents. 7535 Reading malformed documents from unknown or untrusted sources could 7536 result in an attacker gaining privileges of the user running the YANG 7537 parser. In an extreme situation, the entire machine could be 7538 compromised. 7540 16. Contributors 7542 The following people all contributed significantly to the initial 7543 YANG draft: 7545 - Andy Bierman (Netconf Central) 7546 - Balazs Lengyel (Ericsson) 7547 - David Partain (Ericsson) 7548 - Juergen Schoenwaelder (Jacobs University Bremen) 7549 - Phil Shafer (Juniper Networks) 7551 17. Acknowledgements 7553 The editor wishes to thank the following individuals, who all 7554 provided helpful comments on various versions of this document: 7555 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 7556 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 7557 Wijnen. 7559 18. References 7561 18.1. Normative References 7563 [ISO.10646] 7564 International Organization for Standardization, 7565 "Information Technology - Universal Multiple-Octet Coded 7566 Character Set (UCS)", ISO Standard 10646:2003, 2003. 7568 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7569 Requirement Levels", BCP 14, RFC 2119, March 1997. 7571 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 7572 10646", STD 63, RFC 3629, November 2003. 7574 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 7575 January 2004. 7577 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 7578 Resource Identifier (URI): Generic Syntax", STD 66, 7579 RFC 3986, January 2005. 7581 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 7582 Encodings", RFC 4648, October 2006. 7584 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 7585 December 2006. 7587 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 7588 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 7589 May 2008. 7591 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 7592 Specifications: ABNF", STD 68, RFC 5234, January 2008. 7594 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 7595 Notifications", RFC 5277, July 2008. 7597 [XML-NAMES] 7598 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 7599 Layman, "Namespaces in XML 1.0 (Third Edition)", World 7600 Wide Web Consortium Recommendation REC-xml-names-20091208, 7601 December 2009, 7602 . 7604 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 7605 Version 1.0", World Wide Web Consortium 7606 Recommendation REC-xpath-19991116, November 1999, 7607 . 7609 [XSD-TYPES] 7610 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 7611 Second Edition", World Wide Web Consortium 7612 Recommendation REC-xmlschema-2-20041028, October 2004, 7613 . 7615 18.2. Non-Normative References 7617 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7618 Schoenwaelder, Ed., "Structure of Management Information 7619 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 7621 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7622 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 7623 STD 58, RFC 2579, April 1999. 7625 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 7626 Structure of Management Information", RFC 3780, May 2004. 7628 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 7629 Series and RFC Editor", RFC 4844, July 2007. 7631 [XPATH2.0] 7632 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 7633 Kay, M., Robie, J., and J. Simeon, "XML Path Language 7634 (XPath) 2.0", World Wide Web Consortium 7635 Recommendation REC-xpath20-20070123, January 2007, 7636 . 7638 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 7639 Wide Web Consortium Recommendation REC-xslt-19991116, 7640 November 1999, 7641 . 7643 Appendix A. ChangeLog 7645 RFC Editor: remove this section upon publication as an RFC. 7647 A.1. Version -12 7649 o Editorial fixes after IETF Last Call. 7651 A.2. Version -11 7653 o New Copyright text and some editorial fixes. 7655 A.3. Version -10 7657 o Added "description" and "reference" as substatements to "when". 7659 o Make sure identifiers are XML compatible, i.e. do not start with 7660 "xml". 7662 o Use the terms "data node" and "schema node" instead of "node" in 7663 the Terminology section. 7665 o Use the character "@" as separator in recommended file names. 7667 o Require a new "revision" statement in new versions of published 7668 modules. 7670 o Specified which error codes processing should 7671 generate. 7673 o Various editorial fixes and enhancements. 7675 A.4. Version -09 7677 o Specified that we do not specify formal rules for how the server 7678 may modify configuration data stores. 7680 o Added rule to allow defaults to be added to leafs in an updated 7681 module. 7683 o Clarified how ordered-by user lists and leaf-lists entries are 7684 encoded in XML. 7686 o Clarified how child nodes to "case" are encoded in the XML. 7688 A.5. Version -08 7690 o Clarified text on leaf deafults. 7692 o Added the term "top-level data node" to the terminology section. 7694 o Clarified how prefixes are mapped to namespaces in XPath 7695 expressions. 7697 o Added "reference" as a substatement to "revision". 7699 o Added "choice" as a substatement to "case". 7701 o Clarified that a leafreaf must be conditional if the leaf it 7702 refers to is conditional. 7704 o Clarified how identityref default values are represented. 7706 o Various bug fixes, clarifications and editorial fixes. 7708 A.6. Version -07 7710 o The argument string of "augment", "refine", and "deviation" is 7711 described not as an XPath but as a "schema node identifier". 7713 o Clarified that there must be no circular references in a leafref. 7715 A.7. Version -06 7717 o Various bug fixes, clarifications and editorial fixes after WGLC. 7719 o Removed "require-instance" for leafref. 7721 o Allow leafrefs to refer to leaf-lists. 7723 o Clarified the XPath context in Section 6.4.1, and for "must", 7724 "when", "augment", "path" and "instance-identifier". 7726 A.8. Version -05 7728 o Replaced the data types "float32" and "float64" with "decimal64". 7730 o Specified that the elements in the XML encoding of configuration 7731 data can occur in any order. 7733 o Clarified that "augment" cannot add multiple nodes with the same 7734 name. 7736 o Clarified what "when" means in RPC input / output. 7738 o Wrote the IANA Considerations section. 7740 o Changed requirement for minimum identifier length to 64 7741 characters. 7743 A.9. Version -04 7745 o Using "revision-date" substatement to "import" and "include". 7747 o Corrected grammar and text for instance-identifier. 7749 o Fixed bugs in some examples. 7751 o Rewrote the YIN description to use a declarative style. 7753 o Added two error codes in Section 13. 7755 o Clarified that YANG uses the same XPath data model as XSLT. 7757 o Specified which errors are generated in Section 8.3.1. 7759 o Corrected grammar for key-arg; now allowing optional prefix on 7760 each leaf identifier. 7762 o Clarified that "unique" constraints only check instances with 7763 values for all referenced leafs. 7765 o Clarified how mandatory and min-elements constraints are enforced. 7767 o Editorial fixes. 7769 A.10. Version -03 7771 o Added import by revision (yang-00413) 7773 o Changed type "keyref" to "leafref", and added the statement 7774 "require-instance" (yang-01253) 7776 o Clarified that data sent from the server must be in the canonical 7777 form. 7779 o Clarified when and how constraints in the models are enforced. 7781 o Many editorial fixes 7782 o Added more strict grammar for the "deviate" statement. 7784 A.11. Version -02 7786 o Added module update rules. (yang-00000) 7788 o Added "refine" statement as a substatement to "uses". (yang-00088) 7790 o Allow "augment" on top-level and in "uses" only. (yang-00088) 7792 o Allow "when" on all data defintion statements. (yang-00088) 7794 o Added section "Constraints" and clarified when constraints are 7795 enforced. (yang-00172) 7797 o Added "feature" and "if-feature" statements. (yang-00750) 7799 o Added "prefix" as a substatement to "belongs-to". (yang-00755) 7801 o Added section on Conformance. (yang-01281) 7803 o Added "deviation" statement. (yang-01281) 7805 o Added "identity" statement and "identityref" type. (yang-01339) 7807 o Aligned grammar for "enum" with text. 7809 A.12. Version -01 7811 o Removed "Appendix A. Derived YANG Types". 7813 o Removed "Appendix C. XML Schema Considerations". 7815 o Removed "Appendix F. Why We Need a New Modeling Language". 7817 o Moved "Appendix B. YIN" to its own section. 7819 o Moved "Appendix D. YANG ABNF Grammar" to its own section. 7821 o Moved "Appendix E. Error Responses for YANG Related Errors" into 7822 its own section. 7824 o The "input" and "output" nodes are now implicitly created by the 7825 "rpc" statement, in order for augmentation of these nodes to work 7826 correctly. 7828 o Allow "config" in "choice". 7830 o Added reference to XPath 1.0. 7832 o Using an XPath function "current()" instead of the variable 7833 "$this". 7835 o Clarified that a "must" expression in a configuration node must 7836 not reference non-configuration nodes. 7838 o Added XML encoding rules and usage examples for rpc and 7839 notification. 7841 o Removed requirement that refinements are specified in the same 7842 order as in the original grouping's definition. 7844 o Fixed whitespace issues in the ABNF grammar. 7846 o Added the term "mandatory node", and refer to it in the 7847 description of augment (see Section 7.15), and choice (see 7848 Section 7.9.3). 7850 o Added support for multiple "pattern" statements in "type". 7852 o Several clarifications and fixed typos. 7854 A.13. Version -00 7856 Changes from draft-bjorklund-netconf-yang-02.txt 7858 o Fixed bug in grammar for bit-stmt 7860 o Fixed bugs in example XPath expressions 7862 o Added keyword 'presence' to the YIN mapping table 7864 Author's Address 7866 Martin Bjorklund (editor) 7867 Tail-f Systems 7869 Email: mbj@tail-f.com