idnits 2.17.1 draft-ietf-netmod-yang-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 20, 2009) is 5475 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) == Missing Reference: 'TBD' is mentioned on line 1460, but not defined -- Looks like a reference, but probably isn't: '3' on line 5636 ** 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSLT' 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 April 20, 2009 5 Expires: October 22, 2009 7 YANG - A data modeling language for NETCONF 8 draft-ietf-netmod-yang-05 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on October 22, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 YANG is a data modeling language used to model configuration and 47 state data manipulated by the NETCONF protocol, NETCONF remote 48 procedure calls, and NETCONF notifications. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 53 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9 54 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 55 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12 56 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 57 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 58 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 59 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 60 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 61 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19 62 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19 63 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 64 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 65 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 66 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23 67 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 24 68 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25 69 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 70 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 71 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 72 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28 73 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29 74 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30 75 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30 76 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30 77 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30 78 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31 79 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 31 80 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32 81 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 82 5.6.4. Announcing Conformance Information in the 83 Message . . . . . . . . . . . . . . . . . . . . . . . 33 84 5.6.5. Mapping to the NETCONF Schema Discovery Mechanism . . 35 85 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36 86 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36 87 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36 88 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 89 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36 90 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38 91 6.2.1. Identifiers and their namespaces . . . . . . . . . . 38 92 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39 93 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39 94 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39 95 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 41 96 7.1. The module Statement . . . . . . . . . . . . . . . . . . 41 97 7.1.1. The module's Substatements . . . . . . . . . . . . . 42 98 7.1.2. The yang-version Statement . . . . . . . . . . . . . 43 99 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 43 100 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 44 101 7.1.5. The import Statement . . . . . . . . . . . . . . . . 44 102 7.1.6. The include Statement . . . . . . . . . . . . . . . . 45 103 7.1.7. The organization Statement . . . . . . . . . . . . . 45 104 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 46 105 7.1.9. The revision Statement . . . . . . . . . . . . . . . 46 106 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 47 107 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 47 108 7.2.1. The submodule's Substatements . . . . . . . . . . . . 48 109 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 49 110 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 50 111 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 50 112 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 51 113 7.3.2. The typedef's type Statement . . . . . . . . . . . . 51 114 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 51 115 7.3.4. The typedef's default Statement . . . . . . . . . . . 51 116 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 52 117 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 52 118 7.4.1. The type's Substatements . . . . . . . . . . . . . . 52 119 7.5. The container Statement . . . . . . . . . . . . . . . . . 52 120 7.5.1. Containers with Presence . . . . . . . . . . . . . . 53 121 7.5.2. The container's Substatements . . . . . . . . . . . . 54 122 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 54 123 7.5.4. The must's Substatements . . . . . . . . . . . . . . 56 124 7.5.5. The presence Statement . . . . . . . . . . . . . . . 57 125 7.5.6. The container's Child Node Statements . . . . . . . . 57 126 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 57 127 7.5.8. NETCONF Operations . . . . . . . . . . 57 128 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 58 129 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 130 7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 60 131 7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 60 132 7.6.3. The leaf's default Statement . . . . . . . . . . . . 60 133 7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 60 134 7.6.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 61 135 7.6.6. NETCONF Operations . . . . . . . . . . 61 136 7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 61 137 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 62 138 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 63 139 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 64 140 7.7.3. The min-elements Statement . . . . . . . . . . . . . 64 141 7.7.4. The max-elements Statement . . . . . . . . . . . . . 64 142 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 65 143 7.7.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 65 144 7.7.7. NETCONF operations . . . . . . . . . . 65 145 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 146 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 68 147 7.8.1. The list's Substatements . . . . . . . . . . . . . . 69 148 7.8.2. The list's key Statement . . . . . . . . . . . . . . 69 149 7.8.3. The list's unique Statement . . . . . . . . . . . . . 70 150 7.8.4. The list's Child Node Statements . . . . . . . . . . 71 151 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 71 152 7.8.6. NETCONF operations . . . . . . . . . . 72 153 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 72 154 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 76 155 7.9.1. The choice's Substatements . . . . . . . . . . . . . 76 156 7.9.2. The choice's case Statement . . . . . . . . . . . . . 76 157 7.9.3. The choice's default Statement . . . . . . . . . . . 78 158 7.9.4. The choice's mandatory Statement . . . . . . . . . . 79 159 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 80 160 7.9.6. NETCONF operations . . . . . . . . . . 80 161 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 80 162 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 81 163 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 82 164 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 165 7.10.3. NETCONF operations . . . . . . . . . . 82 166 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 83 167 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 83 168 7.11.1. The grouping's Substatements . . . . . . . . . . . . 84 169 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 84 170 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 84 171 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 85 172 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 85 173 7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 86 174 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 86 175 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 87 176 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 88 177 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 88 178 7.13.3. The output Statement . . . . . . . . . . . . . . . . 89 179 7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 90 180 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 90 181 7.14. The notification Statement . . . . . . . . . . . . . . . 91 182 7.14.1. The notification's Substatements . . . . . . . . . . 92 183 7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 184 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 92 185 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 93 186 7.15.1. The augment's Substatements . . . . . . . . . . . . . 95 187 7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 95 188 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 189 7.16. The identity Statement . . . . . . . . . . . . . . . . . 97 190 7.16.1. The identity's Substatements . . . . . . . . . . . . 98 191 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 98 192 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 99 193 7.17. The extension Statement . . . . . . . . . . . . . . . . . 99 194 7.17.1. The extension's Substatements . . . . . . . . . . . . 100 195 7.17.2. The argument Statement . . . . . . . . . . . . . . . 100 196 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 197 7.18. Conformance-related Statements . . . . . . . . . . . . . 101 198 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 101 199 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 103 200 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 103 201 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 106 202 7.19.1. The config Statement . . . . . . . . . . . . . . . . 106 203 7.19.2. The status Statement . . . . . . . . . . . . . . . . 106 204 7.19.3. The description Statement . . . . . . . . . . . . . . 107 205 7.19.4. The reference Statement . . . . . . . . . . . . . . . 107 206 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 107 207 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 110 208 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 110 209 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 110 210 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 110 211 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 111 212 8.3.2. NETCONF Processing . . . . . . . . . . 111 213 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 112 214 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 113 215 9.1. Canonical representation . . . . . . . . . . . . . . . . 113 216 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 113 217 9.2.1. Lexicographic Representation . . . . . . . . . . . . 114 218 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 115 219 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 115 220 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 115 221 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 116 222 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 116 223 9.3.1. Lexicographic Representation . . . . . . . . . . . . 116 224 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 225 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 226 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 117 227 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 228 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 117 229 9.4.1. Lexicographic Representation . . . . . . . . . . . . 117 230 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 231 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 232 9.4.4. The length Statement . . . . . . . . . . . . . . . . 117 233 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 234 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 119 235 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 120 236 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 120 237 9.5.1. Lexicographic Representation . . . . . . . . . . . . 120 238 9.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 120 239 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 120 240 9.6.1. Lexicographic Representation . . . . . . . . . . . . 120 241 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 242 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 121 243 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 121 244 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 122 245 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 122 246 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 122 247 9.7.2. Lexicographic Representation . . . . . . . . . . . . 122 248 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 122 249 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 122 250 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 251 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 124 252 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 253 9.8.2. Lexicographic Representation . . . . . . . . . . . . 124 254 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 124 255 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 124 256 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 257 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 125 258 9.9.3. The require-instance Statement . . . . . . . . . . . 125 259 9.9.4. Lexicographic Representation . . . . . . . . . . . . 126 260 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 126 261 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 126 262 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 128 263 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 128 264 9.10.2. The identityref's base Statement . . . . . . . . . . 128 265 9.10.3. Lexicographic Representation . . . . . . . . . . . . 129 266 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 129 267 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 268 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 130 269 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 130 270 9.11.2. Lexicographic Representation . . . . . . . . . . . . 130 271 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 130 272 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 130 273 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 130 274 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 275 9.12.2. Lexicographic Representation . . . . . . . . . . . . 131 276 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 131 277 9.13. The instance-identifier Built-in Type . . . . . . . . . . 131 278 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 279 9.13.2. Lexicographic Representation . . . . . . . . . . . . 132 280 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 281 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . . 132 282 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 134 283 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 284 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 137 285 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 139 286 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 141 287 13. Error Responses for YANG Related Errors . . . . . . . . . . . 162 288 13.1. Error Message for Data that Violates a unique 289 Statement: . . . . . . . . . . . . . . . . . . . . . . . 162 290 13.2. Error Message for Data that Violates a max-elements 291 Statement: . . . . . . . . . . . . . . . . . . . . . . . 162 292 13.3. Error Message for Data that Violates a min-elements 293 Statement: . . . . . . . . . . . . . . . . . . . . . . . 162 294 13.4. Error Message for Data that Violates a must statement: . 163 295 13.5. Error Message for Data that Violates a 296 require-instance statement: . . . . . . . . . . . . . . . 163 297 13.6. Error Message for Data that Violates a mandatory 298 choice statement: . . . . . . . . . . . . . . . . . . . . 163 299 13.7. Error Message for the "insert" Operation . . . . . . . . 163 300 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 164 301 15. Security Considerations . . . . . . . . . . . . . . . . . . . 165 302 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 166 303 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 167 304 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 168 305 18.1. Normative References . . . . . . . . . . . . . . . . . . 168 306 18.2. Non-Normative References . . . . . . . . . . . . . . . . 169 307 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 170 308 A.1. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 170 309 A.2. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 170 310 A.3. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 171 311 A.4. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 171 312 A.5. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 171 313 A.6. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 172 314 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 174 316 1. Introduction 318 Today, the NETCONF protocol [RFC4741] lacks a standardized way to 319 create data models. Instead, vendors are forced to use proprietary 320 solutions. In order for NETCONF to be a interoperable protocol, 321 models must be defined in a vendor-neutral way. YANG provides the 322 language and rules for defining such models for use with NETCONF. 324 YANG is a data modeling language used to model configuration and 325 state data manipulated by the NETCONF protocol, NETCONF remote 326 procedure calls, and NETCONF notifications. YANG models the 327 operations and content layers of NETCONF (see the NETCONF protocol 328 [RFC4741], section 1.1). 330 This document describes the syntax and semantics of the YANG 331 language, how the data model defined in a YANG module is represented 332 in XML, and how NETCONF operations are used to manipulate the data. 334 2. Key Words 336 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 337 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 338 "OPTIONAL" in this document are to be interpreted as described in BCP 339 14, [RFC2119]. 341 3. Terminology 343 o anyxml: A node which can contain an unknown chunk of XML data. 345 o augment: Adds new nodes to a previously defined node. 347 o base type: The type from which a derived type was derived, which 348 may be either a built-in type or another derived type. 350 o built-in type: A YANG data type defined in the YANG language, such 351 as uint32 or string. 353 o choice: A node where only one of a number of identified 354 alternative nodes is valid. 356 o configuration data: The set of writable data that is required to 357 transform a system from its initial default state into its current 358 state [RFC4741]. 360 o conformance: A measure of how accurately a device follows the 361 model. 363 o container: An interior node in the data tree which exist in at 364 most one instance. A container node has no value, but rather a 365 set of child nodes. 367 o data definition statement: A statement that defines new data 368 nodes. One of container, leaf, leaf-list, list, choice, case, 369 augment, uses, and anyxml. 371 o data model: A data model describes how data is represented and 372 accessed. 374 o data model object: A definition within a module that represents a 375 construct which can be accessed via a network management protocol. 376 Also called an object. 378 o data node: A node in the schema tree that can be instantiated in a 379 data tree. One of container, leaf, leaf-list, list, and anyxml. 381 o data tree: The instantiated tree of configuration and state data 382 on a device. 384 o derived type: A type which is derived from a built-in type (such 385 as uint32), or another derived type. 387 o device deviation: A failure of the device to implement the module 388 faithfully. 390 o extension: An extension attaches non-YANG semantics to nodes. The 391 extension statement defines new statements to express these 392 semantics. 394 o feature: A mechanism for marking a portion of the model as 395 optional. Definitions can be tagged with a feature name and are 396 only valid on devices which support that feature. 398 o grouping: A reusable set of nodes, which may be used locally in 399 the module, in modules which include it, and by other modules 400 which import from it. 402 o identifier: Used to identify different kinds of YANG items by 403 name. 405 o instance identifier: A mechanism for identifying a particular node 406 in a data tree. 408 o interior node: Nodes within a hierarchy that are not leaf nodes. 410 o leaf: A node in the data tree with a value but no child nodes. 412 o leaf-list: Like the leaf node but defines a set of uniquely 413 identifiable nodes rather than a single node. Each node has a 414 value but no child nodes. 416 o list: Interior nodes in the data tree which may exist in multiple 417 instances. A list node has no value, but rather a set of child 418 nodes. 420 o MIB: A Management Information Base, traditionally referring to a 421 management information defined using SNMP's SMI. 423 o module: A YANG module defines a hierarchy of nodes which can be 424 used for NETCONF-based operations. With its definitions and the 425 definitions it imports or includes from elsewhere, a module is 426 self-contained and "compilable". 428 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 430 o RPC method: A specific Remote Procedure Call, as used within the 431 NETCONF protocol. Also called a protocol operation. 433 o schema node: A node in the schema tree. One of container, leaf, 434 leaf-list, list, choice, case, rpc, input, output, notification, 435 and anyxml. 437 o schema node identifier: A mechanism for identifying a particular 438 node in the schema tree. 440 o schema tree: The definition hierarchy specified within a module. 442 o state data: The additional data on a system that is not 443 configuration data such as read-only status information and 444 collected statistics [RFC4741]. 446 o submodule: A partial module definition which contributes derived 447 types, groupings, data nodes, RPCs, and notifications to a module. 448 A YANG module can be constructed from a number of submodules. 450 o uses: The "uses" statement is used to instantiate the set of nodes 451 defined in a grouping statement. The instantiated nodes may be 452 refined and augmented to tailor them to any specific needs. 454 3.1. Mandatory nodes 456 A mandatory node is one of: 458 o A leaf or choice node with a "mandatory" statement with the value 459 "true". 461 o A list or leaf-list node with a "min-elements" statement with a 462 value greater than zero. 464 o A container node without a "presence" statement, which has has at 465 least one mandatory node as a child. 467 4. YANG Overview 469 4.1. Functional Overview 471 YANG is a language used to model data for the NETCONF protocol. A 472 YANG module defines a hierarchy of data which can be used for 473 NETCONF-based operations, including configuration, state data, remote 474 procedure calls (RPCs), and notifications. This allows a complete 475 description of all data sent between a NETCONF client and server. 477 YANG models the hierarchical organization of data as a tree in which 478 each node has a name, and either a value or a set of child nodes. 479 YANG provides clear and concise descriptions of the nodes, as well as 480 the interaction between those nodes. 482 YANG structures data models into modules and submodules. A module 483 can import data from other external modules, and include data from 484 submodules. The hierarchy can be extended, allowing one module to 485 add data nodes to the hierarchy defined in another module. This 486 augmentation can be conditional, with new nodes appearing only if 487 certain conditions are met. 489 YANG models can describe constraints to be enforced on the data, 490 restricting the appearance or value of nodes based on the presence or 491 value of other nodes in the hierarchy. These constraints are 492 enforceable by either the client or the server, and valid content 493 must abide by them. 495 YANG defines a set of built-in types, and has a type mechanism 496 through which additional types may be defined. Derived types can 497 restrict their base type's set of valid values using mechanisms like 498 range or pattern restrictions that can be enforced by clients or 499 servers. They can also define usage conventions for use of the 500 derived type, such as a string-based type that contains a host name. 502 YANG permits the definition of complex types using reusable grouping 503 of nodes. The instantiation of these groupings can refine or augment 504 the nodes, allowing it to tailor the nodes to its particular needs. 505 Derived types and groupings can be defined in one module or submodule 506 and used in either that location or in another module or submodule 507 that imports or includes it. 509 YANG organizational constructs include defining lists where list 510 entries are identified by keys which distinguish them from each 511 other. Such lists may be defined as either sorted by user or 512 automatically sorted by the system. For user-sorted lists, 513 operations are defined for manipulating the order of the list 514 entries. 516 YANG modules can be translated into an XML format called YIN 517 (Section 11), allowing applications using XML parsers and XSLT 518 scripts to operate on the models. The conversion from YANG to YIN is 519 loss-less, so content in YIN can round-tripped back into YANG. 521 YANG strikes a balance between high-level data modeling and low-level 522 bits-on-the-wire encoding. The reader of a YANG module can see the 523 high-level view of the data model while understanding how the data 524 will be encoded in NETCONF operations. 526 YANG is an extensible language, allowing extension statements to be 527 defined by standards bodies, vendors, and individuals. The statement 528 syntax allows these extensions to coexist with standard YANG 529 statements in a natural way, while making extensions stand out 530 sufficiently for the reader to notice them. 532 YANG resists the tendency to solve all possible problems, limiting 533 the problem space to allow expression of NETCONF data models, not 534 arbitrary XML documents or arbitrary data models. The data models 535 described by YANG are designed to be easily operated upon by NETCONF 536 operations. 538 To the extent possible, YANG maintains compatibility with SNMP's 539 SMIv2 (Structure of Management Information version 2 [RFC2578], 540 [RFC2579]). SMIv2-based MIB modules can be automatically translated 541 into YANG modules for read-only access. However YANG is not 542 concerned with reverse translation from YANG to SMIv2. 544 Like NETCONF, YANG targets smooth integration with device's native 545 management infrastructure. This allows implementations to leverage 546 their existing access control mechanisms to protect or expose 547 elements of the data model. 549 4.2. Language Overview 551 This section introduces some important constructs used in YANG that 552 will aid in the understanding of the language specifics in later 553 sections. This progressive approach handles the inter-related nature 554 of YANG concepts and statements. Specifics about YANG statements and 555 syntax begins in Section 7. 557 4.2.1. Modules and Submodules 559 A module contains three types of statements: module-header 560 statements, revision statements, and definition statements. The 561 module header statements describe the module and give information 562 about the module itself, the revision statements give information 563 about the history of the module, and the definition statements are 564 the body of the module where the data model is defined. 566 A NETCONF server may implement a number of modules, allowing multiple 567 views of the same data, or multiple views of disjoint subsections of 568 the device's data. Alternatively, the server may implement only one 569 module that defines all available data. 571 A module may be divided into submodules, based on the needs of the 572 module owner. The external view remains that of a single module, 573 regardless of the presence or size of its submodules. 575 The "include" statement allows a module or submodule to reference 576 material in submodules, and the "import" statement allows references 577 to material defined in other modules. 579 4.2.2. Data Modeling Basics 581 YANG defines four types of nodes for data modeling. In each of the 582 following subsections, the example shows the YANG syntax as well as a 583 corresponding NETCONF XML representation. 585 4.2.2.1. Leaf Nodes 587 A leaf node contains simple data like an integer or a string. It has 588 exactly one value of a particular type, and no child nodes. 590 YANG Example: 592 leaf host-name { 593 type string; 594 description "Hostname for this system"; 595 } 597 NETCONF XML Encoding: 599 my.example.com 601 The "leaf" statement is covered in Section 7.6. 603 4.2.2.2. Leaf-list Nodes 605 A leaf-list is a sequence of leaf nodes with exactly one value of a 606 particular type per leaf. 608 YANG Example: 610 leaf-list domain-search { 611 type string; 612 description "List of domain names to search"; 613 } 615 NETCONF XML Encoding: 617 high.example.com 618 low.example.com 619 everywhere.example.com 621 The "leaf-list" statement is covered in Section 7.7. 623 4.2.2.3. Container Nodes 625 A container node is used to group related nodes in a subtree. A 626 container has only child nodes and no value. A container may contain 627 any number of child nodes of any type (including leafs, lists, 628 containers, and leaf-lists). 630 YANG Example: 632 container system { 633 container login { 634 leaf message { 635 type string; 636 description 637 "Message given at start of login session"; 638 } 639 } 640 } 642 NETCONF XML Encoding: 644 645 646 Good morning, Dave 647 648 650 The "container" statement is covered in Section 7.5. 652 4.2.2.4. List Nodes 654 A list defines a sequence of list entries. Each entry is like a 655 structure or a record instance, and is uniquely identified by the 656 values of its key leafs. A list can define multiple keys and may 657 contain any number of child nodes of any type (including leafs, 658 lists, containers etc.). 660 YANG Example: 662 list user { 663 key "name"; 664 leaf name { 665 type string; 666 } 667 leaf full-name { 668 type string; 669 } 670 leaf class { 671 type string; 672 } 673 } 675 NETCONF XML Encoding: 677 678 glocks 679 Goldie Locks 680 intruder 681 682 683 snowey 684 Snow White 685 free-loader 686 687 688 rzull 689 Repun Zell 690 tower 691 693 The "list" statement is covered in Section 7.8. 695 4.2.2.5. Example Module 697 These statements are combined to define the module: 699 // Contents of "acme-system.yang" 700 module acme-system { 701 namespace "http://acme.example.com/system"; 702 prefix "acme"; 704 organization "ACME Inc."; 705 contact "joe@acme.example.com"; 706 description 707 "The module for entities implementing the ACME system."; 709 revision 2007-06-09 { 710 description "Initial revision."; 711 } 713 container system { 714 leaf host-name { 715 type string; 716 description "Hostname for this system"; 717 } 719 leaf-list domain-search { 720 type string; 721 description "List of domain names to search"; 722 } 724 container login { 725 leaf message { 726 type string; 727 description 728 "Message given at start of login session"; 729 } 731 list user { 732 key "name"; 733 leaf name { 734 type string; 735 } 736 leaf full-name { 737 type string; 738 } 739 leaf class { 740 type string; 741 } 742 } 743 } 744 } 745 } 747 4.2.3. State Data 749 YANG can model state data, as well as configuration data, based on 750 the "config" statement. When a node is tagged with "config false", 751 its subhierarchy is flagged as state data, to be reported using 752 NETCONF's operation, not the operation. Parent 753 containers, lists, and key leafs are reported also, giving the 754 context for the state data. 756 In this example, two leafs are defined for each interface, a 757 configured speed and an observed speed. The observed speed is not 758 configuration, so it can be returned with NETCONF operations, 759 but not with operations. The observed speed is not 760 configuration data, and cannot be manipulated using . 762 list interface { 763 key "name"; 764 config true; 766 leaf name { 767 type string; 768 } 769 leaf speed { 770 type enumeration { 771 enum 10m; 772 enum 100m; 773 enum auto; 774 } 775 } 776 leaf observed-speed { 777 type uint32; 778 config false; 779 } 780 } 782 4.2.4. Built-in Types 784 YANG has a set of built-in types, similar to those of many 785 programming languages, but with some differences due to special 786 requirements from the management domain. The following table 787 summarizes the built-in types discussed in Section 9: 789 +---------------------+-------------+-------------------------------+ 790 | Name | Type | Description | 791 +---------------------+-------------+-------------------------------+ 792 | binary | Text | Any binary data | 793 | bits | Text/Number | A set of bits or flags | 794 | boolean | Text | "true" or "false" | 795 | decimal64 | Number | 64-bit signed decimal number | 796 | empty | Empty | A leaf that does not have any | 797 | | | value | 798 | enumeration | Text/Number | Enumerated strings with | 799 | | | associated numeric values | 800 | identityref | Text | A reference to an abstract | 801 | | | identity | 802 | instance-identifier | Text | References a data tree node | 803 | int8 | Number | 8-bit signed integer | 804 | int16 | Number | 16-bit signed integer | 805 | int32 | Number | 32-bit signed integer | 806 | int64 | Number | 64-bit signed integer | 807 | leafref | Text/Number | A reference to a leaf | 808 | | | instance | 809 | string | Text | Human readable string | 810 | uint8 | Number | 8-bit unsigned integer | 811 | uint16 | Number | 16-bit unsigned integer | 812 | uint32 | Number | 32-bit unsigned integer | 813 | uint64 | Number | 64-bit unsigned integer | 814 | union | Text/Number | Choice of member types | 815 +---------------------+-------------+-------------------------------+ 817 The "type" statement is covered in Section 9. 819 4.2.5. Derived Types (typedef) 821 YANG can define derived types from base types using the "typedef" 822 statement. A base type can be either a built-in type or a derived 823 type, allowing a hierarchy of derived types. 825 A derived type can be used as the argument for the "type" statement. 827 YANG Example: 829 typedef percent { 830 type uint16 { 831 range "0 .. 100"; 832 } 833 description "Percentage"; 834 } 836 leaf completed { 837 type percent; 838 } 840 NETCONF XML Encoding: 842 20 844 The "typedef" statement is covered in Section 7.3. 846 4.2.6. Reusable Node Groups (grouping) 848 Groups of nodes can be assembled into the equivalent of complex types 849 using the "grouping" statement. "grouping" defines a set of nodes 850 that are instantiated with the "uses" statement: 852 grouping target { 853 leaf address { 854 type inet:ip-address; 855 description "Target IP address"; 856 } 857 leaf port { 858 type inet:port-number; 859 description "Target port number"; 860 } 861 } 863 container peer { 864 container destination { 865 uses target; 866 } 867 } 869 NETCONF XML Encoding: 871 872 873
192.0.2.1
874 830 875 876 878 The grouping can be refined as it is used, allowing certain 879 statements to be overridden. In this example, the description is 880 refined: 882 container connection { 883 container source { 884 uses target { 885 refine "address" { 886 description "Source IP address"; 887 } 888 refine "port" { 889 description "Source port number"; 890 } 891 } 892 } 893 container destination { 894 uses target { 895 refine "address" { 896 description "Destination IP address"; 897 } 898 refine "port" { 899 description "Destination port number"; 900 } 901 } 902 } 903 } 905 The "grouping" statement is covered in Section 7.11. 907 4.2.7. Choices 909 YANG allows the data model to segregate incompatible nodes into 910 distinct choices using the "choice" and "case" statements. The 911 "choice" statement contains a set of "case" statements which define 912 sets of schema nodes that cannot appear together. Each "case" may 913 contain multiple nodes, but each node may appear in only one "case" 914 under a "choice". 916 When an element from one case is created, all elements from all other 917 cases are implicitly deleted. The device handles the enforcement of 918 the constraint, preventing incompatibilities from existing in the 919 configuration. 921 The choice and case nodes appear only in the schema tree, not in the 922 data tree or XML encoding. The additional levels of hierarchy are 923 not needed beyond the conceptual schema. 925 YANG Example: 927 container food { 928 choice snack { 929 mandatory true; 930 case sports-arena { 931 leaf pretzel { 932 type empty; 933 } 934 leaf beer { 935 type empty; 936 } 937 } 938 case late-night { 939 leaf chocolate { 940 type enumeration { 941 enum dark; 942 enum milk; 943 enum first-available; 944 } 945 } 946 } 947 } 948 } 950 NETCONF XML Encoding: 952 953 first-available 954 956 The "choice" statement is covered in Section 7.9. 958 4.2.8. Extending Data Models (augment) 960 YANG allows a module to insert additional nodes into data models, 961 including both the current module (and its submodules) or an external 962 module. This is useful e.g. for vendors to add vendor-specific 963 parameters to standard data models in an interoperable way. 965 The "augment" statement defines the location in the data model 966 hierarchy where new nodes are inserted, and the "when" statement 967 defines the conditions when the new nodes are valid. 969 YANG Example: 971 augment system/login/user { 972 when "class != 'wheel'"; 973 leaf uid { 974 type uint16 { 975 range "1000 .. 30000"; 976 } 977 } 978 } 980 This example defines a "uid" node that only is valid when the user's 981 "class" is not "wheel". 983 If a module augments another model, the XML representation of the 984 data will reflect the prefix of the augmenting model. For example, 985 if the above augmentation were in a module with prefix "other", the 986 XML would look like: 988 NETCONF XML Encoding: 990 991 alicew 992 Alice N. Wonderland 993 drop-out 994 1024 995 997 The "augment" statement is covered in Section 7.15. 999 4.2.9. RPC Definitions 1001 YANG allows the definition of NETCONF RPCs. The method names, input 1002 parameters and output parameters are modeled using YANG data 1003 definition statements. 1005 YANG Example: 1007 rpc activate-software-image { 1008 input { 1009 leaf image-name { 1010 type string; 1011 } 1012 } 1013 output { 1014 leaf status { 1015 type string; 1016 } 1017 } 1018 } 1020 NETCONF XML Encoding: 1022 1024 1025 acmefw-2.3 1026 1027 1029 1031 1032 The image acmefw-2.3 is being installed. 1033 1034 1036 The "rpc" statement is covered in Section 7.13. 1038 4.2.10. Notification Definitions 1040 YANG allows the definition of notifications suitable for NETCONF. 1041 YANG data definition statements are used to model the content of the 1042 notification. 1044 YANG Example: 1046 notification link-failure { 1047 description "A link failure has been detected"; 1048 leaf if-name { 1049 type leafref { 1050 path "/interfaces/interface/name"; 1051 } 1052 } 1053 leaf if-admin-status { 1054 type ifAdminStatus; 1055 } 1056 } 1058 NETCONF XML Encoding: 1060 1062 2007-09-01T10:00:00Z 1063 1064 so-1/2/3.0 1065 up 1066 1067 1069 The "notification" statement is covered in Section 7.14. 1071 5. Language Concepts 1073 5.1. Modules and Submodules 1075 The module is the base unit of definition in YANG. A module defines 1076 a single data model. A module can define a complete, cohesive model, 1077 or augment an existing data model with additional nodes. 1079 Submodule are partial modules that contribute definitions to a 1080 module. A module may include any number of submodules, but each 1081 submodule may belong to only one module. 1083 The names of all standard modules and submodules MUST be unique. 1084 Developers of enterprise modules are RECOMMENDED to choose names for 1085 their modules that will have a low probability of colliding with 1086 standard or other enterprise modules, e.g. by using the enterprise or 1087 organization name as a prefix. 1089 A module uses the "include" statement to include its submodules, and 1090 the "import" statement to reference external modules. Similarly, a 1091 submodule uses the "import" statement to reference other modules, and 1092 uses the "include" statement to reference other submodules within its 1093 module. A module or submodule MUST NOT include submodules from other 1094 modules, and a submodule MUST NOT import its own module. 1096 The import and include statements are used to make definitions 1097 available to other modules and submodules: 1099 o For a module or submodule to reference definitions in an external 1100 module, the external module MUST be imported. 1102 o For a module to reference definitions in one of its submodules, 1103 the module MUST include the submodule. 1105 o For a submodule to reference definitions in a second submodule of 1106 the same module, the first submodule MUST include the second 1107 submodule. 1109 There MUST NOT be any circular chains of imports or includes. For 1110 example, if submodule "a" includes submodule "b", "b" cannot include 1111 "a". 1113 When a definition in an external module is referenced, a locally 1114 defined prefix MUST be used, followed by ":", and then the external 1115 identifier. References to definitions in the local module MAY use 1116 the prefix notation. Since built-in data types do not belong to any 1117 module and have no prefix, references to built-in data types (e.g. 1118 int32) cannot use the prefix notation. 1120 5.1.1. Import and Include by Revision 1122 Published modules evolve independently over time. In order to allow 1123 for this evolution, modules need to be imported using specific 1124 revisions. When a module is written, it uses the current revisions 1125 of other modules, based on what is available at the time. As future 1126 revisions of the imported modules are published, the importing module 1127 is unaffected and its contents are unchanged. When the author of the 1128 module is prepared to move to the most recently published revision of 1129 an imported module, the module is republished with an updated import 1130 statement. By republishing with the new revision, the author is 1131 explicitly indicating their acceptance of any changes in the imported 1132 module. 1134 For submodules, the issue is related but simpler. A module or 1135 submodule that includes submodules need to specify the revision of 1136 the included submodules. If a submodule changes, any module or 1137 submodule that includes it needs to be updated. 1139 For example, module "b" imports module "a". 1141 module a { 1142 revision 2008-01-01 { ... } 1143 grouping a { 1144 leaf eh { .... } 1145 } 1146 } 1148 module b { 1149 import a { 1150 prefix a; 1151 revision-date 2008-01-01; 1152 } 1154 container bee { 1155 uses a:a; 1156 } 1157 } 1159 When the author of "a" publishes a new revision, the changes may not 1160 be acceptable to the author of "b". If the new revision is 1161 acceptable, the author of "b" can republish with an updated revision 1162 in the import statement. 1164 5.1.2. Module Hierarchies 1166 YANG allows modeling of data in multiple hierarchies, where data may 1167 have more than one top-level node. Models that have multiple top- 1168 level nodes are sometimes convenient, and are supported by YANG. 1170 NETCONF is capable of carrying any XML content as the payload in the 1171 element. The top-level nodes of YANG modules are encoded as 1172 child elements within the element. 1174 For example: 1176 module my-config { 1177 namespace "http://example.com/schema/config"; 1178 prefix "co"; 1180 container system { ... } 1181 container routing { ... } 1182 } 1184 could be encoded in NETCONF as: 1186 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1204 5.2. File Layout 1206 YANG modules and submodules are typically stored in files, one module 1207 or submodule per file. The name of the file SHOULD be on the form: 1209 module-or-submodule-name ['.' revision-date] ( '.yang' / '.yin' ) 1211 YANG compilers can find imported modules and included submodules via 1212 this convention. While the YANG language defines modules, tools may 1213 compile submodules independently for performance and manageability 1214 reasons. Many errors and warnings that cannot be detected during 1215 submodule compilation may be delayed until the submodules are linked 1216 into a cohesive module. 1218 5.3. XML Namespaces 1220 All YANG definitions are specified within a module that is bound to a 1221 particular XML Namespace [XML-NAMES], which is a globally unique URI 1222 [RFC3986]. A NETCONF client or server uses the namespace during XML 1223 encoding of data. 1225 Namespaces for modules published in RFC streams MUST be assigned by 1226 IANA, see Section 14. 1228 Namespaces for private modules are assigned by the organization 1229 owning the module without a central registry. It is RECOMMENDED to 1230 choose namespaces that will have a low probability of colliding with 1231 standard or other enterprise modules, e.g. by using the enterprise or 1232 organization name in the namespace. 1234 The "namespace" statement is covered in Section 7.1.3. 1236 5.3.1. YANG XML Namespace 1238 YANG defines its own XML namespace for NETCONF 1239 operations. This namespace is "urn:ietf:params:xml:ns:yang:1". 1241 5.4. Resolving Grouping, Type, and Identity Names 1243 Grouping, type, and identity names are resolved in the context in 1244 which they are defined, rather than the context in which they are 1245 used. Users of groupings, typedefs, and identities are not required 1246 to import modules or include submodules to satisfy all references 1247 made by the original definition. This behaves like static scoping in 1248 a conventional programming language. 1250 For example, if a module defines a grouping in which a type is 1251 referenced, when the grouping is used in a second module, the type is 1252 resolved in the context of the original module, not the second 1253 module. There is no worry over conflicts if both modules define the 1254 type, since there is no ambiguity. 1256 5.5. Nested Typedefs and Groupings 1258 Typedefs and groupings may appear nested under many YANG statements, 1259 allowing these to be lexically scoped by the hierarchy under which 1260 they appear. This allows types and groupings to be defined near 1261 where they are used, rather than placing them at the top level of the 1262 hierarchy. The close proximity increases readability. 1264 Scoping also allows types to be defined without concern for naming 1265 conflicts between types in different submodules. Type names can be 1266 specified without adding leading strings designed to prevent name 1267 collisions within large modules. 1269 Finally, scoping allows the module author to keep types and groupings 1270 private to their module or submodule, preventing their reuse. Since 1271 only top-level types and groupings can be used outside the module or 1272 submodule, the developer has more control over what pieces of their 1273 module are presented to the outside world, supporting the need to 1274 hide internal information and maintaining a boundary between what is 1275 shared with the outside world and what is kept private. 1277 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1278 type or group cannot be defined if a higher level in the schema 1279 hierarchy has a definition with a matching identifier. 1281 When a YANG implementation resolves a reference to an unprefixed type 1282 or grouping, or one which uses the prefix of the local module, it 1283 searches up the levels of hierarchy in the schema tree, starting at 1284 the current level, for the definition of the type or grouping. 1286 5.6. Conformance 1288 Conformance is a measure of how accurately a device follows the 1289 model. Generally speaking, devices are responsible for implementing 1290 the model faithfully, allowing applications to treat devices which 1291 implement the model identically. Deviations from the model can 1292 reduce the utility of the model and increase fragility into 1293 applications that use it. 1295 YANG modelers have three mechanisms for conformance: 1297 o the basic behavior of the model 1299 o optional features that are part of the model 1301 o deviations from the model 1303 We will consider each of these in sequence. 1305 5.6.1. Basic Behavior 1307 The model defines a contract between the NETCONF client and server, 1308 which allows both parties to have faith the other knows the syntax 1309 and semantics behind the modeled data. The strength of YANG lies in 1310 the strength of this contract and the mindless devotion with which 1311 implementers follow it. 1313 5.6.2. Optional Features 1315 In many models, the modeler will allow sections of the model to be 1316 conditional, based on the device. The device controls whether these 1317 conditional portions of the model are supported or valid for that 1318 particular device. 1320 For example, a syslog data model may choose to include the ability to 1321 save logs locally, but the modeler will realize that this is only 1322 possible if the device has local storage. If there is no local 1323 storage, an application should not tell the device to save logs. 1325 YANG supports this conditional mechanism using a construct called 1326 "features". Features give the modeler a mechanism for making 1327 portions of the module conditional in a manner that is controlled by 1328 the device. The model can express constructs which are not 1329 universally present in all devices. These features are included in 1330 the model definition, allowing a consistent view and allowing 1331 applications to learn which features are supported and tailor their 1332 behavior to the device. 1334 A module may declare any number of features, identified by simple 1335 strings, and may make portions of the module optional based on those 1336 feature. If the device supports a feature, then the corresponding 1337 portions of the module are valid for that device. If the device 1338 doesn't support the feature, those parts of the module are not valid, 1339 and applications should behave accordingly. 1341 Features are defined using the "feature" statement. Definitions in 1342 the module that are conditional to the feature are noted by the 1343 "if-feature" statement with the name of the feature as its argument. 1345 Further details are available in Section 7.18.1. 1347 5.6.3. Deviations 1349 In an ideal world, all devices would be required to implement the 1350 model exactly as defined, and deviations from the model would not be 1351 allowed. But in the real world, devices are often not able or 1352 willing to implement the model as written. For YANG-based automation 1353 to deal with these device deviations, a mechanism must exist for 1354 devices to inform applications of the specifics of such deviations. 1356 For example, a BGP module may allow any number of BGP peers, but a 1357 particular device may only support 16 BGP peers. Any application 1358 configuring the 17th peer will receive an error. While an error may 1359 suffice to let the application know it cannot add another peer, it 1360 would be far better if the application had prior knowledge of this 1361 limitation and could prevent the user from starting down the path 1362 that could not succeed. 1364 Device deviations are declared using the "deviation" statement, which 1365 takes as its argument a string which identifies a node in the schema 1366 tree. The contents of the statement details the manner in which the 1367 device implementation deviates from the contract as defined in the 1368 module. 1370 5.6.4. Announcing Conformance Information in the Message 1372 The namespace URI is advertised as a capability in the NETCONF 1373 message to indicate support for the YANG module by a NETCONF 1374 server. The capability URI advertised MUST be on the form: 1376 capability-string = namespace-uri [ parameter-list ] 1377 parameter-list = "?" parameter *( "&" parameter ) 1378 parameter = revision-parameter / 1379 module-parameter / 1380 feature-parameter / 1381 deviation-parameter 1382 revision-parameter = "revision=" revision-date 1383 module-parameter = "module=" module-name 1384 feature-parameter = "features=" feature *( "," feature ) 1385 deviation-parameter = "deviations=" deviation *( "," deviation ) 1387 Where "revision-date" is the revision of the module (see 1388 Section 7.1.9) that the NETCONF server implements, "module-name" is 1389 the name of module as it appears in the "module" statement (see 1390 Section 7.1), "namespace-uri" is the namespace for the module as it 1391 appears in the "namespace" statement, "feature" is the name of an 1392 optional feature implemented by the device (see Section 7.18.1), and 1393 "deviation" is the name of a module defining device deviations (see 1394 Section 7.18.3). 1396 5.6.4.1. Modules 1398 Devices indicate the names of supported modules via the 1399 message. Module namespaces are encoded as the base URI in the 1400 capability string, and the module name is encoded as the "module" 1401 parameter to the base URI. 1403 Modules that do not contribute any data definitions, rpcs, 1404 notifications, or deviations to the device MAY be advertised in the 1405 message. 1407 For example, this message advertises one module "syslog". 1409 1410 1411 http://example.com/syslog?module=syslog&revision=2008-04-01 1412 1413 1415 5.6.4.2. Features 1417 Devices indicate the names of supported features via the 1418 message. In hello messages, the features are encoded in the 1419 "features" parameter within the URI. The value of this parameter is 1420 a comma-separated list of feature names which the device supports for 1421 the specific module. 1423 For example, this message advertises one module, informing 1424 the client that it supports the "local-storage" feature of module 1425 "syslog". 1427 1428 1429 http://example.com/syslog?module=syslog&features=local-storage 1430 1431 1433 5.6.4.3. Deviations 1435 Device deviations are announced via the "deviations" parameter. The 1436 value of the deviations parameter is a comma-separated list of 1437 modules containing deviations from the capability's module. 1439 For example, this message advertises two modules, informing 1440 the client that it deviates from module "syslog" according to the 1441 deviations listed in the module "my-devs". 1443 1444 1445 http://example.com/syslog?module=syslog&deviations=my-devs 1446 1447 1448 http://example.com/my-deviations?module=my-devs 1449 1450 1452 5.6.5. Mapping to the NETCONF Schema Discovery Mechanism 1454 +--------------------------------------------------------------+ 1455 | Open Question | 1456 +--------------------------------------------------------------+ 1457 | Move this section to the monitoring spec? | 1458 +--------------------------------------------------------------+ 1460 The NETCONF Schema Discovery process is defined in [TBD]. It 1461 specifies a "schema" list where each entry is identified by 1462 "identifier", "version", and "format". 1464 All revisions of all YANG modules and submodules supported by a 1465 device SHOULD be present in the "schema" list, including modules with 1466 only typedefs and groupings. 1468 The following table specifies how the fields in the "schema" list are 1469 used for YANG modules and submodules: 1471 identifier - the name of the module or submodule. 1472 version - the supported YANG revision string. 1473 format - the string "YANG". 1474 namespace - the module's namespace. if the list entry describes a 1475 submodule, this field contains the namespace of the 1476 module to which the submodule belongs. 1478 Note that the format is "YANG", even if the YIN syntax is used. 1480 6. YANG syntax 1482 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1483 languages like C and C++. This C-like syntax was chosen specifically 1484 for its readability, since YANG values the time and effort of the 1485 readers of models above those of modules writers and YANG tool-chain 1486 developers. This section introduces the YANG syntax. 1488 YANG modules are written in the UTF-8 [RFC3629] character set. 1490 6.1. Lexicographical Tokenization 1492 YANG modules are parsed as a series of tokens. This section details 1493 the rules for recognizing tokens from an input stream. YANG 1494 tokenization rules are both simple and powerful. The simplicity is 1495 driven by a need to keep the parsers easy to implement, while the 1496 power is driven by the fact that modelers need to express their 1497 models in readable formats. 1499 6.1.1. Comments 1501 Comments are C++ style. A single line comment starts with "//" and 1502 ends at the end of the line. A block comment is enclosed within "/*" 1503 and "*/". 1505 6.1.2. Tokens 1507 A token in YANG is either a keyword, a string, ";", "{", or "}". A 1508 string can be quoted or unquoted. A keyword is either one of the 1509 core YANG keywords defined in this document, or a prefix identifier, 1510 followed by ":", followed by a language extension keyword. Keywords 1511 are case sensitive. See Section 6.2 for a formal definition of 1512 identifiers. 1514 6.1.3. Quoting 1516 If a string contains any whitespace characters, a semicolon (";"), 1517 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1518 it MUST be enclosed within double or single quotes. 1520 If the double quoted string contains a line break followed by 1521 whitespace which is used to indent the text according to the layout 1522 in the YANG file, this leading whitespace is stripped from the 1523 string, up to at most the same column of the double quote character. 1525 If the double quoted string contains whitespace before a line break, 1526 this trailing whitespace is stripped from the string. 1528 A single quoted string (enclosed within ' ') preserves each character 1529 within the quotes. A single quote character can not occur in a 1530 single quoted string, even when preceded by a backslash. 1532 If a quoted string is followed by a plus character ("+"), followed by 1533 another quoted string, the two strings are concatenated into one 1534 quoted string, allowing multiple concatenations to build one quoted 1535 string. Whitespace trimming of double quoted strings is done before 1536 concatenation. 1538 Within a double quoted string (enclosed within " "), a backslash 1539 character introduces a special character, which depends on the 1540 character that immediately follows the backslash: 1542 \n new line 1543 \t a tab character 1544 \" a double quote 1545 \\ a single backslash 1547 6.1.3.1. Quoting Examples 1549 The following strings are equivalent: 1551 hello 1552 "hello" 1553 'hello' 1554 "hel" + "lo" 1555 'hel' + "lo" 1557 The following examples show some special strings: 1559 "\"" - string containing a double quote 1560 '"' - string containing a double quote 1561 "\n" - string containing a newline character 1562 '\n' - string containing a backslash followed 1563 by the character n 1565 The following examples show some illegal strings: 1567 '''' - a single-quoted string cannot contain single quotes 1568 """ - a double quote must be escaped in a double quoted string 1570 The following strings are equivalent: 1572 "first line 1573 second line" 1575 "first line\n" + " second line" 1577 6.2. Identifiers 1579 Identifiers are used to identify different kinds of YANG items by 1580 name. Each identifier starts with an upper-case or lower-case ASCII 1581 letter or an underscore character, followed by zero or more ASCII 1582 letters, digits, underscore characters, hyphens, and dots. 1583 Implementations MUST support identifiers up to 64 characters in 1584 length. Identifiers are case sensitive. The identifier syntax is 1585 formally defined by the rule "identifier" in Section 12. Identifiers 1586 can be specified as quoted or unquoted strings. 1588 6.2.1. Identifiers and their namespaces 1590 Each identifier is valid in a namespace which depends on the type of 1591 the YANG item being defined: 1593 o All module and submodule names share the same global module 1594 identifier namespace. 1596 o All extension names defined in a module and its submodules share 1597 the same extension identifier namespace. 1599 o All feature names defined in a module and its submodules share the 1600 same feature identifier namespace. 1602 o All identity names defined in a module and its submodules share 1603 the same identity identifier namespace. 1605 o All derived type names defined within a parent node or at the top- 1606 level of the module or its submodules share the same type 1607 identifier namespace. This namespace is scoped to the parent node 1608 or module. 1610 o All groupings defined within a parent node or at the top-level of 1611 the module or its submodules share the same grouping identifier 1612 namespace. This namespace is scoped to the parent node or module. 1614 o All leafs, leaf-lists, lists, containers, choices, rpcs, and 1615 notifications defined within a parent node or at the top-level of 1616 the module or its submodules share the same identifier namespace. 1617 This namespace is scoped to the parent node or module, unless the 1618 parent node is a case node. In that case, the namespace is scoped 1619 to the parent node of the case node's parent choice node. 1621 o All cases within a choice share the same case identifier 1622 namespace. This namespace is scoped to the parent choice node. 1624 All identifiers defined in a namespace MUST be unique. 1626 Forward references are allowed in YANG. 1628 6.3. Statements 1630 A YANG module contains a sequence of statements. Each statement 1631 starts with a keyword, followed by zero or one argument, followed 1632 either by a semicolon (";") or a block of substatements enclosed 1633 within braces ("{ }"): 1635 statement = keyword [argument] (";" / "{" *statement "}") 1637 The argument is a string, as defined in Section 6.1.2. 1639 6.3.1. Language Extensions 1641 A module can introduce YANG extensions by using the "extension" 1642 keyword (see Section 7.17). The extensions can be imported by other 1643 modules with the "import" statement (see Section 7.1.5). When an 1644 imported extension is used, the extension's keyword MUST be qualified 1645 using the prefix with which the extension's module was imported. If 1646 an extension is used in the module where it is defined, the 1647 extension's keyword MUST be qualified with the module's prefix. 1649 Since submodules cannot include the parent module, any extensions in 1650 the module which need to be exposed to submodules MUST be defined in 1651 a submodule. Submodules can then include this submodule to find the 1652 definition of the extension. 1654 6.4. XPath Evaluations 1656 YANG relies on XPath 1.0 [XPATH] as a notation for specifying many 1657 inter-node references and dependencies. NETCONF clients and servers 1658 are not required to implement an XPath interpreter, but MUST ensure 1659 that the requirements encoded in the data model are enforced. The 1660 manner of enforcement is an implementation decision. The XPath 1661 expressions MUST be valid, but any implementation may choose to 1662 implement them by hand, rather than using the XPath expression 1663 directly. 1665 XPath expressions are evaluated in the context of the current node, 1666 with the namespace of the current module defined as the null 1667 namespace. References to identifiers in external modules MUST be 1668 qualified with appropriate prefixes, and references to the current 1669 module and its submodules MAY use a prefix. 1671 The data model used in the XPath expressions is the same as that used 1672 in XPath 1.0 [XPATH], with the same extension for root node children 1673 as used by XSLT 1.0 [XSLT] (section 3.1). Specifically, it means 1674 that the root node may have any number of root node children. 1676 7. YANG Statements 1678 The following sections describe all of the YANG core statements. 1680 Note that even a statement which does not have any substatements 1681 defined in core YANG can have vendor-specific extensions as 1682 substatements. For example, the "description" statement does not 1683 have any substatements defined in core YANG, but the following is 1684 legal: 1686 description "some text" { 1687 acme:documentation-flag 5; 1688 } 1690 7.1. The module Statement 1692 The "module" statement defines the module's name, and groups all 1693 statements which belong to the module together. The "module" 1694 statement's argument is the name of the module, followed by a block 1695 of substatements that hold detailed module information. The module 1696 name follows the rules for identifiers in Section 6.2. 1698 Names of modules published in RFC streams MUST be assigned by IANA, 1699 see Section 14. 1701 Private module names are assigned by the organization owning the 1702 module without a central registry. It is RECOMMENDED to choose 1703 submodule names that will have a low probability of colliding with 1704 standard or other enterprise modules and submodules, e.g. by using 1705 the enterprise or organization name as a prefix. 1707 A module SHOULD have the following layout: 1709 module { 1711 // header information 1712 1713 1714 1716 // linkage statements 1717 1718 1720 // meta information 1721 1722 1723 1724 1726 // revision history 1727 1729 // module definitions 1730 1731 } 1733 7.1.1. The module's Substatements 1734 +--------------+---------+-------------+ 1735 | substatement | section | cardinality | 1736 +--------------+---------+-------------+ 1737 | anyxml | 7.10 | 0..n | 1738 | augment | 7.15 | 0..n | 1739 | choice | 7.9 | 0..n | 1740 | contact | 7.1.8 | 0..1 | 1741 | container | 7.5 | 0..n | 1742 | description | 7.19.3 | 0..1 | 1743 | deviation | 7.18.3 | 0..n | 1744 | extension | 7.17 | 0..n | 1745 | feature | 7.18.1 | 0..n | 1746 | grouping | 7.11 | 0..n | 1747 | import | 7.1.5 | 0..n | 1748 | include | 7.1.6 | 0..n | 1749 | leaf | 7.6 | 0..n | 1750 | leaf-list | 7.7 | 0..n | 1751 | list | 7.8 | 0..n | 1752 | namespace | 7.1.3 | 1 | 1753 | notification | 7.14 | 0..n | 1754 | organization | 7.1.7 | 0..1 | 1755 | prefix | 7.1.4 | 1 | 1756 | reference | 7.19.4 | 0..1 | 1757 | revision | 7.1.9 | 0..n | 1758 | rpc | 7.13 | 0..n | 1759 | typedef | 7.3 | 0..n | 1760 | uses | 7.12 | 0..n | 1761 | yang-version | 7.1.2 | 0..1 | 1762 +--------------+---------+-------------+ 1764 7.1.2. The yang-version Statement 1766 The "yang-version" statement specifies which version of the YANG 1767 language was used in developing the module. The statement's argument 1768 contains value "1", which is the current yang version and the default 1769 value. 1771 7.1.3. The namespace Statement 1773 The "namespace" statement defines the XML namespace for all XML 1774 elements defined by the module. Its argument is the URI of the 1775 namespace. 1777 See also Section 5.3. 1779 7.1.4. The prefix Statement 1781 The "prefix" statement is used to define the prefix associated with 1782 the module and its namespace. The "prefix" statement's argument is 1783 the prefix string which is used as a prefix to access a module. The 1784 prefix string MAY be used to refer to definitions contained in the 1785 module, e.g. "if:ifName". A prefix follows the same rules as an 1786 identifier (see Section 6.2). 1788 When used inside the "module" statement, the "prefix" statement 1789 defines the prefix to be used when this module is imported. To 1790 improve readability of the NETCONF XML, a NETCONF client or server 1791 which generates XML or XPath that use prefixes, the prefix defined by 1792 a module SHOULD be used, unless there is a conflict. 1794 When used inside the "import" statement, the "prefix" statement 1795 defines the prefix to be used when accessing definitions inside the 1796 imported module. When a reference to an identifier from the imported 1797 module is used, the prefix string for the module from which objects 1798 are being imported is used in combination with a colon (":") and the 1799 identifier, e.g. "if:ifIndex". To improve readability of YANG 1800 modules, the prefix defined by a module SHOULD be used when the 1801 module is imported, unless there is a conflict. 1803 All prefixes, including the prefix for the module itself MUST be 1804 unique within the module or submodule. 1806 7.1.5. The import Statement 1808 The "import" statement makes definitions from one module available 1809 inside another module or submodule. The argument is the name of the 1810 module to import, and the statement is followed by a block of 1811 substatements that holds detailed import information. 1813 The mandatory "prefix" substatement assigns a prefix for the imported 1814 module which is scoped to the importing module or submodule. 1815 Multiple "import" statements may be specified to import from 1816 different modules. 1818 When the optional "revision-date" substatement is present, any 1819 typedef, grouping, extension, feature, and identity referenced by 1820 definitions in the local module are taken from the specified revision 1821 of the imported module. 1823 It is an error to import multiple revisions of the same module. 1825 The import's Substatements 1827 +---------------+---------+-------------+ 1828 | substatement | section | cardinality | 1829 +---------------+---------+-------------+ 1830 | prefix | 7.1.4 | 1 | 1831 | revision-date | 7.1.5.1 | 0..1 | 1832 +---------------+---------+-------------+ 1834 7.1.5.1. The import's revision-date Statement 1836 The import's "revision-date" statement is used to specify the exact 1837 version of the module to import. The "revision-date" statement MUST 1838 match the most recent "revision" statement in the imported module. 1840 7.1.6. The include Statement 1842 The "include" statement is used to make content from a submodule 1843 available to the module. The argument is an identifier which is the 1844 name of the submodule to include. Modules are only allowed to 1845 include submodules that belong to that module, as defined by the 1846 "belongs-to" statement (see Section 7.2.2). 1848 When a module includes a submodule, it incorporates the contents of 1849 the submodule into the node hierarchy of the module. When a 1850 submodule includes another submodule, the target submodule's 1851 definitions are made available to the current submodule. 1853 When the optional "revision-date" is present, the specified revision 1854 of the submodule is included in the module. 1856 It is an error to include multiple revisions of the same submodule. 1858 The includes's Substatements 1860 +---------------+---------+-------------+ 1861 | substatement | section | cardinality | 1862 +---------------+---------+-------------+ 1863 | revision-date | 7.1.5.1 | 0..1 | 1864 +---------------+---------+-------------+ 1866 7.1.7. The organization Statement 1868 The "organization" statement defines the party responsible for this 1869 module. The argument is a string which is used to specify a textual 1870 description of the organization(s) under whose auspices this module 1871 was developed. 1873 7.1.8. The contact Statement 1875 The "contact" statement provides contact information for the module. 1876 The argument is a string which is used to specify the name, postal 1877 address, telephone number, and electronic mail address of the person 1878 to whom technical queries concerning this module should be sent. 1880 7.1.9. The revision Statement 1882 The "revision" statement specifies the editorial revision history of 1883 the module, including the initial revision. A series of revisions 1884 statements detail the changes in the module's definition. The 1885 argument is a date string in the format "YYYY-MM-DD", followed by a 1886 block of substatements that holds detailed revision information. A 1887 module SHOULD have at least one initial "revision" statement. For 1888 every editorial change, a new one SHOULD be added in front of the 1889 revisions sequence, so that all revisions are in reverse 1890 chronological order. 1892 7.1.9.1. The revision's Substatement 1894 +--------------+---------+-------------+ 1895 | substatement | section | cardinality | 1896 +--------------+---------+-------------+ 1897 | description | 7.19.3 | 0..1 | 1898 +--------------+---------+-------------+ 1900 7.1.10. Usage Example 1902 module acme-system { 1903 namespace "http://acme.example.com/system"; 1904 prefix "acme"; 1906 import ietf-yang-types { 1907 prefix "yang"; 1908 } 1910 include acme-types; 1912 organization "ACME Inc."; 1913 contact 1914 "Joe L. User 1916 ACME, Inc. 1917 42 Anywhere Drive 1918 Nowhere, CA 95134 1919 USA 1921 Phone: +1 800 555 0815 1922 EMail: joe@acme.example.com"; 1924 description 1925 "The module for entities implementing the ACME protocol."; 1927 revision "2007-06-09" { 1928 description "Initial revision."; 1929 } 1931 // definitions follows... 1932 } 1934 7.2. The submodule Statement 1936 While the primary unit in YANG is a module, a YANG module can itself 1937 be constructed out of several submodules. Submodules allows a module 1938 designer to split a complex model into several pieces where all the 1939 submodules contribute to a single namespace, which is defined by the 1940 module that includes the submodules. 1942 The "submodule" statement is used to give the submodule a name, and 1943 to group all statements which belong to the submodule together. 1945 The "submodule" statement, which MUST be present at most once, takes 1946 as an argument an identifier which is the name of the submodule, 1947 followed by a block of substatements that hold detailed submodule 1948 information. 1950 Names of submodules published in RFC streams MUST be assigned by 1951 IANA, see Section 14. 1953 Private submodule names are assigned by the organization owning the 1954 submodule without a central registry. It is RECOMMENDED to choose 1955 submodule names that will have a low probability of colliding with 1956 standard or other enterprise modules and submodules, e.g. by using 1957 the enterprise or organization name as a prefix. 1959 A submodule SHOULD have the following layout: 1961 submodule { 1963 1965 // module identification 1966 1968 // linkage statements 1969 1970 1972 // meta information 1973 1974 1975 1976 1978 // revision history 1979 1981 // module definitions 1982 1983 } 1985 7.2.1. The submodule's Substatements 1986 +--------------+---------+-------------+ 1987 | substatement | section | cardinality | 1988 +--------------+---------+-------------+ 1989 | anyxml | 7.10 | 0..n | 1990 | augment | 7.15 | 0..n | 1991 | belongs-to | 7.2.2 | 1 | 1992 | choice | 7.9 | 0..n | 1993 | contact | 7.1.8 | 0..1 | 1994 | container | 7.5 | 0..n | 1995 | description | 7.19.3 | 0..1 | 1996 | deviation | 7.18.3 | 0..n | 1997 | extension | 7.17 | 0..n | 1998 | feature | 7.18.1 | 0..n | 1999 | grouping | 7.11 | 0..n | 2000 | import | 7.1.5 | 0..n | 2001 | include | 7.1.6 | 0..n | 2002 | leaf | 7.6 | 0..n | 2003 | leaf-list | 7.7 | 0..n | 2004 | list | 7.8 | 0..n | 2005 | notification | 7.14 | 0..n | 2006 | organization | 7.1.7 | 0..1 | 2007 | reference | 7.19.4 | 0..1 | 2008 | revision | 7.1.9 | 0..n | 2009 | rpc | 7.13 | 0..n | 2010 | typedef | 7.3 | 0..n | 2011 | uses | 7.12 | 0..n | 2012 | yang-version | 7.1.2 | 0..1 | 2013 +--------------+---------+-------------+ 2015 7.2.2. The belongs-to Statement 2017 The "belongs-to" statement specifies the module to which the 2018 submodule belongs. The argument is an identifier which is the name 2019 of the module. 2021 A submodule MUST only be included by the module to which it belongs, 2022 or by another submodule which belongs to that module. 2024 The mandatory "prefix" substatement assigns a prefix for the module 2025 to which the submodule belongs. All definitions in the local 2026 submodule and any included submodules can be accessed by using the 2027 prefix. 2029 The belongs-to's Substatements 2031 +--------------+---------+-------------+ 2032 | substatement | section | cardinality | 2033 +--------------+---------+-------------+ 2034 | prefix | 7.1.4 | 1 | 2035 +--------------+---------+-------------+ 2037 7.2.3. Usage Example 2039 submodule acme-types { 2041 belongs-to "acme-system" { 2042 prefix "acme"; 2043 } 2045 import ietf-yang-types { 2046 prefix "yang"; 2047 } 2049 organization "ACME Inc."; 2050 contact 2051 "Joe L. User 2053 ACME, Inc. 2054 42 Anywhere Drive 2055 Nowhere, CA 95134 2056 USA 2058 Phone: +1 800 555 0815 2059 EMail: joe@acme.example.com"; 2061 description 2062 "This submodule defines common ACME types."; 2064 revision "2007-06-09" { 2065 description "Initial revision."; 2066 } 2068 // definitions follows... 2069 } 2071 7.3. The typedef Statement 2073 The "typedef" statement defines a new type which may be used locally 2074 in the module, in modules or submodules which include it, and by 2075 other modules which import from it, according to the rules in 2076 Section 5.5. The new type is called the "derived type", and the type 2077 from which it was derived is called the "base type". All derived 2078 types can be traced back to a YANG built-in type. 2080 The "typedef" statement's argument is an identifier which is the name 2081 of the type to be defined, and MUST be followed by a block of 2082 substatements that holds detailed typedef information. 2084 The name of the type MUST NOT be one of the YANG built-in types. If 2085 the typedef is defined at the top level of a YANG module or 2086 submodule, the name of the type to be defined MUST be unique within 2087 the module. 2089 7.3.1. The typedef's Substatements 2091 +--------------+---------+-------------+ 2092 | substatement | section | cardinality | 2093 +--------------+---------+-------------+ 2094 | default | 7.3.4 | 0..1 | 2095 | description | 7.19.3 | 0..1 | 2096 | reference | 7.19.4 | 0..1 | 2097 | status | 7.19.2 | 0..1 | 2098 | type | 7.3.2 | 1 | 2099 | units | 7.3.3 | 0..1 | 2100 +--------------+---------+-------------+ 2102 7.3.2. The typedef's type Statement 2104 The "type" statement, which MUST be present, defines the base type 2105 from which this type is derived. See Section 7.4 for details. 2107 7.3.3. The units Statement 2109 The "units" statement, which is optional, takes as an argument a 2110 string which contains a textual definition of the units associated 2111 with the type. 2113 7.3.4. The typedef's default Statement 2115 The "default" statement takes as an argument a string which contains 2116 a default value for the new type. 2118 The value of the "default" statement MUST be valid according to the 2119 type specified in the "type" statement. 2121 If the base type has a default value, and the new derived type does 2122 not specify a new default value, the base type's default value is 2123 also the default value of the new derived type. If the base type's 2124 default value is not valid according to the new restrictions, the 2125 derived type MUST define a new default value. 2127 7.3.5. Usage Example 2129 typedef listen-ipv4-address { 2130 type inet:ipv4-address; 2131 default "0.0.0.0"; 2132 } 2134 7.4. The type Statement 2136 The "type" statement takes as an argument a string which is the name 2137 of a YANG built-in type (see Section 9) or a derived type (see 2138 Section 7.3), followed by an optional block of substatements that are 2139 used to put further restrictions on the type. 2141 The restrictions that can be applied depend on the type being 2142 restricted. The restriction statements are described in subsections 2143 for each built-in type in Section 9. 2145 7.4.1. The type's Substatements 2147 +--------------+---------+-------------+ 2148 | substatement | section | cardinality | 2149 +--------------+---------+-------------+ 2150 | bit | 9.7.4 | 0..n | 2151 | enum | 9.6.4 | 0..n | 2152 | length | 9.4.4 | 0..1 | 2153 | path | 9.9.2 | 0..1 | 2154 | pattern | 9.4.6 | 0..n | 2155 | range | 9.2.4 | 0..1 | 2156 | type | 7.4 | 0..n | 2157 +--------------+---------+-------------+ 2159 7.5. The container Statement 2161 The "container" statement is used to define an interior node in the 2162 schema tree. It takes one argument, which is an identifier, followed 2163 by a block of substatements that holds detailed container 2164 information. 2166 A container node does not have a value, but it has a list of child 2167 nodes in the data tree. The child nodes are defined in the 2168 container's substatements. 2170 7.5.1. Containers with Presence 2172 YANG supports two styles of containers, those which exist only for 2173 organizing the hierarchy of data nodes, and those whose presence in 2174 the configuration has an explicit meaning. 2176 In the first style, the container has no meaning of its own, existing 2177 only to contain child nodes. This is the default style. 2179 For example, the set of scrambling options for SONET interfaces may 2180 be placed inside a "scrambling" container to enhance the organization 2181 of the configuration hierarchy, and to keep these nodes together. 2182 The "scrambling" node itself has no meaning, so removing the node 2183 when it becomes empty relieves the user from the task of performing 2184 this task. 2186 In the second style, the presence of the container itself is 2187 configuration data, representing a single bit of configuration data. 2188 The container acts as both a configuration knob and a means of 2189 organizing related configuration. These containers are explicitly 2190 created and deleted. 2192 YANG calls this style a "presence container" and they are indicated 2193 using the "presence" statement, which takes as its argument a text 2194 string indicating what the presence of the node means. 2196 For example, an "ssh" container may turn on the ability to log into 2197 the device using ssh, but can also contain any ssh-related 2198 configuration knobs, such as connection rates or retry limits. 2200 The "presence" statement (see Section 7.5.5) is used to give 2201 semantics to the existence of the container in the data tree. 2203 7.5.2. The container's Substatements 2205 +--------------+---------+-------------+ 2206 | substatement | section | cardinality | 2207 +--------------+---------+-------------+ 2208 | anyxml | 7.10 | 0..n | 2209 | choice | 7.9 | 0..n | 2210 | config | 7.19.1 | 0..1 | 2211 | container | 7.5 | 0..n | 2212 | description | 7.19.3 | 0..1 | 2213 | grouping | 7.11 | 0..n | 2214 | if-feature | 7.18.2 | 0..n | 2215 | leaf | 7.6 | 0..n | 2216 | leaf-list | 7.7 | 0..n | 2217 | list | 7.8 | 0..n | 2218 | must | 7.5.3 | 0..n | 2219 | presence | 7.5.5 | 0..1 | 2220 | reference | 7.19.4 | 0..1 | 2221 | status | 7.19.2 | 0..1 | 2222 | typedef | 7.3 | 0..n | 2223 | uses | 7.12 | 0..n | 2224 | when | 7.19.5 | 0..1 | 2225 +--------------+---------+-------------+ 2227 7.5.3. The must Statement 2229 The "must" statement, which is optional, takes as an argument a 2230 string which contains an XPath expression. It is used to formally 2231 declare a constraint on valid data. The constraint is enforced 2232 according to the rules in Section 8. 2234 When a data store is validated, all "must" constraints are 2235 conceptually evaluated once for each corresponding instance in the 2236 data tree, and for all leafs with default values in effect. If an 2237 instance does not exist in the data tree, and it does not have a 2238 default value, its "must" statements are not evaluated. 2240 All such constraints MUST evaluate to true for the data to be valid. 2242 The XPath expression is conceptually evaluated in the following 2243 context: 2245 o The context node is the node in the data tree for which the "must" 2246 statement is defined. 2248 o The accessible tree is made up of all nodes in the data tree, and 2249 all leafs with default values. 2251 o The set of namespace declarations is the set of all "import" 2252 statements' prefix and namespace pairs, and the "prefix" 2253 statement's prefix for the "namespace" statement's URI. 2255 o Elements without a namespace refer to nodes in the current module. 2257 o The function library is the core function library defined in 2258 [XPATH], and a function "current()" which returns a node set with 2259 the initial context node. 2261 The accessible data tree depends on the context node: 2263 o If the context node represents configuration, the tree is the data 2264 in one of the datastores , , or . 2265 The XPath root node has all top-level configuration data nodes in 2266 all modules as children. 2268 o If the context node represents state data, the tree is all state 2269 data on the device, and the datastore. The XPath root 2270 node has all top-level data nodes in all modules as children. 2272 o If the context node represents notification content, the tree is 2273 the notification XML instance document. The XPath root node has 2274 the element representing the notification being defined as the 2275 only child. 2277 o If the context node represents RPC input parameters, the tree is 2278 the RPC XML instance document. The XPath root node has the 2279 element representing the RPC method being defined as the only 2280 child. 2282 o If the context node represents RPC output parameters, the tree is 2283 the RPC reply instance document. The XPath root node has the 2284 elements representing the RPC output parameters as children. 2286 The result of the XPath expression is converted to a boolean value 2287 using the standard XPath rules. 2289 Note that since all leaf values in the data tree are conceptually 2290 stored in their canonical form (see Section 7.6 and Section 7.7), any 2291 XPath comparisons are done on the canonical value. 2293 Also note that the XPath expression is conceptually evaluated. This 2294 means that an implementation does not have to use an XPath evaluator 2295 on the device. How the evaluation is done in practice is an 2296 implementation decision. 2298 7.5.4. The must's Substatements 2300 +---------------+---------+-------------+ 2301 | substatement | section | cardinality | 2302 +---------------+---------+-------------+ 2303 | description | 7.19.3 | 0..1 | 2304 | error-app-tag | 7.5.4.2 | 0..1 | 2305 | error-message | 7.5.4.1 | 0..1 | 2306 | reference | 7.19.4 | 0..1 | 2307 +---------------+---------+-------------+ 2309 7.5.4.1. The error-message Statement 2311 The "error-message" statement, which is optional, takes a string as 2312 an argument. If the constraint evaluates to false, the string is 2313 passed as in the . 2315 7.5.4.2. The error-app-tag Statement 2317 The "error-app-tag" statement, which is optional, takes a string as 2318 an argument. If the constraint evaluates to false, the string is 2319 passed as in the . 2321 7.5.4.3. Usage Example of must and error-message 2323 container interface { 2324 leaf ifType { 2325 type enumeration { 2326 enum ethernet; 2327 enum atm; 2328 } 2329 } 2330 leaf ifMTU { 2331 type uint32; 2332 } 2333 must "ifType != 'ethernet' or " + 2334 "(ifType = 'ethernet' and ifMTU = 1500)" { 2335 error-message "An ethernet MTU must be 1500"; 2336 } 2337 must "ifType != 'atm' or " + 2338 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2339 error-message "An atm MTU must be 64 .. 17966"; 2340 } 2341 } 2343 7.5.5. The presence Statement 2345 The "presence" statement assigns a meaning to the presence of a 2346 container in the data tree. It takes as an argument a string which 2347 contains a textual description of what the node's presence means. 2349 If a container has the "presence" statement, the container's 2350 existence in the data tree carries some meaning. Otherwise, the 2351 container is used to give some structure to the data, and it carries 2352 no meaning by itself. 2354 See Section 7.5.1 for additional information. 2356 7.5.6. The container's Child Node Statements 2358 Within a container, the "container", "leaf", "list", "leaf-list", 2359 "uses", and "choice" statements can be used to define child nodes to 2360 the container. 2362 7.5.7. XML Encoding Rules 2364 A container node is encoded as an XML element. The element's name is 2365 the container's identifier, and its XML namespace is the module's XML 2366 namespace. 2368 The container's child nodes are encoded as subelements to the 2369 container element. If the container defines RPC input or output 2370 parameters, the subelements are encoded in the same order as they are 2371 defined within the container statement. Otherwise, the subelements 2372 are encoded in any order. 2374 A NETCONF server that replies to a or request MAY 2375 choose not to send a container element if the container node does not 2376 have the "presence" statement and no child nodes exist. Thus, a 2377 client that receives an for a or 2378 request, must be prepared to handle the case that a container node 2379 without a presence statement is not present in the XML. 2381 7.5.8. NETCONF Operations 2383 When a NETCONF server processes an request, the 2384 elements of procedure for the container node are: 2386 If the operation is "merge" the node is created if it does not 2387 exist. 2389 If the operation is "replace" and the node exists, all child nodes 2390 not present in the XML are deleted, and child nodes present in the 2391 XML but not present in the datastore are created. 2393 If the operation is "create" the node is created if it does not 2394 exist. 2396 If the operation is "delete" the node is deleted if it exists. 2398 If the container has a "presence" statement, it MAY be implicitly 2399 created if it does not exist, even if the operation is "none". 2401 If a container has a "presence" statement and the last child node 2402 is deleted, the NETCONF server MAY delete the container. 2404 7.5.9. Usage Example 2406 Given the following container definition: 2408 container system { 2409 description "Contains various system parameters"; 2410 container services { 2411 description "Configure externally available services"; 2412 container "ssh" { 2413 presence "Enables SSH"; 2414 description "SSH service specific configuration"; 2415 // more leafs, containers and stuff here... 2416 } 2417 } 2418 } 2420 A corresponding XML encoding would look like this: 2422 2423 2424 2425 2426 2428 Since the element is present, ssh is enabled. 2430 To delete a container with an : 2432 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2449 7.6. The leaf Statement 2451 The "leaf" statement is used to define a leaf node in the schema 2452 tree. It takes one argument, which is an identifier, followed by a 2453 block of substatements that holds detailed leaf information. 2455 A leaf node has a value, but no child nodes in the data tree. 2456 Conceptually, the value in the data tree is always in the canonical 2457 form (see Section 9.1). 2459 A leaf node exists in zero or one instances in the data tree, 2460 depending on the value of the "mandatory" statement. 2462 The "leaf" statement is used to define a scalar variable of a 2463 particular built-in or derived type. 2465 If a leaf has a "default" statement, the leaf's default value is set 2466 to the value of the "default" statement. Otherwise, if the leaf's 2467 type has a default value, and the leaf is not mandatory, then the 2468 leaf's default value is set to the type's default value. In all 2469 other cases, the leaf does not have a default value. 2471 If the leaf has a default value, the server MUST use this value 2472 internally if no value is provided by the NETCONF client when the 2473 instance is created. 2475 7.6.1. The leaf's Substatements 2477 +--------------+---------+-------------+ 2478 | substatement | section | cardinality | 2479 +--------------+---------+-------------+ 2480 | config | 7.19.1 | 0..1 | 2481 | default | 7.6.3 | 0..1 | 2482 | description | 7.19.3 | 0..1 | 2483 | if-feature | 7.18.2 | 0..n | 2484 | mandatory | 7.6.4 | 0..1 | 2485 | must | 7.5.3 | 0..n | 2486 | reference | 7.19.4 | 0..1 | 2487 | status | 7.19.2 | 0..1 | 2488 | type | 7.6.2 | 1 | 2489 | units | 7.3.3 | 0..1 | 2490 | when | 7.19.5 | 0..1 | 2491 +--------------+---------+-------------+ 2493 7.6.2. The leaf's type Statement 2495 The "type" statement, which MUST be present, takes as an argument the 2496 name of an existing built-in or derived type. The optional 2497 substatements specify restrictions on this type. See Section 7.4 for 2498 details. 2500 7.6.3. The leaf's default Statement 2502 The "default" statement, which is optional, takes as an argument a 2503 string which contains a default value for the leaf. 2505 The value of the "default" statement MUST be valid according to the 2506 type specified in the leaf's "type" statement. 2508 The "default" statement MUST NOT be present on nodes where 2509 "mandatory" is true. 2511 7.6.4. The leaf's mandatory Statement 2513 The "mandatory" statement, which is optional, takes as an argument 2514 the string "true" or "false", and puts a constraint on valid data. 2515 If not specified, the default is "false". 2517 If "mandatory" is "true", the behavior of the constraint depends on 2518 the type of the leaf's closest ancestor node in the schema tree which 2519 is not a non-presence container (see Section 7.5.1): 2521 o If this ancestor is a case node, the leaf MUST exist if any other 2522 node from the case exists. 2524 o Otherwise, the leaf MUST exist if the ancestor node exists. 2526 This constraint is enforced according to the rules in Section 8. 2528 7.6.5. XML Encoding Rules 2530 A leaf node is encoded as an XML element. The element's name is the 2531 leaf's identifier, and its XML namespace is the module's XML 2532 namespace. 2534 The value of the leaf node is encoded to XML according to the type, 2535 and sent as character data in the element. 2537 A NETCONF server that replies to a or request MAY 2538 choose not to send the leaf element if its value is the default 2539 value. Thus, a client that receives an for a or 2540 request, MUST be prepared to handle the case that a leaf 2541 node with a default value is not present in the XML. In this case, 2542 the value used by the server is known to be the default value. 2544 See Section 7.6.7 for an example. 2546 7.6.6. NETCONF Operations 2548 When a NETCONF server processes an request, the 2549 elements of procedure for the leaf node are: 2551 If the operation is "merge", the node is created if it does not 2552 exist, and its value is set to the value found in the XML RPC 2553 data. 2555 If the operation is "replace", the node is created if it does not 2556 exist, and its value is set to the value found in the XML RPC 2557 data. 2559 If the operation is "create" the node is created if it does not 2560 exist. 2562 If the operation is "delete" the node is deleted if it exists. 2564 7.6.7. Usage Example 2566 Given the following leaf statement: 2568 leaf port { 2569 type inet:port-number; 2570 default 22; 2571 description "The port which the SSH server listens to" 2572 } 2574 A corresponding XML encoding: 2576 2022 2578 To create a leaf with an : 2580 2583 2584 2585 2586 2587 2588 2589 2590 2591 2022 2592 2593 2594 2595 2596 2597 2599 7.7. The leaf-list Statement 2601 Where the "leaf" statement is used to define a simple scalar variable 2602 of a particular type, the "leaf-list" statement is used to define an 2603 array of a particular type. The "leaf-list" statement takes one 2604 argument, which is an identifier, followed by a block of 2605 substatements that holds detailed leaf-list information. 2607 The values in a leaf-list MUST be unique. 2609 Conceptually, the values in the data tree are always in the canonical 2610 form (see Section 9.1). 2612 If the type referenced by the leaf-list has a default value, it has 2613 no effect in the leaf-list. 2615 7.7.1. Ordering 2617 YANG supports two styles for ordering the entries within a list. In 2618 many lists, the order of list entries does not impact the 2619 implementation of the list's configuration, and the device is free to 2620 sort the list entries in any reasonable order. The "description" 2621 string for the list may suggest an order. YANG calls this style of 2622 list "system ordered" and they are indicated with the statement 2623 "ordered-by system". 2625 For example, a list of valid users would typically be sorted 2626 alphabetically, since the order in which the users appeared in the 2627 configuration would not impact the creation of those users' accounts. 2629 In the other style of lists, the order of list entries matters for 2630 the implementation of the list's configuration and the user is 2631 responsible for ordering the entries, while the device maintains that 2632 order. YANG calls this style of list "user ordered" and they are 2633 indicated with the statement "ordered-by user". 2635 For example, the order in which firewall filters entries are applied 2636 to incoming traffic may affect how that traffic is filtered. The 2637 user would need to decide if the filter entry that discards all TCP 2638 traffic should be applied before or after the filter entry that 2639 allows all traffic from trusted interfaces. The choice of order 2640 would be crucial. 2642 YANG provides a rich set of facilities within NETCONF's 2643 operation which allow the order of list entries in user-ordered lists 2644 to be controlled. List entries may be inserted or rearranged, 2645 positioned as the first or last entry in the list, or positioned 2646 before or after another specific entry. 2648 The "ordered-by" statement is covered in Section 7.7.5. 2650 7.7.2. The leaf-list's Substatements 2652 +--------------+---------+-------------+ 2653 | substatement | section | cardinality | 2654 +--------------+---------+-------------+ 2655 | config | 7.19.1 | 0..1 | 2656 | description | 7.19.3 | 0..1 | 2657 | if-feature | 7.18.2 | 0..n | 2658 | max-elements | 7.7.4 | 0..1 | 2659 | min-elements | 7.7.3 | 0..1 | 2660 | must | 7.5.3 | 0..n | 2661 | ordered-by | 7.7.5 | 0..1 | 2662 | reference | 7.19.4 | 0..1 | 2663 | status | 7.19.2 | 0..1 | 2664 | type | 7.4 | 1 | 2665 | units | 7.3.3 | 0..1 | 2666 | when | 7.19.5 | 0..1 | 2667 +--------------+---------+-------------+ 2669 7.7.3. The min-elements Statement 2671 The "min-elements" statement, which is optional, takes as an argument 2672 a non-negative integer which puts a constraint on valid list entries. 2673 A valid leaf-list or list MUST have least min-elements entries. 2675 If no "min-elements" statement is present, it defaults to zero. 2677 The behavior of the constraint depends on the type of the leaf-list's 2678 or list's closest ancestor node in the schema tree which is not a 2679 non-presence container (see Section 7.5.1): 2681 o If this ancestor is a case node, the constraint is enforced if any 2682 other node from the case exists. 2684 o Otherwise, it is enforced if the ancestor node exists. 2686 The constraint is further enforced according to the rules in 2687 Section 8. 2689 7.7.4. The max-elements Statement 2691 The "max-elements" statement, which is optional, takes as an argument 2692 a positive integer or the string "unbounded", which puts a constraint 2693 on valid list entries. A valid leaf-list or list always has at most 2694 max-elements entries. 2696 If no "max-elements" statement is present, it defaults to 2697 "unbounded". 2699 The "max-elements" constraint is enforced according to the rules in 2700 Section 8. 2702 7.7.5. The ordered-by Statement 2704 The "ordered-by" statement defines whether the order of entries 2705 within a list are determined by the user or the system. The argument 2706 is one of the strings "system" or "user". If not present, order 2707 defaults to "system". 2709 This statement is ignored if the list represents state data, RPC 2710 output parameters, or notification content. 2712 See Section 7.7.1 for additional information. 2714 7.7.5.1. ordered-by system 2716 The entries in the list are sorted according to an unspecified order. 2717 Thus an implementation is free to sort the entries in the most 2718 appropriate order. An implementation SHOULD use the same order for 2719 the same data, regardless of how the data were created. Using a 2720 deterministic order will makes comparisons possible using simple 2721 tools like "diff". 2723 This is the default order. 2725 7.7.5.2. ordered-by user 2727 The entries in the list are sorted according to an order defined by 2728 the user. This order is controlled by using special XML attributes 2729 in the request. See Section 7.7.7 for details. 2731 7.7.6. XML Encoding Rules 2733 A leaf-list node is encoded as a series of XML elements. Each 2734 element's name is the leaf-list's identifier, and its XML namespace 2735 is the module's XML namespace. 2737 The value of the leaf-list node is encoded to XML according to the 2738 type, and sent as character data in the element. 2740 See Section 7.7.8 for an example. 2742 7.7.7. NETCONF operations 2744 Leaf-list entries can be created and deleted, but not modified, 2745 through , by using the "operation" attribute in the 2746 leaf-list entry's XML element. 2748 In an "ordered-by user" leaf-list, the attributes "insert" and 2749 "value" in the YANG XML namespace (Section 5.3.1) can be used to 2750 control where in the leaf-list the entry is inserted. These can be 2751 used during "create" operations to insert a new leaf-list entry, or 2752 during "merge" or "replace" operations to insert a new leaf-list 2753 entry or move an existing one. 2755 The "insert" attribute can take the values "first", "last", "before", 2756 and "after". If the value is "before" or "after", the "value" 2757 attribute MUST also be used to specify an existing entry in the leaf- 2758 list. 2760 If no "insert" attribute is present in the "create" operation, it 2761 defaults to "last". 2763 In a , or an with a "replace" operation 2764 which covers the entire leaf-list, the leaf-list order is the same as 2765 the order of the XML elements in the request. 2767 When a NETCONF server processes an request, the 2768 elements of procedure for a leaf-list node are: 2770 If the operation is "merge" or "replace" the leaf-list entry is 2771 created if it does not exist. 2773 If the operation is "create" the leaf-list entry is created if it 2774 does not exist. 2776 If the operation is "delete" the entry is deleted from the leaf- 2777 list if it exists. 2779 7.7.8. Usage Example 2781 leaf-list allow-user { 2782 type string; 2783 description "A list of user name patterns to allow"; 2784 } 2786 A corresponding XML encoding: 2788 alice 2789 bob 2791 To create a new element in the list: 2793 2796 2797 2798 2799 2800 2801 2802 2803 2804 eric 2805 2806 2807 2808 2809 2810 2812 Given the following ordered-by user leaf-list: 2814 leaf-list cipher { 2815 type string; 2816 ordered-by user; 2817 description "A list of ciphers"; 2818 } 2820 The following would be used to insert a new cipher "blowfish-cbc" 2821 after "3des-cbc": 2823 2827 2828 2829 2830 2831 2832 2833 2834 2835 blowfish-cbc 2838 2839 2840 2841 2842 2843 2845 7.8. The list Statement 2847 The "list" statement is used to define interior nodes in the schema 2848 tree. A list node may exist in multiple instances in the data tree. 2849 Each such instance is known as a list entry. The "list" statement 2850 takes one argument which is an identifier, followed by a block of 2851 substatements that holds detailed list information. 2853 A list entry is uniquely identified by the values of the list's keys. 2855 A list is similar to a table where each list entry is a row in the 2856 table. 2858 7.8.1. The list's Substatements 2860 +--------------+---------+-------------+ 2861 | substatement | section | cardinality | 2862 +--------------+---------+-------------+ 2863 | anyxml | 7.10 | 0..n | 2864 | choice | 7.9 | 0..n | 2865 | config | 7.19.1 | 0..1 | 2866 | container | 7.5 | 0..n | 2867 | description | 7.19.3 | 0..1 | 2868 | grouping | 7.11 | 0..n | 2869 | if-feature | 7.18.2 | 0..n | 2870 | key | 7.8.2 | 0..1 | 2871 | leaf | 7.6 | 0..n | 2872 | leaf-list | 7.7 | 0..n | 2873 | list | 7.8 | 0..n | 2874 | max-elements | 7.7.4 | 0..1 | 2875 | min-elements | 7.7.3 | 0..1 | 2876 | must | 7.5.3 | 0..n | 2877 | ordered-by | 7.7.5 | 0..1 | 2878 | reference | 7.19.4 | 0..1 | 2879 | status | 7.19.2 | 0..1 | 2880 | typedef | 7.3 | 0..n | 2881 | unique | 7.8.3 | 0..n | 2882 | uses | 7.12 | 0..n | 2883 | when | 7.19.5 | 0..1 | 2884 +--------------+---------+-------------+ 2886 7.8.2. The list's key Statement 2888 The "key" statement, which MUST be present if the list represents 2889 configuration, and MAY be present otherwise, takes as an argument a 2890 string which specifies a space separated list of leaf identifiers of 2891 this list. A leaf identifier MUST NOT appear more than once in the 2892 key. Each such leaf identifier MUST refer to a child leaf of the 2893 list. 2895 The combined values of all the leafs specified in the key are used to 2896 uniquely identify a list entry. All key leafs MUST be given values 2897 when a list entry is created. Thus, any default values in the key 2898 leafs or their types are ignored. It also implies that any mandatory 2899 statement in the key leafs are ignored. 2901 A leaf that is part of the key can be of any built-in or derived 2902 type, except it MUST NOT be the built-in type "empty". 2904 All key leafs in a list MUST have the same value for their "config" 2905 as the list itself. 2907 The key string syntax is formally defined by the rule "key-arg" in 2908 Section 12. 2910 7.8.3. The list's unique Statement 2912 The "unique" statement is used to put constraints on valid list 2913 entries. It takes as an argument a string which contains a space 2914 separated list of schema node identifiers, which MUST be given in the 2915 descendant form (see the rule "descendant-schema-nodeid" in 2916 Section 12). Each such schema node identifier MUST refer to a leaf. 2918 If one of the referenced leafs represents configuration data, then 2919 all of the referenced leafs MUST represent configuration data. 2921 The "unique" constraint specifies that the combined values of all the 2922 leaf instances specified in the argument string, including leafs with 2923 default values, MUST be unique within all list entry instances in 2924 which all referenced leafs exist. The constraint is enforced 2925 according to the rules in Section 8. 2927 The unique string syntax is formally defined by the rule "unique-arg" 2928 in Section 12. 2930 7.8.3.1. Usage Example 2932 With the following list: 2934 list server { 2935 key "name"; 2936 unique "ip port"; 2937 leaf name { 2938 type string; 2939 } 2940 leaf ip { 2941 type inet:ip-address; 2942 } 2943 leaf port { 2944 type inet:port-number; 2945 } 2946 } 2948 The following configuration is not valid: 2950 2951 smtp 2952 192.0.2.1 2953 25 2954 2956 2957 http 2958 192.0.2.1 2959 25 2960 2962 The following configuration is valid, since the "http" and "ftp" list 2963 entries do not have a value for all referenced leafs, and are thus 2964 not taken into account when the "unique" constraint is enforced: 2966 2967 smtp 2968 192.0.2.1 2969 25 2970 2972 2973 http 2974 192.0.2.1 2975 2977 2978 ftp 2979 192.0.2.1 2980 2982 7.8.4. The list's Child Node Statements 2984 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 2985 and "choice" statements can be used to define child nodes to the 2986 list. 2988 7.8.5. XML Encoding Rules 2990 A list is encoded as a series of XML elements, one for each entry in 2991 the list. Each element's name is the list's identifier, and its XML 2992 namespace is the module's XML namespace. 2994 The list's key nodes are encoded as subelements to the list's 2995 identifier element, in the same order as they are defined within the 2996 key statement. 2998 The rest of the list's child nodes are encoded as subelements to the 2999 list element, after the keys. If the list defines RPC input or 3000 output parameters, the subelements are encoded in the same order as 3001 they are defined within the list statement. Otherwise, the 3002 subelements are encoded in any order. 3004 7.8.6. NETCONF operations 3006 List entries can be created, deleted, replaced and modified through 3007 , by using the "operation" attribute in the list's XML 3008 element. In each case, the values of all keys are used to uniquely 3009 identify a list entry. If all keys are not specified for a list 3010 entry, a "missing-element" error is returned. 3012 In an "ordered-by user" list, the attributes "insert" and "key" in 3013 the YANG XML namespace (Section 5.3.1) can be used to control where 3014 in the list the entry is inserted. These can be used during "create" 3015 operations to insert a new list entry, or during "merge" or "replace" 3016 operations to insert a new list entry or move an existing one. 3018 The "insert" attribute can take the values "first", "last", "before", 3019 and "after". If the value is "before" or "after", the "key" 3020 attribute MUST also be used, to specify an existing element in the 3021 list. The value of the "key" attribute is the key predicates of the 3022 full instance identifier (see Section 9.13) for the list entry. 3024 If no "insert" attribute is present in the "create" operation, it 3025 defaults to "last". 3027 In a , or an with a "replace" operation 3028 which covers the entire list, the list entry order is the same as the 3029 order of the XML elements in the request. 3031 7.8.7. Usage Example 3033 Given the following list: 3035 list user { 3036 key "name"; 3037 config true; 3038 description "This is a list of users in the system."; 3040 leaf name { 3041 type string; 3042 } 3043 leaf type { 3044 type string; 3045 } 3046 leaf full-name { 3047 type string; 3048 } 3049 } 3051 A corresponding XML encoding: 3053 3054 fred 3055 admin 3056 Fred Flintstone 3057 3059 To create a new user "barney": 3061 3064 3065 3066 3067 3068 3069 3070 3071 barney 3072 admin 3073 Barney Rubble 3074 3075 3076 3077 3078 3080 To change the type of "fred" to "superuser": 3082 3085 3086 3087 3088 3089 3090 3091 3092 fred 3093 superuser 3094 3095 3096 3097 3098 3100 Given the following ordered-by user list: 3102 list user { 3103 description "This is a list of users in the system."; 3104 ordered-by user; 3105 config true; 3107 key "name"; 3109 leaf name { 3110 type string; 3111 } 3112 leaf type { 3113 type string; 3114 } 3115 leaf full-name { 3116 type string; 3117 } 3118 } 3120 The following would be used to insert a new user "barney" after the 3121 user "fred": 3123 3127 3128 3129 3130 3131 3132 3134 3137 barney 3138 admin 3139 Barney Rubble 3140 3141 3142 3143 3144 3146 The following would be used to move the user "barney" before the user 3147 "fred": 3149 3153 3154 3155 3156 3157 3158 3160 3163 barney 3164 3165 3166 3167 3168 3170 7.9. The choice Statement 3172 The "choice" statement defines a set of alternatives, only one of 3173 which may exist at any one time. The argument is an identifier, 3174 followed by a block of substatements that holds detailed choice 3175 information. The identifier is used to identify the choice node in 3176 the schema tree. A choice node does not exist in the data tree. 3178 A choice consists of a number of branches, defined with the "case" 3179 substatement. Each branch contains a number of child nodes. The 3180 nodes from at most one of the choice's branches exist at the same 3181 time. 3183 See Section 8.3.2 for additional information. 3185 7.9.1. The choice's Substatements 3187 +--------------+---------+-------------+ 3188 | substatement | section | cardinality | 3189 +--------------+---------+-------------+ 3190 | anyxml | 7.10 | 0..n | 3191 | case | 7.9.2 | 0..n | 3192 | config | 7.19.1 | 0..1 | 3193 | container | 7.5 | 0..n | 3194 | default | 7.9.3 | 0..1 | 3195 | description | 7.19.3 | 0..1 | 3196 | if-feature | 7.18.2 | 0..n | 3197 | leaf | 7.6 | 0..n | 3198 | leaf-list | 7.7 | 0..n | 3199 | list | 7.8 | 0..n | 3200 | mandatory | 7.9.4 | 0..1 | 3201 | reference | 7.19.4 | 0..1 | 3202 | status | 7.19.2 | 0..1 | 3203 | when | 7.19.5 | 0..1 | 3204 +--------------+---------+-------------+ 3206 7.9.2. The choice's case Statement 3208 The "case" statement is used to define branches of the choice. It 3209 takes as an argument an identifier, followed by a block of 3210 substatements that holds detailed case information. 3212 The identifier is used to identify the case node in the schema tree. 3213 A case node does not exist in the data tree. 3215 Within a "case" statement, the "anyxml", "container", "leaf", "list", 3216 "leaf-list", and "uses" statements can be used to define child nodes 3217 to the case node. The identifiers of all these child nodes MUST be 3218 unique within all cases in a choice. For example, the following is 3219 illegal: 3221 choice interface-type { // This example is illegal YANG 3222 case a { 3223 leaf ethernet { ... } 3224 } 3225 case b { 3226 container ethernet { ...} 3227 } 3228 } 3230 As a shorthand, the "case" statement can be omitted if the branch 3231 contains a single "anyxml", "container", "leaf", "list", or 3232 "leaf-list" statement. In this case, the identifier of the case node 3233 is the same as the identifier in the branch statement. The following 3234 example: 3236 choice interface-type { 3237 container ethernet { ... } 3238 } 3240 is equivalent to: 3242 choice interface-type { 3243 case ethernet { 3244 container ethernet { ... } 3245 } 3246 } 3248 The case identifier MUST be unique within a choice. 3250 7.9.2.1. The case's Substatements 3252 +--------------+---------+-------------+ 3253 | substatement | section | cardinality | 3254 +--------------+---------+-------------+ 3255 | anyxml | 7.10 | 0..n | 3256 | container | 7.5 | 0..n | 3257 | description | 7.19.3 | 0..1 | 3258 | if-feature | 7.18.2 | 0..n | 3259 | leaf | 7.6 | 0..n | 3260 | leaf-list | 7.7 | 0..n | 3261 | list | 7.8 | 0..n | 3262 | reference | 7.19.4 | 0..1 | 3263 | status | 7.19.2 | 0..1 | 3264 | uses | 7.12 | 0..n | 3265 | when | 7.19.5 | 0..1 | 3266 +--------------+---------+-------------+ 3268 7.9.3. The choice's default Statement 3270 The "default" statement indicates if a case should be considered as 3271 the default if no child nodes from any of the choice's cases exists. 3272 The argument is the identifier of the "case" statement. If the 3273 "default" statement is missing, there is no default case. 3275 The "default" statement MUST NOT be present on choices where 3276 "mandatory" is true. 3278 The default case is only important when considering the default 3279 values of nodes under the cases. The default values for nodes under 3280 the default case are used if none of the nodes under any of the cases 3281 are present. 3283 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3284 the default case. 3286 Default values for child nodes under a case are only used if one of 3287 the nodes under that case is present, or if that case is the default 3288 case. If none of the nodes under a case are present and the case is 3289 not the default case, the default values of the cases' child nodes 3290 are ignored. 3292 In this example, the choice defaults to "interval", and the default 3293 value will be used if none of "daily", "time-of-day", or "manual" are 3294 present. If "daily" is present, the default value for "time-of-day" 3295 will be used. 3297 container transfer { 3298 choice how { 3299 default interval; 3300 case interval { 3301 leaf interval { 3302 type uint16; 3303 default 30; 3304 units minutes; 3305 } 3306 } 3307 case daily { 3308 leaf daily { 3309 type empty; 3310 } 3311 leaf time-of-day { 3312 type string; 3313 units 24-hour-clock; 3314 default 1am; 3315 } 3316 } 3317 case manual { 3318 leaf manual { 3319 type empty; 3320 } 3321 } 3322 } 3323 } 3325 7.9.4. The choice's mandatory Statement 3327 The "mandatory" statement, which is optional, takes as an argument 3328 the string "true" or "false", and puts a constraint on valid data. 3329 If "mandatory" is "true", at least one node from exactly one of the 3330 choice's case branches MUST exist. 3332 If not specified, the default is "false". 3334 The behavior of the constraint depends on the type of the choice's 3335 closest ancestor node in the schema tree which is not a non-presence 3336 container (see Section 7.5.1): 3338 o If this ancestor is a case node, the constraint is enforced if any 3339 other node from the case exists. 3341 o Otherwise, it is enforced if the ancestor node exists. 3343 The constraint is further enforced according to the rules in 3344 Section 8. 3346 7.9.5. XML Encoding Rules 3348 The choice and case nodes are not visible in XML. 3350 7.9.6. NETCONF operations 3352 Since only one of the choices cases can be valid at any time, the 3353 creation of a node from one case implicitly deletes all nodes from 3354 all other cases. If an operation creates a node, the 3355 NETCONF server will delete any existing nodes that are defined in 3356 other cases inside the choice. 3358 7.9.7. Usage Example 3360 Given the following choice: 3362 container protocol { 3363 choice name { 3364 case a { 3365 leaf udp { 3366 type empty; 3367 } 3368 } 3369 case b { 3370 leaf tcp { 3371 type empty; 3372 } 3373 } 3374 } 3375 } 3377 A corresponding XML encoding: 3379 3380 3381 3383 To change the protocol from tcp to udp: 3385 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3402 7.10. The anyxml Statement 3404 The "anyxml" statement defines an interior node in the schema tree. 3405 It takes one argument, which is an identifier, followed by a block of 3406 substatements that holds detailed anyxml information. 3408 The anyxml statement is used to represent an unknown chunk of XML. 3409 No restrictions are placed on the XML. This can be useful in e.g. 3410 RPC replies. An example is the parameter in the 3411 operation. 3413 An anyxml node cannot be augmented. 3415 Since the use of anyxml limits the manipulation of the content, it is 3416 RECOMMENDED that the anyxml statement not be used to represent 3417 configuration data. 3419 7.10.1. The anyxml's Substatements 3421 +--------------+---------+-------------+ 3422 | substatement | section | cardinality | 3423 +--------------+---------+-------------+ 3424 | config | 7.19.1 | 0..1 | 3425 | description | 7.19.3 | 0..1 | 3426 | if-feature | 7.18.2 | 0..n | 3427 | mandatory | 7.6.4 | 0..1 | 3428 | must | 7.5.3 | 0..n | 3429 | reference | 7.19.4 | 0..1 | 3430 | status | 7.19.2 | 0..1 | 3431 | when | 7.19.5 | 0..1 | 3432 +--------------+---------+-------------+ 3434 7.10.2. XML Encoding Rules 3436 An anyxml node is encoded as an XML element. The element's name is 3437 the anyxml's identifier, and its XML namespace is the module's XML 3438 namespace. The value of the anyxml node is encoded as XML content of 3439 this element. 3441 Note that any prefixes used in the encoding are local to each 3442 instance encoding. This means that the same XML may be encoded 3443 differently by different implementations. 3445 7.10.3. NETCONF operations 3447 An anyxml node is treated as an opaque chunk of data. This data can 3448 be modified in its entirety only. 3450 Any "operation" attributes within the XML value of an anyxml node are 3451 ignored by the NETCONF server. 3453 When a NETCONF server processes an request, the 3454 elements of procedure for the anyxml node are: 3456 If the operation is "merge", the node is created if it does not 3457 exist, and its value is set to the XML content of the anyxml node 3458 found in the XML RPC data. 3460 If the operation is "replace", the node is created if it does not 3461 exist, and its value is set to the XML content of the anyxml node 3462 found in the XML RPC data. 3464 If the operation is "create" the node is created if it does not 3465 exist, and its value is set to the XML content of the anyxml node 3466 found in the XML RPC data. 3468 If the operation is "delete" the node is deleted if it exists. 3470 7.10.4. Usage Example 3472 Given the following anyxml statement: 3474 anyxml data; 3476 The following are two valid encodings of the same anyxml value: 3478 3479 3480 1 3481 3482 3484 3485 3486 1 3487 3488 3490 7.11. The grouping Statement 3492 The "grouping" statement is used to define a reusable block of nodes, 3493 which may be used locally in the module, in modules which include it, 3494 and by other modules which import from it, according to the rules in 3495 Section 5.5. It takes one argument which is an identifier, followed 3496 by a block of substatements that holds detailed grouping information. 3498 The grouping statement is not a data definition statement and, as 3499 such, does not define any nodes in the schema tree. 3501 A grouping is like a "structure" or a "record" in conventional 3502 programming languages. 3504 Once a grouping is defined, it can be referenced in a "uses" 3505 statement (see Section 7.12). A grouping MUST NOT reference itself, 3506 neither directly nor indirectly through a chain of other groupings. 3508 If the grouping is defined at the top level of a YANG module or 3509 submodule, the grouping's identifier MUST be unique within the 3510 module. 3512 A grouping is more than just a mechanism for textual substitution, 3513 but defines a collection of nodes. References from inside the 3514 grouping are relative to the scope in which the grouping is defined, 3515 not where it is used. Prefix mappings, type names, grouping names, 3516 and extension usage are evaluated in the hierarchy where the grouping 3517 statement appears. For extensions, this means that extensions are 3518 applied to the grouping node, not the use node. 3520 7.11.1. The grouping's Substatements 3522 +--------------+---------+-------------+ 3523 | substatement | section | cardinality | 3524 +--------------+---------+-------------+ 3525 | anyxml | 7.10 | 0..n | 3526 | choice | 7.9 | 0..n | 3527 | container | 7.5 | 0..n | 3528 | description | 7.19.3 | 0..1 | 3529 | grouping | 7.11 | 0..n | 3530 | leaf | 7.6 | 0..n | 3531 | leaf-list | 7.7 | 0..n | 3532 | list | 7.8 | 0..n | 3533 | reference | 7.19.4 | 0..1 | 3534 | status | 7.19.2 | 0..1 | 3535 | typedef | 7.3 | 0..n | 3536 | uses | 7.12 | 0..n | 3537 +--------------+---------+-------------+ 3539 7.11.2. Usage Example 3541 import ietf-inet-types { 3542 prefix "inet"; 3543 } 3545 grouping address { 3546 description "A reusable address group."; 3547 leaf ip { 3548 type inet:ip-address; 3549 } 3550 leaf port { 3551 type inet:port-number; 3552 } 3553 } 3555 7.12. The uses Statement 3557 The "uses" statement is used to reference a "grouping" definition. 3558 It takes one argument, which is the name of the grouping. 3560 The effect of a "uses" reference to a grouping is that the nodes 3561 defined by the grouping are copied into the current schema tree, and 3562 then updated according to the refinement statements. Thus, the 3563 identifiers defined in the grouping are copied into the current 3564 module's namespace, even if the grouping is imported from some other 3565 module. 3567 7.12.1. The uses's Substatements 3569 +--------------+---------+-------------+ 3570 | substatement | section | cardinality | 3571 +--------------+---------+-------------+ 3572 | augment | 7.15 | 0..1 | 3573 | description | 7.19.3 | 0..1 | 3574 | if-feature | 7.18.2 | 0..n | 3575 | refine | 7.12.2 | 0..1 | 3576 | reference | 7.19.4 | 0..1 | 3577 | status | 7.19.2 | 0..1 | 3578 | when | 7.19.5 | 0..1 | 3579 +--------------+---------+-------------+ 3581 7.12.2. The refine Statement 3583 Some of the properties of each node in the grouping can be refined 3584 with the "refine" statement. The argument is a a string which 3585 identifies a node in the grouping. This node is called the refine's 3586 target node. If a node in the grouping is not present as target node 3587 of a refine statement, it is not refined, and thus used exactly as it 3588 was defined in the grouping. 3590 The argument string is a schema node identifier. The syntax is 3591 formally defined by the rule "descendant-schema-nodeid" in 3592 Section 12. 3594 The following refinements can be done: 3596 o A leaf or choice node may get a default value, or a new default 3597 value if it already had one. 3599 o Any node may get a specialized "description" string. 3601 o Any node may get a specialized "reference" string. 3603 o Any node may get a different "config" statement. 3605 o A leaf or choice node may get a different "mandatory" statement. 3607 o A container node may get a "presence" statement. 3609 o A leaf, leaf-list, list or container node may get additional 3610 "must" expressions. 3612 o A leaf-list or list node may get a different "min-elements" or 3613 "max-elements" statement. 3615 7.12.3. XML Encoding Rules 3617 Each node in the grouping is encoded as if it was defined inline, 3618 even if it is imported from another module with another XML 3619 namespace. 3621 7.12.4. Usage Example 3623 To use the "address" grouping defined in Section 7.11.2 in a 3624 definition of an HTTP server in some other module, we can do: 3626 import acme-system { 3627 prefix "acme"; 3628 } 3630 container http-server { 3631 leaf name { 3632 type string; 3633 } 3634 uses acme:address; 3635 } 3637 A corresponding XML encoding: 3639 3640 extern-web 3641 192.0.2.1 3642 80 3643 3645 If port 80 should be the default for the HTTP server, default can be 3646 added: 3648 container http-server { 3649 leaf name { 3650 type string; 3651 } 3652 uses acme:address { 3653 refine port { 3654 default 80; 3655 } 3656 } 3657 } 3659 If we want to define a list of servers, and each server has the ip 3660 and port as keys, we can do: 3662 list server { 3663 key "ip port"; 3664 leaf name { 3665 type string; 3666 } 3667 uses acme:address; 3668 } 3670 The following is an error: 3672 container http-server { 3673 uses acme:address; 3674 leaf ip { // illegal - same identifier "ip" used twice 3675 type string; 3676 } 3677 } 3679 7.13. The rpc Statement 3681 The "rpc" statement is used to define a NETCONF RPC method. It takes 3682 one argument, which is an identifier, followed by a block of 3683 substatements that holds detailed rpc information. This argument is 3684 the name of the RPC, and is used as the element name directly under 3685 the element, as designated by the substitution group 3686 "rpcOperation" in [RFC4741]. 3688 The "rpc" statement defines an rpc node in the schema tree. Under 3689 the rpc node, an input node with the name "input", and an output node 3690 with the name "output" are also defined. The nodes "input" and 3691 "output" are defined in the module's namespace. 3693 7.13.1. The rpc's Substatements 3695 +--------------+---------+-------------+ 3696 | substatement | section | cardinality | 3697 +--------------+---------+-------------+ 3698 | description | 7.19.3 | 0..1 | 3699 | grouping | 7.11 | 0..n | 3700 | if-feature | 7.18.2 | 0..n | 3701 | input | 7.13.2 | 0..1 | 3702 | output | 7.13.3 | 0..1 | 3703 | reference | 7.19.4 | 0..1 | 3704 | status | 7.19.2 | 0..1 | 3705 | typedef | 7.3 | 0..n | 3706 +--------------+---------+-------------+ 3708 7.13.2. The input Statement 3710 The "input" statement, which is optional, is used to define input 3711 parameters to the RPC method. It does not take an argument. The 3712 substatements to "input" defines nodes under the RPC's input node. 3714 If a leaf in the input tree has a "mandatory" statement with the 3715 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3717 If a leaf in the input tree has a default value, the NETCONF server 3718 MUST internally use this default if the leaf is not present in a 3719 NETCONF RPC invocation. 3721 If a "config" statement is present for any node in the input tree, it 3722 is ignored. 3724 If any node has a "when" statement which would evaluate to false, 3725 then this node MUST NOT be present in the input tree. 3727 7.13.2.1. The input's Substatements 3729 +--------------+---------+-------------+ 3730 | substatement | section | cardinality | 3731 +--------------+---------+-------------+ 3732 | anyxml | 7.10 | 0..n | 3733 | choice | 7.9 | 0..n | 3734 | container | 7.5 | 0..n | 3735 | grouping | 7.11 | 0..n | 3736 | leaf | 7.6 | 0..n | 3737 | leaf-list | 7.7 | 0..n | 3738 | list | 7.8 | 0..n | 3739 | typedef | 7.3 | 0..n | 3740 | uses | 7.12 | 0..n | 3741 +--------------+---------+-------------+ 3743 7.13.3. The output Statement 3745 The "output" statement, which is optional, is used to define output 3746 parameters to the RPC method. It does not take an argument. The 3747 substatements to "output" defines nodes under the RPC's output node. 3749 If a leaf in the output tree has a "mandatory" statement with the 3750 value "true", the leaf MUST be present in a NETCONF RPC reply. 3752 If a leaf in the output tree has a default value, the NETCONF client 3753 MUST internally use this default if the leaf is not present in a 3754 NETCONF RPC reply. 3756 If a "config" statement is present for any node in the output tree, 3757 it is ignored. 3759 If any node has a "when" statement which would evaluate to false, 3760 then this node MUST NOT be present in the output tree. 3762 7.13.3.1. The output's Substatements 3764 +--------------+---------+-------------+ 3765 | substatement | section | cardinality | 3766 +--------------+---------+-------------+ 3767 | anyxml | 7.10 | 0..n | 3768 | choice | 7.9 | 0..n | 3769 | container | 7.5 | 0..n | 3770 | grouping | 7.11 | 0..n | 3771 | leaf | 7.6 | 0..n | 3772 | leaf-list | 7.7 | 0..n | 3773 | list | 7.8 | 0..n | 3774 | typedef | 7.3 | 0..n | 3775 | uses | 7.12 | 0..n | 3776 +--------------+---------+-------------+ 3778 7.13.4. XML Encoding Rules 3780 An rpc node is encoded as a child XML element to the element 3781 defined in [RFC4741]. The element's name is the rpc's identifier, 3782 and its XML namespace is the module's XML namespace. 3784 Input parameters are encoded as child XML elements to the rpc node's 3785 XML element, in the same order as they are defined within the input 3786 statement. 3788 If the RPC method invocation succeeded, and no output parameters are 3789 returned, the contains a single element defined in 3790 [RFC4741]. If output parameters are returned, they are encoded as 3791 child elements to the element defined in [RFC4741], in 3792 the same order as they are defined within the output statement. 3794 7.13.5. Usage Example 3796 The following example defines an RPC method: 3798 module rock { 3799 namespace "http://example.net/rock"; 3800 prefix "rock"; 3802 rpc rock-the-house { 3803 input { 3804 leaf zip-code { 3805 type string; 3806 } 3807 } 3808 } 3809 } 3811 A corresponding XML encoding of the complete rpc and rpc-reply: 3813 3815 3816 27606-0100 3817 3818 3820 3822 3823 3825 7.14. The notification Statement 3827 The "notification" statement is used to define a NETCONF 3828 notification. It takes one argument, which is an identifier, 3829 followed by a block of substatements that holds detailed notification 3830 information. The notification "statement" defines a notification 3831 node in the schema tree. 3833 If a container in the notification tree has a "presence" statement, 3834 the container need not be present in a NETCONF notification. 3836 If a leaf in the notification tree has a "mandatory" statement with 3837 the value "true", the leaf MUST be present in a NETCONF notification. 3839 If a leaf in the notification tree has a default value, the NETCONF 3840 server MUST internally use this default if the leaf is not present in 3841 a NETCONF notification. 3843 If a "config" statement is present for any node in the notification 3844 tree, it is ignored. 3846 7.14.1. The notification's Substatements 3848 +--------------+---------+-------------+ 3849 | substatement | section | cardinality | 3850 +--------------+---------+-------------+ 3851 | anyxml | 7.10 | 0..n | 3852 | choice | 7.9 | 0..n | 3853 | container | 7.5 | 0..n | 3854 | description | 7.19.3 | 0..1 | 3855 | grouping | 7.11 | 0..n | 3856 | if-feature | 7.18.2 | 0..n | 3857 | leaf | 7.6 | 0..n | 3858 | leaf-list | 7.7 | 0..n | 3859 | list | 7.8 | 0..n | 3860 | reference | 7.19.4 | 0..1 | 3861 | status | 7.19.2 | 0..1 | 3862 | typedef | 7.3 | 0..n | 3863 | uses | 7.12 | 0..n | 3864 +--------------+---------+-------------+ 3866 7.14.2. XML Encoding Rules 3868 A notification node is encoded as a child XML element to the 3869 element defined in NETCONF Event Notifications 3870 [RFC5277]. The element's name is the notification's identifier, and 3871 its XML namespace is the module's XML namespace. 3873 The notifications's child nodes are encoded as subelements to the 3874 notification node's XML element, in the same order as they are 3875 defined within the notification statement. 3877 7.14.3. Usage Example 3879 The following example defines a notification: 3881 module event { 3883 namespace "http://example.com/event"; 3884 prefix "ev"; 3886 notification event { 3887 leaf event-class { 3888 type string; 3889 } 3890 anyxml reporting-entity; 3891 leaf severity { 3892 type string; 3893 } 3894 } 3895 } 3897 A corresponding XML encoding of the complete notification: 3899 3901 2008-07-08T00:01:00Z 3902 3903 fault 3904 3905 Ethernet0 3906 3907 major 3908 3909 3911 7.15. The augment Statement 3913 The "augment" statement allows a module or submodule to add to the 3914 schema tree defined in an external module, or the current module and 3915 its submodules, and to add to the nodes from a grouping in a "uses" 3916 statement. The argument is a string which identifies a node in the 3917 schema tree. This node is called the augment's target node. The 3918 target node MUST be either a container, list, choice, case, input, 3919 output, or notification node. It is augmented with the nodes defined 3920 in the substatements that follow the "augment" statement. 3922 The argument string is a schema node identifier. The syntax is 3923 formally defined by the rule "augment-arg" in Section 12. If the 3924 "augment" statement is on the top-level in a module or submodule, the 3925 absolute form (defined by the rule "absolute-schema-nodeid" in 3926 Section 12) of a schema node identifier MUST be used. If the 3927 "augment" statement is in a "uses" statement, the descendant form 3928 (defined by the rule "descendant-schema-nodeid" in Section 12) MUST 3929 be used. 3931 The syntax for a schema node identifier is a subset of the XPath 3932 syntax. It is an absolute or relative XPath location path in 3933 abbreviated syntax, where axes and predicates are not permitted. 3935 If the target node is a container, list, case, input, output, or 3936 notification node, the "container", "leaf", "list", "leaf-list", 3937 "uses", and "choice" statements can be used within the "augment" 3938 statement. 3940 If the target node is a choice node, the "case" statement can be used 3941 within the "augment" statement. 3943 If the target node is in another module, then nodes added by the 3944 augmentation MUST NOT be mandatory nodes (see Section 3.1). 3946 The augment statement MUST NOT add multiple nodes with the same name 3947 from the same module to the target node. 3949 7.15.1. The augment's Substatements 3951 +--------------+---------+-------------+ 3952 | substatement | section | cardinality | 3953 +--------------+---------+-------------+ 3954 | anyxml | 7.10 | 0..n | 3955 | case | 7.9.2 | 0..n | 3956 | choice | 7.9 | 0..n | 3957 | container | 7.5 | 0..n | 3958 | description | 7.19.3 | 0..1 | 3959 | if-feature | 7.18.2 | 0..n | 3960 | leaf | 7.6 | 0..n | 3961 | leaf-list | 7.7 | 0..n | 3962 | list | 7.8 | 0..n | 3963 | reference | 7.19.4 | 0..1 | 3964 | status | 7.19.2 | 0..1 | 3965 | uses | 7.12 | 0..n | 3966 | when | 7.19.5 | 0..1 | 3967 +--------------+---------+-------------+ 3969 7.15.2. XML Encoding Rules 3971 All data nodes defined in the "augment" statement are defined as XML 3972 elements in the XML namespace of the module where the "augment" is 3973 specified. 3975 When a node is augmented, the augmenting child nodes are encoded as 3976 subelements to the augmented node, in any order. 3978 7.15.3. Usage Example 3980 In namespace http://example.com/schema/interfaces, we have: 3982 container interfaces { 3983 list ifEntry { 3984 key "ifIndex"; 3986 leaf ifIndex { 3987 type uint32; 3988 } 3989 leaf ifDescr { 3990 type string; 3991 } 3992 leaf ifType { 3993 type iana:IfType; 3994 } 3995 leaf ifMtu { 3996 type int32; 3997 } 3998 } 3999 } 4001 Then in namespace http://example.com/schema/ds0, we have: 4003 import interface-module { 4004 prefix "if"; 4005 } 4006 augment "/if:interfaces/if:ifEntry" { 4007 when "if:ifType='ds0'"; 4008 leaf ds0ChannelNumber { 4009 type ChannelNumber; 4010 } 4011 } 4013 A corresponding XML encoding: 4015 4018 1 4019 Flintstone Inc Ethernet A562 4020 ethernetCsmacd 4021 1500 4022 4023 4024 2 4025 Flintstone Inc DS0 4026 ds0 4027 1 4028 4029 4031 As another example, suppose we have the choice defined in 4032 Section 7.9.7. The following construct can be used to extend the 4033 protocol definition: 4035 augment /ex:system/ex:protocol/ex:name { 4036 case c { 4037 leaf smtp { 4038 type empty; 4039 } 4040 } 4041 } 4043 A corresponding XML encoding: 4045 4046 4047 4048 4049 4051 or 4053 4054 4055 4056 4057 4059 7.16. The identity Statement 4061 The "identity" statement is used to define a new globally unique, 4062 abstract and untyped identity. Its only purpose is to denote its 4063 name, semantics, and existence. An identity can be defined either 4064 from scratch or derived from a base identity. The identity's 4065 argument is an identifier that is the name of the identity. It is 4066 followed by a block of substatements that holds detailed identity 4067 information. 4069 The built-in datatype "identityref" (see Section 9.10) can be used to 4070 reference identities within a data model. 4072 7.16.1. The identity's Substatements 4074 +--------------+---------+-------------+ 4075 | substatement | section | cardinality | 4076 +--------------+---------+-------------+ 4077 | base | 7.16.2 | 0..1 | 4078 | description | 7.19.3 | 0..1 | 4079 | reference | 7.19.4 | 0..1 | 4080 | status | 7.19.2 | 0..1 | 4081 +--------------+---------+-------------+ 4083 7.16.2. The base Statement 4085 The base statement, which is optional, takes as an argument a string 4086 which is the name of an existing identity, from which the new 4087 identity is derived. If no base statement is present, the identity 4088 is defined from scratch. 4090 If a prefix is present on the base name, it refers to an identity 4091 defined in the module which was imported with that prefix, or the 4092 local module if the prefix matches the local module's prefix. 4093 Otherwise an identity with the matching name MUST be defined in the 4094 current module or an included submodule. 4096 Since submodules cannot include the parent module, any identities in 4097 the module which need to be exposed to submodules MUST be defined in 4098 a submodule. Submodules can then include this submodule to find the 4099 definition of the identity. 4101 An identity MUST NOT reference itself, neither directly nor 4102 indirectly through a chain of other identities. 4104 7.16.3. Usage Example 4106 module crypto-base { 4107 namespace "http://example.com/crypto-base"; 4108 prefix "crypto"; 4110 identity crypto-alg { 4111 description 4112 "Base identity from which all crypto algorithms 4113 are derived."; 4114 } 4115 } 4117 module des { 4118 namespace "http://example.com/des"; 4119 prefix "des"; 4121 import "crypto-base" { 4122 prefix "crypto"; 4123 } 4125 identity des { 4126 base "crypto:crypto-alg"; 4127 description "DES crypto algorithm"; 4128 } 4130 identity des3 { 4131 base "crypto:crypto-alg"; 4132 description "Triple DES crypto algorithm"; 4133 } 4134 } 4136 7.17. The extension Statement 4138 The "extension" statement allows the definition of new statements 4139 within the YANG language. This new statement definition can be 4140 imported and used by other modules. 4142 The statement's argument is an identifier that is the new keyword for 4143 the extension and must be followed by a block of substatements that 4144 holds detailed extension information. The purpose of the extension 4145 statement is to define a keyword, so that it can be imported and used 4146 by other modules. 4148 The extension can be used like a normal YANG statement, with the 4149 statement name followed by an argument if one is defined by the 4150 extension, and an optional block of substatements. The statement's 4151 name is created by combining the the prefix of the module in which 4152 the extension was defined, a colon (":"), and the extension's 4153 keyword, with no interleaving whitespace. The substatements of an 4154 extension are defined by the extension, using some mechanism outside 4155 the scope of this specification. Syntactically, the substatements 4156 MUST be core YANG statements, or also defined using "extension" 4157 statements. Core YANG statements in extensions MUST follow the 4158 syntactical rules in Section 12. 4160 7.17.1. The extension's Substatements 4162 +--------------+---------+-------------+ 4163 | substatement | section | cardinality | 4164 +--------------+---------+-------------+ 4165 | argument | 7.17.2 | 0..1 | 4166 | description | 7.19.3 | 0..1 | 4167 | reference | 7.19.4 | 0..1 | 4168 | status | 7.19.2 | 0..1 | 4169 +--------------+---------+-------------+ 4171 7.17.2. The argument Statement 4173 The "argument" statement, which is optional, takes as an argument a 4174 string which is the name of the argument to the keyword. If no 4175 argument statement is present, the keyword expects no argument when 4176 it is used. 4178 The argument's name is used in the YIN mapping, where it is used as 4179 an XML attribute or element name, depending on the argument's text 4180 statement. 4182 7.17.2.1. The argument's Substatements 4184 +--------------+----------+-------------+ 4185 | substatement | section | cardinality | 4186 +--------------+----------+-------------+ 4187 | yin-element | 7.17.2.2 | 0..1 | 4188 +--------------+----------+-------------+ 4190 7.17.2.2. The yin-element Statement 4192 The "yin-element" statement, which is optional, takes as an argument 4193 the string "true" or "false". This statement indicates if the 4194 argument is mapped to an XML element in YIN or to an XML attribute. 4195 (see Section 11). 4197 If no "yin-element" statement is present, it defaults to "false". 4199 7.17.3. Usage Example 4201 To define an extension: 4203 module my-extensions { 4204 ... 4206 extension c-define { 4207 description 4208 "Takes as argument a name string. 4209 Makes the code generator use the given name in the 4210 #define."; 4211 argument "name"; 4212 } 4213 } 4215 To use the extension: 4217 module my-interfaces { 4218 ... 4219 import my-extensions { 4220 prefix "myext"; 4221 } 4222 ... 4224 container interfaces { 4225 ... 4226 myext:c-define "MY_INTERFACES"; 4227 } 4228 } 4230 7.18. Conformance-related Statements 4232 This section defines statements related to conformance, as described 4233 in Section 5.6. 4235 7.18.1. The feature Statement 4237 The "feature" statement is used to define a mechanism by which 4238 portions of the schema are marked as conditional. A feature name is 4239 defined that can later be referenced using the "if-feature" statement 4240 (see Section 7.18.2). Schema nodes tagged with a feature are ignored 4241 unless the device supports the given feature. This allows portions 4242 of the YANG module to be conditional based on conditions on the 4243 device. The model can represent the abilities of the device within 4244 the model, giving a richer model that allows for differing device 4245 abilities and roles. 4247 The argument to the "feature" statement is the name of the new 4248 feature, and follows the rules for identifiers in Section 6.2. This 4249 name is used by the "if-feature" statement to tie the schema nodes to 4250 the feature. 4252 In this example, a feature called "local-storage" represents the 4253 ability for a device to store syslog messages on local storage of 4254 some sort. This feature is used to make the "local-storage-limit" 4255 leaf conditional on the presence of some sort of local storage. If 4256 the device does not report that it supports this feature, the 4257 "local-storage-limit" node is not supported. 4259 module syslog { 4260 ... 4261 feature local-storage { 4262 description 4263 "This feature means the device supports local 4264 storage (memory, flash or disk) that can be used to 4265 store syslog messages."; 4266 } 4268 container syslog { 4269 leaf local-storage-limit { 4270 if-feature local-storage; 4271 type uint64; 4272 units "kilobyte"; 4273 config false; 4274 description 4275 "The amount of local storage that can be 4276 used to hold syslog messages."; 4277 } 4278 } 4279 } 4281 The "if-feature" statement can be used in many places within the YANG 4282 syntax. Definitions tagged with "if-feature" are ignored when the 4283 device does not support that feature. 4285 A feature MUST NOT reference itself, neither directly nor indirectly 4286 through a chain of other features. 4288 7.18.1.1. The feature's Substatements 4290 +--------------+---------+-------------+ 4291 | substatement | section | cardinality | 4292 +--------------+---------+-------------+ 4293 | description | 7.19.3 | 0..1 | 4294 | if-feature | 7.18.2 | 0..n | 4295 | status | 7.19.2 | 0..1 | 4296 | reference | 7.19.4 | 0..1 | 4297 +--------------+---------+-------------+ 4299 7.18.2. The if-feature Statement 4301 The "if-feature" statement makes its parent statement conditional. 4302 The argument is the name of a feature, as defined by a "feature" 4303 statement. The parent statement is implemented by servers that 4304 support this feature. If a prefix is present on the feature name, it 4305 refers to a feature defined in the module which was imported with 4306 that prefix, or the local module if the prefix matches the local 4307 module's prefix. Otherwise a feature with the matching name MUST be 4308 defined in the current module or an included submodule. 4310 Since submodules cannot include the parent module, any features in 4311 the module which need to be exposed to submodules MUST be defined in 4312 a submodule. Submodules can then include this submodule to find the 4313 definition of the feature. 4315 7.18.3. The deviation Statement 4317 The deviation statement defines a hierarchy of the module which the 4318 device does not implement faithfully. The argument is a string that 4319 identifies the node in the schema tree where a deviation from the 4320 module occurs. This node is called the deviation's target node. The 4321 contents of the deviation statement give details about the deviation. 4323 The argument's syntax is formally defined by the rule "deviation-arg" 4324 in Section 12. 4326 Deviations define the way a device or class of devices deviate from 4327 the standard. This means that deviations MUST never be part of a 4328 published standard, since they are the mechanism for learning how 4329 implementations vary from the standards. 4331 Device deviations are strongly discouraged and SHOULD only be used as 4332 a last resort. Telling the application how a device fails to follow 4333 the standard is no substitute for implementing the standard 4334 correctly. 4336 However in some cases a particular device may not have the hardware 4337 or software ability to support parts of a standard module. When this 4338 occurs, the device makes a choice to treat attempts to configure 4339 unsupported parts of the module as either an error that is reported 4340 back to the unsuspecting application, or ignore that incoming 4341 requests. Neither choice is acceptable. 4343 Instead, YANG allows devices to document portions of the base module 4344 which are not supported or supported but with different syntax, by 4345 using the "deviation" statement. 4347 7.18.3.1. The deviation's Substatements 4349 +--------------+----------+-------------+ 4350 | substatement | section | cardinality | 4351 +--------------+----------+-------------+ 4352 | description | 7.19.3 | 0..1 | 4353 | deviate | 7.18.3.2 | 0..n | 4354 | reference | 7.19.4 | 0..1 | 4355 +--------------+----------+-------------+ 4357 7.18.3.2. The deviate Statement 4359 The "deviate" statement defines how the device's implementation of 4360 the target node deviates from its original definition. The argument 4361 is one of the strings "not-supported", "add", "replace", or "delete". 4363 The argument "not-supported" indicates that the target node is not 4364 implemented by this device. 4366 The argument "add" adds properties to the target node. The 4367 properties to add are identified as a substatement to the "deviate" 4368 statement. If the property can only appear once, the property MUST 4369 NOT exist in the target node. 4371 The argument "replace" replaces properties of the target node. The 4372 properties to replace are identified by substatements to the 4373 "deviate" statement. The property to replace MUST exist in the 4374 target node. 4376 The argument "delete" deletes properties from the target node. The 4377 properties to delete are identified by substatement to "delete". The 4378 substatement's keyword MUST match a corresponding keyword in the 4379 target node, and the argument's string MUST be equal to the 4380 corresponding keyword's argument string in the target node. 4382 The deviates's Substatements 4384 +--------------+---------+-------------+ 4385 | substatement | section | cardinality | 4386 +--------------+---------+-------------+ 4387 | config | 7.19.1 | 0..1 | 4388 | default | 7.6.3 | 0..1 | 4389 | mandatory | 7.6.4 | 0..1 | 4390 | max-elements | 7.7.4 | 0..1 | 4391 | min-elements | 7.7.3 | 0..1 | 4392 | must | 7.5.3 | 0..n | 4393 | type | 7.4 | 0..1 | 4394 | unique | 7.8.3 | 0..n | 4395 | units | 7.3.3 | 0..1 | 4396 +--------------+---------+-------------+ 4398 7.18.3.3. Usage Example 4400 In this example, the device is informing client applications that it 4401 does not support the old RFC867-style "daytime" service. 4403 deviation /base:system/base:daytime { 4404 deviate not-supported; 4405 } 4407 The following example sets a device-specific default value to a leaf 4408 that does not have a default value defined: 4410 deviation /base:system/base:user/base:type { 4411 deviate add { 4412 default "admin"; // new users are 'admin' by default 4413 } 4414 } 4416 In this example, the device limits the number of name servers to 3: 4418 deviation /base:system/base:name-server { 4419 deviate replace { 4420 max-elements 3; 4421 } 4422 } 4424 If the original definition is: 4426 container system { 4427 must "daytime or time"; 4428 ... 4429 } 4431 a device might remove this must constraint by doing: 4433 deviation "/base:system" { 4434 deviate delete { 4435 must "daytime or time"; 4436 } 4437 } 4439 7.19. Common Statements 4441 This section defines sub-statements common to several other 4442 statements. 4444 7.19.1. The config Statement 4446 The "config" statement takes as an argument the string "true" or 4447 "false". If "config" is "true", the definition represents 4448 configuration. Data nodes representing configuration will be part of 4449 the reply to a request, and can be sent in a 4450 or request. 4452 If "config" is "false", the definition represents state data. Data 4453 nodes representing state data will be part of the reply to a , 4454 but not to a request. 4456 If "config" is not specified, the default is the same as the parent 4457 schema node's "config" value. If the parent node is a "case" node, 4458 the value is the same as the "case" node's parent "choice" node. 4460 If the top node does not specify a "config" statement, the default is 4461 "true". 4463 If a node has "config" "false", no node underneath it can have 4464 "config" set to "true". 4466 7.19.2. The status Statement 4468 The "status" statement takes as an argument one of the strings 4469 "current", "deprecated", or "obsolete". 4471 o "current" means that the definition is current and valid. 4473 o "deprecated" indicates an obsolete definition, but it permits new/ 4474 continued implementation in order to foster interoperability with 4475 older/existing implementations. 4477 o "obsolete" means the definition is obsolete and SHOULD NOT be 4478 implemented and/or can be removed if previously implemented. 4480 If no status is specified, the default is "current". 4482 If a definition is "current", it MUST NOT reference a "deprecated" or 4483 "obsolete" definition within the same module. 4485 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4486 definition within the same module. 4488 7.19.3. The description Statement 4490 The "description" statement takes as an argument a string which 4491 contains a high-level textual description of this definition. 4493 7.19.4. The reference Statement 4495 The "reference" statement takes as an argument a string which is used 4496 to specify a textual cross-reference to an external document, either 4497 another module which defines related management information, or a 4498 document which provides additional information relevant to this 4499 definition. 4501 7.19.5. The when Statement 4503 The "when" statement makes its parent data definition statement 4504 conditional. The node defined by the parent data definition 4505 statement is only valid when the condition specified by the "when" 4506 statement is satisfied. The statement's argument is an XPath 4507 expression, which is used to formally specify this condition. If the 4508 XPath expression conceptually evaluates to "true" for a particular 4509 instance, then the node defined by the parent data definition 4510 statement is valid, otherwise it is not. 4512 See Section 8.3.2 for additional information. 4514 The XPath expression is conceptually evaluated in the following 4515 context: 4517 o If the "when" statement is a child of an "augment" statement, then 4518 the context node is the augment's target node in the data tree, if 4519 the target node is a data node. Otherwise, the context node is 4520 the closest ancestor node to the target node which is also a data 4521 node. 4523 o If the "when" statement is a child of a "choice" or "case" 4524 statement, then the context node is the closest ancestor node to 4525 the "choice" or "case" node which is also a data node. 4527 o If the "when" statement is a child of any other data definition 4528 statement, the context node is the data definition's node in the 4529 data tree. 4531 o The accessible tree is made up of all nodes in the data tree, and 4532 all leafs with default values. 4534 o The set of namespace declarations is the set of all "import" 4535 statements' prefix and namespace pairs, and the "prefix" 4536 statement's prefix for the "namespace" statement's URI. 4538 o Elements without a namespace refer to nodes in the current module. 4540 o The function library is the core function library defined in 4541 [XPATH], and a function "current()" which returns a node set with 4542 the initial context node. 4544 The accessible data tree depends on the context node: 4546 o If the context node represents configuration, the tree is the data 4547 in one of the datastores , , or . 4548 The XPath root node has all top-level configuration data nodes in 4549 all modules as children. 4551 o If the context node represents state data, the tree is all state 4552 data on the device, and the datastore. The XPath root 4553 node has all top-level data nodes in all modules as children. 4555 o If the context node represents notification content, the tree is 4556 the notification XML instance document. The XPath root node has 4557 the element representing the notification being defined as the 4558 only child. 4560 o If the context node represents RPC input parameters, the tree is 4561 the RPC XML instance document. The XPath root node has the 4562 element representing the RPC method being defined as the only 4563 child. 4565 o If the context node represents RPC output parameters, the tree is 4566 the RPC reply instance document. The XPath root node has the 4567 elements representing the RPC output parameters as children. 4569 The result of the XPath expression is converted to a boolean value 4570 using the standard XPath rules. 4572 The XPath expression MUST NOT include any references to the context 4573 node or any descendants of the context node. 4575 Note that the XPath expression is conceptually evaluated. This means 4576 that an implementation does not have to use an XPath evaluator on the 4577 device. The augment can very well be implemented with specially 4578 written code. 4580 8. Constraints 4582 8.1. Constraints on Data 4584 Several YANG statements define constraints on valid data. These 4585 constraints are enforced in different ways, depending on what type of 4586 data the statement defines. 4588 o If the constraint is defined on configuration data, it MUST be 4589 true in a valid configuration data tree. 4591 o If the constraint is defined on state data, it MUST be true in a 4592 reply to the command. 4594 o If the constraint is defined on notification content, it MUST be 4595 true in any notification instance. 4597 o If the constraint is defined on RPC input parameters, it MUST be 4598 true in an invocation of the RPC method. 4600 o If the constraint is defined on RPC output parameters, it MUST be 4601 true in the RPC reply. 4603 8.2. Hierarchy of Constraints 4605 Conditions on parent nodes affect constraints on child nodes as a 4606 natural consequence of the hierarchy of nodes. "must", "mandatory", 4607 "min-elements", and "max-elements" constraints are not enforced if 4608 the parent node has a "when" or "if-feature" property that is not 4609 satisfied on the current device. 4611 In this example, the mandatory constraints on the "longitude" leaf is 4612 not enforced on devices that lack the the "has-gps" feature: 4614 container location { 4615 if-feature has-gps; 4616 leaf longitude { 4617 mandatory true; 4618 ... 4619 } 4620 } 4622 8.3. Constraint Enforcement Model 4624 For configuration data, there are three windows when constraints can 4625 be enforced: 4627 o during parsing of RPC payloads 4629 o during processing of NETCONF operations 4631 o during validation 4633 Each of these scenarios are considered in the following sections. 4635 8.3.1. Payload Parsing 4637 When content arrives in RPC payloads, it MUST be well-formed XML, 4638 following the hierarchy and content rules defined by the set of 4639 models the device implements. 4641 o If a leaf data value does not match the type constraints for the 4642 leaf, including those defined in the type's range, length, and 4643 pattern properties, the server MUST reply with an "invalid-value" 4644 error-tag in the rpc-error, and with the error-app-tag and error- 4645 message assoicated with the constraint, if any exist. 4647 o If all keys of a list entry are not present, the server MUST reply 4648 with a "missing-element" error-tag in the rpc-error. 4650 o If data for more than one case branch of a choice is present, the 4651 server MUST reply with a "bad-element" in the rpc-error. 4653 o If data for a node tagged with "if-feature" is present, and the 4654 feature is not supported by the device, the server MUST reply with 4655 an "unknown-element" error-tag in the rpc-error. 4657 o If data for a node tagged with "when" is present, and the "when" 4658 condition evaluates to "false", the server MUST reply with an 4659 "unknown-element" error-tag in the rpc-error. 4661 o For insert handling, if the value for the attributes "before" and 4662 "after" are not valid for the type of the appropriate key leafs, 4663 the server MUST reply with a "bad-attribute" error-tag in the rpc- 4664 error. 4666 o If the attributes "before" and "after" appears in any element that 4667 is not a list whose "ordered-by" property is "user", the server 4668 MUST reply with an "unkown-attribute" error-tag in the rpc-error. 4670 8.3.2. NETCONF Processing 4672 After the incoming data is parsed, the NETCONF server performs the 4673 operation by applying the data to the configuration 4674 datastore. During this processing the following errors MUST be 4675 detected: 4677 o Delete requests for non-existent data. 4679 o Create requests for existent data. 4681 o Insert requests with "before" or "after" parameters which do not 4682 exist. 4684 During processing: 4686 o If the NETCONF operation creates data nodes under a "choice", any 4687 existing nodes from other "case" branches are deleted by the 4688 server. 4690 o If the NETCONF operation modifies a data node such that any node's 4691 "when" expression becomes false, then that node is deleted by the 4692 server. 4694 8.3.3. Validation 4696 When datastore processing is complete, the final contents MUST obey 4697 all validation constraints. This validation processing is performed 4698 at differing time according to the datastore. If the datastore is 4699 or , these constraints MUST be enforced at the 4700 end of the or operation. If the 4701 datastore is , the constraint enforcement is delayed until 4702 a or operation. 4704 o Any "must" constraints MUST evaluate to "true". 4706 o Any referential integrity constraints defined via the "path" 4707 statement MUST be satisfied. 4709 o Any "unique" constraints on lists MUST be satisfied. 4711 o The "min-elements" and "max-elements" constraints are enforced for 4712 lists and leaf-lists. 4714 9. Built-in Types 4716 YANG has a set of built-in types, similar to those of many 4717 programming languages, but with some differences due to special 4718 requirements from the management information model. 4720 Additional types may be defined, derived from those built-in types or 4721 from other derived types. Derived types may use subtyping to 4722 formally restrict the set of possible values. 4724 The different built-in types and their derived types allow different 4725 kinds of subtyping, namely length and regular expression restrictions 4726 of strings (Section 9.4.4, Section 9.4.6) and range restrictions of 4727 numeric types (Section 9.2.4). 4729 The lexicographic representation of a value of a certain type is used 4730 in the XML encoding over NETCONF, and when specifying default values 4731 in a YANG module. 4733 9.1. Canonical representation 4735 For most types, there is a single canonical representation of the 4736 type's values. Some types allow multiple lexicographic 4737 representations of the same value, for example the positive integer 4738 "17" can be represented as "+17" or "17". 4740 When NETCONF servers sends data, it MUST be in the canonical form. 4742 Some types have a lexical representation that depends on the XML 4743 context in which they occur. These types do not have a canonical 4744 form. 4746 9.2. The Integer Built-in Types 4748 The integer built-in types are int8, int16, int32, int64, uint8, 4749 uint16, uint32, and uint64. They represent signed and unsigned 4750 integers of different sizes: 4752 int8 represents integer values between -128 and 127, inclusively. 4754 int16 represents integer values between -32768 and 32767, 4755 inclusively. 4757 int32 represents integer values between -2147483648 and 2147483647, 4758 inclusively. 4760 int64 represents integer values between -9223372036854775808 and 4761 9223372036854775807, inclusively. 4763 uint8 represents integer values between 0 and 255, inclusively. 4765 uint16 represents integer values between 0 and 65535, inclusively. 4767 uint32 represents integer values between 0 and 4294967295, 4768 inclusively. 4770 uint64 represents integer values between 0 and 18446744073709551615, 4771 inclusively. 4773 9.2.1. Lexicographic Representation 4775 An integer value is lexicographically represented as an optional sign 4776 ("+" or "-"), followed by a sequence of decimal digits. If no sign 4777 is specified, "+" is assumed. 4779 For convenience, when specifying a default value for an integer in a 4780 YANG module, an alternative lexicographic representation can be used, 4781 which represents the value in a hexadecimal or octal notation. The 4782 hexadecimal notation consists of an optional sign ("+" or "-"), the 4783 characters "0x" followed a number of hexadecimal digits, where 4784 letters may be upper- or lowercase. The octal notation consists of 4785 an optional sign ("+" or "-"), the character "0" followed a number of 4786 octal digits. 4788 Note that if a default value in a YANG module has a leading zero 4789 ("0"), it is interpreted as an octal number. In the XML encoding, an 4790 integer is always interpreted as a decimal number, and leading zeros 4791 are allowed. 4793 Examples: 4795 // legal values 4796 +4711 // legal positive value 4797 4711 // legal positive value 4798 -123 // legal negative value 4799 0xf00f // legal positive hexadecimal value 4800 -0xf // legal negative hexadecimal value 4801 052 // legal positive octal value 4803 // illegal values 4804 - 1 // illegal intermediate space 4806 9.2.2. Canonical Form 4808 The canonical form of a positive integer does not include the sign 4809 "+". Leading zeros are prohibited. The value zero is represented as 4810 "0". 4812 9.2.3. Restrictions 4814 All integer types can be restricted with the "range" statement 4815 (Section 9.2.4). 4817 9.2.4. The range Statement 4819 The "range" statement, which is an optional substatement to the 4820 "type" statement, takes as an argument a range expression string. It 4821 is used to restrict integer and decimal built-in types, or types 4822 derived from those. 4824 A range consists of an explicit value, or a lower inclusive bound, 4825 two consecutive dots "..", and an upper inclusive bound. Multiple 4826 values or ranges can be given, separated by "|". If multiple values 4827 or ranges are given they all MUST be disjoint and MUST be in 4828 ascending order. If a range restriction is applied to an already 4829 range restricted type, the new restriction MUST be equal or more 4830 limiting, that is raising the lower bounds, reducing the upper 4831 bounds, removing explicit values or ranges, or splitting ranges into 4832 multiple ranges with intermediate gaps. Each explicit value and 4833 range boundary value given in the range expression MUST match the 4834 type being restricted, or be one of the special values "min" or 4835 "max". "min" and "max" means the minimum and maximum value accepted 4836 for the type being restricted, respectively. 4838 The range expression syntax is formally defined by the rule 4839 "range-arg" in Section 12. 4841 9.2.4.1. The range's Substatements 4843 +---------------+---------+-------------+ 4844 | substatement | section | cardinality | 4845 +---------------+---------+-------------+ 4846 | description | 7.19.3 | 0..1 | 4847 | error-app-tag | 7.5.4.2 | 0..1 | 4848 | error-message | 7.5.4.1 | 0..1 | 4849 | reference | 7.19.4 | 0..1 | 4850 +---------------+---------+-------------+ 4852 9.2.5. Usage Example 4854 typedef my-base-int32-type { 4855 type int32 { 4856 range "1..4 | 10..20"; 4857 } 4858 } 4860 type my-base-int32-type { 4861 // legal range restriction 4862 range "11..max"; // 11..20 4863 } 4865 type my-base-int32-type { 4866 // illegal range restriction 4867 range "11..100"; 4868 } 4870 9.3. The decimal64 Built-in Type 4872 The decimal64 type represents a subset of the real numbers, which can 4873 be represented by decimal numerals. The value space of decimal64 is 4874 the set of numbers that can be obtained by multiplying a 64 bit 4875 signed integer by a negative power of ten, i.e. expressible as 4876 "i x 10^-n" where i is an integer64 and n is an integer between 1 and 4877 18, inclusively. 4879 9.3.1. Lexicographic Representation 4881 A decimal64 value is lexicographically represented as an optional 4882 sign ("+" or "-"), followed by a sequence of decimal digits, 4883 optionally followed by a period ('.') as a decmial indicator and a 4884 sequence of decimal digits. If no sign is specified, "+" is assumed. 4886 9.3.2. Canonical Form 4888 The canonical form of a positive decimal64 does not include the sign 4889 "+". The decimal point is required. Leading and trailing zeros are 4890 prohibited, subject to the rule that there MUST be at least one digit 4891 before and after the decimal point. The value zero is represented as 4892 "0.0". 4894 9.3.3. Restrictions 4896 A decmial64 type can be restricted with the "range" statement 4897 (Section 9.2.4). 4899 9.3.4. The fraction-digits Statement 4901 The "fraction-digits" statement, which is a substatement to the 4902 "type" statement, MUST be present if the type is "decimal64". It 4903 takes as an argument an integer between 1 and 18, inclusively. It 4904 controls the size of the minimum difference between values of a 4905 decimal64 type, by restricting the value space to numbers that are 4906 expressible as "i x 10^-n" where n is the fraction-digits argument. 4908 9.3.5. Usage Example 4910 type decimal64 { 4911 fraction-digits 2; 4912 range "1 .. 3.14 | 10 | 20..max"; 4913 } 4915 9.4. The string Built-in Type 4917 The string built-in type represents human readable strings in YANG. 4918 Legal characters are tab, carriage return, line feed, and the legal 4919 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 4921 // any Unicode character, excluding the surrogate blocks, 4922 // FFFE, and FFFF. 4923 string = *char 4924 char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / 4925 %x10000-10FFFF 4927 9.4.1. Lexicographic Representation 4929 A string value is lexicographically represented as character data in 4930 the XML encoding. 4932 9.4.2. Canonical Form 4934 The canonical form is the same as the lexicographical representation. 4935 No Unicode normalization is performed of string values. 4937 9.4.3. Restrictions 4939 A string can be restricted with the "length" (Section 9.4.4) and 4940 "pattern" (Section 9.4.6) statements. 4942 9.4.4. The length Statement 4944 The "length" statement, which is an optional substatement to the 4945 "type" statement, takes as an argument a length expression string. 4946 It is used to restrict the built-in type "string", or types derived 4947 from "string". 4949 A "length" statement restricts the number of characters in the 4950 string. 4952 A length range consists of an explicit value, or a lower bound, two 4953 consecutive dots "..", and an upper bound. Multiple values or ranges 4954 can be given, separated by "|". Length restricting values MUST NOT 4955 be negative. If multiple values or ranges are given, they all MUST 4956 be disjoint and MUST be in ascending order. If a length restriction 4957 is applied to an already length restricted type, the new restriction 4958 MUST be equal or more limiting, that is, raising the lower bounds, 4959 reducing the upper bounds, removing explicit length values or ranges, 4960 or splitting ranges into multiple ranges with intermediate gaps. A 4961 length value is a non-negative integer, or one of the special values 4962 "min" or "max". "min" and "max" means the minimum and maximum length 4963 accepted for the type being restricted, respectively. An 4964 implementation is not required to support a length value larger than 4965 18446744073709551615. 4967 The length expression syntax is formally defined by the rule 4968 "length-arg" in Section 12. 4970 9.4.4.1. The length's Substatements 4972 +---------------+---------+-------------+ 4973 | substatement | section | cardinality | 4974 +---------------+---------+-------------+ 4975 | description | 7.19.3 | 0..1 | 4976 | error-app-tag | 7.5.4.2 | 0..1 | 4977 | error-message | 7.5.4.1 | 0..1 | 4978 | reference | 7.19.4 | 0..1 | 4979 +---------------+---------+-------------+ 4981 9.4.5. Usage Example 4983 typedef my-base-str-type { 4984 type string { 4985 length "1..255"; 4986 } 4987 } 4989 type my-base-str-type { 4990 // legal length refinement 4991 length "11 | 42..max"; // 11 | 42..255 4992 } 4994 type my-base-str-type { 4995 // illegal length refinement 4996 length "1..999"; 4997 } 4999 9.4.6. The pattern Statement 5001 The "pattern" statement, which is an optional substatement to the 5002 "type" statement, takes as an argument a regular expression string, 5003 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5004 "string", or types derived from "string", to values that completely 5005 matches the pattern. 5007 If the type has multiple "pattern" statements, the expressions are 5008 AND:ed together, i.e. all such expressions have to match. 5010 If a pattern restriction is applied to an already pattern restricted 5011 type, values must match all patterns in the base type, in addition to 5012 the new patterns. 5014 9.4.6.1. The pattern's Substatements 5016 +---------------+---------+-------------+ 5017 | substatement | section | cardinality | 5018 +---------------+---------+-------------+ 5019 | description | 7.19.3 | 0..1 | 5020 | error-app-tag | 7.5.4.2 | 0..1 | 5021 | error-message | 7.5.4.1 | 0..1 | 5022 | reference | 7.19.4 | 0..1 | 5023 +---------------+---------+-------------+ 5025 9.4.7. Usage Example 5027 With the following type: 5029 type string { 5030 length "0..4"; 5031 pattern "[0-9a-fA-F]*"; 5032 } 5034 the following strings match: 5036 AB // legal 5037 9A00 // legal 5039 and the following strings do not match: 5041 00ABAB // illegal 5042 xx00 // illegal 5044 9.5. The boolean Built-in Type 5046 The boolean built-in type represents a boolean value. 5048 9.5.1. Lexicographic Representation 5050 The lexicographical representation of a boolean value is the strings 5051 "true" and "false". 5053 9.5.2. Restrictions 5055 A boolean cannot be restricted. 5057 9.6. The enumeration Built-in Type 5059 The enumeration built-in type represents values from a set of 5060 assigned names. 5062 9.6.1. Lexicographic Representation 5064 The lexicographical representation of an enumeration value is the 5065 assigned name string. 5067 9.6.2. Canonical Form 5069 The canonical form is the assigned name string. 5071 9.6.3. Restrictions 5073 An enumeration cannot be restricted. 5075 9.6.4. The enum Statement 5077 The "enum" statement, which is a substatement to the "type" 5078 statement, MUST be present if the type is "enumeration". It is 5079 repeatedly used to specify each assigned name of an enumeration type. 5080 It takes as an argument a string which is the assigned name. The 5081 string MUST NOT be empty and MUST NOT have any leading or trailing 5082 whitespace characters. The use of control codes SHOULD be avoided. 5084 The statement is optionally followed by a block of substatements 5085 which holds detailed enum information. 5087 All assigned names in an enumeration MUST be unique. 5089 9.6.4.1. The enum's Substatements 5091 +--------------+---------+-------------+ 5092 | substatement | section | cardinality | 5093 +--------------+---------+-------------+ 5094 | description | 7.19.3 | 0..1 | 5095 | reference | 7.19.4 | 0..1 | 5096 | status | 7.19.2 | 0..1 | 5097 | value | 9.6.4.2 | 0..1 | 5098 +--------------+---------+-------------+ 5100 9.6.4.2. The value Statement 5102 The "value" statement, which is optional, is used to associate an 5103 integer value with the assigned name for the enum. This integer 5104 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5105 unique within the enumeration type. 5107 If a value is not specified, then one will be automatically assigned. 5108 If the enum sub-statement is the first one defined, the assigned 5109 value is zero (0), otherwise the assigned value is one greater than 5110 the current highest enum value. 5112 If the current highest value is equal to 2147483647, then an enum 5113 value MUST be specified for enum sub-statements following the one 5114 with the current highest value. 5116 9.6.5. Usage Example 5118 type enumeration { 5119 enum enabled { 5120 value 1; 5121 } 5122 enum disabled { 5123 value 2; 5124 } 5125 } 5127 type enumeration { 5128 enum zero; 5129 enum one; 5130 enum seven { 5131 value 7; 5132 } 5133 } 5135 9.7. The bits Built-in Type 5137 The bits built-in type represents a bit set. That is, a bits value 5138 is a set of flags identified by small integer position numbers 5139 starting at 0. Each bit number has an assigned name. 5141 9.7.1. Restrictions 5143 A bits type cannot be restricted. 5145 9.7.2. Lexicographic Representation 5147 The lexicographical representation of the bits type is a space 5148 separated list of the individual bit values that are set. An empty 5149 string thus represents a value where no bits are set. 5151 9.7.3. Canonical Form 5153 In the canonical form, the bit values are separated by a single space 5154 character and they appear in the same order as they are specified in 5155 the "bits" statement. 5157 9.7.4. The bit Statement 5159 The "bit" statement, which is a substatement to the "type" statement, 5160 MUST be present if the type is "bits". It is repeatedly used to 5161 specify each assigned named bit of a bits type. It takes as an 5162 argument a string which is the assigned name of the bit. It is 5163 followed by a block of substatements which holds detailed bit 5164 information. A bit name follows the same syntax rules as an 5165 identifier (see Section 6.2). 5167 All bit names in a bits type MUST be unique. 5169 9.7.4.1. The bit's Substatements 5171 +--------------+---------+-------------+ 5172 | substatement | section | cardinality | 5173 +--------------+---------+-------------+ 5174 | description | 7.19.3 | 0..1 | 5175 | reference | 7.19.4 | 0..1 | 5176 | status | 7.19.2 | 0..1 | 5177 | position | 9.7.4.2 | 0..1 | 5178 +--------------+---------+-------------+ 5180 9.7.4.2. The position Statement 5182 The "position" statement, which is optional, takes as an argument a 5183 non-negative integer value which specifies the bit's position within 5184 a hypothetical bit field. The position value MUST be in the range 0 5185 to 4294967295, and it MUST be unique within the bits type. The value 5186 is unused by YANG and the XML encoding, but is carried as a 5187 convenience to implementors. 5189 If a bit position is not specified, then one will be automatically 5190 assigned. If the bit sub-statement is the first one defined, the 5191 assigned value is zero (0), otherwise the assigned value is one 5192 greater than the current highest bit position. 5194 If the current highest bit position value is equal to 4294967295, 5195 then a position value MUST be specified for bit sub-statements 5196 following the one with the current highest position value. 5198 9.7.5. Usage Example 5200 Given the following type: 5202 leaf mybits { 5203 type bits { 5204 bit disable-nagle { 5205 position 0; 5206 } 5207 bit auto-sense-speed { 5208 position 1; 5209 } 5210 bit 10-Mb-only { 5211 position 2; 5212 } 5213 } 5214 default "auto-sense-speed"; 5215 } 5217 The lexicographic representation of this leaf with bit values 5218 disable-nagle and 10-Mb-only set would be: 5220 disable-nagle 10-Mb-only 5222 9.8. The binary Built-in Type 5224 The binary built-in type represents any binary data, i.e. a sequence 5225 of octets. 5227 9.8.1. Restrictions 5229 A binary can be restricted with the "length" (Section 9.4.4) 5230 statement. The length of a binary value is the number of octets it 5231 contains. 5233 9.8.2. Lexicographic Representation 5235 Binary values are encoded with the base64 encoding scheme [RFC4648]. 5237 9.8.3. Canonical Form 5239 The canonical form of a binary value follow the rules in [RFC4648]. 5241 9.9. The leafref Built-in Type 5243 The leafref type is used to reference a particular leaf instance in 5244 the data tree. Its value is constrained to be the same as the value 5245 of an existing leaf. 5247 If the leaf with the leafref type represents configuration data, and 5248 the "require-instance" property (Section 9.9.3) is "true", the leaf 5249 it refers to MUST also represent configuration. Such a leaf puts a 5250 constraint on valid data. All leafref nodes MUST reference existing 5251 leaf instances for the data to be valid. This constraint is enforced 5252 according to the rules in Section 8. 5254 9.9.1. Restrictions 5256 A leafref can be restricted with the "require-instance" statement 5257 (Section 9.9.3). 5259 9.9.2. The path Statement 5261 The "path" statement, which is a substatement to the "type" 5262 statement, MUST be present if the type is "leafref". It takes as an 5263 argument a string which MUST refer to a leaf node. The value of the 5264 referring leaf MUST match the type of the referred leaf. 5266 The syntax for a path argument is a subset of the XPath syntax. It 5267 is an absolute or relative XPath location path in abbreviated syntax, 5268 where axes are not permitted, and predicates are used only for 5269 constraining the values for the key nodes for list entries. Each 5270 predicate consists of exactly one equality test per key. 5272 The predicates are only used when more than one key reference is 5273 needed to uniquely identify a leaf instance. This occurs if a list 5274 has multiple keys, or a reference to a leaf other than the key in a 5275 list is needed. In these cases, multiple leafrefs are typically 5276 specified, and predicates are used to tie them together. 5278 The syntax is formally defined by the rule "path-arg" in Section 12. 5280 For leafs of type "leafref", the "path" expression evaluates to a 5281 node set consisting of zero, one or more nodes. If 5282 "require-instance" is "true", the node set MUST be non-empty. 5284 9.9.3. The require-instance Statement 5286 The "require-instance" statement, which is a substatement to the 5287 "type" statement, MAY be present if the type is "leafref" or 5288 "instance-identifier". It takes as an argument the string "true" or 5289 "false". If this statement is not present, it defaults to "true". 5291 If "require-instance" is "true", it means that the instance being 5292 referred MUST exist for the data to be valid. This constraint is 5293 enforced according to the rules in Section 8. 5295 9.9.4. Lexicographic Representation 5297 A leafref value is encoded the same way as the leaf it references. 5299 9.9.5. Canonical Form 5301 The canonical form of a leafref is the same as the canonical form of 5302 the leaf it references. 5304 9.9.6. Usage Example 5306 With the following list: 5308 list interface { 5309 key "name"; 5310 leaf name { 5311 type string; 5312 } 5313 leaf ifIndex { 5314 type uint32; 5315 } 5316 list address { 5317 key "ip"; 5318 leaf ip { 5319 type yang:ip-address; 5320 } 5321 } 5322 } 5324 The following leafref refers to an existing interface: 5326 leaf mgmt-interface { 5327 type leafref { 5328 path "../interface/name"; 5329 } 5330 } 5332 An example of a corresponding XML snippet: 5334 5335 eth0 5336 5337 5338 lo 5339 5341 eth0 5343 The following leafrefs refer to an existing address of an interface: 5345 container default-address { 5346 leaf ifname { 5347 type leafref { 5348 path "../../interface/name"; 5349 } 5350 } 5351 leaf address { 5352 type leafref { 5353 path "../../interface[name = current()/../ifname]" 5354 + "/address/ip"; 5355 } 5356 } 5357 } 5359 An example of a corresponding XML snippet: 5361 5362 eth0 5363 2 5364
5365 192.0.2.1 5366
5367
5368 192.0.2.2 5369
5370 5371 5372 lo 5373 1 5374
5375 127.0.0.1 5376
5377 5379 5380 eth0 5381
192.0.2.2
5382 5384 The following notification defines two leafrefs to refer to an 5385 existing ifIndex: 5387 notification link-failure { 5388 leaf if-name { 5389 type leafref { 5390 path "/interfaces/interface/name"; 5391 } 5392 } 5393 leaf index { 5394 type leafref { 5395 path 5396 "/interfaces/interface[name = current()/../if-name]" 5397 + "/ifIndex"; 5398 } 5399 } 5400 } 5402 An example of a corresponding XML notification: 5404 5406 2008-04-01T00:01:00Z 5407 5408 eth0 5409 2 5410 5411 5413 9.10. The identityref Built-in Type 5415 The identityref type is used to reference an existing identity (see 5416 Section 7.16). 5418 9.10.1. Restrictions 5420 An identityref cannot be restricted. 5422 9.10.2. The identityref's base Statement 5424 The "base" statement, which is a substatement to the "type" 5425 statement, MUST be present if the type is "identityref". The 5426 argument is the name of an identity, as defined by an "identity" 5427 statement. If a prefix is present on the identity name, it refers to 5428 an identity defined in the module which was imported with that 5429 prefix. Otherwise an identity with the matching name MUST be defined 5430 in the current module or an included submodule. 5432 Valid values for an identityref are any identities derived from the 5433 identityref's base identity. 5435 9.10.3. Lexicographic Representation 5437 An identityref is encoded as the referred identity's Qualified Name 5438 as defined in [XML-NAMES]. If the Prefix is not present, the 5439 namespace of the identityref is the default namespace in effect on 5440 the element which contains the identityref value. 5442 9.10.4. Canonical Form 5444 Since the lexicographic form depends on the XML context in which the 5445 value occurs, this type does not have a canonical form. 5447 9.10.5. Usage Example 5449 With the identity definitions in Section 7.16.3, and the following 5450 module: 5452 module my-crypto { 5454 namespace "http://example.com/my-crypto"; 5455 prefix mc; 5457 import "crypto-base" { 5458 prefix "crypto"; 5459 } 5461 identity aes { 5462 base "crypto:crypto-alg"; 5463 } 5465 leaf crypto { 5466 type identityref { 5467 base "crypto:crypto-alg"; 5468 } 5469 } 5470 } 5472 The leaf "crypto" will be encoded as follows, if the value is the 5473 "des3" identity defined in the "des" module: 5475 des:des3 5477 Any prefixes used in the encoding are local to each instance 5478 encoding. This means that the same identityref may be encoded 5479 differently by different implementations. For example, the following 5480 example encodes the same leaf as above: 5482 x:des3 5484 If the "crypto" leaf's value instead is "aes" defined in the 5485 "my-crypto" module it can be encoded as: 5487 mc:aes 5489 or, using the default namespace: 5491 aes 5493 9.11. The empty Built-in Type 5495 The empty built-in type represents a leaf that does not have any 5496 value, it conveys information by its presence or absence. 5498 An empty type cannot have a default value. 5500 9.11.1. Restrictions 5502 An empty type cannot be restricted. 5504 9.11.2. Lexicographic Representation 5506 Not applicable. 5508 9.11.3. Canonical Form 5510 Not applicable. 5512 9.11.4. Usage Example 5514 The following leaf 5516 leaf enable-qos { 5517 type empty; 5518 } 5520 will be encoded as 5522 5524 if it exists. 5526 9.12. The union Built-in Type 5528 The union built-in type represents a value that corresponds to one of 5529 its member types. 5531 When the type is "union", the "type" statement (Section 7.4) MUST be 5532 present. It is used to repeatedly specify each member type of the 5533 union. It takes as an argument a string which is the name of a 5534 member type. 5536 A member type can be of any built-in or derived type, except it MUST 5537 NOT be one of the built-in types "empty" or "leafref". 5539 When a string representing a union data type is validated, the string 5540 is validated against each member type, in the order they are 5541 specified in the type statement, until a match is found. 5543 Example: 5545 type union { 5546 type int32; 5547 type enumeration { 5548 enum "unbounded"; 5549 } 5550 } 5552 9.12.1. Restrictions 5554 A union can not be restricted. However, each member type can be 5555 restricted, based on the rules defined in Section 9 chapter. 5557 9.12.2. Lexicographic Representation 5559 The lexicographical representation of an union is a value that 5560 corresponds to the representation of any one of the member types. 5562 9.12.3. Canonical Form 5564 The canonical form of a union value is the same as the canonical form 5565 of the member type of the value. 5567 9.13. The instance-identifier Built-in Type 5569 The instance-identifier built-in type is used to uniquely identify a 5570 particular instance node in the data tree. 5572 The syntax for an instance-identifier is a subset of the XPath 5573 syntax, which is used to uniquely identify a node in the data tree. 5574 It is an absolute XPath location path in abbreviated syntax, where 5575 axes are not permitted, and predicates are used only for specifying 5576 the values for the key nodes for list entries, a value of a leaf-list 5577 entry, or a positional index for list without keys. For identifying 5578 list entries with keys, each predicate consists of one equality test 5579 per key, and each key MUST have a corresponding predicate. 5581 If the leaf with the instance-identifier type represents 5582 configuration data, and the "require-instance" property 5583 (Section 9.9.3) is "true", the node it refers to MUST also represent 5584 configuration. Such a leaf puts a constraint on valid data. All 5585 such leaf nodes MUST reference existing nodes for the data to be 5586 valid. This constraint is enforced according to the rules in 5587 Section 8. 5589 The syntax is formally defined by the rule "instance-identifier" in 5590 Section 12. 5592 9.13.1. Restrictions 5594 An instance-identifier can be restricted with the "require-instance" 5595 statement (Section 9.9.3). 5597 9.13.2. Lexicographic Representation 5599 An instance-identifier value is lexicographically represented as a 5600 string in the XML encoding. The namespace prefixes used in the 5601 encoding MUST be declared in the XML namespace scope in the instance- 5602 idenfitier's XML element. 5604 Any prefixes used in the encoding are local to each instance 5605 encoding. This means that the same instance-identifier may be 5606 encoded differently by different implementations. 5608 9.13.3. Canonical Form 5610 Since the lexicographic form depends on the XML context in which the 5611 value occurs, this type does not have a canonical form. 5613 9.13.4. Usage Example 5615 The following are examples of instance identifiers: 5617 /* instance-identifier for a container */ 5618 /ex:system/ex:services/ex:ssh 5620 /* instance-identifier for a leaf */ 5621 /ex:system/ex:services/ex:ssh/ex:port 5623 /* instance-identifier for a list entry */ 5624 /ex:system/ex:user[ex:name='fred'] 5626 /* instance-identifier for a leaf in a list entry */ 5627 /ex:system/ex:user[ex:name='fred']/ex:type 5629 /* instance-identifier for a list entry with two keys */ 5630 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 5632 /* instance-identifier for a leaf-list entry */ 5633 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 5635 /* instance-identifier for a list entry without keys */ 5636 /ex:stats/ex:port[3] 5638 10. Updating a Module 5640 As experience is gained with a module, it may be desirable to revise 5641 that module. However, changes are not allowed if they have any 5642 potential to cause interoperability problems between a client using 5643 an original specification and a server using an updated 5644 specification. 5646 For any published change, a new "revision" statement (Section 7.1.9) 5647 SHOULD be included in front of the existing revision statements. 5648 Furthermore, any necessary changes MUST be applied to any meta 5649 statements, including the "organization" and "contact" statements 5650 (Section 7.1.7, Section 7.1.8). 5652 Note that definitions contained in a module are available to be 5653 imported by any other module, and are referenced in "import" 5654 statements via the module name. Thus, a module name MUST NOT be 5655 changed. Furthermore, the "namespace" statement MUST NOT be changed, 5656 since all XML elements are encoded in the namespace. 5658 Obsolete definitions MUST NOT be removed from modules since their 5659 identifiers may still be referenced by other modules. 5661 A definition may be revised in any of the following ways: 5663 o An "enumeration" type may have new enums added, provided the old 5664 enums's values do not change. 5666 o A "bits" type may have new bits added, provided the old bits's 5667 positions do not change. 5669 o A "range", "length", or "pattern" statement may expand the allowed 5670 value space. 5672 o A "default" statement may be added. 5674 o A "units" statement may be added. 5676 o A "reference" statement may be added or updated. 5678 o A "must" statement may be removed or its constraint relaxed. 5680 o A "mandatory" statement may be removed or changed from "true" to 5681 "false". 5683 o A "min-elements" statement may be removed, or changed to require 5684 less elements. 5686 o A "max-elements" statement may be removed, or changed to allow 5687 more elements. 5689 o A "description" statement may be added or clarified without 5690 changing the semantics of the definition. 5692 o New typedefs, groupings, rpc, notifications, extensions, features, 5693 and identities may be added. 5695 o New data definition statements may be added if they do not add 5696 mandatory nodes (Section 3.1) to existing nodes or at the top- 5697 level in a module or submodule, or if they are conditionally 5698 dependent on a new feature (i.e. have a "if-feature" statement 5699 which refers to a new feature). 5701 o A new "case" statement may be added. 5703 o A node that represented state data may be changed to represent 5704 configuration, provided it is not mandatory (Section 3.1). 5706 o An "if-feature" statement may be removed, provided its node is not 5707 mandatory (Section 3.1). 5709 o A "status" statement may be added, or changed from "current" to 5710 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 5712 o A "type" statement may be replaced with another "type" statement 5713 which does not change the syntax or semantics of the type. For 5714 example, an inline type definition may be replaced with a typedef, 5715 but a int8 type cannot be replaced by a int16, since the syntax 5716 would change. 5718 o Any set of data definition nodes may be replaced with another set 5719 of syntactically and semantically equivalent nodes. For example, 5720 a set of leafs may be replaced by a uses of a grouping with the 5721 same leafs. 5723 o A module may be split into a set of submodules, or submodule may 5724 be removed, provided the definitions in the module do not change 5725 in any other way than allowed here. 5727 o The "prefix" statment may be changed, provided all local uses of 5728 the prefix also are changed. 5730 Otherwise, if the semantics of any previous definition are changed 5731 (i.e. if a non-editorial change is made to any definition other than 5732 those specifically allowed above), then this MUST be achieved by a 5733 new definition with a new identifier. 5735 In statements which have any data definition statements as 5736 substatements, those data definition substatements MUST NOT be 5737 reordered. 5739 11. YIN 5741 A YANG module can be specified in an alternative XML-based syntax 5742 called YIN. This section describes symmetric mapping rules between 5743 the two formats. 5745 The YANG and YIN formats contain equivalent information using 5746 different notations. The purpose of the YIN notation is to allow the 5747 user to translate YANG into YIN, use the rich set of XML based tools 5748 on the YIN format to transform, or filter the model information. 5749 Tools like XSLT or XML validators can be utilized. After this the 5750 model can be transformed back to the YANG format if needed, which 5751 provides a more concise and readable format. 5753 The mapping between YANG and YIN does not modify the information 5754 content of the model. Comments and whitespaces are not preserved. 5756 11.1. Formal YIN Definition 5758 There is a one-to-one correspondence between YANG keywords and YIN 5759 elements. The local name of a YIN element is identical to the 5760 corresponding YANG keyword. This means in particular that the 5761 document element (root) of a YIN document is always or 5762 . 5764 YIN elements corresponding to the core YANG keywords belong to the 5765 namespace whose associated URI is 5766 "urn:ietf:params:xml:ns:yang:yin:1". 5768 YIN elements corresponding to extension keywords belong to the 5769 namespace of the YANG module where the extension keyword is declared 5770 via the "extension" statement. 5772 The names of all YIN elements MUST be properly qualified with their 5773 namespaces specified above using the standard mechanisms of 5774 [XML-NAMES], i.e. "xmlns" and "xmlns:xxx" attributes. 5776 The argument of a YANG statement is encoded in YIN either as an XML 5777 attribute or a subelement of the keyword element. Table 1 defines 5778 the encoding for the set of core YANG keywords. For extensions, the 5779 argument encoding is specified within the "extension" statement (see 5780 Section 7.17). The following rules hold for arguments of both core 5781 and extension statements: 5783 o If the argument is encoded as an attribute, this attribute has no 5784 namespace. 5786 o If the argument is encoded as an element, it is placed to the same 5787 namespace as its parent keyword element. 5789 o If the argument is encoded as an element, it MUST be the first 5790 child of the keyword element. 5792 Substatements of a YANG statement are encoded as (additional) 5793 children of the keyword element and their relative order MUST be the 5794 same as the order of substatements in YANG. 5796 Comments in YANG MAY be mapped to XML comments. 5798 Mapping of arguments of the core YANG statements. 5800 +------------------+---------------+-------------+ 5801 | keyword | argument name | yin-element | 5802 +------------------+---------------+-------------+ 5803 | anyxml | name | false | 5804 | argument | name | false | 5805 | augment | target-node | false | 5806 | base | name | false | 5807 | belongs-to | module | false | 5808 | bit | name | false | 5809 | case | name | false | 5810 | choice | name | false | 5811 | config | value | false | 5812 | contact | info | true | 5813 | container | name | false | 5814 | default | value | false | 5815 | description | text | true | 5816 | deviate | value | false | 5817 | deviation | target-node | false | 5818 | enum | name | false | 5819 | error-app-tag | value | false | 5820 | error-message | value | true | 5821 | extension | name | false | 5822 | feature | name | false | 5823 | fraction-digits | value | false | 5824 | grouping | name | false | 5825 | identity | name | false | 5826 | if-feature | name | false | 5827 | import | module | false | 5828 | include | module | false | 5829 | input | | n/a | 5830 | key | value | false | 5831 | leaf | name | false | 5832 | leaf-list | name | false | 5833 | length | value | false | 5834 | list | name | false | 5835 | mandatory | value | false | 5836 | max-elements | value | false | 5837 | min-elements | value | false | 5838 | module | name | false | 5839 | must | condition | false | 5840 | namespace | uri | false | 5841 | notification | name | false | 5842 | ordered-by | value | false | 5843 | organization | info | true | 5844 | output | | n/a | 5845 | path | value | false | 5846 | pattern | value | false | 5847 | position | value | false | 5848 | prefix | value | false | 5849 | presence | value | false | 5850 | range | value | false | 5851 | reference | info | false | 5852 | refine | target-node | false | 5853 | require-instance | value | false | 5854 | revision | date | false | 5855 | revision-date | date | false | 5856 | rpc | name | false | 5857 | status | value | false | 5858 | submodule | name | false | 5859 | type | name | false | 5860 | typedef | name | false | 5861 | unique | tag | false | 5862 | units | name | false | 5863 | uses | name | false | 5864 | value | value | false | 5865 | when | condition | false | 5866 | yang-version | value | false | 5867 | yin-element | value | false | 5868 +------------------+---------------+-------------+ 5870 Table 1 5872 11.1.1. Usage Example 5874 The following YANG snippet: 5876 leaf mtu { 5877 type uint32; 5878 description "The MTU of the interface."; 5879 myext:c-define "MY_MTU"; 5880 } 5882 where the extension "c-define" is defined in Section 7.17.3, is 5883 translated into the following YIN snippet: 5885 5886 5887 5888 The MTU of the interface. 5889 5890 5891 5893 12. YANG ABNF Grammar 5895 In YANG, almost all statements are unordered. The ABNF grammar 5896 [RFC5234] defines the canonical order. To improve module 5897 readability, it is RECOMMENDED that clauses be entered in this order. 5899 Within the ABNF grammar, unordered statements are marked with 5900 comments. 5902 This grammar assumes that the scanner replaces YANG comments with a 5903 single space character. 5905 module-stmt = optsep module-keyword sep identifier-arg-str 5906 optsep 5907 "{" stmtsep 5908 module-header-stmts 5909 linkage-stmts 5910 meta-stmts 5911 revision-stmts 5912 body-stmts 5913 "}" optsep 5915 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 5916 optsep 5917 "{" stmtsep 5918 submodule-header-stmts 5919 linkage-stmts 5920 meta-stmts 5921 revision-stmts 5922 body-stmts 5923 "}" optsep 5925 module-header-stmts = ;; these stmts can appear in any order 5926 [yang-version-stmt stmtsep] 5927 namespace-stmt stmtsep 5928 prefix-stmt stmtsep 5930 submodule-header-stmts = 5931 ;; these stmts can appear in any order 5932 [yang-version-stmt stmtsep] 5933 belongs-to-stmt stmtsep 5935 meta-stmts = ;; these stmts can appear in any order 5936 [organization-stmt stmtsep] 5937 [contact-stmt stmtsep] 5938 [description-stmt stmtsep] 5939 [reference-stmt stmtsep] 5941 linkage-stmts = ;; these stmts can appear in any order 5942 *(import-stmt stmtsep) 5943 *(include-stmt stmtsep) 5945 revision-stmts = *(revision-stmt stmtsep) 5947 body-stmts = *((extension-stmt / 5948 feature-stmt / 5949 identity-stmt / 5950 typedef-stmt / 5951 grouping-stmt / 5952 data-def-stmt / 5953 augment-stmt / 5954 rpc-stmt / 5955 notification-stmt / 5956 deviation-stmt) stmtsep) 5958 data-def-stmt = container-stmt / 5959 leaf-stmt / 5960 leaf-list-stmt / 5961 list-stmt / 5962 choice-stmt / 5963 anyxml-stmt / 5964 uses-stmt 5966 case-data-def-stmt = container-stmt / 5967 leaf-stmt / 5968 leaf-list-stmt / 5969 list-stmt / 5970 anyxml-stmt / 5971 uses-stmt 5973 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 5974 optsep stmtend 5976 yang-version-arg-str = < a string which matches the rule 5977 yang-version-arg > 5979 yang-version-arg = "1" 5981 import-stmt = import-keyword sep identifier-arg-str optsep 5982 "{" stmtsep 5983 prefix-stmt stmtsep 5984 [revision-date-stmt stmtsep] 5985 "}" 5987 include-stmt = include-keyword sep identifier-arg-str optsep 5988 (";" / 5989 "{" stmtsep 5990 [revision-date-stmt stmtsep] 5991 "}") 5993 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 5995 uri-str = < a string which matches the rule 5996 URI in RFC 3986 > 5998 prefix-stmt = prefix-keyword sep prefix-arg-str 5999 optsep stmtend 6001 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6002 optsep 6003 "{" stmtsep 6004 prefix-stmt stmtsep 6005 "}" 6007 organization-stmt = organization-keyword sep string 6008 optsep stmtend 6010 contact-stmt = contact-keyword sep string optsep stmtend 6012 description-stmt = description-keyword sep string optsep 6013 stmtend 6015 reference-stmt = reference-keyword sep string optsep stmtend 6017 units-stmt = units-keyword sep string optsep stmtend 6019 revision-stmt = revision-keyword sep revision-date optsep 6020 (";" / 6021 "{" stmtsep 6022 [description-stmt stmtsep] 6023 "}") 6025 revision-date = date-arg-str 6027 revision-date-stmt = revision-date-keyword sep revision-date stmtend 6029 extension-stmt = extension-keyword sep identifier-arg-str optsep 6030 (";" / 6031 "{" stmtsep 6032 ;; these stmts can appear in any order 6033 [argument-stmt stmtsep] 6034 [status-stmt stmtsep] 6035 [description-stmt stmtsep] 6036 [reference-stmt stmtsep] 6038 "}") 6040 argument-stmt = argument-keyword sep identifier-arg-str optsep 6041 (";" / 6042 "{" stmtsep 6043 [yin-element-stmt stmtsep] 6044 "}") 6046 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 6047 stmtend 6049 yin-element-arg-str = < a string which matches the rule 6050 yin-element-arg > 6052 yin-element-arg = true-keyword / false-keyword 6054 identity-stmt = identity-keyword sep identifier-arg-str optsep 6055 (";" / 6056 "{" stmtsep 6057 ;; these stmts can appear in any order 6058 [base-stmt stmtsep] 6059 [status-stmt stmtsep] 6060 [description-stmt stmtsep] 6061 [reference-stmt stmtsep] 6062 "}") 6064 base-stmt = base-keyword sep identifier-ref-arg-str 6065 optsep stmtend 6067 feature-stmt = feature-keyword sep identifier-arg-str optsep 6068 (";" / 6069 "{" stmtsep 6070 ;; these stmts can appear in any order 6071 *(if-feature-stmt stmtsep) 6072 [status-stmt stmtsep] 6073 [description-stmt stmtsep] 6074 [reference-stmt stmtsep] 6075 "}") 6077 if-feature-stmt = if-feature-keyword sep identifier-ref-arg-str 6078 optsep stmtend 6080 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 6081 "{" stmtsep 6082 ;; these stmts can appear in any order 6083 type-stmt stmtsep 6084 [units-stmt stmtsep] 6085 [default-stmt stmtsep] 6087 [status-stmt stmtsep] 6088 [description-stmt stmtsep] 6089 [reference-stmt stmtsep] 6090 "}" 6092 type-stmt = type-keyword sep identifier-ref-arg-str optsep 6093 (";" / 6094 "{" stmtsep 6095 type-body-stmts 6096 "}") 6098 type-body-stmts = numerical-restrictions / 6099 decimal64-specification / 6100 string-restrictions / 6101 enum-specification / 6102 leafref-specification / 6103 identityref-specification / 6104 instance-identifier-specification / 6105 bits-specification / 6106 union-specification 6108 numerical-restrictions = range-stmt stmtsep 6110 range-stmt = range-keyword sep range-arg-str optsep 6111 (";" / 6112 "{" stmtsep 6113 ;; these stmts can appear in any order 6114 [error-message-stmt stmtsep] 6115 [error-app-tag-stmt stmtsep] 6116 [description-stmt stmtsep] 6117 [reference-stmt stmtsep] 6118 "}") 6120 decimal64-specification = fraction-digits-stmt 6122 fraction-digits-stmt = fraction-digits-keyword sep 6123 fraction-digits-arg-str stmtend 6125 fraction-digits-arg-str = < a string which matches the rule 6126 fraction-digits-arg > 6128 fraction-digits-arg = ("1" ["2" / "3" / "4" / "5" / "6" / "7" / "8"]) 6129 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 6131 string-restrictions = ;; these stmts can appear in any order 6132 [length-stmt stmtsep] 6133 *(pattern-stmt stmtsep) 6135 length-stmt = length-keyword sep length-arg-str optsep 6136 (";" / 6137 "{" stmtsep 6138 ;; these stmts can appear in any order 6139 [error-message-stmt stmtsep] 6140 [error-app-tag-stmt stmtsep] 6141 [description-stmt stmtsep] 6142 [reference-stmt stmtsep] 6143 "}") 6145 pattern-stmt = pattern-keyword sep string optsep 6146 (";" / 6147 "{" stmtsep 6148 ;; these stmts can appear in any order 6149 [error-message-stmt stmtsep] 6150 [error-app-tag-stmt stmtsep] 6151 [description-stmt stmtsep] 6152 [reference-stmt stmtsep] 6153 "}") 6155 default-stmt = default-keyword sep string stmtend 6157 enum-specification = 1*(enum-stmt stmtsep) 6159 enum-stmt = enum-keyword sep string optsep 6160 (";" / 6161 "{" stmtsep 6162 ;; these stmts can appear in any order 6163 [value-stmt stmtsep] 6164 [status-stmt stmtsep] 6165 [description-stmt stmtsep] 6166 [reference-stmt stmtsep] 6167 "}") 6169 leafref-specification = 6170 ;; these stmts can appear in any order 6171 path-stmt stmtsep 6172 [require-instance-stmt stmtsep] 6174 path-stmt = path-keyword sep path-arg-str stmtend 6176 require-instance-stmt = require-instance-keyword sep 6177 require-instance-arg-str stmtend 6179 require-instance-arg-str = < a string which matches the rule 6180 require-instance-arg > 6182 require-instance-arg = true-keyword / false-keyword 6183 instance-identifier-specification = 6184 [require-instance-stmt stmtsep] 6186 identityref-specification = 6187 base-stmt stmtsep 6189 union-specification = 1*(type-stmt stmtsep) 6191 bits-specification = 1*(bit-stmt stmtsep) 6193 bit-stmt = bit-keyword sep identifier-arg-str optsep 6194 (";" / 6195 "{" stmtsep 6196 ;; these stmts can appear in any order 6197 [position-stmt stmtsep] 6198 [status-stmt stmtsep] 6199 [description-stmt stmtsep] 6200 [reference-stmt stmtsep] 6201 "}" 6202 "}") 6204 position-stmt = position-keyword sep 6205 position-value-arg-str stmtend 6207 position-value-arg-str = < a string which matches the rule 6208 position-value-arg > 6210 position-value-arg = non-negative-integer-value 6212 status-stmt = status-keyword sep status-arg-str stmtend 6214 status-arg-str = < a string which matches the rule 6215 status-arg > 6217 status-arg = current-keyword / 6218 obsolete-keyword / 6219 deprecated-keyword 6221 config-stmt = config-keyword sep 6222 config-arg-str stmtend 6224 config-arg-str = < a string which matches the rule 6225 config-arg > 6227 config-arg = true-keyword / false-keyword 6229 mandatory-stmt = mandatory-keyword sep 6230 mandatory-arg-str stmtend 6232 mandatory-arg-str = < a string which matches the rule 6233 mandatory-arg > 6235 mandatory-arg = true-keyword / false-keyword 6237 presence-stmt = presence-keyword sep string stmtend 6239 ordered-by-stmt = ordered-by-keyword sep 6240 ordered-by-arg-str stmtend 6242 ordered-by-arg-str = < a string which matches the rule 6243 ordered-by-arg > 6245 ordered-by-arg = user-keyword / system-keyword 6247 must-stmt = must-keyword sep string optsep 6248 (";" / 6249 "{" stmtsep 6250 ;; these stmts can appear in any order 6251 [error-message-stmt stmtsep] 6252 [error-app-tag-stmt stmtsep] 6253 [description-stmt stmtsep] 6254 [reference-stmt stmtsep] 6255 "}") 6257 error-message-stmt = error-message-keyword sep string stmtend 6259 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 6261 min-elements-stmt = min-elements-keyword sep 6262 min-value-arg-str stmtend; 6264 min-value-arg-str = < a string which matches the rule 6265 min-value-arg > 6267 min-value-arg = non-negative-integer-value 6269 max-elements-stmt = max-elements-keyword sep 6270 max-value-arg-str stmtend; 6272 max-value-arg-str = < a string which matches the rule 6273 max-value-arg > 6275 max-value-arg = unbounded-keyword / 6276 positive-integer-value 6278 value-stmt = value-keyword sep integer-value stmtend 6279 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 6280 (";" / 6281 "{" stmtsep 6282 ;; these stmts can appear in any order 6283 [status-stmt stmtsep] 6284 [description-stmt stmtsep] 6285 [reference-stmt stmtsep] 6286 *((typedef-stmt / 6287 grouping-stmt) stmtsep) 6288 *(data-def-stmt stmtsep) 6289 "}") 6291 container-stmt = container-keyword sep identifier-arg-str optsep 6292 (";" / 6293 "{" stmtsep 6294 ;; these stmts can appear in any order 6295 [when-stmt stmtsep] 6296 *(if-feature-stmt stmtsep) 6297 *(must-stmt stmtsep) 6298 [presence-stmt stmtsep] 6299 [config-stmt stmtsep] 6300 [status-stmt stmtsep] 6301 [description-stmt stmtsep] 6302 [reference-stmt stmtsep] 6303 *((typedef-stmt / 6304 grouping-stmt) stmtsep) 6305 *(data-def-stmt stmtsep) 6306 "}") 6308 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 6309 "{" stmtsep 6310 ;; these stmts can appear in any order 6311 [when-stmt stmtsep] 6312 *(if-feature-stmt stmtsep) 6313 type-stmt stmtsep 6314 [units-stmt stmtsep] 6315 *(must-stmt stmtsep) 6316 [default-stmt stmtsep] 6317 [config-stmt stmtsep] 6318 [mandatory-stmt stmtsep] 6319 [status-stmt stmtsep] 6320 [description-stmt stmtsep] 6321 [reference-stmt stmtsep] 6322 "}" 6324 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 6325 "{" stmtsep 6326 ;; these stmts can appear in any order 6328 [when-stmt stmtsep] 6329 *(if-feature-stmt stmtsep) 6330 type-stmt stmtsep 6331 [units-stmt stmtsep] 6332 *(must-stmt stmtsep) 6333 [config-stmt stmtsep] 6334 [min-elements-stmt stmtsep] 6335 [max-elements-stmt stmtsep] 6336 [ordered-by-stmt stmtsep] 6337 [status-stmt stmtsep] 6338 [description-stmt stmtsep] 6339 [reference-stmt stmtsep] 6340 "}" 6342 list-stmt = list-keyword sep identifier-arg-str optsep 6343 "{" stmtsep 6344 ;; these stmts can appear in any order 6345 [when-stmt stmtsep] 6346 *(if-feature-stmt stmtsep) 6347 *(must-stmt stmtsep) 6348 [key-stmt stmtsep] 6349 *(unique-stmt stmtsep) 6350 [config-stmt stmtsep] 6351 [min-elements-stmt stmtsep] 6352 [max-elements-stmt stmtsep] 6353 [ordered-by-stmt stmtsep] 6354 [status-stmt stmtsep] 6355 [description-stmt stmtsep] 6356 [reference-stmt stmtsep] 6357 *((typedef-stmt / 6358 grouping-stmt) stmtsep) 6359 1*(data-def-stmt stmtsep) 6360 "}" 6362 key-stmt = key-keyword sep key-arg-str stmtend 6364 key-arg-str = < a string which matches the rule 6365 key-arg > 6367 key-arg = node-identifier *(sep node-identifier) 6369 unique-stmt = unique-keyword sep unique-arg-str stmtend 6371 unique-arg-str = < a string which matches the rule 6372 unique-arg > 6374 unique-arg = descendant-schema-nodeid 6375 *(sep descendant-schema-nodeid) 6377 choice-stmt = choice-keyword sep identifier-arg-str optsep 6378 (";" / 6379 "{" stmtsep 6380 ;; these stmts can appear in any order 6381 [when-stmt stmtsep] 6382 *(if-feature-stmt stmtsep) 6383 [default-stmt stmtsep] 6384 [config-stmt stmtsep] 6385 [mandatory-stmt stmtsep] 6386 [status-stmt stmtsep] 6387 [description-stmt stmtsep] 6388 [reference-stmt stmtsep] 6389 *((short-case-stmt / case-stmt) stmtsep) 6390 "}") 6392 short-case-stmt = container-stmt / 6393 leaf-stmt / 6394 leaf-list-stmt / 6395 list-stmt / 6396 anyxml-stmt 6398 case-stmt = case-keyword sep identifier-arg-str optsep 6399 (";" / 6400 "{" stmtsep 6401 ;; these stmts can appear in any order 6402 [when-stmt stmtsep] 6403 *(if-feature-stmt stmtsep) 6404 [status-stmt stmtsep] 6405 [description-stmt stmtsep] 6406 [reference-stmt stmtsep] 6407 *(case-data-def-stmt stmtsep) 6408 "}") 6410 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 6411 (";" / 6412 "{" stmtsep 6413 ;; these stmts can appear in any order 6414 [when-stmt stmtsep] 6415 *(if-feature-stmt stmtsep) 6416 *(must-stmt stmtsep) 6417 [config-stmt stmtsep] 6418 [mandatory-stmt stmtsep] 6419 [status-stmt stmtsep] 6420 [description-stmt stmtsep] 6421 [reference-stmt stmtsep] 6422 "}") 6424 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 6425 (";" / 6426 "{" stmtsep 6427 ;; these stmts can appear in any order 6428 [when-stmt stmtsep] 6429 *(if-feature-stmt stmtsep) 6430 [status-stmt stmtsep] 6431 [description-stmt stmtsep] 6432 [reference-stmt stmtsep] 6433 *(refine-stmt stmtsep) 6434 *(uses-augment-stmt stmtsep) 6435 "}") 6437 refine-stmt = refine-keyword sep refine-arg-str optsep 6438 (";" / 6439 "{" stmtsep 6440 (refine-container-stmts / 6441 refine-leaf-stmts / 6442 refine-leaf-list-stmts / 6443 refine-list-stmts / 6444 refine-choice-stmts / 6445 refine-case-stmts / 6446 refine-anyxml-stmts) 6447 "}") 6449 refine-arg-str = < a string which matches the rule 6450 refine-arg > 6452 refine-arg = descendant-schema-nodeid 6454 refine-container-stmts = 6455 ;; these stmts can appear in any order 6456 *(must-stmt stmtsep) 6457 [presence-stmt stmtsep] 6458 [config-stmt stmtsep] 6459 [description-stmt stmtsep] 6460 [reference-stmt stmtsep] 6462 refine-leaf-stmts = ;; these stmts can appear in any order 6463 *(must-stmt stmtsep) 6464 [default-stmt stmtsep] 6465 [config-stmt stmtsep] 6466 [mandatory-stmt stmtsep] 6467 [description-stmt stmtsep] 6468 [reference-stmt stmtsep] 6470 refine-leaf-list-stmts = 6471 ;; these stmts can appear in any order 6472 *(must-stmt stmtsep) 6474 [config-stmt stmtsep] 6475 [min-elements-stmt stmtsep] 6476 [max-elements-stmt stmtsep] 6477 [description-stmt stmtsep] 6478 [reference-stmt stmtsep] 6480 refine-list-stmts = ;; these stmts can appear in any order 6481 *(must-stmt stmtsep) 6482 [config-stmt stmtsep] 6483 [min-elements-stmt stmtsep] 6484 [max-elements-stmt stmtsep] 6485 [description-stmt stmtsep] 6486 [reference-stmt stmtsep] 6488 refine-choice-stmts = ;; these stmts can appear in any order 6489 [default-stmt stmtsep] 6490 [config-stmt stmtsep] 6491 [mandatory-stmt stmtsep] 6492 [description-stmt stmtsep] 6493 [reference-stmt stmtsep] 6495 refine-case-stmts = ;; these stmts can appear in any order 6496 [description-stmt stmtsep] 6497 [reference-stmt stmtsep] 6499 refine-anyxml-stmts = ;; these stmts can appear in any order 6500 [config-stmt stmtsep] 6501 [mandatory-stmt stmtsep] 6502 [description-stmt stmtsep] 6503 [reference-stmt stmtsep] 6505 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 6506 "{" stmtsep 6507 ;; these stmts can appear in any order 6508 [when-stmt stmtsep] 6509 *(if-feature-stmt stmtsep) 6510 [status-stmt stmtsep] 6511 [description-stmt stmtsep] 6512 [reference-stmt stmtsep] 6513 1*((data-def-stmt stmtsep) / 6514 (case-stmt stmtsep)) 6515 "}" 6517 uses-augment-arg-str = < a string which matches the rule 6518 uses-augment-arg > 6520 uses-augment-arg = descendant-schema-nodeid 6521 augment-stmt = augment-keyword sep augment-arg-str optsep 6522 "{" stmtsep 6523 ;; these stmts can appear in any order 6524 [when-stmt stmtsep] 6525 *(if-feature-stmt stmtsep) 6526 [status-stmt stmtsep] 6527 [description-stmt stmtsep] 6528 [reference-stmt stmtsep] 6529 1*((data-def-stmt stmtsep) / 6530 (case-stmt stmtsep)) 6531 "}" 6533 augment-arg-str = < a string which matches the rule 6534 augment-arg > 6536 augment-arg = schema-nodeid 6538 unknown-statement = prefix ":" identifier [sep string] optsep 6539 (";" / "{" *unknown-statement "}") 6541 when-stmt = when-keyword sep string stmtend 6543 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 6544 (";" / 6545 "{" stmtsep 6546 ;; these stmts can appear in any order 6547 *(if-feature-stmt stmtsep) 6548 [status-stmt stmtsep] 6549 [description-stmt stmtsep] 6550 [reference-stmt stmtsep] 6551 *((typedef-stmt / 6552 grouping-stmt) stmtsep) 6553 [input-stmt stmtsep] 6554 [output-stmt stmtsep] 6555 "}") 6557 input-stmt = input-keyword optsep 6558 "{" stmtsep 6559 ;; these stmts can appear in any order 6560 *((typedef-stmt / 6561 grouping-stmt) stmtsep) 6562 1*(data-def-stmt stmtsep) 6563 "}" 6565 output-stmt = output-keyword optsep 6566 "{" stmtsep 6567 ;; these stmts can appear in any order 6568 *((typedef-stmt / 6569 grouping-stmt) stmtsep) 6570 1*(data-def-stmt stmtsep) 6571 "}" 6573 notification-stmt = notification-keyword sep 6574 identifier-arg-str optsep 6575 (";" / 6576 "{" stmtsep 6577 ;; these stmts can appear in any order 6578 *(if-feature-stmt stmtsep) 6579 [status-stmt stmtsep] 6580 [description-stmt stmtsep] 6581 [reference-stmt stmtsep] 6582 *((typedef-stmt / 6583 grouping-stmt) stmtsep) 6584 *(data-def-stmt stmtsep) 6585 "}") 6587 deviation-stmt = deviation-keyword sep 6588 deviation-arg-str optsep 6589 "{" stmtsep 6590 ;; these stmts can appear in any order 6591 [description-stmt stmtsep] 6592 [reference-stmt stmtsep] 6593 (deviate-not-supported-stmt / 6594 1*(deviate-add-stmt / 6595 deviate-replace-stmt / 6596 deviate-delete-stmt)) 6597 "}" 6599 deviation-arg-str = < a string which matches the rule 6600 deviation-arg > 6602 deviation-arg = absolute-schema-nodeid 6604 deviate-not-supported-stmt = 6605 deviate-keyword sep 6606 not-supported-keyword optsep 6607 (";" / 6608 "{" stmtsep 6609 "}") 6611 deviate-add-stmt = deviate-keyword sep add-keyword optsep 6612 (";" / 6613 "{" stmtsep 6614 [units-stmt stmtsep] 6615 *(must-stmt stmtsep) 6616 *(unique-stmt stmtsep) 6618 [default-stmt stmtsep] 6619 [config-stmt stmtsep] 6620 [mandatory-stmt stmtsep] 6621 [min-elements-stmt stmtsep] 6622 [max-elements-stmt stmtsep] 6623 "}") 6625 deviate-delete-stmt = deviate-keyword sep delete-keyword optsep 6626 (";" / 6627 "{" stmtsep 6628 [units-stmt stmtsep] 6629 *(must-stmt stmtsep) 6630 *(unique-stmt stmtsep) 6631 [default-stmt stmtsep] 6632 "}") 6634 deviate-replace-stmt = deviate-keyword sep replace-keyword optsep 6635 (";" / 6636 "{" stmtsep 6637 [type-stmt stmtsep] 6638 [units-stmt stmtsep] 6639 [default-stmt stmtsep] 6640 [config-stmt stmtsep] 6641 [mandatory-stmt stmtsep] 6642 [min-elements-stmt stmtsep] 6643 [max-elements-stmt stmtsep] 6644 "}") 6646 ;; Ranges 6648 range-arg-str = < a string which matches the rule 6649 range-arg > 6651 range-arg = range-part *(optsep "|" optsep range-part) 6653 range-part = range-boundary 6654 [optsep ".." optsep range-boundary] 6656 range-boundary = min-keyword / max-keyword / 6657 integer-value / decimal-value 6659 ;; Lengths 6661 length-arg-str = < a string which matches the rule 6662 length-arg > 6664 length-arg = length-part *(optsep "|" optsep length-part) 6665 length-part = length-boundary 6666 [optsep ".." optsep length-boundary] 6668 length-boundary = min-keyword / max-keyword / 6669 non-negative-integer-value 6671 ;; Date 6673 date-arg-str = < a string which matches the rule 6674 date-arg > 6676 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 6678 ;; Schema Node Identifiers 6680 schema-nodeid = absolute-schema-nodeid / 6681 descendant-schema-nodeid 6683 absolute-schema-nodeid = 1*("/" node-identifier) 6685 descendant-schema-nodeid = 6686 node-identifier 6687 absolute-schema-nodeid 6689 node-identifier = [prefix ":"] identifier 6691 ;; Instance Identifiers 6693 instance-identifier = 1*("/" (node-identifier *predicate)) 6695 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 6697 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 6698 ((DQUOTE string DQUOTE) / 6699 (SQUOTE string SQUOTE)) 6701 pos = non-negative-integer-value 6703 ;; leafref path 6705 path-arg-str = < a string which matches the rule 6706 path-arg > 6708 path-arg = absolute-path / relative-path 6710 absolute-path = 1*("/" (node-identifier *path-predicate)) 6711 relative-path = 1*(".." "/") descendant-path 6713 descendant-path = node-identifier 6714 [*path-predicate absolute-path] 6716 path-predicate = "[" *WSP path-equality-expr *WSP "]" 6718 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 6720 path-key-expr = current-function-invocation *WSP "/" *WSP 6721 rel-path-keyexpr 6723 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 6724 *(node-identifier *WSP "/" *WSP) 6725 node-identifier 6727 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 6729 ;; statment keywords 6730 anyxml-keyword = 'anyxml' 6731 argument-keyword = 'argument' 6732 augment-keyword = 'augment' 6733 base-keyword = 'base' 6734 belongs-to-keyword = 'belongs-to' 6735 bit-keyword = 'bit' 6736 case-keyword = 'case' 6737 choice-keyword = 'choice' 6738 config-keyword = 'config' 6739 contact-keyword = 'contact' 6740 container-keyword = 'container' 6741 default-keyword = 'default' 6742 description-keyword = 'description' 6743 enum-keyword = 'enum' 6744 error-app-tag-keyword = 'error-app-tag' 6745 error-message-keyword = 'error-message' 6746 extension-keyword = 'extension' 6747 deviation-keyword = 'deviation' 6748 deviate-keyword = 'deviate' 6749 feature-keyword = 'feature' 6750 fraction-digits-keyword = 'fraction-digits' 6751 grouping-keyword = 'grouping' 6752 identity-keyword = 'identity' 6753 if-feature-keyword = 'if-feature' 6754 import-keyword = 'import' 6755 include-keyword = 'include' 6756 input-keyword = 'input' 6757 key-keyword = 'key' 6758 leaf-keyword = 'leaf' 6759 leaf-list-keyword = 'leaf-list' 6760 length-keyword = 'length' 6761 list-keyword = 'list' 6762 mandatory-keyword = 'mandatory' 6763 max-elements-keyword = 'max-elements' 6764 min-elements-keyword = 'min-elements' 6765 module-keyword = 'module' 6766 must-keyword = 'must' 6767 namespace-keyword = 'namespace' 6768 notification-keyword= 'notification' 6769 ordered-by-keyword = 'ordered-by' 6770 organization-keyword= 'organization' 6771 output-keyword = 'output' 6772 path-keyword = 'path' 6773 pattern-keyword = 'pattern' 6774 position-keyword = 'position' 6775 prefix-keyword = 'prefix' 6776 presence-keyword = 'presence' 6777 range-keyword = 'range' 6778 reference-keyword = 'reference' 6779 refine-keyword = 'refine' 6780 require-instance-keyword = 'require-instance' 6781 revision-keyword = 'revision' 6782 revision-date-keyword = 'revision-date' 6783 rpc-keyword = 'rpc' 6784 status-keyword = 'status' 6785 submodule-keyword = 'submodule' 6786 type-keyword = 'type' 6787 typedef-keyword = 'typedef' 6788 unique-keyword = 'unique' 6789 units-keyword = 'units' 6790 uses-keyword = 'uses' 6791 value-keyword = 'value' 6792 when-keyword = 'when' 6793 yang-version-keyword= 'yang-version' 6794 yin-element-keyword = 'yin-element' 6796 ;; other keywords 6798 add-keyword = 'add' 6799 current-keyword = 'current' 6800 delete-keyword = 'delete' 6801 deprecated-keyword = 'deprecated' 6802 false-keyword = 'false' 6803 max-keyword = 'max' 6804 min-keyword = 'min' 6805 not-supported-keyword = 'not-supported' 6806 obsolete-keyword = 'obsolete' 6807 replace-keyword = 'replace' 6808 system-keyword = 'system' 6809 true-keyword = 'true' 6810 unbounded-keyword = 'unbounded' 6811 user-keyword = 'user' 6813 current-function-invocation = current-keyword *WSP "(" *WSP ")" 6815 ;; Basic Rules 6817 prefix-arg-str = < a string which matches the rule 6818 prefix-arg > 6820 prefix-arg = prefix 6822 prefix = identifier 6824 identifier-arg-str = < a string which matches the rule 6825 identifier-arg > 6827 identifier-arg = identifier 6829 identifier = (ALPHA / "_") 6830 *(ALPHA / DIGIT / "_" / "-" / ".") 6832 identifier-ref-arg-str = < a string which matches the rule 6833 identifier-ref-arg > 6835 identifier-ref-arg = [prefix ":"] identifier 6837 string = < an unquoted string as returned by 6838 the scanner > 6840 integer-value = ("-" non-negative-integer-value) / 6841 non-negative-integer-value 6843 non-negative-integer-value = "0" / positive-integer-value 6845 positive-integer-value = (non-zero-digit *DIGIT) 6847 zero-integer-value = 1*DIGIT 6849 stmtend = ";" / "{" *unknown-statement "}" 6851 sep = 1*(WSP / line-break) 6852 ; unconditional separator 6854 optsep = *(WSP / line-break) 6855 stmtsep = *(WSP / line-break / unknown-statement) 6857 line-break = CRLF / LF 6859 non-zero-digit = %x31-39 6861 decimal-value = integer-value ("." zero-integer-value) 6863 SQUOTE = %x27 6864 ; ' (Single Quote) 6866 ;; 6867 ;; RFC 4234 core rules. 6868 ;; 6870 ALPHA = %x41-5A / %x61-7A 6871 ; A-Z / a-z 6873 CR = %x0D 6874 ; carriage return 6876 CRLF = CR LF 6877 ; Internet standard newline 6879 DIGIT = %x30-39 6880 ; 0-9 6882 DQUOTE = %x22 6883 ; " (Double Quote) 6885 HEXDIG = DIGIT / 6886 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 6887 ; only lower-case a..f 6889 HTAB = %x09 6890 ; horizontal tab 6892 LF = %x0A 6893 ; linefeed 6895 SP = %x20 6896 ; space 6898 VCHAR = %x21-7E 6899 ; visible (printing) characters 6901 WSP = SP / HTAB 6902 ; white space 6904 13. Error Responses for YANG Related Errors 6906 A number of NETCONF error responses are defined for error cases 6907 related to the data-model handling. If the relevant YANG statement 6908 has an "error-app-tag" substatement, that overrides the default value 6909 specified below. 6911 13.1. Error Message for Data that Violates a unique Statement: 6913 If a NETCONF operation would result in configuration data where a 6914 unique constraint is invalidated, the following error is returned: 6916 Tag: operation-failed 6917 Error-app-tag: data-not-unique 6918 Error-info: : Contains an instance identifier which 6919 points to a leaf which invalidates the unique 6920 constraint. This element is present once for each 6921 leaf invalidating the unique constraint. 6923 The element is in the YANG 6924 namespace ("urn:ietf:params:xml:ns:yang:1"). 6926 13.2. Error Message for Data that Violates a max-elements Statement: 6928 If a NETCONF operation would result in configuration data where a 6929 list or a leaf-list would have too many entries the following error 6930 is returned: 6932 Tag: operation-failed 6933 Error-app-tag: too-many-elements 6935 This error is returned once, with the error-path identifying the list 6936 node, even if there are more than one extra child present. 6938 13.3. Error Message for Data that Violates a min-elements Statement: 6940 If a NETCONF operation would result in configuration data where a 6941 list or a leaf-list would have too few entries the following error is 6942 returned: 6944 Tag: operation-failed 6945 Error-app-tag: too-few-elements 6947 This error is returned once, with the error-path identifying the list 6948 node, even if there are more than one child missing. 6950 13.4. Error Message for Data that Violates a must statement: 6952 If a NETCONF operation would result in configuration data where the 6953 restrictions imposed by a "must" statement is violated the following 6954 error is returned, unless a specific "error-app-tag" substatement is 6955 present for the "must" statement. 6957 Tag: operation-failed 6958 Error-app-tag: must-violation 6960 13.5. Error Message for Data that Violates a require-instance 6961 statement: 6963 If a NETCONF operation would result in configuration data where an 6964 instance reference marked with require-instance "true" refers to a 6965 non-existing instance, the following error is returned: 6967 Tag: data-missing 6968 Error-app-tag: instance-required 6969 Error-path: Path to the element with the require-instance 6970 statement 6972 13.6. Error Message for Data that Violates a mandatory choice 6973 statement: 6975 If a NETCONF operation would result in configuration data where no 6976 nodes exists in a mandatory choice, the following error is returned: 6978 Tag: data-missing 6979 Error-app-tag: missing-choice 6980 Error-path: Path to the element with the missing choice. 6981 Error-info: : Contains the name of the missing 6982 mandatory choice. 6984 The element is in the YANG 6985 namespace ("urn:ietf:params:xml:ns:yang:1"). 6987 13.7. Error Message for the "insert" Operation 6989 If the "insert" and "key" or "value" attributes are used in an 6990 for a list or leaf-list node, and the "key" or "value" 6991 refers to a non-existing instance, the following error is returned: 6993 Tag: bad-attribute 6994 Error-app-tag: missing-instance 6996 14. IANA Considerations 6998 This document defines a registry for YANG module and submodule names. 6999 The name of the registry is "YANG Module Names". 7001 The registry shall record for each entry: 7003 o the name of the module or submodule 7005 o for modules, the assigned XML namespace 7007 o for submodules, the name of the module it belongs to 7009 o a reference to the (sub)module's documentation (the RFC number) 7011 For allocation, RFC publication is required as per RFC 5226 7012 [RFC5226]. All registered YANG module names must comply with the 7013 rules for identifiers stated in Section 6.2. There are no initial 7014 assignments. 7016 The module name prefix 'ietf-' is reserved for IETF stream documents 7017 while the module name prefix 'irtf-' is reserved for IRTF stream 7018 documents. Modules published in other RFC streams must have a 7019 similar suitable prefix. The prefix 'iana-' is reserved for modules 7020 maintained by IANA. 7022 This document registers two URIs for the YANG and YIN XML namespaces 7023 in the IETF XML registry [RFC3688]. Following the format in RFC 7024 3688, the following registration is requested. 7026 URI: urn:ietf:params:xml:ns:yang:yin:1 7027 URI: urn:ietf:params:xml:ns:yang:1 7029 Registrant Contact: The IESG. 7031 XML: N/A, the requested URIs are XML namespaces. 7033 15. Security Considerations 7035 This document defines a language with which to write and read 7036 descriptions of management information. The language itself has no 7037 security impact on the Internet. 7039 Data modeled in YANG might contain sensitive information. RPCs or 7040 notifications defined in YANG might transfer sensitive information. 7042 Security issues are related to the usage of data modeled in YANG. 7043 Such issues shall be dealt with in documents describing the data 7044 models and documents about the interfaces used to manipulate the data 7045 e.g. the NETCONF documents. 7047 YANG is dependent upon: 7049 o the security of the transmission infrastructure used to send 7050 sensitive information 7052 o the security of applications which store or release such sensitive 7053 information. 7055 o adequate authentication and access control mechanisms to restrict 7056 the usage of sensitive data. 7058 16. Contributors 7060 The following people all contributed significantly to the initial 7061 YANG draft: 7063 - Andy Bierman (andybierman.com) 7064 - Balazs Lengyel (Ericsson) 7065 - David Partain (Ericsson) 7066 - Juergen Schoenwaelder (Jacobs University Bremen) 7067 - Phil Shafer (Juniper Networks) 7069 17. Acknowledgements 7071 The editor wishes to thank the following individuals, who all 7072 provided helpful comments on various versions of this document: 7073 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 7074 Lhotka, Gerhard Muenz, Tom Petch, Randy Preshun, David Reid, and Bert 7075 Wijnen. 7077 18. References 7079 18.1. Normative References 7081 [ISO.10646] 7082 International Organization for Standardization, 7083 "Information Technology - Universal Multiple-octet coded 7084 Character Set (UCS) - Part 1: Architecture and Basic 7085 Multilingual Plane", ISO Standard 10646-1, May 1993. 7087 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 7088 Requirement Levels", BCP 14, RFC 2119, March 1997. 7090 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 7091 10646", STD 63, RFC 3629, November 2003. 7093 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 7094 January 2004. 7096 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 7097 Resource Identifier (URI): Generic Syntax", STD 66, 7098 RFC 3986, January 2005. 7100 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 7101 Encodings", RFC 4648, October 2006. 7103 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 7104 December 2006. 7106 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 7107 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 7108 May 2008. 7110 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 7111 Specifications: ABNF", STD 68, RFC 5234, January 2008. 7113 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 7114 Notifications", RFC 5277, July 2008. 7116 [XML-NAMES] 7117 Tobin, R., Bray, T., Hollander, D., and A. Layman, 7118 "Namespaces in XML 1.0 (Second Edition)", World Wide Web 7119 Consortium Recommendation REC-xml-names-20060816, 7120 August 2006, 7121 . 7123 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 7124 Version 1.0", World Wide Web Consortium 7125 Recommendation REC-xpath-19991116, November 1999, 7126 . 7128 [XSD-TYPES] 7129 Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes 7130 Second Edition", W3C REC REC-xmlschema-2-20041028, 7131 October 2004. 7133 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 7134 Wide Web Consortium Recommendation REC-xslt-19991116, 7135 November 1999, 7136 . 7138 18.2. Non-Normative References 7140 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7141 Schoenwaelder, Ed., "Structure of Management Information 7142 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 7144 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 7145 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 7146 STD 58, RFC 2579, April 1999. 7148 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 7149 Structure of Management Information", RFC 3780, May 2004. 7151 Appendix A. ChangeLog 7153 A.1. Version -05 7155 o Replaced the data types "float32" and "float64" with "decimal64". 7157 o Specified that the elements in the XML encoding of configuration 7158 data can occur in any order. 7160 o Clarified that "augment" cannot add multiple nodes with the same 7161 name. 7163 o Clarified what "when" means in RPC input / output. 7165 o Wrote the IANA Considerations section. 7167 o Changed requirement for minimum identifier length to 64 7168 characters. 7170 A.2. Version -04 7172 o Using "revision-date" substatement to "import" and "include". 7174 o Corrected grammar and text for instance-identifier. 7176 o Fixed bugs in some examples. 7178 o Rewrote the YIN description to use a declarative style. 7180 o Added two error codes in Section 13. 7182 o Clarified that YANG uses the same XPath data model as XSLT. 7184 o Specified which errors are generated in Section 8.3.1. 7186 o Corrected grammar for key-arg; now allowing optional prefix on 7187 each leaf identifier. 7189 o Clarified that "unique" constraints only check instances with 7190 values for all referenced leafs. 7192 o Clarified how mandatory and min-elements constraints are enforced. 7194 o Editorial fixes. 7196 A.3. Version -03 7198 o Added import by revision (yang-00413) 7200 o Changed type "keyref" to "leafref", and added the statement 7201 "require-instance" (yang-01253) 7203 o Clarified that data sent from the server must be in the canonical 7204 form. 7206 o Clarified when and how constraints in the models are enforced. 7208 o Many editorial fixes 7210 o Added more strict grammar for the "deviate" statement. 7212 A.4. Version -02 7214 o Added module update rules. (yang-00000) 7216 o Added "refine" statement as a substatement to "uses". (yang-00088) 7218 o Allow "augment" on top-level and in "uses" only. (yang-00088) 7220 o Allow "when" on all data defintion statements. (yang-00088) 7222 o Added section "Constraints" and clarified when constraints are 7223 enforced. (yang-00172) 7225 o Added "feature" and "if-feature" statements. (yang-00750) 7227 o Added "prefix" as a substatement to "belongs-to". (yang-00755) 7229 o Added section on Conformance. (yang-01281) 7231 o Added "deviation" statement. (yang-01281) 7233 o Added "identity" statement and "identityref" type. (yang-01339) 7235 o Aligned grammar for "enum" with text. 7237 A.5. Version -01 7239 o Removed "Appendix A. Derived YANG Types". 7241 o Removed "Appendix C. XML Schema Considerations". 7243 o Removed "Appendix F. Why We Need a New Modeling Language". 7245 o Moved "Appendix B. YIN" to its own section. 7247 o Moved "Appendix D. YANG ABNF Grammar" to its own section. 7249 o Moved "Appendix E. Error Responses for YANG Related Errors" into 7250 its own section. 7252 o The "input" and "output" nodes are now implicitly created by the 7253 "rpc" statement, in order for augmentation of these nodes to work 7254 correctly. 7256 o Allow "config" in "choice". 7258 o Added reference to XPath 1.0. 7260 o Using an XPath function "current()" instead of the variable 7261 "$this". 7263 o Clarified that a "must" expression in a configuration node must 7264 not reference non-configuration nodes. 7266 o Added XML encoding rules and usage examples for rpc and 7267 notification. 7269 o Removed requirement that refinements are specified in the same 7270 order as in the original grouping's definition. 7272 o Fixed whitespace issues in the ABNF grammar. 7274 o Added the term "mandatory node", and refer to it in the 7275 description of augment (see Section 7.15), and choice (see 7276 Section 7.9.3). 7278 o Added support for multiple "pattern" statements in "type". 7280 o Several clarifications and fixed typos. 7282 A.6. Version -00 7284 Changes from draft-bjorklund-netconf-yang-02.txt 7286 o Fixed bug in grammar for bit-stmt 7288 o Fixed bugs in example XPath expressions 7289 o Added keyword 'presence' to the YIN mapping table 7291 Author's Address 7293 Martin Bjorklund (editor) 7294 Tail-f Systems 7296 Email: mbj@tail-f.com