idnits 2.17.1 draft-ietf-netmod-rfc6020bis-14.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 == Line 9181 has weird spacing: '...library urn:...' == 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). == 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 (June 17, 2016) is 2870 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 7307 == Unused Reference: 'RFC6691' is defined on line 9482, but no explicit reference was found in the text -- 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' == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-13 == Outdated reference: A later version (-20) exists of draft-ietf-netmod-rfc6087bis-06 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-09 -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) -- Obsolete informational reference (is this intentional?): RFC 6691 (Obsoleted by RFC 9293) Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track June 17, 2016 5 Expires: December 19, 2016 7 The YANG 1.1 Data Modeling Language 8 draft-ietf-netmod-rfc6020bis-14 10 Abstract 12 YANG is a data modeling language used to model configuration data, 13 state data, remote procedure calls, and notifications for network 14 management protocols. This document describes the syntax and 15 semantics of version 1.1 of the YANG language. YANG version 1.1 is a 16 maintenance release of the YANG language, addressing ambiguities and 17 defects in the original specification. There are a small number of 18 backward incompatibilities from YANG version 1. This document also 19 specifies the YANG mappings to the Network Configuration Protocol 20 (NETCONF). 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 19, 2016. 39 Copyright Notice 41 Copyright (c) 2016 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 69 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 9 70 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 3.1. A Note on Examples . . . . . . . . . . . . . . . . . . . 14 73 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 74 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 15 75 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 16 76 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 16 77 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 17 78 4.2.3. Configuration and State Data . . . . . . . . . . . . 21 79 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 21 80 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 22 81 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 23 82 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 24 83 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 25 84 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 26 85 4.2.10. Notification Definitions . . . . . . . . . . . . . . 29 86 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 29 87 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 29 88 5.1.1. Import and Include by Revision . . . . . . . . . . . 31 89 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 32 90 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 33 91 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 34 92 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 34 93 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 34 94 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 34 95 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 35 96 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 35 97 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 36 98 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 36 99 5.6.4. Announcing Conformance Information in NETCONF . . . . 37 100 5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 38 101 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 41 102 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 41 103 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 42 104 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 42 105 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 42 106 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 42 107 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 44 108 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 44 109 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 45 110 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 46 111 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 46 112 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 47 113 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 51 114 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 52 115 7.1. The module Statement . . . . . . . . . . . . . . . . . . 52 116 7.1.1. The module's Substatements . . . . . . . . . . . . . 53 117 7.1.2. The yang-version Statement . . . . . . . . . . . . . 54 118 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 55 119 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 55 120 7.1.5. The import Statement . . . . . . . . . . . . . . . . 56 121 7.1.6. The include Statement . . . . . . . . . . . . . . . . 57 122 7.1.7. The organization Statement . . . . . . . . . . . . . 57 123 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 58 124 7.1.9. The revision Statement . . . . . . . . . . . . . . . 58 125 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 58 126 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 59 127 7.2.1. The submodule's Substatements . . . . . . . . . . . . 60 128 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 61 129 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 62 130 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 62 131 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 63 132 7.3.2. The typedef's type Statement . . . . . . . . . . . . 63 133 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 63 134 7.3.4. The typedef's default Statement . . . . . . . . . . . 63 135 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 64 136 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 64 137 7.4.1. The type's Substatements . . . . . . . . . . . . . . 64 138 7.5. The container Statement . . . . . . . . . . . . . . . . . 64 139 7.5.1. Containers with Presence . . . . . . . . . . . . . . 65 140 7.5.2. The container's Substatements . . . . . . . . . . . . 65 141 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 66 142 7.5.4. The must's Substatements . . . . . . . . . . . . . . 67 143 7.5.5. The presence Statement . . . . . . . . . . . . . . . 68 144 7.5.6. The container's Child Node Statements . . . . . . . . 68 145 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 68 146 7.5.8. NETCONF Operations . . . . . . . . . . 69 147 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 69 148 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 71 149 7.6.1. The leaf's default value . . . . . . . . . . . . . . 71 150 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 72 151 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 72 152 7.6.4. The leaf's default Statement . . . . . . . . . . . . 72 153 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 73 154 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 73 155 7.6.7. NETCONF Operations . . . . . . . . . . 73 156 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 74 157 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 74 158 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 75 159 7.7.2. The leaf-list's default values . . . . . . . . . . . 75 160 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 76 161 7.7.4. The leaf-list's default Statement . . . . . . . . . . 77 162 7.7.5. The min-elements Statement . . . . . . . . . . . . . 77 163 7.7.6. The max-elements Statement . . . . . . . . . . . . . 78 164 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 78 165 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 79 166 7.7.9. NETCONF Operations . . . . . . . . . . 79 167 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 80 168 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 81 169 7.8.1. The list's Substatements . . . . . . . . . . . . . . 82 170 7.8.2. The list's key Statement . . . . . . . . . . . . . . 82 171 7.8.3. The list's unique Statement . . . . . . . . . . . . . 83 172 7.8.4. The list's Child Node Statements . . . . . . . . . . 84 173 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 84 174 7.8.6. NETCONF Operations . . . . . . . . . . 85 175 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 176 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 89 177 7.9.1. The choice's Substatements . . . . . . . . . . . . . 89 178 7.9.2. The choice's case Statement . . . . . . . . . . . . . 90 179 7.9.3. The choice's default Statement . . . . . . . . . . . 91 180 7.9.4. The choice's mandatory Statement . . . . . . . . . . 93 181 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 93 182 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 93 183 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 94 184 7.10.1. The anydata's Substatements . . . . . . . . . . . . 95 185 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 95 186 7.10.3. NETCONF Operations . . . . . . . . . . 95 187 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 96 188 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 97 189 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 97 190 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 97 191 7.11.3. NETCONF Operations . . . . . . . . . . 98 192 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 98 194 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 99 195 7.12.1. The grouping's Substatements . . . . . . . . . . . . 99 196 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 100 197 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 100 198 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 101 199 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 101 200 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 201 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 102 202 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 103 203 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 103 204 7.14.2. The input Statement . . . . . . . . . . . . . . . . 104 205 7.14.3. The output Statement . . . . . . . . . . . . . . . . 105 206 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 106 207 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 106 208 7.15. The action Statement . . . . . . . . . . . . . . . . . . 107 209 7.15.1. The action's Substatements . . . . . . . . . . . . . 108 210 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 211 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 212 7.16. The notification Statement . . . . . . . . . . . . . . . 110 213 7.16.1. The notification's Substatements . . . . . . . . . . 111 214 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 111 215 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 216 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 113 217 7.17.1. The augment's Substatements . . . . . . . . . . . . 115 218 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 116 219 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 220 7.18. The identity Statement . . . . . . . . . . . . . . . . . 118 221 7.18.1. The identity's Substatements . . . . . . . . . . . . 118 222 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 118 223 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 224 7.19. The extension Statement . . . . . . . . . . . . . . . . . 121 225 7.19.1. The extension's Substatements . . . . . . . . . . . 121 226 7.19.2. The argument Statement . . . . . . . . . . . . . . . 121 227 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 122 228 7.20. Conformance-Related Statements . . . . . . . . . . . . . 123 229 7.20.1. The feature Statement . . . . . . . . . . . . . . . 123 230 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 125 231 7.20.3. The deviation Statement . . . . . . . . . . . . . . 125 232 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 129 233 7.21.1. The config Statement . . . . . . . . . . . . . . . . 129 234 7.21.2. The status Statement . . . . . . . . . . . . . . . . 129 235 7.21.3. The description Statement . . . . . . . . . . . . . 130 236 7.21.4. The reference Statement . . . . . . . . . . . . . . 130 237 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 131 238 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 132 239 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 132 240 8.2. Configuration Data Modifications . . . . . . . . . . . . 133 241 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 133 242 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 133 243 8.3.2. NETCONF Processing . . . . . . . . . . 134 244 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 135 245 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 135 246 9.1. Canonical Representation . . . . . . . . . . . . . . . . 135 247 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 136 248 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 136 249 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 137 250 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 137 251 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 137 252 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 253 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 138 254 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 139 255 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 139 256 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 139 257 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 139 258 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 140 259 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 140 260 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 140 261 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 262 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 263 9.4.4. The length Statement . . . . . . . . . . . . . . . . 141 264 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 142 265 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 142 266 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 142 267 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 144 268 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 144 269 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 270 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 271 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 144 272 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 144 273 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 274 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 275 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 144 276 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 277 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 147 278 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 279 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 147 280 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 281 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 148 282 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 149 283 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 150 284 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 285 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 150 286 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 150 287 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 150 288 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 289 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 151 290 9.9.3. The require-instance Statement . . . . . . . . . . . 152 291 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 152 292 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 152 293 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 152 294 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 156 295 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 296 9.10.2. The identityref's base Statement . . . . . . . . . . 156 297 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 156 298 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 157 299 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 157 300 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 158 301 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 302 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 158 303 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 304 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 305 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 159 306 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 159 307 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 159 308 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 159 309 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 310 9.13. The instance-identifier Built-In Type . . . . . . . . . . 160 311 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 161 312 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 161 313 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 161 314 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 162 315 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 162 316 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 162 317 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 162 318 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 163 319 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 163 320 10.3. Functions for the YANG Types "leafref" and "instance- 321 identifier" . . . . . . . . . . . . . . . . . . . . . . 164 322 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 164 323 10.4. Functions for the YANG Type "identityref" . . . . . . . 165 324 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 165 325 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 166 326 10.5. Functions for the YANG Type "enumeration" . . . . . . . 167 327 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 167 328 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 168 329 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 168 330 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 169 331 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 171 332 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 333 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 172 334 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 175 335 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 176 336 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 200 337 15.1. Error Message for Data That Violates a unique Statement 201 338 15.2. Error Message for Data That Violates a max-elements 339 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 340 15.3. Error Message for Data That Violates a min-elements 341 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 342 15.4. Error Message for Data That Violates a must Statement . 201 343 15.5. Error Message for Data That Violates a require-instance 344 Statement . . . . . . . . . . . . . . . . . . . . . . . 202 345 15.6. Error Message for Data That Violates a mandatory choice 346 Statement . . . . . . . . . . . . . . . . . . . . . . . 202 347 15.7. Error Message for the "insert" Operation . . . . . . . . 202 348 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 202 349 17. Security Considerations . . . . . . . . . . . . . . . . . . . 203 350 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 203 351 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 204 352 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 204 353 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 204 354 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 204 355 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 204 356 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 205 357 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 205 358 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 205 359 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 205 360 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 205 361 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 206 362 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 206 363 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 206 364 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 206 365 21.1. Normative References . . . . . . . . . . . . . . . . . . 207 366 21.2. Informative References . . . . . . . . . . . . . . . . . 208 367 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 209 369 1. Introduction 371 YANG is a data modeling language originally designed to model 372 configuration and state data manipulated by the Network Configuration 373 Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF 374 notifications [RFC6241]. Since the publication of YANG version 1 375 [RFC6020], YANG has been used or proposed to be used for other 376 protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI 377 [I-D.vanderstok-core-comi]). Further, other encodings than XML have 378 been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). 380 This document describes the syntax and semantics of version 1.1 of 381 the YANG language. It also describes how a data model defined in a 382 YANG module is encoded in the Extensible Markup Language (XML), and 383 how NETCONF operations are used to manipulate the data. Other 384 protocols and encodings are possible, but out of scope for this 385 specification. 387 In terms of developing YANG data models, [I-D.ietf-netmod-rfc6087bis] 388 provides some guidelines and recommendations. 390 Note that this document does not obsolete RFC 6020 [RFC6020]. 392 1.1. Summary of Changes from RFC 6020 394 This document defines version 1.1 of the YANG language. YANG version 395 1.1 is a maintenance release of the YANG language, addressing 396 ambiguities and defects in the original specification [RFC6020]. 398 The following changes are not backwards compatible with YANG version 399 1: 401 o Changed the rules for the interpretation of escaped characters in 402 double quoted strings. This is an backwards incompatible change 403 from YANG version 1. When updating a YANG version 1 module to 404 1.1, and the module uses a character sequence that is now illegal, 405 the string must be changed to match the new rules. See 406 Section 6.1.3 for details. 408 o An unquoted string cannot contain any single or double quote 409 characters. This is an backwards incompatible change from YANG 410 version 1. When updating a YANG version 1 module to 1.1, and the 411 module uses such quote characters, the string must be changed to 412 match the new rules. See Section 6.1.3 for details. 414 o Made "when" and "if-feature" illegal on list keys. This is an 415 backwards incompatible change from YANG version 1. When updating 416 a YANG version 1 module to 1.1, and the module uses these 417 constructs, they must be removed to match the new rules. 419 o Defined the legal characters in YANG modules. When updating a 420 YANG version 1 module to 1.1, any characters that are now illegal 421 must be removed. See Section 6 for details. 423 o Made noncharacters illegal in the built-in type "string". This 424 change affects the run-time behavior of YANG-based protocols. 426 The following additional changes have been done to YANG: 428 o Changed the YANG version from "1" to "1.1". 430 o Made the "yang-version" statement mandatory in YANG version "1.1". 432 o Extended the "if-feature" syntax to be a boolean expression over 433 feature names. 435 o Allow "if-feature" in "bit", "enum", and "identity". 437 o Allow "if-feature" in "refine". 439 o Allow "choice" as a shorthand case statement (see Section 7.9). 441 o Added a new substatement "modifier" to pattern (see 442 Section 9.4.6). 444 o Allow "must" in "input", "output", and "notification". 446 o Allow "require-instance" in leafref. 448 o Allow "description" and "reference" in "import" and "include". 450 o Allow imports of multiple revisions of a module. 452 o Allow "augment" to add conditionally mandatory nodes (see 453 Section 7.17). 455 o Added a set of new XPath functions in Section 10. 457 o Clarified the XPath context's tree in Section 6.4.1. 459 o Defined the string value of an identityref in XPath expressions 460 (see Section 9.10). 462 o Clarified what unprefixed names mean in leafrefs in typedefs (see 463 Section 6.4.1 and Section 9.9.2). 465 o Allow identities to be derived from multiple base identities (see 466 Section 7.18 and Section 9.10). 468 o Allow enumerations and bits to be subtyped (see Section 9.6 and 469 Section 9.7). 471 o Allow leaf-lists to have default values (see Section 7.7.2). 473 o Allow non-unique values in non-configuration leaf-lists (see 474 Section 7.7). 476 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 478 o Changed the module advertisement mechanism (see Section 5.6.4). 480 o Changed the scoping rules for definitions in submodules. A 481 submodule can now reference all definitions in all submodules that 482 belong to the same module, without using the "include" statement. 484 o Added a new statement "action" that is used to define operations 485 tied to data nodes. 487 o Allow notifications to be tied to data nodes. 489 o Added a new data definition statement "anydata" (see Section 7.10) 490 which is RECOMMENDED to be used instead of "anyxml" when the data 491 can be modeled in YANG 493 o Allow types empty and leafref in unions. 495 o Allow type empty in a key. 497 The following changes have been done to the NETCONF mapping: 499 o A server advertises support for YANG 1.1 modules by using ietf- 500 yang-library [I-D.ietf-netconf-yang-library] instead of listing 501 them as capabilities in the message. 503 2. Keywords 505 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 506 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 507 "OPTIONAL" in this document are to be interpreted as described in BCP 508 14, [RFC2119]. 510 3. Terminology 512 The following terms are used within this document: 514 o action: An operation defined for a node in the data tree. 516 o anydata: A data node that can contain an unknown set of nodes that 517 can be modelled by YANG, except anyxml. 519 o anyxml: A data node that can contain an unknown chunk of XML data. 521 o augment: Adds new schema nodes to a previously defined schema 522 node. 524 o base type: The type from which a derived type was derived, which 525 may be either a built-in type or another derived type. 527 o built-in type: A YANG data type defined in the YANG language, such 528 as uint32 or string. 530 o choice: A schema node where only one of a number of identified 531 alternatives is valid. 533 o client: An entity that can access YANG-defined data on a server, 534 over some network management protocol. 536 o conformance: A measure of how accurately a server follows a data 537 model. 539 o container: An interior data node that exists in at most one 540 instance in the data tree. A container has no value, but rather a 541 set of child nodes. 543 o data definition statement: A statement that defines new data 544 nodes. One of container, leaf, leaf-list, list, choice, case, 545 augment, uses, anydata, and anyxml. 547 o data model: A data model describes how data is represented and 548 accessed. 550 o data node: A node in the schema tree that can be instantiated in a 551 data tree. One of container, leaf, leaf-list, list, anydata, and 552 anyxml. 554 o data tree: An instantiated tree of any data modeled with YANG, 555 e.g., configuration data, state data, combined configuration and 556 state data, RPC or action input, RPC or action output, or 557 notification. 559 o derived type: A type that is derived from a built-in type (such as 560 uint32), or another derived type. 562 o extension: An extension attaches non-YANG semantics to statements. 563 The extension statement defines new statements to express these 564 semantics. 566 o feature: A mechanism for marking a portion of the model as 567 optional. Definitions can be tagged with a feature name and are 568 only valid on servers that support that feature. 570 o grouping: A reusable set of schema nodes, which may be used 571 locally in the module and by other modules that import from it. 572 The grouping statement is not a data definition statement and, as 573 such, does not define any nodes in the schema tree. 575 o identifier: A string used to identify different kinds of YANG 576 items by name. 578 o identity: A globally unique, abstract, and untyped name. 580 o instance identifier: A mechanism for identifying a particular node 581 in a data tree. 583 o interior node: Nodes within a hierarchy that are not leaf nodes. 585 o leaf: A data node that exists in at most one instance in the data 586 tree. A leaf has a value but no child nodes. 588 o leaf-list: Like the leaf node but defines a set of uniquely 589 identifiable nodes rather than a single node. Each node has a 590 value but no child nodes. 592 o list: An interior data node that may exist in multiple instances 593 in the data tree. A list has no value, but rather a set of child 594 nodes. 596 o mandatory node: A mandatory node is one of: 598 * A leaf, choice, anydata, or anyxml node with a "mandatory" 599 statement with the value "true". 601 * A list or leaf-list node with a "min-elements" statement with a 602 value greater than zero. 604 * A container node without a "presence" statement and which has 605 at least one mandatory node as a child. 607 o module: A YANG module defines hierarchies of schema nodes. With 608 its definitions and the definitions it imports or includes from 609 elsewhere, a module is self-contained and "compilable". 611 o non-presence container: A container that has no meaning of its 612 own, existing only to contain child nodes. 614 o presence container: A container where the presence of the 615 container itself carries some meaning. 617 o RPC: A Remote Procedure Call. 619 o RPC operation: A specific Remote Procedure Call. 621 o schema node: A node in the schema tree. One of action, container, 622 leaf, leaf-list, list, choice, case, rpc, input, output, 623 notification, anydata, and anyxml. 625 o schema node identifier: A mechanism for identifying a particular 626 node in the schema tree. 628 o schema tree: The definition hierarchy specified within a module. 630 o server: An entity that provides access to YANG-defined data to a 631 client, over some network management protocol. 633 o server deviation: A failure of the server to implement a module 634 faithfully. 636 o submodule: A partial module definition that contributes derived 637 types, groupings, data nodes, RPCs, actions, and notifications to 638 a module. A YANG module can be constructed from a number of 639 submodules. 641 o top-level data node: A data node where there is no other data node 642 between it and a module or submodule statement. 644 o uses: The "uses" statement is used to instantiate the set of 645 schema nodes defined in a grouping statement. The instantiated 646 nodes may be refined and augmented to tailor them to any specific 647 needs. 649 o value space: For a data type; the set of values permitted by the 650 data type. For a leaf or leaf-list instance; the value space of 651 its data type. 653 The following terms are defined in [RFC6241]: 655 o configuration data 657 o configuration datastore 659 o datastore 661 o state data 663 When modelled with YANG, a datastore is realized as an instantiated 664 data tree. 666 When modelled with YANG, a configuration datastore is realized as an 667 instantiated data tree with configuration data. 669 3.1. A Note on Examples 671 Throughout this document there are many examples of YANG statements. 672 These examples are supposed to illustrate certain features, and are 673 not supposed to be complete, valid YANG modules. 675 4. YANG Overview 677 This non-normative section is intended to give a high-level overview 678 of YANG to first-time readers. 680 4.1. Functional Overview 682 YANG is a language originally designed to model data for the NETCONF 683 protocol. A YANG module defines hierarchies of data that can be used 684 for NETCONF-based operations, including configuration, state data, 685 Remote Procedure Calls (RPCs), and notifications. This allows a 686 complete description of all data sent between a NETCONF client and 687 server. Although out of scope for this specification, YANG can also 688 be used with other protocols than NETCONF. 690 YANG models the hierarchical organization of data as a tree in which 691 each node has a name, and either a value or a set of child nodes. 692 YANG provides clear and concise descriptions of the nodes, as well as 693 the interaction between those nodes. 695 YANG structures data models into modules and submodules. A module 696 can import definitions from other external modules, and include 697 definitions from submodules. The hierarchy can be augmented, 698 allowing one module to add data nodes to the hierarchy defined in 699 another module. This augmentation can be conditional, with new nodes 700 appearing only if certain conditions are met. 702 YANG data models can describe constraints to be enforced on the data, 703 restricting the presence or value of nodes based on the presence or 704 value of other nodes in the hierarchy. These constraints are 705 enforceable by either the client or the server. 707 YANG defines a set of built-in types, and has a type mechanism 708 through which additional types may be defined. Derived types can 709 restrict their base type's set of valid values using mechanisms like 710 range or pattern restrictions that can be enforced by clients or 711 servers. They can also define usage conventions for use of the 712 derived type, such as a string-based type that contains a host name. 714 YANG permits the definition of reusable groupings of nodes. The 715 usage of these groupings can refine or augment the nodes, allowing it 716 to tailor the nodes to its particular needs. Derived types and 717 groupings can be defined in one module and used in either the same 718 module or in another module that imports it. 720 YANG data hierarchy constructs include defining lists where list 721 entries are identified by keys that distinguish them from each other. 722 Such lists may be defined as either sorted by user or automatically 723 sorted by the system. For user-sorted lists, operations are defined 724 for manipulating the order of the list entries. 726 YANG modules can be translated into an equivalent XML syntax called 727 YANG Independent Notation (YIN) (Section 13), allowing applications 728 using XML parsers and Extensible Stylesheet Language Transformations 729 (XSLT) scripts to operate on the models. The conversion from YANG to 730 YIN is semantically lossless, so content in YIN can be round-tripped 731 back into YANG. 733 YANG is an extensible language, allowing extension statements to be 734 defined by standards bodies, vendors, and individuals. The statement 735 syntax allows these extensions to coexist with standard YANG 736 statements in a natural way, while extensions in a YANG module stand 737 out sufficiently for the reader to notice them. 739 YANG resists the tendency to solve all possible problems, limiting 740 the problem space to allow expression of data models for network 741 management protocols such as NETCONF, not arbitrary XML documents or 742 arbitrary data models. 744 To the extent possible, YANG maintains compatibility with Simple 745 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 746 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 747 can be automatically translated into YANG modules for read-only 748 access [RFC6643]. However, YANG is not concerned with reverse 749 translation from YANG to SMIv2. 751 4.2. Language Overview 753 This section introduces some important constructs used in YANG that 754 will aid in the understanding of the language specifics in later 755 sections. 757 4.2.1. Modules and Submodules 759 YANG data models are defined in modules. A module contains a 760 collection of related definitions. 762 A module contains three types of statements: module-header 763 statements, revision statements, and definition statements. The 764 module header statements describe the module and give information 765 about the module itself, the revision statements give information 766 about the history of the module, and the definition statements are 767 the body of the module where the data model is defined. 769 A server may implement a number of modules, allowing multiple views 770 of the same data, or multiple views of disjoint subsections of the 771 server's data. Alternatively, the server may implement only one 772 module that defines all available data. 774 A module may have portions of its definitions separated into 775 submodules, based on the needs of the module designer. The external 776 view remains that of a single module, regardless of the presence or 777 size of its submodules. 779 The "import" statement allows a module or submodule to reference 780 definitions defined in other modules. 782 The "include" statement is used in a module to identify each 783 submodule that belongs to it. 785 4.2.2. Data Modeling Basics 787 YANG defines four main types of data nodes for data modeling. In 788 each of the following subsections, the examples show the YANG syntax 789 as well as a corresponding XML encoding. The syntax of YANG 790 statements is defined in Section 6.3. 792 4.2.2.1. Leaf Nodes 794 A leaf instance contains simple data like an integer or a string. It 795 has exactly one value of a particular type and no child nodes. 797 YANG Example: 799 leaf host-name { 800 type string; 801 description 802 "Hostname for this system"; 803 } 805 XML Encoding Example: 807 my.example.com 809 The "leaf" statement is covered in Section 7.6. 811 4.2.2.2. Leaf-List Nodes 813 A leaf-list defines a sequence of values of a particular type. 815 YANG Example: 817 leaf-list domain-search { 818 type string; 819 description 820 "List of domain names to search"; 821 } 823 XML Encoding Example: 825 high.example.com 826 low.example.com 827 everywhere.example.com 829 The "leaf-list" statement is covered in Section 7.7. 831 4.2.2.3. Container Nodes 833 A container is used to group related nodes in a subtree. A container 834 has only child nodes and no value. A container may contain any 835 number of child nodes of any type (leafs, lists, containers, leaf- 836 lists, actions, and notifications). 838 YANG Example: 840 container system { 841 container login { 842 leaf message { 843 type string; 844 description 845 "Message given at start of login session"; 846 } 847 } 848 } 850 XML Encoding Example: 852 853 854 Good morning 855 856 858 The "container" statement is covered in Section 7.5. 860 4.2.2.4. List Nodes 862 A list defines a sequence of list entries. Each entry is like a 863 container, and is uniquely identified by the values of its key leafs, 864 if it has any key leafs defined. A list can define multiple key 865 leafs and may contain any number of child nodes of any type 866 (including leafs, lists, containers etc.). 868 YANG Example: 870 list user { 871 key "name"; 872 leaf name { 873 type string; 874 } 875 leaf full-name { 876 type string; 877 } 878 leaf class { 879 type string; 880 } 881 } 883 XML Encoding Example: 885 886 glocks 887 Goldie Locks 888 intruder 889 890 891 snowey 892 Snow White 893 free-loader 894 895 896 rzell 897 Rapun Zell 898 tower 899 901 The "list" statement is covered in Section 7.8. 903 4.2.2.5. Example Module 905 These statements are combined to define the module: 907 // Contents of "example-system.yang" 908 module example-system { 909 yang-version 1.1; 910 namespace "urn:example:system"; 911 prefix "sys"; 912 organization "Example Inc."; 913 contact "joe@example.com"; 914 description 915 "The module for entities implementing the Example system."; 917 revision 2007-06-09 { 918 description "Initial revision."; 919 } 921 container system { 922 leaf host-name { 923 type string; 924 description 925 "Hostname for this system"; 926 } 928 leaf-list domain-search { 929 type string; 930 description 931 "List of domain names to search"; 932 } 934 container login { 935 leaf message { 936 type string; 937 description 938 "Message given at start of login session"; 939 } 941 list user { 942 key "name"; 943 leaf name { 944 type string; 945 } 946 leaf full-name { 947 type string; 948 } 949 leaf class { 950 type string; 951 } 952 } 953 } 954 } 955 } 957 4.2.3. Configuration and State Data 959 YANG can model state data, as well as configuration data, based on 960 the "config" statement. When a node is tagged with "config false", 961 its subhierarchy is flagged as state data. If it is tagged with 962 "config true", its subhierarchy is flagged as configuration data. 963 Parent containers, lists, and key leafs are reported also, giving the 964 context for the state data. 966 In this example, two leafs are defined for each interface, a 967 configured speed and an observed speed. 969 list interface { 970 key "name"; 971 config true; 973 leaf name { 974 type string; 975 } 976 leaf speed { 977 type enumeration { 978 enum 10m; 979 enum 100m; 980 enum auto; 981 } 982 } 983 leaf observed-speed { 984 type uint32; 985 config false; 986 } 987 } 989 The "config" statement is covered in Section 7.21.1. 991 4.2.4. Built-In Types 993 YANG has a set of built-in types, similar to those of many 994 programming languages, but with some differences due to special 995 requirements of network management. The following table summarizes 996 the built-in types discussed in Section 9: 998 +---------------------+-------------------------------------+ 999 | Name | Description | 1000 +---------------------+-------------------------------------+ 1001 | binary | Any binary data | 1002 | bits | A set of bits or flags | 1003 | boolean | "true" or "false" | 1004 | decimal64 | 64-bit signed decimal number | 1005 | empty | A leaf that does not have any value | 1006 | enumeration | One of an enumerated set of strings | 1007 | identityref | A reference to an abstract identity | 1008 | instance-identifier | A reference to a data tree node | 1009 | int8 | 8-bit signed integer | 1010 | int16 | 16-bit signed integer | 1011 | int32 | 32-bit signed integer | 1012 | int64 | 64-bit signed integer | 1013 | leafref | A reference to a leaf instance | 1014 | string | A character string | 1015 | uint8 | 8-bit unsigned integer | 1016 | uint16 | 16-bit unsigned integer | 1017 | uint32 | 32-bit unsigned integer | 1018 | uint64 | 64-bit unsigned integer | 1019 | union | Choice of member types | 1020 +---------------------+-------------------------------------+ 1022 The "type" statement is covered in Section 7.4. 1024 4.2.5. Derived Types (typedef) 1026 YANG can define derived types from base types using the "typedef" 1027 statement. A base type can be either a built-in type or a derived 1028 type, allowing a hierarchy of derived types. 1030 A derived type can be used as the argument for the "type" statement. 1032 YANG Example: 1034 typedef percent { 1035 type uint8 { 1036 range "0 .. 100"; 1037 } 1038 } 1040 leaf completed { 1041 type percent; 1042 } 1044 XML Encoding Example: 1046 20 1048 The "typedef" statement is covered in Section 7.3. 1050 4.2.6. Reusable Node Groups (grouping) 1052 Groups of nodes can be assembled into reusable collections using the 1053 "grouping" statement. A grouping defines a set of nodes that are 1054 instantiated with the "uses" statement. 1056 YANG Example: 1058 grouping target { 1059 leaf address { 1060 type inet:ip-address; 1061 description "Target IP address"; 1062 } 1063 leaf port { 1064 type inet:port-number; 1065 description "Target port number"; 1066 } 1067 } 1069 container peer { 1070 container destination { 1071 uses target; 1072 } 1073 } 1075 XML Encoding Example: 1077 1078 1079
2001:db8::2
1080 830 1081 1082 1084 The grouping can be refined as it is used, allowing certain 1085 statements to be overridden. In this example, the description is 1086 refined: 1088 container connection { 1089 container source { 1090 uses target { 1091 refine "address" { 1092 description "Source IP address"; 1093 } 1094 refine "port" { 1095 description "Source port number"; 1096 } 1097 } 1098 } 1099 container destination { 1100 uses target { 1101 refine "address" { 1102 description "Destination IP address"; 1103 } 1104 refine "port" { 1105 description "Destination port number"; 1106 } 1107 } 1108 } 1109 } 1111 The "grouping" statement is covered in Section 7.12. 1113 4.2.7. Choices 1115 YANG allows the data model to segregate incompatible nodes into 1116 distinct choices using the "choice" and "case" statements. The 1117 "choice" statement contains a set of "case" statements that define 1118 sets of schema nodes that cannot appear together. Each "case" may 1119 contain multiple nodes, but each node may appear in only one "case" 1120 under a "choice". 1122 The choice and case nodes appear only in the schema tree but not in 1123 the data tree. The additional levels of hierarchy are not needed 1124 beyond the conceptual schema. The presence of a case is indicated by 1125 the presence of one or more of the nodes within it. 1127 Since only one of the choice's cases can be valid at any time, when a 1128 node from one case is created in the data tree, all nodes from all 1129 other cases are implicitly deleted. The server handles the 1130 enforcement of the constraint, preventing incompatibilities from 1131 existing in the configuration. 1133 YANG Example: 1135 container food { 1136 choice snack { 1137 case sports-arena { 1138 leaf pretzel { 1139 type empty; 1140 } 1141 leaf beer { 1142 type empty; 1143 } 1144 } 1145 case late-night { 1146 leaf chocolate { 1147 type enumeration { 1148 enum dark; 1149 enum milk; 1150 enum first-available; 1151 } 1152 } 1153 } 1154 } 1155 } 1157 XML Encoding Example: 1159 1160 1161 1162 1164 The "choice" statement is covered in Section 7.9. 1166 4.2.8. Extending Data Models (augment) 1168 YANG allows a module to insert additional nodes into data models, 1169 including both the current module (and its submodules) or an external 1170 module. This is useful for example for vendors to add vendor- 1171 specific parameters to standard data models in an interoperable way. 1173 The "augment" statement defines the location in the data model 1174 hierarchy where new nodes are inserted, and the "when" statement 1175 defines the conditions when the new nodes are valid. 1177 When a server implements a module containing an "augment" statement, 1178 that implies that the server's implementation of the augmented module 1179 contains the additional nodes. 1181 YANG Example: 1183 augment /system/login/user { 1184 when "class != 'wheel'"; 1185 leaf uid { 1186 type uint16 { 1187 range "1000 .. 30000"; 1188 } 1189 } 1190 } 1192 This example defines a "uid" node that only is valid when the user's 1193 "class" is not "wheel". 1195 If a module augments another module, the XML elements that are added 1196 to the encoding are in the namespace of the augmenting module. For 1197 example, if the above augmentation were in a module with prefix 1198 "other", the XML would look like: 1200 XML Encoding Example: 1202 1203 alicew 1204 Alice N. Wonderland 1205 drop-out 1206 1024 1207 1209 The "augment" statement is covered in Section 7.17. 1211 4.2.9. Operation Definitions 1213 YANG allows the definition of operations. The operations' name, 1214 input parameters, and output parameters are modeled using YANG data 1215 definition statements. Operations on the top-level in a module are 1216 defined with the "rpc" statement. Operations can also be tied to a 1217 container or list data node. Such operations are defined with the 1218 "action" statement. 1220 YANG Example for an operation at the top-level: 1222 rpc activate-software-image { 1223 input { 1224 leaf image-name { 1225 type string; 1226 } 1227 } 1228 output { 1229 leaf status { 1230 type string; 1231 } 1232 } 1233 } 1235 NETCONF XML Example: 1237 1239 1240 example-fw-2.3 1241 1242 1244 1246 1247 The image example-fw-2.3 is being installed. 1248 1249 1251 YANG Example for an operation tied to a list data node: 1253 list interface { 1254 key "name"; 1256 leaf name { 1257 type string; 1258 } 1260 action ping { 1261 input { 1262 leaf destination { 1263 type inet:ip-address; 1264 } 1265 } 1266 output { 1267 leaf packet-loss { 1268 type uint8; 1269 } 1270 } 1271 } 1272 } 1274 NETCONF XML Example: 1276 1278 1279 1280 eth1 1281 1282 192.0.2.1 1283 1284 1285 1286 1288 1291 60 1292 1294 The "rpc" statement is covered in Section 7.14, and the "action" 1295 statement in Section 7.15. 1297 4.2.10. Notification Definitions 1299 YANG allows the definition of notifications. YANG data definition 1300 statements are used to model the content of the notification. 1302 YANG Example: 1304 notification link-failure { 1305 description 1306 "A link failure has been detected"; 1307 leaf if-name { 1308 type leafref { 1309 path "/interface/name"; 1310 } 1311 } 1312 leaf if-admin-status { 1313 type admin-status; 1314 } 1315 leaf if-oper-status { 1316 type oper-status; 1317 } 1318 } 1320 NETCONF XML Example: 1322 1324 2007-09-01T10:00:00Z 1325 1326 so-1/2/3.0 1327 up 1328 down 1329 1330 1332 The "notification" statement is covered in Section 7.16. 1334 5. Language Concepts 1336 5.1. Modules and Submodules 1338 The module is the base unit of definition in YANG. A module defines 1339 a single data model. A module can also augment an existing data 1340 model with additional nodes. 1342 Submodules are partial modules that contribute definitions to a 1343 module. A module may include any number of submodules, but each 1344 submodule may belong to only one module. 1346 Developers of YANG modules and submodules are RECOMMENDED to choose 1347 names for their modules that will have a low probability of colliding 1348 with standard or other enterprise modules, e.g., by using the 1349 enterprise or organization name as a prefix for the module name. 1350 Within a server, all module names MUST be unique. 1352 A module uses the "include" statement to list all its submodules. A 1353 module, or submodule belonging to that module, can reference 1354 definitions in the module and all submodules included by the module. 1356 A module or submodule uses the "import" statement to reference 1357 external modules. Statements in the module or submodule can 1358 reference definitions in the external module using the prefix 1359 specified in the "import" statement. 1361 For backward compatibility with YANG version 1, a submodule MAY use 1362 the "include" statement to reference other submodules within its 1363 module, but this is not necessary in YANG version 1.1. A submodule 1364 can reference any definition in the module it belongs to and in all 1365 submodules included by the module. A submodule MUST NOT include 1366 different revisions of other submodules than the revisions that its 1367 module includes. 1369 A module or submodule MUST NOT include submodules from other modules, 1370 and a submodule MUST NOT import its own module. 1372 The import and include statements are used to make definitions 1373 available from other modules: 1375 o For a module or submodule to reference definitions in an external 1376 module, the external module MUST be imported. 1378 o A module MUST include all its submodules. 1380 o A module, or submodule belonging to that module, MAY reference 1381 definitions in the module and all submodules included by the 1382 module. 1384 There MUST NOT be any circular chains of imports. For example, if 1385 module "a" imports module "b", "b" cannot import "a". 1387 When a definition in an external module is referenced, a locally 1388 defined prefix MUST be used, followed by a colon (":"), and then the 1389 external identifier. References to definitions in the local module 1390 MAY use the prefix notation. Since built-in data types do not belong 1391 to any module and have no prefix, references to built-in data types 1392 (e.g., int32) cannot use the prefix notation. The syntax for a 1393 reference to a definition is formally defined by the rule 1394 "identifier-ref" in Section 14. 1396 5.1.1. Import and Include by Revision 1398 Published modules evolve independently over time. In order to allow 1399 for this evolution, modules can be imported using specific revisions. 1400 Initially, a module imports the revisions of other modules that are 1401 current when the module is written. As future revisions of the 1402 imported modules are published, the importing module is unaffected 1403 and its contents are unchanged. When the author of the module is 1404 prepared to move to the most recently published revision of an 1405 imported module, the module is republished with an updated "import" 1406 statement. By republishing with the new revision, the authors 1407 explicitly indicate their acceptance of any changes in the imported 1408 module. 1410 For submodules, the issue is related but simpler. A module or 1411 submodule that includes submodules may specify the revision of the 1412 included submodules. If a submodule changes, any module or submodule 1413 that includes it by revision needs to be updated to reference the new 1414 revision. 1416 For example, module "b" imports module "a". 1418 module a { 1419 yang-version 1.1; 1420 namespace "urn:example:a"; 1421 prefix "a"; 1423 revision 2008-01-01 { ... } 1424 grouping a { 1425 leaf eh { .... } 1426 } 1427 } 1429 module b { 1430 yang-version 1.1; 1431 namespace "urn:example:b"; 1432 prefix "b"; 1434 import a { 1435 prefix "p"; 1436 revision-date 2008-01-01; 1437 } 1439 container bee { 1440 uses p:a; 1441 } 1442 } 1444 When the author of "a" publishes a new revision, the changes may not 1445 be acceptable to the author of "b". If the new revision is 1446 acceptable, the author of "b" can republish with an updated revision 1447 in the "import" statement. 1449 If a module is not imported with a specific revision, it is undefined 1450 which revision is used. 1452 5.1.2. Module Hierarchies 1454 YANG allows modeling of data in multiple hierarchies, where data may 1455 have more than one top-level node. Each top-level data node in a 1456 module defines a separate hierarchy. Models that have multiple top- 1457 level nodes are sometimes convenient, and are supported by YANG. 1459 5.1.2.1. NETCONF XML Encoding 1461 NETCONF is capable of carrying any XML content as the payload in the 1462 and elements. The top-level nodes of YANG modules 1463 are encoded as child elements, in any order, within these elements. 1464 This encapsulation guarantees that the corresponding NETCONF messages 1465 are always well-formed XML documents. 1467 For example, an instance of: 1469 module example-config { 1470 yang-version 1.1; 1471 namespace "urn:example:config"; 1472 prefix "co"; 1474 container system { ... } 1475 container routing { ... } 1476 } 1478 could be encoded in NETCONF as: 1480 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1498 5.2. File Layout 1500 YANG modules and submodules are typically stored in files, one module 1501 or submodule statement per file. The name of the file SHOULD be of 1502 the form: 1504 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1506 "module-or-submodule-name" is the name of the module or submodule, 1507 and the optional "revision-date" is the latest revision of the module 1508 or submodule, as defined by the "revision" statement (Section 7.1.9). 1510 The file extension ".yang" denotes that the contents of the file is 1511 written with YANG syntax (Section 6), and ".yin" denotes that it is 1512 written with YIN syntax (Section 13). 1514 YANG parsers can find imported modules and included submodules via 1515 this convention. 1517 5.3. XML Namespaces 1519 All YANG definitions are specified within a module. Each module is 1520 bound to a distinct XML namespace [XML-NAMES], which is a globally 1521 unique URI [RFC3986]. A NETCONF client or server uses the namespace 1522 during XML encoding of data. 1524 XML namespaces for modules published in RFC streams [RFC4844] MUST be 1525 assigned by IANA, see section 14 in [RFC6020]. 1527 XML namespaces for private modules are assigned by the organization 1528 owning the module without a central registry. Namespace URIs MUST be 1529 chosen so they cannot collide with standard or other enterprise 1530 namespaces, for example by using the enterprise or organization name 1531 in the namespace. 1533 The "namespace" statement is covered in Section 7.1.3. 1535 5.3.1. YANG XML Namespace 1537 YANG defines an XML namespace for NETCONF operations, 1538 content, and the element. The name of this 1539 namespace is "urn:ietf:params:xml:ns:yang:1". 1541 5.4. Resolving Grouping, Type, and Identity Names 1543 Grouping, type, and identity names are resolved in the context in 1544 which they are defined, rather than the context in which they are 1545 used. Users of groupings, typedefs, and identities are not required 1546 to import modules or include submodules to satisfy all references 1547 made by the original definition. This behaves like static scoping in 1548 a conventional programming language. 1550 For example, if a module defines a grouping in which a type is 1551 referenced, when the grouping is used in a second module, the type is 1552 resolved in the context of the original module, not the second 1553 module. There is no ambiguity if both modules define the type. 1555 5.5. Nested Typedefs and Groupings 1557 Typedefs and groupings may appear nested under many YANG statements, 1558 allowing these to be lexically scoped by the statement hierarchy 1559 under which they appear. This allows types and groupings to be 1560 defined near where they are used, rather than placing them at the top 1561 level of the hierarchy. The close proximity increases readability. 1563 Scoping also allows types to be defined without concern for naming 1564 conflicts between types in different submodules. Type names can be 1565 specified without adding leading strings designed to prevent name 1566 collisions within large modules. 1568 Finally, scoping allows the module author to keep types and groupings 1569 private to their module or submodule, preventing their reuse. Since 1570 only top-level types and groupings (i.e., those appearing as 1571 substatements to a module or submodule statement) can be used outside 1572 the module or submodule, the developer has more control over what 1573 pieces of their module are presented to the outside world, supporting 1574 the need to hide internal information and maintaining a boundary 1575 between what is shared with the outside world and what is kept 1576 private. 1578 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1579 type or grouping cannot be defined if a higher level in the statement 1580 hierarchy has a definition with a matching identifier. 1582 A reference to an unprefixed type or grouping, or one which uses the 1583 prefix of the current module, is resolved by locating the matching 1584 "typedef" or "grouping" statement among the immediate substatements 1585 of each ancestor statement. 1587 5.6. Conformance 1589 Conformance to a model is a measure of how accurately a server 1590 follows the model. Generally speaking, servers are responsible for 1591 implementing the model faithfully, allowing applications to treat 1592 servers which implement the model identically. Deviations from the 1593 model can reduce the utility of the model and increase fragility of 1594 applications that use it. 1596 YANG modelers have three mechanisms for conformance: 1598 o the basic behavior of the model 1600 o optional features that are part of the model 1602 o deviations from the model 1604 We will consider each of these in sequence. 1606 5.6.1. Basic Behavior 1608 The model defines a contract between a YANG-based client and server, 1609 which allows both parties to have faith the other knows the syntax 1610 and semantics behind the modeled data. The strength of YANG lies in 1611 the strength of this contract. 1613 5.6.2. Optional Features 1615 In many models, the modeler will allow sections of the model to be 1616 conditional. The server controls whether these conditional portions 1617 of the model are supported or valid for that particular server. 1619 For example, a syslog data model may choose to include the ability to 1620 save logs locally, but the modeler will realize that this is only 1621 possible if the server has local storage. If there is no local 1622 storage, an application should not tell the server to save logs. 1624 YANG supports this conditional mechanism using a construct called 1625 "feature". Features give the modeler a mechanism for making portions 1626 of the module conditional in a manner that is controlled by the 1627 server. The model can express constructs that are not universally 1628 present in all servers. These features are included in the model 1629 definition, allowing a consistent view and allowing applications to 1630 learn which features are supported and tailor their behavior to the 1631 server. 1633 A module may declare any number of features, identified by simple 1634 strings, and may make portions of the module optional based on those 1635 features. If the server supports a feature, then the corresponding 1636 portions of the module are valid for that server. If the server 1637 doesn't support the feature, those parts of the module are not valid, 1638 and applications should behave accordingly. 1640 Features are defined using the "feature" statement. Definitions in 1641 the module that are conditional to the feature are noted by the 1642 "if-feature" statement. 1644 Further details are available in Section 7.20.1. 1646 5.6.3. Deviations 1648 In an ideal world, all servers would be required to implement the 1649 model exactly as defined, and deviations from the model would not be 1650 allowed. But in the real world, servers are often not able or 1651 designed to implement the model as written. For YANG-based 1652 automation to deal with these server deviations, a mechanism must 1653 exist for servers to inform applications of the specifics of such 1654 deviations. 1656 For example, a BGP module may allow any number of BGP peers, but a 1657 particular server may only support 16 BGP peers. Any application 1658 configuring the 17th peer will receive an error. While an error may 1659 suffice to let the application know it cannot add another peer, it 1660 would be far better if the application had prior knowledge of this 1661 limitation and could prevent the user from starting down the path 1662 that could not succeed. 1664 Server deviations are declared using the "deviation" statement, which 1665 takes as its argument a string that identifies a node in the schema 1666 tree. The contents of the statement details the manner in which the 1667 server implementation deviates from the contract as defined in the 1668 module. 1670 Further details are available in Section 7.20.3. 1672 5.6.4. Announcing Conformance Information in NETCONF 1674 This document defines the following mechanism for announcing 1675 conformance information. Other mechanisms may be defined by future 1676 specifications. 1678 A NETCONF server MUST announce the modules it implements (see 1679 Section 5.6.5) by implementing the YANG module "ietf-yang-library" 1680 defined in [I-D.ietf-netconf-yang-library], and listing all 1681 implemented modules in the "/modules-state/module" list. 1683 The server also MUST advertise the following capability in the 1684 message (line-breaks and whitespaces are used for formatting 1685 reasons only): 1687 urn:ietf:params:netconf:capability:yang-library:1.0? 1688 revision=&module-set-id= 1690 The parameter "revision" has the same value as the revision date of 1691 the "ietf-yang-library" module implemented by the server. This 1692 parameter MUST be present. 1694 The parameter "module-set-id" has the same value as the leaf 1695 "/modules-state/module-set-id" from "ietf-yang-library". This 1696 parameter MUST be present. 1698 With this mechanism, a client can cache the supported modules for a 1699 server, and only update the cache if the "module-set-id" value in the 1700 message changes. 1702 5.6.5. Implementing a Module 1704 A server implements a module if it implements the module's data 1705 nodes, rpcs, actions, notifications, and deviations. 1707 A server MUST NOT implement more than one revision of a module. 1709 If a server implements a module A that imports a module B, and A uses 1710 any node from B in an "augment" or "path" statement that the server 1711 supports, then the server MUST implement a revision of module B that 1712 has these nodes defined. This is regardless of if module B is 1713 imported by revision or not. 1715 If a server implements a module A that imports a module C without 1716 specifying the revision date of module C, and the server does not 1717 implement C (e.g., if C only defines some typedefs), the server MUST 1718 list module C in the "/modules-state/module" list from 1719 "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set 1720 the leaf "conformance-type" to "import" for this module. 1722 If a server lists a module C in the "/modules-state/module" list from 1723 "ietf-yang-library", and there are other modules Ms listed that 1724 import C without specifying the revision date of module C, the server 1725 MUST use the definitions from the most recent revision of C listed 1726 for modules Ms. 1728 The reason for these rules is that clients need to be able to know 1729 the specific data model structure and types of all leafs and leaf- 1730 lists implemented in a server. 1732 For example, with these modules: 1734 module a { 1735 yang-version 1.1; 1736 namespace "urn:example:a"; 1737 prefix "a"; 1739 import b { 1740 revision-date 2015-01-01; 1741 } 1742 import c; 1744 revision 2015-01-01; 1746 feature foo; 1748 augment "/b:x" { 1749 if-feature foo; 1750 leaf y { 1751 type b:myenum; 1752 } 1753 } 1755 container a { 1756 leaf x { 1757 type c:bar; 1758 } 1759 } 1760 } 1762 module b { 1763 yang-version 1.1; 1764 namespace "urn:example:b"; 1765 prefix "b"; 1767 revision 2015-01-01; 1769 typedef myenum { 1770 type enumeration { 1771 enum zero; 1772 } 1773 } 1775 container x { 1776 } 1777 } 1779 module b { 1780 yang-version 1.1; 1781 namespace "urn:example:b"; 1782 prefix "b"; 1784 revision 2015-04-04; 1785 revision 2015-01-01; 1787 typedef myenum { 1788 type enumeration { 1789 enum zero; // added in 2015-01-01 1790 enum one; // added in 2015-04-04 1791 } 1792 } 1794 container x { // added in 2015-01-01 1795 container y; // added in 2015-04-04 1796 } 1797 } 1798 module c { 1799 yang-version 1.1; 1800 namespace "urn:example:c"; 1801 prefix "c"; 1803 revision 2015-02-02; 1805 typedef bar { 1806 ... 1807 } 1808 } 1810 module c { 1811 yang-version 1.1; 1812 namespace "urn:example:c"; 1813 prefix "c"; 1815 revision 2015-03-03; 1816 revision 2015-02-02; 1818 typedef bar { 1819 ... 1820 } 1821 } 1823 A server that implements revision "2015-01-01" of module "a" and 1824 supports feature "foo" can implement revision "2015-01-01" or 1825 "2015-04-04" of module "b". Since "b" was imported by revision, the 1826 type of leaf "/b:x/a:y" is the same regardless of which revision of 1827 "b" the server implements. 1829 A server that implements module "a", but does not support feature 1830 "foo" does not have to implement module "b". 1832 A server that implements revision "2015-01-01" of module "a" picks 1833 any revision of module "c", and list it in the "/modules-state/ 1834 module" list from "ietf-yang-library". 1836 The following XML encoding example shows valid data for the 1837 "/modules-state/module" list for a server that implements module "a": 1839 1841 ee1ecb017370cafd 1842 1843 a 1844 2015-01-01 1845 urn:example:a 1846 foo 1847 implement 1848 1849 1850 b 1851 2015-04-04 1852 urn:example:b 1853 implement 1854 1855 1856 c 1857 2015-02-02 1858 urn:example:c 1859 import 1860 1861 1863 5.7. Datastore Modification 1865 Data models may allow the server to alter the configuration datastore 1866 in ways not explicitly directed via network management protocol 1867 messages. For example, a data model may define leafs that are 1868 assigned system-generated values when the client does not provide 1869 one. A formal mechanism for specifying the circumstances where these 1870 changes are allowed is out of scope for this specification. 1872 6. YANG Syntax 1874 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1875 languages like C and C++. This C-like syntax was chosen specifically 1876 for its readability, since YANG values the time and effort of the 1877 readers of models above those of modules writers and YANG tool-chain 1878 developers. This section introduces the YANG syntax. 1880 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1881 [ISO.10646] characters, including tab, carriage return, and line feed 1882 but excluding the other C0 control characters, the surrogate blocks, 1883 and the noncharacters. The character syntax is formally defined by 1884 the rule "yang-char" in Section 14. 1886 YANG modules and submodules are stored in files using the UTF-8 1887 [RFC3629] character encoding. 1889 Lines in a YANG module end with a carriage return-line feed 1890 combination or with a line feed alone. A carriage return that is not 1891 followed by a line feed may only appear inside a quoted string 1892 (Section 6.1.3). Note that carriage returns and line feeds that 1893 appear inside quoted strings become part of the value of the string 1894 without modification; the value of a multi-line quoted string 1895 contains the same form of line ends as those lines of the YANG 1896 module. 1898 6.1. Lexical Tokenization 1900 YANG modules are parsed as a series of tokens. This section details 1901 the rules for recognizing tokens from an input stream. YANG 1902 tokenization rules are both simple and powerful. The simplicity is 1903 driven by a need to keep the parsers easy to implement, while the 1904 power is driven by the fact that modelers need to express their 1905 models in readable formats. 1907 6.1.1. Comments 1909 Comments are C++ style. A single line comment starts with "//" and 1910 ends at the end of the line. A block comment starts with "/*" and 1911 ends with the nearest following "*/". 1913 Note that inside a quoted string (Section 6.1.3), these character 1914 pairs are never interpreted as the start or end of a comment. 1916 6.1.2. Tokens 1918 A token in YANG is either a keyword, a string, a semicolon (";"), or 1919 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1920 is either one of the YANG keywords defined in this document, or a 1921 prefix identifier, followed by a colon (":"), followed by a language 1922 extension keyword. Keywords are case sensitive. See Section 6.2 for 1923 a formal definition of identifiers. 1925 6.1.3. Quoting 1927 An unquoted string is any sequence of characters that does not 1928 contain any space, tab, carriage return, or line feed characters, a 1929 single or double quote character, a semicolon (";"), braces ("{" or 1930 "}"), or comment sequences ("//", "/*", or "*/"). 1932 Note that any keyword can legally appear as an unquoted string. 1934 Within an unquoted string, every character is preserved. Note that 1935 this means that the backslash character does not have any special 1936 meaning in an unquoted string. 1938 If a double-quoted string contains a line break followed by space or 1939 tab characters that are used to indent the text according to the 1940 layout in the YANG file, this leading whitespace is stripped from the 1941 string, up to and including the column of the starting double quote 1942 character, or to the first non-whitespace character, whichever occurs 1943 first. Any tab character in a succeeding line that must be examined 1944 for stripping is first converted into 8 space characters. 1946 If a double-quoted string contains space or tab characters before a 1947 line break, this trailing whitespace is stripped from the string. 1949 A single-quoted string (enclosed within ' ') preserves each character 1950 within the quotes. A single quote character cannot occur in a 1951 single-quoted string, even when preceded by a backslash. 1953 Within a double-quoted string (enclosed within " "), a backslash 1954 character introduces a representation of a special character, which 1955 depends on the character that immediately follows the backslash: 1957 \n new line 1958 \t a tab character 1959 \" a double quote 1960 \\ a single backslash 1962 The backslash MUST NOT be followed by any other character. 1964 If a quoted string is followed by a plus character ("+"), followed by 1965 another quoted string, the two strings are concatenated into one 1966 string, allowing multiple concatenations to build one string. 1967 Whitespace, line breaks, and comments are allowed between the quoted 1968 strings and the plus character. 1970 In double-quoted strings, whitespace trimming is done before 1971 substitution of backslash-escaped characters. Concatenation is 1972 performed as the last step. 1974 6.1.3.1. Quoting Examples 1976 The following strings are equivalent: 1978 hello 1979 "hello" 1980 'hello' 1981 "hel" + "lo" 1982 'hel' + "lo" 1984 The following examples show some special strings: 1986 "\"" - string containing a double quote 1987 '"' - string containing a double quote 1988 "\n" - string containing a new line character 1989 '\n' - string containing a backslash followed 1990 by the character n 1992 The following examples show some illegal strings: 1994 '''' - a single-quoted string cannot contain single quotes 1995 """ - a double quote must be escaped in a double-quoted string 1997 The following strings are equivalent: 1999 "first line 2000 second line" 2002 "first line\n" + " second line" 2004 6.2. Identifiers 2006 Identifiers are used to identify different kinds of YANG items by 2007 name. Each identifier starts with an uppercase or lowercase ASCII 2008 letter or an underscore character, followed by zero or more ASCII 2009 letters, digits, underscore characters, hyphens, and dots. 2010 Implementations MUST support identifiers up to 64 characters in 2011 length, and MAY support longer identifiers. Identifiers are case 2012 sensitive. The identifier syntax is formally defined by the rule 2013 "identifier" in Section 14. Identifiers can be specified as quoted 2014 or unquoted strings. 2016 6.2.1. Identifiers and Their Namespaces 2018 Each identifier is valid in a namespace that depends on the type of 2019 the YANG item being defined. All identifiers defined in a namespace 2020 MUST be unique. 2022 o All module and submodule names share the same global module 2023 identifier namespace. 2025 o All extension names defined in a module and its submodules share 2026 the same extension identifier namespace. 2028 o All feature names defined in a module and its submodules share the 2029 same feature identifier namespace. 2031 o All identity names defined in a module and its submodules share 2032 the same identity identifier namespace. 2034 o All derived type names defined within a parent node or at the top 2035 level of the module or its submodules share the same type 2036 identifier namespace. This namespace is scoped to all descendant 2037 nodes of the parent node or module. This means that any 2038 descendent node may use that typedef, and it MUST NOT define a 2039 typedef with the same name. 2041 o All grouping names defined within a parent node or at the top 2042 level of the module or its submodules share the same grouping 2043 identifier namespace. This namespace is scoped to all descendant 2044 nodes of the parent node or module. This means that any 2045 descendent node may use that grouping, and it MUST NOT define a 2046 grouping with the same name. 2048 o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 2049 notifications, anydatas, and anyxmls defined (directly or through 2050 a uses statement) within a parent node or at the top level of the 2051 module or its submodules share the same identifier namespace. 2052 This namespace is scoped to the parent node or module, unless the 2053 parent node is a case node. In that case, the namespace is scoped 2054 to the closest ancestor node that is not a case or choice node. 2056 o All cases within a choice share the same case identifier 2057 namespace. This namespace is scoped to the parent choice node. 2059 Forward references are allowed in YANG. 2061 6.3. Statements 2063 A YANG module contains a sequence of statements. Each statement 2064 starts with a keyword, followed by zero or one argument, followed 2065 either by a semicolon (";") or a block of substatements enclosed 2066 within braces ("{ }"): 2068 statement = keyword [argument] (";" / "{" *statement "}") 2070 The argument is a string, as defined in Section 6.1.2. 2072 6.3.1. Language Extensions 2074 A module can introduce YANG extensions by using the "extension" 2075 keyword (see Section 7.19). The extensions can be imported by other 2076 modules with the "import" statement (see Section 7.1.5). When an 2077 imported extension is used, the extension's keyword MUST be qualified 2078 using the prefix with which the extension's module was imported. If 2079 an extension is used in the module where it is defined, the 2080 extension's keyword MUST be qualified with the prefix of this module. 2082 The processing of extensions depends on whether support for those 2083 extensions is claimed for a given YANG parser or the tool set in 2084 which it is embedded. An unsupported extension, appearing in a YANG 2085 module as an unknown-statement (see Section 14) MAY be ignored in its 2086 entirety. Any supported extension MUST be processed in accordance 2087 with the specification governing that extension. 2089 Care must be taken when defining extensions so that modules that use 2090 the extensions are meaningful also for applications that do not 2091 support the extensions. 2093 6.4. XPath Evaluations 2095 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 2096 for specifying many inter-node references and dependencies. An 2097 implementation is not required to implement an XPath interpreter, but 2098 MUST ensure that the requirements encoded in the data model are 2099 enforced. The manner of enforcement is an implementation decision. 2100 The XPath expressions MUST be syntactically correct, and all prefixes 2101 used MUST be present in the XPath context (see Section 6.4.1). An 2102 implementation may choose to implement them by hand, rather than 2103 using the XPath expression directly. 2105 The data model used in the XPath expressions is the same as that used 2106 in XPath 1.0 [XPATH], with the same extension for root node children 2107 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 2108 that the root node may have any number of element nodes as its 2109 children. 2111 The data tree has no concept of document order. An implementation 2112 needs to choose some document order but how it is done is an 2113 implementation decision. This means that XPath expressions in YANG 2114 modules SHOULD NOT rely on any specific document order. 2116 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 2117 values, see Section 3.5 in [XPATH]. This means that some values of 2118 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 2119 cannot be exactly represented in XPath expressions. Therefore, due 2120 caution should be exercised when using nodes with 64-bit numeric 2121 values in XPath expressions. In particular, numerical comparisons 2122 involving equality may yield unexpected results. 2124 For example, consider the following definition: 2126 leaf lxiv { 2127 type decimal64 { 2128 fraction-digits 18; 2129 } 2130 must ". <= 10"; 2131 } 2133 An instance of the "lxiv" leaf having the value of 2134 10.0000000000000001 will then successfully pass validation. 2136 6.4.1. XPath Context 2138 All YANG XPath expressions share the following XPath context 2139 definition: 2141 o The set of namespace declarations is the set of all "import" 2142 statements' prefix and namespace pairs in the module where the 2143 XPath expression is specified, and the "prefix" statement's prefix 2144 for the "namespace" statement's URI. 2146 o Names without a namespace prefix belong to the same namespace as 2147 the identifier of the current node. Inside a grouping, that 2148 namespace is affected by where the grouping is used (see 2149 Section 7.13). Inside a typedef, that namespace is affected by 2150 where the typedef is referenced. If a typedef is defined and 2151 referenced within a grouping, the namespace is affected by where 2152 the grouping is used (see Section 7.13). 2154 o The function library is the core function library defined in 2155 [XPATH], and the functions defined in Section 10. 2157 o The set of variable bindings is empty. 2159 The mechanism for handling unprefixed names is adopted from XPath 2.0 2160 [XPATH2.0], and helps simplify XPath expressions in YANG. No 2161 ambiguity may ever arise because YANG node identifiers are always 2162 qualified names with a non-null namespace URI. 2164 The accessible tree depends on where the statement with the XPath 2165 expression is defined: 2167 o If the XPath expression is defined in substatement to a data node 2168 that represents configuration, the accessible tree is the data in 2169 the datastore where the context node exists. The root node has 2170 all top-level configuration data nodes in all modules as children. 2172 o If the XPath expression is defined in a substatement to a data 2173 node that represents state data, the accessible tree is all state 2174 data in the server, and the running configuration datastore. The 2175 root node has all top-level data nodes in all modules as children. 2177 o If the XPath expression is defined in a substatement to a 2178 "notification" statement, the accessible tree is the notification 2179 instance, all state data in the server, and the running 2180 configuration datastore. If the notification is defined on the 2181 top-level in a module, then the root node has the node 2182 representing the notification being defined and all top-level data 2183 nodes in all modules as children. Otherwise, the root node has 2184 all top-level data nodes in all modules as children. 2186 o If the XPath expression is defined in a substatement to an "input" 2187 statement in an "rpc" or "action" statement, the accessible tree 2188 is the RPC or action operation instance, all state data in the 2189 server, and the running configuration datastore. The root node 2190 has top-level data nodes in all modules as children. 2191 Additionally, for an RPC, the root node also has the node 2192 representing the RPC operation being defined as a child. The node 2193 representing the operation being defined has the operation's input 2194 parameters as children. 2196 o If the XPath expression is defined in a substatement to an 2197 "output" statement in an "rpc" or "action" statement, the 2198 accessible tree is the RPC or action operation instance, all state 2199 data in the server, and the running configuration datastore. The 2200 root node has top-level data nodes in all modules as children. 2201 Additionally, for an RPC, the root node also has the node 2202 representing the RPC operation being defined as a child. The node 2203 representing the operation being defined has the operation's 2204 output parameters as children. 2206 In the accessible tree, all leafs and leaf-lists with default values 2207 in use exist (See Section 7.6.1 and Section 7.7.2). 2209 If a node that exists in the accessible tree has a non-presence 2210 container as a child, then the non-presence container also exists in 2211 the tree. 2213 The context node varies with the YANG XPath expression, and is 2214 specified where the YANG statement with the XPath expression is 2215 defined. 2217 6.4.1.1. Examples 2219 Given the following module: 2221 module example-a { 2222 yang-version 1.1; 2223 namespace urn:example:a; 2224 prefix a; 2226 container a { 2227 list b { 2228 key id; 2229 leaf id { 2230 type string; 2231 } 2232 notification down { 2233 leaf reason { 2234 type string; 2235 } 2236 } 2237 action reset { 2238 input { 2239 leaf delay { 2240 type uint32; 2241 } 2242 } 2243 output { 2244 leaf result { 2245 type string; 2246 } 2247 } 2248 } 2249 } 2250 } 2251 notification failure { 2252 leaf b-ref { 2253 type leafref { 2254 path "/a/b/id"; 2255 } 2256 } 2257 } 2258 } 2260 And given the following data tree, specified in XML: 2262 2263 2264 1 2265 2266 2267 2 2268 2269 2271 The accessible tree for a notification "down" on /a/b[id="2"] is: 2273 2274 2275 1 2276 2277 2278 2 2279 2280 error 2281 2282 2283 2284 // possibly other top-level nodes here 2286 The accessible tree for an action invocation of "reset" on /a/ 2287 b[id="1"] with the "when" parameter set to "10" would be: 2289 2290 2291 1 2292 2293 10 2294 2295 2296 2297 2 2298 2299 2300 // possibly other top-level nodes here 2302 The accessible tree for the action output of this action is: 2304 2305 2306 1 2307 2308 ok 2309 2310 2311 2312 2 2313 2314 2315 // possibly other top-level nodes here 2317 The accessible tree for a notification "failure" could be: 2319 2320 2321 1 2322 2323 2324 2 2325 2326 2327 2328 2 2329 2330 // possibly other top-level nodes here 2332 6.5. Schema Node Identifier 2334 A schema node identifier is a string that identifies a node in the 2335 schema tree. It has two forms, "absolute" and "descendant", defined 2336 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 2337 in Section 14, respectively. A schema node identifier consists of a 2338 path of identifiers, separated by slashes ("/"). In an absolute 2339 schema node identifier, the first identifier after the leading slash 2340 is any top-level schema node in the local module or in an imported 2341 module. 2343 References to identifiers defined in external modules MUST be 2344 qualified with appropriate prefixes, and references to identifiers 2345 defined in the current module and its submodules MAY use a prefix. 2347 For example, to identify the child node "b" of top-level node "a", 2348 the string "/a/b" can be used. 2350 7. YANG Statements 2352 The following sections describe all of the YANG statements. 2354 Note that even a statement that does not have any substatements 2355 defined in YANG can have vendor-specific extensions as substatements. 2356 For example, the "description" statement does not have any 2357 substatements defined in YANG, but the following is legal: 2359 description "some text" { 2360 ex:documentation-flag 5; 2361 } 2363 7.1. The module Statement 2365 The "module" statement defines the module's name, and groups all 2366 statements that belong to the module together. The "module" 2367 statement's argument is the name of the module, followed by a block 2368 of substatements that hold detailed module information. The module 2369 name is an identifier (see Section 6.2). 2371 Names of modules published in RFC streams [RFC4844] MUST be assigned 2372 by IANA, see section 14 in [RFC6020]. 2374 Private module names are assigned by the organization owning the 2375 module without a central registry. See Section 5.1 for 2376 recommendations on how to name modules. 2378 A module typically has the following layout: 2380 module { 2382 // header information 2383 2384 2385 2387 // linkage statements 2388 2389 2391 // meta information 2392 2393 2394 2395 2397 // revision history 2398 2400 // module definitions 2401 2402 } 2404 7.1.1. The module's Substatements 2405 +--------------+---------+-------------+ 2406 | substatement | section | cardinality | 2407 +--------------+---------+-------------+ 2408 | anydata | 7.10 | 0..n | 2409 | anyxml | 7.11 | 0..n | 2410 | augment | 7.17 | 0..n | 2411 | choice | 7.9 | 0..n | 2412 | contact | 7.1.8 | 0..1 | 2413 | container | 7.5 | 0..n | 2414 | description | 7.21.3 | 0..1 | 2415 | deviation | 7.20.3 | 0..n | 2416 | extension | 7.19 | 0..n | 2417 | feature | 7.20.1 | 0..n | 2418 | grouping | 7.12 | 0..n | 2419 | identity | 7.18 | 0..n | 2420 | import | 7.1.5 | 0..n | 2421 | include | 7.1.6 | 0..n | 2422 | leaf | 7.6 | 0..n | 2423 | leaf-list | 7.7 | 0..n | 2424 | list | 7.8 | 0..n | 2425 | namespace | 7.1.3 | 1 | 2426 | notification | 7.16 | 0..n | 2427 | organization | 7.1.7 | 0..1 | 2428 | prefix | 7.1.4 | 1 | 2429 | reference | 7.21.4 | 0..1 | 2430 | revision | 7.1.9 | 0..n | 2431 | rpc | 7.14 | 0..n | 2432 | typedef | 7.3 | 0..n | 2433 | uses | 7.13 | 0..n | 2434 | yang-version | 7.1.2 | 1 | 2435 +--------------+---------+-------------+ 2437 7.1.2. The yang-version Statement 2439 The "yang-version" statement specifies which version of the YANG 2440 language was used in developing the module. The statement's argument 2441 is a string. It MUST contain the value "1.1" for YANG modules 2442 defined based on this specification. 2444 A module or submodule that doesn't contain the "yang-version" 2445 statement, or one that contains the value "1", is developed for YANG 2446 version 1, defined in [RFC6020]. 2448 Handling of the "yang-version" statement for versions other than 2449 "1.1" (the version defined here) is out of scope for this 2450 specification. Any document that defines a higher version will need 2451 to define the backward compatibility of such a higher version. 2453 For compatibility between YANG version 1 and 1.1, see Section 12. 2455 7.1.3. The namespace Statement 2457 The "namespace" statement defines the XML namespace that all 2458 identifiers defined by the module are qualified by in the XML 2459 encoding, with the exception of identifiers for data nodes, action 2460 nodes, and notification nodes defined inside a grouping (see 2461 Section 7.13 for details). The argument to the "namespace" statement 2462 is the URI of the namespace. 2464 See also Section 5.3. 2466 7.1.4. The prefix Statement 2468 The "prefix" statement is used to define the prefix associated with 2469 the module and its namespace. The "prefix" statement's argument is 2470 the prefix string that is used as a prefix to access a module. The 2471 prefix string MAY be used with the module to refer to definitions 2472 contained in the module, e.g., "if:ifName". A prefix is an 2473 identifier (see Section 6.2). 2475 When used inside the "module" statement, the "prefix" statement 2476 defines the prefix suggested to be used when this module is imported. 2478 To improve readability of the NETCONF XML, a NETCONF client or server 2479 that generates XML or XPath that use prefixes SHOULD use the prefix 2480 defined by the module as the XML namespace prefix, unless there is a 2481 conflict. 2483 When used inside the "import" statement, the "prefix" statement 2484 defines the prefix to be used when accessing definitions inside the 2485 imported module. When a reference to an identifier from the imported 2486 module is used, the prefix string for the imported module followed by 2487 a colon (":") and the identifier is used, e.g., "if:ifIndex". To 2488 improve readability of YANG modules, the prefix defined by a module 2489 SHOULD be used when the module is imported, unless there is a 2490 conflict. If there is a conflict, i.e., two different modules that 2491 both have defined the same prefix are imported, at least one of them 2492 MUST be imported with a different prefix. 2494 All prefixes, including the prefix for the module itself MUST be 2495 unique within the module or submodule. 2497 7.1.5. The import Statement 2499 The "import" statement makes definitions from one module available 2500 inside another module or submodule. The argument is the name of the 2501 module to import, and the statement is followed by a block of 2502 substatements that holds detailed import information. When a module 2503 is imported, the importing module may: 2505 o use any grouping and typedef defined at the top level in the 2506 imported module or its submodules. 2508 o use any extension, feature, and identity defined in the imported 2509 module or its submodules. 2511 o use any node in the imported module's schema tree in "must", 2512 "path", and "when" statements, or as the target node in "augment" 2513 and "deviation" statements. 2515 The mandatory "prefix" substatement assigns a prefix for the imported 2516 module that is scoped to the importing module or submodule. Multiple 2517 "import" statements may be specified to import from different 2518 modules. 2520 When the optional "revision-date" substatement is present, any 2521 typedef, grouping, extension, feature, and identity referenced by 2522 definitions in the local module are taken from the specified revision 2523 of the imported module. It is an error if the specified revision of 2524 the imported module does not exist. If no "revision-date" 2525 substatement is present, it is undefined from which revision of the 2526 module they are taken. 2528 Multiple revisions of the same module can be imported, provided that 2529 different prefixes are used. 2531 +---------------+---------+-------------+ 2532 | substatement | section | cardinality | 2533 +---------------+---------+-------------+ 2534 | prefix | 7.1.4 | 1 | 2535 | revision-date | 7.1.5.1 | 0..1 | 2536 | description | 7.21.3 | 0..1 | 2537 | reference | 7.21.4 | 0..1 | 2538 +---------------+---------+-------------+ 2540 The import's Substatements 2542 7.1.5.1. The import's revision-date Statement 2544 The import's "revision-date" statement is used to specify the version 2545 of the module to import. 2547 7.1.6. The include Statement 2549 The "include" statement is used to make content from a submodule 2550 available to that submodule's parent module. The argument is an 2551 identifier that is the name of the submodule to include. Modules are 2552 only allowed to include submodules that belong to that module, as 2553 defined by the "belongs-to" statement (see Section 7.2.2). 2555 When a module includes a submodule, it incorporates the contents of 2556 the submodule into the node hierarchy of the module. 2558 For backward compatibility with YANG version 1, a submodule is 2559 allowed to include another submodule belonging to the same module, 2560 but this is not necessary in YANG version 1.1 (see Section 5.1). 2562 When the optional "revision-date" substatement is present, the 2563 specified revision of the submodule is included in the module. It is 2564 an error if the specified revision of the submodule does not exist. 2565 If no "revision-date" substatement is present, it is undefined which 2566 revision of the submodule is included. 2568 Multiple revisions of the same submodule MUST NOT be included. 2570 +---------------+---------+-------------+ 2571 | substatement | section | cardinality | 2572 +---------------+---------+-------------+ 2573 | revision-date | 7.1.5.1 | 0..1 | 2574 | description | 7.21.3 | 0..1 | 2575 | reference | 7.21.4 | 0..1 | 2576 +---------------+---------+-------------+ 2578 The includes's Substatements 2580 7.1.7. The organization Statement 2582 The "organization" statement defines the party responsible for this 2583 module. The argument is a string that is used to specify a textual 2584 description of the organization(s) under whose auspices this module 2585 was developed. 2587 7.1.8. The contact Statement 2589 The "contact" statement provides contact information for the module. 2590 The argument is a string that is used to specify contact information 2591 for the person or persons to whom technical queries concerning this 2592 module should be sent, such as their name, postal address, telephone 2593 number, and electronic mail address. 2595 7.1.9. The revision Statement 2597 The "revision" statement specifies the editorial revision history of 2598 the module, including the initial revision. A series of revision 2599 statements detail the changes in the module's definition. The 2600 argument is a date string in the format "YYYY-MM-DD", followed by a 2601 block of substatements that holds detailed revision information. A 2602 module SHOULD have at least one "revision" statement. For every 2603 published editorial change, a new one SHOULD be added in front of the 2604 revisions sequence, so that all revisions are in reverse 2605 chronological order. 2607 7.1.9.1. The revision's Substatement 2609 +--------------+---------+-------------+ 2610 | substatement | section | cardinality | 2611 +--------------+---------+-------------+ 2612 | description | 7.21.3 | 0..1 | 2613 | reference | 7.21.4 | 0..1 | 2614 +--------------+---------+-------------+ 2616 7.1.10. Usage Example 2617 module example-system { 2618 yang-version 1.1; 2619 namespace "urn:example:system"; 2620 prefix "sys"; 2622 import ietf-yang-types { 2623 prefix "yang"; 2624 reference "RFC 6991: Common YANG Data Types"; 2625 } 2627 include example-types; 2629 organization "Example Inc."; 2630 contact 2631 "Joe L. User 2633 Example Inc. 2634 42 Anywhere Drive 2635 Nowhere, CA 95134 2636 USA 2638 Phone: +1 800 555 0100 2639 EMail: joe@example.com"; 2641 description 2642 "The module for entities implementing the Example system."; 2644 revision 2007-06-09 { 2645 description "Initial revision."; 2646 } 2648 // definitions follow... 2649 } 2651 7.2. The submodule Statement 2653 While the primary unit in YANG is a module, a YANG module can itself 2654 be constructed out of several submodules. Submodules allow a module 2655 designer to split a complex model into several pieces where all the 2656 submodules contribute to a single namespace, which is defined by the 2657 module that includes the submodules. 2659 The "submodule" statement defines the submodule's name, and groups 2660 all statements that belong to the submodule together. The 2661 "submodule" statement's argument is the name of the submodule, 2662 followed by a block of substatements that hold detailed submodule 2663 information. The submodule name is an identifier (see Section 6.2). 2665 Names of submodules published in RFC streams [RFC4844] MUST be 2666 assigned by IANA, see section 14 in [RFC6020]. 2668 Private submodule names are assigned by the organization owning the 2669 submodule without a central registry. See Section 5.1 for 2670 recommendations on how to name submodules. 2672 A submodule typically has the following layout: 2674 submodule { 2676 2678 // module identification 2679 2681 // linkage statements 2682 2684 // meta information 2685 2686 2687 2688 2690 // revision history 2691 2693 // module definitions 2694 2695 } 2697 7.2.1. The submodule's Substatements 2698 +--------------+---------+-------------+ 2699 | substatement | section | cardinality | 2700 +--------------+---------+-------------+ 2701 | anydata | 7.10 | 0..n | 2702 | anyxml | 7.11 | 0..n | 2703 | augment | 7.17 | 0..n | 2704 | belongs-to | 7.2.2 | 1 | 2705 | choice | 7.9 | 0..n | 2706 | contact | 7.1.8 | 0..1 | 2707 | container | 7.5 | 0..n | 2708 | description | 7.21.3 | 0..1 | 2709 | deviation | 7.20.3 | 0..n | 2710 | extension | 7.19 | 0..n | 2711 | feature | 7.20.1 | 0..n | 2712 | grouping | 7.12 | 0..n | 2713 | identity | 7.18 | 0..n | 2714 | import | 7.1.5 | 0..n | 2715 | include | 7.1.6 | 0..n | 2716 | leaf | 7.6 | 0..n | 2717 | leaf-list | 7.7 | 0..n | 2718 | list | 7.8 | 0..n | 2719 | notification | 7.16 | 0..n | 2720 | organization | 7.1.7 | 0..1 | 2721 | reference | 7.21.4 | 0..1 | 2722 | revision | 7.1.9 | 0..n | 2723 | rpc | 7.14 | 0..n | 2724 | typedef | 7.3 | 0..n | 2725 | uses | 7.13 | 0..n | 2726 | yang-version | 7.1.2 | 1 | 2727 +--------------+---------+-------------+ 2729 7.2.2. The belongs-to Statement 2731 The "belongs-to" statement specifies the module to which the 2732 submodule belongs. The argument is an identifier that is the name of 2733 the module. 2735 A submodule MUST only be included by the module to which it belongs, 2736 or by another submodule that belongs to that module. 2738 The mandatory "prefix" substatement assigns a prefix for the module 2739 to which the submodule belongs. All definitions in the module that 2740 the submodule belongs to and all its submodules can be accessed by 2741 using the prefix. 2743 +--------------+---------+-------------+ 2744 | substatement | section | cardinality | 2745 +--------------+---------+-------------+ 2746 | prefix | 7.1.4 | 1 | 2747 +--------------+---------+-------------+ 2749 The belongs-to's Substatements 2751 7.2.3. Usage Example 2753 submodule example-types { 2754 yang-version 1.1; 2755 belongs-to "example-system" { 2756 prefix "sys"; 2757 } 2759 import ietf-yang-types { 2760 prefix "yang"; 2761 } 2763 organization "Example Inc."; 2764 contact 2765 "Joe L. User 2767 Example Inc. 2768 42 Anywhere Drive 2769 Nowhere, CA 95134 2770 USA 2772 Phone: +1 800 555 0100 2773 EMail: joe@example.com"; 2775 description 2776 "This submodule defines common Example types."; 2778 revision "2007-06-09" { 2779 description "Initial revision."; 2780 } 2782 // definitions follows... 2783 } 2785 7.3. The typedef Statement 2787 The "typedef" statement defines a new type that may be used locally 2788 in the module or submodule, and by other modules that import from it, 2789 according to the rules in Section 5.5. The new type is called the 2790 "derived type", and the type from which it was derived is called the 2791 "base type". All derived types can be traced back to a YANG built-in 2792 type. 2794 The "typedef" statement's argument is an identifier that is the name 2795 of the type to be defined, and MUST be followed by a block of 2796 substatements that holds detailed typedef information. 2798 The name of the type MUST NOT be one of the YANG built-in types. If 2799 the typedef is defined at the top level of a YANG module or 2800 submodule, the name of the type to be defined MUST be unique within 2801 the module. 2803 7.3.1. The typedef's Substatements 2805 +--------------+---------+-------------+ 2806 | substatement | section | cardinality | 2807 +--------------+---------+-------------+ 2808 | default | 7.3.4 | 0..1 | 2809 | description | 7.21.3 | 0..1 | 2810 | reference | 7.21.4 | 0..1 | 2811 | status | 7.21.2 | 0..1 | 2812 | type | 7.3.2 | 1 | 2813 | units | 7.3.3 | 0..1 | 2814 +--------------+---------+-------------+ 2816 7.3.2. The typedef's type Statement 2818 The "type" statement, which MUST be present, defines the base type 2819 from which this type is derived. See Section 7.4 for details. 2821 7.3.3. The units Statement 2823 The "units" statement, which is optional, takes as an argument a 2824 string that contains a textual definition of the units associated 2825 with the type. 2827 7.3.4. The typedef's default Statement 2829 The "default" statement takes as an argument a string that contains a 2830 default value for the new type. 2832 The value of the "default" statement MUST be valid according to the 2833 type specified in the "type" statement. 2835 If the base type has a default value, and the new derived type does 2836 not specify a new default value, the base type's default value is 2837 also the default value of the new derived type. 2839 If the type's default value is not valid according to the new 2840 restrictions specified in a derived type or leaf definition, the 2841 derived type or leaf definition MUST specify a new default value 2842 compatible with the restrictions. 2844 7.3.5. Usage Example 2846 typedef listen-ipv4-address { 2847 type inet:ipv4-address; 2848 default "0.0.0.0"; 2849 } 2851 7.4. The type Statement 2853 The "type" statement takes as an argument a string that is the name 2854 of a YANG built-in type (see Section 9) or a derived type (see 2855 Section 7.3), followed by an optional block of substatements that are 2856 used to put further restrictions on the type. 2858 The restrictions that can be applied depend on the type being 2859 restricted. The restriction statements for all built-in types are 2860 described in the subsections of Section 9. 2862 7.4.1. The type's Substatements 2864 +------------------+---------+-------------+ 2865 | substatement | section | cardinality | 2866 +------------------+---------+-------------+ 2867 | base | 7.18.2 | 0..n | 2868 | bit | 9.7.4 | 0..n | 2869 | enum | 9.6.4 | 0..n | 2870 | fraction-digits | 9.3.4 | 0..1 | 2871 | length | 9.4.4 | 0..1 | 2872 | path | 9.9.2 | 0..1 | 2873 | pattern | 9.4.5 | 0..n | 2874 | range | 9.2.4 | 0..1 | 2875 | require-instance | 9.9.3 | 0..1 | 2876 | type | 7.4 | 0..n | 2877 +------------------+---------+-------------+ 2879 7.5. The container Statement 2881 The "container" statement is used to define an interior data node in 2882 the schema tree. It takes one argument, which is an identifier, 2883 followed by a block of substatements that holds detailed container 2884 information. 2886 A container node does not have a value, but it has a list of child 2887 nodes in the data tree. The child nodes are defined in the 2888 container's substatements. 2890 7.5.1. Containers with Presence 2892 YANG supports two styles of containers, those that exist only for 2893 organizing the hierarchy of data nodes, and those whose presence in 2894 the data tree has an explicit meaning. 2896 In the first style, the container has no meaning of its own, existing 2897 only to contain child nodes. In particular, the presence of the 2898 container node with no child nodes is semantically equivalent to the 2899 absence of the container node. YANG calls this style a "non-presence 2900 container". This is the default style. 2902 For example, the set of scrambling options for Synchronous Optical 2903 Network (SONET) interfaces may be placed inside a "scrambling" 2904 container to enhance the organization of the configuration hierarchy, 2905 and to keep these nodes together. The "scrambling" node itself has 2906 no meaning, so removing the node when it becomes empty relieves the 2907 user from performing this task. 2909 In the second style, the presence of the container itself carries 2910 some meaning, representing a single bit of data. 2912 For configuration data, the container acts as both a configuration 2913 knob and a means of organizing related configuration. These 2914 containers are explicitly created and deleted. 2916 YANG calls this style a "presence container" and it is indicated 2917 using the "presence" statement, which takes as its argument a text 2918 string indicating what the presence of the node means. 2920 For example, an "ssh" container may turn on the ability to log into 2921 the server using ssh, but can also contain any ssh-related 2922 configuration knobs, such as connection rates or retry limits. 2924 The "presence" statement (see Section 7.5.5) is used to give 2925 semantics to the existence of the container in the data tree. 2927 7.5.2. The container's Substatements 2928 +--------------+---------+-------------+ 2929 | substatement | section | cardinality | 2930 +--------------+---------+-------------+ 2931 | action | 7.15 | 0..n | 2932 | anydata | 7.10 | 0..n | 2933 | anyxml | 7.11 | 0..n | 2934 | choice | 7.9 | 0..n | 2935 | config | 7.21.1 | 0..1 | 2936 | container | 7.5 | 0..n | 2937 | description | 7.21.3 | 0..1 | 2938 | grouping | 7.12 | 0..n | 2939 | if-feature | 7.20.2 | 0..n | 2940 | leaf | 7.6 | 0..n | 2941 | leaf-list | 7.7 | 0..n | 2942 | list | 7.8 | 0..n | 2943 | must | 7.5.3 | 0..n | 2944 | notification | 7.16 | 0..n | 2945 | presence | 7.5.5 | 0..1 | 2946 | reference | 7.21.4 | 0..1 | 2947 | status | 7.21.2 | 0..1 | 2948 | typedef | 7.3 | 0..n | 2949 | uses | 7.13 | 0..n | 2950 | when | 7.21.5 | 0..1 | 2951 +--------------+---------+-------------+ 2953 7.5.3. The must Statement 2955 The "must" statement, which is optional, takes as an argument a 2956 string that contains an XPath expression (see Section 6.4). It is 2957 used to formally declare a constraint on valid data. The constraint 2958 is enforced according to the rules in Section 8. 2960 When a datastore is validated, all "must" constraints are 2961 conceptually evaluated once for each node in the accessible tree (see 2962 Section 6.4.1). 2964 All such constraints MUST evaluate to "true" for the data to be 2965 valid. 2967 The XPath expression is conceptually evaluated in the following 2968 context, in addition to the definition in Section 6.4.1: 2970 o If the "must" statement is a substatement of a "notification" 2971 statement, the context node is the node representing the 2972 notification in the accessible tree. 2974 o If the "must" statement is a substatement of an "input" statement, 2975 the context node is the node representing the operation in the 2976 accessible tree. 2978 o If the "must" statement is a substatement of an "output" 2979 statement, the context node is the node representing the operation 2980 in the accessible tree. 2982 o Otherwise, the context node is the node in the accessible tree for 2983 which the "must" statement is defined. 2985 The result of the XPath expression is converted to a boolean value 2986 using the standard XPath rules. 2988 Note that since all leaf values in the data tree are conceptually 2989 stored in their canonical form (see Section 9.1), any XPath 2990 comparisons are done on the canonical value. 2992 Also note that the XPath expression is conceptually evaluated. This 2993 means that an implementation does not have to use an XPath evaluator 2994 in the server. How the evaluation is done in practice is an 2995 implementation decision. 2997 7.5.4. The must's Substatements 2999 +---------------+---------+-------------+ 3000 | substatement | section | cardinality | 3001 +---------------+---------+-------------+ 3002 | description | 7.21.3 | 0..1 | 3003 | error-app-tag | 7.5.4.2 | 0..1 | 3004 | error-message | 7.5.4.1 | 0..1 | 3005 | reference | 7.21.4 | 0..1 | 3006 +---------------+---------+-------------+ 3008 7.5.4.1. The error-message Statement 3010 The "error-message" statement, which is optional, takes a string as 3011 an argument. If the constraint evaluates to "false", the string is 3012 passed as in the in NETCONF. 3014 7.5.4.2. The error-app-tag Statement 3016 The "error-app-tag" statement, which is optional, takes a string as 3017 an argument. If the constraint evaluates to "false", the string is 3018 passed as in the in NETCONF. 3020 7.5.4.3. Usage Example of must and error-message 3022 container interface { 3023 leaf ifType { 3024 type enumeration { 3025 enum ethernet; 3026 enum atm; 3027 } 3028 } 3029 leaf ifMTU { 3030 type uint32; 3031 } 3032 must 'ifType != "ethernet" or ifMTU = 1500' { 3033 error-message "An ethernet MTU must be 1500"; 3034 } 3035 must 'ifType != "atm" or' 3036 + ' (ifMTU <= 17966 and ifMTU >= 64)' { 3037 error-message "An atm MTU must be 64 .. 17966"; 3038 } 3039 } 3041 7.5.5. The presence Statement 3043 The "presence" statement assigns a meaning to the presence of a 3044 container in the data tree. It takes as an argument a string that 3045 contains a textual description of what the node's presence means. 3047 If a container has the "presence" statement, the container's 3048 existence in the data tree carries some meaning. Otherwise, the 3049 container is used to give some structure to the data, and it carries 3050 no meaning by itself. 3052 See Section 7.5.1 for additional information. 3054 7.5.6. The container's Child Node Statements 3056 Within a container, the "container", "leaf", "list", "leaf-list", 3057 "uses", "choice", "anydata", and "anyxml" statements can be used to 3058 define child nodes to the container. 3060 7.5.7. XML Encoding Rules 3062 A container node is encoded as an XML element. The element's local 3063 name is the container's identifier, and its namespace is the module's 3064 XML namespace (see Section 7.1.3). 3066 The container's child nodes are encoded as subelements to the 3067 container element. If the container defines RPC or action input or 3068 output parameters, these subelements are encoded in the same order as 3069 they are defined within the "container" statement. Otherwise, the 3070 subelements are encoded in any order. 3072 Any whitespace between the subelements to the container is 3073 insignificant, i.e., an implementation MAY insert whitespace 3074 characters between subelements. 3076 If a non-presence container does not have any child nodes, the 3077 container may or may not be present in the XML encoding. 3079 7.5.8. NETCONF Operations 3081 Containers can be created, deleted, replaced, and modified through 3082 , by using the "operation" attribute (see [RFC6241], 3083 Section 7.2) in the container's XML element. 3085 If a container does not have a "presence" statement and the last 3086 child node is deleted, the NETCONF server MAY delete the container. 3088 When a NETCONF server processes an request, the 3089 elements of procedure for the container node are: 3091 If the operation is "merge" or "replace", the node is created if 3092 it does not exist. 3094 If the operation is "create", the node is created if it does not 3095 exist. If the node already exists, a "data-exists" error is 3096 returned. 3098 If the operation is "delete", the node is deleted if it exists. 3099 If the node does not exist, a "data-missing" error is returned. 3101 7.5.9. Usage Example 3103 Given the following container definition: 3105 container system { 3106 description 3107 "Contains various system parameters"; 3108 container services { 3109 description 3110 "Configure externally available services"; 3111 container "ssh" { 3112 presence "Enables SSH"; 3113 description 3114 "SSH service specific configuration"; 3115 // more leafs, containers and stuff here... 3116 } 3117 } 3118 } 3120 A corresponding XML instance example: 3122 3123 3124 3125 3126 3128 Since the element is present, ssh is enabled. 3130 To delete a container with an : 3132 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3149 7.6. The leaf Statement 3151 The "leaf" statement is used to define a leaf node in the schema 3152 tree. It takes one argument, which is an identifier, followed by a 3153 block of substatements that holds detailed leaf information. 3155 A leaf node has a value, but no child nodes in the data tree. 3156 Conceptually, the value in the data tree is always in the canonical 3157 form (see Section 9.1). 3159 A leaf node exists in zero or one instances in the data tree. 3161 The "leaf" statement is used to define a scalar variable of a 3162 particular built-in or derived type. 3164 7.6.1. The leaf's default value 3166 The default value of a leaf is the value that the server uses if the 3167 leaf does not exist in the data tree. The usage of the default value 3168 depends on the leaf's closest ancestor node in the schema tree that 3169 is not a non-presence container (see Section 7.5.1): 3171 o If no such ancestor exists in the schema tree, the default value 3172 MUST be used. 3174 o Otherwise, if this ancestor is a case node, the default value MUST 3175 be used if any node from the case exists in the data tree, or if 3176 the case node is the choice's default case, and no nodes from any 3177 other case exist in the data tree. 3179 o Otherwise, the default value MUST be used if the ancestor node 3180 exists in the data tree. 3182 In these cases, the default value is said to be in use. 3184 Note that if the leaf or any of its ancestors has a "when" condition 3185 or "if-feature" expression that evaluates to "false", then the 3186 default value is not in use. 3188 When the default value is in use, the server MUST operationally 3189 behave as if the leaf was present in the data tree with the default 3190 value as its value. 3192 If a leaf has a "default" statement, the leaf's default value is the 3193 value of the "default" statement. Otherwise, if the leaf's type has 3194 a default value, and the leaf is not mandatory, then the leaf's 3195 default value is the type's default value. In all other cases, the 3196 leaf does not have a default value. 3198 7.6.2. The leaf's Substatements 3200 +--------------+---------+-------------+ 3201 | substatement | section | cardinality | 3202 +--------------+---------+-------------+ 3203 | config | 7.21.1 | 0..1 | 3204 | default | 7.6.4 | 0..1 | 3205 | description | 7.21.3 | 0..1 | 3206 | if-feature | 7.20.2 | 0..n | 3207 | mandatory | 7.6.5 | 0..1 | 3208 | must | 7.5.3 | 0..n | 3209 | reference | 7.21.4 | 0..1 | 3210 | status | 7.21.2 | 0..1 | 3211 | type | 7.6.3 | 1 | 3212 | units | 7.3.3 | 0..1 | 3213 | when | 7.21.5 | 0..1 | 3214 +--------------+---------+-------------+ 3216 7.6.3. The leaf's type Statement 3218 The "type" statement, which MUST be present, takes as an argument the 3219 name of an existing built-in or derived type. The optional 3220 substatements specify restrictions on this type. See Section 7.4 for 3221 details. 3223 7.6.4. The leaf's default Statement 3225 The "default" statement, which is optional, takes as an argument a 3226 string that contains a default value for the leaf. 3228 The value of the "default" statement MUST be valid according to the 3229 type specified in the leaf's "type" statement. 3231 The "default" statement MUST NOT be present on nodes where 3232 "mandatory" is "true". 3234 The definition of the default value MUST NOT be marked with an 3235 "if-feature" statement. For example, the following is illegal: 3237 leaf color { 3238 type enumeration { 3239 enum blue { if-feature blue; } 3240 ... 3241 } 3242 default blue; // illegal - enum value is conditional 3243 } 3245 7.6.5. The leaf's mandatory Statement 3247 The "mandatory" statement, which is optional, takes as an argument 3248 the string "true" or "false", and puts a constraint on valid data. 3249 If not specified, the default is "false". 3251 If "mandatory" is "true", the behavior of the constraint depends on 3252 the type of the leaf's closest ancestor node in the schema tree that 3253 is not a non-presence container (see Section 7.5.1): 3255 o If no such ancestor exists in the schema tree, the leaf MUST 3256 exist. 3258 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 3259 any node from the case exists in the data tree. 3261 o Otherwise, the leaf MUST exist if the ancestor node exists in the 3262 data tree. 3264 This constraint is enforced according to the rules in Section 8. 3266 7.6.6. XML Encoding Rules 3268 A leaf node is encoded as an XML element. The element's local name 3269 is the leaf's identifier, and its namespace is the module's XML 3270 namespace (see Section 7.1.3). 3272 The value of the leaf node is encoded to XML according to the type, 3273 and sent as character data in the element. 3275 See Section 7.6.8 for an example. 3277 7.6.7. NETCONF Operations 3279 When a NETCONF server processes an request, the 3280 elements of procedure for the leaf node are: 3282 If the operation is "merge" or "replace", the node is created if 3283 it does not exist, and its value is set to the value found in the 3284 XML RPC data. 3286 If the operation is "create", the node is created if it does not 3287 exist. If the node already exists, a "data-exists" error is 3288 returned. 3290 If the operation is "delete", the node is deleted if it exists. 3291 If the node does not exist, a "data-missing" error is returned. 3293 7.6.8. Usage Example 3295 Given the following "leaf" statement, placed in the previously 3296 defined "ssh" container (see Section 7.5.9): 3298 leaf port { 3299 type inet:port-number; 3300 default 22; 3301 description 3302 "The port to which the SSH server listens" 3303 } 3305 A corresponding XML instance example: 3307 2022 3309 To set the value of a leaf with an : 3311 3314 3315 3316 3317 3318 3319 3320 3321 3322 2022 3323 3324 3325 3326 3327 3328 3330 7.7. The leaf-list Statement 3332 Where the "leaf" statement is used to define a simple scalar variable 3333 of a particular type, the "leaf-list" statement is used to define an 3334 array of a particular type. The "leaf-list" statement takes one 3335 argument, which is an identifier, followed by a block of 3336 substatements that holds detailed leaf-list information. 3338 In configuration data, the values in a leaf-list MUST be unique. 3340 The definitions of the default values MUST NOT be marked with an 3341 "if-feature" statement. 3343 Conceptually, the values in the data tree MUST be in the canonical 3344 form (see Section 9.1). 3346 7.7.1. Ordering 3348 YANG supports two styles for ordering the entries within lists and 3349 leaf-lists. In many lists, the order of list entries does not impact 3350 the implementation of the list's configuration, and the server is 3351 free to sort the list entries in any reasonable order. The 3352 "description" string for the list may suggest an order to the server 3353 implementor. YANG calls this style of list "system ordered" and they 3354 are indicated with the statement "ordered-by system". 3356 For example, a list of valid users would typically be sorted 3357 alphabetically, since the order in which the users appeared in the 3358 configuration would not impact the creation of those users' accounts. 3360 In the other style of lists, the order of list entries matters for 3361 the implementation of the list's configuration and the user is 3362 responsible for ordering the entries, while the server maintains that 3363 order. YANG calls this style of list "user ordered" and they are 3364 indicated with the statement "ordered-by user". 3366 For example, the order in which packet filters entries are applied to 3367 incoming traffic may affect how that traffic is filtered. The user 3368 would need to decide if the filter entry that discards all TCP 3369 traffic should be applied before or after the filter entry that 3370 allows all traffic from trusted interfaces. The choice of order 3371 would be crucial. 3373 YANG provides a rich set of facilities within NETCONF's 3374 operation that allows the order of list entries in user-ordered lists 3375 to be controlled. List entries may be inserted or rearranged, 3376 positioned as the first or last entry in the list, or positioned 3377 before or after another specific entry. 3379 The "ordered-by" statement is covered in Section 7.7.7. 3381 7.7.2. The leaf-list's default values 3383 The default values of a leaf-list are the values that the server uses 3384 if the leaf-list does not exist in the data tree. The usage of the 3385 default values depends on the leaf-list's closest ancestor node in 3386 the schema tree that is not a non-presence container (see 3387 Section 7.5.1): 3389 o If no such ancestor exists in the schema tree, the default values 3390 MUST be used. 3392 o Otherwise, if this ancestor is a case node, the default values 3393 MUST be used if any node from the case exists in the data tree, or 3394 if the case node is the choice's default case, and no nodes from 3395 any other case exist in the data tree. 3397 o Otherwise, the default values MUST be used if the ancestor node 3398 exists in the data tree. 3400 In these cases, the default values are said to be in use. 3402 Note that if the leaf-list or any of its ancestors has a "when" 3403 condition or "if-feature" expression that evaluates to "false", then 3404 the default values are not in use. 3406 When the default values are in use, the server MUST operationally 3407 behave as if the leaf-list was present in the data tree with the 3408 default values as its values. 3410 If a leaf-list has one or more "default" statement, the leaf-list's 3411 default values are the values of the "default" statements, and if the 3412 leaf-list is user-ordered, the default values are used in the order 3413 of the "default" statements. Otherwise, if the leaf-list's type has 3414 a default value, and the leaf-list does not have a "min-elements" 3415 statement with a value greater than or equal to one, then the leaf- 3416 list's default value is one instance of the type's default value. In 3417 all other cases, the leaf-list does not have any default values. 3419 7.7.3. The leaf-list's Substatements 3420 +--------------+---------+-------------+ 3421 | substatement | section | cardinality | 3422 +--------------+---------+-------------+ 3423 | config | 7.21.1 | 0..1 | 3424 | default | 7.7.4 | 0..n | 3425 | description | 7.21.3 | 0..1 | 3426 | if-feature | 7.20.2 | 0..n | 3427 | max-elements | 7.7.6 | 0..1 | 3428 | min-elements | 7.7.5 | 0..1 | 3429 | must | 7.5.3 | 0..n | 3430 | ordered-by | 7.7.7 | 0..1 | 3431 | reference | 7.21.4 | 0..1 | 3432 | status | 7.21.2 | 0..1 | 3433 | type | 7.4 | 1 | 3434 | units | 7.3.3 | 0..1 | 3435 | when | 7.21.5 | 0..1 | 3436 +--------------+---------+-------------+ 3438 7.7.4. The leaf-list's default Statement 3440 The "default" statement, which is optional, takes as an argument a 3441 string that contains a default value for the leaf-list. 3443 The value of the "default" statement MUST be valid according to the 3444 type specified in the leaf-list's "type" statement. 3446 The "default" statement MUST NOT be present on nodes where 3447 "min-elements" has a value greater than or equal to one. 3449 7.7.5. The min-elements Statement 3451 The "min-elements" statement, which is optional, takes as an argument 3452 a non-negative integer that puts a constraint on valid list entries. 3453 A valid leaf-list or list MUST have at least min-elements entries. 3455 If no "min-elements" statement is present, it defaults to zero. 3457 The behavior of the constraint depends on the type of the leaf-list's 3458 or list's closest ancestor node in the schema tree that is not a non- 3459 presence container (see Section 7.5.1): 3461 o If no such ancestor exists in the schema tree, the constraint is 3462 enforced. 3464 o Otherwise, if this ancestor is a case node, the constraint is 3465 enforced if any other node from the case exists. 3467 o Otherwise, it is enforced if the ancestor node exists. 3469 The constraint is further enforced according to the rules in 3470 Section 8. 3472 7.7.6. The max-elements Statement 3474 The "max-elements" statement, which is optional, takes as an argument 3475 a positive integer or the string "unbounded", which puts a constraint 3476 on valid list entries. A valid leaf-list or list always has at most 3477 max-elements entries. 3479 If no "max-elements" statement is present, it defaults to 3480 "unbounded". 3482 The "max-elements" constraint is enforced according to the rules in 3483 Section 8. 3485 7.7.7. The ordered-by Statement 3487 The "ordered-by" statement defines whether the order of entries 3488 within a list are determined by the user or the system. The argument 3489 is one of the strings "system" or "user". If not present, order 3490 defaults to "system". 3492 This statement is ignored if the list represents state data, RPC 3493 output parameters, or notification content. 3495 See Section 7.7.1 for additional information. 3497 7.7.7.1. ordered-by system 3499 The entries in the list are ordered according to an order determined 3500 by the system. The "description" string for the list may suggest an 3501 order to the server implementor. If not, an implementation is free 3502 to order the entries in any order. An implementation SHOULD use the 3503 same order for the same data, regardless of how the data were 3504 created. Using a deterministic order will make comparisons possible 3505 using simple tools like "diff". 3507 This is the default order. 3509 7.7.7.2. ordered-by user 3511 The entries in the list are ordered according to an order defined by 3512 the user. In NETCONF, this order is controlled by using special XML 3513 attributes in the request. See Section 7.7.9 for 3514 details. 3516 7.7.8. XML Encoding Rules 3518 A leaf-list node is encoded as a series of XML elements. Each 3519 element's local name is the leaf-list's identifier, and its namespace 3520 is the module's XML namespace (see Section 7.1.3). 3522 The value of each leaf-list entry is encoded to XML according to the 3523 type, and sent as character data in the element. 3525 The XML elements representing leaf-list entries MUST appear in the 3526 order specified by the user if the leaf-list is "ordered-by user"; 3527 otherwise, the order is implementation-dependent. The XML elements 3528 representing leaf-list entries MAY be interleaved with elements for 3529 siblings of the leaf-list, unless the leaf-list defines RPC or action 3530 input or output parameters. 3532 See Section 7.7.10 for an example. 3534 7.7.9. NETCONF Operations 3536 Leaf-list entries can be created and deleted, but not modified, 3537 through , by using the "operation" attribute in the 3538 leaf-list entry's XML element. 3540 In an "ordered-by user" leaf-list, the attributes "insert" and 3541 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3542 control where in the leaf-list the entry is inserted. These can be 3543 used during "create" operations to insert a new leaf-list entry, or 3544 during "merge" or "replace" operations to insert a new leaf-list 3545 entry or move an existing one. 3547 The "insert" attribute can take the values "first", "last", "before", 3548 and "after". If the value is "before" or "after", the "value" 3549 attribute MUST also be used to specify an existing entry in the leaf- 3550 list. 3552 If no "insert" attribute is present in the "create" operation, it 3553 defaults to "last". 3555 If several entries in an "ordered-by user" leaf-list are modified in 3556 the same request, the entries are modified one at the 3557 time, in the order of the XML elements in the request. 3559 In a , or an with a "replace" operation 3560 that covers the entire leaf-list, the leaf-list order is the same as 3561 the order of the XML elements in the request. 3563 When a NETCONF server processes an request, the 3564 elements of procedure for a leaf-list node are: 3566 If the operation is "merge" or "replace", the leaf-list entry is 3567 created if it does not exist. 3569 If the operation is "create", the leaf-list entry is created if it 3570 does not exist. If the leaf-list entry already exists, a 3571 "data-exists" error is returned. 3573 If the operation is "delete", the entry is deleted from the leaf- 3574 list if it exists. If the leaf-list entry does not exist, a 3575 "data-missing" error is returned. 3577 7.7.10. Usage Example 3579 leaf-list allow-user { 3580 type string; 3581 description 3582 "A list of user name patterns to allow"; 3583 } 3585 A corresponding XML instance example: 3587 alice 3588 bob 3590 To create a new element in this list, using the default 3591 operation "merge": 3593 3596 3597 3598 3599 3600 3601 3602 3603 3604 eric 3605 3606 3607 3608 3609 3610 3612 Given the following ordered-by user leaf-list: 3614 leaf-list cipher { 3615 type string; 3616 ordered-by user; 3617 description 3618 "A list of ciphers"; 3619 } 3621 The following would be used to insert a new cipher "blowfish-cbc" 3622 after "3des-cbc": 3624 3628 3629 3630 3631 3632 3633 3634 3635 3636 blowfish-cbc 3639 3640 3641 3642 3643 3644 3646 7.8. The list Statement 3648 The "list" statement is used to define an interior data node in the 3649 schema tree. A list node may exist in multiple instances in the data 3650 tree. Each such instance is known as a list entry. The "list" 3651 statement takes one argument, which is an identifier, followed by a 3652 block of substatements that holds detailed list information. 3654 A list entry is uniquely identified by the values of the list's keys, 3655 if defined. 3657 7.8.1. The list's Substatements 3659 +--------------+---------+-------------+ 3660 | substatement | section | cardinality | 3661 +--------------+---------+-------------+ 3662 | action | 7.15 | 0..n | 3663 | anydata | 7.10 | 0..n | 3664 | anyxml | 7.11 | 0..n | 3665 | choice | 7.9 | 0..n | 3666 | config | 7.21.1 | 0..1 | 3667 | container | 7.5 | 0..n | 3668 | description | 7.21.3 | 0..1 | 3669 | grouping | 7.12 | 0..n | 3670 | if-feature | 7.20.2 | 0..n | 3671 | key | 7.8.2 | 0..1 | 3672 | leaf | 7.6 | 0..n | 3673 | leaf-list | 7.7 | 0..n | 3674 | list | 7.8 | 0..n | 3675 | max-elements | 7.7.6 | 0..1 | 3676 | min-elements | 7.7.5 | 0..1 | 3677 | must | 7.5.3 | 0..n | 3678 | notification | 7.16 | 0..n | 3679 | ordered-by | 7.7.7 | 0..1 | 3680 | reference | 7.21.4 | 0..1 | 3681 | status | 7.21.2 | 0..1 | 3682 | typedef | 7.3 | 0..n | 3683 | unique | 7.8.3 | 0..n | 3684 | uses | 7.13 | 0..n | 3685 | when | 7.21.5 | 0..1 | 3686 +--------------+---------+-------------+ 3688 7.8.2. The list's key Statement 3690 The "key" statement, which MUST be present if the list represents 3691 configuration, and MAY be present otherwise, takes as an argument a 3692 string that specifies a space-separated list of one or more leaf 3693 identifiers of this list. A leaf identifier MUST NOT appear more 3694 than once in the key. Each such leaf identifier MUST refer to a 3695 child leaf of the list. The leafs can be defined directly in 3696 substatements to the list, or in groupings used in the list. 3698 The combined values of all the leafs specified in the key are used to 3699 uniquely identify a list entry. All key leafs MUST be given values 3700 when a list entry is created. Thus, any default values in the key 3701 leafs or their types are ignored. It also implies that any mandatory 3702 statement in the key leafs are ignored. 3704 A leaf that is part of the key can be of any built-in or derived 3705 type. 3707 All key leafs in a list MUST have the same value for their "config" 3708 as the list itself. 3710 The key string syntax is formally defined by the rule "key-arg" in 3711 Section 14. 3713 7.8.3. The list's unique Statement 3715 The "unique" statement is used to put constraints on valid list 3716 entries. It takes as an argument a string that contains a space- 3717 separated list of schema node identifiers, which MUST be given in the 3718 descendant form (see the rule "descendant-schema-nodeid" in 3719 Section 14). Each such schema node identifier MUST refer to a leaf. 3721 If one of the referenced leafs represents configuration data, then 3722 all of the referenced leafs MUST represent configuration data. 3724 The "unique" constraint specifies that the combined values of all the 3725 leaf instances specified in the argument string, including leafs with 3726 default values, MUST be unique within all list entry instances in 3727 which all referenced leafs exist or have default values. The 3728 constraint is enforced according to the rules in Section 8. 3730 The unique string syntax is formally defined by the rule "unique-arg" 3731 in Section 14. 3733 7.8.3.1. Usage Example 3735 With the following list: 3737 list server { 3738 key "name"; 3739 unique "ip port"; 3740 leaf name { 3741 type string; 3742 } 3743 leaf ip { 3744 type inet:ip-address; 3745 } 3746 leaf port { 3747 type inet:port-number; 3748 } 3749 } 3751 The following configuration is not valid: 3753 3754 smtp 3755 192.0.2.1 3756 25 3757 3759 3760 http 3761 192.0.2.1 3762 25 3763 3765 The following configuration is valid, since the "http" and "ftp" list 3766 entries do not have a value for all referenced leafs, and are thus 3767 not taken into account when the "unique" constraint is enforced: 3769 3770 smtp 3771 192.0.2.1 3772 25 3773 3775 3776 http 3777 192.0.2.1 3778 3780 3781 ftp 3782 192.0.2.1 3783 3785 7.8.4. The list's Child Node Statements 3787 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3788 "choice", "anydata", and "anyxml" statements can be used to define 3789 child nodes to the list. 3791 7.8.5. XML Encoding Rules 3793 A list is encoded as a series of XML elements, one for each entry in 3794 the list. Each element's local name is the list's identifier, and 3795 its namespace is the module's XML namespace (see Section 7.1.3). 3796 There is no XML element surrounding the list as a whole. 3798 The list's key nodes are encoded as subelements to the list's 3799 identifier element, in the same order as they are defined within the 3800 "key" statement. 3802 The rest of the list's child nodes are encoded as subelements to the 3803 list element, after the keys. If the list defines RPC or action 3804 input or output parameters, the subelements are encoded in the same 3805 order as they are defined within the "list" statement. Otherwise, 3806 the subelements are encoded in any order. 3808 Any whitespace between the subelements to the list entry is 3809 insignificant, i.e., an implementation MAY insert whitespace 3810 characters between subelements. 3812 The XML elements representing list entries MUST appear in the order 3813 specified by the user if the list is "ordered-by user", otherwise the 3814 order is implementation-dependent. The XML elements representing 3815 list entries MAY be interleaved with elements for siblings of the 3816 list, unless the list defines RPC or action input or output 3817 parameters. 3819 7.8.6. NETCONF Operations 3821 List entries can be created, deleted, replaced, and modified through 3822 , by using the "operation" attribute in the list's XML 3823 element. In each case, the values of all keys are used to uniquely 3824 identify a list entry. If all keys are not specified for a list 3825 entry, a "missing-element" error is returned. 3827 In an "ordered-by user" list, the attributes "insert" and "key" in 3828 the YANG XML namespace (Section 5.3.1) can be used to control where 3829 in the list the entry is inserted. These can be used during "create" 3830 operations to insert a new list entry, or during "merge" or "replace" 3831 operations to insert a new list entry or move an existing one. 3833 The "insert" attribute can take the values "first", "last", "before", 3834 and "after". If the value is "before" or "after", the "key" 3835 attribute MUST also be used, to specify an existing element in the 3836 list. The value of the "key" attribute is the key predicates of the 3837 full instance identifier (see Section 9.13) for the list entry. 3839 If no "insert" attribute is present in the "create" operation, it 3840 defaults to "last". 3842 If several entries in an "ordered-by user" list are modified in the 3843 same request, the entries are modified one at the time, 3844 in the order of the XML elements in the request. 3846 In a , or an with a "replace" operation 3847 that covers the entire list, the list entry order is the same as the 3848 order of the XML elements in the request. 3850 When a NETCONF server processes an request, the 3851 elements of procedure for a list node are: 3853 If the operation is "merge" or "replace", the list entry is 3854 created if it does not exist. If the list entry already exists 3855 and the "insert" and "key" attributes are present, the list entry 3856 is moved according to the values of the "insert" and "key" 3857 attributes. If the list entry exists and the "insert" and "key" 3858 attributes are not present, the list entry is not moved. 3860 If the operation is "create", the list entry is created if it does 3861 not exist. If the list entry already exists, a "data-exists" 3862 error is returned. 3864 If the operation is "delete", the entry is deleted from the list 3865 if it exists. If the list entry does not exist, a "data-missing" 3866 error is returned. 3868 7.8.7. Usage Example 3870 Given the following list: 3872 list user { 3873 key "name"; 3874 config true; 3875 description 3876 "This is a list of users in the system."; 3878 leaf name { 3879 type string; 3880 } 3881 leaf type { 3882 type string; 3883 } 3884 leaf full-name { 3885 type string; 3886 } 3887 } 3889 A corresponding XML instance example: 3891 3892 fred 3893 admin 3894 Fred Flintstone 3895 3897 To create a new user "barney": 3899 3902 3903 3904 3905 3906 3907 3908 3909 barney 3910 admin 3911 Barney Rubble 3912 3913 3914 3915 3916 3918 To change the type of "fred" to "superuser": 3920 3923 3924 3925 3926 3927 3928 3929 3930 fred 3931 superuser 3932 3933 3934 3935 3936 3938 Given the following ordered-by user list: 3940 list user { 3941 description 3942 "This is a list of users in the system."; 3943 ordered-by user; 3944 config true; 3946 key "first-name surname"; 3948 leaf first-name { 3949 type string; 3950 } 3951 leaf surname { 3952 type string; 3953 } 3954 leaf type { 3955 type string; 3956 } 3957 } 3959 The following would be used to insert a new user "barney rubble" 3960 after the user "fred flintstone": 3962 3966 3967 3968 3969 3970 3971 3973 3977 barney 3978 rubble 3979 admin 3980 3981 3982 3983 3984 3986 The following would be used to move the user "barney rubble" before 3987 the user "fred flintstone": 3989 3993 3994 3995 3996 3997 3998 4000 4004 barney 4005 rubble 4006 4007 4008 4009 4010 4012 7.9. The choice Statement 4014 The "choice" statement defines a set of alternatives, only one of 4015 which may be present in any one data tree. The argument is an 4016 identifier, followed by a block of substatements that holds detailed 4017 choice information. The identifier is used to identify the choice 4018 node in the schema tree. A choice node does not exist in the data 4019 tree. 4021 A choice consists of a number of branches, each defined with a "case" 4022 substatement. Each branch contains a number of child nodes. The 4023 nodes from at most one of the choice's branches exist at the same 4024 time. 4026 Since only one of the choice's cases can be valid at any time in the 4027 data tree, the creation of a node from one case implicitly deletes 4028 all nodes from all other cases. If a request creates a node from a 4029 case, the server will delete any existing nodes that are defined in 4030 other cases inside the choice. 4032 7.9.1. The choice's Substatements 4033 +--------------+---------+-------------+ 4034 | substatement | section | cardinality | 4035 +--------------+---------+-------------+ 4036 | anydata | 7.10 | 0..n | 4037 | anyxml | 7.11 | 0..n | 4038 | case | 7.9.2 | 0..n | 4039 | choice | 7.9 | 0..n | 4040 | config | 7.21.1 | 0..1 | 4041 | container | 7.5 | 0..n | 4042 | default | 7.9.3 | 0..1 | 4043 | description | 7.21.3 | 0..1 | 4044 | if-feature | 7.20.2 | 0..n | 4045 | leaf | 7.6 | 0..n | 4046 | leaf-list | 7.7 | 0..n | 4047 | list | 7.8 | 0..n | 4048 | mandatory | 7.9.4 | 0..1 | 4049 | reference | 7.21.4 | 0..1 | 4050 | status | 7.21.2 | 0..1 | 4051 | when | 7.21.5 | 0..1 | 4052 +--------------+---------+-------------+ 4054 7.9.2. The choice's case Statement 4056 The "case" statement is used to define branches of the choice. It 4057 takes as an argument an identifier, followed by a block of 4058 substatements that holds detailed case information. 4060 The identifier is used to identify the case node in the schema tree. 4061 A case node does not exist in the data tree. 4063 Within a "case" statement, the "anydata", "anyxml", "choice", 4064 "container", "leaf", "list", "leaf-list", and "uses" statements can 4065 be used to define child nodes to the case node. The identifiers of 4066 all these child nodes MUST be unique within all cases in a choice. 4067 For example, the following is illegal: 4069 choice interface-type { // This example is illegal YANG 4070 case a { 4071 leaf ethernet { ... } 4072 } 4073 case b { 4074 container ethernet { ...} 4075 } 4076 } 4078 As a shorthand, the "case" statement can be omitted if the branch 4079 contains a single "anydata", "anyxml", "choice", "container", "leaf", 4080 "list", or "leaf-list" statement. In this case, the case node still 4081 exists in the schema tree, and its identifier is the same as the 4082 identifier of the child node. Schema node identifiers (Section 6.5) 4083 MUST always explicitly include case node identifiers. The following 4084 example: 4086 choice interface-type { 4087 container ethernet { ... } 4088 } 4090 is equivalent to: 4092 choice interface-type { 4093 case ethernet { 4094 container ethernet { ... } 4095 } 4096 } 4098 The case identifier MUST be unique within a choice. 4100 7.9.2.1. The case's Substatements 4102 +--------------+---------+-------------+ 4103 | substatement | section | cardinality | 4104 +--------------+---------+-------------+ 4105 | anydata | 7.10 | 0..n | 4106 | anyxml | 7.11 | 0..n | 4107 | choice | 7.9 | 0..n | 4108 | container | 7.5 | 0..n | 4109 | description | 7.21.3 | 0..1 | 4110 | if-feature | 7.20.2 | 0..n | 4111 | leaf | 7.6 | 0..n | 4112 | leaf-list | 7.7 | 0..n | 4113 | list | 7.8 | 0..n | 4114 | reference | 7.21.4 | 0..1 | 4115 | status | 7.21.2 | 0..1 | 4116 | uses | 7.13 | 0..n | 4117 | when | 7.21.5 | 0..1 | 4118 +--------------+---------+-------------+ 4120 7.9.3. The choice's default Statement 4122 The "default" statement indicates if a case should be considered as 4123 the default if no child nodes from any of the choice's cases exist. 4124 The argument is the identifier of the default "case" statement. If 4125 the "default" statement is missing, there is no default case. 4127 The "default" statement MUST NOT be present on choices where 4128 "mandatory" is "true". 4130 The default case is only important when considering the default 4131 statements of nodes under the cases (i.e., default values of leafs 4132 and leaf-lists, and default cases of nested choices). The default 4133 values and nested default cases under the default case are used if 4134 none of the nodes under any of the cases are present. 4136 There MUST NOT be any mandatory nodes (Section 3) directly under the 4137 default case. 4139 Default values for child nodes under a case are only used if one of 4140 the nodes under that case is present, or if that case is the default 4141 case. If none of the nodes under a case are present and the case is 4142 not the default case, the default values of the cases' child nodes 4143 are ignored. 4145 In this example, the choice defaults to "interval", and the default 4146 value will be used if none of "daily", "time-of-day", or "manual" are 4147 present. If "daily" is present, the default value for "time-of-day" 4148 will be used. 4150 container transfer { 4151 choice how { 4152 default interval; 4153 case interval { 4154 leaf interval { 4155 type uint16; 4156 units minutes; 4157 default 30; 4158 } 4159 } 4160 case daily { 4161 leaf daily { 4162 type empty; 4163 } 4164 leaf time-of-day { 4165 type string; 4166 units 24-hour-clock; 4167 default "01.00"; 4168 } 4169 } 4170 case manual { 4171 leaf manual { 4172 type empty; 4173 } 4174 } 4175 } 4176 } 4178 7.9.4. The choice's mandatory Statement 4180 The "mandatory" statement, which is optional, takes as an argument 4181 the string "true" or "false", and puts a constraint on valid data. 4182 If "mandatory" is "true", at least one node from exactly one of the 4183 choice's case branches MUST exist. 4185 If not specified, the default is "false". 4187 The behavior of the constraint depends on the type of the choice's 4188 closest ancestor node in the schema tree that is not a non-presence 4189 container (see Section 7.5.1): 4191 o If no such ancestor exists in the schema tree, the constraint is 4192 enforced. 4194 o Otherwise, if this ancestor is a case node, the constraint is 4195 enforced if any other node from the case exists. 4197 o Otherwise, it is enforced if the ancestor node exists. 4199 The constraint is further enforced according to the rules in 4200 Section 8. 4202 7.9.5. XML Encoding Rules 4204 The choice and case nodes are not visible in XML. 4206 The child nodes of the selected "case" statement MUST be encoded in 4207 the same order as they are defined in the "case" statement if they 4208 are part of an RPC or action input or output parameter definition. 4209 Otherwise, the subelements are encoded in any order. 4211 7.9.6. Usage Example 4213 Given the following choice: 4215 container protocol { 4216 choice name { 4217 case a { 4218 leaf udp { 4219 type empty; 4220 } 4221 } 4222 case b { 4223 leaf tcp { 4224 type empty; 4225 } 4226 } 4227 } 4228 } 4230 A corresponding XML instance example: 4232 4233 4234 4236 To change the protocol from tcp to udp: 4238 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4255 7.10. The anydata Statement 4257 The "anydata" statement defines an interior node in the schema tree. 4258 It takes one argument, which is an identifier, followed by a block of 4259 substatements that holds detailed anydata information. 4261 The "anydata" statement is used to represent an unknown set of nodes 4262 that can be modelled with YANG, except anyxml, but for which the data 4263 model is not known at module design time. It is possible, though not 4264 required, for the data model for "anydata" content to become known 4265 through protocol signalling or other means that are outside the scope 4266 of this document. 4268 An example of where anydata can be useful is a list of received 4269 notifications, where the specific notifications are not known at 4270 design time. 4272 An anydata node cannot be augmented (see Section 7.17). 4274 An anydata node exists in zero or one instances in the data tree. 4276 An implementation may or may not know the data model used to model a 4277 specific instance of an anydata node. 4279 Since the use of anydata limits the manipulation of the content, the 4280 "anydata" statement SHOULD NOT be used to define configuration data. 4282 7.10.1. The anydata's Substatements 4284 +--------------+---------+-------------+ 4285 | substatement | section | cardinality | 4286 +--------------+---------+-------------+ 4287 | config | 7.21.1 | 0..1 | 4288 | description | 7.21.3 | 0..1 | 4289 | if-feature | 7.20.2 | 0..n | 4290 | mandatory | 7.6.5 | 0..1 | 4291 | must | 7.5.3 | 0..n | 4292 | reference | 7.21.4 | 0..1 | 4293 | status | 7.21.2 | 0..1 | 4294 | when | 7.21.5 | 0..1 | 4295 +--------------+---------+-------------+ 4297 7.10.2. XML Encoding Rules 4299 An anydata node is encoded as an XML element. The element's local 4300 name is the anydata's identifier, and its namespace is the module's 4301 XML namespace (see Section 7.1.3). The value of the anydata node is 4302 a set of nodes, which are encoded as XML subelements to the anydata 4303 element. 4305 7.10.3. NETCONF Operations 4307 An anydata node is treated as an opaque chunk of data. This data can 4308 be modified in its entirety only. 4310 Any "operation" attributes present on subelements of an anydata node 4311 are ignored by the NETCONF server. 4313 When a NETCONF server processes an request, the 4314 elements of procedure for the anydata node are: 4316 If the operation is "merge" or "replace", the node is created if 4317 it does not exist, and its value is set to the subelements of the 4318 anydata node found in the XML RPC data. 4320 If the operation is "create", the node is created if it does not 4321 exist, and its value is set to the subelements of the anydata node 4322 found in the XML RPC data. If the node already exists, a 4323 "data-exists" error is returned. 4325 If the operation is "delete", the node is deleted if it exists. 4326 If the node does not exist, a "data-missing" error is returned. 4328 7.10.4. Usage Example 4330 Given the following "anydata" statement: 4332 list logged-notification { 4333 key time; 4334 leaf time { 4335 type yang:date-and-time; 4336 } 4337 anydata data; 4338 } 4340 The following is a valid encoding of such a list instance: 4342 4343 4344 4345 4347 2014-07-29T13:43:01Z 4348 4349 fault 4350 4351 Ethernet0 4352 4353 major 4354 4355 4356 4358 7.11. The anyxml Statement 4360 The "anyxml" statement defines an interior node in the schema tree. 4361 It takes one argument, which is an identifier, followed by a block of 4362 substatements that holds detailed anyxml information. 4364 The "anyxml" statement is used to represent an unknown chunk of XML. 4365 No restrictions are placed on the XML. This can be useful, for 4366 example, in RPC replies. An example is the parameter in the 4367 operation in NETCONF. 4369 An anyxml node cannot be augmented (see Section 7.17). 4371 An anyxml node exists in zero or one instances in the data tree. 4373 Since the use of anyxml limits the manipulation of the content, the 4374 "anyxml" statement SHOULD NOT be used to define configuration data. 4376 It should be noted that in YANG version 1, anyxml was the only 4377 statement that could model an unknown hierarchy of data. In many 4378 cases this unknown hierarchy of data is actually modelled in YANG, 4379 but the specific YANG data model is not known at design time. In 4380 these situations, it is RECOMMENDED to use anydata (Section 7.10) 4381 instead of anyxml. 4383 7.11.1. The anyxml's Substatements 4385 +--------------+---------+-------------+ 4386 | substatement | section | cardinality | 4387 +--------------+---------+-------------+ 4388 | config | 7.21.1 | 0..1 | 4389 | description | 7.21.3 | 0..1 | 4390 | if-feature | 7.20.2 | 0..n | 4391 | mandatory | 7.6.5 | 0..1 | 4392 | must | 7.5.3 | 0..n | 4393 | reference | 7.21.4 | 0..1 | 4394 | status | 7.21.2 | 0..1 | 4395 | when | 7.21.5 | 0..1 | 4396 +--------------+---------+-------------+ 4398 7.11.2. XML Encoding Rules 4400 An anyxml node is encoded as an XML element. The element's local 4401 name is the anyxml's identifier, and its namespace is the module's 4402 XML namespace (see Section 7.1.3). The value of the anyxml node is 4403 encoded as XML content of this element. 4405 Note that any XML prefixes used in the encoding are local to each 4406 instance encoding. This means that the same XML may be encoded 4407 differently by different implementations. 4409 7.11.3. NETCONF Operations 4411 An anyxml node is treated as an opaque chunk of data. This data can 4412 be modified in its entirety only. 4414 Any "operation" attributes present on subelements of an anyxml node 4415 are ignored by the NETCONF server. 4417 When a NETCONF server processes an request, the 4418 elements of procedure for the anyxml node are: 4420 If the operation is "merge" or "replace", the node is created if 4421 it does not exist, and its value is set to the XML content of the 4422 anyxml node found in the XML RPC data. 4424 If the operation is "create", the node is created if it does not 4425 exist, and its value is set to the XML content of the anyxml node 4426 found in the XML RPC data. If the node already exists, a 4427 "data-exists" error is returned. 4429 If the operation is "delete", the node is deleted if it exists. 4430 If the node does not exist, a "data-missing" error is returned. 4432 7.11.4. Usage Example 4434 Given the following "anyxml" statement: 4436 anyxml html-info; 4438 The following are two valid encodings of the same anyxml value: 4440 4441

4442 This is very cool. 4443

4444 4446 4447 4448 This is very cool. 4449 4450 4452 7.12. The grouping Statement 4454 The "grouping" statement is used to define a reusable block of nodes, 4455 which may be used locally in the module or submodule, and by other 4456 modules that import from it, according to the rules in Section 5.5. 4457 It takes one argument, which is an identifier, followed by a block of 4458 substatements that holds detailed grouping information. 4460 The "grouping" statement is not a data definition statement and, as 4461 such, does not define any nodes in the schema tree. 4463 A grouping is like a "structure" or a "record" in conventional 4464 programming languages. 4466 Once a grouping is defined, it can be referenced in a "uses" 4467 statement (see Section 7.13). A grouping MUST NOT reference itself, 4468 neither directly nor indirectly through a chain of other groupings. 4470 If the grouping is defined at the top level of a YANG module or 4471 submodule, the grouping's identifier MUST be unique within the 4472 module. 4474 A grouping is more than just a mechanism for textual substitution, 4475 but defines a collection of nodes. Identifiers appearing inside the 4476 grouping are resolved relative to the scope in which the grouping is 4477 defined, not where it is used. Prefix mappings, type names, grouping 4478 names, and extension usage are evaluated in the hierarchy where the 4479 "grouping" statement appears. For extensions, this means that 4480 extensions defined as direct children to a "grouping" statement are 4481 applied to the grouping itself. 4483 Note that if a grouping defines an "action" or a "notification" node 4484 in its hierarchy, then it cannot be used in all contexts. For 4485 example, it cannot be used in an rpc definition. See Section 7.15 4486 and Section 7.16. 4488 7.12.1. The grouping's Substatements 4489 +--------------+---------+-------------+ 4490 | substatement | section | cardinality | 4491 +--------------+---------+-------------+ 4492 | action | 7.15 | 0..n | 4493 | anydata | 7.10 | 0..n | 4494 | anyxml | 7.11 | 0..n | 4495 | choice | 7.9 | 0..n | 4496 | container | 7.5 | 0..n | 4497 | description | 7.21.3 | 0..1 | 4498 | grouping | 7.12 | 0..n | 4499 | leaf | 7.6 | 0..n | 4500 | leaf-list | 7.7 | 0..n | 4501 | list | 7.8 | 0..n | 4502 | notification | 7.16 | 0..n | 4503 | reference | 7.21.4 | 0..1 | 4504 | status | 7.21.2 | 0..1 | 4505 | typedef | 7.3 | 0..n | 4506 | uses | 7.13 | 0..n | 4507 +--------------+---------+-------------+ 4509 7.12.2. Usage Example 4511 import ietf-inet-types { 4512 prefix "inet"; 4513 } 4515 grouping endpoint { 4516 description "A reusable endpoint group."; 4517 leaf ip { 4518 type inet:ip-address; 4519 } 4520 leaf port { 4521 type inet:port-number; 4522 } 4523 } 4525 7.13. The uses Statement 4527 The "uses" statement is used to reference a "grouping" definition. 4528 It takes one argument, which is the name of the grouping. 4530 The effect of a "uses" reference to a grouping is that the nodes 4531 defined by the grouping are copied into the current schema tree, and 4532 then updated according to the "refine" and "augment" statements. 4534 The identifiers defined in the grouping are not bound to a namespace 4535 until the contents of the grouping are added to the schema tree via a 4536 "uses" statement that does not appear inside a "grouping" statement, 4537 at which point they are bound to the namespace of the current module. 4539 7.13.1. The uses's Substatements 4541 +--------------+---------+-------------+ 4542 | substatement | section | cardinality | 4543 +--------------+---------+-------------+ 4544 | augment | 7.17 | 0..n | 4545 | description | 7.21.3 | 0..1 | 4546 | if-feature | 7.20.2 | 0..n | 4547 | refine | 7.13.2 | 0..n | 4548 | reference | 7.21.4 | 0..1 | 4549 | status | 7.21.2 | 0..1 | 4550 | when | 7.21.5 | 0..1 | 4551 +--------------+---------+-------------+ 4553 7.13.2. The refine Statement 4555 Some of the properties of each node in the grouping can be refined 4556 with the "refine" statement. The argument is a string that 4557 identifies a node in the grouping. This node is called the refine's 4558 target node. If a node in the grouping is not present as a target 4559 node of a "refine" statement, it is not refined, and thus used 4560 exactly as it was defined in the grouping. 4562 The argument string is a descendant schema node identifier (see 4563 Section 6.5). 4565 The following refinements can be done: 4567 o A leaf or choice node may get a default value, or a new default 4568 value if it already had one. 4570 o A leaf-list node may get a set of default values, or a new set of 4571 default values if it already had defaults; i.e., the set of 4572 refined default values replaces the defaults already given. 4574 o Any node may get a specialized "description" string. 4576 o Any node may get a specialized "reference" string. 4578 o Any node may get a different "config" statement. 4580 o A leaf, anydata, anyxml, or choice node may get a different 4581 "mandatory" statement. 4583 o A container node may get a "presence" statement. 4585 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4586 get additional "must" expressions. 4588 o A leaf-list or list node may get a different "min-elements" or 4589 "max-elements" statement. 4591 o A leaf, leaf-list, list, container, choice, case, anydata, or 4592 anyxml node may get additional "if-feature" expressions. 4594 o Any node can get refined extensions, if the extension allows 4595 refinement. See Section 7.19 for details. 4597 7.13.3. XML Encoding Rules 4599 Each node in the grouping is encoded as if it was defined inline, 4600 even if it is imported from another module with another XML 4601 namespace. 4603 7.13.4. Usage Example 4605 To use the "endpoint" grouping defined in Section 7.12.2 in a 4606 definition of an HTTP server in some other module, we can do: 4608 import example-system { 4609 prefix "sys"; 4610 } 4612 container http-server { 4613 leaf name { 4614 type string; 4615 } 4616 uses sys:endpoint; 4617 } 4619 A corresponding XML instance example: 4621 4622 extern-web 4623 192.0.2.1 4624 80 4625 4627 If port 80 should be the default for the HTTP server, default can be 4628 added: 4630 container http-server { 4631 leaf name { 4632 type string; 4633 } 4634 uses sys:endpoint { 4635 refine port { 4636 default 80; 4637 } 4638 } 4639 } 4641 If we want to define a list of servers, and each server has the ip 4642 and port as keys, we can do: 4644 list server { 4645 key "ip port"; 4646 leaf name { 4647 type string; 4648 } 4649 uses sys:endpoint; 4650 } 4652 The following is an error: 4654 container http-server { 4655 uses sys:endpoint; 4656 leaf ip { // illegal - same identifier "ip" used twice 4657 type string; 4658 } 4659 } 4661 7.14. The rpc Statement 4663 The "rpc" statement is used to define an RPC operation. It takes one 4664 argument, which is an identifier, followed by a block of 4665 substatements that holds detailed rpc information. This argument is 4666 the name of the RPC. 4668 The "rpc" statement defines an rpc node in the schema tree. Under 4669 the rpc node, a schema node with the name "input", and a schema node 4670 with the name "output" are also defined. The nodes "input" and 4671 "output" are defined in the module's namespace. 4673 7.14.1. The rpc's Substatements 4674 +--------------+---------+-------------+ 4675 | substatement | section | cardinality | 4676 +--------------+---------+-------------+ 4677 | description | 7.21.3 | 0..1 | 4678 | grouping | 7.12 | 0..n | 4679 | if-feature | 7.20.2 | 0..n | 4680 | input | 7.14.2 | 0..1 | 4681 | output | 7.14.3 | 0..1 | 4682 | reference | 7.21.4 | 0..1 | 4683 | status | 7.21.2 | 0..1 | 4684 | typedef | 7.3 | 0..n | 4685 +--------------+---------+-------------+ 4687 7.14.2. The input Statement 4689 The "input" statement, which is optional, is used to define input 4690 parameters to the operation. It does not take an argument. The 4691 substatements to "input" define nodes under the operation's input 4692 node. 4694 If a leaf in the input tree has a "mandatory" statement with the 4695 value "true", the leaf MUST be present in an RPC invocation. 4697 If a leaf in the input tree has a default value, the server MUST use 4698 this value in the same cases as described in Section 7.6.1. In these 4699 cases, the server MUST operationally behave as if the leaf was 4700 present in the RPC invocation with the default value as its value. 4702 If a leaf-list in the input tree has one or more default values, the 4703 server MUST use these values in the same cases as described in 4704 Section 7.7.2. In these cases, the server MUST operationally behave 4705 as if the leaf-list was present in the RPC invocation with the 4706 default values as its values. 4708 Since the input tree is not part of any datastore, all "config" 4709 statements for nodes in the input tree are ignored. 4711 If any node has a "when" statement that would evaluate to "false", 4712 then this node MUST NOT be present in the input tree. 4714 7.14.2.1. The input's Substatements 4715 +--------------+---------+-------------+ 4716 | substatement | section | cardinality | 4717 +--------------+---------+-------------+ 4718 | anydata | 7.10 | 0..n | 4719 | anyxml | 7.11 | 0..n | 4720 | choice | 7.9 | 0..n | 4721 | container | 7.5 | 0..n | 4722 | grouping | 7.12 | 0..n | 4723 | leaf | 7.6 | 0..n | 4724 | leaf-list | 7.7 | 0..n | 4725 | list | 7.8 | 0..n | 4726 | must | 7.5.3 | 0..n | 4727 | typedef | 7.3 | 0..n | 4728 | uses | 7.13 | 0..n | 4729 +--------------+---------+-------------+ 4731 7.14.3. The output Statement 4733 The "output" statement, which is optional, is used to define output 4734 parameters to the RPC operation. It does not take an argument. The 4735 substatements to "output" define nodes under the operation's output 4736 node. 4738 If a leaf in the output tree has a "mandatory" statement with the 4739 value "true", the leaf MUST be present in an RPC reply. 4741 If a leaf in the output tree has a default value, the client MUST use 4742 this value in the same cases as described in Section 7.6.1. In these 4743 cases, the client MUST operationally behave as if the leaf was 4744 present in the RPC reply with the default value as its value. 4746 If a leaf-list in the output tree has one or more default values, the 4747 client MUST use these values in the same cases as described in 4748 Section 7.7.2. In these cases, the client MUST operationally behave 4749 as if the leaf-list was present in the RPC reply with the default 4750 values as its values. 4752 Since the output tree is not part of any datastore, all "config" 4753 statements for nodes in the output tree are ignored. 4755 If any node has a "when" statement that would evaluate to "false", 4756 then this node MUST NOT be present in the output tree. 4758 7.14.3.1. The output's Substatements 4759 +--------------+---------+-------------+ 4760 | substatement | section | cardinality | 4761 +--------------+---------+-------------+ 4762 | anydata | 7.10 | 0..n | 4763 | anyxml | 7.11 | 0..n | 4764 | choice | 7.9 | 0..n | 4765 | container | 7.5 | 0..n | 4766 | grouping | 7.12 | 0..n | 4767 | leaf | 7.6 | 0..n | 4768 | leaf-list | 7.7 | 0..n | 4769 | list | 7.8 | 0..n | 4770 | must | 7.5.3 | 0..n | 4771 | typedef | 7.3 | 0..n | 4772 | uses | 7.13 | 0..n | 4773 +--------------+---------+-------------+ 4775 7.14.4. NETCONF XML Encoding Rules 4777 An rpc node is encoded as a child XML element to the element, 4778 as designated by the substitution group "rpcOperation" in [RFC6241]. 4779 The element's local name is the rpc's identifier, and its namespace 4780 is the module's XML namespace (see Section 7.1.3). 4782 Input parameters are encoded as child XML elements to the rpc node's 4783 XML element, in the same order as they are defined within the "input" 4784 statement. 4786 If the RPC operation invocation succeeded, and no output parameters 4787 are returned, the contains a single element defined 4788 in [RFC6241]. If output parameters are returned, they are encoded as 4789 child elements to the element defined in [RFC6241], in 4790 the same order as they are defined within the "output" statement. 4792 7.14.5. Usage Example 4794 The following example defines an RPC operation: 4796 module example-rock { 4797 yang-version 1.1; 4798 namespace "urn:example:rock"; 4799 prefix "rock"; 4801 rpc rock-the-house { 4802 input { 4803 leaf zip-code { 4804 type string; 4805 } 4806 } 4807 } 4808 } 4810 A corresponding XML instance example of the complete rpc and rpc- 4811 reply: 4813 4815 4816 27606-0100 4817 4818 4820 4822 4823 4825 7.15. The action Statement 4827 The "action" statement is used to define an operation connected to a 4828 specific container or list data node. It takes one argument, which 4829 is an identifier, followed by a block of substatements that holds 4830 detailed action information. The argument is the name of the action. 4832 The "action" statement defines an action node in the schema tree. 4833 Under the action node, a schema node with the name "input", and a 4834 schema node with the name "output" are also defined. The nodes 4835 "input" and "output" are defined in the module's namespace. 4837 An action MUST NOT be defined within an rpc, another action or a 4838 notification, i.e., an action node MUST NOT have an rpc, action, or a 4839 notification node as one of its ancestors in the schema tree. For 4840 example, this means that it is an error if a grouping that contains 4841 an action somewhere in its node hierarchy is used in a notification 4842 definition. 4844 An action MUST NOT have any ancestor node that is a list node without 4845 a "key" statement. 4847 Since an action cannot be defined at the top-level of a module or in 4848 a case statement, it is an error if a grouping that contains an 4849 action at the top of its node hierarchy is used at the top-level of a 4850 module or in a case definition. 4852 The difference between an action and an rpc is that an action is tied 4853 to a node in the datastore, whereas an rpc is not. When an action is 4854 invoked, the node in the datastore is specified along with the name 4855 of the action and the input parameters. 4857 7.15.1. The action's Substatements 4859 +--------------+---------+-------------+ 4860 | substatement | section | cardinality | 4861 +--------------+---------+-------------+ 4862 | description | 7.21.3 | 0..1 | 4863 | grouping | 7.12 | 0..n | 4864 | if-feature | 7.20.2 | 0..n | 4865 | input | 7.14.2 | 0..1 | 4866 | output | 7.14.3 | 0..1 | 4867 | reference | 7.21.4 | 0..1 | 4868 | status | 7.21.2 | 0..1 | 4869 | typedef | 7.3 | 0..n | 4870 +--------------+---------+-------------+ 4872 7.15.2. NETCONF XML Encoding Rules 4874 When an action is invoked, an element with the local name "action" in 4875 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4876 encoded as a child XML element to the element defined in 4877 [RFC6241], as designated by the substitution group "rpcOperation" in 4878 [RFC6241]. 4880 The "action" element contains an hierarchy of nodes that identifies 4881 the node in the datastore. It MUST contain all containers and list 4882 nodes in the direct path from the top level down to the list or 4883 container containing the action. For lists, all key leafs MUST also 4884 be included. The innermost container or list contains an XML element 4885 that carries the name of the defined action. Within this element the 4886 input parameters are encoded as child XML elements, in the same order 4887 as they are defined within the "input" statement. 4889 Only one action can be invoked in one . If more than one action 4890 is present in the , the server MUST reply with an "bad-element" 4891 error-tag in the . 4893 If the action operation invocation succeeded, and no output 4894 parameters are returned, the contains a single 4895 element defined in [RFC6241]. If output parameters are returned, 4896 they are encoded as child elements to the element defined 4897 in [RFC6241], in the same order as they are defined within the 4898 "output" statement. 4900 7.15.3. Usage Example 4902 The following example defines an action to reset one server at a 4903 server farm: 4905 module example-server-farm { 4906 yang-version 1.1; 4907 namespace "urn:example:server-farm"; 4908 prefix "sfarm"; 4910 import ietf-yang-types { 4911 prefix "yang"; 4912 } 4914 list server { 4915 key name; 4916 leaf name { 4917 type string; 4918 } 4919 action reset { 4920 input { 4921 leaf reset-at { 4922 type yang:date-and-time; 4923 mandatory true; 4924 } 4925 } 4926 output { 4927 leaf reset-finished-at { 4928 type yang:date-and-time; 4929 mandatory true; 4930 } 4931 } 4932 } 4933 } 4934 } 4936 A corresponding XML instance example of the complete rpc and rpc- 4937 reply: 4939 4941 4942 4943 apache-1 4944 4945 2014-07-29T13:42:00Z 4946 4947 4948 4949 4951 4953 4954 2014-07-29T13:42:12Z 4955 4956 4958 7.16. The notification Statement 4960 The "notification" statement is used to define a notification. It 4961 takes one argument, which is an identifier, followed by a block of 4962 substatements that holds detailed notification information. The 4963 "notification" statement defines a notification node in the schema 4964 tree. 4966 A notification can be defined at the top-level of a module, or 4967 connected to a specific container or list data node in the schema 4968 tree. 4970 A notification MUST NOT be defined within an rpc, action or another 4971 notification, i.e., a notification node MUST NOT have an rpc, action, 4972 or a notification node as one of its ancestors in the schema tree. 4973 For example, this means that it is an error if a grouping that 4974 contains an notification somewhere in its node hierarchy is used in 4975 an rpc definition. 4977 A notification MUST NOT have any ancestor node that is a list node 4978 without a "key" statement. 4980 Since a notification cannot be defined in a case statement, it is an 4981 error if a grouping that contains a notification at the top of its 4982 node hierarchy is used in a case definition. 4984 If a leaf in the notification tree has a "mandatory" statement with 4985 the value "true", the leaf MUST be present in a notification 4986 instance. 4988 If a leaf in the notification tree has a default value, the client 4989 MUST use this value in the same cases as described in Section 7.6.1. 4990 In these cases, the client MUST operationally behave as if the leaf 4991 was present in the notification instance with the default value as 4992 its value. 4994 If a leaf-list in the notification tree has one or more default 4995 values, the client MUST use these values in the same cases as 4996 described in Section 7.7.2. In these cases, the client MUST 4997 operationally behave as if the leaf-list was present in the 4998 notification instance with the default values as its values. 5000 Since the notification tree is not part of any datastore, all 5001 "config" statements for nodes in the notification tree are ignored. 5003 7.16.1. The notification's Substatements 5005 +--------------+---------+-------------+ 5006 | substatement | section | cardinality | 5007 +--------------+---------+-------------+ 5008 | anydata | 7.10 | 0..n | 5009 | anyxml | 7.11 | 0..n | 5010 | choice | 7.9 | 0..n | 5011 | container | 7.5 | 0..n | 5012 | description | 7.21.3 | 0..1 | 5013 | grouping | 7.12 | 0..n | 5014 | if-feature | 7.20.2 | 0..n | 5015 | leaf | 7.6 | 0..n | 5016 | leaf-list | 7.7 | 0..n | 5017 | list | 7.8 | 0..n | 5018 | must | 7.5.3 | 0..n | 5019 | reference | 7.21.4 | 0..1 | 5020 | status | 7.21.2 | 0..1 | 5021 | typedef | 7.3 | 0..n | 5022 | uses | 7.13 | 0..n | 5023 +--------------+---------+-------------+ 5025 7.16.2. NETCONF XML Encoding Rules 5027 A notification node that is defined on the top-level of a module is 5028 encoded as a child XML element to the element defined 5029 in NETCONF Event Notifications [RFC5277]. The element's local name 5030 is the notification's identifier, and its namespace is the module's 5031 XML namespace (see Section 7.1.3). 5033 When a notification node is defined as a child to a data node, the 5034 element defined in NETCONF Event Notifications 5035 [RFC5277] contains an hierarchy of nodes that identifies the node in 5036 the datastore. It MUST contain all containers and list nodes from 5037 the top level down to the list or container containing the 5038 notification. For lists, all key leafs MUST also be included. The 5039 innermost container or list contains an XML element that carries the 5040 name of the defined notification. 5042 The notification's child nodes are encoded as subelements to the 5043 notification node's XML element, in any order. 5045 7.16.3. Usage Example 5047 The following example defines a notification at the top-level of a 5048 module: 5050 module example-event { 5051 yang-version 1.1; 5052 namespace "urn:example:event"; 5053 prefix "ev"; 5055 notification event { 5056 leaf event-class { 5057 type string; 5058 } 5059 leaf reporting-entity { 5060 type instance-identifier; 5061 } 5062 leaf severity { 5063 type string; 5064 } 5065 } 5066 } 5068 A corresponding XML instance example of the complete notification: 5070 5072 2008-07-08T00:01:00Z 5073 5074 fault 5075 5076 /ex:interface[ex:name='Ethernet0'] 5077 5078 major 5079 5080 5082 The following example defines a notification in a data node: 5084 module example-interface-module { 5085 yang-version 1.1; 5086 namespace "urn:example:interface-module"; 5087 prefix "if"; 5089 container interfaces { 5090 list interface { 5091 key "name"; 5092 leaf name { 5093 type string; 5094 } 5095 notification interface-enabled { 5096 leaf by-user { 5097 type string; 5098 } 5099 } 5100 } 5101 } 5102 } 5104 A corresponding XML instance example of the complete notification: 5106 5108 2008-07-08T00:01:00Z 5109 5110 5111 eth1 5112 5113 fred 5114 5115 5116 5117 5119 7.17. The augment Statement 5121 The "augment" statement allows a module or submodule to add to a 5122 schema tree defined in an external module, or in the current module 5123 and its submodules, and to add to the nodes from a grouping in a 5124 "uses" statement. The argument is a string that identifies a node in 5125 the schema tree. This node is called the augment's target node. The 5126 target node MUST be either a container, list, choice, case, input, 5127 output, or notification node. It is augmented with the nodes defined 5128 in the substatements that follow the "augment" statement. 5130 The argument string is a schema node identifier (see Section 6.5). 5131 If the "augment" statement is on the top level in a module or 5132 submodule, the absolute form (defined by the rule 5133 "absolute-schema-nodeid" in Section 14) of a schema node identifier 5134 MUST be used. If the "augment" statement is a substatement to the 5135 "uses" statement, the descendant form (defined by the rule 5136 "descendant-schema-nodeid" in Section 14) MUST be used. 5138 If the target node is a container, list, case, input, output, or 5139 notification node, the "container", "leaf", "list", "leaf-list", 5140 "uses", and "choice" statements can be used within the "augment" 5141 statement. 5143 If the target node is a container or list node, the "action" and 5144 "notification" statements can be used within the "augment" statement. 5146 If the target node is a choice node, the "case" statement, or a case 5147 shorthand statement (see Section 7.9.2) can be used within the 5148 "augment" statement. 5150 The "augment" statement MUST NOT add multiple nodes with the same 5151 name from the same module to the target node. 5153 If the augmentation adds mandatory nodes (see Section 3) that 5154 represent configuration to a target node in another module, the 5155 augmentation MUST be conditional with a "when" statement. Care must 5156 be taken when defining the "when" expression, so that clients that do 5157 not know about the augmenting module do not break. 5159 In the following example, it is OK to augment the "interface" entry 5160 with "mandatory-leaf" because the augmentation depends on support for 5161 "some-new-iftype". The old client does not know about this type so 5162 it would never select this type, and therefore not be adding a 5163 mandatory data node. 5165 module example-augment { 5166 yang-version 1.1; 5167 namespace "urn:example:augment"; 5168 prefix mymod; 5170 import ietf-interfaces { 5171 prefix if; 5172 } 5174 identity some-new-iftype { 5175 base if:interface-type; 5176 } 5178 augment "/if:interfaces/if:interface" { 5179 when 'derived-from-or-self(if:type, "mymod:some-new-iftype")'; 5181 leaf mandatory-leaf { 5182 mandatory true; 5183 type string; 5184 } 5185 } 5186 } 5188 7.17.1. The augment's Substatements 5190 +--------------+---------+-------------+ 5191 | substatement | section | cardinality | 5192 +--------------+---------+-------------+ 5193 | action | 7.15 | 0..n | 5194 | anydata | 7.10 | 0..n | 5195 | anyxml | 7.11 | 0..n | 5196 | case | 7.9.2 | 0..n | 5197 | choice | 7.9 | 0..n | 5198 | container | 7.5 | 0..n | 5199 | description | 7.21.3 | 0..1 | 5200 | if-feature | 7.20.2 | 0..n | 5201 | leaf | 7.6 | 0..n | 5202 | leaf-list | 7.7 | 0..n | 5203 | list | 7.8 | 0..n | 5204 | notification | 7.16 | 0..n | 5205 | reference | 7.21.4 | 0..1 | 5206 | status | 7.21.2 | 0..1 | 5207 | uses | 7.13 | 0..n | 5208 | when | 7.21.5 | 0..1 | 5209 +--------------+---------+-------------+ 5211 7.17.2. XML Encoding Rules 5213 All data nodes defined in the "augment" statement are defined as XML 5214 elements in the XML namespace of the module where the "augment" is 5215 specified. 5217 When a node is augmented, the augmenting child nodes are encoded as 5218 subelements to the augmented node, in any order. 5220 7.17.3. Usage Example 5222 In namespace urn:example:interface-module, we have: 5224 container interfaces { 5225 list ifEntry { 5226 key "ifIndex"; 5228 leaf ifIndex { 5229 type uint32; 5230 } 5231 leaf ifDescr { 5232 type string; 5233 } 5234 leaf ifType { 5235 type iana:IfType; 5236 } 5237 leaf ifMtu { 5238 type int32; 5239 } 5240 } 5241 } 5243 Then, in namespace urn:example:ds0, we have: 5245 import example-interface-module { 5246 prefix "if"; 5247 } 5248 augment "/if:interfaces/if:ifEntry" { 5249 when "if:ifType='ds0'"; 5250 leaf ds0ChannelNumber { 5251 type ChannelNumber; 5252 } 5253 } 5255 A corresponding XML instance example: 5257 5259 5260 1 5261 Flintstone Inc Ethernet A562 5262 ethernetCsmacd 5263 1500 5264 5265 5266 2 5267 Flintstone Inc DS0 5268 ds0 5269 1 5270 5271 5273 As another example, suppose we have the choice defined in 5274 Section 7.9.6. The following construct can be used to extend the 5275 protocol definition: 5277 augment /ex:system/ex:protocol/ex:name { 5278 case c { 5279 leaf smtp { 5280 type empty; 5281 } 5282 } 5283 } 5285 A corresponding XML instance example: 5287 5288 5289 5290 5291 5293 or 5295 5296 5297 5298 5299 5301 7.18. The identity Statement 5303 The "identity" statement is used to define a new globally unique, 5304 abstract, and untyped identity. The identity's only purpose is to 5305 denote its name, semantics, and existence. An identity can either be 5306 defined from scratch or derived from one or more base identities. 5307 The identity's argument is an identifier that is the name of the 5308 identity. It is followed by a block of substatements that holds 5309 detailed identity information. 5311 The built-in datatype "identityref" (see Section 9.10) can be used to 5312 reference identities within a data model. 5314 7.18.1. The identity's Substatements 5316 +--------------+---------+-------------+ 5317 | substatement | section | cardinality | 5318 +--------------+---------+-------------+ 5319 | base | 7.18.2 | 0..n | 5320 | description | 7.21.3 | 0..1 | 5321 | if-feature | 7.20.2 | 0..n | 5322 | reference | 7.21.4 | 0..1 | 5323 | status | 7.21.2 | 0..1 | 5324 +--------------+---------+-------------+ 5326 7.18.2. The base Statement 5328 The "base" statement, which is optional, takes as an argument a 5329 string that is the name of an existing identity, from which the new 5330 identity is derived. If no "base" statement is present, the identity 5331 is defined from scratch. If multiple "base" statements are present, 5332 the identity is derived from all of them. 5334 If a prefix is present on the base name, it refers to an identity 5335 defined in the module that was imported with that prefix, or the 5336 local module if the prefix matches the local module's prefix. 5337 Otherwise, an identity with the matching name MUST be defined in the 5338 current module or an included submodule. 5340 An identity MUST NOT reference itself, neither directly nor 5341 indirectly through a chain of other identities. 5343 The derivation of identities has the following properties: 5345 o It is irreflexive, which means that an identity is not derived 5346 from itself. 5348 o It is transitive, which means that if identity B is derived from A 5349 and C is derived from B, then C is also derived from A. 5351 7.18.3. Usage Example 5352 module example-crypto-base { 5353 yang-version 1.1; 5354 namespace "urn:example:crypto-base"; 5355 prefix "crypto"; 5357 identity crypto-alg { 5358 description 5359 "Base identity from which all crypto algorithms 5360 are derived."; 5361 } 5363 identity symmetric-key { 5364 description 5365 "Base identity used to identify symmetric-key crypto 5366 algorithms."; 5367 } 5369 identity public-key { 5370 description 5371 "Base identity used to identify public-key crypto 5372 algorithms."; 5373 } 5374 } 5376 module example-des { 5377 yang-version 1.1; 5378 namespace "urn:example:des"; 5379 prefix "des"; 5381 import "example-crypto-base" { 5382 prefix "crypto"; 5383 } 5385 identity des { 5386 base "crypto:crypto-alg"; 5387 base "crypto:symmetric-key"; 5388 description "DES crypto algorithm"; 5389 } 5391 identity des3 { 5392 base "crypto:crypto-alg"; 5393 base "crypto:symmetric-key"; 5394 description "Triple DES crypto algorithm"; 5395 } 5396 } 5398 7.19. The extension Statement 5400 The "extension" statement allows the definition of new statements 5401 within the YANG language. This new statement definition can be 5402 imported and used by other modules. 5404 The "extension" statement's argument is an identifier that is the new 5405 keyword for the extension and must be followed by a block of 5406 substatements that holds detailed extension information. The purpose 5407 of the "extension" statement is to define a keyword, so that it can 5408 be imported and used by other modules. 5410 The extension can be used like a normal YANG statement, with the 5411 statement name followed by an argument if one is defined by the 5412 "extension" statement, and an optional block of substatements. The 5413 statement's name is created by combining the prefix of the module in 5414 which the extension was defined, a colon (":"), and the extension's 5415 keyword, with no interleaving whitespace. The substatements of an 5416 extension are defined by the "extension" statement, using some 5417 mechanism outside the scope of this specification. Syntactically, 5418 the substatements MUST be YANG statements, or also extensions defined 5419 using "extension" statements. YANG statements in extensions MUST 5420 follow the syntactical rules in Section 14. 5422 An extension can allow refinement (see Section 7.13.2) and deviations 5423 (Section 7.20.3.2), but the mechanism for how this is defined is 5424 outside the scope of this specification. 5426 7.19.1. The extension's Substatements 5428 +--------------+---------+-------------+ 5429 | substatement | section | cardinality | 5430 +--------------+---------+-------------+ 5431 | argument | 7.19.2 | 0..1 | 5432 | description | 7.21.3 | 0..1 | 5433 | reference | 7.21.4 | 0..1 | 5434 | status | 7.21.2 | 0..1 | 5435 +--------------+---------+-------------+ 5437 7.19.2. The argument Statement 5439 The "argument" statement, which is optional, takes as an argument a 5440 string that is the name of the argument to the keyword. If no 5441 argument statement is present, the keyword expects no argument when 5442 it is used. 5444 The argument's name is used in the YIN mapping, where it is used as 5445 an XML attribute or element name, depending on the argument's 5446 "yin-element" statement. 5448 7.19.2.1. The argument's Substatements 5450 +--------------+----------+-------------+ 5451 | substatement | section | cardinality | 5452 +--------------+----------+-------------+ 5453 | yin-element | 7.19.2.2 | 0..1 | 5454 +--------------+----------+-------------+ 5456 7.19.2.2. The yin-element Statement 5458 The "yin-element" statement, which is optional, takes as an argument 5459 the string "true" or "false". This statement indicates if the 5460 argument is mapped to an XML element in YIN or to an XML attribute 5461 (see Section 13). 5463 If no "yin-element" statement is present, it defaults to "false". 5465 7.19.3. Usage Example 5467 To define an extension: 5469 module example-extensions { 5470 yang-version 1.1; 5471 ... 5473 extension c-define { 5474 description 5475 "Takes as argument a name string. 5476 Makes the code generator use the given name in the 5477 #define."; 5478 argument "name"; 5479 } 5480 } 5482 To use the extension: 5484 module example-interfaces { 5485 yang-version 1.1; 5487 ... 5488 import example-extensions { 5489 prefix "myext"; 5490 } 5491 ... 5493 container interfaces { 5494 ... 5495 myext:c-define "MY_INTERFACES"; 5496 } 5497 } 5499 7.20. Conformance-Related Statements 5501 This section defines statements related to conformance, as described 5502 in Section 5.6. 5504 7.20.1. The feature Statement 5506 The "feature" statement is used to define a mechanism by which 5507 portions of the schema are marked as conditional. A feature name is 5508 defined that can later be referenced using the "if-feature" statement 5509 (see Section 7.20.2). Schema nodes tagged with an "if-feature" 5510 statement are ignored by the server unless the server supports the 5511 given feature expression. This allows portions of the YANG module to 5512 be conditional based on conditions in the server. The model can 5513 represent the abilities of the server within the model, giving a 5514 richer model that allows for differing server abilities and roles. 5516 The argument to the "feature" statement is the name of the new 5517 feature, and follows the rules for identifiers in Section 6.2. This 5518 name is used by the "if-feature" statement to tie the schema nodes to 5519 the feature. 5521 In this example, a feature called "local-storage" represents the 5522 ability for a server to store syslog messages on local storage of 5523 some sort. This feature is used to make the "local-storage-limit" 5524 leaf conditional on the presence of some sort of local storage. If 5525 the server does not report that it supports this feature, the 5526 "local-storage-limit" node is not supported. 5528 module example-syslog { 5529 yang-version 1.1; 5531 ... 5532 feature local-storage { 5533 description 5534 "This feature means the server supports local 5535 storage (memory, flash or disk) that can be used to 5536 store syslog messages."; 5537 } 5539 container syslog { 5540 leaf local-storage-limit { 5541 if-feature local-storage; 5542 type uint64; 5543 units "kilobyte"; 5544 config false; 5545 description 5546 "The amount of local storage that can be 5547 used to hold syslog messages."; 5548 } 5549 } 5550 } 5552 The "if-feature" statement can be used in many places within the YANG 5553 syntax. Definitions tagged with "if-feature" are ignored when the 5554 server does not support that feature. 5556 A feature MUST NOT reference itself, neither directly nor indirectly 5557 through a chain of other features. 5559 In order for a server to support a feature that is dependent on any 5560 other features (i.e., the feature has one or more "if-feature" 5561 substatements), the server MUST also support all the dependant 5562 features. 5564 7.20.1.1. The feature's Substatements 5566 +--------------+---------+-------------+ 5567 | substatement | section | cardinality | 5568 +--------------+---------+-------------+ 5569 | description | 7.21.3 | 0..1 | 5570 | if-feature | 7.20.2 | 0..n | 5571 | status | 7.21.2 | 0..1 | 5572 | reference | 7.21.4 | 0..1 | 5573 +--------------+---------+-------------+ 5575 7.20.2. The if-feature Statement 5577 The "if-feature" statement makes its parent statement conditional. 5578 The argument is a boolean expression over feature names. In this 5579 expression, a feature name evaluates to "true" if and only if the 5580 feature is supported by the server. The parent statement is 5581 implemented by servers where the boolean expression evaluates to 5582 "true". 5584 The if-feature boolean expression syntax is formally defined by the 5585 rule "if-feature-expr" in Section 14. Parenthesis are used to group 5586 expressions. When the expression is evaluated, the order of 5587 precedence is (highest precedence first): grouping (parenthesis), 5588 "not", "and", "or". 5590 If a prefix is present on a feature name in the boolean expression, 5591 the prefixed name refers to a feature defined in the module that was 5592 imported with that prefix, or the local module if the prefix matches 5593 the local module's prefix. Otherwise, a feature with the matching 5594 name MUST be defined in the current module or an included submodule. 5596 A leaf that is a list key MUST NOT have any "if-feature" statements. 5598 7.20.2.1. Usage Example 5600 In this example, the container "target" is implemented if either of 5601 the features "outbound-tls" or "outbound-ssh" are supported by the 5602 server. 5604 container target { 5605 if-feature "outbound-tls or outbound-ssh"; 5606 ... 5607 } 5609 The following examples are equivalent: 5611 if-feature "not foo or bar and baz"; 5613 if-feature "(not foo) or (bar and baz)"; 5615 7.20.3. The deviation Statement 5617 The "deviation" statement defines a hierarchy of a module that the 5618 server does not implement faithfully. The argument is a string that 5619 identifies the node in the schema tree where a deviation from the 5620 module occurs. This node is called the deviation's target node. The 5621 contents of the "deviation" statement give details about the 5622 deviation. 5624 The argument string is an absolute schema node identifier (see 5625 Section 6.5). 5627 Deviations define the way a server or class of servers deviate from a 5628 standard. This means that deviations MUST never be part of a 5629 published standard, since they are the mechanism for learning how 5630 implementations vary from the standards. 5632 Server deviations are strongly discouraged and MUST only be used as a 5633 last resort. Telling the application how a server fails to follow a 5634 standard is no substitute for implementing the standard correctly. A 5635 server that deviates from a module is not fully compliant with the 5636 module. 5638 However, in some cases, a particular device may not have the hardware 5639 or software ability to support parts of a standard module. When this 5640 occurs, the server makes a choice either to treat attempts to 5641 configure unsupported parts of the module as an error that is 5642 reported back to the unsuspecting application or ignore those 5643 incoming requests. Neither choice is acceptable. 5645 Instead, YANG allows servers to document portions of a base module 5646 that are not supported or supported but with different syntax, by 5647 using the "deviation" statement. 5649 After applying all deviations announced by a server, in any order, 5650 the resulting data model MUST still be valid. 5652 7.20.3.1. The deviation's Substatements 5654 +--------------+----------+-------------+ 5655 | substatement | section | cardinality | 5656 +--------------+----------+-------------+ 5657 | description | 7.21.3 | 0..1 | 5658 | deviate | 7.20.3.2 | 1..n | 5659 | reference | 7.21.4 | 0..1 | 5660 +--------------+----------+-------------+ 5662 7.20.3.2. The deviate Statement 5664 The "deviate" statement defines how the server's implementation of 5665 the target node deviates from its original definition. The argument 5666 is one of the strings "not-supported", "add", "replace", or "delete". 5668 The argument "not-supported" indicates that the target node is not 5669 implemented by this server. 5671 The argument "add" adds properties to the target node. The 5672 properties to add are identified by substatements to the "deviate" 5673 statement. If a property can only appear once, the property MUST NOT 5674 exist in the target node. 5676 The argument "replace" replaces properties of the target node. The 5677 properties to replace are identified by substatements to the 5678 "deviate" statement. The properties to replace MUST exist in the 5679 target node. 5681 The argument "delete" deletes properties from the target node. The 5682 properties to delete are identified by substatements to the "delete" 5683 statement. The substatement's keyword MUST match a corresponding 5684 keyword in the target node, and the argument's string MUST be equal 5685 to the corresponding keyword's argument string in the target node. 5687 +--------------+-------------+-------------+ 5688 | substatement | section | cardinality | 5689 +--------------+-------------+-------------+ 5690 | config | 7.21.1 | 0..1 | 5691 | default | 7.6.4 7.7.4 | 0..n | 5692 | mandatory | 7.6.5 | 0..1 | 5693 | max-elements | 7.7.6 | 0..1 | 5694 | min-elements | 7.7.5 | 0..1 | 5695 | must | 7.5.3 | 0..n | 5696 | type | 7.4 | 0..1 | 5697 | unique | 7.8.3 | 0..n | 5698 | units | 7.3.3 | 0..1 | 5699 +--------------+-------------+-------------+ 5701 The deviate's Substatements 5703 If the target node has a property defined by an extension, this 5704 property can be deviated if the extension allows deviations. See 5705 Section 7.19 for details. 5707 7.20.3.3. Usage Example 5709 In this example, the server is informing client applications that it 5710 does not support the "daytime" service in the style of RFC 867. 5712 module example-deviations { 5713 yang-version 1.1; 5714 namespace "urn:example:deviations"; 5715 prefix md; 5717 import example-base { 5718 prefix base; 5719 } 5721 deviation /base:system/base:daytime { 5722 deviate not-supported; 5723 } 5724 ... 5725 } 5727 A server would advertise both modules "example-base" and 5728 "example-deviations". 5730 The following example sets a server-specific default value to a leaf 5731 that does not have a default value defined: 5733 deviation /base:system/base:user/base:type { 5734 deviate add { 5735 default "admin"; // new users are 'admin' by default 5736 } 5737 } 5739 In this example, the server limits the number of name servers to 3: 5741 deviation /base:system/base:name-server { 5742 deviate replace { 5743 max-elements 3; 5744 } 5745 } 5747 If the original definition is: 5749 container system { 5750 must "daytime or time"; 5751 ... 5752 } 5754 a server might remove this must constraint by doing: 5756 deviation /base:system { 5757 deviate delete { 5758 must "daytime or time"; 5759 } 5760 } 5762 7.21. Common Statements 5764 This section defines substatements common to several other 5765 statements. 5767 7.21.1. The config Statement 5769 The "config" statement takes as an argument the string "true" or 5770 "false". If "config" is "true", the definition represents 5771 configuration. Data nodes representing configuration are part of 5772 configuration datastores. 5774 If "config" is "false", the definition represents state data. Data 5775 nodes representing state data are not part of configuration 5776 datastores. 5778 If "config" is not specified, the default is the same as the parent 5779 schema node's "config" value. If the parent node is a "case" node, 5780 the value is the same as the "case" node's parent "choice" node. 5782 If the top node does not specify a "config" statement, the default is 5783 "true". 5785 If a node has "config" set to "false", no node underneath it can have 5786 "config" set to "true". 5788 7.21.2. The status Statement 5790 The "status" statement takes as an argument one of the strings 5791 "current", "deprecated", or "obsolete". 5793 o "current" means that the definition is current and valid. 5795 o "deprecated" indicates an obsolete definition, but it permits new/ 5796 continued implementation in order to foster interoperability with 5797 older/existing implementations. 5799 o "obsolete" means the definition is obsolete and SHOULD NOT be 5800 implemented and/or can be removed from implementations. 5802 If no status is specified, the default is "current". 5804 If a definition is "current", it MUST NOT reference a "deprecated" or 5805 "obsolete" definition within the same module. 5807 If a definition is "deprecated", it MUST NOT reference an "obsolete" 5808 definition within the same module. 5810 For example, the following is illegal: 5812 typedef my-type { 5813 status deprecated; 5814 type int32; 5815 } 5817 leaf my-leaf { 5818 status current; 5819 type my-type; // illegal, since my-type is deprecated 5820 } 5822 7.21.3. The description Statement 5824 The "description" statement takes as an argument a string that 5825 contains a human-readable textual description of this definition. 5826 The text is provided in a language (or languages) chosen by the 5827 module developer; for the sake of interoperability, it is RECOMMENDED 5828 to choose a language that is widely understood among the community of 5829 network administrators who will use the module. 5831 7.21.4. The reference Statement 5833 The "reference" statement takes as an argument a string that is a 5834 human-readable cross-reference to an external document, either 5835 another module that defines related management information, or a 5836 document that provides additional information relevant to this 5837 definition. 5839 For example, a typedef for a "uri" data type could look like: 5841 typedef uri { 5842 type string; 5843 reference 5844 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5845 ... 5846 } 5848 7.21.5. The when Statement 5850 The "when" statement makes its parent data definition statement 5851 conditional. The node defined by the parent data definition 5852 statement is only valid when the condition specified by the "when" 5853 statement is satisfied. The statement's argument is an XPath 5854 expression (see Section 6.4), which is used to formally specify this 5855 condition. If the XPath expression conceptually evaluates to "true" 5856 for a particular instance, then the node defined by the parent data 5857 definition statement is valid; otherwise, it is not. 5859 A leaf that is a list key MUST NOT have a "when" statement. 5861 If a leaf key is defined in a grouping that is used in a list, the 5862 "uses" statement MUST NOT have a "when" statement. 5864 See Section 8.3.2 for additional information. 5866 The XPath expression is conceptually evaluated in the following 5867 context, in addition to the definition in Section 6.4.1: 5869 o If the "when" statement is a child of an "augment" statement, then 5870 the context node is the augment's target node in the data tree, if 5871 the target node is a data node. Otherwise, the context node is 5872 the closest ancestor node to the target node that is also a data 5873 node. If no such node exists, the context node is the root node. 5874 The accessible tree is tentatively altered during the processing 5875 of the XPath expression by removing all instances (if any) of the 5876 nodes added by the "augment" statement. 5878 o If the "when" statement is a child of a "uses", "choice", or 5879 "case" statement, then the context node is the closest ancestor 5880 node to the "uses", "choice", or "case" node that is also a data 5881 node. If no such node exists, the context node is the root node. 5882 The accessible tree is tentatively altered during the processing 5883 of the XPath expression by removing all instances (if any) of the 5884 nodes added by the "uses", "choice", or "case" statement. 5886 o If the "when" statement is a child of any other data definition 5887 statement, the accessible tree is tentatively altered during the 5888 processing of the XPath expression by replacing all instances of 5889 the data node for which the "when" statement is defined with a 5890 single dummy node with the same name, but with no value and no 5891 children. If no such instance exists, the dummy node is 5892 tentatively created. The context node is this dummy node. 5894 The result of the XPath expression is converted to a boolean value 5895 using the standard XPath rules. 5897 If the XPath expression references any node that also has associated 5898 "when" statements, those "when" expressions MUST be evaluated first. 5899 There MUST NOT be any circular dependencies among "when" expressions. 5901 Note that the XPath expression is conceptually evaluated. This means 5902 that an implementation does not have to use an XPath evaluator in the 5903 server. The "when" statement can very well be implemented with 5904 specially written code. 5906 8. Constraints 5908 8.1. Constraints on Data 5910 Several YANG statements define constraints on valid data. These 5911 constraints are enforced in different ways, depending on what type of 5912 data the statement defines. 5914 o If the constraint is defined on configuration data, it MUST be 5915 true in a valid configuration data tree. 5917 o If the constraint is defined on state data, it MUST be true in a 5918 valid state data tree. 5920 o If the constraint is defined on notification content, it MUST be 5921 true in any notification data tree. 5923 o If the constraint is defined on RPC or action input parameters, it 5924 MUST be true in an invocation of the RPC or action operation. 5926 o If the constraint is defined on RPC or action output parameters, 5927 it MUST be true in the RPC or action reply. 5929 The following properties are true in all data trees: 5931 o All leaf data values MUST match the type constraints for the leaf, 5932 including those defined in the type's "range", "length", and 5933 "pattern" properties. 5935 o All key leafs MUST be present for all list entries. 5937 o Nodes MUST be present for at most one case branch in all choices. 5939 o There MUST be no nodes tagged with "if-feature" present if the 5940 "if-feature" expression evaluates to "false" in the server. 5942 o There MUST be no nodes tagged with "when" present if the "when" 5943 condition evaluates to "false" in the data tree. 5945 The following properties are true in a valid data tree: 5947 o All "must" constraints MUST evaluate to "true". 5949 o All referential integrity constraints defined via the "path" 5950 statement MUST be satisfied. 5952 o All "unique" constraints on lists MUST be satisfied. 5954 o The "mandatory" constraint is enforced for leafs and choices, 5955 unless the node or any of its ancestors has a "when" condition or 5956 "if-feature" expression that evaluates to "false". 5958 o The "min-elements" and "max-elements" constraints are enforced for 5959 lists and leaf-lists, unless the node or any of its ancestors has 5960 a "when" condition or "if-feature" expression that evaluates to 5961 "false". 5963 The running configuration datastore MUST always be valid. 5965 8.2. Configuration Data Modifications 5967 o If a request creates configuration data nodes under a "choice", 5968 any existing nodes from other "case" branches in the data tree are 5969 deleted by the server. 5971 o If a request modifies a configuration data node such that any 5972 node's "when" expression becomes false, then the node in the data 5973 tree with the "when" expression is deleted by the server. 5975 8.3. NETCONF Constraint Enforcement Model 5977 For configuration data, there are three windows when constraints MUST 5978 be enforced: 5980 o during parsing of RPC payloads 5982 o during processing of the operation 5984 o during validation 5986 Each of these scenarios is considered in the following sections. 5988 8.3.1. Payload Parsing 5990 When content arrives in RPC payloads, it MUST be well-formed XML, 5991 following the hierarchy and content rules defined by the set of 5992 models the server implements. 5994 o If a leaf data value does not match the type constraints for the 5995 leaf, including those defined in the type's "range", "length", and 5996 "pattern" properties, the server MUST reply with an 5997 "invalid-value" error-tag in the rpc-error, and with the error- 5998 app-tag and error-message associated with the constraint, if any 5999 exist. 6001 o If all keys of a list entry are not present, the server MUST reply 6002 with a "missing-element" error-tag in the rpc-error. 6004 o If data for more than one case branch of a choice is present, the 6005 server MUST reply with a "bad-element" in the rpc-error. 6007 o If data for a node tagged with "if-feature" is present, and the 6008 if-feature expression evaluates to "false" in the server, the 6009 server MUST reply with an "unknown-element" error-tag in the rpc- 6010 error. 6012 o If data for a node tagged with "when" is present, and the "when" 6013 condition evaluates to "false", the server MUST reply with an 6014 "unknown-element" error-tag in the rpc-error. 6016 o For insert handling, if the value for the attributes "before" and 6017 "after" are not valid for the type of the appropriate key leafs, 6018 the server MUST reply with a "bad-attribute" error-tag in the rpc- 6019 error. 6021 o If the attributes "before" and "after" appears in any element that 6022 is not a list whose "ordered-by" property is "user", the server 6023 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 6025 8.3.2. NETCONF Processing 6027 After the incoming data is parsed, the NETCONF server performs the 6028 operation by applying the data to the configuration 6029 datastore. During this processing, the following errors MUST be 6030 detected: 6032 o Delete requests for non-existent data. 6034 o Create requests for existent data. 6036 o Insert requests with "before" or "after" parameters that do not 6037 exist. 6039 o Modification requests for nodes tagged with "when", and the "when" 6040 condition evaluates to "false". In this case the server MUST 6041 reply with an "unknown-element" error-tag in the rpc-error. 6043 8.3.3. Validation 6045 When datastore processing is complete, the final contents MUST obey 6046 all validation constraints. This validation processing is performed 6047 at differing times according to the datastore. If the datastore is 6048 "running" or "startup", these constraints MUST be enforced at the end 6049 of the or operation. If the datastore is 6050 "candidate", the constraint enforcement is delayed until a 6051 or operation. 6053 9. Built-In Types 6055 YANG has a set of built-in types, similar to those of many 6056 programming languages, but with some differences due to special 6057 requirements from the management information model. 6059 Additional types may be defined, derived from those built-in types or 6060 from other derived types. Derived types may use subtyping to 6061 formally restrict the set of possible values. 6063 The different built-in types and their derived types allow different 6064 kinds of subtyping, namely length and regular expression restrictions 6065 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 6066 numeric types (Section 9.2.4). 6068 The lexical representation of a value of a certain type is used in 6069 the XML encoding and when specifying default values and numerical 6070 ranges in YANG modules. 6072 9.1. Canonical Representation 6074 For most types, there is a single canonical representation of the 6075 type's values. Some types allow multiple lexical representations of 6076 the same value, for example, the positive integer "17" can be 6077 represented as "+17" or "17". Implementations MUST support all 6078 lexical representations specified in this document. 6080 When a server sends XML encoded data, it MUST use the canonical form 6081 defined in this section. Other encodings may introduce alternate 6082 representations. Note, however, that values in the data tree are 6083 conceptually stored in the canonical representation as defined in 6084 this section. In particular, any XPath expression evaluations are 6085 done using the canonical form, if the data type has a canonical form. 6086 If the data type does not have a canonical form, the format of the 6087 value MUST match the data type's lexical representation, but the 6088 exact format is implementation dependent. 6090 Some types have a lexical representation that depends on the 6091 encoding, e.g., the XML context in which they occur. These types do 6092 not have a canonical form. 6094 9.2. The Integer Built-In Types 6096 The integer built-in types are int8, int16, int32, int64, uint8, 6097 uint16, uint32, and uint64. They represent signed and unsigned 6098 integers of different sizes: 6100 int8 represents integer values between -128 and 127, inclusively. 6102 int16 represents integer values between -32768 and 32767, 6103 inclusively. 6105 int32 represents integer values between -2147483648 and 2147483647, 6106 inclusively. 6108 int64 represents integer values between -9223372036854775808 and 6109 9223372036854775807, inclusively. 6111 uint8 represents integer values between 0 and 255, inclusively. 6113 uint16 represents integer values between 0 and 65535, inclusively. 6115 uint32 represents integer values between 0 and 4294967295, 6116 inclusively. 6118 uint64 represents integer values between 0 and 18446744073709551615, 6119 inclusively. 6121 9.2.1. Lexical Representation 6123 An integer value is lexically represented as an optional sign ("+" or 6124 "-"), followed by a sequence of decimal digits. If no sign is 6125 specified, "+" is assumed. 6127 For convenience, when specifying a default value for an integer in a 6128 YANG module, an alternative lexical representation can be used, which 6129 represents the value in a hexadecimal or octal notation. The 6130 hexadecimal notation consists of an optional sign ("+" or "-"), the 6131 characters "0x" followed a number of hexadecimal digits, where 6132 letters may be uppercase or lowercase. The octal notation consists 6133 of an optional sign ("+" or "-"), the character "0" followed a number 6134 of octal digits. 6136 Note that if a default value in a YANG module has a leading zero 6137 ("0"), it is interpreted as an octal number. In the XML encoding, an 6138 integer is always interpreted as a decimal number, and leading zeros 6139 are allowed. 6141 Examples: 6143 // legal values 6144 +4711 // legal positive value 6145 4711 // legal positive value 6146 -123 // legal negative value 6147 0xf00f // legal positive hexadecimal value 6148 -0xf // legal negative hexadecimal value 6149 052 // legal positive octal value 6151 // illegal values 6152 - 1 // illegal intermediate space 6154 9.2.2. Canonical Form 6156 The canonical form of a positive integer does not include the sign 6157 "+". Leading zeros are prohibited. The value zero is represented as 6158 "0". 6160 9.2.3. Restrictions 6162 All integer types can be restricted with the "range" statement 6163 (Section 9.2.4). 6165 9.2.4. The range Statement 6167 The "range" statement, which is an optional substatement to the 6168 "type" statement, takes as an argument a range expression string. It 6169 is used to restrict integer and decimal built-in types, or types 6170 derived from those. 6172 A range consists of an explicit value, or a lower-inclusive bound, 6173 two consecutive dots "..", and an upper-inclusive bound. Multiple 6174 values or ranges can be given, separated by "|". If multiple values 6175 or ranges are given, they all MUST be disjoint and MUST be in 6176 ascending order. If a range restriction is applied to an already 6177 range-restricted type, the new restriction MUST be equal or more 6178 limiting, that is raising the lower bounds, reducing the upper 6179 bounds, removing explicit values or ranges, or splitting ranges into 6180 multiple ranges with intermediate gaps. Each explicit value and 6181 range boundary value given in the range expression MUST match the 6182 type being restricted, or be one of the special values "min" or 6183 "max". "min" and "max" mean the minimum and maximum value accepted 6184 for the type being restricted, respectively. 6186 The range expression syntax is formally defined by the rule 6187 "range-arg" in Section 14. 6189 9.2.4.1. The range's Substatements 6191 +---------------+---------+-------------+ 6192 | substatement | section | cardinality | 6193 +---------------+---------+-------------+ 6194 | description | 7.21.3 | 0..1 | 6195 | error-app-tag | 7.5.4.2 | 0..1 | 6196 | error-message | 7.5.4.1 | 0..1 | 6197 | reference | 7.21.4 | 0..1 | 6198 +---------------+---------+-------------+ 6200 9.2.5. Usage Example 6202 typedef my-base-int32-type { 6203 type int32 { 6204 range "1..4 | 10..20"; 6205 } 6206 } 6208 typedef my-type1 { 6209 type my-base-int32-type { 6210 // legal range restriction 6211 range "11..max"; // 11..20 6212 } 6213 } 6215 typedef my-type2 { 6216 type my-base-int32-type { 6217 // illegal range restriction 6218 range "11..100"; 6219 } 6220 } 6222 9.3. The decimal64 Built-In Type 6224 The decimal64 type represents a subset of the real numbers, which can 6225 be represented by decimal numerals. The value space of decimal64 is 6226 the set of numbers that can be obtained by multiplying a 64-bit 6227 signed integer by a negative power of ten, i.e., expressible as "i x 6228 10^-n" where i is an integer64 and n is an integer between 1 and 18, 6229 inclusively. 6231 9.3.1. Lexical Representation 6233 A decimal64 value is lexically represented as an optional sign ("+" 6234 or "-"), followed by a sequence of decimal digits, optionally 6235 followed by a period ('.') as a decimal indicator and a sequence of 6236 decimal digits. If no sign is specified, "+" is assumed. 6238 9.3.2. Canonical Form 6240 The canonical form of a positive decimal64 does not include the sign 6241 "+". The decimal point is required. Leading and trailing zeros are 6242 prohibited, subject to the rule that there MUST be at least one digit 6243 before and after the decimal point. The value zero is represented as 6244 "0.0". 6246 9.3.3. Restrictions 6248 A decimal64 type can be restricted with the "range" statement 6249 (Section 9.2.4). 6251 9.3.4. The fraction-digits Statement 6253 The "fraction-digits" statement, which is a substatement to the 6254 "type" statement, MUST be present if the type is "decimal64". It 6255 takes as an argument an integer between 1 and 18, inclusively. It 6256 controls the size of the minimum difference between values of a 6257 decimal64 type, by restricting the value space to numbers that are 6258 expressible as "i x 10^-n" where n is the fraction-digits argument. 6260 The following table lists the minimum and maximum value for each 6261 fraction-digit value: 6263 +----------------+-----------------------+----------------------+ 6264 | fraction-digit | min | max | 6265 +----------------+-----------------------+----------------------+ 6266 | 1 | -922337203685477580.8 | 922337203685477580.7 | 6267 | 2 | -92233720368547758.08 | 92233720368547758.07 | 6268 | 3 | -9223372036854775.808 | 9223372036854775.807 | 6269 | 4 | -922337203685477.5808 | 922337203685477.5807 | 6270 | 5 | -92233720368547.75808 | 92233720368547.75807 | 6271 | 6 | -9223372036854.775808 | 9223372036854.775807 | 6272 | 7 | -922337203685.4775808 | 922337203685.4775807 | 6273 | 8 | -92233720368.54775808 | 92233720368.54775807 | 6274 | 9 | -9223372036.854775808 | 9223372036.854775807 | 6275 | 10 | -922337203.6854775808 | 922337203.6854775807 | 6276 | 11 | -92233720.36854775808 | 92233720.36854775807 | 6277 | 12 | -9223372.036854775808 | 9223372.036854775807 | 6278 | 13 | -922337.2036854775808 | 922337.2036854775807 | 6279 | 14 | -92233.72036854775808 | 92233.72036854775807 | 6280 | 15 | -9223.372036854775808 | 9223.372036854775807 | 6281 | 16 | -922.3372036854775808 | 922.3372036854775807 | 6282 | 17 | -92.23372036854775808 | 92.23372036854775807 | 6283 | 18 | -9.223372036854775808 | 9.223372036854775807 | 6284 +----------------+-----------------------+----------------------+ 6286 9.3.5. Usage Example 6288 typedef my-decimal { 6289 type decimal64 { 6290 fraction-digits 2; 6291 range "1 .. 3.14 | 10 | 20..max"; 6292 } 6293 } 6295 9.4. The string Built-In Type 6297 The string built-in type represents human-readable strings in YANG. 6298 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 6299 characters, including tab, carriage return, and line feed but 6300 excluding the other C0 control characters, the surrogate blocks, and 6301 the noncharacters. The string syntax is formally defined by the rule 6302 "yang-string" in Section 14. 6304 9.4.1. Lexical Representation 6306 A string value is lexically represented as character data in the XML 6307 encoding. 6309 9.4.2. Canonical Form 6311 The canonical form is the same as the lexical representation. No 6312 Unicode normalization is performed of string values. 6314 9.4.3. Restrictions 6316 A string can be restricted with the "length" (Section 9.4.4) and 6317 "pattern" (Section 9.4.5) statements. 6319 9.4.4. The length Statement 6321 The "length" statement, which is an optional substatement to the 6322 "type" statement, takes as an argument a length expression string. 6323 It is used to restrict the built-in types "string" and "binary" or 6324 types derived from them. 6326 A "length" statement restricts the number of Unicode characters in 6327 the string. 6329 A length range consists of an explicit value, or a lower bound, two 6330 consecutive dots "..", and an upper bound. Multiple values or ranges 6331 can be given, separated by "|". Length-restricting values MUST NOT 6332 be negative. If multiple values or ranges are given, they all MUST 6333 be disjoint and MUST be in ascending order. If a length restriction 6334 is applied to an already length-restricted type, the new restriction 6335 MUST be equal or more limiting, that is, raising the lower bounds, 6336 reducing the upper bounds, removing explicit length values or ranges, 6337 or splitting ranges into multiple ranges with intermediate gaps. A 6338 length value is a non-negative integer, or one of the special values 6339 "min" or "max". "min" and "max" mean the minimum and maximum length 6340 accepted for the type being restricted, respectively. An 6341 implementation is not required to support a length value larger than 6342 18446744073709551615. 6344 The length expression syntax is formally defined by the rule 6345 "length-arg" in Section 14. 6347 9.4.4.1. The length's Substatements 6349 +---------------+---------+-------------+ 6350 | substatement | section | cardinality | 6351 +---------------+---------+-------------+ 6352 | description | 7.21.3 | 0..1 | 6353 | error-app-tag | 7.5.4.2 | 0..1 | 6354 | error-message | 7.5.4.1 | 0..1 | 6355 | reference | 7.21.4 | 0..1 | 6356 +---------------+---------+-------------+ 6358 9.4.5. The pattern Statement 6360 The "pattern" statement, which is an optional substatement to the 6361 "type" statement, takes as an argument a regular expression string, 6362 as defined in [XSD-TYPES]. It is used to restrict the built-in type 6363 "string", or types derived from "string", to values that match the 6364 pattern. 6366 If the type has multiple "pattern" statements, the expressions are 6367 ANDed together, i.e., all such expressions have to match. 6369 If a pattern restriction is applied to an already pattern-restricted 6370 type, values must match all patterns in the base type, in addition to 6371 the new patterns. 6373 9.4.5.1. The pattern's Substatements 6375 +---------------+---------+-------------+ 6376 | substatement | section | cardinality | 6377 +---------------+---------+-------------+ 6378 | description | 7.21.3 | 0..1 | 6379 | error-app-tag | 7.5.4.2 | 0..1 | 6380 | error-message | 7.5.4.1 | 0..1 | 6381 | modifier | 9.4.6 | 0..1 | 6382 | reference | 7.21.4 | 0..1 | 6383 +---------------+---------+-------------+ 6385 9.4.6. The modifier Statement 6387 The "modifier" statement, which is an optional substatement to the 6388 "pattern" statement, takes as an argument the string "invert-match". 6390 If a pattern has the "invert-match" modifier present, the type is 6391 restricted to values that do not match the pattern. 6393 9.4.7. Usage Example 6395 With the following typedef: 6397 typedef my-base-str-type { 6398 type string { 6399 length "1..255"; 6400 } 6401 } 6403 the following refinement is legal: 6405 type my-base-str-type { 6406 // legal length refinement 6407 length "11 | 42..max"; // 11 | 42..255 6408 } 6410 and the following refinement is illegal: 6412 type my-base-str-type { 6413 // illegal length refinement 6414 length "1..999"; 6415 } 6417 With the following type: 6419 type string { 6420 length "0..4"; 6421 pattern "[0-9a-fA-F]*"; 6422 } 6424 the following strings match: 6426 AB // legal 6427 9A00 // legal 6429 and the following strings do not match: 6431 00ABAB // illegal, too long 6432 xx00 // illegal, bad characters 6434 With the following type: 6436 typedef yang-identifier { 6437 type string { 6438 length "1..max"; 6439 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 6440 pattern '[xX][mM][lL].*' { 6441 modifier invert-match; 6442 } 6443 } 6444 } 6446 the following string match: 6448 enabled // legal 6450 and the following strings do not match: 6452 10-mbit // illegal, starts with a number 6453 xml-element // illegal, starts with illegal sequence 6455 9.5. The boolean Built-In Type 6457 The boolean built-in type represents a boolean value. 6459 9.5.1. Lexical Representation 6461 The lexical representation of a boolean value is a string with a 6462 value of "true" or "false". These values MUST be in lowercase. 6464 9.5.2. Canonical Form 6466 The canonical form is the same as the lexical representation. 6468 9.5.3. Restrictions 6470 A boolean cannot be restricted. 6472 9.6. The enumeration Built-In Type 6474 The enumeration built-in type represents values from a set of 6475 assigned names. 6477 9.6.1. Lexical Representation 6479 The lexical representation of an enumeration value is the assigned 6480 name string. 6482 9.6.2. Canonical Form 6484 The canonical form is the assigned name string. 6486 9.6.3. Restrictions 6488 An enumeration can be restricted with one or more "enum" 6489 (Section 9.6.4) statements, which enumerate a subset of the values 6490 for the base type. 6492 9.6.4. The enum Statement 6494 The "enum" statement, which is a substatement to the "type" 6495 statement, MUST be present if the type is "enumeration". It is 6496 repeatedly used to specify each assigned name of an enumeration type. 6497 It takes as an argument a string which is the assigned name. The 6498 string MUST NOT be zero-length and MUST NOT have any leading or 6499 trailing whitespace characters (any Unicode character with the 6500 "White_Space" property). The use of Unicode control codes SHOULD be 6501 avoided. 6503 The statement is optionally followed by a block of substatements that 6504 holds detailed enum information. 6506 All assigned names in an enumeration MUST be unique. 6508 When an existing enumeration type is restricted, the set of assigned 6509 names in the new type MUST be a subset of the base type's set of 6510 assigned names. The value of such an assigned name MUST NOT be 6511 changed. 6513 9.6.4.1. The enum's Substatements 6515 +--------------+---------+-------------+ 6516 | substatement | section | cardinality | 6517 +--------------+---------+-------------+ 6518 | description | 7.21.3 | 0..1 | 6519 | if-feature | 7.20.2 | 0..n | 6520 | reference | 7.21.4 | 0..1 | 6521 | status | 7.21.2 | 0..1 | 6522 | value | 9.6.4.2 | 0..1 | 6523 +--------------+---------+-------------+ 6525 9.6.4.2. The value Statement 6527 The "value" statement, which is optional, is used to associate an 6528 integer value with the assigned name for the enum. This integer 6529 value MUST be in the range -2147483648 to 2147483647, and it MUST be 6530 unique within the enumeration type. 6532 If a value is not specified, then one will be automatically assigned. 6533 If the "enum" substatement is the first one defined, the assigned 6534 value is zero (0); otherwise, the assigned value is one greater than 6535 the current highest enum value (i.e., the highest enum value, 6536 implicit or explicit, prior to the current "enum" substatement in the 6537 parent "type" statement). 6539 Note that the the presence of an "if-feature" statement in an "enum" 6540 statement does not affect the automatically assigned value. 6542 If the current highest value is equal to 2147483647, then an enum 6543 value MUST be specified for "enum" substatements following the one 6544 with the current highest value. 6546 When an existing enumeration type is restricted, the "value" 6547 statement MUST either have the same value as in the base type or not 6548 be present, in which case the value is the same as in the base type. 6550 9.6.5. Usage Example 6552 leaf myenum { 6553 type enumeration { 6554 enum zero; 6555 enum one; 6556 enum seven { 6557 value 7; 6558 } 6559 } 6560 } 6562 The lexical representation of the leaf "myenum" with value "seven" 6563 is: 6565 seven 6567 With the following typedef: 6569 typedef my-base-enumeration-type { 6570 type enumeration { 6571 enum white { 6572 value 1; 6573 } 6574 enum yellow { 6575 value 2; 6576 } 6577 enum red { 6578 value 3; 6579 } 6580 } 6581 } 6583 the following refinement is legal: 6585 type my-base-enumeration-type { 6586 // legal enum refinement 6587 enum yellow; 6588 enum red { 6589 value 3; 6590 } 6591 } 6593 and the following refinement is illegal: 6595 type my-base-enumeration-type { 6596 // illegal enum refinement 6597 enum yellow { 6598 value 4; // illegal value change 6599 } 6600 enum black; // illegal addition of new name 6601 } 6603 The following example shows how an "enum" can be tagged with 6604 "if-feature", making the value legal only on servers that advertise 6605 the corresponding feature: 6607 type enumeration { 6608 enum tcp; 6609 enum ssh { 6610 if-feature ssh; 6611 } 6612 enum tls { 6613 if-feature tls; 6614 } 6615 } 6617 9.7. The bits Built-In Type 6619 The bits built-in type represents a bit set. That is, a bits value 6620 is a set of flags identified by small integer position numbers 6621 starting at 0. Each bit number has an assigned name. 6623 When an existing bits type is restricted, the set of assigned names 6624 in the new type MUST be a subset of the base type's set of assigned 6625 names. The bit position of such an assigned name MUST NOT be 6626 changed. 6628 9.7.1. Restrictions 6630 A bits type can be restricted with the "bit" (Section 9.7.4) 6631 statement. 6633 9.7.2. Lexical Representation 6635 The lexical representation of the bits type is a space-separated list 6636 of the names of the bits that are set. A zero-length string thus 6637 represents a value where no bits are set. 6639 9.7.3. Canonical Form 6641 In the canonical form, the bit values are separated by a single space 6642 character and they appear ordered by their position (see 6643 Section 9.7.4.2). 6645 9.7.4. The bit Statement 6647 The "bit" statement, which is a substatement to the "type" statement, 6648 MUST be present if the type is "bits". It is repeatedly used to 6649 specify each assigned named bit of a bits type. It takes as an 6650 argument a string that is the assigned name of the bit. It is 6651 followed by a block of substatements that holds detailed bit 6652 information. The assigned name follows the same syntax rules as an 6653 identifier (see Section 6.2). 6655 All assigned names in a bits type MUST be unique. 6657 9.7.4.1. The bit's Substatements 6659 +--------------+---------+-------------+ 6660 | substatement | section | cardinality | 6661 +--------------+---------+-------------+ 6662 | description | 7.21.3 | 0..1 | 6663 | if-feature | 7.20.2 | 0..n | 6664 | reference | 7.21.4 | 0..1 | 6665 | status | 7.21.2 | 0..1 | 6666 | position | 9.7.4.2 | 0..1 | 6667 +--------------+---------+-------------+ 6669 9.7.4.2. The position Statement 6671 The "position" statement, which is optional, takes as an argument a 6672 non-negative integer value that specifies the bit's position within a 6673 hypothetical bit field. The position value MUST be in the range 0 to 6674 4294967295, and it MUST be unique within the bits type. 6676 If a bit position is not specified, then one will be automatically 6677 assigned. If the "bit" substatement is the first one defined, the 6678 assigned value is zero (0); otherwise, the assigned value is one 6679 greater than the current highest bit position (i.e., the highest bit 6680 position, implicit or explicit, prior to the current "bit" 6681 substatement in the parent "type" statement). 6683 Note that the the presence of an "if-feature" statement in an "bit" 6684 statement does not affect the automatically assigned position. 6686 If the current highest bit position value is equal to 4294967295, 6687 then a position value MUST be specified for "bit" substatements 6688 following the one with the current highest position value. 6690 When an existing bits type is restricted, the "position" statement 6691 MUST either have the same value as in the base type or not be 6692 present, in which case the value is the same as in the base type. 6694 9.7.5. Usage Example 6696 Given the following typedef and leaf: 6698 typedef mybits-type { 6699 type bits { 6700 bit disable-nagle { 6701 position 0; 6702 } 6703 bit auto-sense-speed { 6704 position 1; 6705 } 6706 bit ten-mb-only { 6707 position 2; 6708 } 6709 } 6710 } 6712 leaf mybits { 6713 type mybits-type; 6714 default "auto-sense-speed"; 6715 } 6717 The lexical representation of this leaf with bit values disable-nagle 6718 and ten-mb-only set would be: 6720 disable-nagle ten-mb-only 6722 The following example shows a legal refinement of this type: 6724 type mybits-type { 6725 // legal bit refinement 6726 bit disable-nagle { 6727 position 0; 6728 } 6729 bit auto-sense-speed { 6730 position 1; 6731 } 6732 } 6734 and the following refinement is illegal: 6736 type mybits-type { 6737 // illegal bit refinement 6738 bit disable-nagle { 6739 position 2; // illegal position change 6740 } 6741 bit hundred-mb-only; // illegal addition of new name 6742 } 6744 9.8. The binary Built-In Type 6746 The binary built-in type represents any binary data, i.e., a sequence 6747 of octets. 6749 9.8.1. Restrictions 6751 A binary type can be restricted with the "length" (Section 9.4.4) 6752 statement. The length of a binary value is the number of octets it 6753 contains. 6755 9.8.2. Lexical Representation 6757 Binary values are encoded with the base64 encoding scheme (see 6758 [RFC4648], Section 4). 6760 9.8.3. Canonical Form 6762 The canonical form of a binary value follows the rules of "Base 64 6763 Encoding" in [RFC4648]. 6765 9.9. The leafref Built-In Type 6767 The leafref type is restricted to the value space of some leaf or 6768 leaf-list node in the schema tree and optionally further restricted 6769 by corresponding instance nodes in the data tree. The "path" 6770 substatement (Section 9.9.2) is used to identify the referred leaf or 6771 leaf-list node in the schema tree. The value space of the referring 6772 node is the value space of the referred node. 6774 If the "require-instance" property (Section 9.9.3) is "true", there 6775 MUST exist a node in the data tree, or a node with a default value in 6776 use (see Section 7.6.1 and Section 7.7.2), of the referred schema 6777 tree leaf or leaf-list node with the same value as the leafref value 6778 in a valid data tree. 6780 If the referring node represents configuration data, and the 6781 "require-instance" property (Section 9.9.3) is "true", the referred 6782 node MUST also represent configuration. 6784 There MUST NOT be any circular chains of leafrefs. 6786 If the leaf that the leafref refers to is conditional based on one or 6787 more features (see Section 7.20.2), then the leaf with the leafref 6788 type MUST also be conditional based on at least the same set of 6789 features. 6791 9.9.1. Restrictions 6793 A leafref can be restricted with the "require-instance" statement 6794 (Section 9.9.3). 6796 9.9.2. The path Statement 6798 The "path" statement, which is a substatement to the "type" 6799 statement, MUST be present if the type is "leafref". It takes as an 6800 argument a string that MUST refer to a leaf or leaf-list node. 6802 The syntax for a path argument is a subset of the XPath abbreviated 6803 syntax. Predicates are used only for constraining the values for the 6804 key nodes for list entries. Each predicate consists of exactly one 6805 equality test per key, and multiple adjacent predicates MAY be 6806 present if a list has multiple keys. The syntax is formally defined 6807 by the rule "path-arg" in Section 14. 6809 The predicates are only used when more than one key reference is 6810 needed to uniquely identify a leaf instance. This occurs if a list 6811 has multiple keys, or a reference to a leaf other than the key in a 6812 list is needed. In these cases, multiple leafrefs are typically 6813 specified, and predicates are used to tie them together. 6815 The "path" expression evaluates to a node set consisting of zero, 6816 one, or more nodes. If the "require-instance" property is "true", 6817 this node set MUST be non-empty. 6819 The "path" XPath expression is conceptually evaluated in the 6820 following context, in addition to the definition in Section 6.4.1: 6822 o If the "path" statement is defined within a typedef, the context 6823 node is the leaf or leaf-list node in the data tree that 6824 references the typedef. 6826 o Otherwise, the context node is the node in the data tree for which 6827 the "path" statement is defined. 6829 9.9.3. The require-instance Statement 6831 The "require-instance" statement, which is a substatement to the 6832 "type" statement, MAY be present if the type is "instance-identifier" 6833 or "leafref". It takes as an argument the string "true" or "false". 6834 If this statement is not present, it defaults to "true". 6836 If "require-instance" is "true", it means that the instance being 6837 referred to MUST exist for the data to be valid. This constraint is 6838 enforced according to the rules in Section 8. 6840 If "require-instance" is "false", it means that the instance being 6841 referred to MAY exist in valid data. 6843 9.9.4. Lexical Representation 6845 A leafref value is lexically represented the same way as the leaf it 6846 references represents its value. 6848 9.9.5. Canonical Form 6850 The canonical form of a leafref is the same as the canonical form of 6851 the leaf it references. 6853 9.9.6. Usage Example 6855 With the following list: 6857 list interface { 6858 key "name"; 6859 leaf name { 6860 type string; 6861 } 6862 leaf admin-status { 6863 type admin-status; 6864 } 6865 list address { 6866 key "ip"; 6867 leaf ip { 6868 type yang:ip-address; 6869 } 6870 } 6871 } 6873 The following leafref refers to an existing interface: 6875 leaf mgmt-interface { 6876 type leafref { 6877 path "../interface/name"; 6878 } 6879 } 6881 An example of a corresponding XML snippet: 6883 6884 eth0 6885 6886 6887 lo 6888 6890 eth0 6892 The following leafrefs refer to an existing address of an interface: 6894 container default-address { 6895 leaf ifname { 6896 type leafref { 6897 path "../../interface/name"; 6898 } 6899 } 6900 leaf address { 6901 type leafref { 6902 path "../../interface[name = current()/../ifname]" 6903 + "/address/ip"; 6904 } 6905 } 6906 } 6908 An example of a corresponding XML snippet: 6910 6911 eth0 6912 up 6913
6914 192.0.2.1 6915
6916
6917 192.0.2.2 6918
6919 6920 6921 lo 6922 up 6923
6924 127.0.0.1 6925
6926 6928 6929 eth0 6930
192.0.2.2
6931 6933 The following list uses a leafref for one of its keys. This is 6934 similar to a foreign key in a relational database. 6936 list packet-filter { 6937 key "if-name filter-id"; 6938 leaf if-name { 6939 type leafref { 6940 path "/interface/name"; 6941 } 6942 } 6943 leaf filter-id { 6944 type uint32; 6945 } 6946 ... 6947 } 6949 An example of a corresponding XML snippet: 6951 6952 eth0 6953 up 6954
6955 192.0.2.1 6956
6957
6958 192.0.2.2 6959
6960 6962 6963 eth0 6964 1 6965 ... 6966 6967 6968 eth0 6969 2 6970 ... 6971 6973 The following notification defines two leafrefs to refer to an 6974 existing admin-status: 6976 notification link-failure { 6977 leaf if-name { 6978 type leafref { 6979 path "/interface/name"; 6980 } 6981 } 6982 leaf admin-status { 6983 type leafref { 6984 path "/interface[name = current()/../if-name]" 6985 + "/admin-status"; 6986 } 6987 } 6988 } 6990 An example of a corresponding XML notification: 6992 6994 2008-04-01T00:01:00Z 6995 6996 eth0 6997 up 6998 6999 7001 9.10. The identityref Built-In Type 7003 The identityref type is used to reference an existing identity (see 7004 Section 7.18). 7006 9.10.1. Restrictions 7008 An identityref cannot be restricted. 7010 9.10.2. The identityref's base Statement 7012 The "base" statement, which is a substatement to the "type" 7013 statement, MUST be present at least once if the type is 7014 "identityref". The argument is the name of an identity, as defined 7015 by an "identity" statement. If a prefix is present on the identity 7016 name, it refers to an identity defined in the module that was 7017 imported with that prefix. Otherwise, an identity with the matching 7018 name MUST be defined in the current module or an included submodule. 7020 Valid values for an identityref are any identities derived from all 7021 the identityref's base identities. On a particular server, the valid 7022 values are further restricted to the set of identities defined in the 7023 modules implemented by the server. 7025 9.10.3. Lexical Representation 7027 An identityref is lexically represented as the referred identity's 7028 qualified name as defined in [XML-NAMES]. If the prefix is not 7029 present, the namespace of the identityref is the default namespace in 7030 effect on the element that contains the identityref value. 7032 When an identityref is given a default value using the "default" 7033 statement, the identity name in the default value MAY have a prefix. 7034 If a prefix is present on the identity name, it refers to an identity 7035 defined in the module that was imported with that prefix, or the 7036 prefix for the current module if the identity is defined in the 7037 current module or one of its submodules. Otherwise, an identity with 7038 the matching name MUST be defined in the current module or one of its 7039 submodules. 7041 The string value of a node of type identityref in a "must" or "when" 7042 XPath expression is the referred identity's qualified name with the 7043 prefix present. If the referred identity is defined in an imported 7044 module, the prefix in the string value is the prefix defined in the 7045 corresponding "import" statement. Otherwise, the prefix in the 7046 string value is the prefix for the current module. 7048 9.10.4. Canonical Form 7050 Since the lexical form depends on the XML context in which the value 7051 occurs, this type does not have a canonical form. 7053 9.10.5. Usage Example 7055 With the identity definitions in Section 7.18.3 and the following 7056 module: 7058 module example-my-crypto { 7059 yang-version 1.1; 7060 namespace "urn:example:my-crypto"; 7061 prefix mc; 7063 import "example-crypto-base" { 7064 prefix "crypto"; 7065 } 7067 identity aes { 7068 base "crypto:crypto-alg"; 7069 } 7071 leaf crypto { 7072 type identityref { 7073 base "crypto:crypto-alg"; 7074 } 7075 } 7077 container aes-parameters { 7078 when "../crypto = 'mc:aes'"; 7079 ... 7080 } 7081 } 7083 the following is an example how the leaf "crypto" can be encoded, if 7084 the value is the "des3" identity defined in the "des" module: 7086 des:des3 7088 Any prefixes used in the encoding are local to each instance 7089 encoding. This means that the same identityref may be encoded 7090 differently by different implementations. For example, the following 7091 example encodes the same leaf as above: 7093 x:des3 7095 If the "crypto" leaf's value instead is "aes" defined in the 7096 "example-my-crypto" module, it can be encoded as: 7098 mc:aes 7100 or, using the default namespace: 7102 aes 7104 9.11. The empty Built-In Type 7106 The empty built-in type represents a leaf that does not have any 7107 value, it conveys information by its presence or absence. 7109 An empty type cannot have a default value. 7111 9.11.1. Restrictions 7113 An empty type cannot be restricted. 7115 9.11.2. Lexical Representation 7117 Not applicable. 7119 9.11.3. Canonical Form 7121 Not applicable. 7123 9.11.4. Usage Example 7125 With the following leaf 7127 leaf enable-qos { 7128 type empty; 7129 } 7131 the following is an example of a valid encoding 7133 7135 if the leaf exists. 7137 9.12. The union Built-In Type 7139 The union built-in type represents a value that corresponds to one of 7140 its member types. 7142 When the type is "union", the "type" statement (Section 7.4) MUST be 7143 present. It is repeatedly used to specify each member type of the 7144 union. It takes as an argument a string that is the name of a member 7145 type. 7147 A member type can be of any built-in or derived type. 7149 When generating an XML encoding, a value is encoded according to the 7150 rules of the member type to which the value belongs. When 7151 interpreting an XML encoding, a value is validated consecutively 7152 against each member type, in the order they are specified in the 7153 "type" statement, until a match is found. The type that matched will 7154 be the type of the value for the node that was validated, and the 7155 encoding is interpreted according to the rules for that type. 7157 Any default value or "units" property defined in the member types is 7158 not inherited by the union type. 7160 9.12.1. Restrictions 7162 A union cannot be restricted. However, each member type can be 7163 restricted, based on the rules defined in Section 9. 7165 9.12.2. Lexical Representation 7167 The lexical representation of a union is a value that corresponds to 7168 the representation of any one of the member types. 7170 9.12.3. Canonical Form 7172 The canonical form of a union value is the same as the canonical form 7173 of the member type of the value. 7175 9.12.4. Usage Example 7177 The following is a union of an int32 and an enumeration: 7179 type union { 7180 type int32; 7181 type enumeration { 7182 enum "unbounded"; 7183 } 7184 } 7186 Care must be taken when a member type is a leafref where the 7187 "require-instance" property (Section 9.9.3) is "true". If a leaf of 7188 such a type refers to an existing instance, the leaf's value must be 7189 re-validated if the target instance is deleted. For example, with 7190 the following definitions: 7192 list filter { 7193 key name; 7194 leaf name { 7195 type string; 7196 } 7197 ... 7198 } 7200 leaf outbound-filter { 7201 type union { 7202 type leafref { 7203 path "/filter/name"; 7204 } 7205 type enumeration { 7206 enum default-filter; 7207 } 7208 } 7209 } 7211 assume that there exists an entry in the filter list with the name 7212 "http", and that the outbound-filter leaf has this value: 7214 7215 http 7216 7217 http 7219 If the filter entry "http" is removed, the outbound-filter leaf's 7220 value doesn't match the leafref, and the next member type is checked. 7221 The current value ("http") doesn't match the enumeration, so the 7222 resulting configuration is invalid. 7224 If the second member type in the union had been of type "string" 7225 instead of an enumeration, the current value would have matched, and 7226 the resulting configuration would have been valid. 7228 9.13. The instance-identifier Built-In Type 7230 The instance-identifier built-in type is used to uniquely identify a 7231 particular instance node in the data tree. 7233 The syntax for an instance-identifier is a subset of the XPath 7234 abbreviated syntax, formally defined by the rule 7235 "instance-identifier" in Section 14. It is used to uniquely identify 7236 a node in the data tree. Predicates are used only for specifying the 7237 values for the key nodes for list entries, a value of a leaf-list 7238 entry, or a positional index for a list without keys. For 7239 identifying list entries with keys, each predicate consists of one 7240 equality test per key, and each key MUST have a corresponding 7241 predicate. If a key is of type "empty", it is represented as a zero- 7242 length string (""). 7244 If the leaf with the instance-identifier type represents 7245 configuration data, and the "require-instance" property 7246 (Section 9.9.3) is "true", the node it refers to MUST also represent 7247 configuration. Such a leaf puts a constraint on valid data. All 7248 such leaf nodes MUST reference existing nodes or leaf or leaf-list 7249 nodes with their default value in use (see Section 7.6.1 and 7250 Section 7.7.2) for the data to be valid. This constraint is enforced 7251 according to the rules in Section 8. 7253 The "instance-identifier" XPath expression is conceptually evaluated 7254 in the following context, in addition to the definition in 7255 Section 6.4.1: 7257 o The context node is the root node in the accessible tree. 7259 9.13.1. Restrictions 7261 An instance-identifier can be restricted with the "require-instance" 7262 statement (Section 9.9.3). 7264 9.13.2. Lexical Representation 7266 An instance-identifier value is lexically represented as a string. 7267 All node names in an instance-identifier value MUST be qualified with 7268 explicit namespace prefixes, and these prefixes MUST be declared in 7269 the XML namespace scope in the instance-identifier's XML element. 7271 Any prefixes used in the encoding are local to each instance 7272 encoding. This means that the same instance-identifier may be 7273 encoded differently by different implementations. 7275 9.13.3. Canonical Form 7277 Since the lexical form depends on the XML context in which the value 7278 occurs, this type does not have a canonical form. 7280 9.13.4. Usage Example 7282 The following are examples of instance identifiers: 7284 /* instance-identifier for a container */ 7285 /ex:system/ex:services/ex:ssh 7287 /* instance-identifier for a leaf */ 7288 /ex:system/ex:services/ex:ssh/ex:port 7290 /* instance-identifier for a list entry */ 7291 /ex:system/ex:user[ex:name='fred'] 7293 /* instance-identifier for a leaf in a list entry */ 7294 /ex:system/ex:user[ex:name='fred']/ex:type 7296 /* instance-identifier for a list entry with two keys */ 7297 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 7299 /* instance-identifier for a list entry where the second 7300 key ("enabled") is of type empty */ 7301 /ex:system/ex:service[ex:name='foo'][ex:enabled=''] 7303 /* instance-identifier for a leaf-list entry */ 7304 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 7306 /* instance-identifier for a list entry without keys */ 7307 /ex:stats/ex:port[3] 7309 10. XPath Functions 7311 This document defines two generic XPath functions and five YANG type- 7312 specific XPath functions. The function signatures are specified with 7313 the syntax used in [XPATH]. 7315 10.1. Functions for Node Sets 7317 10.1.1. current() 7319 node-set current() 7321 The function current() takes no input parameters, and returns a node 7322 set with the initial context node as its only member. 7324 10.1.1.1. Usage Example 7326 With this list: 7328 list interface { 7329 key "name"; 7330 ... 7331 leaf enabled { 7332 type boolean; 7333 } 7334 ... 7335 } 7337 the following leaf defines a must expression that ensures that the 7338 referred interface is enabled: 7340 leaf outgoing-interface { 7341 type leafref { 7342 path "/interface/name"; 7343 } 7344 must '/interface[name=current()]/enabled = "true"'; 7345 } 7347 10.2. Functions for Strings 7349 10.2.1. re-match() 7351 boolean re-match(string subject, string pattern) 7353 The re-match() function returns "true" if the "subject" string 7354 matches the regular expression "pattern"; otherwise it returns 7355 "false". 7357 The function "re-match" checks if a string matches a given regular 7358 expression. The regular expressions used are the XML Schema regular 7359 expressions [XSD-TYPES]. Note that this includes implicit anchoring 7360 of the regular expression at the head and tail. 7362 10.2.1.1. Usage Example 7364 The expression: 7366 re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}") 7368 returns "true". 7370 To count all logical interfaces called eth0., do: 7372 count(/interface[re-match(name, "eth0\.\d+")]) 7374 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 7376 10.3.1. deref() 7378 node-set deref(node-set nodes) 7380 The deref() function follows the reference defined by the first node 7381 in document order in the argument "nodes", and returns the nodes it 7382 refers to. 7384 If the first argument node is of type instance-identifier, the 7385 function returns a node set that contains the single node that the 7386 instance identifier refers to, if it exists. If no such node exists, 7387 an empty node-set is returned. 7389 If the first argument node is of type leafref, the function returns a 7390 node set that contains the nodes that the leafref refers to. 7391 Specifically, this set contains the nodes selected by the leafref's 7392 "path" statement (Section 9.9.2) that have the same value as the 7393 first argument node. 7395 If the first argument node is of any other type, an empty node set is 7396 returned. 7398 10.3.1.1. Usage Example 7399 list interface { 7400 key "name type"; 7401 leaf name { ... } 7402 leaf type { ... } 7403 leaf enabled { 7404 type boolean; 7405 } 7406 ... 7407 } 7409 container mgmt-interface { 7410 leaf name { 7411 type leafref { 7412 path "/interface/name"; 7413 } 7414 } 7415 leaf type { 7416 type leafref { 7417 path "/interface[name=current()/../name]/type"; 7418 } 7419 must 'deref(.)/../enabled = "true"' { 7420 error-message 7421 "The management interface cannot be disabled."; 7422 } 7423 } 7424 } 7426 10.4. Functions for the YANG Type "identityref" 7428 10.4.1. derived-from() 7430 boolean derived-from(node-set nodes, string identity) 7432 The derived-from() function returns "true" if any node in the 7433 argument "nodes" is a node of type identityref, and its value is an 7434 identity that is derived from (see Section 7.18.2) the identity 7435 "identity"; otherwise it returns "false". 7437 The parameter "identity" is a string matching the rule 7438 "identifier-ref" in Section 14. If a prefix is present on the 7439 identity, it refers to an identity defined in the module that was 7440 imported with that prefix, or the local module if the prefix matches 7441 the local module's prefix. If no prefix is present, the identity 7442 refers to an identity defined in the current module or an included 7443 submodule. 7445 10.4.1.1. Usage Example 7447 module example-interface { 7448 yang-version 1.1; 7450 ... 7451 identity interface-type; 7453 identity ethernet { 7454 base interface-type; 7455 } 7457 identity fast-ethernet { 7458 base ethernet; 7459 } 7461 identity gigabit-ethernet { 7462 base ethernet; 7463 } 7465 list interface { 7466 key name; 7467 ... 7468 leaf type { 7469 type identityref { 7470 base interface-type; 7471 } 7472 } 7473 ... 7474 } 7476 augment "/interface" { 7477 when 'derived-from(type, "exif:ethernet")'; 7478 // generic ethernet definitions here 7479 } 7480 ... 7481 } 7483 10.4.2. derived-from-or-self() 7485 boolean derived-from-or-self(node-set nodes, string identity) 7487 The derived-from-or-self() function returns "true" if any node in the 7488 argument "nodes" is a node of type identityref, and its value is an 7489 identity that is equal to or derived from (see Section 7.18.2) the 7490 identity "identity"; otherwise it returns "false". 7492 The parameter "identity" is a string matching the rule 7493 "identifier-ref" in Section 14. If a prefix is present on the 7494 identity, it refers to an identity defined in the module that was 7495 imported with that prefix, or the local module if the prefix matches 7496 the local module's prefix. If no prefix is present, the identity 7497 refers to an identity defined in the current module or an included 7498 submodule. 7500 10.4.2.1. Usage Example 7502 The module defined in Section 10.4.1.1 might also have: 7504 augment "/interface" { 7505 when 'derived-from-or-self(type, "exif:fast-ethernet"); 7506 // fast-ethernet-specific definitions here 7507 } 7509 10.5. Functions for the YANG Type "enumeration" 7511 10.5.1. enum-value() 7513 number enum-value(node-set nodes) 7515 The enum-value() function checks if the first node in document order 7516 in the argument "nodes" is a node of type enumeration, and returns 7517 the enum's integer value. If the "nodes" node set is empty, or if 7518 the first node in "nodes" is not of type enumeration, it returns NaN. 7520 10.5.1.1. Usage Example 7522 With this data model: 7524 list alarm { 7525 ... 7526 leaf severity { 7527 type enumeration { 7528 enum cleared { 7529 value 1; 7530 } 7531 enum indeterminate { 7532 value 2; 7533 } 7534 enum minor { 7535 value 3; 7536 } 7537 enum warning { 7538 value 4; 7539 } 7540 enum major { 7541 value 5; 7542 } 7543 enum critical { 7544 value 6; 7545 } 7546 } 7547 } 7548 } 7550 the following XPath expression selects only alarms that are of 7551 severity "major" or higher: 7553 /alarm[enum-value(severity) >= 5] 7555 10.6. Functions for the YANG Type "bits" 7557 10.6.1. bit-is-set() 7559 boolean bit-is-set(node-set nodes, string bit-name) 7561 The bit-is-set() function returns "true" if the first node in 7562 document order in the argument "nodes" is a node of type bits, and 7563 its value has the bit "'bit-name" set; otherwise it returns "false". 7565 10.6.1.1. Usage Example 7567 If an interface has this leaf: 7569 leaf flags { 7570 type bits { 7571 bit UP; 7572 bit PROMISCUOUS 7573 bit DISABLED; 7574 } 7575 } 7577 the following XPath expression can be used to select all interfaces 7578 with the UP flag set: 7580 /interface[bit-is-set(flags, "UP")] 7582 11. Updating a Module 7584 As experience is gained with a module, it may be desirable to revise 7585 that module. However, changes to published modules are not allowed 7586 if they have any potential to cause interoperability problems between 7587 a client using an original specification and a server using an 7588 updated specification. 7590 For any published change, a new "revision" statement (Section 7.1.9) 7591 MUST be included in front of the existing "revision" statements. If 7592 there are no existing "revision" statements, then one MUST be added 7593 to identify the new revision. Furthermore, any necessary changes 7594 MUST be applied to any meta-data statements, including the 7595 "organization" and "contact" statements (Section 7.1.7, 7596 Section 7.1.8). 7598 Note that definitions contained in a module are available to be 7599 imported by any other module, and are referenced in "import" 7600 statements via the module name. Thus, a module name MUST NOT be 7601 changed. Furthermore, the "namespace" statement MUST NOT be changed, 7602 since all XML elements are qualified by the namespace. 7604 Obsolete definitions MUST NOT be removed from published modules since 7605 their identifiers may still be referenced by other modules. 7607 A definition in a published module may be revised in any of the 7608 following ways: 7610 o An "enumeration" type may have new enums added, provided the old 7611 enums's values do not change. Note that inserting a new enum 7612 before an existing enum or reordering existing enums will result 7613 in new values for the existing enums, unless they have explicit 7614 values assigned to them. 7616 o A "bits" type may have new bits added, provided the old bit 7617 positions do not change. Note that inserting a new bit before an 7618 existing bit or reordering existing bit will result in new 7619 positions for the existing bits, unless they have explicit 7620 positions assigned to them. 7622 o A "range", "length", or "pattern" statement may expand the allowed 7623 value space. 7625 o A "default" statement may be added to a leaf that does not have a 7626 default value (either directly or indirectly through its type). 7628 o A "units" statement may be added. 7630 o A "reference" statement may be added or updated. 7632 o A "must" statement may be removed or its constraint relaxed. 7634 o A "when" statement may be removed or its constraint relaxed. 7636 o A "mandatory" statement may be removed or changed from "true" to 7637 "false". 7639 o A "min-elements" statement may be removed, or changed to require 7640 fewer elements. 7642 o A "max-elements" statement may be removed, or changed to allow 7643 more elements. 7645 o A "description" statement may be added or changed without changing 7646 the semantics of the definition. 7648 o A "base" statement may be added to an "identity" statement. 7650 o A "base" statement may be removed from an "identityref" type, 7651 provided there is at least one "base" statement left. 7653 o New typedefs, groupings, rpcs, notifications, extensions, 7654 features, and identities may be added. 7656 o New data definition statements may be added if they do not add 7657 mandatory nodes (Section 3) to existing nodes or at the top level 7658 in a module or submodule, or if they are conditionally dependent 7659 on a new feature (i.e., have an "if-feature" statement that refers 7660 to a new feature). 7662 o A new "case" statement may be added. 7664 o A node that represented state data may be changed to represent 7665 configuration, provided it is not mandatory (Section 3). 7667 o An "if-feature" statement may be removed, provided its node is not 7668 mandatory (Section 3). 7670 o A "status" statement may be added, or changed from "current" to 7671 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 7673 o A "type" statement may be replaced with another "type" statement 7674 that does not change the syntax or semantics of the type. For 7675 example, an inline type definition may be replaced with a typedef, 7676 but an int8 type cannot be replaced by an int16, since the syntax 7677 would change. 7679 o Any set of data definition nodes may be replaced with another set 7680 of syntactically and semantically equivalent nodes. For example, 7681 a set of leafs may be replaced by a uses of a grouping with the 7682 same leafs. 7684 o A module may be split into a set of submodules, or a submodule may 7685 be removed, provided the definitions in the module do not change 7686 in any other way than allowed here. 7688 o The "prefix" statement may be changed, provided all local uses of 7689 the prefix also are changed. 7691 Otherwise, if the semantics of any previous definition are changed 7692 (i.e., if a non-editorial change is made to any definition other than 7693 those specifically allowed above), then this MUST be achieved by a 7694 new definition with a new identifier. 7696 In statements that have any data definition statements as 7697 substatements, those data definition substatements MUST NOT be 7698 reordered. If new data definition statements are added, they can be 7699 added anywhere in the sequence of existing substatement. 7701 12. Coexistence with YANG version 1 7703 A YANG version 1.1 module MUST NOT include a YANG version 1 7704 submodule, and a YANG version 1 module MUST NOT include a YANG 7705 version 1.1 submodule. 7707 A YANG version 1 module or submodule MUST NOT import a YANG version 7708 1.1 module by revision. 7710 A YANG version 1.1 module or submodule MAY import a YANG version 1 7711 module by revision. 7713 If a YANG version 1 module A imports module B without revision, and 7714 module B is updated to YANG version 1.1, a server MAY implement both 7715 these modules (A and B) at the same time. In such cases, a NETCONF 7716 server MUST advertise both modules using the rules defined in 7717 Section 5.6.4, and SHOULD advertise module A and the latest revision 7718 of module B that is specified with YANG version 1 according to the 7719 rules defined in [RFC6020]. 7721 This rule exists in order to allow implementations of existing YANG 7722 version 1 modules together with YANG version 1.1 modules. Without 7723 this rule, updating a single module to YANG version 1.1 would have a 7724 cascading effect on modules that import it, requiring all of them to 7725 also be updated to YANG version 1.1, and so on. 7727 13. YIN 7729 A YANG module can be translated into an alternative XML-based syntax 7730 called YIN. The translated module is called a YIN module. This 7731 section describes bidirectional mapping rules between the two 7732 formats. 7734 The YANG and YIN formats contain equivalent information using 7735 different notations. The YIN notation enables developers to 7736 represent YANG data models in XML and therefore use the rich set of 7737 XML-based tools for data filtering and validation, automated 7738 generation of code and documentation, and other tasks. Tools like 7739 XSLT or XML validators can be utilized. 7741 The mapping between YANG and YIN does not modify the information 7742 content of the model. Comments and whitespace are not preserved. 7744 13.1. Formal YIN Definition 7746 There is a one-to-one correspondence between YANG keywords and YIN 7747 elements. The local name of a YIN element is identical to the 7748 corresponding YANG keyword. This means, in particular, that the 7749 document element (root) of a YIN document is always or 7750 . 7752 YIN elements corresponding to the YANG keywords belong to the 7753 namespace whose associated URI is 7754 "urn:ietf:params:xml:ns:yang:yin:1". 7756 YIN elements corresponding to extension keywords belong to the 7757 namespace of the YANG module where the extension keyword is declared 7758 via the "extension" statement. 7760 The names of all YIN elements MUST be properly qualified with their 7761 namespaces specified above using the standard mechanisms of 7762 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 7764 The argument of a YANG statement is represented in YIN either as an 7765 XML attribute or a subelement of the keyword element. Table 1 7766 defines the mapping for the set of YANG keywords. For extensions, 7767 the argument mapping is specified within the "extension" statement 7768 (see Section 7.19). The following rules hold for arguments: 7770 o If the argument is represented as an attribute, this attribute has 7771 no namespace. 7773 o If the argument is represented as an element, it is qualified by 7774 the same namespace as its parent keyword element. 7776 o If the argument is represented as an element, it MUST be the first 7777 child of the keyword element. 7779 Substatements of a YANG statement are represented as (additional) 7780 children of the keyword element and their relative order MUST be the 7781 same as the order of substatements in YANG. 7783 Comments in YANG MAY be mapped to XML comments. 7785 +------------------+---------------+-------------+ 7786 | keyword | argument name | yin-element | 7787 +------------------+---------------+-------------+ 7788 | action | name | false | 7789 | anydata | name | false | 7790 | anyxml | name | false | 7791 | argument | name | false | 7792 | augment | target-node | false | 7793 | base | name | false | 7794 | belongs-to | module | false | 7795 | bit | name | false | 7796 | case | name | false | 7797 | choice | name | false | 7798 | config | value | false | 7799 | contact | text | true | 7800 | container | name | false | 7801 | default | value | false | 7802 | description | text | true | 7803 | deviate | value | false | 7804 | deviation | target-node | false | 7805 | enum | name | false | 7806 | error-app-tag | value | false | 7807 | error-message | value | true | 7808 | extension | name | false | 7809 | feature | name | false | 7810 | fraction-digits | value | false | 7811 | grouping | name | false | 7812 | identity | name | false | 7813 | if-feature | name | false | 7814 | import | module | false | 7815 | include | module | false | 7816 | input | | n/a | 7817 | key | value | false | 7818 | leaf | name | false | 7819 | leaf-list | name | false | 7820 | length | value | false | 7821 | list | name | false | 7822 | mandatory | value | false | 7823 | max-elements | value | false | 7824 | min-elements | value | false | 7825 | modifier | value | false | 7826 | module | name | false | 7827 | must | condition | false | 7828 | namespace | uri | false | 7829 | notification | name | false | 7830 | ordered-by | value | false | 7831 | organization | text | true | 7832 | output | | n/a | 7833 | path | value | false | 7834 | pattern | value | false | 7835 | position | value | false | 7836 | prefix | value | false | 7837 | presence | value | false | 7838 | range | value | false | 7839 | reference | text | true | 7840 | refine | target-node | false | 7841 | require-instance | value | false | 7842 | revision | date | false | 7843 | revision-date | date | false | 7844 | rpc | name | false | 7845 | status | value | false | 7846 | submodule | name | false | 7847 | type | name | false | 7848 | typedef | name | false | 7849 | unique | tag | false | 7850 | units | name | false | 7851 | uses | name | false | 7852 | value | value | false | 7853 | when | condition | false | 7854 | yang-version | value | false | 7855 | yin-element | value | false | 7856 +------------------+---------------+-------------+ 7858 Table 1: Mapping of arguments of the YANG statements. 7860 13.1.1. Usage Example 7862 The following YANG module: 7864 module example-foo { 7865 yang-version 1.1; 7866 namespace "urn:example:foo"; 7867 prefix "foo"; 7869 import example-extensions { 7870 prefix "myext"; 7871 } 7873 list interface { 7874 key "name"; 7875 leaf name { 7876 type string; 7877 } 7879 leaf mtu { 7880 type uint32; 7881 description "The MTU of the interface."; 7882 myext:c-define "MY_MTU"; 7883 } 7884 } 7885 } 7887 where the extension "c-define" is defined in Section 7.19.3, is 7888 translated into the following YIN: 7890 7895 7896 7898 7899 7900 7902 7903 7904 7905 7906 7907 7908 7909 7910 The MTU of the interface. 7911 7912 7913 7914 7915 7917 14. YANG ABNF Grammar 7919 In YANG, almost all statements are unordered. The ABNF grammar 7920 [RFC5234] [RFC7405] defines the canonical order. To improve module 7921 readability, it is RECOMMENDED that clauses be entered in this order. 7923 Within the ABNF grammar, unordered statements are marked with 7924 comments. 7926 This grammar assumes that the scanner replaces YANG comments with a 7927 single space character. 7929 file "yang.abnf" 7931 module-stmt = optsep module-keyword sep identifier-arg-str 7932 optsep 7933 "{" stmtsep 7934 module-header-stmts 7935 linkage-stmts 7936 meta-stmts 7937 revision-stmts 7938 body-stmts 7939 "}" optsep 7941 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 7942 optsep 7943 "{" stmtsep 7944 submodule-header-stmts 7945 linkage-stmts 7946 meta-stmts 7947 revision-stmts 7948 body-stmts 7949 "}" optsep 7951 module-header-stmts = ;; these stmts can appear in any order 7952 yang-version-stmt 7953 namespace-stmt 7954 prefix-stmt 7956 submodule-header-stmts = 7957 ;; these stmts can appear in any order 7958 yang-version-stmt 7959 belongs-to-stmt 7961 meta-stmts = ;; these stmts can appear in any order 7962 [organization-stmt] 7963 [contact-stmt] 7964 [description-stmt] 7965 [reference-stmt] 7967 linkage-stmts = ;; these stmts can appear in any order 7968 *import-stmt 7969 *include-stmt 7971 revision-stmts = *revision-stmt 7973 body-stmts = *(extension-stmt / 7974 feature-stmt / 7975 identity-stmt / 7976 typedef-stmt / 7977 grouping-stmt / 7978 data-def-stmt / 7979 augment-stmt / 7980 rpc-stmt / 7981 notification-stmt / 7982 deviation-stmt) 7984 data-def-stmt = container-stmt / 7985 leaf-stmt / 7986 leaf-list-stmt / 7987 list-stmt / 7988 choice-stmt / 7989 anydata-stmt / 7990 anyxml-stmt / 7991 uses-stmt 7993 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 7994 stmtend 7996 yang-version-arg-str = < a string that matches the rule > 7997 < yang-version-arg > 7999 yang-version-arg = "1.1" 8001 import-stmt = import-keyword sep identifier-arg-str optsep 8002 "{" stmtsep 8003 ;; these stmts can appear in any order 8004 prefix-stmt 8005 [revision-date-stmt] 8006 [description-stmt] 8007 [reference-stmt] 8008 "}" stmtsep 8010 include-stmt = include-keyword sep identifier-arg-str optsep 8011 (";" / 8012 "{" stmtsep 8013 ;; these stmts can appear in any order 8014 [revision-date-stmt] 8015 [description-stmt] 8016 [reference-stmt] 8017 "}") stmtsep 8019 namespace-stmt = namespace-keyword sep uri-str stmtend 8021 uri-str = < a string that matches the rule > 8022 < URI in RFC 3986 > 8024 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 8026 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 8027 optsep 8028 "{" stmtsep 8029 prefix-stmt 8030 "}" stmtsep 8032 organization-stmt = organization-keyword sep string stmtend 8033 contact-stmt = contact-keyword sep string stmtend 8035 description-stmt = description-keyword sep string stmtend 8037 reference-stmt = reference-keyword sep string stmtend 8039 units-stmt = units-keyword sep string stmtend 8041 revision-stmt = revision-keyword sep revision-date optsep 8042 (";" / 8043 "{" stmtsep 8044 ;; these stmts can appear in any order 8045 [description-stmt] 8046 [reference-stmt] 8047 "}") stmtsep 8049 revision-date = date-arg-str 8051 revision-date-stmt = revision-date-keyword sep revision-date stmtend 8053 extension-stmt = extension-keyword sep identifier-arg-str optsep 8054 (";" / 8055 "{" stmtsep 8056 ;; these stmts can appear in any order 8057 [argument-stmt] 8058 [status-stmt] 8059 [description-stmt] 8060 [reference-stmt] 8061 "}") stmtsep 8063 argument-stmt = argument-keyword sep identifier-arg-str optsep 8064 (";" / 8065 "{" stmtsep 8066 [yin-element-stmt] 8067 "}") stmtsep 8069 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 8070 stmtend 8072 yin-element-arg-str = < a string that matches the rule > 8073 < yin-element-arg > 8075 yin-element-arg = true-keyword / false-keyword 8077 identity-stmt = identity-keyword sep identifier-arg-str optsep 8078 (";" / 8079 "{" stmtsep 8080 ;; these stmts can appear in any order 8081 *if-feature-stmt 8082 *base-stmt 8083 [status-stmt] 8084 [description-stmt] 8085 [reference-stmt] 8086 "}") stmtsep 8088 base-stmt = base-keyword sep identifier-ref-arg-str 8089 stmtend 8091 feature-stmt = feature-keyword sep identifier-arg-str optsep 8092 (";" / 8093 "{" stmtsep 8094 ;; these stmts can appear in any order 8095 *if-feature-stmt 8096 [status-stmt] 8097 [description-stmt] 8098 [reference-stmt] 8099 "}") stmtsep 8101 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 8102 stmtend 8104 if-feature-expr-str = < a string that matches the rule > 8105 < if-feature-expr > 8107 if-feature-expr = if-feature-term 8108 [sep or-keyword sep if-feature-expr] 8110 if-feature-term = if-feature-factor 8111 [sep and-keyword sep if-feature-term] 8113 if-feature-factor = not-keyword sep if-feature-factor / 8114 "(" sep if-feature-expr sep ")" / 8115 identifier-ref-arg 8117 boolean-operator = and-keyword / or-keyword 8119 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 8120 "{" stmtsep 8121 ;; these stmts can appear in any order 8122 type-stmt 8123 [units-stmt] 8124 [default-stmt] 8125 [status-stmt] 8126 [description-stmt] 8127 [reference-stmt] 8128 "}" stmtsep 8130 type-stmt = type-keyword sep identifier-ref-arg-str optsep 8131 (";" / 8132 "{" stmtsep 8133 [type-body-stmts] 8134 "}") stmtsep 8136 type-body-stmts = numerical-restrictions / 8137 decimal64-specification / 8138 string-restrictions / 8139 enum-specification / 8140 leafref-specification / 8141 identityref-specification / 8142 instance-identifier-specification / 8143 bits-specification / 8144 union-specification / 8145 binary-specification 8147 numerical-restrictions = [range-stmt] 8149 range-stmt = range-keyword sep range-arg-str optsep 8150 (";" / 8151 "{" stmtsep 8152 ;; these stmts can appear in any order 8153 [error-message-stmt] 8154 [error-app-tag-stmt] 8155 [description-stmt] 8156 [reference-stmt] 8157 "}") stmtsep 8159 decimal64-specification = ;; these stmts can appear in any order 8160 fraction-digits-stmt 8161 [range-stmt] 8163 fraction-digits-stmt = fraction-digits-keyword sep 8164 fraction-digits-arg-str stmtend 8166 fraction-digits-arg-str = < a string that matches the rule > 8167 < fraction-digits-arg > 8169 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 8170 "5" / "6" / "7" / "8"]) 8171 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 8173 string-restrictions = ;; these stmts can appear in any order 8174 [length-stmt] 8175 *pattern-stmt 8177 length-stmt = length-keyword sep length-arg-str optsep 8178 (";" / 8179 "{" stmtsep 8180 ;; these stmts can appear in any order 8181 [error-message-stmt] 8182 [error-app-tag-stmt] 8183 [description-stmt] 8184 [reference-stmt] 8185 "}") stmtsep 8187 pattern-stmt = pattern-keyword sep string optsep 8188 (";" / 8189 "{" stmtsep 8190 ;; these stmts can appear in any order 8191 [modifier-stmt] 8192 [error-message-stmt] 8193 [error-app-tag-stmt] 8194 [description-stmt] 8195 [reference-stmt] 8196 "}") stmtsep 8198 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 8200 modifier-arg-str = < a string that matches the rule > 8201 < modifier-arg > 8203 modifier-arg = invert-match-keyword 8205 default-stmt = default-keyword sep string stmtend 8207 enum-specification = 1*enum-stmt 8209 enum-stmt = enum-keyword sep string optsep 8210 (";" / 8211 "{" stmtsep 8212 ;; these stmts can appear in any order 8213 *if-feature-stmt 8214 [value-stmt] 8215 [status-stmt] 8216 [description-stmt] 8217 [reference-stmt] 8218 "}") stmtsep 8220 leafref-specification = 8221 ;; these stmts can appear in any order 8222 path-stmt 8223 [require-instance-stmt] 8225 path-stmt = path-keyword sep path-arg-str stmtend 8226 require-instance-stmt = require-instance-keyword sep 8227 require-instance-arg-str stmtend 8229 require-instance-arg-str = < a string that matches the rule > 8230 < require-instance-arg > 8232 require-instance-arg = true-keyword / false-keyword 8234 instance-identifier-specification = 8235 [require-instance-stmt] 8237 identityref-specification = 8238 1*base-stmt 8240 union-specification = 1*type-stmt 8242 binary-specification = [length-stmt] 8244 bits-specification = 1*bit-stmt 8246 bit-stmt = bit-keyword sep identifier-arg-str optsep 8247 (";" / 8248 "{" stmtsep 8249 ;; these stmts can appear in any order 8250 *if-feature-stmt 8251 [position-stmt] 8252 [status-stmt] 8253 [description-stmt] 8254 [reference-stmt] 8255 "}") stmtsep 8257 position-stmt = position-keyword sep 8258 position-value-arg-str stmtend 8260 position-value-arg-str = < a string that matches the rule > 8261 < position-value-arg > 8263 position-value-arg = non-negative-integer-value 8265 status-stmt = status-keyword sep status-arg-str stmtend 8267 status-arg-str = < a string that matches the rule > 8268 < status-arg > 8270 status-arg = current-keyword / 8271 obsolete-keyword / 8272 deprecated-keyword 8274 config-stmt = config-keyword sep 8275 config-arg-str stmtend 8277 config-arg-str = < a string that matches the rule > 8278 < config-arg > 8280 config-arg = true-keyword / false-keyword 8282 mandatory-stmt = mandatory-keyword sep 8283 mandatory-arg-str stmtend 8285 mandatory-arg-str = < a string that matches the rule > 8286 < mandatory-arg > 8288 mandatory-arg = true-keyword / false-keyword 8290 presence-stmt = presence-keyword sep string stmtend 8292 ordered-by-stmt = ordered-by-keyword sep 8293 ordered-by-arg-str stmtend 8295 ordered-by-arg-str = < a string that matches the rule > 8296 < ordered-by-arg > 8298 ordered-by-arg = user-keyword / system-keyword 8300 must-stmt = must-keyword sep string optsep 8301 (";" / 8302 "{" stmtsep 8303 ;; these stmts can appear in any order 8304 [error-message-stmt] 8305 [error-app-tag-stmt] 8306 [description-stmt] 8307 [reference-stmt] 8308 "}") stmtsep 8310 error-message-stmt = error-message-keyword sep string stmtend 8312 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 8314 min-elements-stmt = min-elements-keyword sep 8315 min-value-arg-str stmtend 8317 min-value-arg-str = < a string that matches the rule > 8318 < min-value-arg > 8320 min-value-arg = non-negative-integer-value 8321 max-elements-stmt = max-elements-keyword sep 8322 max-value-arg-str stmtend 8324 max-value-arg-str = < a string that matches the rule > 8325 < max-value-arg > 8327 max-value-arg = unbounded-keyword / 8328 positive-integer-value 8330 value-stmt = value-keyword sep integer-value-str stmtend 8332 integer-value-str = < a string that matches the rule > 8333 < integer-value > 8335 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 8336 (";" / 8337 "{" stmtsep 8338 ;; these stmts can appear in any order 8339 [status-stmt] 8340 [description-stmt] 8341 [reference-stmt] 8342 *(typedef-stmt / grouping-stmt) 8343 *data-def-stmt 8344 *action-stmt 8345 *notification-stmt 8346 "}") stmtsep 8348 container-stmt = container-keyword sep identifier-arg-str optsep 8349 (";" / 8350 "{" stmtsep 8351 ;; these stmts can appear in any order 8352 [when-stmt] 8353 *if-feature-stmt 8354 *must-stmt 8355 [presence-stmt] 8356 [config-stmt] 8357 [status-stmt] 8358 [description-stmt] 8359 [reference-stmt] 8360 *(typedef-stmt / grouping-stmt) 8361 *data-def-stmt 8362 *action-stmt 8363 *notification-stmt 8364 "}") stmtsep 8366 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 8367 "{" stmtsep 8368 ;; these stmts can appear in any order 8370 [when-stmt] 8371 *if-feature-stmt 8372 type-stmt 8373 [units-stmt] 8374 *must-stmt 8375 [default-stmt] 8376 [config-stmt] 8377 [mandatory-stmt] 8378 [status-stmt] 8379 [description-stmt] 8380 [reference-stmt] 8381 "}" stmtsep 8383 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 8384 "{" stmtsep 8385 ;; these stmts can appear in any order 8386 [when-stmt] 8387 *if-feature-stmt 8388 type-stmt stmtsep 8389 [units-stmt] 8390 *must-stmt 8391 *default-stmt 8392 [config-stmt] 8393 [min-elements-stmt] 8394 [max-elements-stmt] 8395 [ordered-by-stmt] 8396 [status-stmt] 8397 [description-stmt] 8398 [reference-stmt] 8399 "}" stmtsep 8401 list-stmt = list-keyword sep identifier-arg-str optsep 8402 "{" stmtsep 8403 ;; these stmts can appear in any order 8404 [when-stmt] 8405 *if-feature-stmt 8406 *must-stmt 8407 [key-stmt] 8408 *unique-stmt 8409 [config-stmt] 8410 [min-elements-stmt] 8411 [max-elements-stmt] 8412 [ordered-by-stmt] 8413 [status-stmt] 8414 [description-stmt] 8415 [reference-stmt] 8416 *(typedef-stmt / grouping-stmt) 8417 1*data-def-stmt 8418 *action-stmt 8419 *notification-stmt 8420 "}" stmtsep 8422 key-stmt = key-keyword sep key-arg-str stmtend 8424 key-arg-str = < a string that matches the rule > 8425 < key-arg > 8427 key-arg = node-identifier *(sep node-identifier) 8429 unique-stmt = unique-keyword sep unique-arg-str stmtend 8431 unique-arg-str = < a string that matches the rule > 8432 < unique-arg > 8434 unique-arg = descendant-schema-nodeid 8435 *(sep descendant-schema-nodeid) 8437 choice-stmt = choice-keyword sep identifier-arg-str optsep 8438 (";" / 8439 "{" stmtsep 8440 ;; these stmts can appear in any order 8441 [when-stmt] 8442 *if-feature-stmt 8443 [default-stmt] 8444 [config-stmt] 8445 [mandatory-stmt] 8446 [status-stmt] 8447 [description-stmt] 8448 [reference-stmt] 8449 *(short-case-stmt / case-stmt) 8450 "}") stmtsep 8452 short-case-stmt = choice-stmt / 8453 container-stmt / 8454 leaf-stmt / 8455 leaf-list-stmt / 8456 list-stmt / 8457 anydata-stmt / 8458 anyxml-stmt 8460 case-stmt = case-keyword sep identifier-arg-str optsep 8461 (";" / 8462 "{" stmtsep 8463 ;; these stmts can appear in any order 8464 [when-stmt] 8465 *if-feature-stmt 8467 [status-stmt] 8468 [description-stmt] 8469 [reference-stmt] 8470 *data-def-stmt 8471 "}") stmtsep 8473 anydata-stmt = anydata-keyword sep identifier-arg-str optsep 8474 (";" / 8475 "{" stmtsep 8476 ;; these stmts can appear in any order 8477 [when-stmt] 8478 *if-feature-stmt 8479 *must-stmt 8480 [config-stmt] 8481 [mandatory-stmt] 8482 [status-stmt] 8483 [description-stmt] 8484 [reference-stmt] 8485 "}") stmtsep 8487 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 8488 (";" / 8489 "{" stmtsep 8490 ;; these stmts can appear in any order 8491 [when-stmt] 8492 *if-feature-stmt 8493 *must-stmt 8494 [config-stmt] 8495 [mandatory-stmt] 8496 [status-stmt] 8497 [description-stmt] 8498 [reference-stmt] 8499 "}") stmtsep 8501 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 8502 (";" / 8503 "{" stmtsep 8504 ;; these stmts can appear in any order 8505 [when-stmt] 8506 *if-feature-stmt 8507 [status-stmt] 8508 [description-stmt] 8509 [reference-stmt] 8510 *refine-stmt 8511 *uses-augment-stmt 8512 "}") stmtsep 8514 refine-stmt = refine-keyword sep refine-arg-str optsep 8515 "{" stmtsep 8516 ;; these stmts can appear in any order 8517 *if-feature-stmt 8518 *must-stmt 8519 [presence-stmt] 8520 *default-stmt 8521 [config-stmt] 8522 [mandatory-stmt] 8523 [min-elements-stmt] 8524 [max-elements-stmt] 8525 [description-stmt] 8526 [reference-stmt] 8527 "}" stmtsep 8529 refine-arg-str = < a string that matches the rule > 8530 < refine-arg > 8532 refine-arg = descendant-schema-nodeid 8534 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 8535 "{" stmtsep 8536 ;; these stmts can appear in any order 8537 [when-stmt] 8538 *if-feature-stmt 8539 [status-stmt] 8540 [description-stmt] 8541 [reference-stmt] 8542 1*(data-def-stmt / case-stmt / 8543 action-stmt / notification-stmt) 8544 "}" stmtsep 8546 uses-augment-arg-str = < a string that matches the rule > 8547 < uses-augment-arg > 8549 uses-augment-arg = descendant-schema-nodeid 8551 augment-stmt = augment-keyword sep augment-arg-str optsep 8552 "{" stmtsep 8553 ;; these stmts can appear in any order 8554 [when-stmt] 8555 *if-feature-stmt 8556 [status-stmt] 8557 [description-stmt] 8558 [reference-stmt] 8559 1*(data-def-stmt / case-stmt / 8560 action-stmt / notification-stmt) 8561 "}" stmtsep 8563 augment-arg-str = < a string that matches the rule > 8564 < augment-arg > 8566 augment-arg = absolute-schema-nodeid 8568 when-stmt = when-keyword sep string optsep 8569 (";" / 8570 "{" stmtsep 8571 ;; these stmts can appear in any order 8572 [description-stmt] 8573 [reference-stmt] 8574 "}") stmtsep 8576 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 8577 (";" / 8578 "{" stmtsep 8579 ;; these stmts can appear in any order 8580 *if-feature-stmt 8581 [status-stmt] 8582 [description-stmt] 8583 [reference-stmt] 8584 *(typedef-stmt / grouping-stmt) 8585 [input-stmt] 8586 [output-stmt] 8587 "}") stmtsep 8589 action-stmt = action-keyword sep identifier-arg-str optsep 8590 (";" / 8591 "{" stmtsep 8592 ;; these stmts can appear in any order 8593 *if-feature-stmt 8594 [status-stmt] 8595 [description-stmt] 8596 [reference-stmt] 8597 *(typedef-stmt / grouping-stmt) 8598 [input-stmt] 8599 [output-stmt] 8600 "}") stmtsep 8602 input-stmt = input-keyword optsep 8603 "{" stmtsep 8604 ;; these stmts can appear in any order 8605 *must-stmt 8606 *(typedef-stmt / grouping-stmt) 8607 1*data-def-stmt 8608 "}" stmtsep 8610 output-stmt = output-keyword optsep 8611 "{" stmtsep 8612 ;; these stmts can appear in any order 8613 *must-stmt 8614 *(typedef-stmt / grouping-stmt) 8615 1*data-def-stmt 8616 "}" stmtsep 8618 notification-stmt = notification-keyword sep 8619 identifier-arg-str optsep 8620 (";" / 8621 "{" stmtsep 8622 ;; these stmts can appear in any order 8623 *if-feature-stmt 8624 *must-stmt 8625 [status-stmt] 8626 [description-stmt] 8627 [reference-stmt] 8628 *(typedef-stmt / grouping-stmt) 8629 *data-def-stmt 8630 "}") stmtsep 8632 deviation-stmt = deviation-keyword sep 8633 deviation-arg-str optsep 8634 "{" stmtsep 8635 ;; these stmts can appear in any order 8636 [description-stmt] 8637 [reference-stmt] 8638 (deviate-not-supported-stmt / 8639 1*(deviate-add-stmt / 8640 deviate-replace-stmt / 8641 deviate-delete-stmt)) 8642 "}" stmtsep 8644 deviation-arg-str = < a string that matches the rule > 8645 < deviation-arg > 8647 deviation-arg = absolute-schema-nodeid 8649 deviate-not-supported-stmt = 8650 deviate-keyword sep 8651 not-supported-keyword-str stmtend 8653 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 8654 (";" / 8655 "{" stmtsep 8656 ;; these stmts can appear in any order 8657 [units-stmt] 8658 *must-stmt 8659 *unique-stmt 8660 *default-stmt 8661 [config-stmt] 8662 [mandatory-stmt] 8663 [min-elements-stmt] 8664 [max-elements-stmt] 8665 "}") stmtsep 8667 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 8668 (";" / 8669 "{" stmtsep 8670 ;; these stmts can appear in any order 8671 [units-stmt] 8672 *must-stmt 8673 *unique-stmt 8674 *default-stmt 8675 "}") stmtsep 8677 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 8678 (";" / 8679 "{" stmtsep 8680 ;; these stmts can appear in any order 8681 [type-stmt] 8682 [units-stmt] 8683 [default-stmt] 8684 [config-stmt] 8685 [mandatory-stmt] 8686 [min-elements-stmt] 8687 [max-elements-stmt] 8688 "}") stmtsep 8690 not-supported-keyword-str = < a string that matches the rule > 8691 < not-supported-keyword > 8693 add-keyword-str = < a string that matches the rule > 8694 < add-keyword > 8696 delete-keyword-str = < a string that matches the rule > 8697 < delete-keyword > 8699 replace-keyword-str = < a string that matches the rule > 8700 < replace-keyword > 8702 ;; represents the usage of an extension statement 8703 unknown-statement = prefix ":" identifier [sep string] optsep 8704 (";" / 8705 "{" optsep 8706 *((yang-stmt / unknown-statement) optsep) 8708 "}") stmtsep 8710 yang-stmt = action-stmt / 8711 anydata-stmt / 8712 anyxml-stmt / 8713 argument-stmt / 8714 augment-stmt / 8715 base-stmt / 8716 belongs-to-stmt / 8717 bit-stmt / 8718 case-stmt / 8719 choice-stmt / 8720 config-stmt / 8721 contact-stmt / 8722 container-stmt / 8723 default-stmt / 8724 description-stmt / 8725 deviate-add-stmt / 8726 deviate-delete-stmt / 8727 deviate-not-supported-stmt / 8728 deviate-replace-stmt / 8729 deviation-stmt / 8730 enum-stmt / 8731 error-app-tag-stmt / 8732 error-message-stmt / 8733 extension-stmt / 8734 feature-stmt / 8735 fraction-digits-stmt / 8736 grouping-stmt / 8737 identity-stmt / 8738 if-feature-stmt / 8739 import-stmt / 8740 include-stmt / 8741 input-stmt / 8742 key-stmt / 8743 leaf-list-stmt / 8744 leaf-stmt / 8745 length-stmt / 8746 list-stmt / 8747 mandatory-stmt / 8748 max-elements-stmt / 8749 min-elements-stmt / 8750 modifier-stmt / 8751 module-stmt / 8752 must-stmt / 8753 namespace-stmt / 8754 notification-stmt / 8755 ordered-by-stmt / 8756 organization-stmt / 8757 output-stmt / 8758 path-stmt / 8759 pattern-stmt / 8760 position-stmt / 8761 prefix-stmt / 8762 presence-stmt / 8763 range-stmt / 8764 reference-stmt / 8765 refine-stmt / 8766 require-instance-stmt / 8767 revision-date-stmt / 8768 revision-stmt / 8769 rpc-stmt / 8770 status-stmt / 8771 submodule-stmt / 8772 typedef-stmt / 8773 type-stmt / 8774 unique-stmt / 8775 units-stmt / 8776 uses-augment-stmt / 8777 uses-stmt / 8778 value-stmt / 8779 when-stmt / 8780 yang-version-stmt / 8781 yin-element-stmt 8783 ;; Ranges 8785 range-arg-str = < a string that matches the rule > 8786 < range-arg > 8788 range-arg = range-part *(optsep "|" optsep range-part) 8790 range-part = range-boundary 8791 [optsep ".." optsep range-boundary] 8793 range-boundary = min-keyword / max-keyword / 8794 integer-value / decimal-value 8796 ;; Lengths 8798 length-arg-str = < a string that matches the rule > 8799 < length-arg > 8801 length-arg = length-part *(optsep "|" optsep length-part) 8803 length-part = length-boundary 8805 [optsep ".." optsep length-boundary] 8807 length-boundary = min-keyword / max-keyword / 8808 non-negative-integer-value 8810 ;; Date 8812 date-arg-str = < a string that matches the rule > 8813 < date-arg > 8815 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 8817 ;; Schema Node Identifiers 8819 schema-nodeid = absolute-schema-nodeid / 8820 descendant-schema-nodeid 8822 absolute-schema-nodeid = 1*("/" node-identifier) 8824 descendant-schema-nodeid = 8825 node-identifier 8826 [absolute-schema-nodeid] 8828 node-identifier = [prefix ":"] identifier 8830 ;; Instance Identifiers 8832 instance-identifier = 1*("/" (node-identifier 8833 [1*key-predicate / 8834 leaf-list-predicate / 8835 pos])) 8837 key-predicate = "[" *WSP key-predicate-expr *WSP "]" 8839 key-predicate-expr = node-identifier *WSP "=" *WSP quoted-string 8841 leaf-list-predicate = "[" *WSP leaf-list-predicate-expr *WSP "]" 8843 leaf-list-predicate-expr = "." *WSP "=" *WSP quoted-string 8845 pos = "[" *WSP positive-integer-value *WSP "]" 8847 quoted-string = (DQUOTE string DQUOTE) / (SQUOTE string SQUOTE) 8849 ;; leafref path 8851 path-arg-str = < a string that matches the rule > 8852 < path-arg > 8854 path-arg = absolute-path / relative-path 8856 absolute-path = 1*("/" (node-identifier *path-predicate)) 8858 relative-path = 1*("../") descendant-path 8860 descendant-path = node-identifier 8861 [*path-predicate absolute-path] 8863 path-predicate = "[" *WSP path-equality-expr *WSP "]" 8865 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 8867 path-key-expr = current-function-invocation *WSP "/" *WSP 8868 rel-path-keyexpr 8870 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 8871 *(node-identifier *WSP "/" *WSP) 8872 node-identifier 8874 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 8876 ;; statement keywords 8877 action-keyword = %s"action" 8878 anydata-keyword = %s"anydata" 8879 anyxml-keyword = %s"anyxml" 8880 argument-keyword = %s"argument" 8881 augment-keyword = %s"augment" 8882 base-keyword = %s"base" 8883 belongs-to-keyword = %s"belongs-to" 8884 bit-keyword = %s"bit" 8885 case-keyword = %s"case" 8886 choice-keyword = %s"choice" 8887 config-keyword = %s"config" 8888 contact-keyword = %s"contact" 8889 container-keyword = %s"container" 8890 default-keyword = %s"default" 8891 description-keyword = %s"description" 8892 enum-keyword = %s"enum" 8893 error-app-tag-keyword = %s"error-app-tag" 8894 error-message-keyword = %s"error-message" 8895 extension-keyword = %s"extension" 8896 deviation-keyword = %s"deviation" 8897 deviate-keyword = %s"deviate" 8898 feature-keyword = %s"feature" 8899 fraction-digits-keyword = %s"fraction-digits" 8900 grouping-keyword = %s"grouping" 8901 identity-keyword = %s"identity" 8902 if-feature-keyword = %s"if-feature" 8903 import-keyword = %s"import" 8904 include-keyword = %s"include" 8905 input-keyword = %s"input" 8906 key-keyword = %s"key" 8907 leaf-keyword = %s"leaf" 8908 leaf-list-keyword = %s"leaf-list" 8909 length-keyword = %s"length" 8910 list-keyword = %s"list" 8911 mandatory-keyword = %s"mandatory" 8912 max-elements-keyword = %s"max-elements" 8913 min-elements-keyword = %s"min-elements" 8914 modifier-keyword = %s"modifier" 8915 module-keyword = %s"module" 8916 must-keyword = %s"must" 8917 namespace-keyword = %s"namespace" 8918 notification-keyword = %s"notification" 8919 ordered-by-keyword = %s"ordered-by" 8920 organization-keyword = %s"organization" 8921 output-keyword = %s"output" 8922 path-keyword = %s"path" 8923 pattern-keyword = %s"pattern" 8924 position-keyword = %s"position" 8925 prefix-keyword = %s"prefix" 8926 presence-keyword = %s"presence" 8927 range-keyword = %s"range" 8928 reference-keyword = %s"reference" 8929 refine-keyword = %s"refine" 8930 require-instance-keyword = %s"require-instance" 8931 revision-keyword = %s"revision" 8932 revision-date-keyword = %s"revision-date" 8933 rpc-keyword = %s"rpc" 8934 status-keyword = %s"status" 8935 submodule-keyword = %s"submodule" 8936 type-keyword = %s"type" 8937 typedef-keyword = %s"typedef" 8938 unique-keyword = %s"unique" 8939 units-keyword = %s"units" 8940 uses-keyword = %s"uses" 8941 value-keyword = %s"value" 8942 when-keyword = %s"when" 8943 yang-version-keyword = %s"yang-version" 8944 yin-element-keyword = %s"yin-element" 8946 ;; other keywords 8947 add-keyword = %s"add" 8948 current-keyword = %s"current" 8949 delete-keyword = %s"delete" 8950 deprecated-keyword = %s"deprecated" 8951 false-keyword = %s"false" 8952 invert-match-keyword = %s"invert-match" 8953 max-keyword = %s"max" 8954 min-keyword = %s"min" 8955 not-supported-keyword = %s"not-supported" 8956 obsolete-keyword = %s"obsolete" 8957 replace-keyword = %s"replace" 8958 system-keyword = %s"system" 8959 true-keyword = %s"true" 8960 unbounded-keyword = %s"unbounded" 8961 user-keyword = %s"user" 8963 and-keyword = %s"and" 8964 or-keyword = %s"or" 8965 not-keyword = %s"not" 8967 current-function-invocation = current-keyword *WSP "(" *WSP ")" 8969 ;;; Basic Rules 8971 prefix-arg-str = < a string that matches the rule > 8972 < prefix-arg > 8974 prefix-arg = prefix 8976 prefix = identifier 8978 identifier-arg-str = < a string that matches the rule > 8979 < identifier-arg > 8981 identifier-arg = identifier 8983 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 8984 identifier = (ALPHA / "_") 8985 *(ALPHA / DIGIT / "_" / "-" / ".") 8987 identifier-ref-arg-str = < a string that matches the rule > 8988 < identifier-ref-arg > 8990 identifier-ref-arg = identifier-ref 8992 identifier-ref = [prefix ":"] identifier 8994 string = < an unquoted string as returned by > 8995 < the scanner, that matches the rule > 8996 < yang-string > 8998 yang-string = *yang-char 9000 ;; any Unicode or ISO/IEC 10646 character including tab, carriage 9001 ;; return, and line feed, but excluding the other C0 control 9002 ;; characters, the surrogate blocks, and the noncharacters. 9003 yang-char = %x09 / %x0A / %x0D / %x20-D7FF / 9004 ; exclude surrogate blocks %xD800-DFFF 9005 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 9006 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 9007 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 9008 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 9009 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 9010 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 9011 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 9012 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 9013 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 9014 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 9015 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 9016 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 9017 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 9018 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 9019 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 9020 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 9021 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 9022 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 9024 integer-value = ("-" non-negative-integer-value) / 9025 non-negative-integer-value 9027 non-negative-integer-value = "0" / positive-integer-value 9029 positive-integer-value = (non-zero-digit *DIGIT) 9031 zero-integer-value = 1*DIGIT 9033 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 9035 sep = 1*(WSP / line-break) 9036 ; unconditional separator 9038 optsep = *(WSP / line-break) 9040 stmtsep = *(WSP / line-break / unknown-statement) 9042 line-break = CRLF / LF 9043 non-zero-digit = %x31-39 9045 decimal-value = integer-value ("." zero-integer-value) 9047 SQUOTE = %x27 9048 ; single quote 9050 ;;; RFC 5234 core rules. 9052 ALPHA = %x41-5A / %x61-7A 9053 ; A-Z / a-z 9055 CR = %x0D 9056 ; carriage return 9058 CRLF = CR LF 9059 ; Internet standard new line 9061 DIGIT = %x30-39 9062 ; 0-9 9064 DQUOTE = %x22 9065 ; double quote 9067 HTAB = %x09 9068 ; horizontal tab 9070 LF = %x0A 9071 ; linefeed 9073 SP = %x20 9074 ; space 9076 WSP = SP / HTAB 9077 ; whitespace 9079 9081 15. NETCONF Error Responses for YANG Related Errors 9083 A number of NETCONF error responses are defined for error cases 9084 related to the data-model handling. If the relevant YANG statement 9085 has an "error-app-tag" substatement, that overrides the default value 9086 specified below. 9088 15.1. Error Message for Data That Violates a unique Statement 9090 If a NETCONF operation would result in configuration data where a 9091 unique constraint is invalidated, the following error MUST be 9092 returned: 9094 error-tag: operation-failed 9095 error-app-tag: data-not-unique 9096 error-info: : Contains an instance identifier that 9097 points to a leaf that invalidates the unique 9098 constraint. This element is present once for each 9099 non-unique leaf. 9101 The element is in the YANG 9102 namespace ("urn:ietf:params:xml:ns:yang:1"). 9104 15.2. Error Message for Data That Violates a max-elements Statement 9106 If a NETCONF operation would result in configuration data where a 9107 list or a leaf-list would have too many entries the following error 9108 MUST be returned: 9110 error-tag: operation-failed 9111 error-app-tag: too-many-elements 9113 This error is returned once, with the error-path identifying the list 9114 node, even if there are more than one extra child present. 9116 15.3. Error Message for Data That Violates a min-elements Statement 9118 If a NETCONF operation would result in configuration data where a 9119 list or a leaf-list would have too few entries the following error 9120 MUST be returned: 9122 error-tag: operation-failed 9123 error-app-tag: too-few-elements 9125 This error is returned once, with the error-path identifying the list 9126 node, even if there are more than one child missing. 9128 15.4. Error Message for Data That Violates a must Statement 9130 If a NETCONF operation would result in configuration data where the 9131 restrictions imposed by a "must" statement is violated the following 9132 error MUST be returned, unless a specific "error-app-tag" 9133 substatement is present for the "must" statement. 9135 error-tag: operation-failed 9136 error-app-tag: must-violation 9138 15.5. Error Message for Data That Violates a require-instance Statement 9140 If a NETCONF operation would result in configuration data where a 9141 leaf of type "instance-identifier" or "leafref" marked with require- 9142 instance "true" refers to a non-existing instance, the following 9143 error MUST be returned: 9145 error-tag: data-missing 9146 error-app-tag: instance-required 9147 error-path: Path to the instance-identifier or leafref leaf. 9149 15.6. Error Message for Data That Violates a mandatory choice Statement 9151 If a NETCONF operation would result in configuration data where no 9152 nodes exists in a mandatory choice, the following error MUST be 9153 returned: 9155 error-tag: data-missing 9156 error-app-tag: missing-choice 9157 error-path: Path to the element with the missing choice. 9158 error-info: : Contains the name of the missing 9159 mandatory choice. 9161 The element is in the YANG 9162 namespace ("urn:ietf:params:xml:ns:yang:1"). 9164 15.7. Error Message for the "insert" Operation 9166 If the "insert" and "key" or "value" attributes are used in an 9167 for a list or leaf-list node, and the "key" or "value" 9168 refers to a non-existing instance, the following error MUST be 9169 returned: 9171 error-tag: bad-attribute 9172 error-app-tag: missing-instance 9174 16. IANA Considerations 9176 This document registers one capability identifier URN from the 9177 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 9179 Index Capability Identifier 9180 ------------- --------------------------------------------------- 9181 :yang-library urn:ietf:params:netconf:capability:yang-library:1.0 9183 17. Security Considerations 9185 This document defines a language with which to write and read 9186 descriptions of management information. The language itself has no 9187 security impact on the Internet. 9189 The same considerations are relevant as for the base NETCONF protocol 9190 (see [RFC6241], Section 9). 9192 Data modeled in YANG might contain sensitive information. RPCs or 9193 notifications defined in YANG might transfer sensitive information. 9195 Security issues are related to the usage of data modeled in YANG. 9196 Such issues shall be dealt with in documents describing the data 9197 models and documents about the interfaces used to manipulate the data 9198 e.g., the NETCONF documents. 9200 Data modeled in YANG is dependent upon: 9202 o the security of the transmission infrastructure used to send 9203 sensitive information. 9205 o the security of applications that store or release such sensitive 9206 information. 9208 o adequate authentication and access control mechanisms to restrict 9209 the usage of sensitive data. 9211 YANG parsers need to be robust with respect to malformed documents. 9212 Reading malformed documents from unknown or untrusted sources could 9213 result in an attacker gaining privileges of the user running the YANG 9214 parser. In an extreme situation, the entire machine could be 9215 compromised. 9217 18. Contributors 9219 The following people all contributed significantly to the initial 9220 YANG document: 9222 - Andy Bierman (YumaWorks) 9223 - Balazs Lengyel (Ericsson) 9224 - David Partain (Ericsson) 9225 - Juergen Schoenwaelder (Jacobs University Bremen) 9226 - Phil Shafer (Juniper Networks) 9228 19. Acknowledgements 9230 The editor wishes to thank the following individuals, who all 9231 provided helpful comments on various versions of this document: 9232 Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, 9233 Ladislav Lhotka, Lionel Morand, Gerhard Muenz, Peyman Owladi, Tom 9234 Petch, Randy Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert 9235 Wijnen, Robert Wilton, and Dale Worley. 9237 20. ChangeLog 9239 RFC Editor: remove this section upon publication as an RFC. 9241 20.1. Version -10 9243 o Made single and double quote characters illegal in unquoted 9244 strings. 9246 o Allow "description" and "reference" in "import" and "include". 9248 o Removed redundant NETCONF Error Message subsection. 9250 o Editorial fixes and clarifications after second WGLC reviews. 9252 20.2. Version -09 9254 o Editorial fixes and clarifications after WGLC reviews. 9256 o when statement context clarification. 9258 o Allow "augment" to add conditionally mandatory nodes (see 9259 Section 7.17). 9261 o Allow non-unique config false leaf-lists. 9263 o Made handling of choice and false "when" expressions non-NETCONF 9264 specific. 9266 o Changed the function signatures for "derived-from" and 9267 "derived-from-or-self". 9269 20.3. Version -08 9271 o Fixes after WGLC reviews. 9273 20.4. Version -07 9275 o Fixes after WG review. 9277 o Included solution Y60-01. 9279 20.5. Version -06 9281 o Included solution Y45-05. 9283 20.6. Version -05 9285 o Included solution Y18-01. 9287 o Included solution Y25-02 (parts of it was included in -04). 9289 o Included solution Y34-05. 9291 o Included solution Y36-03. 9293 20.7. Version -04 9295 o Incorporated changes to ABNF grammar after review and errata for 9296 RFC 6020. 9298 o Included solution Y16-03. 9300 o Included solution Y49-04. 9302 o Included solution Y58-01. 9304 o Included solution Y59-01. 9306 20.8. Version -03 9308 o Incorporated changes from WG reviews. 9310 o Included solution Y05-01. 9312 o Included solution Y10-01. 9314 o Included solution Y13-01. 9316 o Included solution Y28-02. 9318 o Included solution Y55-01 (parts of it was included in -01). 9320 20.9. Version -02 9322 o Included solution Y02-01. 9324 o Included solution Y04-02. 9326 o Included solution Y11-01. 9328 o Included solution Y41-01. 9330 o Included solution Y56-01. 9332 20.10. Version -01 9334 o Included solution Y01-01. 9336 o Included solution Y03-01. 9338 o Included solution Y06-02. 9340 o Included solution Y07-01. 9342 o Included solution Y14-01. 9344 o Included solution Y20-01. 9346 o Included solution Y23-01. 9348 o Included solution Y29-01. 9350 o Included solution Y30-01. 9352 o Included solution Y31-01. 9354 o Included solution Y35-01. 9356 20.11. Version -00 9358 o Applied all reported errata for RFC 6020. 9360 o Updated YANG version to 1.1, and made the "yang-version" statement 9361 mandatory. 9363 21. References 9364 21.1. Normative References 9366 [I-D.ietf-netconf-yang-library] 9367 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 9368 Library", draft-ietf-netconf-yang-library-06 (work in 9369 progress), April 2016. 9371 [ISO.10646] 9372 International Organization for Standardization, 9373 "Information Technology - Universal Multiple-Octet Coded 9374 Character Set (UCS)", ISO Standard 10646:2003, 2003. 9376 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9377 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 9378 RFC2119, March 1997, 9379 . 9381 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 9382 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 9383 2003, . 9385 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9386 Resource Identifier (URI): Generic Syntax", STD 66, RFC 9387 3986, DOI 10.17487/RFC3986, January 2005, 9388 . 9390 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9391 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9392 . 9394 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9395 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 9396 RFC5234, January 2008, 9397 . 9399 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 9400 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 9401 . 9403 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 9404 and A. Bierman, Ed., "Network Configuration Protocol 9405 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 9406 . 9408 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 9409 7405, DOI 10.17487/RFC7405, December 2014, 9410 . 9412 [XML-NAMES] 9413 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 9414 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 9415 Wide Web Consortium Recommendation REC-xml-names-20091208, 9416 December 2009, 9417 . 9419 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 9420 Version 1.0", World Wide Web Consortium Recommendation 9421 REC-xpath-19991116, November 1999, 9422 . 9424 [XSD-TYPES] 9425 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 9426 Second Edition", World Wide Web Consortium Recommendation 9427 REC-xmlschema-2-20041028, October 2004, 9428 . 9430 21.2. Informative References 9432 [I-D.ietf-netconf-restconf] 9433 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 9434 Protocol", draft-ietf-netconf-restconf-13 (work in 9435 progress), April 2016. 9437 [I-D.ietf-netmod-rfc6087bis] 9438 Bierman, A., "Guidelines for Authors and Reviewers of YANG 9439 Data Model Documents", draft-ietf-netmod-rfc6087bis-06 9440 (work in progress), March 2016. 9442 [I-D.ietf-netmod-yang-json] 9443 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 9444 draft-ietf-netmod-yang-json-10 (work in progress), March 9445 2016. 9447 [I-D.vanderstok-core-comi] 9448 Stok, P. and A. Bierman, "CoAP Management Interface", 9449 draft-vanderstok-core-comi-09 (work in progress), March 9450 2016. 9452 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9453 Schoenwaelder, Ed., "Structure of Management Information 9454 Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/ 9455 RFC2578, April 1999, 9456 . 9458 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9459 Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 9460 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 9461 . 9463 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 9464 Structure of Management Information", RFC 3780, DOI 9465 10.17487/RFC3780, May 2004, 9466 . 9468 [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC 9469 Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, 9470 July 2007, . 9472 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 9473 the Network Configuration Protocol (NETCONF)", RFC 6020, 9474 DOI 10.17487/RFC6020, October 2010, 9475 . 9477 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 9478 Information Version 2 (SMIv2) MIB Modules to YANG 9479 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 9480 . 9482 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)", 9483 RFC 6691, DOI 10.17487/RFC6691, July 2012, 9484 . 9486 [XPATH2.0] 9487 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 9488 Kay, M., Robie, J., and J. Simeon, "XML Path Language 9489 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 9490 Recommendation REC-xpath20-20101214, December 2010, 9491 . 9493 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 9494 Wide Web Consortium Recommendation REC-xslt-19991116, 9495 November 1999, 9496 . 9498 Author's Address 9500 Martin Bjorklund (editor) 9501 Tail-f Systems 9503 Email: mbj@tail-f.com