idnits 2.17.1 draft-ietf-netmod-rfc6020bis-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: When an existing enumeration type is restricted, the set of assigned names in the new type MUST be a subset of the base type's set of assigned names. The value of such an assigned name MUST not be changed. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 9, 2015) is 3329 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 6363 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Obsoletes: 6020 (if approved) March 9, 2015 5 Intended status: Standards Track 6 Expires: September 10, 2015 8 YANG - A Data Modeling Language for the Network Configuration Protocol 9 (NETCONF) 10 draft-ietf-netmod-rfc6020bis-04 12 Abstract 14 YANG is a data modeling language used to model configuration and 15 state data manipulated by the Network Configuration Protocol 16 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 17 This document obsoletes RFC 6020. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 10, 2015. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 66 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 67 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 12 70 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 71 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 72 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 73 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 74 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 75 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19 76 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 19 77 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 78 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 79 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 80 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23 81 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 24 82 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25 83 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 26 84 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 26 85 5.1.1. Import and Include by Revision . . . . . . . . . . . 27 86 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28 87 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29 88 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30 89 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30 90 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30 91 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30 92 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31 93 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 32 94 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32 95 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 96 5.6.4. Announcing Conformance Information in the 97 Message . . . . . . . . . . . . . . . . . . . . . . . 33 98 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 33 99 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 34 100 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 34 101 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 34 102 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 34 103 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 34 104 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 36 105 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 36 106 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 37 107 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 37 108 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 38 109 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 38 110 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 40 111 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40 112 7.1. The module Statement . . . . . . . . . . . . . . . . . . 41 113 7.1.1. The module's Substatements . . . . . . . . . . . . . 42 114 7.1.2. The yang-version Statement . . . . . . . . . . . . . 43 115 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 44 116 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 44 117 7.1.5. The import Statement . . . . . . . . . . . . . . . . 44 118 7.1.6. The include Statement . . . . . . . . . . . . . . . . 45 119 7.1.7. The organization Statement . . . . . . . . . . . . . 46 120 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 46 121 7.1.9. The revision Statement . . . . . . . . . . . . . . . 46 122 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 47 123 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 48 124 7.2.1. The submodule's Substatements . . . . . . . . . . . . 49 125 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 50 126 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 51 127 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 51 128 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 52 129 7.3.2. The typedef's type Statement . . . . . . . . . . . . 52 130 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 52 131 7.3.4. The typedef's default Statement . . . . . . . . . . . 52 132 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 53 133 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 53 134 7.4.1. The type's Substatements . . . . . . . . . . . . . . 53 135 7.5. The container Statement . . . . . . . . . . . . . . . . . 53 136 7.5.1. Containers with Presence . . . . . . . . . . . . . . 54 137 7.5.2. The container's Substatements . . . . . . . . . . . . 54 138 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 55 139 7.5.4. The must's Substatements . . . . . . . . . . . . . . 56 140 7.5.5. The presence Statement . . . . . . . . . . . . . . . 57 141 7.5.6. The container's Child Node Statements . . . . . . . . 57 142 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 57 143 7.5.8. NETCONF Operations . . . . . . . . . . 58 144 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 58 145 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 146 7.6.1. The leaf's default value . . . . . . . . . . . . . . 60 147 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 60 148 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 61 149 7.6.4. The leaf's default Statement . . . . . . . . . . . . 61 150 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 61 151 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 152 7.6.7. NETCONF Operations . . . . . . . . . . 62 153 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 62 154 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 63 155 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 63 156 7.7.2. The leaf-list's default values . . . . . . . . . . . 64 157 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 65 158 7.7.4. The leaf-list's default Statement . . . . . . . . . . 65 159 7.7.5. The min-elements Statement . . . . . . . . . . . . . 65 160 7.7.6. The max-elements Statement . . . . . . . . . . . . . 66 161 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 66 162 7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 67 163 7.7.9. NETCONF Operations . . . . . . . . . . 67 164 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 68 165 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 70 166 7.8.1. The list's Substatements . . . . . . . . . . . . . . 70 167 7.8.2. The list's key Statement . . . . . . . . . . . . . . 71 168 7.8.3. The list's unique Statement . . . . . . . . . . . . . 72 169 7.8.4. The list's Child Node Statements . . . . . . . . . . 73 170 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 73 171 7.8.6. NETCONF Operations . . . . . . . . . . 74 172 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 75 173 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 78 174 7.9.1. The choice's Substatements . . . . . . . . . . . . . 78 175 7.9.2. The choice's case Statement . . . . . . . . . . . . . 79 176 7.9.3. The choice's default Statement . . . . . . . . . . . 80 177 7.9.4. The choice's mandatory Statement . . . . . . . . . . 82 178 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 179 7.9.6. NETCONF Operations . . . . . . . . . . 82 180 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 82 181 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 83 182 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 84 183 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 84 184 7.10.3. NETCONF Operations . . . . . . . . . . 84 185 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 85 186 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 85 187 7.11.1. The grouping's Substatements . . . . . . . . . . . . 86 188 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . 86 189 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 87 190 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 87 191 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 87 192 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 88 193 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 88 194 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 90 195 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . 90 196 7.13.2. The input Statement . . . . . . . . . . . . . . . . 90 197 7.13.3. The output Statement . . . . . . . . . . . . . . . . 91 198 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 92 199 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . 93 200 7.14. The action Statement . . . . . . . . . . . . . . . . . . 93 201 7.14.1. The action's Substatements . . . . . . . . . . . . . 94 202 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 94 203 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . 95 204 7.15. The notification Statement . . . . . . . . . . . . . . . 96 205 7.15.1. The notification's Substatements . . . . . . . . . . 97 206 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 97 207 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 97 208 7.16. The augment Statement . . . . . . . . . . . . . . . . . . 98 209 7.16.1. The augment's Substatements . . . . . . . . . . . . 99 210 7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 99 211 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 99 212 7.17. The identity Statement . . . . . . . . . . . . . . . . . 101 213 7.17.1. The identity's Substatements . . . . . . . . . . . . 101 214 7.17.2. The base Statement . . . . . . . . . . . . . . . . . 102 215 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 102 216 7.18. The extension Statement . . . . . . . . . . . . . . . . . 103 217 7.18.1. The extension's Substatements . . . . . . . . . . . 104 218 7.18.2. The argument Statement . . . . . . . . . . . . . . . 104 219 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 105 220 7.19. Conformance-Related Statements . . . . . . . . . . . . . 105 221 7.19.1. The feature Statement . . . . . . . . . . . . . . . 105 222 7.19.2. The if-feature Statement . . . . . . . . . . . . . . 107 223 7.19.3. The deviation Statement . . . . . . . . . . . . . . 108 224 7.20. Common Statements . . . . . . . . . . . . . . . . . . . . 110 225 7.20.1. The config Statement . . . . . . . . . . . . . . . . 110 226 7.20.2. The status Statement . . . . . . . . . . . . . . . . 111 227 7.20.3. The description Statement . . . . . . . . . . . . . 112 228 7.20.4. The reference Statement . . . . . . . . . . . . . . 112 229 7.20.5. The when Statement . . . . . . . . . . . . . . . . . 112 230 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 113 231 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 113 232 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 114 233 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 114 234 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 114 235 8.3.2. NETCONF Processing . . . . . . . . . . 115 236 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 116 237 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 116 238 9.1. Canonical Representation . . . . . . . . . . . . . . . . 116 239 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 117 240 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 117 241 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 242 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 243 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 118 244 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 245 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 119 246 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 120 247 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 248 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 249 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 120 250 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 251 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 121 252 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 121 253 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 254 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 255 9.4.4. The length Statement . . . . . . . . . . . . . . . . 122 256 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 123 257 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 123 258 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 123 259 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 124 260 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 125 261 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 262 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 263 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 125 264 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 125 265 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 266 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 267 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 125 268 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 269 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 128 270 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 128 271 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 128 272 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 128 273 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 128 274 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 275 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 130 276 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 130 277 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 130 278 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 130 279 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 130 280 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 281 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 131 282 9.9.3. The require-instance Statement . . . . . . . . . . . 131 283 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 132 284 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 132 285 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 132 286 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 136 287 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 288 9.10.2. The identityref's base Statement . . . . . . . . . . 136 289 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 136 290 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 137 291 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 137 292 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 138 293 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 138 294 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 138 295 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 138 296 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 138 297 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 139 298 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 139 299 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 139 300 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 139 301 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 139 302 9.13. The instance-identifier Built-In Type . . . . . . . . . . 140 303 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 141 304 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 141 305 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 141 306 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 141 307 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 142 308 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 142 309 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 142 310 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 142 311 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 142 312 10.3. Functions for the YANG Types "leafref" and "instance- 313 identifier" . . . . . . . . . . . . . . . . . . . . . . 143 314 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 143 315 10.4. Functions for the YANG Type "identityref" . . . . . . . 144 316 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 144 317 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 144 318 10.5. Functions for the YANG Type "enumeration" . . . . . . . 145 319 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 145 320 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 146 321 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 146 322 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 147 323 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 324 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 150 325 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 152 326 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 153 327 14. Error Responses for YANG Related Errors . . . . . . . . . . . 177 328 14.1. Error Message for Data That Violates a unique Statement 177 329 14.2. Error Message for Data That Violates a max-elements 330 Statement . . . . . . . . . . . . . . . . . . . . . . . 177 331 14.3. Error Message for Data That Violates a min-elements 332 Statement . . . . . . . . . . . . . . . . . . . . . . . 177 333 14.4. Error Message for Data That Violates a must Statement . 178 334 14.5. Error Message for Data That Violates a require-instance 335 Statement . . . . . . . . . . . . . . . . . . . . . . . 178 337 14.6. Error Message for Data That Does Not Match a leafref 338 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 178 339 14.7. Error Message for Data That Violates a mandatory choice 340 Statement . . . . . . . . . . . . . . . . . . . . . . . 178 341 14.8. Error Message for the "insert" Operation . . . . . . . . 179 342 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 179 343 15.1. Media type application/yang . . . . . . . . . . . . . . 180 344 15.2. Media type application/yin+xml . . . . . . . . . . . . . 181 345 16. Security Considerations . . . . . . . . . . . . . . . . . . . 183 346 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 183 347 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 184 348 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 184 349 19.1. Version -04 . . . . . . . . . . . . . . . . . . . . . . 184 350 19.2. Version -03 . . . . . . . . . . . . . . . . . . . . . . 184 351 19.3. Version -02 . . . . . . . . . . . . . . . . . . . . . . 184 352 19.4. Version -01 . . . . . . . . . . . . . . . . . . . . . . 185 353 19.5. Version -00 . . . . . . . . . . . . . . . . . . . . . . 185 354 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 185 355 20.1. Normative References . . . . . . . . . . . . . . . . . . 185 356 20.2. Informative References . . . . . . . . . . . . . . . . . 187 357 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 187 359 1. Introduction 361 YANG is a data modeling language used to model configuration and 362 state data manipulated by the Network Configuration Protocol 363 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 364 YANG is used to model the operations and content layers of NETCONF 365 (see the NETCONF Configuration Protocol [RFC6241], Section 1.2). 367 This document describes the syntax and semantics of the YANG 368 language, how the data model defined in a YANG module is represented 369 in the Extensible Markup Language (XML), and how NETCONF operations 370 are used to manipulate the data. 372 1.1. Summary of Changes from RFC 6020 374 This document defines version 1.1 of the YANG language. YANG version 375 1.1 is a maintenance release of the YANG language, addressing 376 ambiguities and defects in the original specification [RFC6020]. 378 o Changed the YANG version from "1" to "1.1". 380 o Made noncharacters illegal in the built-in type "string". 382 o Defined the legal characters in YANG modules. 384 o Made the "yang-version" statement mandatory. 386 o Changed the rules for the interpretation of escaped characters in 387 double quoted strings. This is an backwards incompatible change 388 from YANG 1.0. A module that uses a character sequence that is 389 now illegal must change the string to match the new rules. See 390 Section 6.1.3 for details. 392 o Extended the "if-feature" syntax to be a boolean expression over 393 feature names. 395 o Allow "if-feature" in "bit", "enum", and "identity". 397 o Allow "if-feature" in "refine". 399 o Made "when" and "if-feature" illegal on list keys, unless the 400 parent is also conditional, and the condition matches the parent's 401 condition. 403 o Allow "choice" as a shorthand case statement (see Section 7.9). 405 o Added a new substatement "modifier" to pattern (see 406 Section 9.4.6). 408 o Allow "must" in "input", "output", and "notification". 410 o Added a set of new XPath functions in Section 10. 412 o Clarified the XPath context's tree in Section 6.4.1. 414 o Defined the string value of an identityref in XPath expressions 415 (see Section 9.10). 417 o Clarified what unprefixed names means in leafrefs in typedefs (see 418 Section 9.9.2). 420 o Allow identities to be derived from multiple base identities (see 421 Section 7.17 and Section 9.10). 423 o Allow enumerations to be subtyped (see Section 9.6). 425 o Allow leaf-lists to have default values (see Section 7.7.2). 427 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 429 o Changed the module advertisement mechanism (see Section 5.6.4). 431 o Changed the scoping rules for definitions in submodules. A 432 submodule can now reference all defintions in all submodules that 433 belong to the same module, without using the "include" statement. 435 o Added a new statement "action" that is used to define operations 436 tied to data nodes. 438 2. Keywords 440 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 441 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 442 "OPTIONAL" in this document are to be interpreted as described in BCP 443 14, [RFC2119]. 445 3. Terminology 447 o action: An operation defined for a node in the data tree. 449 o anyxml: A data node that can contain an unknown chunk of XML data. 451 o augment: Adds new schema nodes to a previously defined schema 452 node. 454 o base type: The type from which a derived type was derived, which 455 may be either a built-in type or another derived type. 457 o built-in type: A YANG data type defined in the YANG language, such 458 as uint32 or string. 460 o choice: A schema node where only one of a number of identified 461 alternatives is valid. 463 o configuration data: The set of writable data that is required to 464 transform a system from its initial default state into its current 465 state [RFC6241]. 467 o conformance: A measure of how accurately a device follows a data 468 model. 470 o container: An interior data node that exists in at most one 471 instance in the data tree. A container has no value, but rather a 472 set of child nodes. 474 o data definition statement: A statement that defines new data 475 nodes. One of container, leaf, leaf-list, list, choice, case, 476 augment, uses, and anyxml. 478 o data model: A data model describes how data is represented and 479 accessed. 481 o data node: A node in the schema tree that can be instantiated in a 482 data tree. One of container, leaf, leaf-list, list, and anyxml. 484 o data tree: The instantiated tree of configuration and state data 485 on a device. 487 o derived type: A type that is derived from a built-in type (such as 488 uint32), or another derived type. 490 o device deviation: A failure of the device to implement the module 491 faithfully. 493 o extension: An extension attaches non-YANG semantics to statements. 494 The extension statement defines new statements to express these 495 semantics. 497 o feature: A mechanism for marking a portion of the model as 498 optional. Definitions can be tagged with a feature name and are 499 only valid on devices that support that feature. 501 o grouping: A reusable set of schema nodes, which may be used 502 locally in the module, in modules that include it, and by other 503 modules that import from it. The grouping statement is not a data 504 definition statement and, as such, does not define any nodes in 505 the schema tree. 507 o identifier: Used to identify different kinds of YANG items by 508 name. 510 o instance identifier: A mechanism for identifying a particular node 511 in a data tree. 513 o interior node: Nodes within a hierarchy that are not leaf nodes. 515 o leaf: A data node that exists in at most one instance in the data 516 tree. A leaf has a value but no child nodes. 518 o leaf-list: Like the leaf node but defines a set of uniquely 519 identifiable nodes rather than a single node. Each node has a 520 value but no child nodes. 522 o list: An interior data node that may exist in multiple instances 523 in the data tree. A list has no value, but rather a set of child 524 nodes. 526 o module: A YANG module defines a hierarchy of nodes that can be 527 used for NETCONF-based operations. With its definitions and the 528 definitions it imports or includes from elsewhere, a module is 529 self-contained and "compilable". 531 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 533 o RPC operation: A specific Remote Procedure Call, as used within 534 the NETCONF protocol. It is also called a protocol operation. 536 o schema node: A node in the schema tree. One of container, leaf, 537 leaf-list, list, choice, case, rpc, input, output, notification, 538 and anyxml. 540 o schema node identifier: A mechanism for identifying a particular 541 node in the schema tree. 543 o schema tree: The definition hierarchy specified within a module. 545 o state data: The additional data on a system that is not 546 configuration data such as read-only status information and 547 collected statistics [RFC6241]. 549 o submodule: A partial module definition that contributes derived 550 types, groupings, data nodes, RPCs, and notifications to a module. 551 A YANG module can be constructed from a number of submodules. 553 o top-level data node: A data node where there is no other data node 554 between it and a module or submodule statement. 556 o uses: The "uses" statement is used to instantiate the set of 557 schema nodes defined in a grouping statement. The instantiated 558 nodes may be refined and augmented to tailor them to any specific 559 needs. 561 3.1. Mandatory Nodes 563 A mandatory node is one of: 565 o A leaf, choice, or anyxml node with a "mandatory" statement with 566 the value "true". 568 o A list or leaf-list node with a "min-elements" statement with a 569 value greater than zero. 571 o A container node without a "presence" statement, which has at 572 least one mandatory node as a child. 574 4. YANG Overview 576 4.1. Functional Overview 578 YANG is a language used to model data for the NETCONF protocol. A 579 YANG module defines a hierarchy of data that can be used for NETCONF- 580 based operations, including configuration, state data, Remote 581 Procedure Calls (RPCs), and notifications. This allows a complete 582 description of all data sent between a NETCONF client and server. 584 YANG models the hierarchical organization of data as a tree in which 585 each node has a name, and either a value or a set of child nodes. 586 YANG provides clear and concise descriptions of the nodes, as well as 587 the interaction between those nodes. 589 YANG structures data models into modules and submodules. A module 590 can import data from other external modules, and include data from 591 submodules. The hierarchy can be augmented, allowing one module to 592 add data nodes to the hierarchy defined in another module. This 593 augmentation can be conditional, with new nodes appearing only if 594 certain conditions are met. 596 YANG models can describe constraints to be enforced on the data, 597 restricting the appearance or value of nodes based on the presence or 598 value of other nodes in the hierarchy. These constraints are 599 enforceable by either the client or the server, and valid content 600 MUST abide by them. 602 YANG defines a set of built-in types, and has a type mechanism 603 through which additional types may be defined. Derived types can 604 restrict their base type's set of valid values using mechanisms like 605 range or pattern restrictions that can be enforced by clients or 606 servers. They can also define usage conventions for use of the 607 derived type, such as a string-based type that contains a host name. 609 YANG permits the definition of reusable groupings of nodes. The 610 instantiation of these groupings can refine or augment the nodes, 611 allowing it to tailor the nodes to its particular needs. Derived 612 types and groupings can be defined in one module or submodule and 613 used in either that location or in another module or submodule that 614 imports or includes it. 616 YANG data hierarchy constructs include defining lists where list 617 entries are identified by keys that distinguish them from each other. 618 Such lists may be defined as either sorted by user or automatically 619 sorted by the system. For user-sorted lists, operations are defined 620 for manipulating the order of the list entries. 622 YANG modules can be translated into an equivalent XML syntax called 623 YANG Independent Notation (YIN) (Section 12), allowing applications 624 using XML parsers and Extensible Stylesheet Language Transformations 625 (XSLT) scripts to operate on the models. The conversion from YANG to 626 YIN is lossless, so content in YIN can be round-tripped back into 627 YANG. 629 YANG strikes a balance between high-level data modeling and low-level 630 bits-on-the-wire encoding. The reader of a YANG module can see the 631 high-level view of the data model while understanding how the data 632 will be encoded in NETCONF operations. 634 YANG is an extensible language, allowing extension statements to be 635 defined by standards bodies, vendors, and individuals. The statement 636 syntax allows these extensions to coexist with standard YANG 637 statements in a natural way, while extensions in a YANG module stand 638 out sufficiently for the reader to notice them. 640 YANG resists the tendency to solve all possible problems, limiting 641 the problem space to allow expression of NETCONF data models, not 642 arbitrary XML documents or arbitrary data models. The data models 643 described by YANG are designed to be easily operated upon by NETCONF 644 operations. 646 To the extent possible, YANG maintains compatibility with Simple 647 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 648 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 649 can be automatically translated into YANG modules for read-only 650 access. However, YANG is not concerned with reverse translation from 651 YANG to SMIv2. 653 Like NETCONF, YANG targets smooth integration with the device's 654 native management infrastructure. This allows implementations to 655 leverage their existing access control mechanisms to protect or 656 expose elements of the data model. 658 4.2. Language Overview 660 This section introduces some important constructs used in YANG that 661 will aid in the understanding of the language specifics in later 662 sections. This progressive approach handles the inter-related nature 663 of YANG concepts and statements. A detailed description of YANG 664 statements and syntax begins in Section 7. 666 4.2.1. Modules and Submodules 668 A module contains three types of statements: module-header 669 statements, revision statements, and definition statements. The 670 module header statements describe the module and give information 671 about the module itself, the revision statements give information 672 about the history of the module, and the definition statements are 673 the body of the module where the data model is defined. 675 A NETCONF server may implement a number of modules, allowing multiple 676 views of the same data, or multiple views of disjoint subsections of 677 the device's data. Alternatively, the server may implement only one 678 module that defines all available data. 680 A module may be divided into submodules, based on the needs of the 681 module owner. The external view remains that of a single module, 682 regardless of the presence or size of its submodules. 684 The "import" statement allows a module or submodule to reference 685 material defined in other modules. 687 The "include" statement is used by a module to incorporate the 688 contents of its submodules into the module. 690 4.2.2. Data Modeling Basics 692 YANG defines four types of nodes for data modeling. In each of the 693 following subsections, the example shows the YANG syntax as well as a 694 corresponding NETCONF XML representation. 696 4.2.2.1. Leaf Nodes 698 A leaf node contains simple data like an integer or a string. It has 699 exactly one value of a particular type and no child nodes. 701 YANG Example: 703 leaf host-name { 704 type string; 705 description "Hostname for this system"; 706 } 708 NETCONF XML Example: 710 my.example.com 712 The "leaf" statement is covered in Section 7.6. 714 4.2.2.2. Leaf-List Nodes 716 A leaf-list defines a sequence of values of a particular type. 718 YANG Example: 720 leaf-list domain-search { 721 type string; 722 description "List of domain names to search"; 723 } 725 NETCONF XML Example: 727 high.example.com 728 low.example.com 729 everywhere.example.com 731 The "leaf-list" statement is covered in Section 7.7. 733 4.2.2.3. Container Nodes 735 A container node is used to group related nodes in a subtree. A 736 container has only child nodes and no value. A container may contain 737 any number of child nodes of any type (including leafs, lists, 738 containers, and leaf-lists). 740 YANG Example: 742 container system { 743 container login { 744 leaf message { 745 type string; 746 description 747 "Message given at start of login session"; 748 } 749 } 750 } 752 NETCONF XML Example: 754 755 756 Good morning 757 758 760 The "container" statement is covered in Section 7.5. 762 4.2.2.4. List Nodes 764 A list defines a sequence of list entries. Each entry is like a 765 structure or a record instance, and is uniquely identified by the 766 values of its key leafs. A list can define multiple key leafs and 767 may contain any number of child nodes of any type (including leafs, 768 lists, containers etc.). 770 YANG Example: 772 list user { 773 key "name"; 774 leaf name { 775 type string; 776 } 777 leaf full-name { 778 type string; 779 } 780 leaf class { 781 type string; 782 } 783 } 785 NETCONF XML Example: 787 788 glocks 789 Goldie Locks 790 intruder 791 792 793 snowey 794 Snow White 795 free-loader 796 797 798 rzell 799 Rapun Zell 800 tower 801 803 The "list" statement is covered in Section 7.8. 805 4.2.2.5. Example Module 807 These statements are combined to define the module: 809 // Contents of "acme-system.yang" 810 module acme-system { 811 yang-version 1.1; 812 namespace "http://acme.example.com/system"; 813 prefix "acme"; 815 organization "ACME Inc."; 816 contact "joe@acme.example.com"; 817 description 818 "The module for entities implementing the ACME system."; 820 revision 2007-06-09 { 821 description "Initial revision."; 822 } 824 container system { 825 leaf host-name { 826 type string; 827 description "Hostname for this system"; 828 } 830 leaf-list domain-search { 831 type string; 832 description "List of domain names to search"; 833 } 835 container login { 836 leaf message { 837 type string; 838 description 839 "Message given at start of login session"; 840 } 842 list user { 843 key "name"; 844 leaf name { 845 type string; 846 } 847 leaf full-name { 848 type string; 849 } 850 leaf class { 851 type string; 852 } 853 } 854 } 855 } 856 } 858 4.2.3. State Data 860 YANG can model state data, as well as configuration data, based on 861 the "config" statement. When a node is tagged with "config false", 862 its subhierarchy is flagged as state data, to be reported using 863 NETCONF's operation, not the operation. Parent 864 containers, lists, and key leafs are reported also, giving the 865 context for the state data. 867 In this example, two leafs are defined for each interface, a 868 configured speed and an observed speed. The observed speed is not 869 configuration, so it can be returned with NETCONF operations, 870 but not with operations. The observed speed is not 871 configuration data, and it cannot be manipulated using . 873 list interface { 874 key "name"; 876 leaf name { 877 type string; 878 } 879 leaf speed { 880 type enumeration { 881 enum 10m; 882 enum 100m; 883 enum auto; 884 } 885 } 886 leaf observed-speed { 887 type uint32; 888 config false; 889 } 890 } 892 4.2.4. Built-In Types 894 YANG has a set of built-in types, similar to those of many 895 programming languages, but with some differences due to special 896 requirements from the management domain. The following table 897 summarizes the built-in types discussed in Section 9: 899 +---------------------+-------------------------------------+ 900 | Name | Description | 901 +---------------------+-------------------------------------+ 902 | binary | Any binary data | 903 | bits | A set of bits or flags | 904 | boolean | "true" or "false" | 905 | decimal64 | 64-bit signed decimal number | 906 | empty | A leaf that does not have any value | 907 | enumeration | Enumerated strings | 908 | identityref | A reference to an abstract identity | 909 | instance-identifier | References a data tree node | 910 | int8 | 8-bit signed integer | 911 | int16 | 16-bit signed integer | 912 | int32 | 32-bit signed integer | 913 | int64 | 64-bit signed integer | 914 | leafref | A reference to a leaf instance | 915 | string | Human-readable string | 916 | uint8 | 8-bit unsigned integer | 917 | uint16 | 16-bit unsigned integer | 918 | uint32 | 32-bit unsigned integer | 919 | uint64 | 64-bit unsigned integer | 920 | union | Choice of member types | 921 +---------------------+-------------------------------------+ 923 The "type" statement is covered in Section 7.4. 925 4.2.5. Derived Types (typedef) 927 YANG can define derived types from base types using the "typedef" 928 statement. A base type can be either a built-in type or a derived 929 type, allowing a hierarchy of derived types. 931 A derived type can be used as the argument for the "type" statement. 933 YANG Example: 935 typedef percent { 936 type uint8 { 937 range "0 .. 100"; 938 } 939 description "Percentage"; 940 } 942 leaf completed { 943 type percent; 944 } 946 NETCONF XML Example: 948 20 950 The "typedef" statement is covered in Section 7.3. 952 4.2.6. Reusable Node Groups (grouping) 954 Groups of nodes can be assembled into reusable collections using the 955 "grouping" statement. A grouping defines a set of nodes that are 956 instantiated with the "uses" statement: 958 grouping target { 959 leaf address { 960 type inet:ip-address; 961 description "Target IP address"; 962 } 963 leaf port { 964 type inet:port-number; 965 description "Target port number"; 966 } 967 } 969 container peer { 970 container destination { 971 uses target; 972 } 973 } 975 NETCONF XML Example: 977 978 979
192.0.2.1
980 830 981 982 984 The grouping can be refined as it is used, allowing certain 985 statements to be overridden. In this example, the description is 986 refined: 988 container connection { 989 container source { 990 uses target { 991 refine "address" { 992 description "Source IP address"; 993 } 994 refine "port" { 995 description "Source port number"; 996 } 997 } 998 } 999 container destination { 1000 uses target { 1001 refine "address" { 1002 description "Destination IP address"; 1003 } 1004 refine "port" { 1005 description "Destination port number"; 1006 } 1007 } 1008 } 1009 } 1011 The "grouping" statement is covered in Section 7.11. 1013 4.2.7. Choices 1015 YANG allows the data model to segregate incompatible nodes into 1016 distinct choices using the "choice" and "case" statements. The 1017 "choice" statement contains a set of "case" statements that define 1018 sets of schema nodes that cannot appear together. Each "case" may 1019 contain multiple nodes, but each node may appear in only one "case" 1020 under a "choice". 1022 When a node from one case is created in the data tree, all nodes from 1023 all other cases are implicitly deleted. The device handles the 1024 enforcement of the constraint, preventing incompatibilities from 1025 existing in the configuration. 1027 The choice and case nodes appear only in the schema tree, not in the 1028 data tree or NETCONF messages. The additional levels of hierarchy 1029 are not needed beyond the conceptual schema. 1031 YANG Example: 1033 container food { 1034 choice snack { 1035 case sports-arena { 1036 leaf pretzel { 1037 type empty; 1038 } 1039 leaf beer { 1040 type empty; 1041 } 1042 } 1043 case late-night { 1044 leaf chocolate { 1045 type enumeration { 1046 enum dark; 1047 enum milk; 1048 enum first-available; 1049 } 1050 } 1051 } 1052 } 1053 } 1055 NETCONF XML Example: 1057 1058 1059 1060 1062 The "choice" statement is covered in Section 7.9. 1064 4.2.8. Extending Data Models (augment) 1066 YANG allows a module to insert additional nodes into data models, 1067 including both the current module (and its submodules) or an external 1068 module. This is useful for example for vendors to add vendor- 1069 specific parameters to standard data models in an interoperable way. 1071 The "augment" statement defines the location in the data model 1072 hierarchy where new nodes are inserted, and the "when" statement 1073 defines the conditions when the new nodes are valid. 1075 YANG Example: 1077 augment /system/login/user { 1078 when "class != 'wheel'"; 1079 leaf uid { 1080 type uint16 { 1081 range "1000 .. 30000"; 1082 } 1083 } 1084 } 1086 This example defines a "uid" node that only is valid when the user's 1087 "class" is not "wheel". 1089 If a module augments another module, the XML representation of the 1090 data will reflect the prefix of the augmenting module. For example, 1091 if the above augmentation were in a module with prefix "other", the 1092 XML would look like: 1094 NETCONF XML Example: 1096 1097 alicew 1098 Alice N. Wonderland 1099 drop-out 1100 1024 1101 1103 The "augment" statement is covered in Section 7.16. 1105 4.2.9. Operation Definitions 1107 YANG allows the definition of operations. The operations' names, 1108 input parameters, and output parameters are modeled using YANG data 1109 definition statements. Operations on the top-level in a module are 1110 defined with the "rpc" statement. Operations can also be tied to a 1111 node in the data hierarchy. Such operations are defined with the 1112 "action" statement. 1114 YANG Example: 1116 rpc activate-software-image { 1117 input { 1118 leaf image-name { 1119 type string; 1120 } 1121 } 1122 output { 1123 leaf status { 1124 type string; 1125 } 1126 } 1127 } 1129 NETCONF XML Example: 1131 1133 1134 acmefw-2.3 1135 1136 1138 1140 1141 The image acmefw-2.3 is being installed. 1142 1143 1145 The "rpc" statement is covered in Section 7.13, and the "action" 1146 statement in Section 7.14. 1148 4.2.10. Notification Definitions 1150 YANG allows the definition of notifications suitable for NETCONF. 1151 YANG data definition statements are used to model the content of the 1152 notification. 1154 YANG Example: 1156 notification link-failure { 1157 description "A link failure has been detected"; 1158 leaf if-name { 1159 type leafref { 1160 path "/interface/name"; 1161 } 1162 } 1163 leaf if-admin-status { 1164 type admin-status; 1165 } 1166 leaf if-oper-status { 1167 type oper-status; 1168 } 1169 } 1171 NETCONF XML Example: 1173 1175 2007-09-01T10:00:00Z 1176 1177 so-1/2/3.0 1178 up 1179 down 1180 1181 1183 The "notification" statement is covered in Section 7.15. 1185 5. Language Concepts 1187 5.1. Modules and Submodules 1189 The module is the base unit of definition in YANG. A module defines 1190 a single data model. A module can define a complete, cohesive model, 1191 or augment an existing data model with additional nodes. 1193 Submodules are partial modules that contribute definitions to a 1194 module. A module may include any number of submodules, but each 1195 submodule may belong to only one module. 1197 The names of all standard modules and submodules MUST be unique. 1198 Developers of enterprise modules are RECOMMENDED to choose names for 1199 their modules that will have a low probability of colliding with 1200 standard or other enterprise modules, e.g., by using the enterprise 1201 or organization name as a prefix for the module name. 1203 A module uses the "include" statement to include all its submodules, 1204 and the "import" statement to reference external modules. Similarly, 1205 a submodule uses the "import" statement to reference other modules. 1207 For backwards compatibility with YANG version 1, a submodule is 1208 allowed it use the "include" statement to reference other submodules 1209 within its module, but this is not necessary in YANG version 1.1. A 1210 submodule can reference any definition in the module it belongs to 1211 and in all submodules included by the module. 1213 A module or submodule MUST NOT include submodules from other modules, 1214 and a submodule MUST NOT import its own module. 1216 The import and include statements are used to make definitions 1217 available from other modules: 1219 o For a module or submodule to reference definitions in an external 1220 module, the external module MUST be imported. 1222 o A module MUST include all its submodules. 1224 o A module or submodule belonging to that module can reference 1225 definitions in the module and all submodules included by the 1226 module. 1228 There MUST NOT be any circular chains of imports or includes. For 1229 example, if module "a" imports module "b", "b" cannot import "a". 1231 When a definition in an external module is referenced, a locally 1232 defined prefix MUST be used, followed by ":", and then the external 1233 identifier. References to definitions in the local module MAY use 1234 the prefix notation. Since built-in data types do not belong to any 1235 module and have no prefix, references to built-in data types (e.g., 1236 int32) cannot use the prefix notation. The syntax for a reference to 1237 a definition is formally defined by the rule "identifier-ref" in 1238 Section 13. 1240 5.1.1. Import and Include by Revision 1242 Published modules evolve independently over time. In order to allow 1243 for this evolution, modules need to be imported using specific 1244 revisions. When a module is written, it uses the current revisions 1245 of other modules, based on what is available at the time. As future 1246 revisions of the imported modules are published, the importing module 1247 is unaffected and its contents are unchanged. When the author of the 1248 module is prepared to move to the most recently published revision of 1249 an imported module, the module is republished with an updated 1250 "import" statement. By republishing with the new revision, the 1251 authors explicitly indicate their acceptance of any changes in the 1252 imported module. 1254 For submodules, the issue is related but simpler. A module or 1255 submodule that includes submodules needs to specify the revision of 1256 the included submodules. If a submodule changes, any module or 1257 submodule that includes it needs to be updated. 1259 For example, module "b" imports module "a". 1261 module a { 1262 yang-version 1.1; 1263 namespace "http://example.com/a"; 1264 prefix "a"; 1266 revision 2008-01-01 { ... } 1267 grouping a { 1268 leaf eh { .... } 1269 } 1270 } 1272 module b { 1273 yang-version 1.1; 1274 namespace "http://example.com/b"; 1275 prefix "b"; 1277 import a { 1278 prefix p; 1279 revision-date 2008-01-01; 1280 } 1282 container bee { 1283 uses p:a; 1284 } 1285 } 1287 When the author of "a" publishes a new revision, the changes may not 1288 be acceptable to the author of "b". If the new revision is 1289 acceptable, the author of "b" can republish with an updated revision 1290 in the "import" statement. 1292 5.1.2. Module Hierarchies 1294 YANG allows modeling of data in multiple hierarchies, where data may 1295 have more than one top-level node. Models that have multiple top- 1296 level nodes are sometimes convenient, and are supported by YANG. 1298 NETCONF is capable of carrying any XML content as the payload in the 1299 and elements. The top-level nodes of YANG modules 1300 are encoded as child elements, in any order, within these elements. 1301 This encapsulation guarantees that the corresponding NETCONF messages 1302 are always well-formed XML documents. 1304 For example: 1306 module my-config { 1307 yang-version 1.1; 1308 namespace "http://example.com/schema/config"; 1309 prefix "co"; 1311 container system { ... } 1312 container routing { ... } 1313 } 1315 could be encoded in NETCONF as: 1317 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1335 5.2. File Layout 1337 YANG modules and submodules are typically stored in files, one module 1338 or submodule per file. The name of the file SHOULD be of the form: 1340 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1342 YANG compilers can find imported modules and included submodules via 1343 this convention. While the YANG language defines modules, tools may 1344 compile submodules independently for performance and manageability 1345 reasons. Errors and warnings that cannot be detected during 1346 submodule compilation may be delayed until the submodules are linked 1347 into a cohesive module. 1349 5.3. XML Namespaces 1351 All YANG definitions are specified within a module that is bound to a 1352 particular XML namespace [XML-NAMES], which is a globally unique URI 1353 [RFC3986]. A NETCONF client or server uses the namespace during XML 1354 encoding of data. 1356 Namespaces for modules published in RFC streams [RFC4844] MUST be 1357 assigned by IANA, see Section 15. 1359 Namespaces for private modules are assigned by the organization 1360 owning the module without a central registry. Namespace URIs MUST be 1361 chosen so they cannot collide with standard or other enterprise 1362 namespaces, for example by using the enterprise or organization name 1363 in the namespace. 1365 The "namespace" statement is covered in Section 7.1.3. 1367 5.3.1. YANG XML Namespace 1369 YANG defines an XML namespace for NETCONF operations, 1370 content, and the element. The name of this 1371 namespace is "urn:ietf:params:xml:ns:yang:1". 1373 5.4. Resolving Grouping, Type, and Identity Names 1375 Grouping, type, and identity names are resolved in the context in 1376 which they are defined, rather than the context in which they are 1377 used. Users of groupings, typedefs, and identities are not required 1378 to import modules or include submodules to satisfy all references 1379 made by the original definition. This behaves like static scoping in 1380 a conventional programming language. 1382 For example, if a module defines a grouping in which a type is 1383 referenced, when the grouping is used in a second module, the type is 1384 resolved in the context of the original module, not the second 1385 module. There is no worry over conflicts if both modules define the 1386 type, since there is no ambiguity. 1388 5.5. Nested Typedefs and Groupings 1390 Typedefs and groupings may appear nested under many YANG statements, 1391 allowing these to be lexically scoped by the hierarchy under which 1392 they appear. This allows types and groupings to be defined near 1393 where they are used, rather than placing them at the top level of the 1394 hierarchy. The close proximity increases readability. 1396 Scoping also allows types to be defined without concern for naming 1397 conflicts between types in different submodules. Type names can be 1398 specified without adding leading strings designed to prevent name 1399 collisions within large modules. 1401 Finally, scoping allows the module author to keep types and groupings 1402 private to their module or submodule, preventing their reuse. Since 1403 only top-level types and groupings (i.e., those appearing as 1404 substatements to a module or submodule statement) can be used outside 1405 the module or submodule, the developer has more control over what 1406 pieces of their module are presented to the outside world, supporting 1407 the need to hide internal information and maintaining a boundary 1408 between what is shared with the outside world and what is kept 1409 private. 1411 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1412 type or grouping cannot be defined if a higher level in the schema 1413 hierarchy has a definition with a matching identifier. 1415 A reference to an unprefixed type or grouping, or one which uses the 1416 prefix of the current module, is resolved by locating the closest 1417 matching "typedef" or "grouping" statement among the immediate 1418 substatements of each ancestor statement. 1420 5.6. Conformance 1422 Conformance is a measure of how accurately a device follows the 1423 model. Generally speaking, devices are responsible for implementing 1424 the model faithfully, allowing applications to treat devices which 1425 implement the model identically. Deviations from the model can 1426 reduce the utility of the model and increase fragility of 1427 applications that use it. 1429 YANG modelers have three mechanisms for conformance: 1431 o the basic behavior of the model 1433 o optional features that are part of the model 1435 o deviations from the model 1437 We will consider each of these in sequence. 1439 5.6.1. Basic Behavior 1441 The model defines a contract between the NETCONF client and server, 1442 which allows both parties to have faith the other knows the syntax 1443 and semantics behind the modeled data. The strength of YANG lies in 1444 the strength of this contract. 1446 5.6.2. Optional Features 1448 In many models, the modeler will allow sections of the model to be 1449 conditional. The device controls whether these conditional portions 1450 of the model are supported or valid for that particular device. 1452 For example, a syslog data model may choose to include the ability to 1453 save logs locally, but the modeler will realize that this is only 1454 possible if the device has local storage. If there is no local 1455 storage, an application should not tell the device to save logs. 1457 YANG supports this conditional mechanism using a construct called 1458 "feature". Features give the modeler a mechanism for making portions 1459 of the module conditional in a manner that is controlled by the 1460 device. The model can express constructs that are not universally 1461 present in all devices. These features are included in the model 1462 definition, allowing a consistent view and allowing applications to 1463 learn which features are supported and tailor their behavior to the 1464 device. 1466 A module may declare any number of features, identified by simple 1467 strings, and may make portions of the module optional based on those 1468 features. If the device supports a feature, then the corresponding 1469 portions of the module are valid for that device. If the device 1470 doesn't support the feature, those parts of the module are not valid, 1471 and applications should behave accordingly. 1473 Features are defined using the "feature" statement. Definitions in 1474 the module that are conditional to the feature are noted by the 1475 "if-feature" statement. 1477 Further details are available in Section 7.19.1. 1479 5.6.3. Deviations 1481 In an ideal world, all devices would be required to implement the 1482 model exactly as defined, and deviations from the model would not be 1483 allowed. But in the real world, devices are often not able or 1484 designed to implement the model as written. For YANG-based 1485 automation to deal with these device deviations, a mechanism must 1486 exist for devices to inform applications of the specifics of such 1487 deviations. 1489 For example, a BGP module may allow any number of BGP peers, but a 1490 particular device may only support 16 BGP peers. Any application 1491 configuring the 17th peer will receive an error. While an error may 1492 suffice to let the application know it cannot add another peer, it 1493 would be far better if the application had prior knowledge of this 1494 limitation and could prevent the user from starting down the path 1495 that could not succeed. 1497 Device deviations are declared using the "deviation" statement, which 1498 takes as its argument a string that identifies a node in the schema 1499 tree. The contents of the statement details the manner in which the 1500 device implementation deviates from the contract as defined in the 1501 module. 1503 Further details are available in Section 7.19.3. 1505 5.6.4. Announcing Conformance Information in the Message 1507 This document defines the following mechanism for announcing 1508 conformance information. Other mechanisms may be defined by future 1509 specificiations. 1511 A NETCONF server announces the modules it implements by implementing 1512 the YANG module "ietf-yang-library" defined in 1513 [I-D.ietf-netconf-yang-library]. The server also advertises the 1514 following capability in the message (line-breaks and 1515 whitespaces are used for formatting reasons only): 1517 urn:ietf:params:netconf:capability:yang-library:1.0? 1518 module-set-id= 1520 The parameter "module-set-id" has the same value as the leaf 1521 "/modules/module-set-id" from "ietf-yang-library". This parameter 1522 MUST be present. 1524 With this mechanism, a client can cache the supported modules for a 1525 server, and only update the cache if the "module-set-id" value in the 1526 message changes. 1528 5.7. Data Store Modification 1530 Data models may allow the server to alter the configuration data 1531 store in ways not explicitly directed via NETCONF protocol messages. 1532 For example, a data model may define leafs that are assigned system- 1533 generated values when the client does not provide one. A formal 1534 mechanism for specifying the circumstances where these changes are 1535 allowed is out of scope for this specification. 1537 6. YANG Syntax 1539 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1540 languages like C and C++. This C-like syntax was chosen specifically 1541 for its readability, since YANG values the time and effort of the 1542 readers of models above those of modules writers and YANG tool-chain 1543 developers. This section introduces the YANG syntax. 1545 YANG modules use the UTF-8 [RFC3629] character encoding. 1547 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1548 [ISO.10646] characters, including tab, carriage return, and line feed 1549 but excluding the other C0 control characters, the surrogate blocks, 1550 and the noncharacters. The character syntax is formally defined by 1551 the rule "yang-char" in Section 13. 1553 6.1. Lexical Tokenization 1555 YANG modules are parsed as a series of tokens. This section details 1556 the rules for recognizing tokens from an input stream. YANG 1557 tokenization rules are both simple and powerful. The simplicity is 1558 driven by a need to keep the parsers easy to implement, while the 1559 power is driven by the fact that modelers need to express their 1560 models in readable formats. 1562 6.1.1. Comments 1564 Comments are C++ style. A single line comment starts with "//" and 1565 ends at the end of the line. A block comment is enclosed within "/*" 1566 and "*/". 1568 6.1.2. Tokens 1570 A token in YANG is either a keyword, a string, a semicolon (";"), or 1571 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1572 is either one of the YANG keywords defined in this document, or a 1573 prefix identifier, followed by ":", followed by a language extension 1574 keyword. Keywords are case sensitive. See Section 6.2 for a formal 1575 definition of identifiers. 1577 6.1.3. Quoting 1579 If a string contains any space or tab characters, a semicolon (";"), 1580 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1581 it MUST be enclosed within double or single quotes. 1583 If the double-quoted string contains a line break followed by space 1584 or tab characters that are used to indent the text according to the 1585 layout in the YANG file, this leading whitespace is stripped from the 1586 string, up to and including the column of the double quote character, 1587 or to the first non-whitespace character, whichever occurs first. In 1588 this process, a tab character is treated as 8 space characters. 1590 If the double-quoted string contains space or tab characters before a 1591 line break, this trailing whitespace is stripped from the string. 1593 A single-quoted string (enclosed within ' ') preserves each character 1594 within the quotes. A single quote character cannot occur in a 1595 single-quoted string, even when preceded by a backslash. 1597 Within a double-quoted string (enclosed within " "), a backslash 1598 character introduces a special character, which depends on the 1599 character that immediately follows the backslash: 1601 \n new line 1602 \t a tab character 1603 \" a double quote 1604 \\ a single backslash 1606 It is an error if any other character follows the backslash 1607 character. 1609 If a quoted string is followed by a plus character ("+"), followed by 1610 another quoted string, the two strings are concatenated into one 1611 string, allowing multiple concatenations to build one string. 1612 Whitespace trimming and substitution of backslash-escaped characters 1613 in double-quoted strings is done before concatenation. 1615 6.1.3.1. Quoting Examples 1617 The following strings are equivalent: 1619 hello 1620 "hello" 1621 'hello' 1622 "hel" + "lo" 1623 'hel' + "lo" 1625 The following examples show some special strings: 1627 "\"" - string containing a double quote 1628 '"' - string containing a double quote 1629 "\n" - string containing a new line character 1630 '\n' - string containing a backslash followed 1631 by the character n 1633 The following examples show some illegal strings: 1635 '''' - a single-quoted string cannot contain single quotes 1636 """ - a double quote must be escaped in a double-quoted string 1638 The following strings are equivalent: 1640 "first line 1641 second line" 1643 "first line\n" + " second line" 1645 6.2. Identifiers 1647 Identifiers are used to identify different kinds of YANG items by 1648 name. Each identifier starts with an uppercase or lowercase ASCII 1649 letter or an underscore character, followed by zero or more ASCII 1650 letters, digits, underscore characters, hyphens, and dots. 1651 Implementations MUST support identifiers up to 64 characters in 1652 length. Identifiers are case sensitive. The identifier syntax is 1653 formally defined by the rule "identifier" in Section 13. Identifiers 1654 can be specified as quoted or unquoted strings. 1656 6.2.1. Identifiers and Their Namespaces 1658 Each identifier is valid in a namespace that depends on the type of 1659 the YANG item being defined. All identifiers defined in a namespace 1660 MUST be unique. 1662 o All module and submodule names share the same global module 1663 identifier namespace. 1665 o All extension names defined in a module and its submodules share 1666 the same extension identifier namespace. 1668 o All feature names defined in a module and its submodules share the 1669 same feature identifier namespace. 1671 o All identity names defined in a module and its submodules share 1672 the same identity identifier namespace. 1674 o All derived type names defined within a parent node or at the top 1675 level of the module or its submodules share the same type 1676 identifier namespace. This namespace is scoped to all descendant 1677 nodes of the parent node or module. This means that any 1678 descendent node may use that typedef, and it MUST NOT define a 1679 typedef with the same name. 1681 o All grouping names defined within a parent node or at the top 1682 level of the module or its submodules share the same grouping 1683 identifier namespace. This namespace is scoped to all descendant 1684 nodes of the parent node or module. This means that any 1685 descendent node may use that grouping, and it MUST NOT define a 1686 grouping with the same name. 1688 o All leafs, leaf-lists, lists, containers, choices, rpcs, 1689 notifications, and anyxmls defined (directly or through a uses 1690 statement) within a parent node or at the top level of the module 1691 or its submodules share the same identifier namespace. This 1692 namespace is scoped to the parent node or module, unless the 1693 parent node is a case node. In that case, the namespace is scoped 1694 to the closest ancestor node that is not a case or choice node. 1696 o All cases within a choice share the same case identifier 1697 namespace. This namespace is scoped to the parent choice node. 1699 Forward references are allowed in YANG. 1701 6.3. Statements 1703 A YANG module contains a sequence of statements. Each statement 1704 starts with a keyword, followed by zero or one argument, followed 1705 either by a semicolon (";") or a block of substatements enclosed 1706 within braces ("{ }"): 1708 statement = keyword [argument] (";" / "{" *statement "}") 1710 The argument is a string, as defined in Section 6.1.2. 1712 6.3.1. Language Extensions 1714 A module can introduce YANG extensions by using the "extension" 1715 keyword (see Section 7.18). The extensions can be imported by other 1716 modules with the "import" statement (see Section 7.1.5). When an 1717 imported extension is used, the extension's keyword MUST be qualified 1718 using the prefix with which the extension's module was imported. If 1719 an extension is used in the module where it is defined, the 1720 extension's keyword MUST be qualified with the module's prefix. 1722 If a YANG compiler does not support a particular extension, which 1723 appears in a YANG module as an unknown-statement (see Section 13), 1724 the entire unknown-statement MAY be ignored by the compiler. 1726 6.4. XPath Evaluations 1728 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 1729 for specifying many inter-node references and dependencies. NETCONF 1730 clients and servers are not required to implement an XPath 1731 interpreter, but MUST ensure that the requirements encoded in the 1732 data model are enforced. The manner of enforcement is an 1733 implementation decision. The XPath expressions MUST be syntactically 1734 correct, and all prefixes used MUST be present in the XPath context 1735 (see Section 6.4.1). An implementation may choose to implement them 1736 by hand, rather than using the XPath expression directly. 1738 The data model used in the XPath expressions is the same as that used 1739 in XPath 1.0 [XPATH], with the same extension for root node children 1740 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 1741 that the root node may have any number of element nodes as its 1742 children. 1744 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 1745 values, see Section 3.5 in [XPATH]. This means that some values of 1746 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 1747 cannot be exactly represented in XPath expressions. Therefore, due 1748 caution should be exercised when using nodes with 64-bit numeric 1749 values in XPath expressions. In particular, numerical comparisons 1750 involving equality may yield unexpected results. 1752 For example, consider the following definition: 1754 leaf lxiv { 1755 type decimal64 { 1756 fraction-digits 18; 1757 } 1758 must ". <= 10"; 1759 } 1761 An instance of the "lxiv" leaf having the value of 1762 10.0000000000000001 will then successfully pass validation. 1764 6.4.1. XPath Context 1766 All YANG XPath expressions share the following XPath context 1767 definition: 1769 o The set of namespace declarations is the set of all "import" 1770 statements' prefix and namespace pairs in the module where the 1771 XPath expression is specified, and the "prefix" statement's prefix 1772 for the "namespace" statement's URI. 1774 o Names without a namespace prefix belong to the same namespace as 1775 the identifier of the current node. Inside a grouping, that 1776 namespace is affected by where the grouping is used (see 1777 Section 7.12). Inside a typedef, that namespace is affected by 1778 where the typedef is referenced. If a typedef is defined and 1779 referenced within a grouping, the namespace is affected by where 1780 the grouping is used (see Section 7.12). 1782 o The function library is the core function library defined in 1783 [XPATH], and the functions defined in Section 10. 1785 o The set of variable bindings is empty. 1787 The mechanism for handling unprefixed names is adopted from XPath 2.0 1788 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1789 ambiguity may ever arise because YANG node identifiers are always 1790 qualified names with a non-null namespace URI. 1792 The accessible tree depends on where the statement with the XPath 1793 expression is defined: 1795 o If the XPath expression is defined in substatement to a data node 1796 that represents configuration, the accessible tree is the data in 1797 the NETCONF datastore where the context node exists. The root 1798 node has all top-level configuration data nodes in all modules as 1799 children. 1801 o If the XPath expression is defined in a substatement to a data 1802 node that represents state data, the accessible tree is all all 1803 state data on the device, and the "running" datastore. The root 1804 node has all top-level data nodes in all modules as children. 1806 o If the XPath expression is defined in a substatement to a 1807 "notification" statement, the accessible tree is the notification 1808 instance, all state data on the device, and the "running" 1809 datastore. The root node has the node representing the 1810 notification being defined and all top-level data nodes in all 1811 modules as children. 1813 o If the XPath expression is defined in a substatement to an "input" 1814 statement in an "rpc" statement, the accessible tree is the RPC 1815 operation instance, all state data on the device, and the 1816 "running" datastore. The root node has the node representing the 1817 operation being defined and all top-level data nodes in all 1818 modules as children. The node representing the operation being 1819 defined has the operation's input parameters as children. 1821 o If the XPath expression is defined in a substatement to an 1822 "output" statement in an "rpc" statement, the accessible tree is 1823 the RPC operation's output, all state data on the device, and the 1824 "running" datastore. The root node has the node representing the 1825 operation being defined and all top-level data nodes in all 1826 modules as children. The node representing the operation being 1827 defined has the operation's output parameters as children. 1829 In the accessible tree, all leafs and leaf-lists with default values 1830 in use exist (See Section 7.6.1 and Section 7.7.2). 1832 If a node that exists in the accessible tree has a non-presence 1833 container as a child, then the non-presence container also exists in 1834 the tree. 1836 The context node varies with the YANG XPath expression, and is 1837 specified where the YANG statement with the XPath expression is 1838 defined. 1840 6.5. Schema Node Identifier 1842 A schema node identifier is a string that identifies a node in the 1843 schema tree. It has two forms, "absolute" and "descendant", defined 1844 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1845 in Section 13, respectively. A schema node identifier consists of a 1846 path of identifiers, separated by slashes ("/"). In an absolute 1847 schema node identifier, the first identifier after the leading slash 1848 is any top-level schema node in the local module or in all imported 1849 modules. 1851 References to identifiers defined in external modules MUST be 1852 qualified with appropriate prefixes, and references to identifiers 1853 defined in the current module and its submodules MAY use a prefix. 1855 For example, to identify the child node "b" of top-level node "a", 1856 the string "/a/b" can be used. 1858 7. YANG Statements 1860 The following sections describe all of the YANG statements. 1862 Note that even a statement that does not have any substatements 1863 defined in YANG can have vendor-specific extensions as substatements. 1865 For example, the "description" statement does not have any 1866 substatements defined in YANG, but the following is legal: 1868 description "some text" { 1869 acme:documentation-flag 5; 1870 } 1872 7.1. The module Statement 1874 The "module" statement defines the module's name, and groups all 1875 statements that belong to the module together. The "module" 1876 statement's argument is the name of the module, followed by a block 1877 of substatements that hold detailed module information. The module 1878 name follows the rules for identifiers in Section 6.2. 1880 Names of modules published in RFC streams [RFC4844] MUST be assigned 1881 by IANA, see Section 15. 1883 Private module names are assigned by the organization owning the 1884 module without a central registry. It is RECOMMENDED to choose 1885 module names that will have a low probability of colliding with 1886 standard or other enterprise modules and submodules, e.g., by using 1887 the enterprise or organization name as a prefix for the module name. 1889 A module typically has the following layout: 1891 module { 1893 // header information 1894 1895 1896 1898 // linkage statements 1899 1900 1902 // meta information 1903 1904 1905 1906 1908 // revision history 1909 1911 // module definitions 1912 1913 } 1915 7.1.1. The module's Substatements 1916 +--------------+---------+-------------+ 1917 | substatement | section | cardinality | 1918 +--------------+---------+-------------+ 1919 | anyxml | 7.10 | 0..n | 1920 | augment | 7.16 | 0..n | 1921 | choice | 7.9 | 0..n | 1922 | contact | 7.1.8 | 0..1 | 1923 | container | 7.5 | 0..n | 1924 | description | 7.20.3 | 0..1 | 1925 | deviation | 7.19.3 | 0..n | 1926 | extension | 7.18 | 0..n | 1927 | feature | 7.19.1 | 0..n | 1928 | grouping | 7.11 | 0..n | 1929 | identity | 7.17 | 0..n | 1930 | import | 7.1.5 | 0..n | 1931 | include | 7.1.6 | 0..n | 1932 | leaf | 7.6 | 0..n | 1933 | leaf-list | 7.7 | 0..n | 1934 | list | 7.8 | 0..n | 1935 | namespace | 7.1.3 | 1 | 1936 | notification | 7.15 | 0..n | 1937 | organization | 7.1.7 | 0..1 | 1938 | prefix | 7.1.4 | 1 | 1939 | reference | 7.20.4 | 0..1 | 1940 | revision | 7.1.9 | 0..n | 1941 | rpc | 7.13 | 0..n | 1942 | typedef | 7.3 | 0..n | 1943 | uses | 7.12 | 0..n | 1944 | yang-version | 7.1.2 | 1 | 1945 +--------------+---------+-------------+ 1947 7.1.2. The yang-version Statement 1949 The "yang-version" statement specifies which version of the YANG 1950 language was used in developing the module. The statement's argument 1951 is a string. It MUST contain the value "1.1", which is the current 1952 YANG version. 1954 A module or submodule that doesn't contain the "yang-version" 1955 statement, or one that contains the value "1", is developed for YANG 1956 version 1, defined in [RFC6020]. 1958 Handling of the "yang-version" statement for versions other than 1959 "1.1" (the version defined here) is out of scope for this 1960 specification. Any document that defines a higher version will need 1961 to define the backward compatibility of such a higher version. 1963 7.1.3. The namespace Statement 1965 The "namespace" statement defines the XML namespace that all 1966 identifiers defined by the module are qualified by, with the 1967 exception of data node identifiers defined inside a grouping (see 1968 Section 7.12 for details). The argument to the "namespace" statement 1969 is the URI of the namespace. 1971 See also Section 5.3. 1973 7.1.4. The prefix Statement 1975 The "prefix" statement is used to define the prefix associated with 1976 the module and its namespace. The "prefix" statement's argument is 1977 the prefix string that is used as a prefix to access a module. The 1978 prefix string MAY be used to refer to definitions contained in the 1979 module, e.g., "if:ifName". A prefix follows the same rules as an 1980 identifier (see Section 6.2). 1982 When used inside the "module" statement, the "prefix" statement 1983 defines the prefix to be used when this module is imported. To 1984 improve readability of the NETCONF XML, a NETCONF client or server 1985 that generates XML or XPath that use prefixes SHOULD use the prefix 1986 defined by the module, unless there is a conflict. 1988 When used inside the "import" statement, the "prefix" statement 1989 defines the prefix to be used when accessing definitions inside the 1990 imported module. When a reference to an identifier from the imported 1991 module is used, the prefix string for the imported module is used in 1992 combination with a colon (":") and the identifier, e.g., 1993 "if:ifIndex". To improve readability of YANG modules, the prefix 1994 defined by a module SHOULD be used when the module is imported, 1995 unless there is a conflict. If there is a conflict, i.e., two 1996 different modules that both have defined the same prefix are 1997 imported, at least one of them MUST be imported with a different 1998 prefix. 2000 All prefixes, including the prefix for the module itself MUST be 2001 unique within the module or submodule. 2003 7.1.5. The import Statement 2005 The "import" statement makes definitions from one module available 2006 inside another module or submodule. The argument is the name of the 2007 module to import, and the statement is followed by a block of 2008 substatements that holds detailed import information. When a module 2009 is imported, the importing module may: 2011 o use any grouping and typedef defined at the top level in the 2012 imported module or its submodules. 2014 o use any extension, feature, and identity defined in the imported 2015 module or its submodules. 2017 o use any node in the imported module's schema tree in "must", 2018 "path", and "when" statements, or as the target node in "augment" 2019 and "deviation" statements. 2021 The mandatory "prefix" substatement assigns a prefix for the imported 2022 module that is scoped to the importing module or submodule. Multiple 2023 "import" statements may be specified to import from different 2024 modules. 2026 When the optional "revision-date" substatement is present, any 2027 typedef, grouping, extension, feature, and identity referenced by 2028 definitions in the local module are taken from the specified revision 2029 of the imported module. It is an error if the specified revision of 2030 the imported module does not exist. If no "revision-date" 2031 substatement is present, it is undefined from which revision of the 2032 module they are taken. 2034 Multiple revisions of the same module MUST NOT be imported. 2036 +---------------+---------+-------------+ 2037 | substatement | section | cardinality | 2038 +---------------+---------+-------------+ 2039 | prefix | 7.1.4 | 1 | 2040 | revision-date | 7.1.5.1 | 0..1 | 2041 +---------------+---------+-------------+ 2043 The import's Substatements 2045 7.1.5.1. The import's revision-date Statement 2047 The import's "revision-date" statement is used to specify the exact 2048 version of the module to import. The "revision-date" statement MUST 2049 match the most recent "revision" statement in the imported module. 2051 7.1.6. The include Statement 2053 The "include" statement is used to make content from a submodule 2054 available to that submodule's parent module. The argument is an 2055 identifier that is the name of the submodule to include. Modules are 2056 only allowed to include submodules that belong to that module, as 2057 defined by the "belongs-to" statement (see Section 7.2.2). 2059 Submodules are only allowed to include other submodules belonging to 2060 the same module. 2062 When a module includes a submodule, it incorporates the contents of 2063 the submodule into the node hierarchy of the module. 2065 For backwards compatibility with YANG version 1, a submodule is 2066 allowed to include another submodule belonging to the same module, 2067 but this is not necessary in YANG version 1.1. 2069 When the optional "revision-date" substatement is present, the 2070 specified revision of the submodule is included in the module. It is 2071 an error if the specified revision of the submodule does not exist. 2072 If no "revision-date" substatement is present, it is undefined which 2073 revision of the submodule is included. 2075 Multiple revisions of the same submodule MUST NOT be included. 2077 +---------------+---------+-------------+ 2078 | substatement | section | cardinality | 2079 +---------------+---------+-------------+ 2080 | revision-date | 7.1.5.1 | 0..1 | 2081 +---------------+---------+-------------+ 2083 The includes's Substatements 2085 7.1.7. The organization Statement 2087 The "organization" statement defines the party responsible for this 2088 module. The argument is a string that is used to specify a textual 2089 description of the organization(s) under whose auspices this module 2090 was developed. 2092 7.1.8. The contact Statement 2094 The "contact" statement provides contact information for the module. 2095 The argument is a string that is used to specify contact information 2096 for the person or persons to whom technical queries concerning this 2097 module should be sent, such as their name, postal address, telephone 2098 number, and electronic mail address. 2100 7.1.9. The revision Statement 2102 The "revision" statement specifies the editorial revision history of 2103 the module, including the initial revision. A series of revision 2104 statements detail the changes in the module's definition. The 2105 argument is a date string in the format "YYYY-MM-DD", followed by a 2106 block of substatements that holds detailed revision information. A 2107 module SHOULD have at least one "revision" statement. For every 2108 published editorial change, a new one SHOULD be added in front of the 2109 revisions sequence, so that all revisions are in reverse 2110 chronological order. 2112 7.1.9.1. The revision's Substatement 2114 +--------------+---------+-------------+ 2115 | substatement | section | cardinality | 2116 +--------------+---------+-------------+ 2117 | description | 7.20.3 | 0..1 | 2118 | reference | 7.20.4 | 0..1 | 2119 +--------------+---------+-------------+ 2121 7.1.10. Usage Example 2123 module acme-system { 2124 yang-version 1.1; 2125 namespace "http://acme.example.com/system"; 2126 prefix "acme"; 2128 import ietf-yang-types { 2129 prefix "yang"; 2130 } 2132 include acme-types; 2134 organization "ACME Inc."; 2135 contact 2136 "Joe L. User 2138 ACME, Inc. 2139 42 Anywhere Drive 2140 Nowhere, CA 95134 2141 USA 2143 Phone: +1 800 555 0100 2144 EMail: joe@acme.example.com"; 2146 description 2147 "The module for entities implementing the ACME protocol."; 2149 revision "2007-06-09" { 2150 description "Initial revision."; 2151 } 2153 // definitions follow... 2154 } 2156 7.2. The submodule Statement 2158 While the primary unit in YANG is a module, a YANG module can itself 2159 be constructed out of several submodules. Submodules allow a module 2160 designer to split a complex model into several pieces where all the 2161 submodules contribute to a single namespace, which is defined by the 2162 module that includes the submodules. 2164 The "submodule" statement defines the submodule's name, and groups 2165 all statements that belong to the submodule together. The 2166 "submodule" statement's argument is the name of the submodule, 2167 followed by a block of substatements that hold detailed submodule 2168 information. The submodule name follows the rules for identifiers in 2169 Section 6.2. 2171 Names of submodules published in RFC streams [RFC4844] MUST be 2172 assigned by IANA, see Section 15. 2174 Private submodule names are assigned by the organization owning the 2175 submodule without a central registry. It is RECOMMENDED to choose 2176 submodule names that will have a low probability of colliding with 2177 standard or other enterprise modules and submodules, e.g., by using 2178 the enterprise or organization name as a prefix for the submodule 2179 name. 2181 A submodule typically has the following layout: 2183 submodule { 2185 2186 // module identification 2187 2189 // linkage statements 2190 2192 // meta information 2193 2194 2195 2196 2198 // revision history 2199 2201 // module definitions 2202 2203 } 2205 7.2.1. The submodule's Substatements 2206 +--------------+---------+-------------+ 2207 | substatement | section | cardinality | 2208 +--------------+---------+-------------+ 2209 | anyxml | 7.10 | 0..n | 2210 | augment | 7.16 | 0..n | 2211 | belongs-to | 7.2.2 | 1 | 2212 | choice | 7.9 | 0..n | 2213 | contact | 7.1.8 | 0..1 | 2214 | container | 7.5 | 0..n | 2215 | description | 7.20.3 | 0..1 | 2216 | deviation | 7.19.3 | 0..n | 2217 | extension | 7.18 | 0..n | 2218 | feature | 7.19.1 | 0..n | 2219 | grouping | 7.11 | 0..n | 2220 | identity | 7.17 | 0..n | 2221 | import | 7.1.5 | 0..n | 2222 | include | 7.1.6 | 0..n | 2223 | leaf | 7.6 | 0..n | 2224 | leaf-list | 7.7 | 0..n | 2225 | list | 7.8 | 0..n | 2226 | notification | 7.15 | 0..n | 2227 | organization | 7.1.7 | 0..1 | 2228 | reference | 7.20.4 | 0..1 | 2229 | revision | 7.1.9 | 0..n | 2230 | rpc | 7.13 | 0..n | 2231 | typedef | 7.3 | 0..n | 2232 | uses | 7.12 | 0..n | 2233 | yang-version | 7.1.2 | 1 | 2234 +--------------+---------+-------------+ 2236 7.2.2. The belongs-to Statement 2238 The "belongs-to" statement specifies the module to which the 2239 submodule belongs. The argument is an identifier that is the name of 2240 the module. 2242 A submodule MUST only be included by the module to which it belongs, 2243 or by another submodule that belongs to that module. 2245 The mandatory "prefix" substatement assigns a prefix for the module 2246 to which the submodule belongs. All definitions in the module that 2247 the submodule belongs to and all its submodules can be accessed by 2248 using the prefix. 2250 +--------------+---------+-------------+ 2251 | substatement | section | cardinality | 2252 +--------------+---------+-------------+ 2253 | prefix | 7.1.4 | 1 | 2254 +--------------+---------+-------------+ 2256 The belongs-to's Substatements 2258 7.2.3. Usage Example 2260 submodule acme-types { 2261 yang-version 1.1; 2262 belongs-to "acme-system" { 2263 prefix "acme"; 2264 } 2266 import ietf-yang-types { 2267 prefix "yang"; 2268 } 2270 organization "ACME Inc."; 2271 contact 2272 "Joe L. User 2274 ACME, Inc. 2275 42 Anywhere Drive 2276 Nowhere, CA 95134 2277 USA 2279 Phone: +1 800 555 0100 2280 EMail: joe@acme.example.com"; 2282 description 2283 "This submodule defines common ACME types."; 2285 revision "2007-06-09" { 2286 description "Initial revision."; 2287 } 2289 // definitions follows... 2290 } 2292 7.3. The typedef Statement 2294 The "typedef" statement defines a new type that may be used locally 2295 in the module or submodule, and by other modules that import from it, 2296 according to the rules in Section 5.5. The new type is called the 2297 "derived type", and the type from which it was derived is called the 2298 "base type". All derived types can be traced back to a YANG built-in 2299 type. 2301 The "typedef" statement's argument is an identifier that is the name 2302 of the type to be defined, and MUST be followed by a block of 2303 substatements that holds detailed typedef information. 2305 The name of the type MUST NOT be one of the YANG built-in types. If 2306 the typedef is defined at the top level of a YANG module or 2307 submodule, the name of the type to be defined MUST be unique within 2308 the module. 2310 7.3.1. The typedef's Substatements 2312 +--------------+---------+-------------+ 2313 | substatement | section | cardinality | 2314 +--------------+---------+-------------+ 2315 | default | 7.3.4 | 0..1 | 2316 | description | 7.20.3 | 0..1 | 2317 | reference | 7.20.4 | 0..1 | 2318 | status | 7.20.2 | 0..1 | 2319 | type | 7.3.2 | 1 | 2320 | units | 7.3.3 | 0..1 | 2321 +--------------+---------+-------------+ 2323 7.3.2. The typedef's type Statement 2325 The "type" statement, which MUST be present, defines the base type 2326 from which this type is derived. See Section 7.4 for details. 2328 7.3.3. The units Statement 2330 The "units" statement, which is optional, takes as an argument a 2331 string that contains a textual definition of the units associated 2332 with the type. 2334 7.3.4. The typedef's default Statement 2336 The "default" statement takes as an argument a string that contains a 2337 default value for the new type. 2339 The value of the "default" statement MUST be valid according to the 2340 type specified in the "type" statement. 2342 If the base type has a default value, and the new derived type does 2343 not specify a new default value, the base type's default value is 2344 also the default value of the new derived type. 2346 If the type's default value is not valid according to the new 2347 restrictions specified in a derived type or leaf definition, the 2348 derived type or leaf definition MUST specify a new default value 2349 compatible with the restrictions. 2351 7.3.5. Usage Example 2353 typedef listen-ipv4-address { 2354 type inet:ipv4-address; 2355 default "0.0.0.0"; 2356 } 2358 7.4. The type Statement 2360 The "type" statement takes as an argument a string that is the name 2361 of a YANG built-in type (see Section 9) or a derived type (see 2362 Section 7.3), followed by an optional block of substatements that are 2363 used to put further restrictions on the type. 2365 The restrictions that can be applied depend on the type being 2366 restricted. The restriction statements for all built-in types are 2367 described in the subsections of Section 9. 2369 7.4.1. The type's Substatements 2371 +------------------+---------+-------------+ 2372 | substatement | section | cardinality | 2373 +------------------+---------+-------------+ 2374 | base | 7.17.2 | 0..n | 2375 | bit | 9.7.4 | 0..n | 2376 | enum | 9.6.4 | 0..n | 2377 | fraction-digits | 9.3.4 | 0..1 | 2378 | length | 9.4.4 | 0..1 | 2379 | path | 9.9.2 | 0..1 | 2380 | pattern | 9.4.5 | 0..n | 2381 | range | 9.2.4 | 0..1 | 2382 | require-instance | 9.9.3 | 0..1 | 2383 | type | 7.4 | 0..n | 2384 +------------------+---------+-------------+ 2386 7.5. The container Statement 2388 The "container" statement is used to define an interior data node in 2389 the schema tree. It takes one argument, which is an identifier, 2390 followed by a block of substatements that holds detailed container 2391 information. 2393 A container node does not have a value, but it has a list of child 2394 nodes in the data tree. The child nodes are defined in the 2395 container's substatements. 2397 7.5.1. Containers with Presence 2399 YANG supports two styles of containers, those that exist only for 2400 organizing the hierarchy of data nodes, and those whose presence in 2401 the configuration has an explicit meaning. 2403 In the first style, the container has no meaning of its own, existing 2404 only to contain child nodes. This is the default style. 2406 For example, the set of scrambling options for Synchronous Optical 2407 Network (SONET) interfaces may be placed inside a "scrambling" 2408 container to enhance the organization of the configuration hierarchy, 2409 and to keep these nodes together. The "scrambling" node itself has 2410 no meaning, so removing the node when it becomes empty relieves the 2411 user from performing this task. 2413 In the second style, the presence of the container itself is 2414 configuration data, representing a single bit of configuration data. 2415 The container acts as both a configuration knob and a means of 2416 organizing related configuration. These containers are explicitly 2417 created and deleted. 2419 YANG calls this style a "presence container" and it is indicated 2420 using the "presence" statement, which takes as its argument a text 2421 string indicating what the presence of the node means. 2423 For example, an "ssh" container may turn on the ability to log into 2424 the device using ssh, but can also contain any ssh-related 2425 configuration knobs, such as connection rates or retry limits. 2427 The "presence" statement (see Section 7.5.5) is used to give 2428 semantics to the existence of the container in the data tree. 2430 7.5.2. The container's Substatements 2431 +--------------+---------+-------------+ 2432 | substatement | section | cardinality | 2433 +--------------+---------+-------------+ 2434 | action | 7.14 | 0..n | 2435 | anyxml | 7.10 | 0..n | 2436 | choice | 7.9 | 0..n | 2437 | config | 7.20.1 | 0..1 | 2438 | container | 7.5 | 0..n | 2439 | description | 7.20.3 | 0..1 | 2440 | grouping | 7.11 | 0..n | 2441 | if-feature | 7.19.2 | 0..n | 2442 | leaf | 7.6 | 0..n | 2443 | leaf-list | 7.7 | 0..n | 2444 | list | 7.8 | 0..n | 2445 | must | 7.5.3 | 0..n | 2446 | presence | 7.5.5 | 0..1 | 2447 | reference | 7.20.4 | 0..1 | 2448 | status | 7.20.2 | 0..1 | 2449 | typedef | 7.3 | 0..n | 2450 | uses | 7.12 | 0..n | 2451 | when | 7.20.5 | 0..1 | 2452 +--------------+---------+-------------+ 2454 7.5.3. The must Statement 2456 The "must" statement, which is optional, takes as an argument a 2457 string that contains an XPath expression (see Section 6.4). It is 2458 used to formally declare a constraint on valid data. The constraint 2459 is enforced according to the rules in Section 8. 2461 When a datastore is validated, all "must" constraints are 2462 conceptually evaluated once for each data node in the accessible tree 2463 (see Section 6.4.1). 2465 All such constraints MUST evaluate to true for the data to be valid. 2467 The XPath expression is conceptually evaluated in the following 2468 context, in addition to the definition in Section 6.4.1: 2470 o The context node is the node in the accessible tree for which the 2471 "must" statement is defined. 2473 The result of the XPath expression is converted to a boolean value 2474 using the standard XPath rules. 2476 Note that since all leaf values in the data tree are conceptually 2477 stored in their canonical form (see Section 7.6 and Section 7.7), any 2478 XPath comparisons are done on the canonical value. 2480 Also note that the XPath expression is conceptually evaluated. This 2481 means that an implementation does not have to use an XPath evaluator 2482 on the device. How the evaluation is done in practice is an 2483 implementation decision. 2485 7.5.4. The must's Substatements 2487 +---------------+---------+-------------+ 2488 | substatement | section | cardinality | 2489 +---------------+---------+-------------+ 2490 | description | 7.20.3 | 0..1 | 2491 | error-app-tag | 7.5.4.2 | 0..1 | 2492 | error-message | 7.5.4.1 | 0..1 | 2493 | reference | 7.20.4 | 0..1 | 2494 +---------------+---------+-------------+ 2496 7.5.4.1. The error-message Statement 2498 The "error-message" statement, which is optional, takes a string as 2499 an argument. If the constraint evaluates to false, the string is 2500 passed as in the . 2502 7.5.4.2. The error-app-tag Statement 2504 The "error-app-tag" statement, which is optional, takes a string as 2505 an argument. If the constraint evaluates to false, the string is 2506 passed as in the . 2508 7.5.4.3. Usage Example of must and error-message 2509 container interface { 2510 leaf ifType { 2511 type enumeration { 2512 enum ethernet; 2513 enum atm; 2514 } 2515 } 2516 leaf ifMTU { 2517 type uint32; 2518 } 2519 must "ifType != 'ethernet' or " + 2520 "(ifType = 'ethernet' and ifMTU = 1500)" { 2521 error-message "An ethernet MTU must be 1500"; 2522 } 2523 must "ifType != 'atm' or " + 2524 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2525 error-message "An atm MTU must be 64 .. 17966"; 2526 } 2527 } 2529 7.5.5. The presence Statement 2531 The "presence" statement assigns a meaning to the presence of a 2532 container in the data tree. It takes as an argument a string that 2533 contains a textual description of what the node's presence means. 2535 If a container has the "presence" statement, the container's 2536 existence in the data tree carries some meaning. Otherwise, the 2537 container is used to give some structure to the data, and it carries 2538 no meaning by itself. 2540 See Section 7.5.1 for additional information. 2542 7.5.6. The container's Child Node Statements 2544 Within a container, the "container", "leaf", "list", "leaf-list", 2545 "uses", "choice", and "anyxml" statements can be used to define child 2546 nodes to the container. 2548 7.5.7. XML Mapping Rules 2550 A container node is encoded as an XML element. The element's local 2551 name is the container's identifier, and its namespace is the module's 2552 XML namespace (see Section 7.1.3). 2554 The container's child nodes are encoded as subelements to the 2555 container element. If the container defines RPC input or output 2556 parameters, these subelements are encoded in the same order as they 2557 are defined within the "container" statement. Otherwise, the 2558 subelements are encoded in any order. 2560 A NETCONF server that replies to a or request MAY 2561 choose not to send a container element if the container node does not 2562 have the "presence" statement and no child nodes exist. Thus, a 2563 client that receives an for a or 2564 request, must be prepared to handle the case that a container node 2565 without a "presence" statement is not present in the XML. 2567 7.5.8. NETCONF Operations 2569 Containers can be created, deleted, replaced, and modified through 2570 , by using the "operation" attribute (see [RFC6241], 2571 Section 7.2) in the container's XML element. 2573 If a container does not have a "presence" statement and the last 2574 child node is deleted, the NETCONF server MAY delete the container. 2576 When a NETCONF server processes an request, the 2577 elements of procedure for the container node are: 2579 If the operation is "merge" or "replace", the node is created if 2580 it does not exist. 2582 If the operation is "create", the node is created if it does not 2583 exist. If the node already exists, a "data-exists" error is 2584 returned. 2586 If the operation is "delete", the node is deleted if it exists. 2587 If the node does not exist, a "data-missing" error is returned. 2589 7.5.9. Usage Example 2591 Given the following container definition: 2593 container system { 2594 description "Contains various system parameters"; 2595 container services { 2596 description "Configure externally available services"; 2597 container "ssh" { 2598 presence "Enables SSH"; 2599 description "SSH service specific configuration"; 2600 // more leafs, containers and stuff here... 2601 } 2602 } 2603 } 2605 A corresponding XML instance example: 2607 2608 2609 2610 2611 2613 Since the element is present, ssh is enabled. 2615 To delete a container with an : 2617 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2634 7.6. The leaf Statement 2636 The "leaf" statement is used to define a leaf node in the schema 2637 tree. It takes one argument, which is an identifier, followed by a 2638 block of substatements that holds detailed leaf information. 2640 A leaf node has a value, but no child nodes in the data tree. 2641 Conceptually, the value in the data tree is always in the canonical 2642 form (see Section 9.1). 2644 A leaf node exists in zero or one instances in the data tree. 2646 The "leaf" statement is used to define a scalar variable of a 2647 particular built-in or derived type. 2649 7.6.1. The leaf's default value 2651 The default value of a leaf is the value that the server uses if the 2652 leaf does not exist in the data tree. The usage of the default value 2653 depends on the leaf's closest ancestor node in the schema tree that 2654 is not a non-presence container: 2656 o If no such ancestor exists in the schema tree, the default value 2657 MUST be used. 2659 o Otherwise, if this ancestor is a case node, the default value MUST 2660 be used if any node from the case exists in the data tree, or if 2661 the case node is the choice's default case, and no nodes from any 2662 other case exist in the data tree. 2664 o Otherwise, the default value MUST be used if the ancestor node 2665 exists in the data tree. 2667 In these cases, the default value is said to be in use. 2669 When the default value is in use, the server MUST operationally 2670 behave as if the leaf was present in the data tree with the default 2671 value as its value. 2673 If a leaf has a "default" statement, the leaf's default value is the 2674 value of the "default" statement. Otherwise, if the leaf's type has 2675 a default value, and the leaf is not mandatory, then the leaf's 2676 default value is the type's default value. In all other cases, the 2677 leaf does not have a default value. 2679 7.6.2. The leaf's Substatements 2681 +--------------+---------+-------------+ 2682 | substatement | section | cardinality | 2683 +--------------+---------+-------------+ 2684 | config | 7.20.1 | 0..1 | 2685 | default | 7.6.4 | 0..1 | 2686 | description | 7.20.3 | 0..1 | 2687 | if-feature | 7.19.2 | 0..n | 2688 | mandatory | 7.6.5 | 0..1 | 2689 | must | 7.5.3 | 0..n | 2690 | reference | 7.20.4 | 0..1 | 2691 | status | 7.20.2 | 0..1 | 2692 | type | 7.6.3 | 1 | 2693 | units | 7.3.3 | 0..1 | 2694 | when | 7.20.5 | 0..1 | 2695 +--------------+---------+-------------+ 2697 7.6.3. The leaf's type Statement 2699 The "type" statement, which MUST be present, takes as an argument the 2700 name of an existing built-in or derived type. The optional 2701 substatements specify restrictions on this type. See Section 7.4 for 2702 details. 2704 7.6.4. The leaf's default Statement 2706 The "default" statement, which is optional, takes as an argument a 2707 string that contains a default value for the leaf. 2709 The value of the "default" statement MUST be valid according to the 2710 type specified in the leaf's "type" statement. 2712 The "default" statement MUST NOT be present on nodes where 2713 "mandatory" is true. 2715 7.6.5. The leaf's mandatory Statement 2717 The "mandatory" statement, which is optional, takes as an argument 2718 the string "true" or "false", and puts a constraint on valid data. 2719 If not specified, the default is "false". 2721 If "mandatory" is "true", the behavior of the constraint depends on 2722 the type of the leaf's closest ancestor node in the schema tree that 2723 is not a non-presence container (see Section 7.5.1): 2725 o If no such ancestor exists in the schema tree, the leaf MUST 2726 exist. 2728 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2729 any node from the case exists in the data tree. 2731 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2732 data tree. 2734 This constraint is enforced according to the rules in Section 8. 2736 7.6.6. XML Mapping Rules 2738 A leaf node is encoded as an XML element. The element's local name 2739 is the leaf's identifier, and its namespace is the module's XML 2740 namespace (see Section 7.1.3). 2742 The value of the leaf node is encoded to XML according to the type, 2743 and sent as character data in the element. 2745 A NETCONF server that replies to a or request MAY 2746 choose not to send the leaf element if its value is the default 2747 value. Thus, a client that receives an for a or 2748 request, MUST be prepared to handle the case that a leaf 2749 node with a default value is not present in the XML. In this case, 2750 the value used by the server is known to be the default value. 2752 See Section 7.6.8 for an example. 2754 7.6.7. NETCONF Operations 2756 When a NETCONF server processes an request, the 2757 elements of procedure for the leaf node are: 2759 If the operation is "merge" or "replace", the node is created if 2760 it does not exist, and its value is set to the value found in the 2761 XML RPC data. 2763 If the operation is "create", the node is created if it does not 2764 exist. If the node already exists, a "data-exists" error is 2765 returned. 2767 If the operation is "delete", the node is deleted if it exists. 2768 If the node does not exist, a "data-missing" error is returned. 2770 7.6.8. Usage Example 2772 Given the following "leaf" statement, placed in the previously 2773 defined "ssh" container (see Section 7.5.9): 2775 leaf port { 2776 type inet:port-number; 2777 default 22; 2778 description "The port to which the SSH server listens" 2779 } 2781 A corresponding XML instance example: 2783 2022 2785 To set the value of a leaf with an : 2787 2790 2791 2792 2793 2794 2795 2796 2797 2798 2022 2799 2800 2801 2802 2803 2804 2806 7.7. The leaf-list Statement 2808 Where the "leaf" statement is used to define a simple scalar variable 2809 of a particular type, the "leaf-list" statement is used to define an 2810 array of a particular type. The "leaf-list" statement takes one 2811 argument, which is an identifier, followed by a block of 2812 substatements that holds detailed leaf-list information. 2814 The values in a leaf-list MUST be unique. 2816 Conceptually, the values in the data tree are always in the canonical 2817 form (see Section 9.1). 2819 7.7.1. Ordering 2821 YANG supports two styles for ordering the entries within lists and 2822 leaf-lists. In many lists, the order of list entries does not impact 2823 the implementation of the list's configuration, and the device is 2824 free to sort the list entries in any reasonable order. The 2825 "description" string for the list may suggest an order to the device 2826 implementor. YANG calls this style of list "system ordered" and they 2827 are indicated with the statement "ordered-by system". 2829 For example, a list of valid users would typically be sorted 2830 alphabetically, since the order in which the users appeared in the 2831 configuration would not impact the creation of those users' accounts. 2833 In the other style of lists, the order of list entries matters for 2834 the implementation of the list's configuration and the user is 2835 responsible for ordering the entries, while the device maintains that 2836 order. YANG calls this style of list "user ordered" and they are 2837 indicated with the statement "ordered-by user". 2839 For example, the order in which firewall filters entries are applied 2840 to incoming traffic may affect how that traffic is filtered. The 2841 user would need to decide if the filter entry that discards all TCP 2842 traffic should be applied before or after the filter entry that 2843 allows all traffic from trusted interfaces. The choice of order 2844 would be crucial. 2846 YANG provides a rich set of facilities within NETCONF's 2847 operation that allows the order of list entries in user-ordered lists 2848 to be controlled. List entries may be inserted or rearranged, 2849 positioned as the first or last entry in the list, or positioned 2850 before or after another specific entry. 2852 The "ordered-by" statement is covered in Section 7.7.7. 2854 7.7.2. The leaf-list's default values 2856 The default values of a leaf-list are the values that the server uses 2857 if the leaf-list does not exist in the data tree. The usage of the 2858 default values depends on the leaf-list's closest ancestor node in 2859 the schema tree that is not a non-presence container: 2861 o If no such ancestor exists in the schema tree, the default values 2862 MUST be used. 2864 o Otherwise, if this ancestor is a case node, the default values 2865 MUST be used if any node from the case exists in the data tree, or 2866 if the case node is the choice's default case, and no nodes from 2867 any other case exist in the data tree. 2869 o Otherwise, the default values MUST be used if the ancestor node 2870 exists in the data tree. 2872 In these cases, the default values are said to be in use. 2874 When the default values are in use, the server MUST operationally 2875 behave as if the leaf-list was present in the data tree with the 2876 default values as its values. 2878 If a leaf-list has one or more "default" statement, the leaf-list's 2879 default value are the values of the "default" statements, and if the 2880 leaf-list is user-ordered, the default values are used in the order 2881 of the "default" statements. Otherwise, if the leaf-list's type has 2882 a default value, and the leaf-list does not have a "min-elements" 2883 statement with a value greater than or equal to one, then the leaf- 2884 list's default value is the type's default value. In all other 2885 cases, the leaf-list does not have any default values. 2887 7.7.3. The leaf-list's Substatements 2889 +--------------+---------+-------------+ 2890 | substatement | section | cardinality | 2891 +--------------+---------+-------------+ 2892 | config | 7.20.1 | 0..1 | 2893 | default | 7.7.4 | 0..n | 2894 | description | 7.20.3 | 0..1 | 2895 | if-feature | 7.19.2 | 0..n | 2896 | max-elements | 7.7.6 | 0..1 | 2897 | min-elements | 7.7.5 | 0..1 | 2898 | must | 7.5.3 | 0..n | 2899 | ordered-by | 7.7.7 | 0..1 | 2900 | reference | 7.20.4 | 0..1 | 2901 | status | 7.20.2 | 0..1 | 2902 | type | 7.4 | 1 | 2903 | units | 7.3.3 | 0..1 | 2904 | when | 7.20.5 | 0..1 | 2905 +--------------+---------+-------------+ 2907 7.7.4. The leaf-list's default Statement 2909 The "default" statement, which is optional, takes as an argument a 2910 string that contains a default value for the leaf-list. 2912 The value of the "default" statement MUST be valid according to the 2913 type specified in the leaf-list's "type" statement. 2915 The "default" statement MUST NOT be present on nodes where 2916 "min-elements" has a value greater than or equal to one. 2918 7.7.5. The min-elements Statement 2920 The "min-elements" statement, which is optional, takes as an argument 2921 a non-negative integer that puts a constraint on valid list entries. 2922 A valid leaf-list or list MUST have at least min-elements entries. 2924 If no "min-elements" statement is present, it defaults to zero. 2926 The behavior of the constraint depends on the type of the leaf-list's 2927 or list's closest ancestor node in the schema tree that is not a non- 2928 presence container (see Section 7.5.1): 2930 o If this ancestor is a case node, the constraint is enforced if any 2931 other node from the case exists. 2933 o Otherwise, it is enforced if the ancestor node exists. 2935 The constraint is further enforced according to the rules in 2936 Section 8. 2938 7.7.6. The max-elements Statement 2940 The "max-elements" statement, which is optional, takes as an argument 2941 a positive integer or the string "unbounded", which puts a constraint 2942 on valid list entries. A valid leaf-list or list always has at most 2943 max-elements entries. 2945 If no "max-elements" statement is present, it defaults to 2946 "unbounded". 2948 The "max-elements" constraint is enforced according to the rules in 2949 Section 8. 2951 7.7.7. The ordered-by Statement 2953 The "ordered-by" statement defines whether the order of entries 2954 within a list are determined by the user or the system. The argument 2955 is one of the strings "system" or "user". If not present, order 2956 defaults to "system". 2958 This statement is ignored if the list represents state data, RPC 2959 output parameters, or notification content. 2961 See Section 7.7.1 for additional information. 2963 7.7.7.1. ordered-by system 2965 The entries in the list are sorted according to an unspecified order. 2966 Thus, an implementation is free to sort the entries in the most 2967 appropriate order. An implementation SHOULD use the same order for 2968 the same data, regardless of how the data were created. Using a 2969 deterministic order will make comparisons possible using simple tools 2970 like "diff". 2972 This is the default order. 2974 7.7.7.2. ordered-by user 2976 The entries in the list are sorted according to an order defined by 2977 the user. This order is controlled by using special XML attributes 2978 in the request. See Section 7.7.9 for details. 2980 7.7.8. XML Mapping Rules 2982 A leaf-list node is encoded as a series of XML elements. Each 2983 element's local name is the leaf-list's identifier, and its namespace 2984 is the module's XML namespace (see Section 7.1.3). 2986 The value of each leaf-list entry is encoded to XML according to the 2987 type, and sent as character data in the element. 2989 The XML elements representing leaf-list entries MUST appear in the 2990 order specified by the user if the leaf-list is "ordered-by user"; 2991 otherwise, the order is implementation-dependent. The XML elements 2992 representing leaf-list entries MAY be interleaved with other sibling 2993 elements, unless the leaf-list defines RPC input or output 2994 parameters. 2996 See Section 7.7.10 for an example. 2998 7.7.9. NETCONF Operations 3000 Leaf-list entries can be created and deleted, but not modified, 3001 through , by using the "operation" attribute in the 3002 leaf-list entry's XML element. 3004 In an "ordered-by user" leaf-list, the attributes "insert" and 3005 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3006 control where in the leaf-list the entry is inserted. These can be 3007 used during "create" operations to insert a new leaf-list entry, or 3008 during "merge" or "replace" operations to insert a new leaf-list 3009 entry or move an existing one. 3011 The "insert" attribute can take the values "first", "last", "before", 3012 and "after". If the value is "before" or "after", the "value" 3013 attribute MUST also be used to specify an existing entry in the leaf- 3014 list. 3016 If no "insert" attribute is present in the "create" operation, it 3017 defaults to "last". 3019 If several entries in an "ordered-by user" leaf-list are modified in 3020 the same request, the entries are modified one at the 3021 time, in the order of the XML elements in the request. 3023 In a , or an with a "replace" operation 3024 that covers the entire leaf-list, the leaf-list order is the same as 3025 the order of the XML elements in the request. 3027 When a NETCONF server processes an request, the 3028 elements of procedure for a leaf-list node are: 3030 If the operation is "merge" or "replace", the leaf-list entry is 3031 created if it does not exist. 3033 If the operation is "create", the leaf-list entry is created if it 3034 does not exist. If the leaf-list entry already exists, a 3035 "data-exists" error is returned. 3037 If the operation is "delete", the entry is deleted from the leaf- 3038 list if it exists. If the leaf-list entry does not exist, a 3039 "data-missing" error is returned. 3041 7.7.10. Usage Example 3043 leaf-list allow-user { 3044 type string; 3045 description "A list of user name patterns to allow"; 3046 } 3048 A corresponding XML instance example: 3050 alice 3051 bob 3053 To create a new element in this list, using the default 3054 operation "merge": 3056 3059 3060 3061 3062 3063 3064 3065 3066 3067 eric 3068 3069 3070 3071 3072 3073 3075 Given the following ordered-by user leaf-list: 3077 leaf-list cipher { 3078 type string; 3079 ordered-by user; 3080 description "A list of ciphers"; 3081 } 3083 The following would be used to insert a new cipher "blowfish-cbc" 3084 after "3des-cbc": 3086 3090 3091 3092 3093 3094 3095 3096 3097 3098 blowfish-cbc 3101 3102 3103 3104 3105 3106 3108 7.8. The list Statement 3110 The "list" statement is used to define an interior data node in the 3111 schema tree. A list node may exist in multiple instances in the data 3112 tree. Each such instance is known as a list entry. The "list" 3113 statement takes one argument, which is an identifier, followed by a 3114 block of substatements that holds detailed list information. 3116 A list entry is uniquely identified by the values of the list's keys, 3117 if defined. 3119 7.8.1. The list's Substatements 3120 +--------------+---------+-------------+ 3121 | substatement | section | cardinality | 3122 +--------------+---------+-------------+ 3123 | action | 7.14 | 0..n | 3124 | anyxml | 7.10 | 0..n | 3125 | choice | 7.9 | 0..n | 3126 | config | 7.20.1 | 0..1 | 3127 | container | 7.5 | 0..n | 3128 | description | 7.20.3 | 0..1 | 3129 | grouping | 7.11 | 0..n | 3130 | if-feature | 7.19.2 | 0..n | 3131 | key | 7.8.2 | 0..1 | 3132 | leaf | 7.6 | 0..n | 3133 | leaf-list | 7.7 | 0..n | 3134 | list | 7.8 | 0..n | 3135 | max-elements | 7.7.6 | 0..1 | 3136 | min-elements | 7.7.5 | 0..1 | 3137 | must | 7.5.3 | 0..n | 3138 | ordered-by | 7.7.7 | 0..1 | 3139 | reference | 7.20.4 | 0..1 | 3140 | status | 7.20.2 | 0..1 | 3141 | typedef | 7.3 | 0..n | 3142 | unique | 7.8.3 | 0..n | 3143 | uses | 7.12 | 0..n | 3144 | when | 7.20.5 | 0..1 | 3145 +--------------+---------+-------------+ 3147 7.8.2. The list's key Statement 3149 The "key" statement, which MUST be present if the list represents 3150 configuration, and MAY be present otherwise, takes as an argument a 3151 string that specifies a space-separated list of leaf identifiers of 3152 this list. A leaf identifier MUST NOT appear more than once in the 3153 key. Each such leaf identifier MUST refer to a child leaf of the 3154 list. The leafs can be defined directly in substatements to the 3155 list, or in groupings used in the list. 3157 The combined values of all the leafs specified in the key are used to 3158 uniquely identify a list entry. All key leafs MUST be given values 3159 when a list entry is created. Thus, any default values in the key 3160 leafs or their types are ignored. It also implies that any mandatory 3161 statement in the key leafs are ignored. 3163 A leaf that is part of the key can be of any built-in or derived 3164 type, except it MUST NOT be the built-in type "empty". 3166 All key leafs in a list MUST have the same value for their "config" 3167 as the list itself. 3169 The key string syntax is formally defined by the rule "key-arg" in 3170 Section 13. 3172 7.8.3. The list's unique Statement 3174 The "unique" statement is used to put constraints on valid list 3175 entries. It takes as an argument a string that contains a space- 3176 separated list of schema node identifiers, which MUST be given in the 3177 descendant form (see the rule "descendant-schema-nodeid" in 3178 Section 13). Each such schema node identifier MUST refer to a leaf. 3180 If one of the referenced leafs represents configuration data, then 3181 all of the referenced leafs MUST represent configuration data. 3183 The "unique" constraint specifies that the combined values of all the 3184 leaf instances specified in the argument string, including leafs with 3185 default values, MUST be unique within all list entry instances in 3186 which all referenced leafs exist. The constraint is enforced 3187 according to the rules in Section 8. 3189 The unique string syntax is formally defined by the rule "unique-arg" 3190 in Section 13. 3192 7.8.3.1. Usage Example 3194 With the following list: 3196 list server { 3197 key "name"; 3198 unique "ip port"; 3199 leaf name { 3200 type string; 3201 } 3202 leaf ip { 3203 type inet:ip-address; 3204 } 3205 leaf port { 3206 type inet:port-number; 3207 } 3208 } 3210 The following configuration is not valid: 3212 3213 smtp 3214 192.0.2.1 3215 25 3216 3218 3219 http 3220 192.0.2.1 3221 25 3222 3224 The following configuration is valid, since the "http" and "ftp" list 3225 entries do not have a value for all referenced leafs, and are thus 3226 not taken into account when the "unique" constraint is enforced: 3228 3229 smtp 3230 192.0.2.1 3231 25 3232 3234 3235 http 3236 192.0.2.1 3237 3239 3240 ftp 3241 192.0.2.1 3242 3244 7.8.4. The list's Child Node Statements 3246 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3247 "choice", and "anyxml" statements can be used to define child nodes 3248 to the list. 3250 7.8.5. XML Mapping Rules 3252 A list is encoded as a series of XML elements, one for each entry in 3253 the list. Each element's local name is the list's identifier, and 3254 its namespace is the module's XML namespace (see Section 7.1.3). 3256 The list's key nodes are encoded as subelements to the list's 3257 identifier element, in the same order as they are defined within the 3258 "key" statement. 3260 The rest of the list's child nodes are encoded as subelements to the 3261 list element, after the keys. If the list defines RPC input or 3262 output parameters, the subelements are encoded in the same order as 3263 they are defined within the "list" statement. Otherwise, the 3264 subelements are encoded in any order. 3266 The XML elements representing list entries MUST appear in the order 3267 specified by the user if the list is "ordered-by user", otherwise the 3268 order is implementation-dependent. The XML elements representing 3269 list entries MAY be interleaved with other sibling elements, unless 3270 the list defines RPC input or output parameters. 3272 7.8.6. NETCONF Operations 3274 List entries can be created, deleted, replaced, and modified through 3275 , by using the "operation" attribute in the list's XML 3276 element. In each case, the values of all keys are used to uniquely 3277 identify a list entry. If all keys are not specified for a list 3278 entry, a "missing-element" error is returned. 3280 In an "ordered-by user" list, the attributes "insert" and "key" in 3281 the YANG XML namespace (Section 5.3.1) can be used to control where 3282 in the list the entry is inserted. These can be used during "create" 3283 operations to insert a new list entry, or during "merge" or "replace" 3284 operations to insert a new list entry or move an existing one. 3286 The "insert" attribute can take the values "first", "last", "before", 3287 and "after". If the value is "before" or "after", the "key" 3288 attribute MUST also be used, to specify an existing element in the 3289 list. The value of the "key" attribute is the key predicates of the 3290 full instance identifier (see Section 9.13) for the list entry. 3292 If no "insert" attribute is present in the "create" operation, it 3293 defaults to "last". 3295 If several entries in an "ordered-by user" list are modified in the 3296 same request, the entries are modified one at the time, 3297 in the order of the XML elements in the request. 3299 In a , or an with a "replace" operation 3300 that covers the entire list, the list entry order is the same as the 3301 order of the XML elements in the request. 3303 When a NETCONF server processes an request, the 3304 elements of procedure for a list node are: 3306 If the operation is "merge" or "replace", the list entry is 3307 created if it does not exist. If the list entry already exists 3308 and the "insert" and "key" attributes are present, the list entry 3309 is moved according to the values of the "insert" and "key" 3310 attributes. If the list entry exists and the "insert" and "key" 3311 attributes are not present, the list entry is not moved. 3313 If the operation is "create", the list entry is created if it does 3314 not exist. If the list entry already exists, a "data-exists" 3315 error is returned. 3317 If the operation is "delete", the entry is deleted from the list 3318 if it exists. If the list entry does not exist, a "data-missing" 3319 error is returned. 3321 7.8.7. Usage Example 3323 Given the following list: 3325 list user { 3326 key "name"; 3327 config true; 3328 description "This is a list of users in the system."; 3330 leaf name { 3331 type string; 3332 } 3333 leaf type { 3334 type string; 3335 } 3336 leaf full-name { 3337 type string; 3338 } 3339 } 3341 A corresponding XML instance example: 3343 3344 fred 3345 admin 3346 Fred Flintstone 3347 3349 To create a new user "barney": 3351 3354 3355 3356 3357 3358 3359 3360 3361 barney 3362 admin 3363 Barney Rubble 3364 3365 3366 3367 3368 3370 To change the type of "fred" to "superuser": 3372 3375 3376 3377 3378 3379 3380 3381 3382 fred 3383 superuser 3384 3385 3386 3387 3388 3390 Given the following ordered-by user list: 3392 list user { 3393 description "This is a list of users in the system."; 3394 ordered-by user; 3395 config true; 3397 key "name"; 3399 leaf name { 3400 type string; 3401 } 3402 leaf type { 3403 type string; 3404 } 3405 leaf full-name { 3406 type string; 3407 } 3408 } 3410 The following would be used to insert a new user "barney" after the 3411 user "fred": 3413 3417 3418 3419 3420 3421 3422 3424 3427 barney 3428 admin 3429 Barney Rubble 3430 3431 3432 3433 3434 3436 The following would be used to move the user "barney" before the user 3437 "fred": 3439 3443 3444 3445 3446 3447 3448 3450 3453 barney 3454 3455 3456 3457 3458 3460 7.9. The choice Statement 3462 The "choice" statement defines a set of alternatives, only one of 3463 which may exist at any one time. The argument is an identifier, 3464 followed by a block of substatements that holds detailed choice 3465 information. The identifier is used to identify the choice node in 3466 the schema tree. A choice node does not exist in the data tree. 3468 A choice consists of a number of branches, defined with the "case" 3469 substatement. Each branch contains a number of child nodes. The 3470 nodes from at most one of the choice's branches exist at the same 3471 time. 3473 See Section 8.3.2 for additional information. 3475 7.9.1. The choice's Substatements 3476 +--------------+---------+-------------+ 3477 | substatement | section | cardinality | 3478 +--------------+---------+-------------+ 3479 | anyxml | 7.10 | 0..n | 3480 | case | 7.9.2 | 0..n | 3481 | choice | 7.9 | 0..n | 3482 | config | 7.20.1 | 0..1 | 3483 | container | 7.5 | 0..n | 3484 | default | 7.9.3 | 0..1 | 3485 | description | 7.20.3 | 0..1 | 3486 | if-feature | 7.19.2 | 0..n | 3487 | leaf | 7.6 | 0..n | 3488 | leaf-list | 7.7 | 0..n | 3489 | list | 7.8 | 0..n | 3490 | mandatory | 7.9.4 | 0..1 | 3491 | reference | 7.20.4 | 0..1 | 3492 | status | 7.20.2 | 0..1 | 3493 | when | 7.20.5 | 0..1 | 3494 +--------------+---------+-------------+ 3496 7.9.2. The choice's case Statement 3498 The "case" statement is used to define branches of the choice. It 3499 takes as an argument an identifier, followed by a block of 3500 substatements that holds detailed case information. 3502 The identifier is used to identify the case node in the schema tree. 3503 A case node does not exist in the data tree. 3505 Within a "case" statement, the "anyxml", "choice", "container", 3506 "leaf", "list", "leaf-list", and "uses" statements can be used to 3507 define child nodes to the case node. The identifiers of all these 3508 child nodes MUST be unique within all cases in a choice. For 3509 example, the following is illegal: 3511 choice interface-type { // This example is illegal YANG 3512 case a { 3513 leaf ethernet { ... } 3514 } 3515 case b { 3516 container ethernet { ...} 3517 } 3518 } 3520 As a shorthand, the "case" statement can be omitted if the branch 3521 contains a single "anyxml", "choice", "container", "leaf", "list", or 3522 "leaf-list" statement. In this case, the identifier of the case node 3523 is the same as the identifier in the branch statement. The following 3524 example: 3526 choice interface-type { 3527 container ethernet { ... } 3528 } 3530 is equivalent to: 3532 choice interface-type { 3533 case ethernet { 3534 container ethernet { ... } 3535 } 3536 } 3538 The case identifier MUST be unique within a choice. 3540 7.9.2.1. The case's Substatements 3542 +--------------+---------+-------------+ 3543 | substatement | section | cardinality | 3544 +--------------+---------+-------------+ 3545 | anyxml | 7.10 | 0..n | 3546 | choice | 7.9 | 0..n | 3547 | container | 7.5 | 0..n | 3548 | description | 7.20.3 | 0..1 | 3549 | if-feature | 7.19.2 | 0..n | 3550 | leaf | 7.6 | 0..n | 3551 | leaf-list | 7.7 | 0..n | 3552 | list | 7.8 | 0..n | 3553 | reference | 7.20.4 | 0..1 | 3554 | status | 7.20.2 | 0..1 | 3555 | uses | 7.12 | 0..n | 3556 | when | 7.20.5 | 0..1 | 3557 +--------------+---------+-------------+ 3559 7.9.3. The choice's default Statement 3561 The "default" statement indicates if a case should be considered as 3562 the default if no child nodes from any of the choice's cases exist. 3563 The argument is the identifier of the "case" statement. If the 3564 "default" statement is missing, there is no default case. 3566 The "default" statement MUST NOT be present on choices where 3567 "mandatory" is true. 3569 The default case is only important when considering the default 3570 values of nodes under the cases. The default values for nodes under 3571 the default case are used if none of the nodes under any of the cases 3572 are present. 3574 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3575 the default case. 3577 Default values for child nodes under a case are only used if one of 3578 the nodes under that case is present, or if that case is the default 3579 case. If none of the nodes under a case are present and the case is 3580 not the default case, the default values of the cases' child nodes 3581 are ignored. 3583 In this example, the choice defaults to "interval", and the default 3584 value will be used if none of "daily", "time-of-day", or "manual" are 3585 present. If "daily" is present, the default value for "time-of-day" 3586 will be used. 3588 container transfer { 3589 choice how { 3590 default interval; 3591 case interval { 3592 leaf interval { 3593 type uint16; 3594 default 30; 3595 units minutes; 3596 } 3597 } 3598 case daily { 3599 leaf daily { 3600 type empty; 3601 } 3602 leaf time-of-day { 3603 type string; 3604 units 24-hour-clock; 3605 default 1am; 3606 } 3607 } 3608 case manual { 3609 leaf manual { 3610 type empty; 3611 } 3612 } 3613 } 3614 } 3616 7.9.4. The choice's mandatory Statement 3618 The "mandatory" statement, which is optional, takes as an argument 3619 the string "true" or "false", and puts a constraint on valid data. 3620 If "mandatory" is "true", at least one node from exactly one of the 3621 choice's case branches MUST exist. 3623 If not specified, the default is "false". 3625 The behavior of the constraint depends on the type of the choice's 3626 closest ancestor node in the schema tree which is not a non-presence 3627 container (see Section 7.5.1): 3629 o If this ancestor is a case node, the constraint is enforced if any 3630 other node from the case exists. 3632 o Otherwise, it is enforced if the ancestor node exists. 3634 The constraint is further enforced according to the rules in 3635 Section 8. 3637 7.9.5. XML Mapping Rules 3639 The choice and case nodes are not visible in XML. 3641 The child nodes of the selected "case" statement MUST be encoded in 3642 the same order as they are defined in the "case" statement if they 3643 are part of an RPC input or output parameter definition. Otherwise, 3644 the subelements are encoded in any order. 3646 7.9.6. NETCONF Operations 3648 Since only one of the choice's cases can be valid at any time, the 3649 creation of a node from one case implicitly deletes all nodes from 3650 all other cases. If an operation creates a node from a 3651 case, the NETCONF server will delete any existing nodes that are 3652 defined in other cases inside the choice. 3654 7.9.7. Usage Example 3656 Given the following choice: 3658 container protocol { 3659 choice name { 3660 case a { 3661 leaf udp { 3662 type empty; 3663 } 3664 } 3665 case b { 3666 leaf tcp { 3667 type empty; 3668 } 3669 } 3670 } 3671 } 3673 A corresponding XML instance example: 3675 3676 3677 3679 To change the protocol from tcp to udp: 3681 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3698 7.10. The anyxml Statement 3700 The "anyxml" statement defines an interior node in the schema tree. 3701 It takes one argument, which is an identifier, followed by a block of 3702 substatements that holds detailed anyxml information. 3704 The "anyxml" statement is used to represent an unknown chunk of XML. 3705 No restrictions are placed on the XML. This can be useful, for 3706 example, in RPC replies. An example is the parameter in the 3707 operation. 3709 An anyxml node cannot be augmented (see Section 7.16). 3711 Since the use of anyxml limits the manipulation of the content, it is 3712 RECOMMENDED that the "anyxml" statement not be used to represent 3713 configuration data. 3715 An anyxml node exists in zero or one instances in the data tree. 3717 7.10.1. The anyxml's Substatements 3719 +--------------+---------+-------------+ 3720 | substatement | section | cardinality | 3721 +--------------+---------+-------------+ 3722 | config | 7.20.1 | 0..1 | 3723 | description | 7.20.3 | 0..1 | 3724 | if-feature | 7.19.2 | 0..n | 3725 | mandatory | 7.6.5 | 0..1 | 3726 | must | 7.5.3 | 0..n | 3727 | reference | 7.20.4 | 0..1 | 3728 | status | 7.20.2 | 0..1 | 3729 | when | 7.20.5 | 0..1 | 3730 +--------------+---------+-------------+ 3732 7.10.2. XML Mapping Rules 3734 An anyxml node is encoded as an XML element. The element's local 3735 name is the anyxml's identifier, and its namespace is the module's 3736 XML namespace (see Section 7.1.3). The value of the anyxml node is 3737 encoded as XML content of this element. 3739 Note that any prefixes used in the encoding are local to each 3740 instance encoding. This means that the same XML may be encoded 3741 differently by different implementations. 3743 7.10.3. NETCONF Operations 3745 An anyxml node is treated as an opaque chunk of data. This data can 3746 be modified in its entirety only. 3748 Any "operation" attributes present on subelements of an anyxml node 3749 are ignored by the NETCONF server. 3751 When a NETCONF server processes an request, the 3752 elements of procedure for the anyxml node are: 3754 If the operation is "merge" or "replace", the node is created if 3755 it does not exist, and its value is set to the XML content of the 3756 anyxml node found in the XML RPC data. 3758 If the operation is "create", the node is created if it does not 3759 exist, and its value is set to the XML content of the anyxml node 3760 found in the XML RPC data. If the node already exists, a 3761 "data-exists" error is returned. 3763 If the operation is "delete", the node is deleted if it exists. 3764 If the node does not exist, a "data-missing" error is returned. 3766 7.10.4. Usage Example 3768 Given the following "anyxml" statement: 3770 anyxml data; 3772 The following are two valid encodings of the same anyxml value: 3774 3775 3776 1 3777 3778 3780 3781 3782 1 3783 3784 3786 7.11. The grouping Statement 3788 The "grouping" statement is used to define a reusable block of nodes, 3789 which may be used locally in the module or submodule, and by other 3790 modules that import from it, according to the rules in Section 5.5. 3791 It takes one argument, which is an identifier, followed by a block of 3792 substatements that holds detailed grouping information. 3794 The "grouping" statement is not a data definition statement and, as 3795 such, does not define any nodes in the schema tree. 3797 A grouping is like a "structure" or a "record" in conventional 3798 programming languages. 3800 Once a grouping is defined, it can be referenced in a "uses" 3801 statement (see Section 7.12). A grouping MUST NOT reference itself, 3802 neither directly nor indirectly through a chain of other groupings. 3804 If the grouping is defined at the top level of a YANG module or 3805 submodule, the grouping's identifier MUST be unique within the 3806 module. 3808 A grouping is more than just a mechanism for textual substitution, 3809 but defines a collection of nodes. Identifiers appearing inside the 3810 grouping are resolved relative to the scope in which the grouping is 3811 defined, not where it is used. Prefix mappings, type names, grouping 3812 names, and extension usage are evaluated in the hierarchy where the 3813 "grouping" statement appears. For extensions, this means that 3814 extensions are applied to the grouping node, not the uses node. 3816 7.11.1. The grouping's Substatements 3818 +--------------+---------+-------------+ 3819 | substatement | section | cardinality | 3820 +--------------+---------+-------------+ 3821 | action | 7.14 | 0..n | 3822 | anyxml | 7.10 | 0..n | 3823 | choice | 7.9 | 0..n | 3824 | container | 7.5 | 0..n | 3825 | description | 7.20.3 | 0..1 | 3826 | grouping | 7.11 | 0..n | 3827 | leaf | 7.6 | 0..n | 3828 | leaf-list | 7.7 | 0..n | 3829 | list | 7.8 | 0..n | 3830 | reference | 7.20.4 | 0..1 | 3831 | status | 7.20.2 | 0..1 | 3832 | typedef | 7.3 | 0..n | 3833 | uses | 7.12 | 0..n | 3834 +--------------+---------+-------------+ 3836 7.11.2. Usage Example 3837 import ietf-inet-types { 3838 prefix "inet"; 3839 } 3841 grouping endpoint { 3842 description "A reusable endpoint group."; 3843 leaf ip { 3844 type inet:ip-address; 3845 } 3846 leaf port { 3847 type inet:port-number; 3848 } 3849 } 3851 7.12. The uses Statement 3853 The "uses" statement is used to reference a "grouping" definition. 3854 It takes one argument, which is the name of the grouping. 3856 The effect of a "uses" reference to a grouping is that the nodes 3857 defined by the grouping are copied into the current schema tree, and 3858 then updated according to the "refine" and "augment" statements. 3860 The identifiers defined in the grouping are not bound to a namespace 3861 until the contents of the grouping are added to the schema tree via a 3862 "uses" statement that does not appear inside a "grouping" statement, 3863 at which point they are bound to the namespace of the current module. 3865 7.12.1. The uses's Substatements 3867 +--------------+---------+-------------+ 3868 | substatement | section | cardinality | 3869 +--------------+---------+-------------+ 3870 | augment | 7.16 | 0..n | 3871 | description | 7.20.3 | 0..1 | 3872 | if-feature | 7.19.2 | 0..n | 3873 | refine | 7.12.2 | 0..n | 3874 | reference | 7.20.4 | 0..1 | 3875 | status | 7.20.2 | 0..1 | 3876 | when | 7.20.5 | 0..1 | 3877 +--------------+---------+-------------+ 3879 7.12.2. The refine Statement 3881 Some of the properties of each node in the grouping can be refined 3882 with the "refine" statement. The argument is a string that 3883 identifies a node in the grouping. This node is called the refine's 3884 target node. If a node in the grouping is not present as a target 3885 node of a "refine" statement, it is not refined, and thus used 3886 exactly as it was defined in the grouping. 3888 The argument string is a descendant schema node identifier (see 3889 Section 6.5). 3891 The following refinements can be done: 3893 o A leaf or choice node may get a default value, or a new default 3894 value if it already had one. 3896 o Any node may get a specialized "description" string. 3898 o Any node may get a specialized "reference" string. 3900 o Any node may get a different "config" statement. 3902 o A leaf, anyxml, or choice node may get a different "mandatory" 3903 statement. 3905 o A container node may get a "presence" statement. 3907 o A leaf, leaf-list, list, container, or anyxml node may get 3908 additional "must" expressions. 3910 o A leaf-list or list node may get a different "min-elements" or 3911 "max-elements" statement. 3913 o A leaf, leaf-list, list, container, or anyxml node may get 3914 additional "if-feature" expressions. 3916 7.12.3. XML Mapping Rules 3918 Each node in the grouping is encoded as if it was defined inline, 3919 even if it is imported from another module with another XML 3920 namespace. 3922 7.12.4. Usage Example 3924 To use the "endpoint" grouping defined in Section 7.11.2 in a 3925 definition of an HTTP server in some other module, we can do: 3927 import acme-system { 3928 prefix "acme"; 3929 } 3931 container http-server { 3932 leaf name { 3933 type string; 3934 } 3935 uses acme:endpoint; 3936 } 3938 A corresponding XML instance example: 3940 3941 extern-web 3942 192.0.2.1 3943 80 3944 3946 If port 80 should be the default for the HTTP server, default can be 3947 added: 3949 container http-server { 3950 leaf name { 3951 type string; 3952 } 3953 uses acme:endpoint { 3954 refine port { 3955 default 80; 3956 } 3957 } 3958 } 3960 If we want to define a list of servers, and each server has the ip 3961 and port as keys, we can do: 3963 list server { 3964 key "ip port"; 3965 leaf name { 3966 type string; 3967 } 3968 uses acme:endpoint; 3969 } 3971 The following is an error: 3973 container http-server { 3974 uses acme:endpoint; 3975 leaf ip { // illegal - same identifier "ip" used twice 3976 type string; 3977 } 3978 } 3980 7.13. The rpc Statement 3982 The "rpc" statement is used to define an RPC operation. It takes one 3983 argument, which is an identifier, followed by a block of 3984 substatements that holds detailed rpc information. This argument is 3985 the name of the RPC, and is used as the element name directly under 3986 the element, as designated by the substitution group 3987 "rpcOperation" in [RFC6241]. 3989 The "rpc" statement defines an rpc node in the schema tree. Under 3990 the rpc node, a schema node with the name "input", and a schema node 3991 with the name "output" are also defined. The nodes "input" and 3992 "output" are defined in the module's namespace. 3994 7.13.1. The rpc's Substatements 3996 +--------------+---------+-------------+ 3997 | substatement | section | cardinality | 3998 +--------------+---------+-------------+ 3999 | description | 7.20.3 | 0..1 | 4000 | grouping | 7.11 | 0..n | 4001 | if-feature | 7.19.2 | 0..n | 4002 | input | 7.13.2 | 0..1 | 4003 | output | 7.13.3 | 0..1 | 4004 | reference | 7.20.4 | 0..1 | 4005 | status | 7.20.2 | 0..1 | 4006 | typedef | 7.3 | 0..n | 4007 +--------------+---------+-------------+ 4009 7.13.2. The input Statement 4011 The "input" statement, which is optional, is used to define input 4012 parameters to the operation. It does not take an argument. The 4013 substatements to "input" define nodes under the operation's input 4014 node. 4016 If a leaf in the input tree has a "mandatory" statement with the 4017 value "true", the leaf MUST be present in a NETCONF RPC invocation. 4018 Otherwise, the server MUST return a "missing-element" error. 4020 If a leaf in the input tree has a default value, the NETCONF server 4021 MUST use this value in the same cases as described in Section 7.6.1. 4022 In these cases, the server MUST operationally behave as if the leaf 4023 was present in the NETCONF RPC invocation with the default value as 4024 its value. 4026 If a leaf-list in the input tree has one or more default values, the 4027 NETCONF server MUST use these values in the same cases as described 4028 in Section 7.7.2. In these cases, the server MUST operationally 4029 behave as if the leaf-list was present in the NETCONF RPC invocation 4030 with the default values as its values. 4032 If a "config" statement is present for any node in the input tree, 4033 the "config" statement is ignored. 4035 If any node has a "when" statement that would evaluate to false, then 4036 this node MUST NOT be present in the input tree. 4038 7.13.2.1. The input's Substatements 4040 +--------------+---------+-------------+ 4041 | substatement | section | cardinality | 4042 +--------------+---------+-------------+ 4043 | anyxml | 7.10 | 0..n | 4044 | choice | 7.9 | 0..n | 4045 | container | 7.5 | 0..n | 4046 | grouping | 7.11 | 0..n | 4047 | leaf | 7.6 | 0..n | 4048 | leaf-list | 7.7 | 0..n | 4049 | list | 7.8 | 0..n | 4050 | must | 7.5.3 | 0..n | 4051 | typedef | 7.3 | 0..n | 4052 | uses | 7.12 | 0..n | 4053 +--------------+---------+-------------+ 4055 7.13.3. The output Statement 4057 The "output" statement, which is optional, is used to define output 4058 parameters to the RPC operation. It does not take an argument. The 4059 substatements to "output" define nodes under the operation's output 4060 node. 4062 If a leaf in the output tree has a "mandatory" statement with the 4063 value "true", the leaf MUST be present in a NETCONF RPC reply. 4065 If a leaf in the output tree has a default value, the NETCONF client 4066 MUST use this value in the same cases as described in Section 7.6.1. 4067 In these cases, the client MUST operationally behave as if the leaf 4068 was present in the NETCONF RPC reply with the default value as its 4069 value. 4071 If a leaf-list in the output tree has one or more default values, the 4072 NETCONF client MUST use these values in the same cases as described 4073 in Section 7.7.2. In these cases, the client MUST operationally 4074 behave as if the leaf-list was present in the NETCONF RPC reply with 4075 the default values as its values. 4077 If a "config" statement is present for any node in the output tree, 4078 the "config" statement is ignored. 4080 If any node has a "when" statement that would evaluate to false, then 4081 this node MUST NOT be present in the output tree. 4083 7.13.3.1. The output's Substatements 4085 +--------------+---------+-------------+ 4086 | substatement | section | cardinality | 4087 +--------------+---------+-------------+ 4088 | anyxml | 7.10 | 0..n | 4089 | choice | 7.9 | 0..n | 4090 | container | 7.5 | 0..n | 4091 | grouping | 7.11 | 0..n | 4092 | leaf | 7.6 | 0..n | 4093 | leaf-list | 7.7 | 0..n | 4094 | list | 7.8 | 0..n | 4095 | must | 7.5.3 | 0..n | 4096 | typedef | 7.3 | 0..n | 4097 | uses | 7.12 | 0..n | 4098 +--------------+---------+-------------+ 4100 7.13.4. XML Mapping Rules 4102 An rpc node is encoded as a child XML element to the element 4103 defined in [RFC6241]. The element's local name is the rpc's 4104 identifier, and its namespace is the module's XML namespace (see 4105 Section 7.1.3). 4107 Input parameters are encoded as child XML elements to the rpc node's 4108 XML element, in the same order as they are defined within the "input" 4109 statement. 4111 If the RPC operation invocation succeeded, and no output parameters 4112 are returned, the contains a single element defined 4113 in [RFC6241]. If output parameters are returned, they are encoded as 4114 child elements to the element defined in [RFC6241], in 4115 the same order as they are defined within the "output" statement. 4117 7.13.5. Usage Example 4119 The following example defines an RPC operation: 4121 module rock { 4122 yang-version 1.1; 4123 namespace "http://example.net/rock"; 4124 prefix "rock"; 4126 rpc rock-the-house { 4127 input { 4128 leaf zip-code { 4129 type string; 4130 } 4131 } 4132 } 4133 } 4135 A corresponding XML instance example of the complete rpc and rpc- 4136 reply: 4138 4140 4141 27606-0100 4142 4143 4145 4147 4148 4150 7.14. The action Statement 4152 The "action" statement is used to define an operation connected to a 4153 specific container or list data node. It takes one argument, which 4154 is an identifier, followed by a block of substatements that holds 4155 detailed action information. The argument is the name of the action. 4157 The "action" statement defines an action node in the schema tree. 4158 Under the action node, a schema node with the name "input", and a 4159 schema node with the name "output" are also defined. The nodes 4160 "input" and "output" are defined in the module's namespace. 4162 An action MUST NOT be defined within an rpc, another action or a 4163 notification, i.e., an action node MUST NOT have an rpc, action, or a 4164 notification node as one of its ancestors in the schema tree. For 4165 example, this means that it is an error if a grouping that contains 4166 an action is used in a notification definition. 4168 The difference between an action and an rpc is that an action is tied 4169 to a node in the data tree, whereas an rpc is not. When an action is 4170 invoked, the node in the data tree is specified along with the name 4171 of the action and the input parameters. 4173 7.14.1. The action's Substatements 4175 +--------------+---------+-------------+ 4176 | substatement | section | cardinality | 4177 +--------------+---------+-------------+ 4178 | description | 7.20.3 | 0..1 | 4179 | grouping | 7.11 | 0..n | 4180 | if-feature | 7.19.2 | 0..n | 4181 | input | 7.13.2 | 0..1 | 4182 | output | 7.13.3 | 0..1 | 4183 | reference | 7.20.4 | 0..1 | 4184 | status | 7.20.2 | 0..1 | 4185 | typedef | 7.3 | 0..n | 4186 +--------------+---------+-------------+ 4188 7.14.2. XML Mapping Rules 4190 When an action is invoked, an element with the local name "action" in 4191 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4192 encoded as a child XML element to the element defined in 4193 [RFC6241], as designated by the substitution group "rpcOperation" in 4194 [RFC6241]. 4196 The "action" element contains an hierarchy of nodes that identifies 4197 the node in the data tree. It MUST contain all containers and list 4198 nodes from the top level down to the list or container containing the 4199 action. For lists, all key leafs MUST also be included. The last 4200 container or list contains an XML element that carries the name of 4201 the defined action. Within this element the input parameters are 4202 encoded as child XML elements, in the same order as they are defined 4203 within the "input" statement. 4205 Only one action can be invoked in one . If more than one 4206 actions are present in the , the server MUST reply with an 4207 "bad-element" error-tag in the . 4209 If the action operation invocation succeeded, and no output 4210 parameters are returned, the contains a single 4211 element defined in [RFC6241]. If output parameters are returned, 4212 they are encoded as child elements to the element defined 4213 in [RFC6241], in the same order as they are defined within the 4214 "output" statement. 4216 7.14.3. Usage Example 4218 The following example defines an action to reset one server at a 4219 server farm: 4221 module server-farm { 4222 yang-version 1.1; 4223 namespace "http://example.net/server-farm"; 4224 prefix "sfarm"; 4226 import ietf-yang-types { 4227 prefix "yang"; 4228 } 4230 list server { 4231 key name; 4232 leaf name { 4233 type string; 4234 } 4235 action reset { 4236 input { 4237 leaf reset-at { 4238 type yang:date-and-time; 4239 mandatory true; 4240 } 4241 } 4242 output { 4243 leaf reset-finished-at { 4244 type yang:date-and-time; 4245 mandatory true; 4246 } 4247 } 4248 } 4249 } 4250 } 4252 A corresponding XML instance example of the complete rpc and rpc- 4253 reply: 4255 4257 4258 4259 apache-1 4260 4261 2014-07-29T13:42:00Z 4262 4263 4264 4265 4267 4269 4270 2014-07-29T13:42:12Z 4271 4272 4274 7.15. The notification Statement 4276 The "notification" statement is used to define a NETCONF 4277 notification. It takes one argument, which is an identifier, 4278 followed by a block of substatements that holds detailed notification 4279 information. The "notification" statement defines a notification 4280 node in the schema tree. 4282 If a leaf in the notification tree has a "mandatory" statement with 4283 the value "true", the leaf MUST be present in a NETCONF notification. 4285 If a leaf in the notification tree has a default value, the NETCONF 4286 client MUST use this value in the same cases as described in 4287 Section 7.6.1. In these cases, the client MUST operationally behave 4288 as if the leaf was present in the NETCONF notification with the 4289 default value as its value. 4291 If a leaf-list in the notification tree has one or more default 4292 values, the NETCONF client MUST use these values in the same cases as 4293 described in Section 7.7.2. In these cases, the client MUST 4294 operationally behave as if the leaf-list was present in the NETCONF 4295 notification with the default values as its values. 4297 If a "config" statement is present for any node in the notification 4298 tree, the "config" statement is ignored. 4300 7.15.1. The notification's Substatements 4302 +--------------+---------+-------------+ 4303 | substatement | section | cardinality | 4304 +--------------+---------+-------------+ 4305 | anyxml | 7.10 | 0..n | 4306 | choice | 7.9 | 0..n | 4307 | container | 7.5 | 0..n | 4308 | description | 7.20.3 | 0..1 | 4309 | grouping | 7.11 | 0..n | 4310 | if-feature | 7.19.2 | 0..n | 4311 | leaf | 7.6 | 0..n | 4312 | leaf-list | 7.7 | 0..n | 4313 | list | 7.8 | 0..n | 4314 | must | 7.5.3 | 0..n | 4315 | reference | 7.20.4 | 0..1 | 4316 | status | 7.20.2 | 0..1 | 4317 | typedef | 7.3 | 0..n | 4318 | uses | 7.12 | 0..n | 4319 +--------------+---------+-------------+ 4321 7.15.2. XML Mapping Rules 4323 A notification node is encoded as a child XML element to the 4324 element defined in NETCONF Event Notifications 4325 [RFC5277]. The element's local name is the notification's 4326 identifier, and its namespace is the module's XML namespace (see 4327 Section 7.1.3). 4329 7.15.3. Usage Example 4331 The following example defines a notification: 4333 module event { 4334 yang-version 1.1; 4335 namespace "http://example.com/event"; 4336 prefix "ev"; 4338 notification event { 4339 leaf event-class { 4340 type string; 4341 } 4342 anyxml reporting-entity; 4343 leaf severity { 4344 type string; 4345 } 4346 } 4347 } 4349 A corresponding XML instance example of the complete notification: 4351 4353 2008-07-08T00:01:00Z 4354 4355 fault 4356 4357 Ethernet0 4358 4359 major 4360 4361 4363 7.16. The augment Statement 4365 The "augment" statement allows a module or submodule to add to the 4366 schema tree defined in an external module, or the current module and 4367 its submodules, and to add to the nodes from a grouping in a "uses" 4368 statement. The argument is a string that identifies a node in the 4369 schema tree. This node is called the augment's target node. The 4370 target node MUST be either a container, list, choice, case, input, 4371 output, or notification node. It is augmented with the nodes defined 4372 in the substatements that follow the "augment" statement. 4374 The argument string is a schema node identifier (see Section 6.5). 4375 If the "augment" statement is on the top level in a module or 4376 submodule, the absolute form (defined by the rule 4377 "absolute-schema-nodeid" in Section 13) of a schema node identifier 4378 MUST be used. If the "augment" statement is a substatement to the 4379 "uses" statement, the descendant form (defined by the rule 4380 "descendant-schema-nodeid" in Section 13) MUST be used. 4382 If the target node is a container, list, case, input, output, or 4383 notification node, the "container", "leaf", "list", "leaf-list", 4384 "uses", and "choice" statements can be used within the "augment" 4385 statement. 4387 If the target node is a choice node, the "case" statement, or a case 4388 shorthand statement (see Section 7.9.2) can be used within the 4389 "augment" statement. 4391 If the target node is in another module, then nodes added by the 4392 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4394 The "augment" statement MUST NOT add multiple nodes with the same 4395 name from the same module to the target node. 4397 7.16.1. The augment's Substatements 4399 +--------------+---------+-------------+ 4400 | substatement | section | cardinality | 4401 +--------------+---------+-------------+ 4402 | action | 7.14 | 0..n | 4403 | anyxml | 7.10 | 0..n | 4404 | case | 7.9.2 | 0..n | 4405 | choice | 7.9 | 0..n | 4406 | container | 7.5 | 0..n | 4407 | description | 7.20.3 | 0..1 | 4408 | if-feature | 7.19.2 | 0..n | 4409 | leaf | 7.6 | 0..n | 4410 | leaf-list | 7.7 | 0..n | 4411 | list | 7.8 | 0..n | 4412 | reference | 7.20.4 | 0..1 | 4413 | status | 7.20.2 | 0..1 | 4414 | uses | 7.12 | 0..n | 4415 | when | 7.20.5 | 0..1 | 4416 +--------------+---------+-------------+ 4418 7.16.2. XML Mapping Rules 4420 All data nodes defined in the "augment" statement are defined as XML 4421 elements in the XML namespace of the module where the "augment" is 4422 specified. 4424 When a node is augmented, the augmenting child nodes are encoded as 4425 subelements to the augmented node, in any order. 4427 7.16.3. Usage Example 4429 In namespace http://example.com/schema/interfaces, we have: 4431 container interfaces { 4432 list ifEntry { 4433 key "ifIndex"; 4435 leaf ifIndex { 4436 type uint32; 4437 } 4438 leaf ifDescr { 4439 type string; 4440 } 4441 leaf ifType { 4442 type iana:IfType; 4443 } 4444 leaf ifMtu { 4445 type int32; 4446 } 4447 } 4448 } 4450 Then, in namespace http://example.com/schema/ds0, we have: 4452 import interface-module { 4453 prefix "if"; 4454 } 4455 augment "/if:interfaces/if:ifEntry" { 4456 when "if:ifType='ds0'"; 4457 leaf ds0ChannelNumber { 4458 type ChannelNumber; 4459 } 4460 } 4462 A corresponding XML instance example: 4464 4466 4467 1 4468 Flintstone Inc Ethernet A562 4469 ethernetCsmacd 4470 1500 4471 4472 4473 2 4474 Flintstone Inc DS0 4475 ds0 4476 1 4477 4478 4480 As another example, suppose we have the choice defined in 4481 Section 7.9.7. The following construct can be used to extend the 4482 protocol definition: 4484 augment /ex:system/ex:protocol/ex:name { 4485 case c { 4486 leaf smtp { 4487 type empty; 4488 } 4489 } 4490 } 4492 A corresponding XML instance example: 4494 4495 4496 4497 4498 4500 or 4502 4503 4504 4505 4506 4508 7.17. The identity Statement 4510 The "identity" statement is used to define a new globally unique, 4511 abstract, and untyped identity. Its only purpose is to denote its 4512 name, semantics, and existence. An identity can either be defined 4513 from scratch or derived from one or more base identities. The 4514 identity's argument is an identifier that is the name of the 4515 identity. It is followed by a block of substatements that holds 4516 detailed identity information. 4518 The built-in datatype "identityref" (see Section 9.10) can be used to 4519 reference identities within a data model. 4521 7.17.1. The identity's Substatements 4522 +--------------+---------+-------------+ 4523 | substatement | section | cardinality | 4524 +--------------+---------+-------------+ 4525 | base | 7.17.2 | 0..n | 4526 | description | 7.20.3 | 0..1 | 4527 | if-feature | 7.19.2 | 0..n | 4528 | reference | 7.20.4 | 0..1 | 4529 | status | 7.20.2 | 0..1 | 4530 +--------------+---------+-------------+ 4532 7.17.2. The base Statement 4534 The "base" statement, which is optional, takes as an argument a 4535 string that is the name of an existing identity, from which the new 4536 identity is derived. If no "base" statement is present, the identity 4537 is defined from scratch. If multiple "base" statements are present, 4538 the identity is derived from all of them. 4540 If a prefix is present on the base name, it refers to an identity 4541 defined in the module that was imported with that prefix, or the 4542 local module if the prefix matches the local module's prefix. 4543 Otherwise, an identity with the matching name MUST be defined in the 4544 current module or an included submodule. 4546 An identity MUST NOT reference itself, neither directly nor 4547 indirectly through a chain of other identities. 4549 The derivation of identities has the following properties: 4551 o It is irreflexive, which means that an identity is not derived 4552 from itself. 4554 o It is transitive, which means that if identity B is derived from A 4555 and C is derived from B, then C is also derived from A. 4557 7.17.3. Usage Example 4558 module crypto-base { 4559 yang-version 1.1; 4560 namespace "http://example.com/crypto-base"; 4561 prefix "crypto"; 4563 identity crypto-alg { 4564 description 4565 "Base identity from which all crypto algorithms 4566 are derived."; 4567 } 4568 } 4570 module des { 4571 yang-version 1.1; 4572 namespace "http://example.com/des"; 4573 prefix "des"; 4575 import "crypto-base" { 4576 prefix "crypto"; 4577 } 4579 identity des { 4580 base "crypto:crypto-alg"; 4581 description "DES crypto algorithm"; 4582 } 4584 identity des3 { 4585 base "crypto:crypto-alg"; 4586 description "Triple DES crypto algorithm"; 4587 } 4588 } 4590 7.18. The extension Statement 4592 The "extension" statement allows the definition of new statements 4593 within the YANG language. This new statement definition can be 4594 imported and used by other modules. 4596 The statement's argument is an identifier that is the new keyword for 4597 the extension and must be followed by a block of substatements that 4598 holds detailed extension information. The purpose of the "extension" 4599 statement is to define a keyword, so that it can be imported and used 4600 by other modules. 4602 The extension can be used like a normal YANG statement, with the 4603 statement name followed by an argument if one is defined by the 4604 "extension" statement, and an optional block of substatements. The 4605 statement's name is created by combining the prefix of the module in 4606 which the extension was defined, a colon (":"), and the extension's 4607 keyword, with no interleaving whitespace. The substatements of an 4608 extension are defined by the "extension" statement, using some 4609 mechanism outside the scope of this specification. Syntactically, 4610 the substatements MUST be YANG statements, or also extensions defined 4611 using "extension" statements. YANG statements in extensions MUST 4612 follow the syntactical rules in Section 13. 4614 7.18.1. The extension's Substatements 4616 +--------------+---------+-------------+ 4617 | substatement | section | cardinality | 4618 +--------------+---------+-------------+ 4619 | argument | 7.18.2 | 0..1 | 4620 | description | 7.20.3 | 0..1 | 4621 | reference | 7.20.4 | 0..1 | 4622 | status | 7.20.2 | 0..1 | 4623 +--------------+---------+-------------+ 4625 7.18.2. The argument Statement 4627 The "argument" statement, which is optional, takes as an argument a 4628 string that is the name of the argument to the keyword. If no 4629 argument statement is present, the keyword expects no argument when 4630 it is used. 4632 The argument's name is used in the YIN mapping, where it is used as 4633 an XML attribute or element name, depending on the argument's 4634 "yin-element" statement. 4636 7.18.2.1. The argument's Substatements 4638 +--------------+----------+-------------+ 4639 | substatement | section | cardinality | 4640 +--------------+----------+-------------+ 4641 | yin-element | 7.18.2.2 | 0..1 | 4642 +--------------+----------+-------------+ 4644 7.18.2.2. The yin-element Statement 4646 The "yin-element" statement, which is optional, takes as an argument 4647 the string "true" or "false". This statement indicates if the 4648 argument is mapped to an XML element in YIN or to an XML attribute 4649 (see Section 12). 4651 If no "yin-element" statement is present, it defaults to "false". 4653 7.18.3. Usage Example 4655 To define an extension: 4657 module my-extensions { 4658 ... 4660 extension c-define { 4661 description 4662 "Takes as argument a name string. 4663 Makes the code generator use the given name in the 4664 #define."; 4665 argument "name"; 4666 } 4667 } 4669 To use the extension: 4671 module my-interfaces { 4672 ... 4673 import my-extensions { 4674 prefix "myext"; 4675 } 4676 ... 4678 container interfaces { 4679 ... 4680 myext:c-define "MY_INTERFACES"; 4681 } 4682 } 4684 7.19. Conformance-Related Statements 4686 This section defines statements related to conformance, as described 4687 in Section 5.6. 4689 7.19.1. The feature Statement 4691 The "feature" statement is used to define a mechanism by which 4692 portions of the schema are marked as conditional. A feature name is 4693 defined that can later be referenced using the "if-feature" statement 4694 (see Section 7.19.2). Schema nodes tagged with an "if-feature" 4695 statement are ignored by the device unless the device supports the 4696 given feature expression. This allows portions of the YANG module to 4697 be conditional based on conditions on the device. The model can 4698 represent the abilities of the device within the model, giving a 4699 richer model that allows for differing device abilities and roles. 4701 The argument to the "feature" statement is the name of the new 4702 feature, and follows the rules for identifiers in Section 6.2. This 4703 name is used by the "if-feature" statement to tie the schema nodes to 4704 the feature. 4706 In this example, a feature called "local-storage" represents the 4707 ability for a device to store syslog messages on local storage of 4708 some sort. This feature is used to make the "local-storage-limit" 4709 leaf conditional on the presence of some sort of local storage. If 4710 the device does not report that it supports this feature, the 4711 "local-storage-limit" node is not supported. 4713 module syslog { 4714 ... 4715 feature local-storage { 4716 description 4717 "This feature means the device supports local 4718 storage (memory, flash or disk) that can be used to 4719 store syslog messages."; 4720 } 4722 container syslog { 4723 leaf local-storage-limit { 4724 if-feature local-storage; 4725 type uint64; 4726 units "kilobyte"; 4727 config false; 4728 description 4729 "The amount of local storage that can be 4730 used to hold syslog messages."; 4731 } 4732 } 4733 } 4735 The "if-feature" statement can be used in many places within the YANG 4736 syntax. Definitions tagged with "if-feature" are ignored when the 4737 device does not support that feature. 4739 A feature MUST NOT reference itself, neither directly nor indirectly 4740 through a chain of other features. 4742 In order for a device to implement a feature that is dependent on any 4743 other features (i.e., the feature has one or more "if-feature" 4744 substatements), the device MUST also implement all the dependant 4745 features. 4747 7.19.1.1. The feature's Substatements 4749 +--------------+---------+-------------+ 4750 | substatement | section | cardinality | 4751 +--------------+---------+-------------+ 4752 | description | 7.20.3 | 0..1 | 4753 | if-feature | 7.19.2 | 0..n | 4754 | status | 7.20.2 | 0..1 | 4755 | reference | 7.20.4 | 0..1 | 4756 +--------------+---------+-------------+ 4758 7.19.2. The if-feature Statement 4760 The "if-feature" statement makes its parent statement conditional. 4761 The argument is a boolean expression over feature names. In this 4762 expression, a feature name evaluates to "true" if and only if the 4763 feature is implemented by the server. The parent statement is 4764 implemented by servers where the boolean expression evaluates to 4765 "true". 4767 The if-feature boolean expression syntax is formally defined by the 4768 rule "if-feature-expr" in Section 13. When this boolean expression 4769 is evaluated, the operator order of precedence is (highest precedence 4770 first): "not", "and", "or". 4772 If a prefix is present on a feature name in the boolean expression, 4773 the prefixed name refers to a feature defined in the module that was 4774 imported with that prefix, or the local module if the prefix matches 4775 the local module's prefix. Otherwise, a feature with the matching 4776 name MUST be defined in the current module or an included submodule. 4778 A leaf that is a list key MUST NOT have any "if-feature" statements, 4779 unless the conditions specified in the "if-feature" statements are 4780 the same as the "if-feature" conditions in effect on the leaf's 4781 parent node. 4783 7.19.2.1. Usage Example 4785 In this example, the container "target" is implemented if any of the 4786 features "outbound-tls" or "outbound-ssh" is implemented by the 4787 server. 4789 container target { 4790 if-feature "outbound-tls or outbound-ssh"; 4791 ... 4792 } 4794 7.19.3. The deviation Statement 4796 The "deviation" statement defines a hierarchy of a module that the 4797 device does not implement faithfully. The argument is a string that 4798 identifies the node in the schema tree where a deviation from the 4799 module occurs. This node is called the deviation's target node. The 4800 contents of the "deviation" statement give details about the 4801 deviation. 4803 The argument string is an absolute schema node identifier (see 4804 Section 6.5). 4806 Deviations define the way a device or class of devices deviate from a 4807 standard. This means that deviations MUST never be part of a 4808 published standard, since they are the mechanism for learning how 4809 implementations vary from the standards. 4811 Device deviations are strongly discouraged and MUST only be used as a 4812 last resort. Telling the application how a device fails to follow a 4813 standard is no substitute for implementing the standard correctly. A 4814 device that deviates from a module is not fully compliant with the 4815 module. 4817 However, in some cases, a particular device may not have the hardware 4818 or software ability to support parts of a standard module. When this 4819 occurs, the device makes a choice either to treat attempts to 4820 configure unsupported parts of the module as an error that is 4821 reported back to the unsuspecting application or ignore those 4822 incoming requests. Neither choice is acceptable. 4824 Instead, YANG allows devices to document portions of a base module 4825 that are not supported or supported but with different syntax, by 4826 using the "deviation" statement. 4828 7.19.3.1. The deviation's Substatements 4830 +--------------+----------+-------------+ 4831 | substatement | section | cardinality | 4832 +--------------+----------+-------------+ 4833 | description | 7.20.3 | 0..1 | 4834 | deviate | 7.19.3.2 | 1..n | 4835 | reference | 7.20.4 | 0..1 | 4836 +--------------+----------+-------------+ 4838 7.19.3.2. The deviate Statement 4840 The "deviate" statement defines how the device's implementation of 4841 the target node deviates from its original definition. The argument 4842 is one of the strings "not-supported", "add", "replace", or "delete". 4844 The argument "not-supported" indicates that the target node is not 4845 implemented by this device. 4847 The argument "add" adds properties to the target node. The 4848 properties to add are identified by substatements to the "deviate" 4849 statement. If a property can only appear once, the property MUST NOT 4850 exist in the target node. 4852 The argument "replace" replaces properties of the target node. The 4853 properties to replace are identified by substatements to the 4854 "deviate" statement. The properties to replace MUST exist in the 4855 target node. 4857 The argument "delete" deletes properties from the target node. The 4858 properties to delete are identified by substatements to the "delete" 4859 statement. The substatement's keyword MUST match a corresponding 4860 keyword in the target node, and the argument's string MUST be equal 4861 to the corresponding keyword's argument string in the target node. 4863 +--------------+-------------+-------------+ 4864 | substatement | section | cardinality | 4865 +--------------+-------------+-------------+ 4866 | config | 7.20.1 | 0..1 | 4867 | default | 7.6.4 7.7.4 | 0..n | 4868 | mandatory | 7.6.5 | 0..1 | 4869 | max-elements | 7.7.6 | 0..1 | 4870 | min-elements | 7.7.5 | 0..1 | 4871 | must | 7.5.3 | 0..n | 4872 | type | 7.4 | 0..1 | 4873 | unique | 7.8.3 | 0..n | 4874 | units | 7.3.3 | 0..1 | 4875 +--------------+-------------+-------------+ 4877 The deviate's Substatements 4879 7.19.3.3. Usage Example 4881 In this example, the device is informing client applications that it 4882 does not support the "daytime" service in the style of RFC 867. 4884 deviation /base:system/base:daytime { 4885 deviate not-supported; 4886 } 4888 The following example sets a device-specific default value to a leaf 4889 that does not have a default value defined: 4891 deviation /base:system/base:user/base:type { 4892 deviate add { 4893 default "admin"; // new users are 'admin' by default 4894 } 4895 } 4897 In this example, the device limits the number of name servers to 3: 4899 deviation /base:system/base:name-server { 4900 deviate replace { 4901 max-elements 3; 4902 } 4903 } 4905 If the original definition is: 4907 container system { 4908 must "daytime or time"; 4909 ... 4910 } 4912 a device might remove this must constraint by doing: 4914 deviation "/base:system" { 4915 deviate delete { 4916 must "daytime or time"; 4917 } 4918 } 4920 7.20. Common Statements 4922 This section defines substatements common to several other 4923 statements. 4925 7.20.1. The config Statement 4927 The "config" statement takes as an argument the string "true" or 4928 "false". If "config" is "true", the definition represents 4929 configuration. Data nodes representing configuration will be part of 4930 the reply to a request, and can be sent in a 4931 or request. 4933 If "config" is "false", the definition represents state data. Data 4934 nodes representing state data will be part of the reply to a , 4935 but not to a request, and cannot be sent in a 4936 or request. 4938 If "config" is not specified, the default is the same as the parent 4939 schema node's "config" value. If the parent node is a "case" node, 4940 the value is the same as the "case" node's parent "choice" node. 4942 If the top node does not specify a "config" statement, the default is 4943 "true". 4945 If a node has "config" set to "false", no node underneath it can have 4946 "config" set to "true". 4948 7.20.2. The status Statement 4950 The "status" statement takes as an argument one of the strings 4951 "current", "deprecated", or "obsolete". 4953 o "current" means that the definition is current and valid. 4955 o "deprecated" indicates an obsolete definition, but it permits new/ 4956 continued implementation in order to foster interoperability with 4957 older/existing implementations. 4959 o "obsolete" means the definition is obsolete and SHOULD NOT be 4960 implemented and/or can be removed from implementations. 4962 If no status is specified, the default is "current". 4964 If a definition is "current", it MUST NOT reference a "deprecated" or 4965 "obsolete" definition within the same module. 4967 If a definition is "deprecated", it MUST NOT reference an "obsolete" 4968 definition within the same module. 4970 For example, the following is illegal: 4972 typedef my-type { 4973 status deprecated; 4974 type int32; 4975 } 4977 leaf my-leaf { 4978 status current; 4979 type my-type; // illegal, since my-type is deprecated 4980 } 4982 7.20.3. The description Statement 4984 The "description" statement takes as an argument a string that 4985 contains a human-readable textual description of this definition. 4986 The text is provided in a language (or languages) chosen by the 4987 module developer; for the sake of interoperability, it is RECOMMENDED 4988 to choose a language that is widely understood among the community of 4989 network administrators who will use the module. 4991 7.20.4. The reference Statement 4993 The "reference" statement takes as an argument a string that is used 4994 to specify a textual cross-reference to an external document, either 4995 another module that defines related management information, or a 4996 document that provides additional information relevant to this 4997 definition. 4999 For example, a typedef for a "uri" data type could look like: 5001 typedef uri { 5002 type string; 5003 reference 5004 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5005 ... 5006 } 5008 7.20.5. The when Statement 5010 The "when" statement makes its parent data definition statement 5011 conditional. The node defined by the parent data definition 5012 statement is only valid when the condition specified by the "when" 5013 statement is satisfied. The statement's argument is an XPath 5014 expression (see Section 6.4), which is used to formally specify this 5015 condition. If the XPath expression conceptually evaluates to "true" 5016 for a particular instance, then the node defined by the parent data 5017 definition statement is valid; otherwise, it is not. 5019 A leaf that is a list key MUST NOT have a "when" statement, unless 5020 the condition specified in the "when" statement is the same as the 5021 "when" condition in effect on the leaf's parent node. 5023 See Section 8.3.2 for additional information. 5025 The XPath expression is conceptually evaluated in the following 5026 context, in addition to the definition in Section 6.4.1: 5028 o If the "when" statement is a child of an "augment" statement, then 5029 the context node is the augment's target node in the data tree, if 5030 the target node is a data node. Otherwise, the context node is 5031 the closest ancestor node to the target node that is also a data 5032 node. 5034 o If the "when" statement is a child of a "uses", "choice", or 5035 "case" statement, then the context node is the closest ancestor 5036 node to the "uses", "choice", or "case" node that is also a data 5037 node. 5039 o If the "when" statement is a child of any other data definition 5040 statement, the context node is the node in the accessible tree for 5041 which the "when" statement is defined. 5043 The result of the XPath expression is converted to a boolean value 5044 using the standard XPath rules. 5046 If the XPath expression references any node that also has associated 5047 "when" statements, these "when" expressions MUST be evaluated first. 5048 There MUST NOT be any circular dependencies in these "when" 5049 expressions. 5051 Note that the XPath expression is conceptually evaluated. This means 5052 that an implementation does not have to use an XPath evaluator on the 5053 device. The "when" statement can very well be implemented with 5054 specially written code. 5056 8. Constraints 5058 8.1. Constraints on Data 5060 Several YANG statements define constraints on valid data. These 5061 constraints are enforced in different ways, depending on what type of 5062 data the statement defines. 5064 o If the constraint is defined on configuration data, it MUST be 5065 true in a valid configuration data tree. 5067 o If the constraint is defined on state data, it MUST be true in a 5068 reply to a operation without a filter. 5070 o If the constraint is defined on notification content, it MUST be 5071 true in any notification instance. 5073 o If the constraint is defined on RPC input parameters, it MUST be 5074 true in an invocation of the RPC operation. 5076 o If the constraint is defined on RPC output parameters, it MUST be 5077 true in the RPC reply. 5079 8.2. Hierarchy of Constraints 5081 Conditions on parent nodes affect constraints on child nodes as a 5082 natural consequence of the hierarchy of nodes. "must", "mandatory", 5083 "min-elements", and "max-elements" constraints are not enforced if 5084 the parent node has a "when" or "if-feature" property that is not 5085 satisfied on the current device. 5087 In this example, the "mandatory" constraint on the "longitude" leaf 5088 is not enforced on devices that lack the "has-gps" feature: 5090 container location { 5091 if-feature has-gps; 5092 leaf longitude { 5093 mandatory true; 5094 ... 5095 } 5096 } 5098 8.3. Constraint Enforcement Model 5100 For configuration data, there are three windows when constraints MUST 5101 be enforced: 5103 o during parsing of RPC payloads 5105 o during processing of NETCONF operations 5107 o during validation 5109 Each of these scenarios is considered in the following sections. 5111 8.3.1. Payload Parsing 5113 When content arrives in RPC payloads, it MUST be well-formed XML, 5114 following the hierarchy and content rules defined by the set of 5115 models the device implements. 5117 o If a leaf data value does not match the type constraints for the 5118 leaf, including those defined in the type's "range", "length", and 5119 "pattern" properties, the server MUST reply with an 5120 "invalid-value" error-tag in the rpc-error, and with the error- 5121 app-tag and error-message associated with the constraint, if any 5122 exist. 5124 o If all keys of a list entry are not present, the server MUST reply 5125 with a "missing-element" error-tag in the rpc-error. 5127 o If data for more than one case branch of a choice is present, the 5128 server MUST reply with a "bad-element" in the rpc-error. 5130 o If data for a node tagged with "if-feature" is present, and the 5131 if-feature expression evaluates to "false" on the device, the 5132 server MUST reply with an "unknown-element" error-tag in the rpc- 5133 error. 5135 o If data for a node tagged with "when" is present, and the "when" 5136 condition evaluates to "false", the server MUST reply with an 5137 "unknown-element" error-tag in the rpc-error. 5139 o For insert handling, if the value for the attributes "before" and 5140 "after" are not valid for the type of the appropriate key leafs, 5141 the server MUST reply with a "bad-attribute" error-tag in the rpc- 5142 error. 5144 o If the attributes "before" and "after" appears in any element that 5145 is not a list whose "ordered-by" property is "user", the server 5146 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 5148 8.3.2. NETCONF Processing 5150 After the incoming data is parsed, the NETCONF server performs the 5151 operation by applying the data to the configuration 5152 datastore. During this processing, the following errors MUST be 5153 detected: 5155 o Delete requests for non-existent data. 5157 o Create requests for existent data. 5159 o Insert requests with "before" or "after" parameters that do not 5160 exist. 5162 During processing: 5164 o If the NETCONF operation creates data nodes under a "choice", any 5165 existing nodes from other "case" branches are deleted by the 5166 server. 5168 o If the NETCONF operation modifies a data node such that any node's 5169 "when" expression becomes false, then the node with the "when" 5170 expression is deleted by the server. 5172 8.3.3. Validation 5174 When datastore processing is complete, the final contents MUST obey 5175 all validation constraints. This validation processing is performed 5176 at differing times according to the datastore. If the datastore is 5177 "running" or "startup", these constraints MUST be enforced at the end 5178 of the or operation. If the datastore is 5179 "candidate", the constraint enforcement is delayed until a 5180 or operation. 5182 o Any "must" constraints MUST evaluate to "true". 5184 o Any referential integrity constraints defined via the "path" 5185 statement MUST be satisfied. 5187 o Any "unique" constraints on lists MUST be satisfied. 5189 o The "min-elements" and "max-elements" constraints are enforced for 5190 lists and leaf-lists. 5192 9. Built-In Types 5194 YANG has a set of built-in types, similar to those of many 5195 programming languages, but with some differences due to special 5196 requirements from the management information model. 5198 Additional types may be defined, derived from those built-in types or 5199 from other derived types. Derived types may use subtyping to 5200 formally restrict the set of possible values. 5202 The different built-in types and their derived types allow different 5203 kinds of subtyping, namely length and regular expression restrictions 5204 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 5205 numeric types (Section 9.2.4). 5207 The lexical representation of a value of a certain type is used in 5208 the NETCONF messages and when specifying default values and numerical 5209 ranges in YANG modules. 5211 9.1. Canonical Representation 5213 For most types, there is a single canonical representation of the 5214 type's values. Some types allow multiple lexical representations of 5215 the same value, for example, the positive integer "17" can be 5216 represented as "+17" or "17". Implementations MUST support all 5217 lexical representations specified in this document. 5219 When a NETCONF server sends data, it MUST be in the canonical form. 5221 Some types have a lexical representation that depends on the XML 5222 context in which they occur. These types do not have a canonical 5223 form. 5225 9.2. The Integer Built-In Types 5227 The integer built-in types are int8, int16, int32, int64, uint8, 5228 uint16, uint32, and uint64. They represent signed and unsigned 5229 integers of different sizes: 5231 int8 represents integer values between -128 and 127, inclusively. 5233 int16 represents integer values between -32768 and 32767, 5234 inclusively. 5236 int32 represents integer values between -2147483648 and 2147483647, 5237 inclusively. 5239 int64 represents integer values between -9223372036854775808 and 5240 9223372036854775807, inclusively. 5242 uint8 represents integer values between 0 and 255, inclusively. 5244 uint16 represents integer values between 0 and 65535, inclusively. 5246 uint32 represents integer values between 0 and 4294967295, 5247 inclusively. 5249 uint64 represents integer values between 0 and 18446744073709551615, 5250 inclusively. 5252 9.2.1. Lexical Representation 5254 An integer value is lexically represented as an optional sign ("+" or 5255 "-"), followed by a sequence of decimal digits. If no sign is 5256 specified, "+" is assumed. 5258 For convenience, when specifying a default value for an integer in a 5259 YANG module, an alternative lexical representation can be used, which 5260 represents the value in a hexadecimal or octal notation. The 5261 hexadecimal notation consists of an optional sign ("+" or "-"), the 5262 characters "0x" followed a number of hexadecimal digits, where 5263 letters may be uppercase or lowercase. The octal notation consists 5264 of an optional sign ("+" or "-"), the character "0" followed a number 5265 of octal digits. 5267 Note that if a default value in a YANG module has a leading zero 5268 ("0"), it is interpreted as an octal number. In the XML instance 5269 documents, an integer is always interpreted as a decimal number, and 5270 leading zeros are allowed. 5272 Examples: 5274 // legal values 5275 +4711 // legal positive value 5276 4711 // legal positive value 5277 -123 // legal negative value 5278 0xf00f // legal positive hexadecimal value 5279 -0xf // legal negative hexadecimal value 5280 052 // legal positive octal value 5282 // illegal values 5283 - 1 // illegal intermediate space 5285 9.2.2. Canonical Form 5287 The canonical form of a positive integer does not include the sign 5288 "+". Leading zeros are prohibited. The value zero is represented as 5289 "0". 5291 9.2.3. Restrictions 5293 All integer types can be restricted with the "range" statement 5294 (Section 9.2.4). 5296 9.2.4. The range Statement 5298 The "range" statement, which is an optional substatement to the 5299 "type" statement, takes as an argument a range expression string. It 5300 is used to restrict integer and decimal built-in types, or types 5301 derived from those. 5303 A range consists of an explicit value, or a lower-inclusive bound, 5304 two consecutive dots "..", and an upper-inclusive bound. Multiple 5305 values or ranges can be given, separated by "|". If multiple values 5306 or ranges are given, they all MUST be disjoint and MUST be in 5307 ascending order. If a range restriction is applied to an already 5308 range-restricted type, the new restriction MUST be equal or more 5309 limiting, that is raising the lower bounds, reducing the upper 5310 bounds, removing explicit values or ranges, or splitting ranges into 5311 multiple ranges with intermediate gaps. Each explicit value and 5312 range boundary value given in the range expression MUST match the 5313 type being restricted, or be one of the special values "min" or 5314 "max". "min" and "max" mean the minimum and maximum value accepted 5315 for the type being restricted, respectively. 5317 The range expression syntax is formally defined by the rule 5318 "range-arg" in Section 13. 5320 9.2.4.1. The range's Substatements 5322 +---------------+---------+-------------+ 5323 | substatement | section | cardinality | 5324 +---------------+---------+-------------+ 5325 | description | 7.20.3 | 0..1 | 5326 | error-app-tag | 7.5.4.2 | 0..1 | 5327 | error-message | 7.5.4.1 | 0..1 | 5328 | reference | 7.20.4 | 0..1 | 5329 +---------------+---------+-------------+ 5331 9.2.5. Usage Example 5333 typedef my-base-int32-type { 5334 type int32 { 5335 range "1..4 | 10..20"; 5336 } 5337 } 5339 typedef my-type1 { 5340 type my-base-int32-type { 5341 // legal range restriction 5342 range "11..max"; // 11..20 5343 } 5344 } 5346 typedef my-type2 { 5347 type my-base-int32-type { 5348 // illegal range restriction 5349 range "11..100"; 5350 } 5351 } 5353 9.3. The decimal64 Built-In Type 5355 The decimal64 type represents a subset of the real numbers, which can 5356 be represented by decimal numerals. The value space of decimal64 is 5357 the set of numbers that can be obtained by multiplying a 64-bit 5358 signed integer by a negative power of ten, i.e., expressible as "i x 5359 10^-n" where i is an integer64 and n is an integer between 1 and 18, 5360 inclusively. 5362 9.3.1. Lexical Representation 5364 A decimal64 value is lexically represented as an optional sign ("+" 5365 or "-"), followed by a sequence of decimal digits, optionally 5366 followed by a period ('.') as a decimal indicator and a sequence of 5367 decimal digits. If no sign is specified, "+" is assumed. 5369 9.3.2. Canonical Form 5371 The canonical form of a positive decimal64 does not include the sign 5372 "+". The decimal point is required. Leading and trailing zeros are 5373 prohibited, subject to the rule that there MUST be at least one digit 5374 before and after the decimal point. The value zero is represented as 5375 "0.0". 5377 9.3.3. Restrictions 5379 A decimal64 type can be restricted with the "range" statement 5380 (Section 9.2.4). 5382 9.3.4. The fraction-digits Statement 5384 The "fraction-digits" statement, which is a substatement to the 5385 "type" statement, MUST be present if the type is "decimal64". It 5386 takes as an argument an integer between 1 and 18, inclusively. It 5387 controls the size of the minimum difference between values of a 5388 decimal64 type, by restricting the value space to numbers that are 5389 expressible as "i x 10^-n" where n is the fraction-digits argument. 5391 The following table lists the minimum and maximum value for each 5392 fraction-digit value: 5394 +----------------+-----------------------+----------------------+ 5395 | fraction-digit | min | max | 5396 +----------------+-----------------------+----------------------+ 5397 | 1 | -922337203685477580.8 | 922337203685477580.7 | 5398 | 2 | -92233720368547758.08 | 92233720368547758.07 | 5399 | 3 | -9223372036854775.808 | 9223372036854775.807 | 5400 | 4 | -922337203685477.5808 | 922337203685477.5807 | 5401 | 5 | -92233720368547.75808 | 92233720368547.75807 | 5402 | 6 | -9223372036854.775808 | 9223372036854.775807 | 5403 | 7 | -922337203685.4775808 | 922337203685.4775807 | 5404 | 8 | -92233720368.54775808 | 92233720368.54775807 | 5405 | 9 | -9223372036.854775808 | 9223372036.854775807 | 5406 | 10 | -922337203.6854775808 | 922337203.6854775807 | 5407 | 11 | -92233720.36854775808 | 92233720.36854775807 | 5408 | 12 | -9223372.036854775808 | 9223372.036854775807 | 5409 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5410 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5411 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5412 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5413 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5414 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5415 +----------------+-----------------------+----------------------+ 5417 9.3.5. Usage Example 5419 typedef my-decimal { 5420 type decimal64 { 5421 fraction-digits 2; 5422 range "1 .. 3.14 | 10 | 20..max"; 5423 } 5424 } 5426 9.4. The string Built-In Type 5428 The string built-in type represents human-readable strings in YANG. 5429 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 5430 characters, including tab, carriage return, and line feed but 5431 excluding the other C0 control characters, the surrogate blocks, and 5432 the noncharacters. The string syntax is formally defined by the rule 5433 "yang-string" in Section 13. 5435 9.4.1. Lexical Representation 5437 A string value is lexically represented as character data in the XML 5438 instance documents. 5440 9.4.2. Canonical Form 5442 The canonical form is the same as the lexical representation. No 5443 Unicode normalization is performed of string values. 5445 9.4.3. Restrictions 5447 A string can be restricted with the "length" (Section 9.4.4) and 5448 "pattern" (Section 9.4.5) statements. 5450 9.4.4. The length Statement 5452 The "length" statement, which is an optional substatement to the 5453 "type" statement, takes as an argument a length expression string. 5454 It is used to restrict the built-in types "string" and "binary" or 5455 types derived from them. 5457 A "length" statement restricts the number of Unicode characters in 5458 the string. 5460 A length range consists of an explicit value, or a lower bound, two 5461 consecutive dots "..", and an upper bound. Multiple values or ranges 5462 can be given, separated by "|". Length-restricting values MUST NOT 5463 be negative. If multiple values or ranges are given, they all MUST 5464 be disjoint and MUST be in ascending order. If a length restriction 5465 is applied to an already length-restricted type, the new restriction 5466 MUST be equal or more limiting, that is, raising the lower bounds, 5467 reducing the upper bounds, removing explicit length values or ranges, 5468 or splitting ranges into multiple ranges with intermediate gaps. A 5469 length value is a non-negative integer, or one of the special values 5470 "min" or "max". "min" and "max" mean the minimum and maximum length 5471 accepted for the type being restricted, respectively. An 5472 implementation is not required to support a length value larger than 5473 18446744073709551615. 5475 The length expression syntax is formally defined by the rule 5476 "length-arg" in Section 13. 5478 9.4.4.1. The length's Substatements 5480 +---------------+---------+-------------+ 5481 | substatement | section | cardinality | 5482 +---------------+---------+-------------+ 5483 | description | 7.20.3 | 0..1 | 5484 | error-app-tag | 7.5.4.2 | 0..1 | 5485 | error-message | 7.5.4.1 | 0..1 | 5486 | reference | 7.20.4 | 0..1 | 5487 +---------------+---------+-------------+ 5489 9.4.5. The pattern Statement 5491 The "pattern" statement, which is an optional substatement to the 5492 "type" statement, takes as an argument a regular expression string, 5493 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5494 "string", or types derived from "string", to values that match the 5495 pattern. 5497 If the type has multiple "pattern" statements, the expressions are 5498 ANDed together, i.e., all such expressions have to match. 5500 If a pattern restriction is applied to an already pattern-restricted 5501 type, values must match all patterns in the base type, in addition to 5502 the new patterns. 5504 9.4.5.1. The pattern's Substatements 5506 +---------------+---------+-------------+ 5507 | substatement | section | cardinality | 5508 +---------------+---------+-------------+ 5509 | description | 7.20.3 | 0..1 | 5510 | error-app-tag | 7.5.4.2 | 0..1 | 5511 | error-message | 7.5.4.1 | 0..1 | 5512 | modifier | 9.4.6 | 0..1 | 5513 | reference | 7.20.4 | 0..1 | 5514 +---------------+---------+-------------+ 5516 9.4.6. The modifier Statement 5518 9.4.7. Usage Example 5520 With the following typedef: 5522 typedef my-base-str-type { 5523 type string { 5524 length "1..255"; 5525 } 5526 } 5528 the following refinement is legal: 5530 type my-base-str-type { 5531 // legal length refinement 5532 length "11 | 42..max"; // 11 | 42..255 5533 } 5535 and the following refinement is illegal: 5537 type my-base-str-type { 5538 // illegal length refinement 5539 length "1..999"; 5540 } 5542 With the following type: 5544 type string { 5545 length "0..4"; 5546 pattern "[0-9a-fA-F]*"; 5547 } 5549 the following strings match: 5551 AB // legal 5552 9A00 // legal 5554 and the following strings do not match: 5556 00ABAB // illegal, too long 5557 xx00 // illegal, bad characters 5559 With the following type: 5561 typedef yang-identifier { 5562 type string { 5563 length "1..max"; 5564 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 5565 pattern '[xX][mM][lL].*' { 5566 modifier invert-match; 5567 } 5568 } 5569 } 5571 the following string match: 5573 enabled // legal 5575 and the following strings do not match: 5577 10-mbit // illegal, starts with a number 5578 xml-element // illegal, starts with illegal sequence 5580 9.5. The boolean Built-In Type 5582 The boolean built-in type represents a boolean value. 5584 9.5.1. Lexical Representation 5586 The lexical representation of a boolean value is a string with a 5587 value of "true" or "false". These values MUST be in lowercase. 5589 9.5.2. Canonical Form 5591 The canonical form is the same as the lexical representation. 5593 9.5.3. Restrictions 5595 A boolean cannot be restricted. 5597 9.6. The enumeration Built-In Type 5599 The enumeration built-in type represents values from a set of 5600 assigned names. 5602 9.6.1. Lexical Representation 5604 The lexical representation of an enumeration value is the assigned 5605 name string. 5607 9.6.2. Canonical Form 5609 The canonical form is the assigned name string. 5611 9.6.3. Restrictions 5613 An enumeration can be restricted with the "enum" (Section 9.6.4) 5614 statement. 5616 9.6.4. The enum Statement 5618 The "enum" statement, which is a substatement to the "type" 5619 statement, MUST be present if the type is "enumeration". It is 5620 repeatedly used to specify each assigned name of an enumeration type. 5621 It takes as an argument a string which is the assigned name. The 5622 string MUST NOT be empty and MUST NOT have any leading or trailing 5623 whitespace characters. The use of Unicode control codes SHOULD be 5624 avoided. 5626 The statement is optionally followed by a block of substatements that 5627 holds detailed enum information. 5629 All assigned names in an enumeration MUST be unique. 5631 When an existing enumeration type is restricted, the set of assigned 5632 names in the new type MUST be a subset of the base type's set of 5633 assigned names. The value of such an assigned name MUST not be 5634 changed. 5636 9.6.4.1. The enum's Substatements 5638 +--------------+---------+-------------+ 5639 | substatement | section | cardinality | 5640 +--------------+---------+-------------+ 5641 | description | 7.20.3 | 0..1 | 5642 | if-feature | 7.19.2 | 0..n | 5643 | reference | 7.20.4 | 0..1 | 5644 | status | 7.20.2 | 0..1 | 5645 | value | 9.6.4.2 | 0..1 | 5646 +--------------+---------+-------------+ 5648 9.6.4.2. The value Statement 5650 The "value" statement, which is optional, is used to associate an 5651 integer value with the assigned name for the enum. This integer 5652 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5653 unique within the enumeration type. 5655 If a value is not specified, then one will be automatically assigned. 5656 If the "enum" substatement is the first one defined, the assigned 5657 value is zero (0); otherwise, the assigned value is one greater than 5658 the current highest enum value (i.e., the highest enum value, 5659 implicit or explicit, prior to the current "enum" substatement in the 5660 parent "type" statement). 5662 If the current highest value is equal to 2147483647, then an enum 5663 value MUST be specified for "enum" substatements following the one 5664 with the current highest value. 5666 When an existing enumeration type is restricted, the "value" 5667 statement MUST either have the same value as the in the base type or 5668 not be present, in which case the value is the same as in the base 5669 type. 5671 9.6.5. Usage Example 5672 leaf myenum { 5673 type enumeration { 5674 enum zero; 5675 enum one; 5676 enum seven { 5677 value 7; 5678 } 5679 } 5680 } 5682 The lexical representation of the leaf "myenum" with value "seven" 5683 is: 5685 seven 5687 With the following typedef: 5689 typedef my-base-enumeration-type { 5690 type enumeration { 5691 enum white { 5692 value 1; 5693 } 5694 enum yellow { 5695 value 2; 5696 } 5697 enum red { 5698 value 3; 5699 } 5700 } 5701 } 5703 the following refinement is legal: 5705 type my-base-enumeration-type { 5706 // legal enum refinement 5707 enum yellow; 5708 enum red { 5709 value 3; 5710 } 5711 } 5713 and the following refinement is illegal: 5715 type my-base-enumeration-type { 5716 // illegal enum refinement 5717 enum yellow { 5718 value 4; // illegal value change 5719 } 5720 enum black; // illegal addition of new name 5721 } 5723 9.7. The bits Built-In Type 5725 The bits built-in type represents a bit set. That is, a bits value 5726 is a set of flags identified by small integer position numbers 5727 starting at 0. Each bit number has an assigned name. 5729 9.7.1. Restrictions 5731 A bits type cannot be restricted. 5733 9.7.2. Lexical Representation 5735 The lexical representation of the bits type is a space-separated list 5736 of the individual bit values that are set. An empty string thus 5737 represents a value where no bits are set. 5739 9.7.3. Canonical Form 5741 In the canonical form, the bit values are separated by a single space 5742 character and they appear ordered by their position (see 5743 Section 9.7.4.2). 5745 9.7.4. The bit Statement 5747 The "bit" statement, which is a substatement to the "type" statement, 5748 MUST be present if the type is "bits". It is repeatedly used to 5749 specify each assigned named bit of a bits type. It takes as an 5750 argument a string that is the assigned name of the bit. It is 5751 followed by a block of substatements that holds detailed bit 5752 information. The assigned name follows the same syntax rules as an 5753 identifier (see Section 6.2). 5755 All assigned names in a bits type MUST be unique. 5757 9.7.4.1. The bit's Substatements 5758 +--------------+---------+-------------+ 5759 | substatement | section | cardinality | 5760 +--------------+---------+-------------+ 5761 | description | 7.20.3 | 0..1 | 5762 | if-feature | 7.19.2 | 0..n | 5763 | reference | 7.20.4 | 0..1 | 5764 | status | 7.20.2 | 0..1 | 5765 | position | 9.7.4.2 | 0..1 | 5766 +--------------+---------+-------------+ 5768 9.7.4.2. The position Statement 5770 The "position" statement, which is optional, takes as an argument a 5771 non-negative integer value that specifies the bit's position within a 5772 hypothetical bit field. The position value MUST be in the range 0 to 5773 4294967295, and it MUST be unique within the bits type. The value is 5774 unused by YANG and the NETCONF messages, but is carried as a 5775 convenience to implementors. 5777 If a bit position is not specified, then one will be automatically 5778 assigned. If the "bit" substatement is the first one defined, the 5779 assigned value is zero (0); otherwise, the assigned value is one 5780 greater than the current highest bit position (i.e., the highest bit 5781 position, implicit or explicit, prior to the current "bit" 5782 substatement in the parent "type" statement). 5784 If the current highest bit position value is equal to 4294967295, 5785 then a position value MUST be specified for "bit" substatements 5786 following the one with the current highest position value. 5788 9.7.5. Usage Example 5790 Given the following leaf: 5792 leaf mybits { 5793 type bits { 5794 bit disable-nagle { 5795 position 0; 5796 } 5797 bit auto-sense-speed { 5798 position 1; 5799 } 5800 bit ten-Mb-only { 5801 position 2; 5802 } 5803 } 5804 default "auto-sense-speed"; 5805 } 5807 The lexical representation of this leaf with bit values disable-nagle 5808 and ten-Mb-only set would be: 5810 disable-nagle ten-Mb-only 5812 9.8. The binary Built-In Type 5814 The binary built-in type represents any binary data, i.e., a sequence 5815 of octets. 5817 9.8.1. Restrictions 5819 A binary can be restricted with the "length" (Section 9.4.4) 5820 statement. The length of a binary value is the number of octets it 5821 contains. 5823 9.8.2. Lexical Representation 5825 Binary values are encoded with the base64 encoding scheme (see 5826 [RFC4648], Section 4). 5828 9.8.3. Canonical Form 5830 The canonical form of a binary value follows the rules in [RFC4648]. 5832 9.9. The leafref Built-In Type 5834 The leafref type is used to declare a constraint on the value space 5835 of a leaf, based on a reference to a set of leaf instances in the 5836 data tree. The "path" substatement (Section 9.9.2) selects a set of 5837 leaf instances, and the leafref value space is the set of values of 5838 these leaf instances. 5840 If the leaf with the leafref type represents configuration data, and 5841 the "require-instance" property (Section 9.9.3) is "true", the leaf 5842 it refers to MUST also represent configuration. Such a leaf puts a 5843 constraint on valid data. All such nodes MUST reference existing 5844 leaf instances or leafs with default values in use (see Section 7.6.1 5845 and Section 7.7.2) for the data to be valid. This constraint is 5846 enforced according to the rules in Section 8. 5848 There MUST NOT be any circular chains of leafrefs. 5850 If the leaf that the leafref refers to is conditional based on one or 5851 more features (see Section 7.19.2), then the leaf with the leafref 5852 type MUST also be conditional based on at least the same set of 5853 features. 5855 9.9.1. Restrictions 5857 A leafref can be restricted with the "require-instance" statement 5858 (Section 9.9.3). 5860 9.9.2. The path Statement 5862 The "path" statement, which is a substatement to the "type" 5863 statement, MUST be present if the type is "leafref". It takes as an 5864 argument a string that MUST refer to a leaf or leaf-list node. 5866 The syntax for a path argument is a subset of the XPath abbreviated 5867 syntax. Predicates are used only for constraining the values for the 5868 key nodes for list entries. Each predicate consists of exactly one 5869 equality test per key, and multiple adjacent predicates MAY be 5870 present if a list has multiple keys. The syntax is formally defined 5871 by the rule "path-arg" in Section 13. 5873 The predicates are only used when more than one key reference is 5874 needed to uniquely identify a leaf instance. This occurs if a list 5875 has multiple keys, or a reference to a leaf other than the key in a 5876 list is needed. In these cases, multiple leafrefs are typically 5877 specified, and predicates are used to tie them together. 5879 The "path" expression evaluates to a node set consisting of zero, 5880 one, or more nodes. If the leaf with the leafref type represents 5881 configuration data, this node set MUST be non-empty. 5883 The "path" XPath expression is conceptually evaluated in the 5884 following context, in addition to the definition in Section 6.4.1: 5886 o If the "path" statement is defined within a typedef, the context 5887 node is the leaf or leaf-list node in the data tree that 5888 references the typedef. 5890 o Otherwise, the context node is the node in the data tree for which 5891 the "path" statement is defined. 5893 9.9.3. The require-instance Statement 5895 The "require-instance" statement, which is a substatement to the 5896 "type" statement, MAY be present if the type is "instance-identifier" 5897 or "leafref". It takes as an argument the string "true" or "false". 5898 If this statement is not present, it defaults to "true". 5900 If "require-instance" is "true", it means that the instance being 5901 referred MUST exist for the data to be valid. This constraint is 5902 enforced according to the rules in Section 8. 5904 If "require-instance" is "false", it means that the instance being 5905 referred MAY exist in valid data. 5907 9.9.4. Lexical Representation 5909 A leafref value is encoded the same way as the leaf it references. 5911 9.9.5. Canonical Form 5913 The canonical form of a leafref is the same as the canonical form of 5914 the leaf it references. 5916 9.9.6. Usage Example 5918 With the following list: 5920 list interface { 5921 key "name"; 5922 leaf name { 5923 type string; 5924 } 5925 leaf admin-status { 5926 type admin-status; 5927 } 5928 list address { 5929 key "ip"; 5930 leaf ip { 5931 type yang:ip-address; 5932 } 5933 } 5934 } 5936 The following leafref refers to an existing interface: 5938 leaf mgmt-interface { 5939 type leafref { 5940 path "../interface/name"; 5941 } 5942 } 5944 An example of a corresponding XML snippet: 5946 5947 eth0 5948 5949 5950 lo 5951 5953 eth0 5955 The following leafrefs refer to an existing address of an interface: 5957 container default-address { 5958 leaf ifname { 5959 type leafref { 5960 path "../../interface/name"; 5961 } 5962 } 5963 leaf address { 5964 type leafref { 5965 path "../../interface[name = current()/../ifname]" 5966 + "/address/ip"; 5967 } 5968 } 5969 } 5971 An example of a corresponding XML snippet: 5973 5974 eth0 5975 up 5976
5977 192.0.2.1 5978
5979
5980 192.0.2.2 5981
5982 5983 5984 lo 5985 up 5986
5987 127.0.0.1 5988
5989 5991 5992 eth0 5993
192.0.2.2
5994 5996 The following list uses a leafref for one of its keys. This is 5997 similar to a foreign key in a relational database. 5999 list packet-filter { 6000 key "if-name filter-id"; 6001 leaf if-name { 6002 type leafref { 6003 path "/interface/name"; 6004 } 6005 } 6006 leaf filter-id { 6007 type uint32; 6008 } 6009 ... 6010 } 6012 An example of a corresponding XML snippet: 6014 6015 eth0 6016 up 6017
6018 192.0.2.1 6019
6020
6021 192.0.2.2 6022
6023 6025 6026 eth0 6027 1 6028 ... 6029 6030 6031 eth0 6032 2 6033 ... 6034 6036 The following notification defines two leafrefs to refer to an 6037 existing admin-status: 6039 notification link-failure { 6040 leaf if-name { 6041 type leafref { 6042 path "/interface/name"; 6043 } 6044 } 6045 leaf admin-status { 6046 type leafref { 6047 path 6048 "/interface[name = current()/../if-name]" 6049 + "/admin-status"; 6050 } 6051 } 6052 } 6054 An example of a corresponding XML notification: 6056 6058 2008-04-01T00:01:00Z 6059 6060 eth0 6061 up 6062 6063 6065 9.10. The identityref Built-In Type 6067 The identityref type is used to reference an existing identity (see 6068 Section 7.17). 6070 9.10.1. Restrictions 6072 An identityref cannot be restricted. 6074 9.10.2. The identityref's base Statement 6076 The "base" statement, which is a substatement to the "type" 6077 statement, MUST be present at least once if the type is 6078 "identityref". The argument is the name of an identity, as defined 6079 by an "identity" statement. If a prefix is present on the identity 6080 name, it refers to an identity defined in the module that was 6081 imported with that prefix. Otherwise, an identity with the matching 6082 name MUST be defined in the current module or an included submodule. 6084 Valid values for an identityref are any identities derived from all 6085 the identityref's base identities. On a particular server, the valid 6086 values are further restricted to the set of identities defined in the 6087 modules supported by the server. 6089 9.10.3. Lexical Representation 6091 An identityref is encoded as the referred identity's qualified name 6092 as defined in [XML-NAMES]. If the prefix is not present, the 6093 namespace of the identityref is the default namespace in effect on 6094 the element that contains the identityref value. 6096 When an identityref is given a default value using the "default" 6097 statement, the identity name in the default value MAY have a prefix. 6098 If a prefix is present on the identity name, it refers to an identity 6099 defined in the module that was imported with that prefix, or the 6100 prefix for the current module if the identity is defined in the 6101 current module or one of its submodules. Otherwise, an identity with 6102 the matching name MUST be defined in the current module or one of its 6103 submodules. 6105 The string value of a node of type identityref in a "must" or "when" 6106 XPath expression is the referred identity's qualified name with the 6107 prefix present. If the referred identity is defined in an imported 6108 module, the prefix in the string value is the prefix defined in the 6109 corresponding "import" statement. Otherwise, the prefix in the 6110 string value is the prefix for the current module. 6112 9.10.4. Canonical Form 6114 Since the lexical form depends on the XML context in which the value 6115 occurs, this type does not have a canonical form. 6117 9.10.5. Usage Example 6119 With the identity definitions in Section 7.17.3 and the following 6120 module: 6122 module my-crypto { 6123 yang-version 1.1; 6124 namespace "http://example.com/my-crypto"; 6125 prefix mc; 6127 import "crypto-base" { 6128 prefix "crypto"; 6129 } 6131 identity aes { 6132 base "crypto:crypto-alg"; 6133 } 6135 leaf crypto { 6136 type identityref { 6137 base "crypto:crypto-alg"; 6138 } 6139 } 6141 container aes-parameters { 6142 when "../crypto = 'mc:aes'"; 6143 ... 6144 } 6145 } 6147 the following is an example how the leaf "crypto" can be encoded, if 6148 the value is the "des3" identity defined in the "des" module: 6150 des:des3 6152 Any prefixes used in the encoding are local to each instance 6153 encoding. This means that the same identityref may be encoded 6154 differently by different implementations. For example, the following 6155 example encodes the same leaf as above: 6157 x:des3 6159 If the "crypto" leaf's value instead is "aes" defined in the 6160 "my-crypto" module, it can be encoded as: 6162 mc:aes 6164 or, using the default namespace: 6166 aes 6168 9.11. The empty Built-In Type 6170 The empty built-in type represents a leaf that does not have any 6171 value, it conveys information by its presence or absence. 6173 An empty type cannot have a default value. 6175 9.11.1. Restrictions 6177 An empty type cannot be restricted. 6179 9.11.2. Lexical Representation 6181 Not applicable. 6183 9.11.3. Canonical Form 6185 Not applicable. 6187 9.11.4. Usage Example 6189 With the following leaf 6191 leaf enable-qos { 6192 type empty; 6193 } 6195 the following is an example of a valid encoding 6197 6199 if the leaf exists. 6201 9.12. The union Built-In Type 6203 The union built-in type represents a value that corresponds to one of 6204 its member types. 6206 When the type is "union", the "type" statement (Section 7.4) MUST be 6207 present. It is used to repeatedly specify each member type of the 6208 union. It takes as an argument a string that is the name of a member 6209 type. 6211 A member type can be of any built-in or derived type. 6213 A value representing a union data type is validated consecutively 6214 against each member type, in the order they are specified in the 6215 "type" statement, until a match is found. The type that matched will 6216 be the type of the value for the node that was validated. 6218 Any default value or "units" property defined in the member types is 6219 not inherited by the union type. 6221 9.12.1. Restrictions 6223 A union cannot be restricted. However, each member type can be 6224 restricted, based on the rules defined in Section 9. 6226 9.12.2. Lexical Representation 6228 The lexical representation of a union is a value that corresponds to 6229 the representation of any one of the member types. 6231 9.12.3. Canonical Form 6233 The canonical form of a union value is the same as the canonical form 6234 of the member type of the value. 6236 9.12.4. Usage Example 6238 The following is a union of an int32 an enumeration: 6240 type union { 6241 type int32; 6242 type enumeration { 6243 enum "unbounded"; 6244 } 6245 } 6247 Care must be taken when a member type is a leafref where the 6248 "require-instance" property (Section 9.9.3) is "true". If a leaf of 6249 such a type refers to an existing instance, the leaf's value must be 6250 re-validated if the target instance is deleted. For example, with 6251 the following definitions: 6253 list filter { 6254 key name; 6255 leaf name { 6256 type string; 6257 } 6258 ... 6259 } 6261 leaf outbound-filter { 6262 type union { 6263 type leafref { 6264 path "/filter/name"; 6265 } 6266 type enumeration { 6267 enum default-filter; 6268 } 6269 } 6270 } 6272 assume that there exists an entry in the filter list with the name 6273 "http", and that the outbound-filter leaf has this value: 6275 6276 http 6277 6278 http 6280 If the filter entry "http" is removed, the outbound-filter leaf's 6281 value doesn't match the leafref, and the next member type is checked. 6282 The current value ("http") doesn't match the enumeration, so the 6283 resulting configuration is invalid. 6285 If the second member type in the union had been of type "string" 6286 instead of an enumeration, the current value would have matched, and 6287 the resulting configuration would have been valid. 6289 9.13. The instance-identifier Built-In Type 6291 The instance-identifier built-in type is used to uniquely identify a 6292 particular instance node in the data tree. 6294 The syntax for an instance-identifier is a subset of the XPath 6295 abbreviated syntax, formally defined by the rule 6296 "instance-identifier" in Section 13. It is used to uniquely identify 6297 a node in the data tree. Predicates are used only for specifying the 6298 values for the key nodes for list entries, a value of a leaf-list 6299 entry, or a positional index for a list without keys. For 6300 identifying list entries with keys, each predicate consists of one 6301 equality test per key, and each key MUST have a corresponding 6302 predicate. 6304 If the leaf with the instance-identifier type represents 6305 configuration data, and the "require-instance" property 6306 (Section 9.9.3) is "true", the node it refers to MUST also represent 6307 configuration. Such a leaf puts a constraint on valid data. All 6308 such leaf nodes MUST reference existing nodes or leaf or leaf-list 6309 nodes with their default value in use (see Section 7.6.1 and 6310 Section 7.7.2) for the data to be valid. This constraint is enforced 6311 according to the rules in Section 8. 6313 The "instance-identifier" XPath expression is conceptually evaluated 6314 in the following context, in addition to the definition in 6315 Section 6.4.1: 6317 o The context node is the root node in the accessible tree. 6319 9.13.1. Restrictions 6321 An instance-identifier can be restricted with the "require-instance" 6322 statement (Section 9.9.3). 6324 9.13.2. Lexical Representation 6326 An instance-identifier value is lexically represented as a string. 6327 All node names in an instance-identifier value MUST be qualified with 6328 explicit namespace prefixes, and these prefixes MUST be declared in 6329 the XML namespace scope in the instance-identifier's XML element. 6331 Any prefixes used in the encoding are local to each instance 6332 encoding. This means that the same instance-identifier may be 6333 encoded differently by different implementations. 6335 9.13.3. Canonical Form 6337 Since the lexical form depends on the XML context in which the value 6338 occurs, this type does not have a canonical form. 6340 9.13.4. Usage Example 6342 The following are examples of instance identifiers: 6344 /* instance-identifier for a container */ 6345 /ex:system/ex:services/ex:ssh 6347 /* instance-identifier for a leaf */ 6348 /ex:system/ex:services/ex:ssh/ex:port 6350 /* instance-identifier for a list entry */ 6351 /ex:system/ex:user[ex:name='fred'] 6353 /* instance-identifier for a leaf in a list entry */ 6354 /ex:system/ex:user[ex:name='fred']/ex:type 6356 /* instance-identifier for a list entry with two keys */ 6357 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 6359 /* instance-identifier for a leaf-list entry */ 6360 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 6362 /* instance-identifier for a list entry without keys */ 6363 /ex:stats/ex:port[3] 6365 10. XPath Functions 6367 This document defines two generic XPath functions and four YANG type- 6368 specific XPath functions. The function signatures are specified with 6369 the syntax used in [XPATH]. 6371 10.1. Functions for Node Sets 6373 10.1.1. current() 6375 node-set current() 6377 The function current() takes no input parameters, and returns a node 6378 set with the initial context node as its only member. 6380 10.2. Functions for Strings 6382 10.2.1. re-match() 6384 boolean re-match(string subject, string pattern) 6386 The re-match() function returns true if the "subject" string matches 6387 the regular expression "pattern"; otherwise it returns false. 6389 The function "re-match" checks if a string matches a given regular 6390 expression. The regular expressions used are the XML Schema regular 6391 expressions [XSD-TYPES]. Note that this includes implicit anchoring 6392 of the regular expression at the head and tail. 6394 10.2.1.1. Usage Example 6396 The expression: 6398 re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') 6400 returns true. 6402 To count all logical interfaces called eth0., do: 6404 count(/interface[re-match(name, 'eth0\.\d+')]) 6406 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 6408 10.3.1. deref() 6410 node-set deref(node-set nodes) 6412 The deref() function follows the reference defined by the first node 6413 in document order in the argument "nodes", and returns the nodes it 6414 refers to. 6416 If the first argument node is of type instance-identifier, the 6417 function returns a node set that contains the single node that the 6418 instance identifier refers to, if it exists. If no such node exists, 6419 an empty node-set is returned. 6421 If the first argument node is of type leafref, the function returns a 6422 node set that contains the nodes that the leafref refers to. 6424 If the first argument node is of any other type, an empty node set is 6425 returned. 6427 10.3.1.1. Usage Example 6428 list interface { 6429 key name; 6430 leaf name { ... } 6431 leaf enabled { 6432 type boolean; 6433 } 6434 ... 6435 } 6437 leaf mgmt-interface { 6438 type leafref { 6439 path "/interface/name"; 6440 } 6441 must 'deref(.)/../enabled = "true"' { 6442 error-message 6443 "The management interface cannot be disabled."; 6444 } 6445 } 6447 10.4. Functions for the YANG Type "identityref" 6449 10.4.1. derived-from() 6451 boolean derived-from(node-set nodes, 6452 string module-name, 6453 string identity-name) 6455 The derived-from() function returns true if the first node in 6456 document order in the argument "nodes" is a node of type identityref, 6457 and its value is an identity that is derived from the identity 6458 "identity-name" defined in the YANG module "module-name"; otherwise 6459 it returns false. 6461 10.4.2. derived-from-or-self() 6463 boolean derived-from-or-self(node-set nodes, 6464 string module-name, 6465 string identity-name) 6467 The derived-from-or-self() function returns true if the first node in 6468 document order in the argument "nodes" is a node of type identityref, 6469 and its value is an identity that is equal to or derived from the 6470 identity "identity-name" defined in the YANG module "module-name"; 6471 otherwise it returns false. 6473 10.4.2.1. Usage Example 6475 module example-interface { 6476 ... 6478 identity interface-type; 6480 identity ethernet { 6481 base interface-type; 6482 } 6484 identity fast-ethernet { 6485 base ethernet; 6486 } 6488 identity gigabit-ethernet { 6489 base ethernet; 6490 } 6492 list interface { 6493 key name; 6494 ... 6495 leaf type { 6496 type identityref { 6497 base interface-type; 6498 } 6499 } 6500 ... 6501 } 6503 augment "/interface" { 6504 when 'derived-from(type, 6505 "example-interface", 6506 "ethernet")'; 6507 // ethernet-specific definitions here 6508 } 6509 } 6511 10.5. Functions for the YANG Type "enumeration" 6513 10.5.1. enum-value() 6515 number enum-value(node-set nodes) 6517 The enum-value() function checks if the first node in document order 6518 in the argument "nodes" is a node of type enumeration, and returns 6519 the enum's integer value. If the "nodes" node set is empty, or if 6520 the first node in "nodes" is not of type enumeration, it returns NaN. 6522 10.5.1.1. Usage Example 6524 With this data model: 6526 list alarm { 6527 ... 6528 leaf severity { 6529 type enumeration { 6530 enum cleared { 6531 value 1; 6532 } 6533 enum indeterminate { 6534 value 2; 6535 } 6536 enum minor { 6537 value 3; 6538 } 6539 enum warning { 6540 value 4; 6541 } 6542 enum major { 6543 value 5; 6544 } 6545 enum critical { 6546 value 6; 6547 } 6548 } 6549 } 6550 } 6552 the following XPath expression selects only alarms that are of 6553 severity "major" or higher: 6555 /alarm[enum-value(severity) >= 5] 6557 10.6. Functions for the YANG Type "bits" 6559 10.6.1. bit-is-set() 6561 boolean bit-is-set(node-set nodes, string bit-name) 6563 The bit-is-set() function returns true if the first node in document 6564 order in the argument "nodes" is a node of type bits, and its value 6565 has the bit "'bit-name" set; otherwise it returns false. 6567 10.6.1.1. Usage Example 6569 If an interface has this leaf: 6571 leaf flags { 6572 type bits { 6573 bit UP; 6574 bit PROMISCUOUS 6575 bit DISABLED; 6576 } 6577 } 6579 the following XPath expression can be used to select all interfaces 6580 with the UP flag set: 6582 /interface[bit-is-set(flags, "UP")] 6584 11. Updating a Module 6586 As experience is gained with a module, it may be desirable to revise 6587 that module. However, changes are not allowed if they have any 6588 potential to cause interoperability problems between a client using 6589 an original specification and a server using an updated 6590 specification. 6592 For any published change, a new "revision" statement (Section 7.1.9) 6593 MUST be included in front of the existing "revision" statements. If 6594 there are no existing "revision" statements, then one MUST be added 6595 to identify the new revision. Furthermore, any necessary changes 6596 MUST be applied to any meta-data statements, including the 6597 "organization" and "contact" statements (Section 7.1.7, 6598 Section 7.1.8). 6600 Note that definitions contained in a module are available to be 6601 imported by any other module, and are referenced in "import" 6602 statements via the module name. Thus, a module name MUST NOT be 6603 changed. Furthermore, the "namespace" statement MUST NOT be changed, 6604 since all XML elements are qualified by the namespace. 6606 Obsolete definitions MUST NOT be removed from modules since their 6607 identifiers may still be referenced by other modules. 6609 A definition may be revised in any of the following ways: 6611 o An "enumeration" type may have new enums added, provided the old 6612 enums's values do not change. 6614 o A "bits" type may have new bits added, provided the old bit 6615 positions do not change. 6617 o A "range", "length", or "pattern" statement may expand the allowed 6618 value space. 6620 o A "default" statement may be added to a leaf that does not have a 6621 default value (either directly or indirectly through its type). 6623 o A "units" statement may be added. 6625 o A "reference" statement may be added or updated. 6627 o A "must" statement may be removed or its constraint relaxed. 6629 o A "mandatory" statement may be removed or changed from "true" to 6630 "false". 6632 o A "min-elements" statement may be removed, or changed to require 6633 fewer elements. 6635 o A "max-elements" statement may be removed, or changed to allow 6636 more elements. 6638 o A "description" statement may be added or clarified without 6639 changing the semantics of the definition. 6641 o A "base" statement may be added to an "identity" statement. 6643 o A "base" statement may be removed from an "identityref" type, 6644 provided there is at least one "base" statement left. 6646 o New typedefs, groupings, rpcs, notifications, extensions, 6647 features, and identities may be added. 6649 o New data definition statements may be added if they do not add 6650 mandatory nodes (Section 3.1) to existing nodes or at the top 6651 level in a module or submodule, or if they are conditionally 6652 dependent on a new feature (i.e., have an "if-feature" statement 6653 that refers to a new feature). 6655 o A new "case" statement may be added. 6657 o A node that represented state data may be changed to represent 6658 configuration, provided it is not mandatory (Section 3.1). 6660 o An "if-feature" statement may be removed, provided its node is not 6661 mandatory (Section 3.1). 6663 o A "status" statement may be added, or changed from "current" to 6664 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 6666 o A "type" statement may be replaced with another "type" statement 6667 that does not change the syntax or semantics of the type. For 6668 example, an inline type definition may be replaced with a typedef, 6669 but an int8 type cannot be replaced by an int16, since the syntax 6670 would change. 6672 o Any set of data definition nodes may be replaced with another set 6673 of syntactically and semantically equivalent nodes. For example, 6674 a set of leafs may be replaced by a uses of a grouping with the 6675 same leafs. 6677 o A module may be split into a set of submodules, or a submodule may 6678 be removed, provided the definitions in the module do not change 6679 in any other way than allowed here. 6681 o The "prefix" statement may be changed, provided all local uses of 6682 the prefix also are changed. 6684 Otherwise, if the semantics of any previous definition are changed 6685 (i.e., if a non-editorial change is made to any definition other than 6686 those specifically allowed above), then this MUST be achieved by a 6687 new definition with a new identifier. 6689 In statements that have any data definition statements as 6690 substatements, those data definition substatements MUST NOT be 6691 reordered. 6693 12. YIN 6695 A YANG module can be translated into an alternative XML-based syntax 6696 called YIN. The translated module is called a YIN module. This 6697 section describes symmetric mapping rules between the two formats. 6699 The YANG and YIN formats contain equivalent information using 6700 different notations. The YIN notation enables developers to 6701 represent YANG data models in XML and therefore use the rich set of 6702 XML-based tools for data filtering and validation, automated 6703 generation of code and documentation, and other tasks. Tools like 6704 XSLT or XML validators can be utilized. 6706 The mapping between YANG and YIN does not modify the information 6707 content of the model. Comments and whitespace are not preserved. 6709 12.1. Formal YIN Definition 6711 There is a one-to-one correspondence between YANG keywords and YIN 6712 elements. The local name of a YIN element is identical to the 6713 corresponding YANG keyword. This means, in particular, that the 6714 document element (root) of a YIN document is always or 6715 . 6717 YIN elements corresponding to the YANG keywords belong to the 6718 namespace whose associated URI is 6719 "urn:ietf:params:xml:ns:yang:yin:1". 6721 YIN elements corresponding to extension keywords belong to the 6722 namespace of the YANG module where the extension keyword is declared 6723 via the "extension" statement. 6725 The names of all YIN elements MUST be properly qualified with their 6726 namespaces specified above using the standard mechanisms of 6727 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 6729 The argument of a YANG statement is represented in YIN either as an 6730 XML attribute or a subelement of the keyword element. Table 1 6731 defines the mapping for the set of YANG keywords. For extensions, 6732 the argument mapping is specified within the "extension" statement 6733 (see Section 7.18). The following rules hold for arguments: 6735 o If the argument is represented as an attribute, this attribute has 6736 no namespace. 6738 o If the argument is represented as an element, it is qualified by 6739 the same namespace as its parent keyword element. 6741 o If the argument is represented as an element, it MUST be the first 6742 child of the keyword element. 6744 Substatements of a YANG statement are represented as (additional) 6745 children of the keyword element and their relative order MUST be the 6746 same as the order of substatements in YANG. 6748 Comments in YANG MAY be mapped to XML comments. 6750 +------------------+---------------+-------------+ 6751 | keyword | argument name | yin-element | 6752 +------------------+---------------+-------------+ 6753 | anyxml | name | false | 6754 | argument | name | false | 6755 | augment | target-node | false | 6756 | base | name | false | 6757 | belongs-to | module | false | 6758 | bit | name | false | 6759 | case | name | false | 6760 | choice | name | false | 6761 | config | value | false | 6762 | contact | text | true | 6763 | container | name | false | 6764 | default | value | false | 6765 | description | text | true | 6766 | deviate | value | false | 6767 | deviation | target-node | false | 6768 | enum | name | false | 6769 | error-app-tag | value | false | 6770 | error-message | value | true | 6771 | extension | name | false | 6772 | feature | name | false | 6773 | fraction-digits | value | false | 6774 | grouping | name | false | 6775 | identity | name | false | 6776 | if-feature | name | false | 6777 | import | module | false | 6778 | include | module | false | 6779 | input | | n/a | 6780 | key | value | false | 6781 | leaf | name | false | 6782 | leaf-list | name | false | 6783 | length | value | false | 6784 | list | name | false | 6785 | mandatory | value | false | 6786 | max-elements | value | false | 6787 | min-elements | value | false | 6788 | module | name | false | 6789 | must | condition | false | 6790 | namespace | uri | false | 6791 | notification | name | false | 6792 | ordered-by | value | false | 6793 | organization | text | true | 6794 | output | | n/a | 6795 | path | value | false | 6796 | pattern | value | false | 6797 | position | value | false | 6798 | prefix | value | false | 6799 | presence | value | false | 6800 | range | value | false | 6801 | reference | text | true | 6802 | refine | target-node | false | 6803 | require-instance | value | false | 6804 | revision | date | false | 6805 | revision-date | date | false | 6806 | rpc | name | false | 6807 | status | value | false | 6808 | submodule | name | false | 6809 | type | name | false | 6810 | typedef | name | false | 6811 | unique | tag | false | 6812 | units | name | false | 6813 | uses | name | false | 6814 | value | value | false | 6815 | when | condition | false | 6816 | yang-version | value | false | 6817 | yin-element | value | false | 6818 +------------------+---------------+-------------+ 6820 Table 1: Mapping of arguments of the YANG statements. 6822 12.1.1. Usage Example 6824 The following YANG module: 6826 module acme-foo { 6827 yang-version 1.1; 6828 namespace "http://acme.example.com/foo"; 6829 prefix "acfoo"; 6831 import my-extensions { 6832 prefix "myext"; 6833 } 6835 list interface { 6836 key "name"; 6837 leaf name { 6838 type string; 6839 } 6841 leaf mtu { 6842 type uint32; 6843 description "The MTU of the interface."; 6844 myext:c-define "MY_MTU"; 6845 } 6846 } 6847 } 6849 where the extension "c-define" is defined in Section 7.18.3, is 6850 translated into the following YIN: 6852 6857 6858 6860 6861 6862 6864 6865 6866 6867 6868 6869 6870 6871 6872 The MTU of the interface. 6873 6874 6875 6876 6877 6879 13. YANG ABNF Grammar 6881 In YANG, almost all statements are unordered. The ABNF grammar 6882 [RFC5234] [RFC7405] defines the canonical order. To improve module 6883 readability, it is RECOMMENDED that clauses be entered in this order. 6885 Within the ABNF grammar, unordered statements are marked with 6886 comments. 6888 This grammar assumes that the scanner replaces YANG comments with a 6889 single space character. 6891 file "yang.abnf" 6893 module-stmt = optsep module-keyword sep identifier-arg-str 6894 optsep 6895 "{" stmtsep 6896 module-header-stmts 6897 linkage-stmts 6898 meta-stmts 6899 revision-stmts 6900 body-stmts 6901 "}" optsep 6903 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 6904 optsep 6905 "{" stmtsep 6906 submodule-header-stmts 6907 linkage-stmts 6908 meta-stmts 6909 revision-stmts 6910 body-stmts 6911 "}" optsep 6913 module-header-stmts = ;; these stmts can appear in any order 6914 yang-version-stmt 6915 namespace-stmt 6916 prefix-stmt 6918 submodule-header-stmts = 6919 ;; these stmts can appear in any order 6920 yang-version-stmt 6921 belongs-to-stmt 6923 meta-stmts = ;; these stmts can appear in any order 6924 [organization-stmt] 6925 [contact-stmt] 6926 [description-stmt] 6927 [reference-stmt] 6929 linkage-stmts = ;; these stmts can appear in any order 6930 *import-stmt 6931 *include-stmt 6933 revision-stmts = *revision-stmt 6935 body-stmts = *(extension-stmt / 6936 feature-stmt / 6937 identity-stmt / 6938 typedef-stmt / 6939 grouping-stmt / 6940 data-def-stmt / 6941 augment-stmt / 6942 rpc-stmt / 6943 notification-stmt / 6944 deviation-stmt) 6946 data-def-stmt = container-stmt / 6947 leaf-stmt / 6948 leaf-list-stmt / 6949 list-stmt / 6950 choice-stmt / 6951 anyxml-stmt / 6952 uses-stmt 6954 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 6955 stmtend 6957 yang-version-arg-str = < a string that matches the rule > 6958 < yang-version-arg > 6960 yang-version-arg = "1.1" 6962 import-stmt = import-keyword sep identifier-arg-str optsep 6963 "{" stmtsep 6964 prefix-stmt 6965 [revision-date-stmt] 6966 "}" stmtsep 6968 include-stmt = include-keyword sep identifier-arg-str optsep 6969 (";" / 6970 "{" stmtsep 6971 [revision-date-stmt] 6972 "}") stmtsep 6974 namespace-stmt = namespace-keyword sep uri-str stmtend 6976 uri-str = < a string that matches the rule > 6977 < URI in RFC 3986 > 6979 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 6981 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 6982 optsep 6983 "{" stmtsep 6984 prefix-stmt 6985 "}" stmtsep 6987 organization-stmt = organization-keyword sep string stmtend 6989 contact-stmt = contact-keyword sep string stmtend 6991 description-stmt = description-keyword sep string stmtend 6993 reference-stmt = reference-keyword sep string stmtend 6995 units-stmt = units-keyword sep string stmtend 6996 revision-stmt = revision-keyword sep revision-date optsep 6997 (";" / 6998 "{" stmtsep 6999 ;; these stmts can appear in any order 7000 [description-stmt] 7001 [reference-stmt] 7002 "}") stmtsep 7004 revision-date = date-arg-str 7006 revision-date-stmt = revision-date-keyword sep revision-date stmtend 7008 extension-stmt = extension-keyword sep identifier-arg-str optsep 7009 (";" / 7010 "{" stmtsep 7011 ;; these stmts can appear in any order 7012 [argument-stmt] 7013 [status-stmt] 7014 [description-stmt] 7015 [reference-stmt] 7016 "}") stmtsep 7018 argument-stmt = argument-keyword sep identifier-arg-str optsep 7019 (";" / 7020 "{" stmtsep 7021 [yin-element-stmt] 7022 "}") stmtsep 7024 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 7025 stmtend 7027 yin-element-arg-str = < a string that matches the rule > 7028 < yin-element-arg > 7030 yin-element-arg = true-keyword / false-keyword 7032 identity-stmt = identity-keyword sep identifier-arg-str optsep 7033 (";" / 7034 "{" stmtsep 7035 ;; these stmts can appear in any order 7036 *if-feature-stmt 7037 *base-stmt 7038 [status-stmt] 7039 [description-stmt] 7040 [reference-stmt] 7041 "}") stmtsep 7043 base-stmt = base-keyword sep identifier-ref-arg-str 7044 stmtend 7046 feature-stmt = feature-keyword sep identifier-arg-str optsep 7047 (";" / 7048 "{" stmtsep 7049 ;; these stmts can appear in any order 7050 *if-feature-stmt 7051 [status-stmt] 7052 [description-stmt] 7053 [reference-stmt] 7054 "}") stmtsep 7056 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 7057 stmtend 7059 if-feature-expr-str = < a string that matches the rule > 7060 < if-feature-expr > 7062 if-feature-expr = "(" if-feature-expr ")" / 7063 if-feature-expr sep boolean-operator sep 7064 if-feature-expr / 7065 not-keyword sep if-feature-expr / 7066 identifier-ref-arg 7068 boolean-operator = and-keyword / or-keyword 7070 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 7071 "{" stmtsep 7072 ;; these stmts can appear in any order 7073 type-stmt 7074 [units-stmt] 7075 [default-stmt] 7076 [status-stmt] 7077 [description-stmt] 7078 [reference-stmt] 7079 "}" stmtsep 7081 type-stmt = type-keyword sep identifier-ref-arg-str optsep 7082 (";" / 7083 "{" stmtsep 7084 [type-body-stmts] 7085 "}") stmtsep 7087 type-body-stmts = numerical-restrictions / 7088 decimal64-specification / 7089 string-restrictions / 7090 enum-specification / 7091 leafref-specification / 7092 identityref-specification / 7093 instance-identifier-specification / 7094 bits-specification / 7095 union-specification / 7096 binary-specification 7098 numerical-restrictions = range-stmt 7100 range-stmt = range-keyword sep range-arg-str optsep 7101 (";" / 7102 "{" stmtsep 7103 ;; these stmts can appear in any order 7104 [error-message-stmt] 7105 [error-app-tag-stmt] 7106 [description-stmt] 7107 [reference-stmt] 7108 "}") stmtsep 7110 decimal64-specification = ;; these stmts can appear in any order 7111 fraction-digits-stmt 7112 [range-stmt] 7114 fraction-digits-stmt = fraction-digits-keyword sep 7115 fraction-digits-arg-str stmtend 7117 fraction-digits-arg-str = < a string that matches the rule > 7118 < fraction-digits-arg > 7120 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 7121 "5" / "6" / "7" / "8"]) 7122 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 7124 string-restrictions = ;; these stmts can appear in any order 7125 [length-stmt] 7126 *pattern-stmt 7128 length-stmt = length-keyword sep length-arg-str optsep 7129 (";" / 7130 "{" stmtsep 7131 ;; these stmts can appear in any order 7132 [error-message-stmt] 7133 [error-app-tag-stmt] 7134 [description-stmt] 7135 [reference-stmt] 7136 "}") stmtsep 7138 pattern-stmt = pattern-keyword sep string optsep 7139 (";" / 7140 "{" stmtsep 7141 ;; these stmts can appear in any order 7142 [modifier-stmt] 7143 [error-message-stmt] 7144 [error-app-tag-stmt] 7145 [description-stmt] 7146 [reference-stmt] 7147 "}") stmtsep 7149 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 7151 modifier-arg-str = < a string that matches the rule > 7152 < modifier-arg > 7154 modifier-arg = invert-match-keyword 7156 default-stmt = default-keyword sep string stmtend 7158 enum-specification = 1*enum-stmt 7160 enum-stmt = enum-keyword sep string optsep 7161 (";" / 7162 "{" stmtsep 7163 ;; these stmts can appear in any order 7164 *if-feature-stmt 7165 [value-stmt] 7166 [status-stmt] 7167 [description-stmt] 7168 [reference-stmt] 7169 "}") stmtsep 7171 leafref-specification = 7172 ;; these stmts can appear in any order 7173 path-stmt 7174 [require-instance-stmt] 7176 path-stmt = path-keyword sep path-arg-str stmtend 7178 require-instance-stmt = require-instance-keyword sep 7179 require-instance-arg-str stmtend 7181 require-instance-arg-str = < a string that matches the rule > 7182 < require-instance-arg > 7184 require-instance-arg = true-keyword / false-keyword 7186 instance-identifier-specification = 7188 [require-instance-stmt] 7190 identityref-specification = 7191 1*base-stmt 7193 union-specification = 1*type-stmt 7195 binary-specification = [length-stmt] 7197 bits-specification = 1*bit-stmt 7199 bit-stmt = bit-keyword sep identifier-arg-str optsep 7200 (";" / 7201 "{" stmtsep 7202 ;; these stmts can appear in any order 7203 *if-feature-stmt 7204 [position-stmt] 7205 [status-stmt] 7206 [description-stmt] 7207 [reference-stmt] 7208 "}") stmtsep 7210 position-stmt = position-keyword sep 7211 position-value-arg-str stmtend 7213 position-value-arg-str = < a string that matches the rule > 7214 < position-value-arg > 7216 position-value-arg = non-negative-integer-value 7218 status-stmt = status-keyword sep status-arg-str stmtend 7220 status-arg-str = < a string that matches the rule > 7221 < status-arg > 7223 status-arg = current-keyword / 7224 obsolete-keyword / 7225 deprecated-keyword 7227 config-stmt = config-keyword sep 7228 config-arg-str stmtend 7230 config-arg-str = < a string that matches the rule > 7231 < config-arg > 7233 config-arg = true-keyword / false-keyword 7235 mandatory-stmt = mandatory-keyword sep 7236 mandatory-arg-str stmtend 7238 mandatory-arg-str = < a string that matches the rule > 7239 < mandatory-arg > 7241 mandatory-arg = true-keyword / false-keyword 7243 presence-stmt = presence-keyword sep string stmtend 7245 ordered-by-stmt = ordered-by-keyword sep 7246 ordered-by-arg-str stmtend 7248 ordered-by-arg-str = < a string that matches the rule > 7249 < ordered-by-arg > 7251 ordered-by-arg = user-keyword / system-keyword 7253 must-stmt = must-keyword sep string optsep 7254 (";" / 7255 "{" stmtsep 7256 ;; these stmts can appear in any order 7257 [error-message-stmt] 7258 [error-app-tag-stmt] 7259 [description-stmt] 7260 [reference-stmt] 7261 "}") stmtsep 7263 error-message-stmt = error-message-keyword sep string stmtend 7265 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 7267 min-elements-stmt = min-elements-keyword sep 7268 min-value-arg-str stmtend 7270 min-value-arg-str = < a string that matches the rule > 7271 < min-value-arg > 7273 min-value-arg = non-negative-integer-value 7275 max-elements-stmt = max-elements-keyword sep 7276 max-value-arg-str stmtend 7278 max-value-arg-str = < a string that matches the rule > 7279 < max-value-arg > 7281 max-value-arg = unbounded-keyword / 7282 positive-integer-value 7284 value-stmt = value-keyword sep integer-value-str stmtend 7286 integer-value-str = < a string that matches the rule > 7287 < integer-value > 7289 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 7290 (";" / 7291 "{" stmtsep 7292 ;; these stmts can appear in any order 7293 [status-stmt] 7294 [description-stmt] 7295 [reference-stmt] 7296 *(typedef-stmt / grouping-stmt) 7297 *data-def-stmt 7298 *action-stmt 7299 "}") stmtsep 7301 container-stmt = container-keyword sep identifier-arg-str optsep 7302 (";" / 7303 "{" stmtsep 7304 ;; these stmts can appear in any order 7305 [when-stmt] 7306 *if-feature-stmt 7307 *must-stmt 7308 [presence-stmt] 7309 [config-stmt] 7310 [status-stmt] 7311 [description-stmt] 7312 [reference-stmt] 7313 *(typedef-stmt / grouping-stmt) 7314 *data-def-stmt 7315 *action-stmt 7316 "}") stmtsep 7318 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 7319 "{" stmtsep 7320 ;; these stmts can appear in any order 7321 [when-stmt] 7322 *if-feature-stmt 7323 type-stmt 7324 [units-stmt] 7325 *must-stmt 7326 [default-stmt] 7327 [config-stmt] 7328 [mandatory-stmt] 7329 [status-stmt] 7330 [description-stmt] 7331 [reference-stmt] 7333 "}" stmtsep 7335 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 7336 "{" stmtsep 7337 ;; these stmts can appear in any order 7338 [when-stmt] 7339 *if-feature-stmt 7340 type-stmt stmtsep 7341 [units-stmt] 7342 *must-stmt 7343 *default-stmt 7344 [config-stmt] 7345 [min-elements-stmt] 7346 [max-elements-stmt] 7347 [ordered-by-stmt] 7348 [status-stmt] 7349 [description-stmt] 7350 [reference-stmt] 7351 "}" stmtsep 7353 list-stmt = list-keyword sep identifier-arg-str optsep 7354 "{" stmtsep 7355 ;; these stmts can appear in any order 7356 [when-stmt] 7357 *if-feature-stmt 7358 *must-stmt 7359 [key-stmt] 7360 *unique-stmt 7361 [config-stmt] 7362 [min-elements-stmt] 7363 [max-elements-stmt] 7364 [ordered-by-stmt] 7365 [status-stmt] 7366 [description-stmt] 7367 [reference-stmt] 7368 *(typedef-stmt / grouping-stmt) 7369 1*data-def-stmt 7370 *action-stmt 7371 "}" stmtsep 7373 key-stmt = key-keyword sep key-arg-str stmtend 7375 key-arg-str = < a string that matches the rule > 7376 < key-arg > 7378 key-arg = node-identifier *(sep node-identifier) 7380 unique-stmt = unique-keyword sep unique-arg-str stmtend 7381 unique-arg-str = < a string that matches the rule > 7382 < unique-arg > 7384 unique-arg = descendant-schema-nodeid 7385 *(sep descendant-schema-nodeid) 7387 choice-stmt = choice-keyword sep identifier-arg-str optsep 7388 (";" / 7389 "{" stmtsep 7390 ;; these stmts can appear in any order 7391 [when-stmt] 7392 *if-feature-stmt 7393 [default-stmt] 7394 [config-stmt] 7395 [mandatory-stmt] 7396 [status-stmt] 7397 [description-stmt] 7398 [reference-stmt] 7399 *(short-case-stmt / case-stmt) 7400 "}") stmtsep 7402 short-case-stmt = choice-stmt / 7403 container-stmt / 7404 leaf-stmt / 7405 leaf-list-stmt / 7406 list-stmt / 7407 anyxml-stmt 7409 case-stmt = case-keyword sep identifier-arg-str optsep 7410 (";" / 7411 "{" stmtsep 7412 ;; these stmts can appear in any order 7413 [when-stmt] 7414 *if-feature-stmt 7415 [status-stmt] 7416 [description-stmt] 7417 [reference-stmt] 7418 *data-def-stmt 7419 "}") stmtsep 7421 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 7422 (";" / 7423 "{" stmtsep 7424 ;; these stmts can appear in any order 7425 [when-stmt] 7426 *if-feature-stmt 7427 *must-stmt 7428 [config-stmt] 7430 [mandatory-stmt] 7431 [status-stmt] 7432 [description-stmt] 7433 [reference-stmt] 7434 "}") stmtsep 7436 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 7437 (";" / 7438 "{" stmtsep 7439 ;; these stmts can appear in any order 7440 [when-stmt] 7441 *if-feature-stmt 7442 [status-stmt] 7443 [description-stmt] 7444 [reference-stmt] 7445 *refine-stmt 7446 *uses-augment-stmt 7447 "}") stmtsep 7449 refine-stmt = refine-keyword sep refine-arg-str optsep 7450 "{" stmtsep 7451 ;; these stmts can appear in any order 7452 *if-feature-stmt 7453 *must-stmt 7454 [presence-stmt] 7455 [default-stmt] 7456 [config-stmt] 7457 [mandatory-stmt] 7458 [min-elements-stmt] 7459 [max-elements-stmt] 7460 [description-stmt] 7461 [reference-stmt] 7462 "}" stmtsep 7464 refine-arg-str = < a string that matches the rule > 7465 < refine-arg > 7467 refine-arg = descendant-schema-nodeid 7469 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 7470 "{" stmtsep 7471 ;; these stmts can appear in any order 7472 [when-stmt] 7473 *if-feature-stmt 7474 [status-stmt] 7475 [description-stmt] 7476 [reference-stmt] 7477 1*(data-def-stmt / case-stmt / action-stmt) 7479 "}" stmtsep 7481 uses-augment-arg-str = < a string that matches the rule > 7482 < uses-augment-arg > 7484 uses-augment-arg = descendant-schema-nodeid 7486 augment-stmt = augment-keyword sep augment-arg-str optsep 7487 "{" stmtsep 7488 ;; these stmts can appear in any order 7489 [when-stmt] 7490 *if-feature-stmt 7491 [status-stmt] 7492 [description-stmt] 7493 [reference-stmt] 7494 1*(data-def-stmt / case-stmt / action-stmt) 7495 "}" stmtsep 7497 augment-arg-str = < a string that matches the rule > 7498 < augment-arg > 7500 augment-arg = absolute-schema-nodeid 7502 when-stmt = when-keyword sep string optsep 7503 (";" / 7504 "{" stmtsep 7505 ;; these stmts can appear in any order 7506 [description-stmt] 7507 [reference-stmt] 7508 "}") stmtsep 7510 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 7511 (";" / 7512 "{" stmtsep 7513 ;; these stmts can appear in any order 7514 *if-feature-stmt 7515 [status-stmt] 7516 [description-stmt] 7517 [reference-stmt] 7518 *(typedef-stmt / grouping-stmt) 7519 [input-stmt] 7520 [output-stmt] 7521 "}") stmtsep 7523 action-stmt = action-keyword sep identifier-arg-str optsep 7524 (";" / 7525 "{" stmtsep 7526 ;; these stmts can appear in any order 7527 *if-feature-stmt 7528 [status-stmt] 7529 [description-stmt] 7530 [reference-stmt] 7531 *(typedef-stmt / grouping-stmt) 7532 [input-stmt] 7533 [output-stmt] 7534 "}") stmtsep 7536 input-stmt = input-keyword optsep 7537 "{" stmtsep 7538 ;; these stmts can appear in any order 7539 *must-stmt 7540 *(typedef-stmt / grouping-stmt) 7541 1*data-def-stmt 7542 "}" stmtsep 7544 output-stmt = output-keyword optsep 7545 "{" stmtsep 7546 ;; these stmts can appear in any order 7547 *must-stmt 7548 *(typedef-stmt / grouping-stmt) 7549 1*data-def-stmt 7550 "}" stmtsep 7552 notification-stmt = notification-keyword sep 7553 identifier-arg-str optsep 7554 (";" / 7555 "{" stmtsep 7556 ;; these stmts can appear in any order 7557 *if-feature-stmt 7558 *must-stmt 7559 [status-stmt] 7560 [description-stmt] 7561 [reference-stmt] 7562 *(typedef-stmt / grouping-stmt) 7563 *data-def-stmt 7564 "}") stmtsep 7566 deviation-stmt = deviation-keyword sep 7567 deviation-arg-str optsep 7568 "{" stmtsep 7569 ;; these stmts can appear in any order 7570 [description-stmt] 7571 [reference-stmt] 7572 (deviate-not-supported-stmt / 7573 1*(deviate-add-stmt / 7574 deviate-replace-stmt / 7575 deviate-delete-stmt)) 7576 "}" stmtsep 7578 deviation-arg-str = < a string that matches the rule > 7579 < deviation-arg > 7581 deviation-arg = absolute-schema-nodeid 7583 deviate-not-supported-stmt = 7584 deviate-keyword sep 7585 not-supported-keyword-str stmtend 7587 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 7588 (";" / 7589 "{" stmtsep 7590 ;; these stmts can appear in any order 7591 [units-stmt] 7592 *must-stmt 7593 *unique-stmt 7594 [default-stmt] 7595 [config-stmt] 7596 [mandatory-stmt] 7597 [min-elements-stmt] 7598 [max-elements-stmt] 7599 "}") stmtsep 7601 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 7602 (";" / 7603 "{" stmtsep 7604 ;; these stmts can appear in any order 7605 [units-stmt] 7606 *must-stmt 7607 *unique-stmt 7608 [default-stmt] 7609 "}") stmtsep 7611 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 7612 (";" / 7613 "{" stmtsep 7614 ;; these stmts can appear in any order 7615 [type-stmt] 7616 [units-stmt] 7617 [default-stmt] 7618 [config-stmt] 7619 [mandatory-stmt] 7620 [min-elements-stmt] 7621 [max-elements-stmt] 7622 "}") stmtsep 7624 not-supported-keyword-str = < a string that matches the rule > 7625 < not-supported-keyword > 7627 add-keyword-str = < a string that matches the rule > 7628 < add-keyword > 7630 delete-keyword-str = < a string that matches the rule > 7631 < delete-keyword > 7633 replace-keyword-str = < a string that matches the rule > 7634 < replace-keyword > 7636 ;; represents the usage of an extension statement 7637 unknown-statement = prefix ":" identifier [sep string] optsep 7638 (";" / 7639 "{" optsep 7640 *((yang-stmt / unknown-statement) optsep) 7641 "}") stmtsep 7643 yang-stmt = action-stmt / 7644 anyxml-stmt / 7645 argument-stmt / 7646 augment-stmt / 7647 base-stmt / 7648 belongs-to-stmt / 7649 bit-stmt / 7650 case-stmt / 7651 choice-stmt / 7652 config-stmt / 7653 contact-stmt / 7654 container-stmt / 7655 default-stmt / 7656 description-stmt / 7657 deviate-add-stmt / 7658 deviate-delete-stmt / 7659 deviate-not-supported-stmt / 7660 deviate-replace-stmt / 7661 deviation-stmt / 7662 enum-stmt / 7663 error-app-tag-stmt / 7664 error-message-stmt / 7665 extension-stmt / 7666 feature-stmt / 7667 fraction-digits-stmt / 7668 grouping-stmt / 7669 identity-stmt / 7670 if-feature-stmt / 7671 import-stmt / 7672 include-stmt / 7673 input-stmt / 7674 key-stmt / 7675 leaf-list-stmt / 7676 leaf-stmt / 7677 length-stmt / 7678 list-stmt / 7679 mandatory-stmt / 7680 max-elements-stmt / 7681 min-elements-stmt / 7682 modifier-stmt / 7683 module-stmt / 7684 must-stmt / 7685 namespace-stmt / 7686 notification-stmt / 7687 ordered-by-stmt / 7688 organization-stmt / 7689 output-stmt / 7690 path-stmt / 7691 pattern-stmt / 7692 position-stmt / 7693 prefix-stmt / 7694 presence-stmt / 7695 range-stmt / 7696 reference-stmt / 7697 refine-stmt / 7698 require-instance-stmt / 7699 revision-date-stmt / 7700 revision-stmt / 7701 rpc-stmt / 7702 status-stmt / 7703 submodule-stmt / 7704 typedef-stmt / 7705 type-stmt / 7706 unique-stmt / 7707 units-stmt / 7708 uses-augment-stmt / 7709 uses-stmt / 7710 value-stmt / 7711 when-stmt / 7712 yang-version-stmt / 7713 yin-element-stmt 7715 ;; Ranges 7717 range-arg-str = < a string that matches the rule > 7718 < range-arg > 7720 range-arg = range-part *(optsep "|" optsep range-part) 7722 range-part = range-boundary 7723 [optsep ".." optsep range-boundary] 7725 range-boundary = min-keyword / max-keyword / 7726 integer-value / decimal-value 7728 ;; Lengths 7730 length-arg-str = < a string that matches the rule > 7731 < length-arg > 7733 length-arg = length-part *(optsep "|" optsep length-part) 7735 length-part = length-boundary 7736 [optsep ".." optsep length-boundary] 7738 length-boundary = min-keyword / max-keyword / 7739 non-negative-integer-value 7741 ;; Date 7743 date-arg-str = < a string that matches the rule > 7744 < date-arg > 7746 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 7748 ;; Schema Node Identifiers 7750 schema-nodeid = absolute-schema-nodeid / 7751 descendant-schema-nodeid 7753 absolute-schema-nodeid = 1*("/" node-identifier) 7755 descendant-schema-nodeid = 7756 node-identifier 7757 [absolute-schema-nodeid] 7759 node-identifier = [prefix ":"] identifier 7761 ;; Instance Identifiers 7763 instance-identifier = 1*("/" (node-identifier *predicate)) 7765 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 7766 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 7767 ((DQUOTE string DQUOTE) / 7768 (SQUOTE string SQUOTE)) 7770 pos = non-negative-integer-value 7772 ;; leafref path 7774 path-arg-str = < a string that matches the rule > 7775 < path-arg > 7777 path-arg = absolute-path / relative-path 7779 absolute-path = 1*("/" (node-identifier *path-predicate)) 7781 relative-path = 1*(".." "/") descendant-path 7783 descendant-path = node-identifier 7784 [*path-predicate absolute-path] 7786 path-predicate = "[" *WSP path-equality-expr *WSP "]" 7788 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 7790 path-key-expr = current-function-invocation *WSP "/" *WSP 7791 rel-path-keyexpr 7793 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 7794 *(node-identifier *WSP "/" *WSP) 7795 node-identifier 7797 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 7799 ;; statement keywords 7800 action-keyword = %s"action" 7801 anyxml-keyword = %s"anyxml" 7802 argument-keyword = %s"argument" 7803 augment-keyword = %s"augment" 7804 base-keyword = %s"base" 7805 belongs-to-keyword = %s"belongs-to" 7806 bit-keyword = %s"bit" 7807 case-keyword = %s"case" 7808 choice-keyword = %s"choice" 7809 config-keyword = %s"config" 7810 contact-keyword = %s"contact" 7811 container-keyword = %s"container" 7812 default-keyword = %s"default" 7813 description-keyword = %s"description" 7814 enum-keyword = %s"enum" 7815 error-app-tag-keyword = %s"error-app-tag" 7816 error-message-keyword = %s"error-message" 7817 extension-keyword = %s"extension" 7818 deviation-keyword = %s"deviation" 7819 deviate-keyword = %s"deviate" 7820 feature-keyword = %s"feature" 7821 fraction-digits-keyword = %s"fraction-digits" 7822 grouping-keyword = %s"grouping" 7823 identity-keyword = %s"identity" 7824 if-feature-keyword = %s"if-feature" 7825 import-keyword = %s"import" 7826 include-keyword = %s"include" 7827 input-keyword = %s"input" 7828 key-keyword = %s"key" 7829 leaf-keyword = %s"leaf" 7830 leaf-list-keyword = %s"leaf-list" 7831 length-keyword = %s"length" 7832 list-keyword = %s"list" 7833 mandatory-keyword = %s"mandatory" 7834 max-elements-keyword = %s"max-elements" 7835 min-elements-keyword = %s"min-elements" 7836 modifier-keyword = %s"modifier" 7837 module-keyword = %s"module" 7838 must-keyword = %s"must" 7839 namespace-keyword = %s"namespace" 7840 notification-keyword= %s"notification" 7841 ordered-by-keyword = %s"ordered-by" 7842 organization-keyword= %s"organization" 7843 output-keyword = %s"output" 7844 path-keyword = %s"path" 7845 pattern-keyword = %s"pattern" 7846 position-keyword = %s"position" 7847 prefix-keyword = %s"prefix" 7848 presence-keyword = %s"presence" 7849 range-keyword = %s"range" 7850 reference-keyword = %s"reference" 7851 refine-keyword = %s"refine" 7852 require-instance-keyword = %s"require-instance" 7853 revision-keyword = %s"revision" 7854 revision-date-keyword = %s"revision-date" 7855 rpc-keyword = %s"rpc" 7856 status-keyword = %s"status" 7857 submodule-keyword = %s"submodule" 7858 type-keyword = %s"type" 7859 typedef-keyword = %s"typedef" 7860 unique-keyword = %s"unique" 7861 units-keyword = %s"units" 7862 uses-keyword = %s"uses" 7863 value-keyword = %s"value" 7864 when-keyword = %s"when" 7865 yang-version-keyword= %s"yang-version" 7866 yin-element-keyword = %s"yin-element" 7868 ;; other keywords 7870 add-keyword = %s"add" 7871 current-keyword = %s"current" 7872 delete-keyword = %s"delete" 7873 deprecated-keyword = %s"deprecated" 7874 false-keyword = %s"false" 7875 invert-match-keyword = %s"invert-match" 7876 max-keyword = %s"max" 7877 min-keyword = %s"min" 7878 not-supported-keyword = %s"not-supported" 7879 obsolete-keyword = %s"obsolete" 7880 replace-keyword = %s"replace" 7881 system-keyword = %s"system" 7882 true-keyword = %s"true" 7883 unbounded-keyword = %s"unbounded" 7884 user-keyword = %s"user" 7886 and-keyword = %s"and" 7887 or-keyword = %s"or" 7888 not-keyword = %s"not" 7890 current-function-invocation = current-keyword *WSP "(" *WSP ")" 7892 ;;; Basic Rules 7894 prefix-arg-str = < a string that matches the rule > 7895 < prefix-arg > 7897 prefix-arg = prefix 7899 prefix = identifier 7901 identifier-arg-str = < a string that matches the rule > 7902 < identifier-arg > 7904 identifier-arg = identifier 7906 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 7907 identifier = (ALPHA / "_") 7908 *(ALPHA / DIGIT / "_" / "-" / ".") 7910 identifier-ref-arg-str = < a string that matches the rule > 7911 < identifier-ref-arg > 7913 identifier-ref-arg = identifier-ref 7915 identifier-ref = [prefix ":"] identifier 7917 string = < an unquoted string as returned by > 7918 < the scanner, that matches the rule > 7919 < yang-string > 7921 yang-string = *yang-char 7923 ;; any Unicode character including tab, carriage return, and line 7924 ;; feed, but excluding the other C0 control characters, the surrogate 7925 ;; blocks, and the noncharacters. 7926 yang-char = %x9 / %xA / %xD / %x20-D7FF / 7927 ; exclude surrogate blocks %xD800-DFFF 7928 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 7929 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 7930 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 7931 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 7932 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 7933 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 7934 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 7935 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 7936 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 7937 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 7938 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 7939 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 7940 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 7941 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 7942 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 7943 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 7944 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 7945 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 7947 integer-value = ("-" non-negative-integer-value) / 7948 non-negative-integer-value 7950 non-negative-integer-value = "0" / positive-integer-value 7952 positive-integer-value = (non-zero-digit *DIGIT) 7954 zero-integer-value = 1*DIGIT 7956 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 7957 sep = 1*(WSP / line-break) 7958 ; unconditional separator 7960 optsep = *(WSP / line-break) 7962 stmtsep = *(WSP / line-break / unknown-statement) 7964 line-break = CRLF / LF 7966 non-zero-digit = %x31-39 7968 decimal-value = integer-value ("." zero-integer-value) 7970 SQUOTE = %x27 7971 ; ' (Single Quote) 7973 ;;; RFC 5234 core rules. 7975 ALPHA = %x41-5A / %x61-7A 7976 ; A-Z / a-z 7978 CR = %x0D 7979 ; carriage return 7981 CRLF = CR LF 7982 ; Internet standard new line 7984 DIGIT = %x30-39 7985 ; 0-9 7987 DQUOTE = %x22 7988 ; double quote 7990 HEXDIG = DIGIT / 7991 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 7992 ; only lower-case a..f 7994 HTAB = %x09 7995 ; horizontal tab 7997 LF = %x0A 7998 ; linefeed 8000 SP = %x20 8001 ; space 8003 VCHAR = %x21-7E 8004 ; visible (printing) characters 8006 WSP = SP / HTAB 8007 ; whitespace 8009 8011 14. Error Responses for YANG Related Errors 8013 A number of NETCONF error responses are defined for error cases 8014 related to the data-model handling. If the relevant YANG statement 8015 has an "error-app-tag" substatement, that overrides the default value 8016 specified below. 8018 14.1. Error Message for Data That Violates a unique Statement 8020 If a NETCONF operation would result in configuration data where a 8021 unique constraint is invalidated, the following error is returned: 8023 error-tag: operation-failed 8024 error-app-tag: data-not-unique 8025 error-info: : Contains an instance identifier that 8026 points to a leaf that invalidates the unique 8027 constraint. This element is present once for each 8028 non-unique leaf. 8030 The element is in the YANG 8031 namespace ("urn:ietf:params:xml:ns:yang:1"). 8033 14.2. Error Message for Data That Violates a max-elements Statement 8035 If a NETCONF operation would result in configuration data where a 8036 list or a leaf-list would have too many entries the following error 8037 is returned: 8039 error-tag: operation-failed 8040 error-app-tag: too-many-elements 8042 This error is returned once, with the error-path identifying the list 8043 node, even if there are more than one extra child present. 8045 14.3. Error Message for Data That Violates a min-elements Statement 8047 If a NETCONF operation would result in configuration data where a 8048 list or a leaf-list would have too few entries the following error is 8049 returned: 8051 error-tag: operation-failed 8052 error-app-tag: too-few-elements 8054 This error is returned once, with the error-path identifying the list 8055 node, even if there are more than one child missing. 8057 14.4. Error Message for Data That Violates a must Statement 8059 If a NETCONF operation would result in configuration data where the 8060 restrictions imposed by a "must" statement is violated the following 8061 error is returned, unless a specific "error-app-tag" substatement is 8062 present for the "must" statement. 8064 error-tag: operation-failed 8065 error-app-tag: must-violation 8067 14.5. Error Message for Data That Violates a require-instance Statement 8069 If a NETCONF operation would result in configuration data where a 8070 leaf of type "instance-identifier" marked with require-instance 8071 "true" refers to a non-existing instance, the following error is 8072 returned: 8074 error-tag: data-missing 8075 error-app-tag: instance-required 8076 error-path: Path to the instance-identifier leaf. 8078 14.6. Error Message for Data That Does Not Match a leafref Type 8080 If a NETCONF operation would result in configuration data where a 8081 leaf of type "leafref" refers to a non-existing instance, the 8082 following error is returned: 8084 error-tag: data-missing 8085 error-app-tag: instance-required 8086 error-path: Path to the leafref leaf. 8088 14.7. Error Message for Data That Violates a mandatory choice Statement 8090 If a NETCONF operation would result in configuration data where no 8091 nodes exists in a mandatory choice, the following error is returned: 8093 error-tag: data-missing 8094 error-app-tag: missing-choice 8095 error-path: Path to the element with the missing choice. 8096 error-info: : Contains the name of the missing 8097 mandatory choice. 8099 The element is in the YANG 8100 namespace ("urn:ietf:params:xml:ns:yang:1"). 8102 14.8. Error Message for the "insert" Operation 8104 If the "insert" and "key" or "value" attributes are used in an 8105 for a list or leaf-list node, and the "key" or "value" 8106 refers to a non-existing instance, the following error is returned: 8108 error-tag: bad-attribute 8109 error-app-tag: missing-instance 8111 15. IANA Considerations 8113 This document defines a registry for YANG module and submodule names. 8114 The name of the registry is "YANG Module Names". 8116 The registry shall record for each entry: 8118 o the name of the module or submodule 8120 o for modules, the assigned XML namespace 8122 o for modules, the prefix of the module 8124 o for submodules, the name of the module it belongs to 8126 o a reference to the (sub)module's documentation (e.g., the RFC 8127 number) 8129 There are no initial assignments. 8131 For allocation, RFC publication is required as per RFC 5226 8132 [RFC5226]. All registered YANG module names MUST comply with the 8133 rules for identifiers stated in Section 6.2, and MUST have a module 8134 name prefix. 8136 The module name prefix 'ietf-' is reserved for IETF stream documents 8137 [RFC4844], while the module name prefix 'irtf-' is reserved for IRTF 8138 stream documents. Modules published in other RFC streams MUST have a 8139 similar suitable prefix. 8141 All module and submodule names in the registry MUST be unique. 8143 All XML namespaces in the registry MUST be unique. 8145 This document registers two URIs for the YANG and YIN XML namespaces 8146 in the IETF XML registry [RFC3688]. Following the format in RFC 8147 3688, the following have been registered. 8149 URI: urn:ietf:params:xml:ns:yang:yin:1 8150 URI: urn:ietf:params:xml:ns:yang:1 8152 Registrant Contact: The IESG. 8154 XML: N/A, the requested URIs are XML namespaces. 8156 This document registers one capability identifier URN from the 8157 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 8159 urn:ietf:params:netconf:capability:yang-library:1.0 8161 This document registers two new media types as defined in the 8162 following sections. 8164 15.1. Media type application/yang 8165 MIME media type name: application 8167 MIME subtype name: yang 8169 Mandatory parameters: none 8171 Optional parameters: none 8173 Encoding considerations: 8-bit 8175 Security considerations: See Section 15 in RFC XXXX 8177 Interoperability considerations: None 8179 Published specification: RFC XXXX 8181 Applications that use this media type: 8183 YANG module validators, web servers used for downloading YANG 8184 modules, email clients, etc. 8186 Additional information: 8188 Magic Number: None 8190 File Extension: .yang 8192 Macintosh file type code: 'TEXT' 8194 Personal and email address for further information: 8195 Martin Bjorklund 8197 Intended usage: COMMON 8199 Author: 8200 This specification is a work item of the IETF NETMOD working 8201 group, with mailing list address . 8203 Change controller: 8204 The IESG 8206 15.2. Media type application/yin+xml 8207 MIME media type name: application 8209 MIME subtype name: yin+xml 8211 Mandatory parameters: none 8213 Optional parameters: 8215 "charset": This parameter has identical semantics to the 8216 charset parameter of the "application/xml" media type as 8217 specified in [RFC3023]. 8219 Encoding considerations: 8221 Identical to those of "application/xml" as 8222 described in [RFC3023], Section 3.2. 8224 Security considerations: See Section 15 in RFC XXXX 8226 Interoperability considerations: None 8228 Published specification: RFC XXXX 8230 Applications that use this media type: 8232 YANG module validators, web servers used for downloading YANG 8233 modules, email clients, etc. 8235 Additional information: 8237 Magic Number: As specified for "application/xml" in [RFC3023], 8238 Section 3.2. 8240 File Extension: .yin 8242 Macintosh file type code: 'TEXT' 8244 Personal and email address for further information: 8245 Martin Bjorklund 8247 Intended usage: COMMON 8249 Author: 8250 This specification is a work item of the IETF NETMOD working 8251 group, with mailing list address . 8253 Change controller: 8254 The IESG 8256 16. Security Considerations 8258 This document defines a language with which to write and read 8259 descriptions of management information. The language itself has no 8260 security impact on the Internet. 8262 The same considerations are relevant as for the base NETCONF protocol 8263 (see [RFC6241], Section 9). 8265 Data modeled in YANG might contain sensitive information. RPCs or 8266 notifications defined in YANG might transfer sensitive information. 8268 Security issues are related to the usage of data modeled in YANG. 8269 Such issues shall be dealt with in documents describing the data 8270 models and documents about the interfaces used to manipulate the data 8271 e.g., the NETCONF documents. 8273 Data modeled in YANG is dependent upon: 8275 o the security of the transmission infrastructure used to send 8276 sensitive information. 8278 o the security of applications that store or release such sensitive 8279 information. 8281 o adequate authentication and access control mechanisms to restrict 8282 the usage of sensitive data. 8284 YANG parsers need to be robust with respect to malformed documents. 8285 Reading malformed documents from unknown or untrusted sources could 8286 result in an attacker gaining privileges of the user running the YANG 8287 parser. In an extreme situation, the entire machine could be 8288 compromised. 8290 17. Contributors 8292 The following people all contributed significantly to the initial 8293 YANG document: 8295 - Andy Bierman (Brocade) 8296 - Balazs Lengyel (Ericsson) 8297 - David Partain (Ericsson) 8298 - Juergen Schoenwaelder (Jacobs University Bremen) 8299 - Phil Shafer (Juniper Networks) 8301 18. Acknowledgements 8303 The editor wishes to thank the following individuals, who all 8304 provided helpful comments on various versions of this document: 8305 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 8306 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 8307 Wijnen. 8309 19. ChangeLog 8311 RFC Editor: remove this section upon publication as an RFC. 8313 19.1. Version -04 8315 o Incorporated changes to ABNF grammar after review and errata for 8316 RFC 6020. 8318 o Included solution Y16-03. 8320 o Included solution Y49-04. 8322 o Included solution Y58-01. 8324 o Included solution Y59-01. 8326 19.2. Version -03 8328 o Incorporated changes from WG reviews. 8330 o Included solution Y05-01. 8332 o Included solution Y10-01. 8334 o Included solution Y13-01. 8336 o Included solution Y28-02. 8338 o Included solution Y55-01 (parts of it was included in -01). 8340 19.3. Version -02 8342 o Included solution Y02-01. 8344 o Included solution Y04-02. 8346 o Included solution Y11-01. 8348 o Included solution Y41-01. 8350 o Included solution Y56-01. 8352 19.4. Version -01 8354 o Included solution Y01-01. 8356 o Included solution Y03-01. 8358 o Included solution Y06-02. 8360 o Included solution Y07-01. 8362 o Included solution Y14-01. 8364 o Included solution Y20-01. 8366 o Included solution Y23-01. 8368 o Included solution Y29-01. 8370 o Included solution Y30-01. 8372 o Included solution Y31-01. 8374 o Included solution Y35-01. 8376 19.5. Version -00 8378 o Applied all reported errata for RFC 6020. 8380 o Updated YANG version to 1.1, and made the "yang-version" statement 8381 mandatory. 8383 20. References 8385 20.1. Normative References 8387 [I-D.ietf-netconf-yang-library] 8388 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 8389 Library", draft-ietf-netconf-yang-library (work in 8390 progress), January 2015. 8392 [ISO.10646] 8393 International Organization for Standardization, 8394 "Information Technology - Universal Multiple-Octet Coded 8395 Character Set (UCS)", ISO Standard 10646:2003, 2003. 8397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8398 Requirement Levels", BCP 14, RFC 2119, March 1997. 8400 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 8401 Types", RFC 3023, January 2001. 8403 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 8404 10646", STD 63, RFC 3629, November 2003. 8406 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 8407 January 2004. 8409 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8410 Resource Identifier (URI): Generic Syntax", STD 66, RFC 8411 3986, January 2005. 8413 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8414 Encodings", RFC 4648, October 2006. 8416 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 8417 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 8418 May 2008. 8420 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 8421 Specifications: ABNF", STD 68, RFC 5234, January 2008. 8423 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 8424 Notifications", RFC 5277, July 2008. 8426 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 8427 Bierman, "Network Configuration Protocol (NETCONF)", RFC 8428 6241, June 2011. 8430 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 8431 7405, December 2014. 8433 [XML-NAMES] 8434 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 8435 Layman, "Namespaces in XML 1.0 (Third Edition)", World 8436 Wide Web Consortium Recommendation REC-xml-names-20091208, 8437 December 2009, 8438 . 8440 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 8441 Version 1.0", World Wide Web Consortium Recommendation 8442 REC-xpath-19991116, November 1999, 8443 . 8445 [XSD-TYPES] 8446 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 8447 Second Edition", World Wide Web Consortium Recommendation 8448 REC-xmlschema-2-20041028, October 2004, 8449 . 8451 20.2. Informative References 8453 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8454 Schoenwaelder, Ed., "Structure of Management Information 8455 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 8457 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8458 Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 8459 58, RFC 2579, April 1999. 8461 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 8462 Structure of Management Information", RFC 3780, May 2004. 8464 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 8465 Series and RFC Editor", RFC 4844, July 2007. 8467 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 8468 Network Configuration Protocol (NETCONF)", RFC 6020, 8469 October 2010. 8471 [XPATH2.0] 8472 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 8473 Kay, M., Robie, J., and J. Simeon, "XML Path Language 8474 (XPath) 2.0", World Wide Web Consortium Recommendation 8475 REC-xpath20-20070123, January 2007, 8476 . 8478 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 8479 Wide Web Consortium Recommendation REC-xslt-19991116, 8480 November 1999, 8481 . 8483 Author's Address 8485 Martin Bjorklund (editor) 8486 Tail-f Systems 8488 Email: mbj@tail-f.com