idnits 2.17.1 draft-ietf-netmod-rfc6020bis-12.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 9044 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 (April 28, 2016) is 2913 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 7177 == Unused Reference: 'RFC6691' is defined on line 9341, 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 (-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 (~~), 8 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track April 28, 2016 5 Expires: October 30, 2016 7 The YANG 1.1 Data Modeling Language 8 draft-ietf-netmod-rfc6020bis-12 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 also specifies the YANG mappings 15 to the Network Configuration Protocol (NETCONF). 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on October 30, 2016. 34 Copyright Notice 36 Copyright (c) 2016 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 This document may contain material from IETF Documents or IETF 50 Contributions published or made publicly available before November 51 10, 2008. The person(s) controlling the copyright in some of this 52 material may not have granted the IETF Trust the right to allow 53 modifications of such material outside the IETF Standards Process. 54 Without obtaining an adequate license from the person(s) controlling 55 the copyright in such materials, this document may not be modified 56 outside the IETF Standards Process, and derivative works of it may 57 not be created outside the IETF Standards Process, except to format 58 it for publication as an RFC or to translate it into languages other 59 than English. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 64 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 9 65 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 3.1. A Note on Examples . . . . . . . . . . . . . . . . . . . 14 68 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 69 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 14 70 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 16 71 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 16 72 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 73 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 74 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 21 75 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 22 76 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 23 77 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 24 78 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 25 79 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 26 80 4.2.10. Notification Definitions . . . . . . . . . . . . . . 29 81 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 29 82 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 29 83 5.1.1. Import and Include by Revision . . . . . . . . . . . 31 84 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 32 85 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 33 86 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 33 87 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 34 88 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 34 89 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 34 90 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 35 91 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 35 92 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 35 93 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 36 94 5.6.4. Announcing Conformance Information in NETCONF . . . . 36 95 5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 37 96 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 40 98 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 40 99 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 41 100 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 41 101 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 41 102 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 41 103 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 43 104 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 43 105 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 44 106 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 44 107 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 45 108 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 45 109 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 50 110 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 51 111 7.1. The module Statement . . . . . . . . . . . . . . . . . . 51 112 7.1.1. The module's Substatements . . . . . . . . . . . . . 52 113 7.1.2. The yang-version Statement . . . . . . . . . . . . . 53 114 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 54 115 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 54 116 7.1.5. The import Statement . . . . . . . . . . . . . . . . 54 117 7.1.6. The include Statement . . . . . . . . . . . . . . . . 56 118 7.1.7. The organization Statement . . . . . . . . . . . . . 56 119 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 56 120 7.1.9. The revision Statement . . . . . . . . . . . . . . . 57 121 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 57 122 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 58 123 7.2.1. The submodule's Substatements . . . . . . . . . . . . 59 124 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 60 125 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 61 126 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 61 127 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 62 128 7.3.2. The typedef's type Statement . . . . . . . . . . . . 62 129 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 62 130 7.3.4. The typedef's default Statement . . . . . . . . . . . 62 131 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 63 132 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 63 133 7.4.1. The type's Substatements . . . . . . . . . . . . . . 63 134 7.5. The container Statement . . . . . . . . . . . . . . . . . 63 135 7.5.1. Containers with Presence . . . . . . . . . . . . . . 64 136 7.5.2. The container's Substatements . . . . . . . . . . . . 64 137 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 65 138 7.5.4. The must's Substatements . . . . . . . . . . . . . . 66 139 7.5.5. The presence Statement . . . . . . . . . . . . . . . 67 140 7.5.6. The container's Child Node Statements . . . . . . . . 67 141 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 67 142 7.5.8. NETCONF Operations . . . . . . . . . . 68 143 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 68 144 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 69 145 7.6.1. The leaf's default value . . . . . . . . . . . . . . 69 146 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 70 147 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 71 148 7.6.4. The leaf's default Statement . . . . . . . . . . . . 71 149 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 71 150 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 72 151 7.6.7. NETCONF Operations . . . . . . . . . . 72 152 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 72 153 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 73 154 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 73 155 7.7.2. The leaf-list's default values . . . . . . . . . . . 74 156 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 75 157 7.7.4. The leaf-list's default Statement . . . . . . . . . . 75 158 7.7.5. The min-elements Statement . . . . . . . . . . . . . 76 159 7.7.6. The max-elements Statement . . . . . . . . . . . . . 76 160 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 76 161 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 77 162 7.7.9. NETCONF Operations . . . . . . . . . . 77 163 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 78 164 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 80 165 7.8.1. The list's Substatements . . . . . . . . . . . . . . 80 166 7.8.2. The list's key Statement . . . . . . . . . . . . . . 81 167 7.8.3. The list's unique Statement . . . . . . . . . . . . . 82 168 7.8.4. The list's Child Node Statements . . . . . . . . . . 83 169 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 83 170 7.8.6. NETCONF Operations . . . . . . . . . . 84 171 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 85 172 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 88 173 7.9.1. The choice's Substatements . . . . . . . . . . . . . 88 174 7.9.2. The choice's case Statement . . . . . . . . . . . . . 89 175 7.9.3. The choice's default Statement . . . . . . . . . . . 90 176 7.9.4. The choice's mandatory Statement . . . . . . . . . . 92 177 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 178 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 92 179 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 93 180 7.10.1. The anydata's Substatements . . . . . . . . . . . . 94 181 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 94 182 7.10.3. NETCONF Operations . . . . . . . . . . 94 183 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 95 184 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 95 185 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 96 186 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 96 187 7.11.3. NETCONF Operations . . . . . . . . . . 96 188 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 97 189 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 97 190 7.12.1. The grouping's Substatements . . . . . . . . . . . . 98 191 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 99 192 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 99 193 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 99 194 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 100 195 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 101 196 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 101 197 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 102 198 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 102 199 7.14.2. The input Statement . . . . . . . . . . . . . . . . 103 200 7.14.3. The output Statement . . . . . . . . . . . . . . . . 104 201 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 105 202 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 105 203 7.15. The action Statement . . . . . . . . . . . . . . . . . . 106 204 7.15.1. The action's Substatements . . . . . . . . . . . . . 107 205 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 107 206 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 207 7.16. The notification Statement . . . . . . . . . . . . . . . 109 208 7.16.1. The notification's Substatements . . . . . . . . . . 110 209 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 110 210 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 111 211 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 112 212 7.17.1. The augment's Substatements . . . . . . . . . . . . 114 213 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 115 214 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 115 215 7.18. The identity Statement . . . . . . . . . . . . . . . . . 117 216 7.18.1. The identity's Substatements . . . . . . . . . . . . 117 217 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 117 218 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 118 219 7.19. The extension Statement . . . . . . . . . . . . . . . . . 120 220 7.19.1. The extension's Substatements . . . . . . . . . . . 120 221 7.19.2. The argument Statement . . . . . . . . . . . . . . . 120 222 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 121 223 7.20. Conformance-Related Statements . . . . . . . . . . . . . 122 224 7.20.1. The feature Statement . . . . . . . . . . . . . . . 122 225 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 124 226 7.20.3. The deviation Statement . . . . . . . . . . . . . . 124 227 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 128 228 7.21.1. The config Statement . . . . . . . . . . . . . . . . 128 229 7.21.2. The status Statement . . . . . . . . . . . . . . . . 128 230 7.21.3. The description Statement . . . . . . . . . . . . . 129 231 7.21.4. The reference Statement . . . . . . . . . . . . . . 129 232 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 130 233 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 131 234 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 131 235 8.2. Configuration Data Modifications . . . . . . . . . . . . 132 236 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 132 237 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 132 238 8.3.2. NETCONF Processing . . . . . . . . . . 133 239 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 134 240 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 134 241 9.1. Canonical Representation . . . . . . . . . . . . . . . . 134 242 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 135 243 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 135 244 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 136 245 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 136 246 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 136 247 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 248 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 137 249 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 138 250 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 138 251 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 252 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 138 253 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 139 254 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 139 255 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 139 256 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 140 257 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 140 258 9.4.4. The length Statement . . . . . . . . . . . . . . . . 140 259 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 141 260 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 141 261 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 141 262 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 143 263 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 143 264 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 143 265 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 143 266 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 143 267 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 143 268 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 143 269 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 143 270 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 143 271 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 145 272 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 146 273 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 274 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 146 275 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 147 276 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 147 277 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 148 278 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 149 279 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149 280 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 149 281 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 149 282 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 149 283 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 284 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 150 285 9.9.3. The require-instance Statement . . . . . . . . . . . 150 286 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 151 287 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 151 288 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 151 289 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 155 290 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 155 291 9.10.2. The identityref's base Statement . . . . . . . . . . 155 292 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 155 293 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 156 294 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 156 295 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 157 296 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 157 297 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 157 298 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 157 299 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 157 300 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 158 301 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 302 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 158 303 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 304 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 305 9.13. The instance-identifier Built-In Type . . . . . . . . . . 159 306 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 160 307 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 160 308 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 160 309 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 161 310 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 161 311 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 161 312 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 161 313 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 162 314 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 162 315 10.3. Functions for the YANG Types "leafref" and "instance- 316 identifier" . . . . . . . . . . . . . . . . . . . . . . 163 317 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 163 318 10.4. Functions for the YANG Type "identityref" . . . . . . . 164 319 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 164 320 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 165 321 10.5. Functions for the YANG Type "enumeration" . . . . . . . 166 322 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 166 323 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 167 324 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 167 325 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 168 326 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 170 327 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 328 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 171 329 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 174 330 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 175 331 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 199 332 15.1. Error Message for Data That Violates a unique Statement 199 333 15.2. Error Message for Data That Violates a max-elements 334 Statement . . . . . . . . . . . . . . . . . . . . . . . 200 335 15.3. Error Message for Data That Violates a min-elements 336 Statement . . . . . . . . . . . . . . . . . . . . . . . 200 337 15.4. Error Message for Data That Violates a must Statement . 200 338 15.5. Error Message for Data That Violates a require-instance 339 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 340 15.6. Error Message for Data That Violates a mandatory choice 341 Statement . . . . . . . . . . . . . . . . . . . . . . . 201 342 15.7. Error Message for the "insert" Operation . . . . . . . . 201 343 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 201 344 17. Security Considerations . . . . . . . . . . . . . . . . . . . 201 345 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 202 346 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 202 347 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 203 348 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 203 349 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 203 350 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 203 351 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 203 352 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 203 353 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 204 354 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 204 355 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 204 356 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 204 357 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 205 358 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 205 359 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 205 360 21.1. Normative References . . . . . . . . . . . . . . . . . . 205 361 21.2. Informative References . . . . . . . . . . . . . . . . . 207 362 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 208 364 1. Introduction 366 YANG is a data modeling language originally designed to model 367 configuration and state data manipulated by the Network Configuration 368 Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF 369 notifications [RFC6241]. Since the publication of YANG version 1 370 [RFC6020], YANG has been used or proposed to be used for other 371 protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI 372 [I-D.vanderstok-core-comi]). Further, other encodings than XML have 373 been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). 375 This document describes the syntax and semantics of version 1.1 of 376 the YANG language. It also describes how a data model defined in a 377 YANG module is encoded in the Extensible Markup Language (XML), and 378 how NETCONF operations are used to manipulate the data. Other 379 protocols and encodings are possible, but out of scope for this 380 specification. 382 1.1. Summary of Changes from RFC 6020 384 This document defines version 1.1 of the YANG language. YANG version 385 1.1 is a maintenance release of the YANG language, addressing 386 ambiguities and defects in the original specification [RFC6020]. 388 The following changes are not backwards compatible with YANG version 389 1: 391 o Changed the rules for the interpretation of escaped characters in 392 double quoted strings. This is an backwards incompatible change 393 from YANG version 1. A module that uses a character sequence that 394 is now illegal must change the string to match the new rules. See 395 Section 6.1.3 for details. 397 o An unquoted string cannot contain any single or double quote 398 characters. This is an backwards incompatible change from YANG 399 version 1. 401 The following additional changes have been done to YANG: 403 o Changed the YANG version from "1" to "1.1". 405 o Made the "yang-version" statement mandatory. 407 o Made noncharacters illegal in the built-in type "string". 409 o Defined the legal characters in YANG modules. 411 o Extended the "if-feature" syntax to be a boolean expression over 412 feature names. 414 o Allow "if-feature" in "bit", "enum", and "identity". 416 o Allow "if-feature" in "refine". 418 o Made "when" and "if-feature" illegal on list keys. 420 o Allow "choice" as a shorthand case statement (see Section 7.9). 422 o Added a new substatement "modifier" to pattern (see 423 Section 9.4.6). 425 o Allow "must" in "input", "output", and "notification". 427 o Allow "require-instance" in leafref. 429 o Allow "description" and "reference" in "import" and "include". 431 o Allow imports of multiple revisions of a module. 433 o Allow "augment" to add conditionally mandatory nodes (see 434 Section 7.17). 436 o Added a set of new XPath functions in Section 10. 438 o Clarified the XPath context's tree in Section 6.4.1. 440 o Defined the string value of an identityref in XPath expressions 441 (see Section 9.10). 443 o Clarified what unprefixed names mean in leafrefs in typedefs (see 444 Section 6.4.1 and Section 9.9.2). 446 o Allow identities to be derived from multiple base identities (see 447 Section 7.18 and Section 9.10). 449 o Allow enumerations and bits to be subtyped (see Section 9.6 and 450 Section 9.7). 452 o Allow leaf-lists to have default values (see Section 7.7.2). 454 o Allow non-unique values in non-configuration leaf-lists (see 455 Section 7.7). 457 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 459 o Changed the module advertisement mechanism (see Section 5.6.4). 461 o Changed the scoping rules for definitions in submodules. A 462 submodule can now reference all definitions in all submodules that 463 belong to the same module, without using the "include" statement. 465 o Added a new statement "action" that is used to define operations 466 tied to data nodes. 468 o Allow notifications to be tied to data nodes. 470 o Added a new data definition statement "anydata" (see Section 7.10) 471 which is RECOMMENDED to be used instead of "anyxml" when the data 472 can be modeled in YANG 474 o Allow types empty and leafref in unions. 476 o Allow type empty in a key. 478 The following changes have been done to the NETCONF mapping: 480 o A server advertises support for YANG 1.1 modules by using ietf- 481 yang-library [I-D.ietf-netconf-yang-library] instead of listing 482 them as capabilities in the message. 484 2. Keywords 486 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 487 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 488 "OPTIONAL" in this document are to be interpreted as described in BCP 489 14, [RFC2119]. 491 3. Terminology 493 The following terms are used within this document: 495 o action: An operation defined for a node in the data tree. 497 o anydata: A data node that can contain an unknown set of nodes that 498 can be modelled by YANG, except anyxml. 500 o anyxml: A data node that can contain an unknown chunk of XML data. 502 o augment: Adds new schema nodes to a previously defined schema 503 node. 505 o base type: The type from which a derived type was derived, which 506 may be either a built-in type or another derived type. 508 o built-in type: A YANG data type defined in the YANG language, such 509 as uint32 or string. 511 o choice: A schema node where only one of a number of identified 512 alternatives is valid. 514 o client: An entity that can access YANG-defined data on a server, 515 over some network management protocol. 517 o conformance: A measure of how accurately a server follows a data 518 model. 520 o container: An interior data node that exists in at most one 521 instance in the data tree. A container has no value, but rather a 522 set of child nodes. 524 o data definition statement: A statement that defines new data 525 nodes. One of container, leaf, leaf-list, list, choice, case, 526 augment, uses, anydata, and anyxml. 528 o data model: A data model describes how data is represented and 529 accessed. 531 o data node: A node in the schema tree that can be instantiated in a 532 data tree. One of container, leaf, leaf-list, list, anydata, and 533 anyxml. 535 o data tree: An instantiated tree of any data modeled with YANG, 536 e.g., configuration data, state data, combined configuration and 537 state data, RPC or action input, RPC or action output, or 538 notification. 540 o derived type: A type that is derived from a built-in type (such as 541 uint32), or another derived type. 543 o extension: An extension attaches non-YANG semantics to statements. 544 The extension statement defines new statements to express these 545 semantics. 547 o feature: A mechanism for marking a portion of the model as 548 optional. Definitions can be tagged with a feature name and are 549 only valid on servers that support that feature. 551 o grouping: A reusable set of schema nodes, which may be used 552 locally in the module and by other modules that import from it. 553 The grouping statement is not a data definition statement and, as 554 such, does not define any nodes in the schema tree. 556 o identifier: Used to identify different kinds of YANG items by 557 name. 559 o identity: A globally unique, abstract, and untyped name. 561 o instance identifier: A mechanism for identifying a particular node 562 in a data tree. 564 o interior node: Nodes within a hierarchy that are not leaf nodes. 566 o leaf: A data node that exists in at most one instance in the data 567 tree. A leaf has a value but no child nodes. 569 o leaf-list: Like the leaf node but defines a set of uniquely 570 identifiable nodes rather than a single node. Each node has a 571 value but no child nodes. 573 o list: An interior data node that may exist in multiple instances 574 in the data tree. A list has no value, but rather a set of child 575 nodes. 577 o mandatory node: A mandatory node is one of: 579 * A leaf, choice, anydata, or anyxml node with a "mandatory" 580 statement with the value "true". 582 * A list or leaf-list node with a "min-elements" statement with a 583 value greater than zero. 585 * A container node without a "presence" statement, which has at 586 least one mandatory node as a child. 588 o module: A YANG module defines a hierarchy of schema nodes. With 589 its definitions and the definitions it imports or includes from 590 elsewhere, a module is self-contained and "compilable". 592 o RPC: A Remote Procedure Call. 594 o RPC operation: A specific Remote Procedure Call. 596 o schema node: A node in the schema tree. One of action, container, 597 leaf, leaf-list, list, choice, case, rpc, input, output, 598 notification, anydata, and anyxml. 600 o schema node identifier: A mechanism for identifying a particular 601 node in the schema tree. 603 o schema tree: The definition hierarchy specified within a module. 605 o server: An entity that provides access to YANG-defined data to a 606 client, over some network management protocol. 608 o server deviation: A failure of the server to implement a module 609 faithfully. 611 o submodule: A partial module definition that contributes derived 612 types, groupings, data nodes, RPCs, actions, and notifications to 613 a module. A YANG module can be constructed from a number of 614 submodules. 616 o top-level data node: A data node where there is no other data node 617 between it and a module or submodule statement. 619 o uses: The "uses" statement is used to instantiate the set of 620 schema nodes defined in a grouping statement. The instantiated 621 nodes may be refined and augmented to tailor them to any specific 622 needs. 624 The following terms are defined in [RFC6241]: 626 o configuration data 628 o configuration datastore 630 o datastore 632 o state data 634 When modelled with YANG, a datastore is realized as an instantiated 635 data tree. 637 When modelled with YANG, a configuration datastore is realized as an 638 instantiated data tree with configuration data. 640 3.1. A Note on Examples 642 Throughout this document there are many examples of YANG statements. 643 These examples are supposed to illustrate certain features, and are 644 not supposed to be complete, valid YANG modules. 646 4. YANG Overview 648 This non-normative section is intended to give a high-level overview 649 of YANG to first-time readers. 651 4.1. Functional Overview 653 YANG is a language originally designed to model data for the NETCONF 654 protocol. A YANG module defines a hierarchy of data that can be used 655 for NETCONF-based operations, including configuration, state data, 656 Remote Procedure Calls (RPCs), and notifications. This allows a 657 complete description of all data sent between a NETCONF client and 658 server. Although out of scope for this specification, YANG can also 659 be used with other protocols than NETCONF. 661 YANG models the hierarchical organization of data as a tree in which 662 each node has a name, and either a value or a set of child nodes. 663 YANG provides clear and concise descriptions of the nodes, as well as 664 the interaction between those nodes. 666 YANG structures data models into modules and submodules. A module 667 can import data from other external modules, and include data from 668 submodules. The hierarchy can be augmented, allowing one module to 669 add data nodes to the hierarchy defined in another module. This 670 augmentation can be conditional, with new nodes appearing only if 671 certain conditions are met. 673 YANG data models can describe constraints to be enforced on the data, 674 restricting the presence or value of nodes based on the presence or 675 value of other nodes in the hierarchy. These constraints are 676 enforceable by either the client or the server, and valid content 677 MUST abide by them. 679 YANG defines a set of built-in types, and has a type mechanism 680 through which additional types may be defined. Derived types can 681 restrict their base type's set of valid values using mechanisms like 682 range or pattern restrictions that can be enforced by clients or 683 servers. They can also define usage conventions for use of the 684 derived type, such as a string-based type that contains a host name. 686 YANG permits the definition of reusable groupings of nodes. The 687 instantiation of these groupings can refine or augment the nodes, 688 allowing it to tailor the nodes to its particular needs. Derived 689 types and groupings can be defined in one module and used in either 690 the same module or in another module that imports it. 692 YANG data hierarchy constructs include defining lists where list 693 entries are identified by keys that distinguish them from each other. 694 Such lists may be defined as either sorted by user or automatically 695 sorted by the system. For user-sorted lists, operations are defined 696 for manipulating the order of the list entries. 698 YANG modules can be translated into an equivalent XML syntax called 699 YANG Independent Notation (YIN) (Section 13), allowing applications 700 using XML parsers and Extensible Stylesheet Language Transformations 701 (XSLT) scripts to operate on the models. The conversion from YANG to 702 YIN is lossless, so content in YIN can be round-tripped back into 703 YANG. 705 YANG strikes a balance between high-level data modeling and low-level 706 bits-on-the-wire encoding. The reader of a YANG module can see the 707 high-level view of the data model while understanding how the data 708 will be encoded on-the-wire. 710 YANG is an extensible language, allowing extension statements to be 711 defined by standards bodies, vendors, and individuals. The statement 712 syntax allows these extensions to coexist with standard YANG 713 statements in a natural way, while extensions in a YANG module stand 714 out sufficiently for the reader to notice them. 716 YANG resists the tendency to solve all possible problems, limiting 717 the problem space to allow expression of data models for network 718 management protocols such as NETCONF, not arbitrary XML documents or 719 arbitrary data models. 721 To the extent possible, YANG maintains compatibility with Simple 722 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 723 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 724 can be automatically translated into YANG modules for read-only 725 access [RFC6643]. However, YANG is not concerned with reverse 726 translation from YANG to SMIv2. 728 4.2. Language Overview 730 This section introduces some important constructs used in YANG that 731 will aid in the understanding of the language specifics in later 732 sections. 734 4.2.1. Modules and Submodules 736 A module contains three types of statements: module-header 737 statements, revision statements, and definition statements. The 738 module header statements describe the module and give information 739 about the module itself, the revision statements give information 740 about the history of the module, and the definition statements are 741 the body of the module where the data model is defined. 743 A server may implement a number of modules, allowing multiple views 744 of the same data, or multiple views of disjoint subsections of the 745 server's data. Alternatively, the server may implement only one 746 module that defines all available data. 748 A module may be divided into submodules, based on the needs of the 749 module owner. The external view remains that of a single module, 750 regardless of the presence or size of its submodules. 752 The "import" statement allows a module or submodule to reference 753 material defined in other modules. 755 The "include" statement is used by a module to incorporate the 756 contents of its submodules into the module. 758 4.2.2. Data Modeling Basics 760 YANG defines four main types of data nodes for data modeling. In 761 each of the following subsections, the examples show the YANG syntax 762 as well as a corresponding XML encoding. 764 4.2.2.1. Leaf Nodes 766 A leaf instance contains simple data like an integer or a string. It 767 has exactly one value of a particular type and no child nodes. 769 YANG Example: 771 leaf host-name { 772 type string; 773 description 774 "Hostname for this system"; 775 } 777 XML Encoding Example: 779 my.example.com 781 The "leaf" statement is covered in Section 7.6. 783 4.2.2.2. Leaf-List Nodes 785 A leaf-list defines a sequence of values of a particular type. 787 YANG Example: 789 leaf-list domain-search { 790 type string; 791 description 792 "List of domain names to search"; 793 } 795 XML Encoding Example: 797 high.example.com 798 low.example.com 799 everywhere.example.com 801 The "leaf-list" statement is covered in Section 7.7. 803 4.2.2.3. Container Nodes 805 A container is used to group related nodes in a subtree. A container 806 has only child nodes and no value. A container may contain any 807 number of child nodes of any type (leafs, lists, containers, leaf- 808 lists, actions, and notifications). 810 YANG Example: 812 container system { 813 container login { 814 leaf message { 815 type string; 816 description 817 "Message given at start of login session"; 818 } 819 } 820 } 822 XML Encoding Example: 824 825 826 Good morning 827 828 830 The "container" statement is covered in Section 7.5. 832 4.2.2.4. List Nodes 834 A list defines a sequence of list entries. Each entry is like a 835 structure or a record instance, and is uniquely identified by the 836 values of its key leafs. A list can define multiple key leafs and 837 may contain any number of child nodes of any type (including leafs, 838 lists, containers etc.). 840 YANG Example: 842 list user { 843 key "name"; 844 leaf name { 845 type string; 846 } 847 leaf full-name { 848 type string; 849 } 850 leaf class { 851 type string; 852 } 853 } 855 XML Encoding Example: 857 858 glocks 859 Goldie Locks 860 intruder 861 862 863 snowey 864 Snow White 865 free-loader 866 867 868 rzell 869 Rapun Zell 870 tower 871 873 The "list" statement is covered in Section 7.8. 875 4.2.2.5. Example Module 877 These statements are combined to define the module: 879 // Contents of "example-system.yang" 880 module example-system { 881 yang-version 1.1; 882 namespace "urn:example:system"; 883 prefix "sys"; 885 organization "Example Inc."; 886 contact "joe@example.com"; 887 description 888 "The module for entities implementing the Example system."; 890 revision 2007-06-09 { 891 description "Initial revision."; 892 } 894 container system { 895 leaf host-name { 896 type string; 897 description 898 "Hostname for this system"; 899 } 901 leaf-list domain-search { 902 type string; 903 description 904 "List of domain names to search"; 906 } 908 container login { 909 leaf message { 910 type string; 911 description 912 "Message given at start of login session"; 913 } 915 list user { 916 key "name"; 917 leaf name { 918 type string; 919 } 920 leaf full-name { 921 type string; 922 } 923 leaf class { 924 type string; 925 } 926 } 927 } 928 } 929 } 931 4.2.3. State Data 933 YANG can model state data, as well as configuration data, based on 934 the "config" statement. When a node is tagged with "config false", 935 its subhierarchy is flagged as state data. In NETCONF, state data is 936 reported using the operation, not the operation. 937 Parent containers, lists, and key leafs are reported also, giving the 938 context for the state data. 940 In this example, two leafs are defined for each interface, a 941 configured speed and an observed speed. The observed speed is not 942 configuration, so it can be returned with NETCONF operations, 943 but not with operations. The observed speed is not 944 configuration data, and it cannot be manipulated using . 946 list interface { 947 key "name"; 949 leaf name { 950 type string; 951 } 952 leaf speed { 953 type enumeration { 954 enum 10m; 955 enum 100m; 956 enum auto; 957 } 958 } 959 leaf observed-speed { 960 type uint32; 961 config false; 962 } 963 } 965 4.2.4. Built-In Types 967 YANG has a set of built-in types, similar to those of many 968 programming languages, but with some differences due to special 969 requirements from the management domain. The following table 970 summarizes the built-in types discussed in Section 9: 972 +---------------------+-------------------------------------+ 973 | Name | Description | 974 +---------------------+-------------------------------------+ 975 | binary | Any binary data | 976 | bits | A set of bits or flags | 977 | boolean | "true" or "false" | 978 | decimal64 | 64-bit signed decimal number | 979 | empty | A leaf that does not have any value | 980 | enumeration | Enumerated strings | 981 | identityref | A reference to an abstract identity | 982 | instance-identifier | A reference a data tree node | 983 | int8 | 8-bit signed integer | 984 | int16 | 16-bit signed integer | 985 | int32 | 32-bit signed integer | 986 | int64 | 64-bit signed integer | 987 | leafref | A reference to a leaf instance | 988 | string | Human-readable string | 989 | uint8 | 8-bit unsigned integer | 990 | uint16 | 16-bit unsigned integer | 991 | uint32 | 32-bit unsigned integer | 992 | uint64 | 64-bit unsigned integer | 993 | union | Choice of member types | 994 +---------------------+-------------------------------------+ 996 The "type" statement is covered in Section 7.4. 998 4.2.5. Derived Types (typedef) 1000 YANG can define derived types from base types using the "typedef" 1001 statement. A base type can be either a built-in type or a derived 1002 type, allowing a hierarchy of derived types. 1004 A derived type can be used as the argument for the "type" statement. 1006 YANG Example: 1008 typedef percent { 1009 type uint8 { 1010 range "0 .. 100"; 1011 } 1012 } 1014 leaf completed { 1015 type percent; 1016 } 1018 XML Encoding Example: 1020 20 1022 The "typedef" statement is covered in Section 7.3. 1024 4.2.6. Reusable Node Groups (grouping) 1026 Groups of nodes can be assembled into reusable collections using the 1027 "grouping" statement. A grouping defines a set of nodes that are 1028 instantiated with the "uses" statement: 1030 grouping target { 1031 leaf address { 1032 type inet:ip-address; 1033 description "Target IP address"; 1034 } 1035 leaf port { 1036 type inet:port-number; 1037 description "Target port number"; 1038 } 1039 } 1041 container peer { 1042 container destination { 1043 uses target; 1044 } 1045 } 1047 XML Encoding Example: 1049 1050 1051
2001:db8::2
1052 830 1053 1054 1056 The grouping can be refined as it is used, allowing certain 1057 statements to be overridden. In this example, the description is 1058 refined: 1060 container connection { 1061 container source { 1062 uses target { 1063 refine "address" { 1064 description "Source IP address"; 1065 } 1066 refine "port" { 1067 description "Source port number"; 1068 } 1069 } 1070 } 1071 container destination { 1072 uses target { 1073 refine "address" { 1074 description "Destination IP address"; 1075 } 1076 refine "port" { 1077 description "Destination port number"; 1078 } 1079 } 1080 } 1081 } 1083 The "grouping" statement is covered in Section 7.12. 1085 4.2.7. Choices 1087 YANG allows the data model to segregate incompatible nodes into 1088 distinct choices using the "choice" and "case" statements. The 1089 "choice" statement contains a set of "case" statements that define 1090 sets of schema nodes that cannot appear together. Each "case" may 1091 contain multiple nodes, but each node may appear in only one "case" 1092 under a "choice". 1094 When a node from one case is created in the data tree, all nodes from 1095 all other cases are implicitly deleted. The server handles the 1096 enforcement of the constraint, preventing incompatibilities from 1097 existing in the configuration. 1099 The choice and case nodes appear only in the schema tree but not in 1100 the data tree. The additional levels of hierarchy are not needed 1101 beyond the conceptual schema. 1103 YANG Example: 1105 container food { 1106 choice snack { 1107 case sports-arena { 1108 leaf pretzel { 1109 type empty; 1110 } 1111 leaf beer { 1112 type empty; 1113 } 1114 } 1115 case late-night { 1116 leaf chocolate { 1117 type enumeration { 1118 enum dark; 1119 enum milk; 1120 enum first-available; 1121 } 1122 } 1123 } 1124 } 1125 } 1127 XML Encoding Example: 1129 1130 1131 1132 1134 The "choice" statement is covered in Section 7.9. 1136 4.2.8. Extending Data Models (augment) 1138 YANG allows a module to insert additional nodes into data models, 1139 including both the current module (and its submodules) or an external 1140 module. This is useful for example for vendors to add vendor- 1141 specific parameters to standard data models in an interoperable way. 1143 The "augment" statement defines the location in the data model 1144 hierarchy where new nodes are inserted, and the "when" statement 1145 defines the conditions when the new nodes are valid. 1147 YANG Example: 1149 augment /system/login/user { 1150 when "class != 'wheel'"; 1151 leaf uid { 1152 type uint16 { 1153 range "1000 .. 30000"; 1154 } 1155 } 1156 } 1158 This example defines a "uid" node that only is valid when the user's 1159 "class" is not "wheel". 1161 If a module augments another module, the XML encoding of the data 1162 will reflect the prefix of the augmenting module. For example, if 1163 the above augmentation were in a module with prefix "other", the XML 1164 would look like: 1166 XML Encoding Example: 1168 1169 alicew 1170 Alice N. Wonderland 1171 drop-out 1172 1024 1173 1175 The "augment" statement is covered in Section 7.17. 1177 4.2.9. Operation Definitions 1179 YANG allows the definition of operations. The operations' name, 1180 input parameters, and output parameters are modeled using YANG data 1181 definition statements. Operations on the top-level in a module are 1182 defined with the "rpc" statement. Operations can also be tied to a 1183 container or list data node. Such operations are defined with the 1184 "action" statement. 1186 YANG Example: 1188 rpc activate-software-image { 1189 input { 1190 leaf image-name { 1191 type string; 1192 } 1193 } 1194 output { 1195 leaf status { 1196 type string; 1197 } 1198 } 1199 } 1201 NETCONF XML Example: 1203 1205 1206 example-fw-2.3 1207 1208 1210 1212 1213 The image example-fw-2.3 is being installed. 1214 1215 1217 YANG Example: 1219 list interface { 1220 key "name"; 1222 leaf name { 1223 type string; 1224 } 1226 action ping { 1227 input { 1228 leaf destination { 1229 type inet:ip-address; 1230 } 1231 } 1232 output { 1233 leaf packet-loss { 1234 type uint8; 1235 } 1236 } 1237 } 1238 } 1240 NETCONF XML Example: 1242 1244 1245 1246 eth1 1247 1248 192.0.2.1 1249 1250 1251 1252 1254 1257 60 1258 1260 The "rpc" statement is covered in Section 7.14, and the "action" 1261 statement in Section 7.15. 1263 4.2.10. Notification Definitions 1265 YANG allows the definition of notifications. YANG data definition 1266 statements are used to model the content of the notification. 1268 YANG Example: 1270 notification link-failure { 1271 description 1272 "A link failure has been detected"; 1273 leaf if-name { 1274 type leafref { 1275 path "/interface/name"; 1276 } 1277 } 1278 leaf if-admin-status { 1279 type admin-status; 1280 } 1281 leaf if-oper-status { 1282 type oper-status; 1283 } 1284 } 1286 NETCONF XML Example: 1288 1290 2007-09-01T10:00:00Z 1291 1292 so-1/2/3.0 1293 up 1294 down 1295 1296 1298 The "notification" statement is covered in Section 7.16. 1300 5. Language Concepts 1302 5.1. Modules and Submodules 1304 The module is the base unit of definition in YANG. A module defines 1305 a single data model. A module can define a complete, cohesive model, 1306 or augment an existing data model with additional nodes. 1308 Submodules are partial modules that contribute definitions to a 1309 module. A module may include any number of submodules, but each 1310 submodule may belong to only one module. 1312 Developers of YANG modules and submodules are RECOMMENDED to choose 1313 names for their modules that will have a low probability of colliding 1314 with standard or other enterprise modules, e.g., by using the 1315 enterprise or organization name as a prefix for the module name. 1316 Within a server, all module names MUST be unique. 1318 A module uses the "include" statement to include all its submodules, 1319 and the "import" statement to reference external modules. Similarly, 1320 a submodule uses the "import" statement to reference other modules. 1322 For backward compatibility with YANG version 1, a submodule is 1323 allowed to use the "include" statement to reference other submodules 1324 within its module, but this is not necessary in YANG version 1.1. A 1325 submodule can reference any definition in the module it belongs to 1326 and in all submodules included by the module. A submodule MUST NOT 1327 include different revisions of other submodules than the revisions 1328 that its module includes. 1330 A module or submodule MUST NOT include submodules from other modules, 1331 and a submodule MUST NOT import its own module. 1333 The import and include statements are used to make definitions 1334 available from other modules: 1336 o For a module or submodule to reference definitions in an external 1337 module, the external module MUST be imported. 1339 o A module MUST include all its submodules. 1341 o A module, or submodule belonging to that module, can reference 1342 definitions in the module and all submodules included by the 1343 module. 1345 There MUST NOT be any circular chains of imports. For example, if 1346 module "a" imports module "b", "b" cannot import "a". 1348 When a definition in an external module is referenced, a locally 1349 defined prefix MUST be used, followed by ":", and then the external 1350 identifier. References to definitions in the local module MAY use 1351 the prefix notation. Since built-in data types do not belong to any 1352 module and have no prefix, references to built-in data types (e.g., 1353 int32) cannot use the prefix notation. The syntax for a reference to 1354 a definition is formally defined by the rule "identifier-ref" in 1355 Section 14. 1357 5.1.1. Import and Include by Revision 1359 Published modules evolve independently over time. In order to allow 1360 for this evolution, modules can be imported using specific revisions. 1361 When a module is written, it can import the current revisions of 1362 other modules, based on what is available at the time. As future 1363 revisions of the imported modules are published, the importing module 1364 is unaffected and its contents are unchanged. When the author of the 1365 module is prepared to move to the most recently published revision of 1366 an imported module, the module is republished with an updated 1367 "import" statement. By republishing with the new revision, the 1368 authors explicitly indicate their acceptance of any changes in the 1369 imported module. 1371 For submodules, the issue is related but simpler. A module or 1372 submodule that includes submodules needs to specify the revision of 1373 the included submodules. If a submodule changes, any module or 1374 submodule that includes it needs to be updated. 1376 For example, module "b" imports module "a". 1378 module a { 1379 yang-version 1.1; 1380 namespace "urn:example:a"; 1381 prefix "a"; 1383 revision 2008-01-01 { ... } 1384 grouping a { 1385 leaf eh { .... } 1386 } 1387 } 1389 module b { 1390 yang-version 1.1; 1391 namespace "urn:example:b"; 1392 prefix "b"; 1394 import a { 1395 prefix "p"; 1396 revision-date 2008-01-01; 1397 } 1399 container bee { 1400 uses p:a; 1401 } 1402 } 1404 When the author of "a" publishes a new revision, the changes may not 1405 be acceptable to the author of "b". If the new revision is 1406 acceptable, the author of "b" can republish with an updated revision 1407 in the "import" statement. 1409 If a module is not imported with a specific revision, it is undefined 1410 which exact revision is used. 1412 5.1.2. Module Hierarchies 1414 YANG allows modeling of data in multiple hierarchies, where data may 1415 have more than one top-level node. Models that have multiple top- 1416 level nodes are sometimes convenient, and are supported by YANG. 1418 5.1.2.1. NETCONF XML Encoding 1420 NETCONF is capable of carrying any XML content as the payload in the 1421 and elements. The top-level nodes of YANG modules 1422 are encoded as child elements, in any order, within these elements. 1423 This encapsulation guarantees that the corresponding NETCONF messages 1424 are always well-formed XML documents. 1426 For example: 1428 module example-config { 1429 yang-version 1.1; 1430 namespace "urn:example:config"; 1431 prefix "co"; 1433 container system { ... } 1434 container routing { ... } 1435 } 1437 could be encoded in NETCONF as: 1439 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1457 5.2. File Layout 1459 YANG modules and submodules are typically stored in files, one module 1460 or submodule per file. The name of the file SHOULD be of the form: 1462 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1464 YANG parsers can find imported modules and included submodules via 1465 this convention. 1467 5.3. XML Namespaces 1469 All YANG definitions are specified within a module that is bound to a 1470 particular XML namespace [XML-NAMES], which is a globally unique URI 1471 [RFC3986]. A NETCONF client or server uses the namespace during XML 1472 encoding of data. 1474 XML namespaces for modules published in RFC streams [RFC4844] MUST be 1475 assigned by IANA, see section 14 in [RFC6020]. 1477 XML namespaces for private modules are assigned by the organization 1478 owning the module without a central registry. Namespace URIs MUST be 1479 chosen so they cannot collide with standard or other enterprise 1480 namespaces, for example by using the enterprise or organization name 1481 in the namespace. 1483 The "namespace" statement is covered in Section 7.1.3. 1485 5.3.1. YANG XML Namespace 1487 YANG defines an XML namespace for NETCONF operations, 1488 content, and the element. The name of this 1489 namespace is "urn:ietf:params:xml:ns:yang:1". 1491 5.4. Resolving Grouping, Type, and Identity Names 1493 Grouping, type, and identity names are resolved in the context in 1494 which they are defined, rather than the context in which they are 1495 used. Users of groupings, typedefs, and identities are not required 1496 to import modules or include submodules to satisfy all references 1497 made by the original definition. This behaves like static scoping in 1498 a conventional programming language. 1500 For example, if a module defines a grouping in which a type is 1501 referenced, when the grouping is used in a second module, the type is 1502 resolved in the context of the original module, not the second 1503 module. There is no worry over conflicts if both modules define the 1504 type, since there is no ambiguity. 1506 5.5. Nested Typedefs and Groupings 1508 Typedefs and groupings may appear nested under many YANG statements, 1509 allowing these to be lexically scoped by the hierarchy under which 1510 they appear. This allows types and groupings to be defined near 1511 where they are used, rather than placing them at the top level of the 1512 hierarchy. The close proximity increases readability. 1514 Scoping also allows types to be defined without concern for naming 1515 conflicts between types in different submodules. Type names can be 1516 specified without adding leading strings designed to prevent name 1517 collisions within large modules. 1519 Finally, scoping allows the module author to keep types and groupings 1520 private to their module or submodule, preventing their reuse. Since 1521 only top-level types and groupings (i.e., those appearing as 1522 substatements to a module or submodule statement) can be used outside 1523 the module or submodule, the developer has more control over what 1524 pieces of their module are presented to the outside world, supporting 1525 the need to hide internal information and maintaining a boundary 1526 between what is shared with the outside world and what is kept 1527 private. 1529 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1530 type or grouping cannot be defined if a higher level in the schema 1531 hierarchy has a definition with a matching identifier. 1533 A reference to an unprefixed type or grouping, or one which uses the 1534 prefix of the current module, is resolved by locating the matching 1535 "typedef" or "grouping" statement among the immediate substatements 1536 of each ancestor statement. 1538 5.6. Conformance 1540 Conformance is a measure of how accurately a server follows the 1541 model. Generally speaking, servers are responsible for implementing 1542 the model faithfully, allowing applications to treat servers which 1543 implement the model identically. Deviations from the model can 1544 reduce the utility of the model and increase fragility of 1545 applications that use it. 1547 YANG modelers have three mechanisms for conformance: 1549 o the basic behavior of the model 1551 o optional features that are part of the model 1553 o deviations from the model 1555 We will consider each of these in sequence. 1557 5.6.1. Basic Behavior 1559 The model defines a contract between a YANG-based client and server, 1560 which allows both parties to have faith the other knows the syntax 1561 and semantics behind the modeled data. The strength of YANG lies in 1562 the strength of this contract. 1564 5.6.2. Optional Features 1566 In many models, the modeler will allow sections of the model to be 1567 conditional. The server controls whether these conditional portions 1568 of the model are supported or valid for that particular server. 1570 For example, a syslog data model may choose to include the ability to 1571 save logs locally, but the modeler will realize that this is only 1572 possible if the server has local storage. If there is no local 1573 storage, an application should not tell the server to save logs. 1575 YANG supports this conditional mechanism using a construct called 1576 "feature". Features give the modeler a mechanism for making portions 1577 of the module conditional in a manner that is controlled by the 1578 server. The model can express constructs that are not universally 1579 present in all servers. These features are included in the model 1580 definition, allowing a consistent view and allowing applications to 1581 learn which features are supported and tailor their behavior to the 1582 server. 1584 A module may declare any number of features, identified by simple 1585 strings, and may make portions of the module optional based on those 1586 features. If the server supports a feature, then the corresponding 1587 portions of the module are valid for that server. If the server 1588 doesn't support the feature, those parts of the module are not valid, 1589 and applications should behave accordingly. 1591 Features are defined using the "feature" statement. Definitions in 1592 the module that are conditional to the feature are noted by the 1593 "if-feature" statement. 1595 Further details are available in Section 7.20.1. 1597 5.6.3. Deviations 1599 In an ideal world, all servers would be required to implement the 1600 model exactly as defined, and deviations from the model would not be 1601 allowed. But in the real world, servers are often not able or 1602 designed to implement the model as written. For YANG-based 1603 automation to deal with these server deviations, a mechanism must 1604 exist for servers to inform applications of the specifics of such 1605 deviations. 1607 For example, a BGP module may allow any number of BGP peers, but a 1608 particular server may only support 16 BGP peers. Any application 1609 configuring the 17th peer will receive an error. While an error may 1610 suffice to let the application know it cannot add another peer, it 1611 would be far better if the application had prior knowledge of this 1612 limitation and could prevent the user from starting down the path 1613 that could not succeed. 1615 Server deviations are declared using the "deviation" statement, which 1616 takes as its argument a string that identifies a node in the schema 1617 tree. The contents of the statement details the manner in which the 1618 server implementation deviates from the contract as defined in the 1619 module. 1621 Further details are available in Section 7.20.3. 1623 5.6.4. Announcing Conformance Information in NETCONF 1625 This document defines the following mechanism for announcing 1626 conformance information. Other mechanisms may be defined by future 1627 specifications. 1629 A NETCONF server announces the modules it implements (see 1630 Section 5.6.5) by implementing the YANG module "ietf-yang-library" 1631 defined in [I-D.ietf-netconf-yang-library], and listing all 1632 implemented modules in the "/modules-state/module" list. 1634 The server also advertises the following capability in the 1635 message (line-breaks and whitespaces are used for formatting reasons 1636 only): 1638 urn:ietf:params:netconf:capability:yang-library:1.0? 1639 revision=&module-set-id= 1641 The parameter "revision" has the same value as the revision date of 1642 the "ietf-yang-library" module implemented by the server. This 1643 parameter MUST be present. 1645 The parameter "module-set-id" has the same value as the leaf 1646 "/modules-state/module-set-id" from "ietf-yang-library". This 1647 parameter MUST be present. 1649 With this mechanism, a client can cache the supported modules for a 1650 server, and only update the cache if the "module-set-id" value in the 1651 message changes. 1653 5.6.5. Implementing a Module 1655 A server implements a module if it implements the module's data 1656 nodes, rpcs, actions, notifications, and deviations. 1658 A server MUST NOT implement more than one revision of a module. 1660 If a server implements a module A that imports a module B, and A uses 1661 any node from B in an "augment" or "path" statement that the server 1662 supports, then the server MUST implement a revision of module B that 1663 has these nodes defined. This is regardless of if module B is 1664 imported by revision or not. 1666 If a server implements a module A that imports a module C without 1667 specifying the revision date of module C, and the server does not 1668 implement C (e.g., if C only defines some typedefs), the server MUST 1669 list module C in the "/modules-state/module" list from 1670 "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set 1671 the leaf "conformance-type" to "import" for this module. 1673 If a server lists a module C in the "/modules-state/module" list from 1674 "ietf-yang-library", and there are other modules Ms listed that 1675 import C without specifying the revision date of module C, the server 1676 MUST use the definitions from the most recent revision of C listed 1677 for modules Ms. 1679 The reason for these rules is that clients need to be able to know 1680 the exact data model structure and types of all leafs and leaf-lists 1681 implemented in a server. 1683 For example, with these modules: 1685 module a { 1686 yang-version 1.1; 1687 namespace "urn:example:a"; 1688 prefix "a"; 1690 import b { 1691 revision-date 2015-01-01; 1692 } 1693 import c; 1695 revision 2015-01-01; 1697 feature foo; 1699 augment "/b:x" { 1700 if-feature foo; 1701 leaf y { 1702 type b:myenum; 1703 } 1704 } 1706 container a { 1707 leaf x { 1708 type c:bar; 1709 } 1710 } 1711 } 1713 module b { 1714 yang-version 1.1; 1715 namespace "urn:example:b"; 1716 prefix "b"; 1718 revision 2015-04-04; 1719 revision 2015-01-01; 1721 typedef myenum { 1722 type enumeration { 1723 enum zero; // added in 2015-01-01 1724 enum one; // added in 2015-04-04 1725 } 1726 } 1728 container x { // added in 2015-01-01 1729 container y; // added in 2015-04-04 1730 } 1731 } 1733 module c { 1734 yang-version 1.1; 1735 namespace "urn:example:c"; 1736 prefix "c"; 1738 revision 2015-03-03; 1739 revision 2015-02-02; 1741 typedef bar { 1742 ... 1743 } 1744 } 1746 A server that implements revision "2015-01-01" of module "a" and 1747 supports feature "foo" can implement revision "2015-01-01" or 1748 "2015-04-04" of module "b". Since "b" was imported by revision, the 1749 type of leaf "/b:x/a:y" is the same regardless of which revision of 1750 "b" the server implements. 1752 A server that implements module "a", but does not support feature 1753 "foo" does not have to implement module "b". 1755 A server that implements revision "2015-01-01" of module "a" must 1756 pick a revision of module "c", and list it in the "/modules-state/ 1757 module" list from "ietf-yang-library". 1759 The following XML encoding example shows valid data for the 1760 "/modules-state/module" list for a server that implements module "a": 1762 1764 ee1ecb017370cafd 1765 1766 a 1767 2015-01-01 1768 urn:example:a 1769 foo 1770 implement 1771 1772 1773 b 1774 2015-04-04 1775 urn:example:b 1776 implement 1777 1778 1779 c 1780 2015-02-02 1781 urn:example:c 1782 import 1783 1784 1786 5.7. Datastore Modification 1788 Data models may allow the server to alter the configuration datastore 1789 in ways not explicitly directed via network management protocol 1790 messages. For example, a data model may define leafs that are 1791 assigned system-generated values when the client does not provide 1792 one. A formal mechanism for specifying the circumstances where these 1793 changes are allowed is out of scope for this specification. 1795 6. YANG Syntax 1797 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1798 languages like C and C++. This C-like syntax was chosen specifically 1799 for its readability, since YANG values the time and effort of the 1800 readers of models above those of modules writers and YANG tool-chain 1801 developers. This section introduces the YANG syntax. 1803 YANG modules use the UTF-8 [RFC3629] character encoding. 1805 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1806 [ISO.10646] characters, including tab, carriage return, and line feed 1807 but excluding the other C0 control characters, the surrogate blocks, 1808 and the noncharacters. The character syntax is formally defined by 1809 the rule "yang-char" in Section 14. 1811 6.1. Lexical Tokenization 1813 YANG modules are parsed as a series of tokens. This section details 1814 the rules for recognizing tokens from an input stream. YANG 1815 tokenization rules are both simple and powerful. The simplicity is 1816 driven by a need to keep the parsers easy to implement, while the 1817 power is driven by the fact that modelers need to express their 1818 models in readable formats. 1820 6.1.1. Comments 1822 Comments are C++ style. A single line comment starts with "//" and 1823 ends at the end of the line. A block comment is enclosed within "/*" 1824 and "*/". 1826 Note that inside a quoted string (Section 6.1.3), these character 1827 pairs are never interpreted as the start or end of a comment. 1829 6.1.2. Tokens 1831 A token in YANG is either a keyword, a string, a semicolon (";"), or 1832 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1833 is either one of the YANG keywords defined in this document, or a 1834 prefix identifier, followed by ":", followed by a language extension 1835 keyword. Keywords are case sensitive. See Section 6.2 for a formal 1836 definition of identifiers. 1838 6.1.3. Quoting 1840 If a string contains any space, tab, or newline characters, a single 1841 or double quote character, a semicolon (";"), braces ("{" or "}"), or 1842 comment sequences ("//", "/*", or "*/"), then it MUST be enclosed 1843 within double or single quotes. 1845 Within an unquoted string, every character is preserved. Note that 1846 this means that the backslash character does not have any special 1847 meaning in an unquoted string. 1849 If a double-quoted string contains a line break followed by space or 1850 tab characters that are used to indent the text according to the 1851 layout in the YANG file, this leading whitespace is stripped from the 1852 string, up to and including the column of the double quote character, 1853 or to the first non-whitespace character, whichever occurs first. In 1854 this process, a tab character is treated as 8 space characters. 1856 If a double-quoted string contains space or tab characters before a 1857 line break, this trailing whitespace is stripped from the string. 1859 A single-quoted string (enclosed within ' ') preserves each character 1860 within the quotes. A single quote character cannot occur in a 1861 single-quoted string, even when preceded by a backslash. 1863 Within a double-quoted string (enclosed within " "), a backslash 1864 character introduces a special character, which depends on the 1865 character that immediately follows the backslash: 1867 \n new line 1868 \t a tab character 1869 \" a double quote 1870 \\ a single backslash 1872 It is an error if any other character follows the backslash 1873 character. 1875 If a quoted string is followed by a plus character ("+"), followed by 1876 another quoted string, the two strings are concatenated into one 1877 string, allowing multiple concatenations to build one string. 1878 Whitespace trimming is done before substitution of backslash-escaped 1879 characters in double-quoted strings. Concatenation is performed as 1880 the last step. 1882 6.1.3.1. Quoting Examples 1884 The following strings are equivalent: 1886 hello 1887 "hello" 1888 'hello' 1889 "hel" + "lo" 1890 'hel' + "lo" 1892 The following examples show some special strings: 1894 "\"" - string containing a double quote 1895 '"' - string containing a double quote 1896 "\n" - string containing a new line character 1897 '\n' - string containing a backslash followed 1898 by the character n 1900 The following examples show some illegal strings: 1902 '''' - a single-quoted string cannot contain single quotes 1903 """ - a double quote must be escaped in a double-quoted string 1905 The following strings are equivalent: 1907 "first line 1908 second line" 1910 "first line\n" + " second line" 1912 6.2. Identifiers 1914 Identifiers are used to identify different kinds of YANG items by 1915 name. Each identifier starts with an uppercase or lowercase ASCII 1916 letter or an underscore character, followed by zero or more ASCII 1917 letters, digits, underscore characters, hyphens, and dots. 1918 Implementations MUST support identifiers up to 64 characters in 1919 length, and MAY support longer identifiers. Identifiers are case 1920 sensitive. The identifier syntax is formally defined by the rule 1921 "identifier" in Section 14. Identifiers can be specified as quoted 1922 or unquoted strings. 1924 6.2.1. Identifiers and Their Namespaces 1926 Each identifier is valid in a namespace that depends on the type of 1927 the YANG item being defined. All identifiers defined in a namespace 1928 MUST be unique. 1930 o All module and submodule names share the same global module 1931 identifier namespace. 1933 o All extension names defined in a module and its submodules share 1934 the same extension identifier namespace. 1936 o All feature names defined in a module and its submodules share the 1937 same feature identifier namespace. 1939 o All identity names defined in a module and its submodules share 1940 the same identity identifier namespace. 1942 o All derived type names defined within a parent node or at the top 1943 level of the module or its submodules share the same type 1944 identifier namespace. This namespace is scoped to all descendant 1945 nodes of the parent node or module. This means that any 1946 descendent node may use that typedef, and it MUST NOT define a 1947 typedef with the same name. 1949 o All grouping names defined within a parent node or at the top 1950 level of the module or its submodules share the same grouping 1951 identifier namespace. This namespace is scoped to all descendant 1952 nodes of the parent node or module. This means that any 1953 descendent node may use that grouping, and it MUST NOT define a 1954 grouping with the same name. 1956 o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 1957 notifications, anydatas, and anyxmls defined (directly or through 1958 a uses statement) within a parent node or at the top level of the 1959 module or its submodules share the same identifier namespace. 1960 This namespace is scoped to the parent node or module, unless the 1961 parent node is a case node. In that case, the namespace is scoped 1962 to the closest ancestor node that is not a case or choice node. 1964 o All cases within a choice share the same case identifier 1965 namespace. This namespace is scoped to the parent choice node. 1967 Forward references are allowed in YANG. 1969 6.3. Statements 1971 A YANG module contains a sequence of statements. Each statement 1972 starts with a keyword, followed by zero or one argument, followed 1973 either by a semicolon (";") or a block of substatements enclosed 1974 within braces ("{ }"): 1976 statement = keyword [argument] (";" / "{" *statement "}") 1978 The argument is a string, as defined in Section 6.1.2. 1980 6.3.1. Language Extensions 1982 A module can introduce YANG extensions by using the "extension" 1983 keyword (see Section 7.19). The extensions can be imported by other 1984 modules with the "import" statement (see Section 7.1.5). When an 1985 imported extension is used, the extension's keyword MUST be qualified 1986 using the prefix with which the extension's module was imported. If 1987 an extension is used in the module where it is defined, the 1988 extension's keyword MUST be qualified with the module's prefix. 1990 The processing of extensions depends on whether support for those 1991 extensions is claimed for a given YANG parser or the tool set in 1992 which it is embedded. An unsupported extension, appearing in a YANG 1993 module as an unknown-statement (see Section 14) MAY be ignored in its 1994 entirety. Any supported extension MUST be processed in accordance 1995 with the specification governing that extension. 1997 Care must be taken when defining extensions so that modules that use 1998 the extensions are meaningful also for applications that do not 1999 support the extensions. 2001 6.4. XPath Evaluations 2003 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 2004 for specifying many inter-node references and dependencies. An 2005 implementation is not required to implement an XPath interpreter, but 2006 MUST ensure that the requirements encoded in the data model are 2007 enforced. The manner of enforcement is an implementation decision. 2008 The XPath expressions MUST be syntactically correct, and all prefixes 2009 used MUST be present in the XPath context (see Section 6.4.1). An 2010 implementation may choose to implement them by hand, rather than 2011 using the XPath expression directly. 2013 The data model used in the XPath expressions is the same as that used 2014 in XPath 1.0 [XPATH], with the same extension for root node children 2015 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 2016 that the root node may have any number of element nodes as its 2017 children. 2019 The data tree has no concept of document order. An implementation 2020 needs to choose some document order but how it is done is an 2021 implementation decision. This means that XPath expressions in YANG 2022 modules SHOULD NOT rely on any specific document order. 2024 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 2025 values, see Section 3.5 in [XPATH]. This means that some values of 2026 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 2027 cannot be exactly represented in XPath expressions. Therefore, due 2028 caution should be exercised when using nodes with 64-bit numeric 2029 values in XPath expressions. In particular, numerical comparisons 2030 involving equality may yield unexpected results. 2032 For example, consider the following definition: 2034 leaf lxiv { 2035 type decimal64 { 2036 fraction-digits 18; 2037 } 2038 must ". <= 10"; 2039 } 2041 An instance of the "lxiv" leaf having the value of 2042 10.0000000000000001 will then successfully pass validation. 2044 6.4.1. XPath Context 2046 All YANG XPath expressions share the following XPath context 2047 definition: 2049 o The set of namespace declarations is the set of all "import" 2050 statements' prefix and namespace pairs in the module where the 2051 XPath expression is specified, and the "prefix" statement's prefix 2052 for the "namespace" statement's URI. 2054 o Names without a namespace prefix belong to the same namespace as 2055 the identifier of the current node. Inside a grouping, that 2056 namespace is affected by where the grouping is used (see 2057 Section 7.13). Inside a typedef, that namespace is affected by 2058 where the typedef is referenced. If a typedef is defined and 2059 referenced within a grouping, the namespace is affected by where 2060 the grouping is used (see Section 7.13). 2062 o The function library is the core function library defined in 2063 [XPATH], and the functions defined in Section 10. 2065 o The set of variable bindings is empty. 2067 The mechanism for handling unprefixed names is adopted from XPath 2.0 2068 [XPATH2.0], and helps simplify XPath expressions in YANG. No 2069 ambiguity may ever arise because YANG node identifiers are always 2070 qualified names with a non-null namespace URI. 2072 The accessible tree depends on where the statement with the XPath 2073 expression is defined: 2075 o If the XPath expression is defined in substatement to a data node 2076 that represents configuration, the accessible tree is the data in 2077 the datastore where the context node exists. The root node has 2078 all top-level configuration data nodes in all modules as children. 2080 o If the XPath expression is defined in a substatement to a data 2081 node that represents state data, the accessible tree is all state 2082 data in the server, and the running configuration datastore. The 2083 root node has all top-level data nodes in all modules as children. 2085 o If the XPath expression is defined in a substatement to a 2086 "notification" statement, the accessible tree is the notification 2087 instance, all state data in the server, and the running 2088 configuration datastore. If the notification is defined on the 2089 top-level in a module, then the root node has the node 2090 representing the notification being defined and all top-level data 2091 nodes in all modules as children. Otherwise, the root node has 2092 all top-level data nodes in all modules as children. 2094 o If the XPath expression is defined in a substatement to an "input" 2095 statement in an "rpc" or "action" statement, the accessible tree 2096 is the RPC or action operation instance, all state data in the 2097 server, and the running configuration datastore. The root node 2098 has top-level data nodes in all modules as children. 2099 Additionally, for an RPC, the root node also has the node 2100 representing the RPC operation being defined as a child. The node 2101 representing the operation being defined has the operation's input 2102 parameters as children. 2104 o If the XPath expression is defined in a substatement to an 2105 "output" statement in an "rpc" or "action" statement, the 2106 accessible tree is the RPC or action operation instance, all state 2107 data in the server, and the running configuration datastore. The 2108 root node has top-level data nodes in all modules as children. 2109 Additionally, for an RPC, the root node also has the node 2110 representing the RPC operation being defined as a child. The node 2111 representing the operation being defined has the operation's 2112 output parameters as children. 2114 In the accessible tree, all leafs and leaf-lists with default values 2115 in use exist (See Section 7.6.1 and Section 7.7.2). 2117 If a node that exists in the accessible tree has a non-presence 2118 container as a child, then the non-presence container also exists in 2119 the tree. 2121 The context node varies with the YANG XPath expression, and is 2122 specified where the YANG statement with the XPath expression is 2123 defined. 2125 6.4.1.1. Examples 2127 Given the following module: 2129 module example-a { 2130 yang-version 1.1; 2131 namespace urn:example:a; 2132 prefix a; 2134 container a { 2135 list b { 2136 key id; 2137 leaf id { 2138 type string; 2139 } 2140 notification down { 2141 leaf reason { 2142 type string; 2143 } 2144 } 2145 action reset { 2146 input { 2147 leaf delay { 2148 type uint32; 2149 } 2150 } 2151 output { 2152 leaf result { 2153 type string; 2154 } 2155 } 2156 } 2157 } 2158 } 2159 notification failure { 2160 leaf b-ref { 2161 type leafref { 2162 path "/a/b/id"; 2163 } 2164 } 2165 } 2166 } 2168 And given the following data tree, specified in XML: 2170 2171 2172 1 2173 2174 2175 2 2176 2177 2179 The accessible tree for a notification "down" on /a/b[id="2"] is: 2181 2182 2183 1 2184 2185 2186 2 2187 2188 error 2189 2190 2191 2192 // possibly other top-level nodes here 2194 The accessible tree for an action invocation of "reset" on /a/ 2195 b[id="1"] with the "when" parameter set to "10" would be: 2197 2198 2199 1 2200 2201 10 2202 2203 2204 2205 2 2206 2207 2208 // possibly other top-level nodes here 2210 The accessible tree for the action output of this action is: 2212 2213 2214 1 2215 2216 ok 2217 2218 2219 2220 2 2221 2222 2223 // possibly other top-level nodes here 2225 The accessible tree for a notification "failure" could be: 2227 2228 2229 1 2230 2231 2232 2 2233 2234 2235 2236 2 2237 2238 // possibly other top-level nodes here 2240 6.5. Schema Node Identifier 2242 A schema node identifier is a string that identifies a node in the 2243 schema tree. It has two forms, "absolute" and "descendant", defined 2244 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 2245 in Section 14, respectively. A schema node identifier consists of a 2246 path of identifiers, separated by slashes ("/"). In an absolute 2247 schema node identifier, the first identifier after the leading slash 2248 is any top-level schema node in the local module or in all imported 2249 modules. 2251 References to identifiers defined in external modules MUST be 2252 qualified with appropriate prefixes, and references to identifiers 2253 defined in the current module and its submodules MAY use a prefix. 2255 For example, to identify the child node "b" of top-level node "a", 2256 the string "/a/b" can be used. 2258 7. YANG Statements 2260 The following sections describe all of the YANG statements. 2262 Note that even a statement that does not have any substatements 2263 defined in YANG can have vendor-specific extensions as substatements. 2264 For example, the "description" statement does not have any 2265 substatements defined in YANG, but the following is legal: 2267 description "some text" { 2268 ex:documentation-flag 5; 2269 } 2271 7.1. The module Statement 2273 The "module" statement defines the module's name, and groups all 2274 statements that belong to the module together. The "module" 2275 statement's argument is the name of the module, followed by a block 2276 of substatements that hold detailed module information. The module 2277 name follows the rules for identifiers in Section 6.2. 2279 Names of modules published in RFC streams [RFC4844] MUST be assigned 2280 by IANA, see section 14 in [RFC6020]. 2282 Private module names are assigned by the organization owning the 2283 module without a central registry. See Section 5.1 for 2284 recommendations on how to name modules. 2286 A module typically has the following layout: 2288 module { 2290 // header information 2291 2292 2293 2295 // linkage statements 2296 2297 2299 // meta information 2300 2301 2302 2303 2305 // revision history 2306 2308 // module definitions 2309 2310 } 2312 7.1.1. The module's Substatements 2313 +--------------+---------+-------------+ 2314 | substatement | section | cardinality | 2315 +--------------+---------+-------------+ 2316 | anydata | 7.10 | 0..n | 2317 | anyxml | 7.11 | 0..n | 2318 | augment | 7.17 | 0..n | 2319 | choice | 7.9 | 0..n | 2320 | contact | 7.1.8 | 0..1 | 2321 | container | 7.5 | 0..n | 2322 | description | 7.21.3 | 0..1 | 2323 | deviation | 7.20.3 | 0..n | 2324 | extension | 7.19 | 0..n | 2325 | feature | 7.20.1 | 0..n | 2326 | grouping | 7.12 | 0..n | 2327 | identity | 7.18 | 0..n | 2328 | import | 7.1.5 | 0..n | 2329 | include | 7.1.6 | 0..n | 2330 | leaf | 7.6 | 0..n | 2331 | leaf-list | 7.7 | 0..n | 2332 | list | 7.8 | 0..n | 2333 | namespace | 7.1.3 | 1 | 2334 | notification | 7.16 | 0..n | 2335 | organization | 7.1.7 | 0..1 | 2336 | prefix | 7.1.4 | 1 | 2337 | reference | 7.21.4 | 0..1 | 2338 | revision | 7.1.9 | 0..n | 2339 | rpc | 7.14 | 0..n | 2340 | typedef | 7.3 | 0..n | 2341 | uses | 7.13 | 0..n | 2342 | yang-version | 7.1.2 | 1 | 2343 +--------------+---------+-------------+ 2345 7.1.2. The yang-version Statement 2347 The "yang-version" statement specifies which version of the YANG 2348 language was used in developing the module. The statement's argument 2349 is a string. It MUST contain the value "1.1", which is the current 2350 YANG version. 2352 A module or submodule that doesn't contain the "yang-version" 2353 statement, or one that contains the value "1", is developed for YANG 2354 version 1, defined in [RFC6020]. 2356 Handling of the "yang-version" statement for versions other than 2357 "1.1" (the version defined here) is out of scope for this 2358 specification. Any document that defines a higher version will need 2359 to define the backward compatibility of such a higher version. 2361 For compatibility between YANG version 1 and 1.1, see Section 12. 2363 7.1.3. The namespace Statement 2365 The "namespace" statement defines the XML namespace that all 2366 identifiers defined by the module are qualified by in the XML 2367 encoding, with the exception of identifiers for data nodes, action 2368 nodes, and notification nodes defined inside a grouping (see 2369 Section 7.13 for details). The argument to the "namespace" statement 2370 is the URI of the namespace. 2372 See also Section 5.3. 2374 7.1.4. The prefix Statement 2376 The "prefix" statement is used to define the prefix associated with 2377 the module and its namespace. The "prefix" statement's argument is 2378 the prefix string that is used as a prefix to access a module. The 2379 prefix string MAY be used to refer to definitions contained in the 2380 module, e.g., "if:ifName". A prefix follows the same rules as an 2381 identifier (see Section 6.2). 2383 When used inside the "module" statement, the "prefix" statement 2384 defines the prefix suggested to be used when this module is imported. 2385 To improve readability of the NETCONF XML, a NETCONF client or server 2386 that generates XML or XPath that use prefixes SHOULD use the prefix 2387 defined by the module, unless there is a conflict. 2389 When used inside the "import" statement, the "prefix" statement 2390 defines the prefix to be used when accessing definitions inside the 2391 imported module. When a reference to an identifier from the imported 2392 module is used, the prefix string for the imported module is used in 2393 combination with a colon (":") and the identifier, e.g., 2394 "if:ifIndex". To improve readability of YANG modules, the prefix 2395 defined by a module SHOULD be used when the module is imported, 2396 unless there is a conflict. If there is a conflict, i.e., two 2397 different modules that both have defined the same prefix are 2398 imported, at least one of them MUST be imported with a different 2399 prefix. 2401 All prefixes, including the prefix for the module itself MUST be 2402 unique within the module or submodule. 2404 7.1.5. The import Statement 2406 The "import" statement makes definitions from one module available 2407 inside another module or submodule. The argument is the name of the 2408 module to import, and the statement is followed by a block of 2409 substatements that holds detailed import information. When a module 2410 is imported, the importing module may: 2412 o use any grouping and typedef defined at the top level in the 2413 imported module or its submodules. 2415 o use any extension, feature, and identity defined in the imported 2416 module or its submodules. 2418 o use any node in the imported module's schema tree in "must", 2419 "path", and "when" statements, or as the target node in "augment" 2420 and "deviation" statements. 2422 The mandatory "prefix" substatement assigns a prefix for the imported 2423 module that is scoped to the importing module or submodule. Multiple 2424 "import" statements may be specified to import from different 2425 modules. 2427 When the optional "revision-date" substatement is present, any 2428 typedef, grouping, extension, feature, and identity referenced by 2429 definitions in the local module are taken from the specified revision 2430 of the imported module. It is an error if the specified revision of 2431 the imported module does not exist. If no "revision-date" 2432 substatement is present, it is undefined from which revision of the 2433 module they are taken. 2435 Multiple revisions of the same module can be imported, provided that 2436 different prefixes are used. 2438 +---------------+---------+-------------+ 2439 | substatement | section | cardinality | 2440 +---------------+---------+-------------+ 2441 | prefix | 7.1.4 | 1 | 2442 | revision-date | 7.1.5.1 | 0..1 | 2443 | description | 7.21.3 | 0..1 | 2444 | reference | 7.21.4 | 0..1 | 2445 +---------------+---------+-------------+ 2447 The import's Substatements 2449 7.1.5.1. The import's revision-date Statement 2451 The import's "revision-date" statement is used to specify the exact 2452 version of the module to import. 2454 7.1.6. The include Statement 2456 The "include" statement is used to make content from a submodule 2457 available to that submodule's parent module. The argument is an 2458 identifier that is the name of the submodule to include. Modules are 2459 only allowed to include submodules that belong to that module, as 2460 defined by the "belongs-to" statement (see Section 7.2.2). 2462 When a module includes a submodule, it incorporates the contents of 2463 the submodule into the node hierarchy of the module. 2465 For backward compatibility with YANG version 1, a submodule is 2466 allowed to include another submodule belonging to the same module, 2467 but this is not necessary in YANG version 1.1. 2469 When the optional "revision-date" substatement is present, the 2470 specified revision of the submodule is included in the module. It is 2471 an error if the specified revision of the submodule does not exist. 2472 If no "revision-date" substatement is present, it is undefined which 2473 revision of the submodule is included. 2475 Multiple revisions of the same submodule MUST NOT be included. 2477 +---------------+---------+-------------+ 2478 | substatement | section | cardinality | 2479 +---------------+---------+-------------+ 2480 | revision-date | 7.1.5.1 | 0..1 | 2481 | description | 7.21.3 | 0..1 | 2482 | reference | 7.21.4 | 0..1 | 2483 +---------------+---------+-------------+ 2485 The includes's Substatements 2487 7.1.7. The organization Statement 2489 The "organization" statement defines the party responsible for this 2490 module. The argument is a string that is used to specify a textual 2491 description of the organization(s) under whose auspices this module 2492 was developed. 2494 7.1.8. The contact Statement 2496 The "contact" statement provides contact information for the module. 2497 The argument is a string that is used to specify contact information 2498 for the person or persons to whom technical queries concerning this 2499 module should be sent, such as their name, postal address, telephone 2500 number, and electronic mail address. 2502 7.1.9. The revision Statement 2504 The "revision" statement specifies the editorial revision history of 2505 the module, including the initial revision. A series of revision 2506 statements detail the changes in the module's definition. The 2507 argument is a date string in the format "YYYY-MM-DD", followed by a 2508 block of substatements that holds detailed revision information. A 2509 module SHOULD have at least one "revision" statement. For every 2510 published editorial change, a new one SHOULD be added in front of the 2511 revisions sequence, so that all revisions are in reverse 2512 chronological order. 2514 7.1.9.1. The revision's Substatement 2516 +--------------+---------+-------------+ 2517 | substatement | section | cardinality | 2518 +--------------+---------+-------------+ 2519 | description | 7.21.3 | 0..1 | 2520 | reference | 7.21.4 | 0..1 | 2521 +--------------+---------+-------------+ 2523 7.1.10. Usage Example 2524 module example-system { 2525 yang-version 1.1; 2526 namespace "urn:example:system"; 2527 prefix "sys"; 2529 import ietf-yang-types { 2530 prefix "yang"; 2531 reference "RFC 6991: Common YANG Data Types"; 2532 } 2534 include example-types; 2536 organization "Example Inc."; 2537 contact 2538 "Joe L. User 2540 Example Inc. 2541 42 Anywhere Drive 2542 Nowhere, CA 95134 2543 USA 2545 Phone: +1 800 555 0100 2546 EMail: joe@example.com"; 2548 description 2549 "The module for entities implementing the Example system."; 2551 revision 2007-06-09 { 2552 description "Initial revision."; 2553 } 2555 // definitions follow... 2556 } 2558 7.2. The submodule Statement 2560 While the primary unit in YANG is a module, a YANG module can itself 2561 be constructed out of several submodules. Submodules allow a module 2562 designer to split a complex model into several pieces where all the 2563 submodules contribute to a single namespace, which is defined by the 2564 module that includes the submodules. 2566 The "submodule" statement defines the submodule's name, and groups 2567 all statements that belong to the submodule together. The 2568 "submodule" statement's argument is the name of the submodule, 2569 followed by a block of substatements that hold detailed submodule 2570 information. The submodule name follows the rules for identifiers in 2571 Section 6.2. 2573 Names of submodules published in RFC streams [RFC4844] MUST be 2574 assigned by IANA, see section 14 in [RFC6020]. 2576 Private submodule names are assigned by the organization owning the 2577 submodule without a central registry. See Section 5.1 for 2578 recommendations on how to name submodules. 2580 A submodule typically has the following layout: 2582 submodule { 2584 2586 // module identification 2587 2589 // linkage statements 2590 2592 // meta information 2593 2594 2595 2596 2598 // revision history 2599 2601 // module definitions 2602 2603 } 2605 7.2.1. The submodule's Substatements 2606 +--------------+---------+-------------+ 2607 | substatement | section | cardinality | 2608 +--------------+---------+-------------+ 2609 | anydata | 7.10 | 0..n | 2610 | anyxml | 7.11 | 0..n | 2611 | augment | 7.17 | 0..n | 2612 | belongs-to | 7.2.2 | 1 | 2613 | choice | 7.9 | 0..n | 2614 | contact | 7.1.8 | 0..1 | 2615 | container | 7.5 | 0..n | 2616 | description | 7.21.3 | 0..1 | 2617 | deviation | 7.20.3 | 0..n | 2618 | extension | 7.19 | 0..n | 2619 | feature | 7.20.1 | 0..n | 2620 | grouping | 7.12 | 0..n | 2621 | identity | 7.18 | 0..n | 2622 | import | 7.1.5 | 0..n | 2623 | include | 7.1.6 | 0..n | 2624 | leaf | 7.6 | 0..n | 2625 | leaf-list | 7.7 | 0..n | 2626 | list | 7.8 | 0..n | 2627 | notification | 7.16 | 0..n | 2628 | organization | 7.1.7 | 0..1 | 2629 | reference | 7.21.4 | 0..1 | 2630 | revision | 7.1.9 | 0..n | 2631 | rpc | 7.14 | 0..n | 2632 | typedef | 7.3 | 0..n | 2633 | uses | 7.13 | 0..n | 2634 | yang-version | 7.1.2 | 1 | 2635 +--------------+---------+-------------+ 2637 7.2.2. The belongs-to Statement 2639 The "belongs-to" statement specifies the module to which the 2640 submodule belongs. The argument is an identifier that is the name of 2641 the module. 2643 A submodule MUST only be included by the module to which it belongs, 2644 or by another submodule that belongs to that module. 2646 The mandatory "prefix" substatement assigns a prefix for the module 2647 to which the submodule belongs. All definitions in the module that 2648 the submodule belongs to and all its submodules can be accessed by 2649 using the prefix. 2651 +--------------+---------+-------------+ 2652 | substatement | section | cardinality | 2653 +--------------+---------+-------------+ 2654 | prefix | 7.1.4 | 1 | 2655 +--------------+---------+-------------+ 2657 The belongs-to's Substatements 2659 7.2.3. Usage Example 2661 submodule example-types { 2662 yang-version 1.1; 2663 belongs-to "example-system" { 2664 prefix "sys"; 2665 } 2667 import ietf-yang-types { 2668 prefix "yang"; 2669 } 2671 organization "Example Inc."; 2672 contact 2673 "Joe L. User 2675 Example Inc. 2676 42 Anywhere Drive 2677 Nowhere, CA 95134 2678 USA 2680 Phone: +1 800 555 0100 2681 EMail: joe@example.com"; 2683 description 2684 "This submodule defines common Example types."; 2686 revision "2007-06-09" { 2687 description "Initial revision."; 2688 } 2690 // definitions follows... 2691 } 2693 7.3. The typedef Statement 2695 The "typedef" statement defines a new type that may be used locally 2696 in the module or submodule, and by other modules that import from it, 2697 according to the rules in Section 5.5. The new type is called the 2698 "derived type", and the type from which it was derived is called the 2699 "base type". All derived types can be traced back to a YANG built-in 2700 type. 2702 The "typedef" statement's argument is an identifier that is the name 2703 of the type to be defined, and MUST be followed by a block of 2704 substatements that holds detailed typedef information. 2706 The name of the type MUST NOT be one of the YANG built-in types. If 2707 the typedef is defined at the top level of a YANG module or 2708 submodule, the name of the type to be defined MUST be unique within 2709 the module. 2711 7.3.1. The typedef's Substatements 2713 +--------------+---------+-------------+ 2714 | substatement | section | cardinality | 2715 +--------------+---------+-------------+ 2716 | default | 7.3.4 | 0..1 | 2717 | description | 7.21.3 | 0..1 | 2718 | reference | 7.21.4 | 0..1 | 2719 | status | 7.21.2 | 0..1 | 2720 | type | 7.3.2 | 1 | 2721 | units | 7.3.3 | 0..1 | 2722 +--------------+---------+-------------+ 2724 7.3.2. The typedef's type Statement 2726 The "type" statement, which MUST be present, defines the base type 2727 from which this type is derived. See Section 7.4 for details. 2729 7.3.3. The units Statement 2731 The "units" statement, which is optional, takes as an argument a 2732 string that contains a textual definition of the units associated 2733 with the type. 2735 7.3.4. The typedef's default Statement 2737 The "default" statement takes as an argument a string that contains a 2738 default value for the new type. 2740 The value of the "default" statement MUST be valid according to the 2741 type specified in the "type" statement. 2743 If the base type has a default value, and the new derived type does 2744 not specify a new default value, the base type's default value is 2745 also the default value of the new derived type. 2747 If the type's default value is not valid according to the new 2748 restrictions specified in a derived type or leaf definition, the 2749 derived type or leaf definition MUST specify a new default value 2750 compatible with the restrictions. 2752 7.3.5. Usage Example 2754 typedef listen-ipv4-address { 2755 type inet:ipv4-address; 2756 default "0.0.0.0"; 2757 } 2759 7.4. The type Statement 2761 The "type" statement takes as an argument a string that is the name 2762 of a YANG built-in type (see Section 9) or a derived type (see 2763 Section 7.3), followed by an optional block of substatements that are 2764 used to put further restrictions on the type. 2766 The restrictions that can be applied depend on the type being 2767 restricted. The restriction statements for all built-in types are 2768 described in the subsections of Section 9. 2770 7.4.1. The type's Substatements 2772 +------------------+---------+-------------+ 2773 | substatement | section | cardinality | 2774 +------------------+---------+-------------+ 2775 | base | 7.18.2 | 0..n | 2776 | bit | 9.7.4 | 0..n | 2777 | enum | 9.6.4 | 0..n | 2778 | fraction-digits | 9.3.4 | 0..1 | 2779 | length | 9.4.4 | 0..1 | 2780 | path | 9.9.2 | 0..1 | 2781 | pattern | 9.4.5 | 0..n | 2782 | range | 9.2.4 | 0..1 | 2783 | require-instance | 9.9.3 | 0..1 | 2784 | type | 7.4 | 0..n | 2785 +------------------+---------+-------------+ 2787 7.5. The container Statement 2789 The "container" statement is used to define an interior data node in 2790 the schema tree. It takes one argument, which is an identifier, 2791 followed by a block of substatements that holds detailed container 2792 information. 2794 A container node does not have a value, but it has a list of child 2795 nodes in the data tree. The child nodes are defined in the 2796 container's substatements. 2798 7.5.1. Containers with Presence 2800 YANG supports two styles of containers, those that exist only for 2801 organizing the hierarchy of data nodes, and those whose presence in 2802 the data tree has an explicit meaning. 2804 In the first style, the container has no meaning of its own, existing 2805 only to contain child nodes. This is the default style. 2807 For example, the set of scrambling options for Synchronous Optical 2808 Network (SONET) interfaces may be placed inside a "scrambling" 2809 container to enhance the organization of the configuration hierarchy, 2810 and to keep these nodes together. The "scrambling" node itself has 2811 no meaning, so removing the node when it becomes empty relieves the 2812 user from performing this task. 2814 In the second style, the presence of the container itself carries 2815 some meaning, representing a single bit of data. 2817 In configuration data, the container acts as both a configuration 2818 knob and a means of organizing related configuration. These 2819 containers are explicitly created and deleted. 2821 YANG calls this style a "presence container" and it is indicated 2822 using the "presence" statement, which takes as its argument a text 2823 string indicating what the presence of the node means. 2825 For example, an "ssh" container may turn on the ability to log into 2826 the server using ssh, but can also contain any ssh-related 2827 configuration knobs, such as connection rates or retry limits. 2829 The "presence" statement (see Section 7.5.5) is used to give 2830 semantics to the existence of the container in the data tree. 2832 7.5.2. The container's Substatements 2833 +--------------+---------+-------------+ 2834 | substatement | section | cardinality | 2835 +--------------+---------+-------------+ 2836 | action | 7.15 | 0..n | 2837 | anydata | 7.10 | 0..n | 2838 | anyxml | 7.11 | 0..n | 2839 | choice | 7.9 | 0..n | 2840 | config | 7.21.1 | 0..1 | 2841 | container | 7.5 | 0..n | 2842 | description | 7.21.3 | 0..1 | 2843 | grouping | 7.12 | 0..n | 2844 | if-feature | 7.20.2 | 0..n | 2845 | leaf | 7.6 | 0..n | 2846 | leaf-list | 7.7 | 0..n | 2847 | list | 7.8 | 0..n | 2848 | must | 7.5.3 | 0..n | 2849 | notification | 7.16 | 0..n | 2850 | presence | 7.5.5 | 0..1 | 2851 | reference | 7.21.4 | 0..1 | 2852 | status | 7.21.2 | 0..1 | 2853 | typedef | 7.3 | 0..n | 2854 | uses | 7.13 | 0..n | 2855 | when | 7.21.5 | 0..1 | 2856 +--------------+---------+-------------+ 2858 7.5.3. The must Statement 2860 The "must" statement, which is optional, takes as an argument a 2861 string that contains an XPath expression (see Section 6.4). It is 2862 used to formally declare a constraint on valid data. The constraint 2863 is enforced according to the rules in Section 8. 2865 When a datastore is validated, all "must" constraints are 2866 conceptually evaluated once for each node in the accessible tree (see 2867 Section 6.4.1). 2869 All such constraints MUST evaluate to true for the data to be valid. 2871 The XPath expression is conceptually evaluated in the following 2872 context, in addition to the definition in Section 6.4.1: 2874 o The context node is the node in the accessible tree for which the 2875 "must" statement is defined. 2877 The result of the XPath expression is converted to a boolean value 2878 using the standard XPath rules. 2880 Note that since all leaf values in the data tree are conceptually 2881 stored in their canonical form (see Section 9.1), any XPath 2882 comparisons are done on the canonical value. 2884 Also note that the XPath expression is conceptually evaluated. This 2885 means that an implementation does not have to use an XPath evaluator 2886 in the server. How the evaluation is done in practice is an 2887 implementation decision. 2889 7.5.4. The must's Substatements 2891 +---------------+---------+-------------+ 2892 | substatement | section | cardinality | 2893 +---------------+---------+-------------+ 2894 | description | 7.21.3 | 0..1 | 2895 | error-app-tag | 7.5.4.2 | 0..1 | 2896 | error-message | 7.5.4.1 | 0..1 | 2897 | reference | 7.21.4 | 0..1 | 2898 +---------------+---------+-------------+ 2900 7.5.4.1. The error-message Statement 2902 The "error-message" statement, which is optional, takes a string as 2903 an argument. If the constraint evaluates to false, the string is 2904 passed as in the in NETCONF. 2906 7.5.4.2. The error-app-tag Statement 2908 The "error-app-tag" statement, which is optional, takes a string as 2909 an argument. If the constraint evaluates to false, the string is 2910 passed as in the in NETCONF. 2912 7.5.4.3. Usage Example of must and error-message 2913 container interface { 2914 leaf ifType { 2915 type enumeration { 2916 enum ethernet; 2917 enum atm; 2918 } 2919 } 2920 leaf ifMTU { 2921 type uint32; 2922 } 2923 must "ifType != 'ethernet' or " + 2924 "(ifType = 'ethernet' and ifMTU = 1500)" { 2925 error-message "An ethernet MTU must be 1500"; 2926 } 2927 must "ifType != 'atm' or " + 2928 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2929 error-message "An atm MTU must be 64 .. 17966"; 2930 } 2931 } 2933 7.5.5. The presence Statement 2935 The "presence" statement assigns a meaning to the presence of a 2936 container in the data tree. It takes as an argument a string that 2937 contains a textual description of what the node's presence means. 2939 If a container has the "presence" statement, the container's 2940 existence in the data tree carries some meaning. Otherwise, the 2941 container is used to give some structure to the data, and it carries 2942 no meaning by itself. 2944 See Section 7.5.1 for additional information. 2946 7.5.6. The container's Child Node Statements 2948 Within a container, the "container", "leaf", "list", "leaf-list", 2949 "uses", "choice", "anydata", and "anyxml" statements can be used to 2950 define child nodes to the container. 2952 7.5.7. XML Encoding Rules 2954 A container node is encoded as an XML element. The element's local 2955 name is the container's identifier, and its namespace is the module's 2956 XML namespace (see Section 7.1.3). 2958 The container's child nodes are encoded as subelements to the 2959 container element. If the container defines RPC or action input or 2960 output parameters, these subelements are encoded in the same order as 2961 they are defined within the "container" statement. Otherwise, the 2962 subelements are encoded in any order. 2964 If a non-presence container does not have any child nodes, the 2965 container may or may not be present in the XML encoding. 2967 7.5.8. NETCONF Operations 2969 Containers can be created, deleted, replaced, and modified through 2970 , by using the "operation" attribute (see [RFC6241], 2971 Section 7.2) in the container's XML element. 2973 If a container does not have a "presence" statement and the last 2974 child node is deleted, the NETCONF server MAY delete the container. 2976 When a NETCONF server processes an request, the 2977 elements of procedure for the container node are: 2979 If the operation is "merge" or "replace", the node is created if 2980 it does not exist. 2982 If the operation is "create", the node is created if it does not 2983 exist. If the node already exists, a "data-exists" error is 2984 returned. 2986 If the operation is "delete", the node is deleted if it exists. 2987 If the node does not exist, a "data-missing" error is returned. 2989 7.5.9. Usage Example 2991 Given the following container definition: 2993 container system { 2994 description 2995 "Contains various system parameters"; 2996 container services { 2997 description 2998 "Configure externally available services"; 2999 container "ssh" { 3000 presence "Enables SSH"; 3001 description 3002 "SSH service specific configuration"; 3003 // more leafs, containers and stuff here... 3004 } 3005 } 3006 } 3008 A corresponding XML instance example: 3010 3011 3012 3013 3014 3016 Since the element is present, ssh is enabled. 3018 To delete a container with an : 3020 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3037 7.6. The leaf Statement 3039 The "leaf" statement is used to define a leaf node in the schema 3040 tree. It takes one argument, which is an identifier, followed by a 3041 block of substatements that holds detailed leaf information. 3043 A leaf node has a value, but no child nodes in the data tree. 3044 Conceptually, the value in the data tree is always in the canonical 3045 form (see Section 9.1). 3047 A leaf node exists in zero or one instances in the data tree. 3049 The "leaf" statement is used to define a scalar variable of a 3050 particular built-in or derived type. 3052 7.6.1. The leaf's default value 3054 The default value of a leaf is the value that the server uses if the 3055 leaf does not exist in the data tree. The usage of the default value 3056 depends on the leaf's closest ancestor node in the schema tree that 3057 is not a non-presence-container (see Section 7.5.1): 3059 o If no such ancestor exists in the schema tree, the default value 3060 MUST be used. 3062 o Otherwise, if this ancestor is a case node, the default value MUST 3063 be used if any node from the case exists in the data tree, or if 3064 the case node is the choice's default case, and no nodes from any 3065 other case exist in the data tree. 3067 o Otherwise, the default value MUST be used if the ancestor node 3068 exists in the data tree. 3070 In these cases, the default value is said to be in use. 3072 Note that if the leaf or any of its ancestors has a "when" condition 3073 or "if-feature" expression that evaluates to "false", then the 3074 default value is not in use. 3076 When the default value is in use, the server MUST operationally 3077 behave as if the leaf was present in the data tree with the default 3078 value as its value. 3080 If a leaf has a "default" statement, the leaf's default value is the 3081 value of the "default" statement. Otherwise, if the leaf's type has 3082 a default value, and the leaf is not mandatory, then the leaf's 3083 default value is the type's default value. In all other cases, the 3084 leaf does not have a default value. 3086 7.6.2. The leaf's Substatements 3088 +--------------+---------+-------------+ 3089 | substatement | section | cardinality | 3090 +--------------+---------+-------------+ 3091 | config | 7.21.1 | 0..1 | 3092 | default | 7.6.4 | 0..1 | 3093 | description | 7.21.3 | 0..1 | 3094 | if-feature | 7.20.2 | 0..n | 3095 | mandatory | 7.6.5 | 0..1 | 3096 | must | 7.5.3 | 0..n | 3097 | reference | 7.21.4 | 0..1 | 3098 | status | 7.21.2 | 0..1 | 3099 | type | 7.6.3 | 1 | 3100 | units | 7.3.3 | 0..1 | 3101 | when | 7.21.5 | 0..1 | 3102 +--------------+---------+-------------+ 3104 7.6.3. The leaf's type Statement 3106 The "type" statement, which MUST be present, takes as an argument the 3107 name of an existing built-in or derived type. The optional 3108 substatements specify restrictions on this type. See Section 7.4 for 3109 details. 3111 7.6.4. The leaf's default Statement 3113 The "default" statement, which is optional, takes as an argument a 3114 string that contains a default value for the leaf. 3116 The value of the "default" statement MUST be valid according to the 3117 type specified in the leaf's "type" statement. 3119 The "default" statement MUST NOT be present on nodes where 3120 "mandatory" is true. 3122 The default value MUST NOT be marked with an "if-feature" statement. 3123 For example, the following is illegal: 3125 leaf color { 3126 type enumeration { 3127 enum blue { if-feature blue; } 3128 ... 3129 } 3130 default blue; // illegal - enum value is conditional 3131 } 3133 7.6.5. The leaf's mandatory Statement 3135 The "mandatory" statement, which is optional, takes as an argument 3136 the string "true" or "false", and puts a constraint on valid data. 3137 If not specified, the default is "false". 3139 If "mandatory" is "true", the behavior of the constraint depends on 3140 the type of the leaf's closest ancestor node in the schema tree that 3141 is not a non-presence-container (see Section 7.5.1): 3143 o If no such ancestor exists in the schema tree, the leaf MUST 3144 exist. 3146 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 3147 any node from the case exists in the data tree. 3149 o Otherwise, the leaf MUST exist if the ancestor node exists in the 3150 data tree. 3152 This constraint is enforced according to the rules in Section 8. 3154 7.6.6. XML Encoding Rules 3156 A leaf node is encoded as an XML element. The element's local name 3157 is the leaf's identifier, and its namespace is the module's XML 3158 namespace (see Section 7.1.3). 3160 The value of the leaf node is encoded to XML according to the type, 3161 and sent as character data in the element. 3163 See Section 7.6.8 for an example. 3165 7.6.7. NETCONF Operations 3167 When a NETCONF server processes an request, the 3168 elements of procedure for the leaf node are: 3170 If the operation is "merge" or "replace", the node is created if 3171 it does not exist, and its value is set to the value found in the 3172 XML RPC data. 3174 If the operation is "create", the node is created if it does not 3175 exist. If the node already exists, a "data-exists" error is 3176 returned. 3178 If the operation is "delete", the node is deleted if it exists. 3179 If the node does not exist, a "data-missing" error is returned. 3181 7.6.8. Usage Example 3183 Given the following "leaf" statement, placed in the previously 3184 defined "ssh" container (see Section 7.5.9): 3186 leaf port { 3187 type inet:port-number; 3188 default 22; 3189 description 3190 "The port to which the SSH server listens" 3191 } 3193 A corresponding XML instance example: 3195 2022 3197 To set the value of a leaf with an : 3199 3202 3203 3204 3205 3206 3207 3208 3209 3210 2022 3211 3212 3213 3214 3215 3216 3218 7.7. The leaf-list Statement 3220 Where the "leaf" statement is used to define a simple scalar variable 3221 of a particular type, the "leaf-list" statement is used to define an 3222 array of a particular type. The "leaf-list" statement takes one 3223 argument, which is an identifier, followed by a block of 3224 substatements that holds detailed leaf-list information. 3226 In configuration data, the values in a leaf-list MUST be unique. 3228 The default values MUST NOT be marked with an "if-feature" statement. 3230 Conceptually, the values in the data tree are always in the canonical 3231 form (see Section 9.1). 3233 7.7.1. Ordering 3235 YANG supports two styles for ordering the entries within lists and 3236 leaf-lists. In many lists, the order of list entries does not impact 3237 the implementation of the list's configuration, and the server is 3238 free to sort the list entries in any reasonable order. The 3239 "description" string for the list may suggest an order to the server 3240 implementor. YANG calls this style of list "system ordered" and they 3241 are indicated with the statement "ordered-by system". 3243 For example, a list of valid users would typically be sorted 3244 alphabetically, since the order in which the users appeared in the 3245 configuration would not impact the creation of those users' accounts. 3247 In the other style of lists, the order of list entries matters for 3248 the implementation of the list's configuration and the user is 3249 responsible for ordering the entries, while the server maintains that 3250 order. YANG calls this style of list "user ordered" and they are 3251 indicated with the statement "ordered-by user". 3253 For example, the order in which packet filters entries are applied to 3254 incoming traffic may affect how that traffic is filtered. The user 3255 would need to decide if the filter entry that discards all TCP 3256 traffic should be applied before or after the filter entry that 3257 allows all traffic from trusted interfaces. The choice of order 3258 would be crucial. 3260 YANG provides a rich set of facilities within NETCONF's 3261 operation that allows the order of list entries in user-ordered lists 3262 to be controlled. List entries may be inserted or rearranged, 3263 positioned as the first or last entry in the list, or positioned 3264 before or after another specific entry. 3266 The "ordered-by" statement is covered in Section 7.7.7. 3268 7.7.2. The leaf-list's default values 3270 The default values of a leaf-list are the values that the server uses 3271 if the leaf-list does not exist in the data tree. The usage of the 3272 default values depends on the leaf-list's closest ancestor node in 3273 the schema tree that is not a non-presence-container (see 3274 Section 7.5.1): 3276 o If no such ancestor exists in the schema tree, the default values 3277 MUST be used. 3279 o Otherwise, if this ancestor is a case node, the default values 3280 MUST be used if any node from the case exists in the data tree, or 3281 if the case node is the choice's default case, and no nodes from 3282 any other case exist in the data tree. 3284 o Otherwise, the default values MUST be used if the ancestor node 3285 exists in the data tree. 3287 In these cases, the default values are said to be in use. 3289 Note that if the leaf-list or any of its ancestors has a "when" 3290 condition or "if-feature" expression that evaluates to "false", then 3291 the default values are not in use. 3293 When the default values are in use, the server MUST operationally 3294 behave as if the leaf-list was present in the data tree with the 3295 default values as its values. 3297 If a leaf-list has one or more "default" statement, the leaf-list's 3298 default value are the values of the "default" statements, and if the 3299 leaf-list is user-ordered, the default values are used in the order 3300 of the "default" statements. Otherwise, if the leaf-list's type has 3301 a default value, and the leaf-list does not have a "min-elements" 3302 statement with a value greater than or equal to one, then the leaf- 3303 list's default value is the type's default value. In all other 3304 cases, the leaf-list does not have any default values. 3306 7.7.3. The leaf-list's Substatements 3308 +--------------+---------+-------------+ 3309 | substatement | section | cardinality | 3310 +--------------+---------+-------------+ 3311 | config | 7.21.1 | 0..1 | 3312 | default | 7.7.4 | 0..n | 3313 | description | 7.21.3 | 0..1 | 3314 | if-feature | 7.20.2 | 0..n | 3315 | max-elements | 7.7.6 | 0..1 | 3316 | min-elements | 7.7.5 | 0..1 | 3317 | must | 7.5.3 | 0..n | 3318 | ordered-by | 7.7.7 | 0..1 | 3319 | reference | 7.21.4 | 0..1 | 3320 | status | 7.21.2 | 0..1 | 3321 | type | 7.4 | 1 | 3322 | units | 7.3.3 | 0..1 | 3323 | when | 7.21.5 | 0..1 | 3324 +--------------+---------+-------------+ 3326 7.7.4. The leaf-list's default Statement 3328 The "default" statement, which is optional, takes as an argument a 3329 string that contains a default value for the leaf-list. 3331 The value of the "default" statement MUST be valid according to the 3332 type specified in the leaf-list's "type" statement. 3334 The "default" statement MUST NOT be present on nodes where 3335 "min-elements" has a value greater than or equal to one. 3337 7.7.5. The min-elements Statement 3339 The "min-elements" statement, which is optional, takes as an argument 3340 a non-negative integer that puts a constraint on valid list entries. 3341 A valid leaf-list or list MUST have at least min-elements entries. 3343 If no "min-elements" statement is present, it defaults to zero. 3345 The behavior of the constraint depends on the type of the leaf-list's 3346 or list's closest ancestor node in the schema tree that is not a non- 3347 presence-container (see Section 7.5.1): 3349 o If this ancestor is a case node, the constraint is enforced if any 3350 other node from the case exists. 3352 o Otherwise, it is enforced if the ancestor node exists. 3354 The constraint is further enforced according to the rules in 3355 Section 8. 3357 7.7.6. The max-elements Statement 3359 The "max-elements" statement, which is optional, takes as an argument 3360 a positive integer or the string "unbounded", which puts a constraint 3361 on valid list entries. A valid leaf-list or list always has at most 3362 max-elements entries. 3364 If no "max-elements" statement is present, it defaults to 3365 "unbounded". 3367 The "max-elements" constraint is enforced according to the rules in 3368 Section 8. 3370 7.7.7. The ordered-by Statement 3372 The "ordered-by" statement defines whether the order of entries 3373 within a list are determined by the user or the system. The argument 3374 is one of the strings "system" or "user". If not present, order 3375 defaults to "system". 3377 This statement is ignored if the list represents state data, RPC 3378 output parameters, or notification content. 3380 See Section 7.7.1 for additional information. 3382 7.7.7.1. ordered-by system 3384 The entries in the list are sorted according to an order determined 3385 by the system. The "description" string for the list may suggest an 3386 order to the server implementor. If not, an implementation is free 3387 to sort the entries in the most appropriate order. An implementation 3388 SHOULD use the same order for the same data, regardless of how the 3389 data were created. Using a deterministic order will make comparisons 3390 possible using simple tools like "diff". 3392 This is the default order. 3394 7.7.7.2. ordered-by user 3396 The entries in the list are sorted according to an order defined by 3397 the user. This order is controlled by using special XML attributes 3398 in the request. See Section 7.7.9 for details. 3400 7.7.8. XML Encoding Rules 3402 A leaf-list node is encoded as a series of XML elements. Each 3403 element's local name is the leaf-list's identifier, and its namespace 3404 is the module's XML namespace (see Section 7.1.3). 3406 The value of each leaf-list entry is encoded to XML according to the 3407 type, and sent as character data in the element. 3409 The XML elements representing leaf-list entries MUST appear in the 3410 order specified by the user if the leaf-list is "ordered-by user"; 3411 otherwise, the order is implementation-dependent. The XML elements 3412 representing leaf-list entries MAY be interleaved with other sibling 3413 elements, unless the leaf-list defines RPC or action input or output 3414 parameters. 3416 See Section 7.7.10 for an example. 3418 7.7.9. NETCONF Operations 3420 Leaf-list entries can be created and deleted, but not modified, 3421 through , by using the "operation" attribute in the 3422 leaf-list entry's XML element. 3424 In an "ordered-by user" leaf-list, the attributes "insert" and 3425 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3426 control where in the leaf-list the entry is inserted. These can be 3427 used during "create" operations to insert a new leaf-list entry, or 3428 during "merge" or "replace" operations to insert a new leaf-list 3429 entry or move an existing one. 3431 The "insert" attribute can take the values "first", "last", "before", 3432 and "after". If the value is "before" or "after", the "value" 3433 attribute MUST also be used to specify an existing entry in the leaf- 3434 list. 3436 If no "insert" attribute is present in the "create" operation, it 3437 defaults to "last". 3439 If several entries in an "ordered-by user" leaf-list are modified in 3440 the same request, the entries are modified one at the 3441 time, in the order of the XML elements in the request. 3443 In a , or an with a "replace" operation 3444 that covers the entire leaf-list, the leaf-list order is the same as 3445 the order of the XML elements in the request. 3447 When a NETCONF server processes an request, the 3448 elements of procedure for a leaf-list node are: 3450 If the operation is "merge" or "replace", the leaf-list entry is 3451 created if it does not exist. 3453 If the operation is "create", the leaf-list entry is created if it 3454 does not exist. If the leaf-list entry already exists, a 3455 "data-exists" error is returned. 3457 If the operation is "delete", the entry is deleted from the leaf- 3458 list if it exists. If the leaf-list entry does not exist, a 3459 "data-missing" error is returned. 3461 7.7.10. Usage Example 3463 leaf-list allow-user { 3464 type string; 3465 description 3466 "A list of user name patterns to allow"; 3467 } 3469 A corresponding XML instance example: 3471 alice 3472 bob 3474 To create a new element in this list, using the default 3475 operation "merge": 3477 3480 3481 3482 3483 3484 3485 3486 3487 3488 eric 3489 3490 3491 3492 3493 3494 3496 Given the following ordered-by user leaf-list: 3498 leaf-list cipher { 3499 type string; 3500 ordered-by user; 3501 description 3502 "A list of ciphers"; 3503 } 3505 The following would be used to insert a new cipher "blowfish-cbc" 3506 after "3des-cbc": 3508 3512 3513 3514 3515 3516 3517 3518 3519 3520 blowfish-cbc 3523 3524 3525 3526 3527 3528 3530 7.8. The list Statement 3532 The "list" statement is used to define an interior data node in the 3533 schema tree. A list node may exist in multiple instances in the data 3534 tree. Each such instance is known as a list entry. The "list" 3535 statement takes one argument, which is an identifier, followed by a 3536 block of substatements that holds detailed list information. 3538 A list entry is uniquely identified by the values of the list's keys, 3539 if defined. 3541 7.8.1. The list's Substatements 3542 +--------------+---------+-------------+ 3543 | substatement | section | cardinality | 3544 +--------------+---------+-------------+ 3545 | action | 7.15 | 0..n | 3546 | anydata | 7.10 | 0..n | 3547 | anyxml | 7.11 | 0..n | 3548 | choice | 7.9 | 0..n | 3549 | config | 7.21.1 | 0..1 | 3550 | container | 7.5 | 0..n | 3551 | description | 7.21.3 | 0..1 | 3552 | grouping | 7.12 | 0..n | 3553 | if-feature | 7.20.2 | 0..n | 3554 | key | 7.8.2 | 0..1 | 3555 | leaf | 7.6 | 0..n | 3556 | leaf-list | 7.7 | 0..n | 3557 | list | 7.8 | 0..n | 3558 | max-elements | 7.7.6 | 0..1 | 3559 | min-elements | 7.7.5 | 0..1 | 3560 | must | 7.5.3 | 0..n | 3561 | notification | 7.16 | 0..n | 3562 | ordered-by | 7.7.7 | 0..1 | 3563 | reference | 7.21.4 | 0..1 | 3564 | status | 7.21.2 | 0..1 | 3565 | typedef | 7.3 | 0..n | 3566 | unique | 7.8.3 | 0..n | 3567 | uses | 7.13 | 0..n | 3568 | when | 7.21.5 | 0..1 | 3569 +--------------+---------+-------------+ 3571 7.8.2. The list's key Statement 3573 The "key" statement, which MUST be present if the list represents 3574 configuration, and MAY be present otherwise, takes as an argument a 3575 string that specifies a space-separated list of leaf identifiers of 3576 this list. A leaf identifier MUST NOT appear more than once in the 3577 key. Each such leaf identifier MUST refer to a child leaf of the 3578 list. The leafs can be defined directly in substatements to the 3579 list, or in groupings used in the list. 3581 The combined values of all the leafs specified in the key are used to 3582 uniquely identify a list entry. All key leafs MUST be given values 3583 when a list entry is created. Thus, any default values in the key 3584 leafs or their types are ignored. It also implies that any mandatory 3585 statement in the key leafs are ignored. 3587 A leaf that is part of the key can be of any built-in or derived 3588 type. 3590 All key leafs in a list MUST have the same value for their "config" 3591 as the list itself. 3593 The key string syntax is formally defined by the rule "key-arg" in 3594 Section 14. 3596 7.8.3. The list's unique Statement 3598 The "unique" statement is used to put constraints on valid list 3599 entries. It takes as an argument a string that contains a space- 3600 separated list of schema node identifiers, which MUST be given in the 3601 descendant form (see the rule "descendant-schema-nodeid" in 3602 Section 14). Each such schema node identifier MUST refer to a leaf. 3604 If one of the referenced leafs represents configuration data, then 3605 all of the referenced leafs MUST represent configuration data. 3607 The "unique" constraint specifies that the combined values of all the 3608 leaf instances specified in the argument string, including leafs with 3609 default values, MUST be unique within all list entry instances in 3610 which all referenced leafs exist. The constraint is enforced 3611 according to the rules in Section 8. 3613 The unique string syntax is formally defined by the rule "unique-arg" 3614 in Section 14. 3616 7.8.3.1. Usage Example 3618 With the following list: 3620 list server { 3621 key "name"; 3622 unique "ip port"; 3623 leaf name { 3624 type string; 3625 } 3626 leaf ip { 3627 type inet:ip-address; 3628 } 3629 leaf port { 3630 type inet:port-number; 3631 } 3632 } 3634 The following configuration is not valid: 3636 3637 smtp 3638 192.0.2.1 3639 25 3640 3642 3643 http 3644 192.0.2.1 3645 25 3646 3648 The following configuration is valid, since the "http" and "ftp" list 3649 entries do not have a value for all referenced leafs, and are thus 3650 not taken into account when the "unique" constraint is enforced: 3652 3653 smtp 3654 192.0.2.1 3655 25 3656 3658 3659 http 3660 192.0.2.1 3661 3663 3664 ftp 3665 192.0.2.1 3666 3668 7.8.4. The list's Child Node Statements 3670 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3671 "choice", "anydata", and "anyxml" statements can be used to define 3672 child nodes to the list. 3674 7.8.5. XML Encoding Rules 3676 A list is encoded as a series of XML elements, one for each entry in 3677 the list. Each element's local name is the list's identifier, and 3678 its namespace is the module's XML namespace (see Section 7.1.3). 3680 The list's key nodes are encoded as subelements to the list's 3681 identifier element, in the same order as they are defined within the 3682 "key" statement. 3684 The rest of the list's child nodes are encoded as subelements to the 3685 list element, after the keys. If the list defines RPC or action 3686 input or output parameters, the subelements are encoded in the same 3687 order as they are defined within the "list" statement. Otherwise, 3688 the subelements are encoded in any order. 3690 The XML elements representing list entries MUST appear in the order 3691 specified by the user if the list is "ordered-by user", otherwise the 3692 order is implementation-dependent. The XML elements representing 3693 list entries MAY be interleaved with other sibling elements, unless 3694 the list defines RPC or action input or output parameters. 3696 7.8.6. NETCONF Operations 3698 List entries can be created, deleted, replaced, and modified through 3699 , by using the "operation" attribute in the list's XML 3700 element. In each case, the values of all keys are used to uniquely 3701 identify a list entry. If all keys are not specified for a list 3702 entry, a "missing-element" error is returned. 3704 In an "ordered-by user" list, the attributes "insert" and "key" in 3705 the YANG XML namespace (Section 5.3.1) can be used to control where 3706 in the list the entry is inserted. These can be used during "create" 3707 operations to insert a new list entry, or during "merge" or "replace" 3708 operations to insert a new list entry or move an existing one. 3710 The "insert" attribute can take the values "first", "last", "before", 3711 and "after". If the value is "before" or "after", the "key" 3712 attribute MUST also be used, to specify an existing element in the 3713 list. The value of the "key" attribute is the key predicates of the 3714 full instance identifier (see Section 9.13) for the list entry. 3716 If no "insert" attribute is present in the "create" operation, it 3717 defaults to "last". 3719 If several entries in an "ordered-by user" list are modified in the 3720 same request, the entries are modified one at the time, 3721 in the order of the XML elements in the request. 3723 In a , or an with a "replace" operation 3724 that covers the entire list, the list entry order is the same as the 3725 order of the XML elements in the request. 3727 When a NETCONF server processes an request, the 3728 elements of procedure for a list node are: 3730 If the operation is "merge" or "replace", the list entry is 3731 created if it does not exist. If the list entry already exists 3732 and the "insert" and "key" attributes are present, the list entry 3733 is moved according to the values of the "insert" and "key" 3734 attributes. If the list entry exists and the "insert" and "key" 3735 attributes are not present, the list entry is not moved. 3737 If the operation is "create", the list entry is created if it does 3738 not exist. If the list entry already exists, a "data-exists" 3739 error is returned. 3741 If the operation is "delete", the entry is deleted from the list 3742 if it exists. If the list entry does not exist, a "data-missing" 3743 error is returned. 3745 7.8.7. Usage Example 3747 Given the following list: 3749 list user { 3750 key "name"; 3751 config true; 3752 description 3753 "This is a list of users in the system."; 3755 leaf name { 3756 type string; 3757 } 3758 leaf type { 3759 type string; 3760 } 3761 leaf full-name { 3762 type string; 3763 } 3764 } 3766 A corresponding XML instance example: 3768 3769 fred 3770 admin 3771 Fred Flintstone 3772 3774 To create a new user "barney": 3776 3779 3780 3781 3782 3783 3784 3785 3786 barney 3787 admin 3788 Barney Rubble 3789 3790 3791 3792 3793 3795 To change the type of "fred" to "superuser": 3797 3800 3801 3802 3803 3804 3805 3806 3807 fred 3808 superuser 3809 3810 3811 3812 3813 3815 Given the following ordered-by user list: 3817 list user { 3818 description 3819 "This is a list of users in the system."; 3820 ordered-by user; 3821 config true; 3823 key "first-name surname"; 3825 leaf first-name { 3826 type string; 3827 } 3828 leaf surname { 3829 type string; 3830 } 3831 leaf type { 3832 type string; 3833 } 3834 } 3836 The following would be used to insert a new user "barney rubble" 3837 after the user "fred flintstone": 3839 3843 3844 3845 3846 3847 3848 3850 3854 barney 3855 rubble 3856 admin 3857 3858 3859 3860 3861 3863 The following would be used to move the user "barney rubble" before 3864 the user "fred flintstone": 3866 3870 3871 3872 3873 3874 3875 3877 3881 barney 3882 rubble 3883 3884 3885 3886 3887 3889 7.9. The choice Statement 3891 The "choice" statement defines a set of alternatives, only one of 3892 which may exist at any one time. The argument is an identifier, 3893 followed by a block of substatements that holds detailed choice 3894 information. The identifier is used to identify the choice node in 3895 the schema tree. A choice node does not exist in the data tree. 3897 A choice consists of a number of branches, defined with the "case" 3898 substatement. Each branch contains a number of child nodes. The 3899 nodes from at most one of the choice's branches exist at the same 3900 time. 3902 Since only one of the choice's cases can be valid at any time in the 3903 data tree, the creation of a node from one case implicitly deletes 3904 all nodes from all other cases. If a request creates a node from a 3905 case, the server will delete any existing nodes that are defined in 3906 other cases inside the choice. 3908 7.9.1. The choice's Substatements 3909 +--------------+---------+-------------+ 3910 | substatement | section | cardinality | 3911 +--------------+---------+-------------+ 3912 | anydata | 7.10 | 0..n | 3913 | anyxml | 7.11 | 0..n | 3914 | case | 7.9.2 | 0..n | 3915 | choice | 7.9 | 0..n | 3916 | config | 7.21.1 | 0..1 | 3917 | container | 7.5 | 0..n | 3918 | default | 7.9.3 | 0..1 | 3919 | description | 7.21.3 | 0..1 | 3920 | if-feature | 7.20.2 | 0..n | 3921 | leaf | 7.6 | 0..n | 3922 | leaf-list | 7.7 | 0..n | 3923 | list | 7.8 | 0..n | 3924 | mandatory | 7.9.4 | 0..1 | 3925 | reference | 7.21.4 | 0..1 | 3926 | status | 7.21.2 | 0..1 | 3927 | when | 7.21.5 | 0..1 | 3928 +--------------+---------+-------------+ 3930 7.9.2. The choice's case Statement 3932 The "case" statement is used to define branches of the choice. It 3933 takes as an argument an identifier, followed by a block of 3934 substatements that holds detailed case information. 3936 The identifier is used to identify the case node in the schema tree. 3937 A case node does not exist in the data tree. 3939 Within a "case" statement, the "anydata", "anyxml", "choice", 3940 "container", "leaf", "list", "leaf-list", and "uses" statements can 3941 be used to define child nodes to the case node. The identifiers of 3942 all these child nodes MUST be unique within all cases in a choice. 3943 For example, the following is illegal: 3945 choice interface-type { // This example is illegal YANG 3946 case a { 3947 leaf ethernet { ... } 3948 } 3949 case b { 3950 container ethernet { ...} 3951 } 3952 } 3954 As a shorthand, the "case" statement can be omitted if the branch 3955 contains a single "anydata", "anyxml", "choice", "container", "leaf", 3956 "list", or "leaf-list" statement. In this case, the case node still 3957 exists in the schema tree, and its identifier is the same as the 3958 identifier in the branch statement. Schema node identifiers 3959 (Section 6.5) MUST always explicitly include case node identifiers. 3960 The following example: 3962 choice interface-type { 3963 container ethernet { ... } 3964 } 3966 is equivalent to: 3968 choice interface-type { 3969 case ethernet { 3970 container ethernet { ... } 3971 } 3972 } 3974 The case identifier MUST be unique within a choice. 3976 7.9.2.1. The case's Substatements 3978 +--------------+---------+-------------+ 3979 | substatement | section | cardinality | 3980 +--------------+---------+-------------+ 3981 | anydata | 7.10 | 0..n | 3982 | anyxml | 7.11 | 0..n | 3983 | choice | 7.9 | 0..n | 3984 | container | 7.5 | 0..n | 3985 | description | 7.21.3 | 0..1 | 3986 | if-feature | 7.20.2 | 0..n | 3987 | leaf | 7.6 | 0..n | 3988 | leaf-list | 7.7 | 0..n | 3989 | list | 7.8 | 0..n | 3990 | reference | 7.21.4 | 0..1 | 3991 | status | 7.21.2 | 0..1 | 3992 | uses | 7.13 | 0..n | 3993 | when | 7.21.5 | 0..1 | 3994 +--------------+---------+-------------+ 3996 7.9.3. The choice's default Statement 3998 The "default" statement indicates if a case should be considered as 3999 the default if no child nodes from any of the choice's cases exist. 4000 The argument is the identifier of the "case" statement. If the 4001 "default" statement is missing, there is no default case. 4003 The "default" statement MUST NOT be present on choices where 4004 "mandatory" is true. 4006 The default case is only important when considering the default 4007 statements of nodes under the cases (i.e., default values of leafs 4008 and leaf-lists, and default cases of nested choices). The default 4009 values and nested default cases under the default case are used if 4010 none of the nodes under any of the cases are present. 4012 There MUST NOT be any mandatory nodes (Section 3) directly under the 4013 default case. 4015 Default values for child nodes under a case are only used if one of 4016 the nodes under that case is present, or if that case is the default 4017 case. If none of the nodes under a case are present and the case is 4018 not the default case, the default values of the cases' child nodes 4019 are ignored. 4021 In this example, the choice defaults to "interval", and the default 4022 value will be used if none of "daily", "time-of-day", or "manual" are 4023 present. If "daily" is present, the default value for "time-of-day" 4024 will be used. 4026 container transfer { 4027 choice how { 4028 default interval; 4029 case interval { 4030 leaf interval { 4031 type uint16; 4032 units minutes; 4033 default 30; 4034 } 4035 } 4036 case daily { 4037 leaf daily { 4038 type empty; 4039 } 4040 leaf time-of-day { 4041 type string; 4042 units 24-hour-clock; 4043 default "01.00"; 4044 } 4045 } 4046 case manual { 4047 leaf manual { 4048 type empty; 4049 } 4050 } 4051 } 4052 } 4054 7.9.4. The choice's mandatory Statement 4056 The "mandatory" statement, which is optional, takes as an argument 4057 the string "true" or "false", and puts a constraint on valid data. 4058 If "mandatory" is "true", at least one node from exactly one of the 4059 choice's case branches MUST exist. 4061 If not specified, the default is "false". 4063 The behavior of the constraint depends on the type of the choice's 4064 closest ancestor node in the schema tree that is not a non-presence- 4065 container (see Section 7.5.1): 4067 o If this ancestor is a case node, the constraint is enforced if any 4068 other node from the case exists. 4070 o Otherwise, it is enforced if the ancestor node exists. 4072 The constraint is further enforced according to the rules in 4073 Section 8. 4075 7.9.5. XML Encoding Rules 4077 The choice and case nodes are not visible in XML. 4079 The child nodes of the selected "case" statement MUST be encoded in 4080 the same order as they are defined in the "case" statement if they 4081 are part of an RPC or action input or output parameter definition. 4082 Otherwise, the subelements are encoded in any order. 4084 7.9.6. Usage Example 4086 Given the following choice: 4088 container protocol { 4089 choice name { 4090 case a { 4091 leaf udp { 4092 type empty; 4093 } 4094 } 4095 case b { 4096 leaf tcp { 4097 type empty; 4098 } 4099 } 4100 } 4101 } 4103 A corresponding XML instance example: 4105 4106 4107 4109 To change the protocol from tcp to udp: 4111 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4128 7.10. The anydata Statement 4130 The "anydata" statement defines an interior node in the schema tree. 4131 It takes one argument, which is an identifier, followed by a block of 4132 substatements that holds detailed anydata information. 4134 The "anydata" statement is used to represent an unknown set of nodes 4135 that can be modelled with YANG, except anyxml, but for which the data 4136 model is not known at module design time. It is possible, though not 4137 required, for the data model for "anydata" content to become known 4138 through protocol signalling or other means that are outside the scope 4139 of this document. 4141 An example of where anydata can be useful is a list of received 4142 notifications, where the exact notifications are not known at design 4143 time. 4145 An anydata node cannot be augmented (see Section 7.17). 4147 An anydata node exists in zero or one instances in the data tree. 4149 An implementation may or may not know the data model used to model a 4150 specific instance of an anydata node. 4152 Since the use of anydata limits the manipulation of the content, it 4153 is RECOMMENDED that the "anydata" statement not be used to define 4154 configuration data. 4156 7.10.1. The anydata's Substatements 4158 +--------------+---------+-------------+ 4159 | substatement | section | cardinality | 4160 +--------------+---------+-------------+ 4161 | config | 7.21.1 | 0..1 | 4162 | description | 7.21.3 | 0..1 | 4163 | if-feature | 7.20.2 | 0..n | 4164 | mandatory | 7.6.5 | 0..1 | 4165 | must | 7.5.3 | 0..n | 4166 | reference | 7.21.4 | 0..1 | 4167 | status | 7.21.2 | 0..1 | 4168 | when | 7.21.5 | 0..1 | 4169 +--------------+---------+-------------+ 4171 7.10.2. XML Encoding Rules 4173 An anydata node is encoded as an XML element. The element's local 4174 name is the anydata's identifier, and its namespace is the module's 4175 XML namespace (see Section 7.1.3). The value of the anydata node is 4176 a set of nodes, which are encoded as XML subelements to the anydata 4177 element. 4179 7.10.3. NETCONF Operations 4181 An anydata node is treated as an opaque chunk of data. This data can 4182 be modified in its entirety only. 4184 Any "operation" attributes present on subelements of an anydata node 4185 are ignored by the NETCONF server. 4187 When a NETCONF server processes an request, the 4188 elements of procedure for the anydata node are: 4190 If the operation is "merge" or "replace", the node is created if 4191 it does not exist, and its value is set to the subelements of the 4192 anydata node found in the XML RPC data. 4194 If the operation is "create", the node is created if it does not 4195 exist, and its value is set to the subelements of the anydata node 4196 found in the XML RPC data. If the node already exists, a 4197 "data-exists" error is returned. 4199 If the operation is "delete", the node is deleted if it exists. 4200 If the node does not exist, a "data-missing" error is returned. 4202 7.10.4. Usage Example 4204 Given the following "anydata" statement: 4206 list logged-notification { 4207 key time; 4208 leaf time { 4209 type yang:date-and-time; 4210 } 4211 anydata data; 4212 } 4214 The following is a valid encoding of such a list instance: 4216 4217 4218 4219 4221 2014-07-29T13:43:01Z 4222 4223 fault 4224 4225 Ethernet0 4226 4227 major 4228 4229 4230 4232 7.11. The anyxml Statement 4234 The "anyxml" statement defines an interior node in the schema tree. 4235 It takes one argument, which is an identifier, followed by a block of 4236 substatements that holds detailed anyxml information. 4238 The "anyxml" statement is used to represent an unknown chunk of XML. 4239 No restrictions are placed on the XML. This can be useful, for 4240 example, in RPC replies. An example is the parameter in the 4241 operation in NETCONF. 4243 An anyxml node cannot be augmented (see Section 7.17). 4245 An anyxml node exists in zero or one instances in the data tree. 4247 Since the use of anyxml limits the manipulation of the content, it is 4248 RECOMMENDED that the "anyxml" statement not be used to define 4249 configuration data. 4251 It should be noted that in YANG version 1, anyxml was the only 4252 statement that could model an unknown hierarchy of data. In many 4253 cases this unknown hierarchy of data is actually modelled in YANG, 4254 but the exact YANG data model is not known at design time. In these 4255 situations, it is RECOMMENDED to use anydata (Section 7.10) instead 4256 of anyxml. 4258 7.11.1. The anyxml's Substatements 4260 +--------------+---------+-------------+ 4261 | substatement | section | cardinality | 4262 +--------------+---------+-------------+ 4263 | config | 7.21.1 | 0..1 | 4264 | description | 7.21.3 | 0..1 | 4265 | if-feature | 7.20.2 | 0..n | 4266 | mandatory | 7.6.5 | 0..1 | 4267 | must | 7.5.3 | 0..n | 4268 | reference | 7.21.4 | 0..1 | 4269 | status | 7.21.2 | 0..1 | 4270 | when | 7.21.5 | 0..1 | 4271 +--------------+---------+-------------+ 4273 7.11.2. XML Encoding Rules 4275 An anyxml node is encoded as an XML element. The element's local 4276 name is the anyxml's identifier, and its namespace is the module's 4277 XML namespace (see Section 7.1.3). The value of the anyxml node is 4278 encoded as XML content of this element. 4280 Note that any XML prefixes used in the encoding are local to each 4281 instance encoding. This means that the same XML may be encoded 4282 differently by different implementations. 4284 7.11.3. NETCONF Operations 4286 An anyxml node is treated as an opaque chunk of data. This data can 4287 be modified in its entirety only. 4289 Any "operation" attributes present on subelements of an anyxml node 4290 are ignored by the NETCONF server. 4292 When a NETCONF server processes an request, the 4293 elements of procedure for the anyxml node are: 4295 If the operation is "merge" or "replace", the node is created if 4296 it does not exist, and its value is set to the XML content of the 4297 anyxml node found in the XML RPC data. 4299 If the operation is "create", the node is created if it does not 4300 exist, and its value is set to the XML content of the anyxml node 4301 found in the XML RPC data. If the node already exists, a 4302 "data-exists" error is returned. 4304 If the operation is "delete", the node is deleted if it exists. 4305 If the node does not exist, a "data-missing" error is returned. 4307 7.11.4. Usage Example 4309 Given the following "anyxml" statement: 4311 anyxml html-info; 4313 The following are two valid encodings of the same anyxml value: 4315 4316

4317 This is very cool. 4318

4319 4321 4322 4323 This is very cool. 4324 4325 4327 7.12. The grouping Statement 4329 The "grouping" statement is used to define a reusable block of nodes, 4330 which may be used locally in the module or submodule, and by other 4331 modules that import from it, according to the rules in Section 5.5. 4332 It takes one argument, which is an identifier, followed by a block of 4333 substatements that holds detailed grouping information. 4335 The "grouping" statement is not a data definition statement and, as 4336 such, does not define any nodes in the schema tree. 4338 A grouping is like a "structure" or a "record" in conventional 4339 programming languages. 4341 Once a grouping is defined, it can be referenced in a "uses" 4342 statement (see Section 7.13). A grouping MUST NOT reference itself, 4343 neither directly nor indirectly through a chain of other groupings. 4345 If the grouping is defined at the top level of a YANG module or 4346 submodule, the grouping's identifier MUST be unique within the 4347 module. 4349 A grouping is more than just a mechanism for textual substitution, 4350 but defines a collection of nodes. Identifiers appearing inside the 4351 grouping are resolved relative to the scope in which the grouping is 4352 defined, not where it is used. Prefix mappings, type names, grouping 4353 names, and extension usage are evaluated in the hierarchy where the 4354 "grouping" statement appears. For extensions, this means that 4355 extensions defined as direct children to a "grouping" statement are 4356 applied to the grouping itself. 4358 Note that if a grouping defines an "action" or a "notification" node 4359 in its hierarchy, then it cannot be used in all contexts. For 4360 example, it cannot be used in an rpc definition. See Section 7.15 4361 and Section 7.16. 4363 7.12.1. The grouping's Substatements 4365 +--------------+---------+-------------+ 4366 | substatement | section | cardinality | 4367 +--------------+---------+-------------+ 4368 | action | 7.15 | 0..n | 4369 | anydata | 7.10 | 0..n | 4370 | anyxml | 7.11 | 0..n | 4371 | choice | 7.9 | 0..n | 4372 | container | 7.5 | 0..n | 4373 | description | 7.21.3 | 0..1 | 4374 | grouping | 7.12 | 0..n | 4375 | leaf | 7.6 | 0..n | 4376 | leaf-list | 7.7 | 0..n | 4377 | list | 7.8 | 0..n | 4378 | notification | 7.16 | 0..n | 4379 | reference | 7.21.4 | 0..1 | 4380 | status | 7.21.2 | 0..1 | 4381 | typedef | 7.3 | 0..n | 4382 | uses | 7.13 | 0..n | 4383 +--------------+---------+-------------+ 4385 7.12.2. Usage Example 4387 import ietf-inet-types { 4388 prefix "inet"; 4389 } 4391 grouping endpoint { 4392 description "A reusable endpoint group."; 4393 leaf ip { 4394 type inet:ip-address; 4395 } 4396 leaf port { 4397 type inet:port-number; 4398 } 4399 } 4401 7.13. The uses Statement 4403 The "uses" statement is used to reference a "grouping" definition. 4404 It takes one argument, which is the name of the grouping. 4406 The effect of a "uses" reference to a grouping is that the nodes 4407 defined by the grouping are copied into the current schema tree, and 4408 then updated according to the "refine" and "augment" statements. 4410 The identifiers defined in the grouping are not bound to a namespace 4411 until the contents of the grouping are added to the schema tree via a 4412 "uses" statement that does not appear inside a "grouping" statement, 4413 at which point they are bound to the namespace of the current module. 4415 7.13.1. The uses's Substatements 4417 +--------------+---------+-------------+ 4418 | substatement | section | cardinality | 4419 +--------------+---------+-------------+ 4420 | augment | 7.17 | 0..n | 4421 | description | 7.21.3 | 0..1 | 4422 | if-feature | 7.20.2 | 0..n | 4423 | refine | 7.13.2 | 0..n | 4424 | reference | 7.21.4 | 0..1 | 4425 | status | 7.21.2 | 0..1 | 4426 | when | 7.21.5 | 0..1 | 4427 +--------------+---------+-------------+ 4429 7.13.2. The refine Statement 4431 Some of the properties of each node in the grouping can be refined 4432 with the "refine" statement. The argument is a string that 4433 identifies a node in the grouping. This node is called the refine's 4434 target node. If a node in the grouping is not present as a target 4435 node of a "refine" statement, it is not refined, and thus used 4436 exactly as it was defined in the grouping. 4438 The argument string is a descendant schema node identifier (see 4439 Section 6.5). 4441 The following refinements can be done: 4443 o A leaf or choice node may get a default value, or a new default 4444 value if it already had one. 4446 o A leaf-list node may get a set of default values, or a new set of 4447 default values if it already had defaults; i.e., the set of 4448 refined default values replaces the defaults already given. 4450 o Any node may get a specialized "description" string. 4452 o Any node may get a specialized "reference" string. 4454 o Any node may get a different "config" statement. 4456 o A leaf, anydata, anyxml, or choice node may get a different 4457 "mandatory" statement. 4459 o A container node may get a "presence" statement. 4461 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4462 get additional "must" expressions. 4464 o A leaf-list or list node may get a different "min-elements" or 4465 "max-elements" statement. 4467 o A leaf, leaf-list, list, container, choice, case, anydata, or 4468 anyxml node may get additional "if-feature" expressions. 4470 o Any node can get refined extensions, if the extension allows 4471 refinement. See Section 7.19 for details. 4473 7.13.3. XML Encoding Rules 4475 Each node in the grouping is encoded as if it was defined inline, 4476 even if it is imported from another module with another XML 4477 namespace. 4479 7.13.4. Usage Example 4481 To use the "endpoint" grouping defined in Section 7.12.2 in a 4482 definition of an HTTP server in some other module, we can do: 4484 import example-system { 4485 prefix "sys"; 4486 } 4488 container http-server { 4489 leaf name { 4490 type string; 4491 } 4492 uses sys:endpoint; 4493 } 4495 A corresponding XML instance example: 4497 4498 extern-web 4499 192.0.2.1 4500 80 4501 4503 If port 80 should be the default for the HTTP server, default can be 4504 added: 4506 container http-server { 4507 leaf name { 4508 type string; 4509 } 4510 uses sys:endpoint { 4511 refine port { 4512 default 80; 4513 } 4514 } 4515 } 4517 If we want to define a list of servers, and each server has the ip 4518 and port as keys, we can do: 4520 list server { 4521 key "ip port"; 4522 leaf name { 4523 type string; 4524 } 4525 uses sys:endpoint; 4526 } 4528 The following is an error: 4530 container http-server { 4531 uses sys:endpoint; 4532 leaf ip { // illegal - same identifier "ip" used twice 4533 type string; 4534 } 4535 } 4537 7.14. The rpc Statement 4539 The "rpc" statement is used to define an RPC operation. It takes one 4540 argument, which is an identifier, followed by a block of 4541 substatements that holds detailed rpc information. This argument is 4542 the name of the RPC. 4544 The "rpc" statement defines an rpc node in the schema tree. Under 4545 the rpc node, a schema node with the name "input", and a schema node 4546 with the name "output" are also defined. The nodes "input" and 4547 "output" are defined in the module's namespace. 4549 7.14.1. The rpc's Substatements 4551 +--------------+---------+-------------+ 4552 | substatement | section | cardinality | 4553 +--------------+---------+-------------+ 4554 | description | 7.21.3 | 0..1 | 4555 | grouping | 7.12 | 0..n | 4556 | if-feature | 7.20.2 | 0..n | 4557 | input | 7.14.2 | 0..1 | 4558 | output | 7.14.3 | 0..1 | 4559 | reference | 7.21.4 | 0..1 | 4560 | status | 7.21.2 | 0..1 | 4561 | typedef | 7.3 | 0..n | 4562 +--------------+---------+-------------+ 4564 7.14.2. The input Statement 4566 The "input" statement, which is optional, is used to define input 4567 parameters to the operation. It does not take an argument. The 4568 substatements to "input" define nodes under the operation's input 4569 node. 4571 If a leaf in the input tree has a "mandatory" statement with the 4572 value "true", the leaf MUST be present in an RPC invocation. 4574 If a leaf in the input tree has a default value, the server MUST use 4575 this value in the same cases as described in Section 7.6.1. In these 4576 cases, the server MUST operationally behave as if the leaf was 4577 present in the RPC invocation with the default value as its value. 4579 If a leaf-list in the input tree has one or more default values, the 4580 server MUST use these values in the same cases as described in 4581 Section 7.7.2. In these cases, the server MUST operationally behave 4582 as if the leaf-list was present in the RPC invocation with the 4583 default values as its values. 4585 Since the input tree is not part of any datastore, all "config" 4586 statements for nodes in the input tree are ignored. 4588 If any node has a "when" statement that would evaluate to false, then 4589 this node MUST NOT be present in the input tree. 4591 7.14.2.1. The input's Substatements 4593 +--------------+---------+-------------+ 4594 | substatement | section | cardinality | 4595 +--------------+---------+-------------+ 4596 | anydata | 7.10 | 0..n | 4597 | anyxml | 7.11 | 0..n | 4598 | choice | 7.9 | 0..n | 4599 | container | 7.5 | 0..n | 4600 | grouping | 7.12 | 0..n | 4601 | leaf | 7.6 | 0..n | 4602 | leaf-list | 7.7 | 0..n | 4603 | list | 7.8 | 0..n | 4604 | must | 7.5.3 | 0..n | 4605 | typedef | 7.3 | 0..n | 4606 | uses | 7.13 | 0..n | 4607 +--------------+---------+-------------+ 4609 7.14.3. The output Statement 4611 The "output" statement, which is optional, is used to define output 4612 parameters to the RPC operation. It does not take an argument. The 4613 substatements to "output" define nodes under the operation's output 4614 node. 4616 If a leaf in the output tree has a "mandatory" statement with the 4617 value "true", the leaf MUST be present in an RPC reply. 4619 If a leaf in the output tree has a default value, the client MUST use 4620 this value in the same cases as described in Section 7.6.1. In these 4621 cases, the client MUST operationally behave as if the leaf was 4622 present in the RPC reply with the default value as its value. 4624 If a leaf-list in the output tree has one or more default values, the 4625 client MUST use these values in the same cases as described in 4626 Section 7.7.2. In these cases, the client MUST operationally behave 4627 as if the leaf-list was present in the RPC reply with the default 4628 values as its values. 4630 Since the output tree is not part of any datastore, all "config" 4631 statements for nodes in the output tree are ignored. 4633 If any node has a "when" statement that would evaluate to false, then 4634 this node MUST NOT be present in the output tree. 4636 7.14.3.1. The output's Substatements 4638 +--------------+---------+-------------+ 4639 | substatement | section | cardinality | 4640 +--------------+---------+-------------+ 4641 | anydata | 7.10 | 0..n | 4642 | anyxml | 7.11 | 0..n | 4643 | choice | 7.9 | 0..n | 4644 | container | 7.5 | 0..n | 4645 | grouping | 7.12 | 0..n | 4646 | leaf | 7.6 | 0..n | 4647 | leaf-list | 7.7 | 0..n | 4648 | list | 7.8 | 0..n | 4649 | must | 7.5.3 | 0..n | 4650 | typedef | 7.3 | 0..n | 4651 | uses | 7.13 | 0..n | 4652 +--------------+---------+-------------+ 4654 7.14.4. NETCONF XML Encoding Rules 4656 An rpc node is encoded as a child XML element to the element, 4657 as designated by the substitution group "rpcOperation" in [RFC6241]. 4658 The element's local name is the rpc's identifier, and its namespace 4659 is the module's XML namespace (see Section 7.1.3). 4661 Input parameters are encoded as child XML elements to the rpc node's 4662 XML element, in the same order as they are defined within the "input" 4663 statement. 4665 If the RPC operation invocation succeeded, and no output parameters 4666 are returned, the contains a single element defined 4667 in [RFC6241]. If output parameters are returned, they are encoded as 4668 child elements to the element defined in [RFC6241], in 4669 the same order as they are defined within the "output" statement. 4671 7.14.5. Usage Example 4673 The following example defines an RPC operation: 4675 module example-rock { 4676 yang-version 1.1; 4677 namespace "urn:example:rock"; 4678 prefix "rock"; 4680 rpc rock-the-house { 4681 input { 4682 leaf zip-code { 4683 type string; 4684 } 4685 } 4686 } 4687 } 4689 A corresponding XML instance example of the complete rpc and rpc- 4690 reply: 4692 4694 4695 27606-0100 4696 4697 4699 4701 4702 4704 7.15. The action Statement 4706 The "action" statement is used to define an operation connected to a 4707 specific container or list data node. It takes one argument, which 4708 is an identifier, followed by a block of substatements that holds 4709 detailed action information. The argument is the name of the action. 4711 The "action" statement defines an action node in the schema tree. 4712 Under the action node, a schema node with the name "input", and a 4713 schema node with the name "output" are also defined. The nodes 4714 "input" and "output" are defined in the module's namespace. 4716 An action MUST NOT be defined within an rpc, another action or a 4717 notification, i.e., an action node MUST NOT have an rpc, action, or a 4718 notification node as one of its ancestors in the schema tree. For 4719 example, this means that it is an error if a grouping that contains 4720 an action somewhere in its node hierarchy is used in a notification 4721 definition. 4723 An action MUST NOT have any ancestor node that is a list node without 4724 a "key" statement. 4726 Since an action cannot be defined at the top-level of a module or in 4727 a case statement, it is an error if a grouping that contains an 4728 action at the top of its node hierarchy is used at the top-level of a 4729 module or in a case definition. 4731 The difference between an action and an rpc is that an action is tied 4732 to a node in the datastore, whereas an rpc is not. When an action is 4733 invoked, the node in the datastore is specified along with the name 4734 of the action and the input parameters. 4736 7.15.1. The action's Substatements 4738 +--------------+---------+-------------+ 4739 | substatement | section | cardinality | 4740 +--------------+---------+-------------+ 4741 | description | 7.21.3 | 0..1 | 4742 | grouping | 7.12 | 0..n | 4743 | if-feature | 7.20.2 | 0..n | 4744 | input | 7.14.2 | 0..1 | 4745 | output | 7.14.3 | 0..1 | 4746 | reference | 7.21.4 | 0..1 | 4747 | status | 7.21.2 | 0..1 | 4748 | typedef | 7.3 | 0..n | 4749 +--------------+---------+-------------+ 4751 7.15.2. NETCONF XML Encoding Rules 4753 When an action is invoked, an element with the local name "action" in 4754 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4755 encoded as a child XML element to the element defined in 4756 [RFC6241], as designated by the substitution group "rpcOperation" in 4757 [RFC6241]. 4759 The "action" element contains an hierarchy of nodes that identifies 4760 the node in the datastore. It MUST contain all containers and list 4761 nodes in the direct path from the top level down to the list or 4762 container containing the action. For lists, all key leafs MUST also 4763 be included. The last container or list contains an XML element that 4764 carries the name of the defined action. Within this element the 4765 input parameters are encoded as child XML elements, in the same order 4766 as they are defined within the "input" statement. 4768 Only one action can be invoked in one . If more than one action 4769 is present in the , the server MUST reply with an "bad-element" 4770 error-tag in the . 4772 If the action operation invocation succeeded, and no output 4773 parameters are returned, the contains a single 4774 element defined in [RFC6241]. If output parameters are returned, 4775 they are encoded as child elements to the element defined 4776 in [RFC6241], in the same order as they are defined within the 4777 "output" statement. 4779 7.15.3. Usage Example 4781 The following example defines an action to reset one server at a 4782 server farm: 4784 module example-server-farm { 4785 yang-version 1.1; 4786 namespace "urn:example:server-farm"; 4787 prefix "sfarm"; 4789 import ietf-yang-types { 4790 prefix "yang"; 4791 } 4793 list server { 4794 key name; 4795 leaf name { 4796 type string; 4797 } 4798 action reset { 4799 input { 4800 leaf reset-at { 4801 type yang:date-and-time; 4802 mandatory true; 4803 } 4804 } 4805 output { 4806 leaf reset-finished-at { 4807 type yang:date-and-time; 4808 mandatory true; 4809 } 4810 } 4811 } 4812 } 4813 } 4815 A corresponding XML instance example of the complete rpc and rpc- 4816 reply: 4818 4820 4821 4822 apache-1 4823 4824 2014-07-29T13:42:00Z 4825 4826 4827 4828 4830 4832 4833 2014-07-29T13:42:12Z 4834 4835 4837 7.16. The notification Statement 4839 The "notification" statement is used to define a notification. It 4840 takes one argument, which is an identifier, followed by a block of 4841 substatements that holds detailed notification information. The 4842 "notification" statement defines a notification node in the schema 4843 tree. 4845 A notification can be defined at the top-level of a module, or 4846 connected to a specific container or list data node in the schema 4847 tree. 4849 A notification MUST NOT be defined within an rpc, action or another 4850 notification, i.e., a notification node MUST NOT have an rpc, action, 4851 or a notification node as one of its ancestors in the schema tree. 4852 For example, this means that it is an error if a grouping that 4853 contains an notification somewhere in its node hierarchy is used in 4854 an rpc definition. 4856 A notification MUST NOT have any ancestor node that is a list node 4857 without a "key" statement. 4859 Since a notification cannot be defined in a case statement, it is an 4860 error if a grouping that contains a notification at the top of its 4861 node hierarchy is used in a case definition. 4863 If a leaf in the notification tree has a "mandatory" statement with 4864 the value "true", the leaf MUST be present in a notification 4865 instance. 4867 If a leaf in the notification tree has a default value, the client 4868 MUST use this value in the same cases as described in Section 7.6.1. 4869 In these cases, the client MUST operationally behave as if the leaf 4870 was present in the notification instance with the default value as 4871 its value. 4873 If a leaf-list in the notification tree has one or more default 4874 values, the client MUST use these values in the same cases as 4875 described in Section 7.7.2. In these cases, the client MUST 4876 operationally behave as if the leaf-list was present in the 4877 notification instance with the default values as its values. 4879 Since the notification tree is not part of any datastore, all 4880 "config" statements for nodes in the notification tree are ignored. 4882 7.16.1. The notification's Substatements 4884 +--------------+---------+-------------+ 4885 | substatement | section | cardinality | 4886 +--------------+---------+-------------+ 4887 | anydata | 7.10 | 0..n | 4888 | anyxml | 7.11 | 0..n | 4889 | choice | 7.9 | 0..n | 4890 | container | 7.5 | 0..n | 4891 | description | 7.21.3 | 0..1 | 4892 | grouping | 7.12 | 0..n | 4893 | if-feature | 7.20.2 | 0..n | 4894 | leaf | 7.6 | 0..n | 4895 | leaf-list | 7.7 | 0..n | 4896 | list | 7.8 | 0..n | 4897 | must | 7.5.3 | 0..n | 4898 | reference | 7.21.4 | 0..1 | 4899 | status | 7.21.2 | 0..1 | 4900 | typedef | 7.3 | 0..n | 4901 | uses | 7.13 | 0..n | 4902 +--------------+---------+-------------+ 4904 7.16.2. NETCONF XML Encoding Rules 4906 A notification node that is defined on the top-level of a module is 4907 encoded as a child XML element to the element defined 4908 in NETCONF Event Notifications [RFC5277]. The element's local name 4909 is the notification's identifier, and its namespace is the module's 4910 XML namespace (see Section 7.1.3). 4912 When a notification node is defined as a child to a data node, the 4913 element defined in NETCONF Event Notifications 4914 [RFC5277] contains an hierarchy of nodes that identifies the node in 4915 the datastore. It MUST contain all containers and list nodes from 4916 the top level down to the list or container containing the 4917 notification. For lists, all key leafs MUST also be included. The 4918 last container or list contains an XML element that carries the name 4919 of the defined notification. 4921 The notification's child nodes are encoded as subelements to the 4922 notification node's XML element, in any order. 4924 7.16.3. Usage Example 4926 The following example defines a notification at the top-level of a 4927 module: 4929 module example-event { 4930 yang-version 1.1; 4931 namespace "urn:example:event"; 4932 prefix "ev"; 4934 notification event { 4935 leaf event-class { 4936 type string; 4937 } 4938 leaf reporting-entity { 4939 type instance-identifier; 4940 } 4941 leaf severity { 4942 type string; 4943 } 4944 } 4945 } 4947 A corresponding XML instance example of the complete notification: 4949 4951 2008-07-08T00:01:00Z 4952 4953 fault 4954 4955 /ex:interface[ex:name='Ethernet0'] 4956 4957 major 4958 4959 4961 The following example defines a notification in a data node: 4963 module example-interface-module { 4964 yang-version 1.1; 4965 namespace "urn:example:interface-module"; 4966 prefix "if"; 4968 container interfaces { 4969 list interface { 4970 key "name"; 4971 leaf name { 4972 type string; 4973 } 4974 notification interface-enabled { 4975 leaf by-user { 4976 type string; 4977 } 4978 } 4979 } 4980 } 4981 } 4983 A corresponding XML instance example of the complete notification: 4985 4987 2008-07-08T00:01:00Z 4988 4989 4990 eth1 4991 4992 fred 4993 4994 4995 4996 4998 7.17. The augment Statement 5000 The "augment" statement allows a module or submodule to add to the 5001 schema tree defined in an external module, or the current module and 5002 its submodules, and to add to the nodes from a grouping in a "uses" 5003 statement. The argument is a string that identifies a node in the 5004 schema tree. This node is called the augment's target node. The 5005 target node MUST be either a container, list, choice, case, input, 5006 output, or notification node. It is augmented with the nodes defined 5007 in the substatements that follow the "augment" statement. 5009 The argument string is a schema node identifier (see Section 6.5). 5010 If the "augment" statement is on the top level in a module or 5011 submodule, the absolute form (defined by the rule 5012 "absolute-schema-nodeid" in Section 14) of a schema node identifier 5013 MUST be used. If the "augment" statement is a substatement to the 5014 "uses" statement, the descendant form (defined by the rule 5015 "descendant-schema-nodeid" in Section 14) MUST be used. 5017 If the target node is a container, list, case, input, output, or 5018 notification node, the "container", "leaf", "list", "leaf-list", 5019 "uses", and "choice" statements can be used within the "augment" 5020 statement. 5022 If the target node is a container or list node, the "action" and 5023 "notification" statements can be used within the "augment" statement. 5025 If the target node is a choice node, the "case" statement, or a case 5026 shorthand statement (see Section 7.9.2) can be used within the 5027 "augment" statement. 5029 The "augment" statement MUST NOT add multiple nodes with the same 5030 name from the same module to the target node. 5032 If the augmentation adds mandatory configuration nodes (see 5033 Section 3) to a target node in another module, the augmentation MUST 5034 be conditional with a "when" statement. Care must be taken when 5035 defining the "when" expression, so that clients that do not know 5036 about the augmenting module do not break. 5038 In the following example, it is OK to augment the "interface" entry 5039 with "mandatory-leaf" because the augmentation depends on support for 5040 "some-new-iftype". The old client does not know about this type so 5041 it would never select this type, and therefore not be adding a 5042 mandatory data node. 5044 module example-augment { 5045 yang-version 1.1; 5046 namespace "urn:example:augment"; 5047 prefix mymod; 5049 import ietf-interfaces { 5050 prefix if; 5051 } 5053 identity some-new-iftype { 5054 base if:interface-type; 5055 } 5057 augment "/if:interfaces/if:interface" { 5058 when 'derived-from-or-self(if:type, "mymod:some-new-iftype")'; 5060 leaf mandatory-leaf { 5061 mandatory true; 5062 type string; 5063 } 5064 } 5065 } 5067 7.17.1. The augment's Substatements 5069 +--------------+---------+-------------+ 5070 | substatement | section | cardinality | 5071 +--------------+---------+-------------+ 5072 | action | 7.15 | 0..n | 5073 | anydata | 7.10 | 0..n | 5074 | anyxml | 7.11 | 0..n | 5075 | case | 7.9.2 | 0..n | 5076 | choice | 7.9 | 0..n | 5077 | container | 7.5 | 0..n | 5078 | description | 7.21.3 | 0..1 | 5079 | if-feature | 7.20.2 | 0..n | 5080 | leaf | 7.6 | 0..n | 5081 | leaf-list | 7.7 | 0..n | 5082 | list | 7.8 | 0..n | 5083 | notification | 7.16 | 0..n | 5084 | reference | 7.21.4 | 0..1 | 5085 | status | 7.21.2 | 0..1 | 5086 | uses | 7.13 | 0..n | 5087 | when | 7.21.5 | 0..1 | 5088 +--------------+---------+-------------+ 5090 7.17.2. XML Encoding Rules 5092 All data nodes defined in the "augment" statement are defined as XML 5093 elements in the XML namespace of the module where the "augment" is 5094 specified. 5096 When a node is augmented, the augmenting child nodes are encoded as 5097 subelements to the augmented node, in any order. 5099 7.17.3. Usage Example 5101 In namespace urn:example:interface-module, we have: 5103 container interfaces { 5104 list ifEntry { 5105 key "ifIndex"; 5107 leaf ifIndex { 5108 type uint32; 5109 } 5110 leaf ifDescr { 5111 type string; 5112 } 5113 leaf ifType { 5114 type iana:IfType; 5115 } 5116 leaf ifMtu { 5117 type int32; 5118 } 5119 } 5120 } 5122 Then, in namespace urn:example:ds0, we have: 5124 import example-interface-module { 5125 prefix "if"; 5126 } 5127 augment "/if:interfaces/if:ifEntry" { 5128 when "if:ifType='ds0'"; 5129 leaf ds0ChannelNumber { 5130 type ChannelNumber; 5131 } 5132 } 5134 A corresponding XML instance example: 5136 5138 5139 1 5140 Flintstone Inc Ethernet A562 5141 ethernetCsmacd 5142 1500 5143 5144 5145 2 5146 Flintstone Inc DS0 5147 ds0 5148 1 5149 5150 5152 As another example, suppose we have the choice defined in 5153 Section 7.9.6. The following construct can be used to extend the 5154 protocol definition: 5156 augment /ex:system/ex:protocol/ex:name { 5157 case c { 5158 leaf smtp { 5159 type empty; 5160 } 5161 } 5162 } 5164 A corresponding XML instance example: 5166 5167 5168 5169 5170 5172 or 5174 5175 5176 5177 5178 5180 7.18. The identity Statement 5182 The "identity" statement is used to define a new globally unique, 5183 abstract, and untyped identity. Its only purpose is to denote its 5184 name, semantics, and existence. An identity can either be defined 5185 from scratch or derived from one or more base identities. The 5186 identity's argument is an identifier that is the name of the 5187 identity. It is followed by a block of substatements that holds 5188 detailed identity information. 5190 The built-in datatype "identityref" (see Section 9.10) can be used to 5191 reference identities within a data model. 5193 7.18.1. The identity's Substatements 5195 +--------------+---------+-------------+ 5196 | substatement | section | cardinality | 5197 +--------------+---------+-------------+ 5198 | base | 7.18.2 | 0..n | 5199 | description | 7.21.3 | 0..1 | 5200 | if-feature | 7.20.2 | 0..n | 5201 | reference | 7.21.4 | 0..1 | 5202 | status | 7.21.2 | 0..1 | 5203 +--------------+---------+-------------+ 5205 7.18.2. The base Statement 5207 The "base" statement, which is optional, takes as an argument a 5208 string that is the name of an existing identity, from which the new 5209 identity is derived. If no "base" statement is present, the identity 5210 is defined from scratch. If multiple "base" statements are present, 5211 the identity is derived from all of them. 5213 If a prefix is present on the base name, it refers to an identity 5214 defined in the module that was imported with that prefix, or the 5215 local module if the prefix matches the local module's prefix. 5216 Otherwise, an identity with the matching name MUST be defined in the 5217 current module or an included submodule. 5219 An identity MUST NOT reference itself, neither directly nor 5220 indirectly through a chain of other identities. 5222 The derivation of identities has the following properties: 5224 o It is irreflexive, which means that an identity is not derived 5225 from itself. 5227 o It is transitive, which means that if identity B is derived from A 5228 and C is derived from B, then C is also derived from A. 5230 7.18.3. Usage Example 5231 module example-crypto-base { 5232 yang-version 1.1; 5233 namespace "urn:example:crypto-base"; 5234 prefix "crypto"; 5236 identity crypto-alg { 5237 description 5238 "Base identity from which all crypto algorithms 5239 are derived."; 5240 } 5242 identity symmetric-key { 5243 description 5244 "Base identity used to identify symmetric-key crypto 5245 algorithms."; 5246 } 5248 identity public-key { 5249 description 5250 "Base identity used to identify public-key crypto 5251 algorithms."; 5252 } 5253 } 5255 module example-des { 5256 yang-version 1.1; 5257 namespace "urn:example:des"; 5258 prefix "des"; 5260 import "example-crypto-base" { 5261 prefix "crypto"; 5262 } 5264 identity des { 5265 base "crypto:crypto-alg"; 5266 base "crypto:symmetric-key"; 5267 description "DES crypto algorithm"; 5268 } 5270 identity des3 { 5271 base "crypto:crypto-alg"; 5272 base "crypto:symmetric-key"; 5273 description "Triple DES crypto algorithm"; 5274 } 5275 } 5277 7.19. The extension Statement 5279 The "extension" statement allows the definition of new statements 5280 within the YANG language. This new statement definition can be 5281 imported and used by other modules. 5283 The statement's argument is an identifier that is the new keyword for 5284 the extension and must be followed by a block of substatements that 5285 holds detailed extension information. The purpose of the "extension" 5286 statement is to define a keyword, so that it can be imported and used 5287 by other modules. 5289 The extension can be used like a normal YANG statement, with the 5290 statement name followed by an argument if one is defined by the 5291 "extension" statement, and an optional block of substatements. The 5292 statement's name is created by combining the prefix of the module in 5293 which the extension was defined, a colon (":"), and the extension's 5294 keyword, with no interleaving whitespace. The substatements of an 5295 extension are defined by the "extension" statement, using some 5296 mechanism outside the scope of this specification. Syntactically, 5297 the substatements MUST be YANG statements, or also extensions defined 5298 using "extension" statements. YANG statements in extensions MUST 5299 follow the syntactical rules in Section 14. 5301 An extension can allow refinement (see Section 7.13.2) and deviations 5302 (Section 7.20.3.2), but the mechanism for how this is defined is 5303 outside the scope of this specification. 5305 7.19.1. The extension's Substatements 5307 +--------------+---------+-------------+ 5308 | substatement | section | cardinality | 5309 +--------------+---------+-------------+ 5310 | argument | 7.19.2 | 0..1 | 5311 | description | 7.21.3 | 0..1 | 5312 | reference | 7.21.4 | 0..1 | 5313 | status | 7.21.2 | 0..1 | 5314 +--------------+---------+-------------+ 5316 7.19.2. The argument Statement 5318 The "argument" statement, which is optional, takes as an argument a 5319 string that is the name of the argument to the keyword. If no 5320 argument statement is present, the keyword expects no argument when 5321 it is used. 5323 The argument's name is used in the YIN mapping, where it is used as 5324 an XML attribute or element name, depending on the argument's 5325 "yin-element" statement. 5327 7.19.2.1. The argument's Substatements 5329 +--------------+----------+-------------+ 5330 | substatement | section | cardinality | 5331 +--------------+----------+-------------+ 5332 | yin-element | 7.19.2.2 | 0..1 | 5333 +--------------+----------+-------------+ 5335 7.19.2.2. The yin-element Statement 5337 The "yin-element" statement, which is optional, takes as an argument 5338 the string "true" or "false". This statement indicates if the 5339 argument is mapped to an XML element in YIN or to an XML attribute 5340 (see Section 13). 5342 If no "yin-element" statement is present, it defaults to "false". 5344 7.19.3. Usage Example 5346 To define an extension: 5348 module example-extensions { 5349 yang-version 1.1; 5350 ... 5352 extension c-define { 5353 description 5354 "Takes as argument a name string. 5355 Makes the code generator use the given name in the 5356 #define."; 5357 argument "name"; 5358 } 5359 } 5361 To use the extension: 5363 module example-interfaces { 5364 yang-version 1.1; 5366 ... 5367 import example-extensions { 5368 prefix "myext"; 5369 } 5370 ... 5372 container interfaces { 5373 ... 5374 myext:c-define "MY_INTERFACES"; 5375 } 5376 } 5378 7.20. Conformance-Related Statements 5380 This section defines statements related to conformance, as described 5381 in Section 5.6. 5383 7.20.1. The feature Statement 5385 The "feature" statement is used to define a mechanism by which 5386 portions of the schema are marked as conditional. A feature name is 5387 defined that can later be referenced using the "if-feature" statement 5388 (see Section 7.20.2). Schema nodes tagged with an "if-feature" 5389 statement are ignored by the server unless the server supports the 5390 given feature expression. This allows portions of the YANG module to 5391 be conditional based on conditions in the server. The model can 5392 represent the abilities of the server within the model, giving a 5393 richer model that allows for differing server abilities and roles. 5395 The argument to the "feature" statement is the name of the new 5396 feature, and follows the rules for identifiers in Section 6.2. This 5397 name is used by the "if-feature" statement to tie the schema nodes to 5398 the feature. 5400 In this example, a feature called "local-storage" represents the 5401 ability for a server to store syslog messages on local storage of 5402 some sort. This feature is used to make the "local-storage-limit" 5403 leaf conditional on the presence of some sort of local storage. If 5404 the server does not report that it supports this feature, the 5405 "local-storage-limit" node is not supported. 5407 module example-syslog { 5408 yang-version 1.1; 5410 ... 5411 feature local-storage { 5412 description 5413 "This feature means the server supports local 5414 storage (memory, flash or disk) that can be used to 5415 store syslog messages."; 5416 } 5418 container syslog { 5419 leaf local-storage-limit { 5420 if-feature local-storage; 5421 type uint64; 5422 units "kilobyte"; 5423 config false; 5424 description 5425 "The amount of local storage that can be 5426 used to hold syslog messages."; 5427 } 5428 } 5429 } 5431 The "if-feature" statement can be used in many places within the YANG 5432 syntax. Definitions tagged with "if-feature" are ignored when the 5433 server does not support that feature. 5435 A feature MUST NOT reference itself, neither directly nor indirectly 5436 through a chain of other features. 5438 In order for a server to support a feature that is dependent on any 5439 other features (i.e., the feature has one or more "if-feature" 5440 substatements), the server MUST also support all the dependant 5441 features. 5443 7.20.1.1. The feature's Substatements 5445 +--------------+---------+-------------+ 5446 | substatement | section | cardinality | 5447 +--------------+---------+-------------+ 5448 | description | 7.21.3 | 0..1 | 5449 | if-feature | 7.20.2 | 0..n | 5450 | status | 7.21.2 | 0..1 | 5451 | reference | 7.21.4 | 0..1 | 5452 +--------------+---------+-------------+ 5454 7.20.2. The if-feature Statement 5456 The "if-feature" statement makes its parent statement conditional. 5457 The argument is a boolean expression over feature names. In this 5458 expression, a feature name evaluates to "true" if and only if the 5459 feature is supported by the server. The parent statement is 5460 implemented by servers where the boolean expression evaluates to 5461 "true". 5463 The if-feature boolean expression syntax is formally defined by the 5464 rule "if-feature-expr" in Section 14. Parenthesis are used to group 5465 expressions. When the expression is evaluated, the order of 5466 precedence is (highest precedence first): grouping (parenthesis), 5467 "not", "and", "or". 5469 If a prefix is present on a feature name in the boolean expression, 5470 the prefixed name refers to a feature defined in the module that was 5471 imported with that prefix, or the local module if the prefix matches 5472 the local module's prefix. Otherwise, a feature with the matching 5473 name MUST be defined in the current module or an included submodule. 5475 A leaf that is a list key MUST NOT have any "if-feature" statements. 5477 7.20.2.1. Usage Example 5479 In this example, the container "target" is implemented if any of the 5480 features "outbound-tls" or "outbound-ssh" are supported by the 5481 server. 5483 container target { 5484 if-feature "outbound-tls or outbound-ssh"; 5485 ... 5486 } 5488 The following examples are equivalent: 5490 if-feature "not foo or bar and baz"; 5492 if-feature "(not foo) or (bar and baz)"; 5494 7.20.3. The deviation Statement 5496 The "deviation" statement defines a hierarchy of a module that the 5497 server does not implement faithfully. The argument is a string that 5498 identifies the node in the schema tree where a deviation from the 5499 module occurs. This node is called the deviation's target node. The 5500 contents of the "deviation" statement give details about the 5501 deviation. 5503 The argument string is an absolute schema node identifier (see 5504 Section 6.5). 5506 Deviations define the way a server or class of servers deviate from a 5507 standard. This means that deviations MUST never be part of a 5508 published standard, since they are the mechanism for learning how 5509 implementations vary from the standards. 5511 Server deviations are strongly discouraged and MUST only be used as a 5512 last resort. Telling the application how a server fails to follow a 5513 standard is no substitute for implementing the standard correctly. A 5514 server that deviates from a module is not fully compliant with the 5515 module. 5517 However, in some cases, a particular device may not have the hardware 5518 or software ability to support parts of a standard module. When this 5519 occurs, the server makes a choice either to treat attempts to 5520 configure unsupported parts of the module as an error that is 5521 reported back to the unsuspecting application or ignore those 5522 incoming requests. Neither choice is acceptable. 5524 Instead, YANG allows servers to document portions of a base module 5525 that are not supported or supported but with different syntax, by 5526 using the "deviation" statement. 5528 7.20.3.1. The deviation's Substatements 5530 +--------------+----------+-------------+ 5531 | substatement | section | cardinality | 5532 +--------------+----------+-------------+ 5533 | description | 7.21.3 | 0..1 | 5534 | deviate | 7.20.3.2 | 1..n | 5535 | reference | 7.21.4 | 0..1 | 5536 +--------------+----------+-------------+ 5538 7.20.3.2. The deviate Statement 5540 The "deviate" statement defines how the server's implementation of 5541 the target node deviates from its original definition. The argument 5542 is one of the strings "not-supported", "add", "replace", or "delete". 5544 The argument "not-supported" indicates that the target node is not 5545 implemented by this server. 5547 The argument "add" adds properties to the target node. The 5548 properties to add are identified by substatements to the "deviate" 5549 statement. If a property can only appear once, the property MUST NOT 5550 exist in the target node. 5552 The argument "replace" replaces properties of the target node. The 5553 properties to replace are identified by substatements to the 5554 "deviate" statement. The properties to replace MUST exist in the 5555 target node. 5557 The argument "delete" deletes properties from the target node. The 5558 properties to delete are identified by substatements to the "delete" 5559 statement. The substatement's keyword MUST match a corresponding 5560 keyword in the target node, and the argument's string MUST be equal 5561 to the corresponding keyword's argument string in the target node. 5563 +--------------+-------------+-------------+ 5564 | substatement | section | cardinality | 5565 +--------------+-------------+-------------+ 5566 | config | 7.21.1 | 0..1 | 5567 | default | 7.6.4 7.7.4 | 0..n | 5568 | mandatory | 7.6.5 | 0..1 | 5569 | max-elements | 7.7.6 | 0..1 | 5570 | min-elements | 7.7.5 | 0..1 | 5571 | must | 7.5.3 | 0..n | 5572 | type | 7.4 | 0..1 | 5573 | unique | 7.8.3 | 0..n | 5574 | units | 7.3.3 | 0..1 | 5575 +--------------+-------------+-------------+ 5577 The deviate's Substatements 5579 If the target node has a property defined by an extension, this 5580 property can be deviated if the extension allows deviations. See 5581 Section 7.19 for details. 5583 7.20.3.3. Usage Example 5585 In this example, the server is informing client applications that it 5586 does not support the "daytime" service in the style of RFC 867. 5588 module example-deviations { 5589 yang-version 1.1; 5590 namespace "urn:example:deviations"; 5591 prefix md; 5593 import example-base { 5594 prefix base; 5595 } 5597 deviation /base:system/base:daytime { 5598 deviate not-supported; 5599 } 5600 ... 5601 } 5603 A server would advertise both modules "example-base" and 5604 "example-deviations". 5606 The following example sets a server-specific default value to a leaf 5607 that does not have a default value defined: 5609 deviation /base:system/base:user/base:type { 5610 deviate add { 5611 default "admin"; // new users are 'admin' by default 5612 } 5613 } 5615 In this example, the server limits the number of name servers to 3: 5617 deviation /base:system/base:name-server { 5618 deviate replace { 5619 max-elements 3; 5620 } 5621 } 5623 If the original definition is: 5625 container system { 5626 must "daytime or time"; 5627 ... 5628 } 5630 a server might remove this must constraint by doing: 5632 deviation /base:system { 5633 deviate delete { 5634 must "daytime or time"; 5635 } 5636 } 5638 7.21. Common Statements 5640 This section defines substatements common to several other 5641 statements. 5643 7.21.1. The config Statement 5645 The "config" statement takes as an argument the string "true" or 5646 "false". If "config" is "true", the definition represents 5647 configuration. Data nodes representing configuration are part of 5648 configuration datastores. 5650 If "config" is "false", the definition represents state data. Data 5651 nodes representing state data are not part of configuration 5652 datastores. 5654 If "config" is not specified, the default is the same as the parent 5655 schema node's "config" value. If the parent node is a "case" node, 5656 the value is the same as the "case" node's parent "choice" node. 5658 If the top node does not specify a "config" statement, the default is 5659 "true". 5661 If a node has "config" set to "false", no node underneath it can have 5662 "config" set to "true". 5664 7.21.2. The status Statement 5666 The "status" statement takes as an argument one of the strings 5667 "current", "deprecated", or "obsolete". 5669 o "current" means that the definition is current and valid. 5671 o "deprecated" indicates an obsolete definition, but it permits new/ 5672 continued implementation in order to foster interoperability with 5673 older/existing implementations. 5675 o "obsolete" means the definition is obsolete and SHOULD NOT be 5676 implemented and/or can be removed from implementations. 5678 If no status is specified, the default is "current". 5680 If a definition is "current", it MUST NOT reference a "deprecated" or 5681 "obsolete" definition within the same module. 5683 If a definition is "deprecated", it MUST NOT reference an "obsolete" 5684 definition within the same module. 5686 For example, the following is illegal: 5688 typedef my-type { 5689 status deprecated; 5690 type int32; 5691 } 5693 leaf my-leaf { 5694 status current; 5695 type my-type; // illegal, since my-type is deprecated 5696 } 5698 7.21.3. The description Statement 5700 The "description" statement takes as an argument a string that 5701 contains a human-readable textual description of this definition. 5702 The text is provided in a language (or languages) chosen by the 5703 module developer; for the sake of interoperability, it is RECOMMENDED 5704 to choose a language that is widely understood among the community of 5705 network administrators who will use the module. 5707 7.21.4. The reference Statement 5709 The "reference" statement takes as an argument a string that is used 5710 to specify a textual cross-reference to an external document, either 5711 another module that defines related management information, or a 5712 document that provides additional information relevant to this 5713 definition. 5715 For example, a typedef for a "uri" data type could look like: 5717 typedef uri { 5718 type string; 5719 reference 5720 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5721 ... 5722 } 5724 7.21.5. The when Statement 5726 The "when" statement makes its parent data definition statement 5727 conditional. The node defined by the parent data definition 5728 statement is only valid when the condition specified by the "when" 5729 statement is satisfied. The statement's argument is an XPath 5730 expression (see Section 6.4), which is used to formally specify this 5731 condition. If the XPath expression conceptually evaluates to "true" 5732 for a particular instance, then the node defined by the parent data 5733 definition statement is valid; otherwise, it is not. 5735 A leaf that is a list key MUST NOT have a "when" statement. 5737 If a leaf key is defined in a grouping that is used in a list, the 5738 "uses" statement MUST NOT have a "when" statement. 5740 See Section 8.3.2 for additional information. 5742 The XPath expression is conceptually evaluated in the following 5743 context, in addition to the definition in Section 6.4.1: 5745 o If the "when" statement is a child of an "augment" statement, then 5746 the context node is the augment's target node in the data tree, if 5747 the target node is a data node. Otherwise, the context node is 5748 the closest ancestor node to the target node that is also a data 5749 node. If no such node exists, the context node is the root node. 5750 The accessible tree is tentatively altered during the processing 5751 of the XPath expression by removing all instances (if any) of the 5752 nodes added by the "augment" statement. 5754 o If the "when" statement is a child of a "uses", "choice", or 5755 "case" statement, then the context node is the closest ancestor 5756 node to the "uses", "choice", or "case" node that is also a data 5757 node. If no such node exists, the context node is the root node. 5758 The accessible tree is tentatively altered during the processing 5759 of the XPath expression by removing all instances (if any) of the 5760 nodes added by the "uses", "choice", or "case" statement. 5762 o If the "when" statement is a child of any other data definition 5763 statement, the accessible tree is tentatively altered during the 5764 processing of the XPath expression by replacing all instances of 5765 the data node for which the "when" statement is defined with a 5766 single dummy node with the same name, but with no value and no 5767 children. If no such instance exists, the dummy node is 5768 tentatively created. The context node is this dummy node. 5770 The result of the XPath expression is converted to a boolean value 5771 using the standard XPath rules. 5773 If the XPath expression references any node that also has associated 5774 "when" statements, these "when" expressions MUST be evaluated first. 5775 There MUST NOT be any circular dependencies in these "when" 5776 expressions. 5778 Note that the XPath expression is conceptually evaluated. This means 5779 that an implementation does not have to use an XPath evaluator in the 5780 server. The "when" statement can very well be implemented with 5781 specially written code. 5783 8. Constraints 5785 8.1. Constraints on Data 5787 Several YANG statements define constraints on valid data. These 5788 constraints are enforced in different ways, depending on what type of 5789 data the statement defines. 5791 o If the constraint is defined on configuration data, it MUST be 5792 true in a valid configuration data tree. 5794 o If the constraint is defined on state data, it MUST be true in a 5795 valid state data tree. 5797 o If the constraint is defined on notification content, it MUST be 5798 true in any notification data tree. 5800 o If the constraint is defined on RPC or action input parameters, it 5801 MUST be true in an invocation of the RPC or action operation. 5803 o If the constraint is defined on RPC or action output parameters, 5804 it MUST be true in the RPC or action reply. 5806 The following properties are true in all data trees: 5808 o All leaf data values MUST match the type constraints for the leaf, 5809 including those defined in the type's "range", "length", and 5810 "pattern" properties. 5812 o All key leafs MUST be present for all list entries. 5814 o Nodes MUST be present for at most one case branch in all choices. 5816 o There MUST be no nodes tagged with "if-feature" present if the 5817 "if-feature" expression evaluates to "false" in the server. 5819 o There MUST be no nodes tagged with "when" present if the "when" 5820 condition evaluates to "false" in the data tree. 5822 The following properties are true in a valid data tree: 5824 o All "must" constraints MUST evaluate to "true". 5826 o All referential integrity constraints defined via the "path" 5827 statement MUST be satisfied. 5829 o All "unique" constraints on lists MUST be satisfied. 5831 o The "mandatory" constraint is enforced for leafs and choices, 5832 unless the node or any of its ancestors has a "when" condition or 5833 "if-feature" expression that evaluates to "false". 5835 o The "min-elements" and "max-elements" constraints are enforced for 5836 lists and leaf-lists, unless the node or any of its ancestors has 5837 a "when" condition or "if-feature" expression that evaluates to 5838 "false". 5840 The running configuration datastore MUST always be valid. 5842 8.2. Configuration Data Modifications 5844 o If a request creates configuration data nodes under a "choice", 5845 any existing nodes from other "case" branches in the data tree are 5846 deleted by the server. 5848 o If a request modifies a configuration data node such that any 5849 node's "when" expression becomes false, then the node in the data 5850 tree with the "when" expression is deleted by the server. 5852 8.3. NETCONF Constraint Enforcement Model 5854 For configuration data, there are three windows when constraints MUST 5855 be enforced: 5857 o during parsing of RPC payloads 5859 o during processing of the operation 5861 o during validation 5863 Each of these scenarios is considered in the following sections. 5865 8.3.1. Payload Parsing 5867 When content arrives in RPC payloads, it MUST be well-formed XML, 5868 following the hierarchy and content rules defined by the set of 5869 models the server implements. 5871 o If a leaf data value does not match the type constraints for the 5872 leaf, including those defined in the type's "range", "length", and 5873 "pattern" properties, the server MUST reply with an 5874 "invalid-value" error-tag in the rpc-error, and with the error- 5875 app-tag and error-message associated with the constraint, if any 5876 exist. 5878 o If all keys of a list entry are not present, the server MUST reply 5879 with a "missing-element" error-tag in the rpc-error. 5881 o If data for more than one case branch of a choice is present, the 5882 server MUST reply with a "bad-element" in the rpc-error. 5884 o If data for a node tagged with "if-feature" is present, and the 5885 if-feature expression evaluates to "false" in the server, the 5886 server MUST reply with an "unknown-element" error-tag in the rpc- 5887 error. 5889 o If data for a node tagged with "when" is present, and the "when" 5890 condition evaluates to "false", the server MUST reply with an 5891 "unknown-element" error-tag in the rpc-error. 5893 o For insert handling, if the value for the attributes "before" and 5894 "after" are not valid for the type of the appropriate key leafs, 5895 the server MUST reply with a "bad-attribute" error-tag in the rpc- 5896 error. 5898 o If the attributes "before" and "after" appears in any element that 5899 is not a list whose "ordered-by" property is "user", the server 5900 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 5902 8.3.2. NETCONF Processing 5904 After the incoming data is parsed, the NETCONF server performs the 5905 operation by applying the data to the configuration 5906 datastore. During this processing, the following errors MUST be 5907 detected: 5909 o Delete requests for non-existent data. 5911 o Create requests for existent data. 5913 o Insert requests with "before" or "after" parameters that do not 5914 exist. 5916 o Modification requests for nodes tagged with "when", and the "when" 5917 condition evaluates to "false". In this case the server MUST 5918 reply with an "unknown-element" error-tag in the rpc-error. 5920 8.3.3. Validation 5922 When datastore processing is complete, the final contents MUST obey 5923 all validation constraints. This validation processing is performed 5924 at differing times according to the datastore. If the datastore is 5925 "running" or "startup", these constraints MUST be enforced at the end 5926 of the or operation. If the datastore is 5927 "candidate", the constraint enforcement is delayed until a 5928 or operation. 5930 9. Built-In Types 5932 YANG has a set of built-in types, similar to those of many 5933 programming languages, but with some differences due to special 5934 requirements from the management information model. 5936 Additional types may be defined, derived from those built-in types or 5937 from other derived types. Derived types may use subtyping to 5938 formally restrict the set of possible values. 5940 The different built-in types and their derived types allow different 5941 kinds of subtyping, namely length and regular expression restrictions 5942 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 5943 numeric types (Section 9.2.4). 5945 The lexical representation of a value of a certain type is used in 5946 the XML encoding and when specifying default values and numerical 5947 ranges in YANG modules. 5949 9.1. Canonical Representation 5951 For most types, there is a single canonical representation of the 5952 type's values. Some types allow multiple lexical representations of 5953 the same value, for example, the positive integer "17" can be 5954 represented as "+17" or "17". Implementations MUST support all 5955 lexical representations specified in this document. 5957 When a server sends XML encoded data, it MUST use the canonical form 5958 defined in this section. Other encodings may introduce alternate 5959 representations. Note, however, that values in the data tree are 5960 conceptually stored in the canonical representation as defined in 5961 this section. In particular, any XPath expression evaluations are 5962 done using the canonical form, if the data type has a canonical form. 5963 If the data type does not have a canonical form, the format of the 5964 value MUST match the data type's lexical representation, but the 5965 exact format is implementation dependent. 5967 Some types have a lexical representation that depends on the 5968 encoding, e.g., the XML context in which they occur. These types do 5969 not have a canonical form. 5971 9.2. The Integer Built-In Types 5973 The integer built-in types are int8, int16, int32, int64, uint8, 5974 uint16, uint32, and uint64. They represent signed and unsigned 5975 integers of different sizes: 5977 int8 represents integer values between -128 and 127, inclusively. 5979 int16 represents integer values between -32768 and 32767, 5980 inclusively. 5982 int32 represents integer values between -2147483648 and 2147483647, 5983 inclusively. 5985 int64 represents integer values between -9223372036854775808 and 5986 9223372036854775807, inclusively. 5988 uint8 represents integer values between 0 and 255, inclusively. 5990 uint16 represents integer values between 0 and 65535, inclusively. 5992 uint32 represents integer values between 0 and 4294967295, 5993 inclusively. 5995 uint64 represents integer values between 0 and 18446744073709551615, 5996 inclusively. 5998 9.2.1. Lexical Representation 6000 An integer value is lexically represented as an optional sign ("+" or 6001 "-"), followed by a sequence of decimal digits. If no sign is 6002 specified, "+" is assumed. 6004 For convenience, when specifying a default value for an integer in a 6005 YANG module, an alternative lexical representation can be used, which 6006 represents the value in a hexadecimal or octal notation. The 6007 hexadecimal notation consists of an optional sign ("+" or "-"), the 6008 characters "0x" followed a number of hexadecimal digits, where 6009 letters may be uppercase or lowercase. The octal notation consists 6010 of an optional sign ("+" or "-"), the character "0" followed a number 6011 of octal digits. 6013 Note that if a default value in a YANG module has a leading zero 6014 ("0"), it is interpreted as an octal number. In the XML encoding, an 6015 integer is always interpreted as a decimal number, and leading zeros 6016 are allowed. 6018 Examples: 6020 // legal values 6021 +4711 // legal positive value 6022 4711 // legal positive value 6023 -123 // legal negative value 6024 0xf00f // legal positive hexadecimal value 6025 -0xf // legal negative hexadecimal value 6026 052 // legal positive octal value 6028 // illegal values 6029 - 1 // illegal intermediate space 6031 9.2.2. Canonical Form 6033 The canonical form of a positive integer does not include the sign 6034 "+". Leading zeros are prohibited. The value zero is represented as 6035 "0". 6037 9.2.3. Restrictions 6039 All integer types can be restricted with the "range" statement 6040 (Section 9.2.4). 6042 9.2.4. The range Statement 6044 The "range" statement, which is an optional substatement to the 6045 "type" statement, takes as an argument a range expression string. It 6046 is used to restrict integer and decimal built-in types, or types 6047 derived from those. 6049 A range consists of an explicit value, or a lower-inclusive bound, 6050 two consecutive dots "..", and an upper-inclusive bound. Multiple 6051 values or ranges can be given, separated by "|". If multiple values 6052 or ranges are given, they all MUST be disjoint and MUST be in 6053 ascending order. If a range restriction is applied to an already 6054 range-restricted type, the new restriction MUST be equal or more 6055 limiting, that is raising the lower bounds, reducing the upper 6056 bounds, removing explicit values or ranges, or splitting ranges into 6057 multiple ranges with intermediate gaps. Each explicit value and 6058 range boundary value given in the range expression MUST match the 6059 type being restricted, or be one of the special values "min" or 6060 "max". "min" and "max" mean the minimum and maximum value accepted 6061 for the type being restricted, respectively. 6063 The range expression syntax is formally defined by the rule 6064 "range-arg" in Section 14. 6066 9.2.4.1. The range's Substatements 6068 +---------------+---------+-------------+ 6069 | substatement | section | cardinality | 6070 +---------------+---------+-------------+ 6071 | description | 7.21.3 | 0..1 | 6072 | error-app-tag | 7.5.4.2 | 0..1 | 6073 | error-message | 7.5.4.1 | 0..1 | 6074 | reference | 7.21.4 | 0..1 | 6075 +---------------+---------+-------------+ 6077 9.2.5. Usage Example 6079 typedef my-base-int32-type { 6080 type int32 { 6081 range "1..4 | 10..20"; 6082 } 6083 } 6085 typedef my-type1 { 6086 type my-base-int32-type { 6087 // legal range restriction 6088 range "11..max"; // 11..20 6089 } 6090 } 6092 typedef my-type2 { 6093 type my-base-int32-type { 6094 // illegal range restriction 6095 range "11..100"; 6096 } 6097 } 6099 9.3. The decimal64 Built-In Type 6101 The decimal64 type represents a subset of the real numbers, which can 6102 be represented by decimal numerals. The value space of decimal64 is 6103 the set of numbers that can be obtained by multiplying a 64-bit 6104 signed integer by a negative power of ten, i.e., expressible as "i x 6105 10^-n" where i is an integer64 and n is an integer between 1 and 18, 6106 inclusively. 6108 9.3.1. Lexical Representation 6110 A decimal64 value is lexically represented as an optional sign ("+" 6111 or "-"), followed by a sequence of decimal digits, optionally 6112 followed by a period ('.') as a decimal indicator and a sequence of 6113 decimal digits. If no sign is specified, "+" is assumed. 6115 9.3.2. Canonical Form 6117 The canonical form of a positive decimal64 does not include the sign 6118 "+". The decimal point is required. Leading and trailing zeros are 6119 prohibited, subject to the rule that there MUST be at least one digit 6120 before and after the decimal point. The value zero is represented as 6121 "0.0". 6123 9.3.3. Restrictions 6125 A decimal64 type can be restricted with the "range" statement 6126 (Section 9.2.4). 6128 9.3.4. The fraction-digits Statement 6130 The "fraction-digits" statement, which is a substatement to the 6131 "type" statement, MUST be present if the type is "decimal64". It 6132 takes as an argument an integer between 1 and 18, inclusively. It 6133 controls the size of the minimum difference between values of a 6134 decimal64 type, by restricting the value space to numbers that are 6135 expressible as "i x 10^-n" where n is the fraction-digits argument. 6137 The following table lists the minimum and maximum value for each 6138 fraction-digit value: 6140 +----------------+-----------------------+----------------------+ 6141 | fraction-digit | min | max | 6142 +----------------+-----------------------+----------------------+ 6143 | 1 | -922337203685477580.8 | 922337203685477580.7 | 6144 | 2 | -92233720368547758.08 | 92233720368547758.07 | 6145 | 3 | -9223372036854775.808 | 9223372036854775.807 | 6146 | 4 | -922337203685477.5808 | 922337203685477.5807 | 6147 | 5 | -92233720368547.75808 | 92233720368547.75807 | 6148 | 6 | -9223372036854.775808 | 9223372036854.775807 | 6149 | 7 | -922337203685.4775808 | 922337203685.4775807 | 6150 | 8 | -92233720368.54775808 | 92233720368.54775807 | 6151 | 9 | -9223372036.854775808 | 9223372036.854775807 | 6152 | 10 | -922337203.6854775808 | 922337203.6854775807 | 6153 | 11 | -92233720.36854775808 | 92233720.36854775807 | 6154 | 12 | -9223372.036854775808 | 9223372.036854775807 | 6155 | 13 | -922337.2036854775808 | 922337.2036854775807 | 6156 | 14 | -92233.72036854775808 | 92233.72036854775807 | 6157 | 15 | -9223.372036854775808 | 9223.372036854775807 | 6158 | 16 | -922.3372036854775808 | 922.3372036854775807 | 6159 | 17 | -92.23372036854775808 | 92.23372036854775807 | 6160 | 18 | -9.223372036854775808 | 9.223372036854775807 | 6161 +----------------+-----------------------+----------------------+ 6163 9.3.5. Usage Example 6165 typedef my-decimal { 6166 type decimal64 { 6167 fraction-digits 2; 6168 range "1 .. 3.14 | 10 | 20..max"; 6169 } 6170 } 6172 9.4. The string Built-In Type 6174 The string built-in type represents human-readable strings in YANG. 6175 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 6176 characters, including tab, carriage return, and line feed but 6177 excluding the other C0 control characters, the surrogate blocks, and 6178 the noncharacters. The string syntax is formally defined by the rule 6179 "yang-string" in Section 14. 6181 9.4.1. Lexical Representation 6183 A string value is lexically represented as character data in the XML 6184 encoding. 6186 9.4.2. Canonical Form 6188 The canonical form is the same as the lexical representation. No 6189 Unicode normalization is performed of string values. 6191 9.4.3. Restrictions 6193 A string can be restricted with the "length" (Section 9.4.4) and 6194 "pattern" (Section 9.4.5) statements. 6196 9.4.4. The length Statement 6198 The "length" statement, which is an optional substatement to the 6199 "type" statement, takes as an argument a length expression string. 6200 It is used to restrict the built-in types "string" and "binary" or 6201 types derived from them. 6203 A "length" statement restricts the number of Unicode characters in 6204 the string. 6206 A length range consists of an explicit value, or a lower bound, two 6207 consecutive dots "..", and an upper bound. Multiple values or ranges 6208 can be given, separated by "|". Length-restricting values MUST NOT 6209 be negative. If multiple values or ranges are given, they all MUST 6210 be disjoint and MUST be in ascending order. If a length restriction 6211 is applied to an already length-restricted type, the new restriction 6212 MUST be equal or more limiting, that is, raising the lower bounds, 6213 reducing the upper bounds, removing explicit length values or ranges, 6214 or splitting ranges into multiple ranges with intermediate gaps. A 6215 length value is a non-negative integer, or one of the special values 6216 "min" or "max". "min" and "max" mean the minimum and maximum length 6217 accepted for the type being restricted, respectively. An 6218 implementation is not required to support a length value larger than 6219 18446744073709551615. 6221 The length expression syntax is formally defined by the rule 6222 "length-arg" in Section 14. 6224 9.4.4.1. The length's Substatements 6226 +---------------+---------+-------------+ 6227 | substatement | section | cardinality | 6228 +---------------+---------+-------------+ 6229 | description | 7.21.3 | 0..1 | 6230 | error-app-tag | 7.5.4.2 | 0..1 | 6231 | error-message | 7.5.4.1 | 0..1 | 6232 | reference | 7.21.4 | 0..1 | 6233 +---------------+---------+-------------+ 6235 9.4.5. The pattern Statement 6237 The "pattern" statement, which is an optional substatement to the 6238 "type" statement, takes as an argument a regular expression string, 6239 as defined in [XSD-TYPES]. It is used to restrict the built-in type 6240 "string", or types derived from "string", to values that match the 6241 pattern. 6243 If the type has multiple "pattern" statements, the expressions are 6244 ANDed together, i.e., all such expressions have to match. 6246 If a pattern restriction is applied to an already pattern-restricted 6247 type, values must match all patterns in the base type, in addition to 6248 the new patterns. 6250 9.4.5.1. The pattern's Substatements 6252 +---------------+---------+-------------+ 6253 | substatement | section | cardinality | 6254 +---------------+---------+-------------+ 6255 | description | 7.21.3 | 0..1 | 6256 | error-app-tag | 7.5.4.2 | 0..1 | 6257 | error-message | 7.5.4.1 | 0..1 | 6258 | modifier | 9.4.6 | 0..1 | 6259 | reference | 7.21.4 | 0..1 | 6260 +---------------+---------+-------------+ 6262 9.4.6. The modifier Statement 6264 The "modifier" statement, which is an optional substatement to the 6265 "pattern" statement, takes as an argument the string "invert-match". 6267 If a pattern has the "invert-match" modifier present, the type is 6268 restricted to values that do not match the pattern. 6270 9.4.7. Usage Example 6272 With the following typedef: 6274 typedef my-base-str-type { 6275 type string { 6276 length "1..255"; 6277 } 6278 } 6280 the following refinement is legal: 6282 type my-base-str-type { 6283 // legal length refinement 6284 length "11 | 42..max"; // 11 | 42..255 6285 } 6287 and the following refinement is illegal: 6289 type my-base-str-type { 6290 // illegal length refinement 6291 length "1..999"; 6292 } 6294 With the following type: 6296 type string { 6297 length "0..4"; 6298 pattern "[0-9a-fA-F]*"; 6299 } 6301 the following strings match: 6303 AB // legal 6304 9A00 // legal 6306 and the following strings do not match: 6308 00ABAB // illegal, too long 6309 xx00 // illegal, bad characters 6311 With the following type: 6313 typedef yang-identifier { 6314 type string { 6315 length "1..max"; 6316 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 6317 pattern '[xX][mM][lL].*' { 6318 modifier invert-match; 6319 } 6320 } 6321 } 6323 the following string match: 6325 enabled // legal 6327 and the following strings do not match: 6329 10-mbit // illegal, starts with a number 6330 xml-element // illegal, starts with illegal sequence 6332 9.5. The boolean Built-In Type 6334 The boolean built-in type represents a boolean value. 6336 9.5.1. Lexical Representation 6338 The lexical representation of a boolean value is a string with a 6339 value of "true" or "false". These values MUST be in lowercase. 6341 9.5.2. Canonical Form 6343 The canonical form is the same as the lexical representation. 6345 9.5.3. Restrictions 6347 A boolean cannot be restricted. 6349 9.6. The enumeration Built-In Type 6351 The enumeration built-in type represents values from a set of 6352 assigned names. 6354 9.6.1. Lexical Representation 6356 The lexical representation of an enumeration value is the assigned 6357 name string. 6359 9.6.2. Canonical Form 6361 The canonical form is the assigned name string. 6363 9.6.3. Restrictions 6365 An enumeration can be restricted with the "enum" (Section 9.6.4) 6366 statement. 6368 9.6.4. The enum Statement 6370 The "enum" statement, which is a substatement to the "type" 6371 statement, MUST be present if the type is "enumeration". It is 6372 repeatedly used to specify each assigned name of an enumeration type. 6373 It takes as an argument a string which is the assigned name. The 6374 string MUST NOT be zero-length and MUST NOT have any leading or 6375 trailing whitespace characters (any Unicode character with the 6376 "White_Space" property). The use of Unicode control codes SHOULD be 6377 avoided. 6379 The statement is optionally followed by a block of substatements that 6380 holds detailed enum information. 6382 All assigned names in an enumeration MUST be unique. 6384 When an existing enumeration type is restricted, the set of assigned 6385 names in the new type MUST be a subset of the base type's set of 6386 assigned names. The value of such an assigned name MUST NOT be 6387 changed. 6389 9.6.4.1. The enum's Substatements 6391 +--------------+---------+-------------+ 6392 | substatement | section | cardinality | 6393 +--------------+---------+-------------+ 6394 | description | 7.21.3 | 0..1 | 6395 | if-feature | 7.20.2 | 0..n | 6396 | reference | 7.21.4 | 0..1 | 6397 | status | 7.21.2 | 0..1 | 6398 | value | 9.6.4.2 | 0..1 | 6399 +--------------+---------+-------------+ 6401 9.6.4.2. The value Statement 6403 The "value" statement, which is optional, is used to associate an 6404 integer value with the assigned name for the enum. This integer 6405 value MUST be in the range -2147483648 to 2147483647, and it MUST be 6406 unique within the enumeration type. 6408 If a value is not specified, then one will be automatically assigned. 6409 If the "enum" substatement is the first one defined, the assigned 6410 value is zero (0); otherwise, the assigned value is one greater than 6411 the current highest enum value (i.e., the highest enum value, 6412 implicit or explicit, prior to the current "enum" substatement in the 6413 parent "type" statement). 6415 Note that the the presence of an "if-feature" statement in an "enum" 6416 statement does not affect the automatically assigned value. 6418 If the current highest value is equal to 2147483647, then an enum 6419 value MUST be specified for "enum" substatements following the one 6420 with the current highest value. 6422 When an existing enumeration type is restricted, the "value" 6423 statement MUST either have the same value as in the base type or not 6424 be present, in which case the value is the same as in the base type. 6426 9.6.5. Usage Example 6428 leaf myenum { 6429 type enumeration { 6430 enum zero; 6431 enum one; 6432 enum seven { 6433 value 7; 6434 } 6435 } 6436 } 6438 The lexical representation of the leaf "myenum" with value "seven" 6439 is: 6441 seven 6443 With the following typedef: 6445 typedef my-base-enumeration-type { 6446 type enumeration { 6447 enum white { 6448 value 1; 6449 } 6450 enum yellow { 6451 value 2; 6452 } 6453 enum red { 6454 value 3; 6455 } 6456 } 6457 } 6459 the following refinement is legal: 6461 type my-base-enumeration-type { 6462 // legal enum refinement 6463 enum yellow; 6464 enum red { 6465 value 3; 6466 } 6467 } 6469 and the following refinement is illegal: 6471 type my-base-enumeration-type { 6472 // illegal enum refinement 6473 enum yellow { 6474 value 4; // illegal value change 6475 } 6476 enum black; // illegal addition of new name 6477 } 6479 The following example shows how an "enum" can be tagged with 6480 "if-feature", making the value legal only on servers that advertise 6481 the corresponding feature: 6483 type enumeration { 6484 enum tcp; 6485 enum ssh { 6486 if-feature ssh; 6487 } 6488 enum tls { 6489 if-feature tls; 6490 } 6491 } 6493 9.7. The bits Built-In Type 6495 The bits built-in type represents a bit set. That is, a bits value 6496 is a set of flags identified by small integer position numbers 6497 starting at 0. Each bit number has an assigned name. 6499 When an existing bits type is restricted, the set of assigned names 6500 in the new type MUST be a subset of the base type's set of assigned 6501 names. The bit position of such an assigned name MUST NOT be 6502 changed. 6504 9.7.1. Restrictions 6506 A bits type can be restricted with the "bit" (Section 9.7.4) 6507 statement. 6509 9.7.2. Lexical Representation 6511 The lexical representation of the bits type is a space-separated list 6512 of the individual bit values that are set. A zero-length string thus 6513 represents a value where no bits are set. 6515 9.7.3. Canonical Form 6517 In the canonical form, the bit values are separated by a single space 6518 character and they appear ordered by their position (see 6519 Section 9.7.4.2). 6521 9.7.4. The bit Statement 6523 The "bit" statement, which is a substatement to the "type" statement, 6524 MUST be present if the type is "bits". It is repeatedly used to 6525 specify each assigned named bit of a bits type. It takes as an 6526 argument a string that is the assigned name of the bit. It is 6527 followed by a block of substatements that holds detailed bit 6528 information. The assigned name follows the same syntax rules as an 6529 identifier (see Section 6.2). 6531 All assigned names in a bits type MUST be unique. 6533 9.7.4.1. The bit's Substatements 6535 +--------------+---------+-------------+ 6536 | substatement | section | cardinality | 6537 +--------------+---------+-------------+ 6538 | description | 7.21.3 | 0..1 | 6539 | if-feature | 7.20.2 | 0..n | 6540 | reference | 7.21.4 | 0..1 | 6541 | status | 7.21.2 | 0..1 | 6542 | position | 9.7.4.2 | 0..1 | 6543 +--------------+---------+-------------+ 6545 9.7.4.2. The position Statement 6547 The "position" statement, which is optional, takes as an argument a 6548 non-negative integer value that specifies the bit's position within a 6549 hypothetical bit field. The position value MUST be in the range 0 to 6550 4294967295, and it MUST be unique within the bits type. 6552 If a bit position is not specified, then one will be automatically 6553 assigned. If the "bit" substatement is the first one defined, the 6554 assigned value is zero (0); otherwise, the assigned value is one 6555 greater than the current highest bit position (i.e., the highest bit 6556 position, implicit or explicit, prior to the current "bit" 6557 substatement in the parent "type" statement). 6559 Note that the the presence of an "if-feature" statement in an "bit" 6560 statement does not affect the automatically assigned position. 6562 If the current highest bit position value is equal to 4294967295, 6563 then a position value MUST be specified for "bit" substatements 6564 following the one with the current highest position value. 6566 When an existing bits type is restricted, the "position" statement 6567 MUST either have the same value as in the base type or not be 6568 present, in which case the value is the same as in the base type. 6570 9.7.5. Usage Example 6572 Given the following typedef and leaf: 6574 typedef mybits-type { 6575 type bits { 6576 bit disable-nagle { 6577 position 0; 6578 } 6579 bit auto-sense-speed { 6580 position 1; 6581 } 6582 bit ten-mb-only { 6583 position 2; 6584 } 6585 } 6586 } 6588 leaf mybits { 6589 type mybits-type; 6590 default "auto-sense-speed"; 6591 } 6593 The lexical representation of this leaf with bit values disable-nagle 6594 and ten-mb-only set would be: 6596 disable-nagle ten-mb-only 6598 The following example shows a legal refinement of this type: 6600 type mybits-type { 6601 // legal bit refinement 6602 bit disable-nagle { 6603 position 0; 6604 } 6605 bit auto-sense-speed { 6606 position 1; 6607 } 6608 } 6610 and the following refinement is illegal: 6612 type mybits-type { 6613 // illegal bit refinement 6614 bit disable-nagle { 6615 position 2; // illegal position change 6616 } 6617 bit hundred-mb-only; // illegal addition of new name 6618 } 6620 9.8. The binary Built-In Type 6622 The binary built-in type represents any binary data, i.e., a sequence 6623 of octets. 6625 9.8.1. Restrictions 6627 A binary type can be restricted with the "length" (Section 9.4.4) 6628 statement. The length of a binary value is the number of octets it 6629 contains. 6631 9.8.2. Lexical Representation 6633 Binary values are encoded with the base64 encoding scheme (see 6634 [RFC4648], Section 4). 6636 9.8.3. Canonical Form 6638 The canonical form of a binary value follows the rules in [RFC4648]. 6640 9.9. The leafref Built-In Type 6642 The leafref type is used to declare a constraint on the value space 6643 of a leaf, based on a reference to a set of leaf instances in the 6644 data tree. The "path" substatement (Section 9.9.2) selects a set of 6645 leaf instances, and the leafref value space is the set of values of 6646 these leaf instances. 6648 If the leaf with the leafref type represents configuration data, and 6649 the "require-instance" property (Section 9.9.3) is "true", the leaf 6650 it refers to MUST also represent configuration. Such a leaf puts a 6651 constraint on valid data. All such nodes MUST reference existing 6652 leaf instances or leafs with default values in use (see Section 7.6.1 6653 and Section 7.7.2) for the data to be valid. This constraint is 6654 enforced according to the rules in Section 8. 6656 There MUST NOT be any circular chains of leafrefs. 6658 If the leaf that the leafref refers to is conditional based on one or 6659 more features (see Section 7.20.2), then the leaf with the leafref 6660 type MUST also be conditional based on at least the same set of 6661 features. 6663 9.9.1. Restrictions 6665 A leafref can be restricted with the "require-instance" statement 6666 (Section 9.9.3). 6668 9.9.2. The path Statement 6670 The "path" statement, which is a substatement to the "type" 6671 statement, MUST be present if the type is "leafref". It takes as an 6672 argument a string that MUST refer to a leaf or leaf-list node. 6674 The syntax for a path argument is a subset of the XPath abbreviated 6675 syntax. Predicates are used only for constraining the values for the 6676 key nodes for list entries. Each predicate consists of exactly one 6677 equality test per key, and multiple adjacent predicates MAY be 6678 present if a list has multiple keys. The syntax is formally defined 6679 by the rule "path-arg" in Section 14. 6681 The predicates are only used when more than one key reference is 6682 needed to uniquely identify a leaf instance. This occurs if a list 6683 has multiple keys, or a reference to a leaf other than the key in a 6684 list is needed. In these cases, multiple leafrefs are typically 6685 specified, and predicates are used to tie them together. 6687 The "path" expression evaluates to a node set consisting of zero, 6688 one, or more nodes. If the leaf with the leafref type represents 6689 configuration data, this node set MUST be non-empty. 6691 The "path" XPath expression is conceptually evaluated in the 6692 following context, in addition to the definition in Section 6.4.1: 6694 o If the "path" statement is defined within a typedef, the context 6695 node is the leaf or leaf-list node in the data tree that 6696 references the typedef. 6698 o Otherwise, the context node is the node in the data tree for which 6699 the "path" statement is defined. 6701 9.9.3. The require-instance Statement 6703 The "require-instance" statement, which is a substatement to the 6704 "type" statement, MAY be present if the type is "instance-identifier" 6705 or "leafref". It takes as an argument the string "true" or "false". 6706 If this statement is not present, it defaults to "true". 6708 If "require-instance" is "true", it means that the instance being 6709 referred MUST exist for the data to be valid. This constraint is 6710 enforced according to the rules in Section 8. 6712 If "require-instance" is "false", it means that the instance being 6713 referred MAY exist in valid data. 6715 9.9.4. Lexical Representation 6717 A leafref value is lexically represented the same way as the leaf it 6718 references. 6720 9.9.5. Canonical Form 6722 The canonical form of a leafref is the same as the canonical form of 6723 the leaf it references. 6725 9.9.6. Usage Example 6727 With the following list: 6729 list interface { 6730 key "name"; 6731 leaf name { 6732 type string; 6733 } 6734 leaf admin-status { 6735 type admin-status; 6736 } 6737 list address { 6738 key "ip"; 6739 leaf ip { 6740 type yang:ip-address; 6741 } 6742 } 6743 } 6745 The following leafref refers to an existing interface: 6747 leaf mgmt-interface { 6748 type leafref { 6749 path "../interface/name"; 6750 } 6751 } 6753 An example of a corresponding XML snippet: 6755 6756 eth0 6757 6758 6759 lo 6760 6762 eth0 6764 The following leafrefs refer to an existing address of an interface: 6766 container default-address { 6767 leaf ifname { 6768 type leafref { 6769 path "../../interface/name"; 6770 } 6771 } 6772 leaf address { 6773 type leafref { 6774 path "../../interface[name = current()/../ifname]" 6775 + "/address/ip"; 6776 } 6777 } 6778 } 6780 An example of a corresponding XML snippet: 6782 6783 eth0 6784 up 6785
6786 192.0.2.1 6787
6788
6789 192.0.2.2 6790
6791 6792 6793 lo 6794 up 6795
6796 127.0.0.1 6797
6798 6800 6801 eth0 6802
192.0.2.2
6803 6805 The following list uses a leafref for one of its keys. This is 6806 similar to a foreign key in a relational database. 6808 list packet-filter { 6809 key "if-name filter-id"; 6810 leaf if-name { 6811 type leafref { 6812 path "/interface/name"; 6813 } 6814 } 6815 leaf filter-id { 6816 type uint32; 6817 } 6818 ... 6819 } 6821 An example of a corresponding XML snippet: 6823 6824 eth0 6825 up 6826
6827 192.0.2.1 6828
6829
6830 192.0.2.2 6831
6832 6834 6835 eth0 6836 1 6837 ... 6838 6839 6840 eth0 6841 2 6842 ... 6843 6845 The following notification defines two leafrefs to refer to an 6846 existing admin-status: 6848 notification link-failure { 6849 leaf if-name { 6850 type leafref { 6851 path "/interface/name"; 6852 } 6853 } 6854 leaf admin-status { 6855 type leafref { 6856 path "/interface[name = current()/../if-name]" 6857 + "/admin-status"; 6858 } 6859 } 6860 } 6862 An example of a corresponding XML notification: 6864 6866 2008-04-01T00:01:00Z 6867 6868 eth0 6869 up 6870 6871 6873 9.10. The identityref Built-In Type 6875 The identityref type is used to reference an existing identity (see 6876 Section 7.18). 6878 9.10.1. Restrictions 6880 An identityref cannot be restricted. 6882 9.10.2. The identityref's base Statement 6884 The "base" statement, which is a substatement to the "type" 6885 statement, MUST be present at least once if the type is 6886 "identityref". The argument is the name of an identity, as defined 6887 by an "identity" statement. If a prefix is present on the identity 6888 name, it refers to an identity defined in the module that was 6889 imported with that prefix. Otherwise, an identity with the matching 6890 name MUST be defined in the current module or an included submodule. 6892 Valid values for an identityref are any identities derived from all 6893 the identityref's base identities. On a particular server, the valid 6894 values are further restricted to the set of identities defined in the 6895 modules implemented by the server. 6897 9.10.3. Lexical Representation 6899 An identityref is lexically represented as the referred identity's 6900 qualified name as defined in [XML-NAMES]. If the prefix is not 6901 present, the namespace of the identityref is the default namespace in 6902 effect on the element that contains the identityref value. 6904 When an identityref is given a default value using the "default" 6905 statement, the identity name in the default value MAY have a prefix. 6906 If a prefix is present on the identity name, it refers to an identity 6907 defined in the module that was imported with that prefix, or the 6908 prefix for the current module if the identity is defined in the 6909 current module or one of its submodules. Otherwise, an identity with 6910 the matching name MUST be defined in the current module or one of its 6911 submodules. 6913 The string value of a node of type identityref in a "must" or "when" 6914 XPath expression is the referred identity's qualified name with the 6915 prefix present. If the referred identity is defined in an imported 6916 module, the prefix in the string value is the prefix defined in the 6917 corresponding "import" statement. Otherwise, the prefix in the 6918 string value is the prefix for the current module. 6920 9.10.4. Canonical Form 6922 Since the lexical form depends on the XML context in which the value 6923 occurs, this type does not have a canonical form. 6925 9.10.5. Usage Example 6927 With the identity definitions in Section 7.18.3 and the following 6928 module: 6930 module example-my-crypto { 6931 yang-version 1.1; 6932 namespace "urn:example:my-crypto"; 6933 prefix mc; 6935 import "example-crypto-base" { 6936 prefix "crypto"; 6937 } 6939 identity aes { 6940 base "crypto:crypto-alg"; 6941 } 6943 leaf crypto { 6944 type identityref { 6945 base "crypto:crypto-alg"; 6946 } 6947 } 6949 container aes-parameters { 6950 when "../crypto = 'mc:aes'"; 6951 ... 6952 } 6953 } 6955 the following is an example how the leaf "crypto" can be encoded, if 6956 the value is the "des3" identity defined in the "des" module: 6958 des:des3 6960 Any prefixes used in the encoding are local to each instance 6961 encoding. This means that the same identityref may be encoded 6962 differently by different implementations. For example, the following 6963 example encodes the same leaf as above: 6965 x:des3 6967 If the "crypto" leaf's value instead is "aes" defined in the 6968 "example-my-crypto" module, it can be encoded as: 6970 mc:aes 6972 or, using the default namespace: 6974 aes 6976 9.11. The empty Built-In Type 6978 The empty built-in type represents a leaf that does not have any 6979 value, it conveys information by its presence or absence. 6981 An empty type cannot have a default value. 6983 9.11.1. Restrictions 6985 An empty type cannot be restricted. 6987 9.11.2. Lexical Representation 6989 Not applicable. 6991 9.11.3. Canonical Form 6993 Not applicable. 6995 9.11.4. Usage Example 6997 With the following leaf 6999 leaf enable-qos { 7000 type empty; 7001 } 7003 the following is an example of a valid encoding 7005 7007 if the leaf exists. 7009 9.12. The union Built-In Type 7011 The union built-in type represents a value that corresponds to one of 7012 its member types. 7014 When the type is "union", the "type" statement (Section 7.4) MUST be 7015 present. It is used to repeatedly specify each member type of the 7016 union. It takes as an argument a string that is the name of a member 7017 type. 7019 A member type can be of any built-in or derived type. 7021 In the XML encoding, a value representing a union data type is 7022 validated consecutively against each member type, in the order they 7023 are specified in the "type" statement, until a match is found. The 7024 type that matched will be the type of the value for the node that was 7025 validated. 7027 Any default value or "units" property defined in the member types is 7028 not inherited by the union type. 7030 9.12.1. Restrictions 7032 A union cannot be restricted. However, each member type can be 7033 restricted, based on the rules defined in Section 9. 7035 9.12.2. Lexical Representation 7037 The lexical representation of a union is a value that corresponds to 7038 the representation of any one of the member types. 7040 9.12.3. Canonical Form 7042 The canonical form of a union value is the same as the canonical form 7043 of the member type of the value. 7045 9.12.4. Usage Example 7047 The following is a union of an int32 an enumeration: 7049 type union { 7050 type int32; 7051 type enumeration { 7052 enum "unbounded"; 7053 } 7054 } 7056 Care must be taken when a member type is a leafref where the 7057 "require-instance" property (Section 9.9.3) is "true". If a leaf of 7058 such a type refers to an existing instance, the leaf's value must be 7059 re-validated if the target instance is deleted. For example, with 7060 the following definitions: 7062 list filter { 7063 key name; 7064 leaf name { 7065 type string; 7066 } 7067 ... 7068 } 7070 leaf outbound-filter { 7071 type union { 7072 type leafref { 7073 path "/filter/name"; 7074 } 7075 type enumeration { 7076 enum default-filter; 7077 } 7078 } 7079 } 7081 assume that there exists an entry in the filter list with the name 7082 "http", and that the outbound-filter leaf has this value: 7084 7085 http 7086 7087 http 7089 If the filter entry "http" is removed, the outbound-filter leaf's 7090 value doesn't match the leafref, and the next member type is checked. 7091 The current value ("http") doesn't match the enumeration, so the 7092 resulting configuration is invalid. 7094 If the second member type in the union had been of type "string" 7095 instead of an enumeration, the current value would have matched, and 7096 the resulting configuration would have been valid. 7098 9.13. The instance-identifier Built-In Type 7100 The instance-identifier built-in type is used to uniquely identify a 7101 particular instance node in the data tree. 7103 The syntax for an instance-identifier is a subset of the XPath 7104 abbreviated syntax, formally defined by the rule 7105 "instance-identifier" in Section 14. It is used to uniquely identify 7106 a node in the data tree. Predicates are used only for specifying the 7107 values for the key nodes for list entries, a value of a leaf-list 7108 entry, or a positional index for a list without keys. For 7109 identifying list entries with keys, each predicate consists of one 7110 equality test per key, and each key MUST have a corresponding 7111 predicate. If a key is of type "empty", it is represented as a zero- 7112 length string (""). 7114 If the leaf with the instance-identifier type represents 7115 configuration data, and the "require-instance" property 7116 (Section 9.9.3) is "true", the node it refers to MUST also represent 7117 configuration. Such a leaf puts a constraint on valid data. All 7118 such leaf nodes MUST reference existing nodes or leaf or leaf-list 7119 nodes with their default value in use (see Section 7.6.1 and 7120 Section 7.7.2) for the data to be valid. This constraint is enforced 7121 according to the rules in Section 8. 7123 The "instance-identifier" XPath expression is conceptually evaluated 7124 in the following context, in addition to the definition in 7125 Section 6.4.1: 7127 o The context node is the root node in the accessible tree. 7129 9.13.1. Restrictions 7131 An instance-identifier can be restricted with the "require-instance" 7132 statement (Section 9.9.3). 7134 9.13.2. Lexical Representation 7136 An instance-identifier value is lexically represented as a string. 7137 All node names in an instance-identifier value MUST be qualified with 7138 explicit namespace prefixes, and these prefixes MUST be declared in 7139 the XML namespace scope in the instance-identifier's XML element. 7141 Any prefixes used in the encoding are local to each instance 7142 encoding. This means that the same instance-identifier may be 7143 encoded differently by different implementations. 7145 9.13.3. Canonical Form 7147 Since the lexical form depends on the XML context in which the value 7148 occurs, this type does not have a canonical form. 7150 9.13.4. Usage Example 7152 The following are examples of instance identifiers: 7154 /* instance-identifier for a container */ 7155 /ex:system/ex:services/ex:ssh 7157 /* instance-identifier for a leaf */ 7158 /ex:system/ex:services/ex:ssh/ex:port 7160 /* instance-identifier for a list entry */ 7161 /ex:system/ex:user[ex:name='fred'] 7163 /* instance-identifier for a leaf in a list entry */ 7164 /ex:system/ex:user[ex:name='fred']/ex:type 7166 /* instance-identifier for a list entry with two keys */ 7167 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 7169 /* instance-identifier for a list entry where the second 7170 key ("enabled") is of type empty */ 7171 /ex:system/ex:service[ex:name='foo'][ex:enabled=''] 7173 /* instance-identifier for a leaf-list entry */ 7174 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 7176 /* instance-identifier for a list entry without keys */ 7177 /ex:stats/ex:port[3] 7179 10. XPath Functions 7181 This document defines two generic XPath functions and five YANG type- 7182 specific XPath functions. The function signatures are specified with 7183 the syntax used in [XPATH]. 7185 10.1. Functions for Node Sets 7187 10.1.1. current() 7189 node-set current() 7191 The function current() takes no input parameters, and returns a node 7192 set with the initial context node as its only member. 7194 10.1.1.1. Usage Example 7196 With this list: 7198 list interface { 7199 key "name"; 7200 ... 7201 leaf enabled { 7202 type boolean; 7203 } 7204 ... 7205 } 7207 the following leaf defines a must expression that ensures that the 7208 referred interface is enabled: 7210 leaf outgoing-interface { 7211 type leafref { 7212 path "/interface/name"; 7213 } 7214 must '/interface[name=current()]/enabled = "true"'; 7215 } 7217 10.2. Functions for Strings 7219 10.2.1. re-match() 7221 boolean re-match(string subject, string pattern) 7223 The re-match() function returns true if the "subject" string matches 7224 the regular expression "pattern"; otherwise it returns false. 7226 The function "re-match" checks if a string matches a given regular 7227 expression. The regular expressions used are the XML Schema regular 7228 expressions [XSD-TYPES]. Note that this includes implicit anchoring 7229 of the regular expression at the head and tail. 7231 10.2.1.1. Usage Example 7233 The expression: 7235 re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}") 7237 returns true. 7239 To count all logical interfaces called eth0., do: 7241 count(/interface[re-match(name, "eth0\.\d+")]) 7243 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 7245 10.3.1. deref() 7247 node-set deref(node-set nodes) 7249 The deref() function follows the reference defined by the first node 7250 in document order in the argument "nodes", and returns the nodes it 7251 refers to. 7253 If the first argument node is of type instance-identifier, the 7254 function returns a node set that contains the single node that the 7255 instance identifier refers to, if it exists. If no such node exists, 7256 an empty node-set is returned. 7258 If the first argument node is of type leafref, the function returns a 7259 node set that contains the nodes that the leafref refers to. 7261 If the first argument node is of any other type, an empty node set is 7262 returned. 7264 10.3.1.1. Usage Example 7265 list interface { 7266 key "name type"; 7267 leaf name { ... } 7268 leaf type { ... } 7269 leaf enabled { 7270 type boolean; 7271 } 7272 ... 7273 } 7275 container mgmt-interface { 7276 leaf name { 7277 type leafref { 7278 path "/interface/name"; 7279 } 7280 } 7281 leaf type { 7282 type leafref { 7283 path "/interface[name=current()/../name]/type"; 7284 } 7285 must 'deref(.)/../enabled = "true"' { 7286 error-message 7287 "The management interface cannot be disabled."; 7288 } 7289 } 7290 } 7292 10.4. Functions for the YANG Type "identityref" 7294 10.4.1. derived-from() 7296 boolean derived-from(node-set nodes, string identity) 7298 The derived-from() function returns true if any node in the argument 7299 "nodes" is a node of type identityref, and its value is an identity 7300 that is derived from (see Section 7.18.2) the identity "identity"; 7301 otherwise it returns false. 7303 The parameter "identity" is a string matching the rule 7304 "identifier-ref" in Section 14. If a prefix is present on the 7305 identity, it refers to an identity defined in the module that was 7306 imported with that prefix, or the local module if the prefix matches 7307 the local module's prefix. If no prefix is present, the identity 7308 refers to an identity defined in the current module or an included 7309 submodule. 7311 10.4.1.1. Usage Example 7313 module example-interface { 7314 yang-version 1.1; 7316 ... 7317 identity interface-type; 7319 identity ethernet { 7320 base interface-type; 7321 } 7323 identity fast-ethernet { 7324 base ethernet; 7325 } 7327 identity gigabit-ethernet { 7328 base ethernet; 7329 } 7331 list interface { 7332 key name; 7333 ... 7334 leaf type { 7335 type identityref { 7336 base interface-type; 7337 } 7338 } 7339 ... 7340 } 7342 augment "/interface" { 7343 when 'derived-from(type, "exif:ethernet")'; 7344 // generic ethernet definitions here 7345 } 7346 ... 7347 } 7349 10.4.2. derived-from-or-self() 7351 boolean derived-from-or-self(node-set nodes, string identity) 7353 The derived-from-or-self() function returns true if any node in the 7354 argument "nodes" is a node of type identityref, and its value is an 7355 identity that is equal to or derived from (see Section 7.18.2) the 7356 identity "identity"; otherwise it returns false. 7358 The parameter "identity" is a string matching the rule 7359 "identifier-ref" in Section 14. If a prefix is present on the 7360 identity, it refers to an identity defined in the module that was 7361 imported with that prefix, or the local module if the prefix matches 7362 the local module's prefix. If no prefix is present, the identity 7363 refers to an identity defined in the current module or an included 7364 submodule. 7366 10.4.2.1. Usage Example 7368 The module defined in Section 10.4.1.1 might also have: 7370 augment "/interface" { 7371 when 'derived-from-or-self(type, "exif:fast-ethernet"); 7372 // fast-ethernet-specific definitions here 7373 } 7375 10.5. Functions for the YANG Type "enumeration" 7377 10.5.1. enum-value() 7379 number enum-value(node-set nodes) 7381 The enum-value() function checks if the first node in document order 7382 in the argument "nodes" is a node of type enumeration, and returns 7383 the enum's integer value. If the "nodes" node set is empty, or if 7384 the first node in "nodes" is not of type enumeration, it returns NaN. 7386 10.5.1.1. Usage Example 7388 With this data model: 7390 list alarm { 7391 ... 7392 leaf severity { 7393 type enumeration { 7394 enum cleared { 7395 value 1; 7396 } 7397 enum indeterminate { 7398 value 2; 7399 } 7400 enum minor { 7401 value 3; 7402 } 7403 enum warning { 7404 value 4; 7405 } 7406 enum major { 7407 value 5; 7408 } 7409 enum critical { 7410 value 6; 7411 } 7412 } 7413 } 7414 } 7416 the following XPath expression selects only alarms that are of 7417 severity "major" or higher: 7419 /alarm[enum-value(severity) >= 5] 7421 10.6. Functions for the YANG Type "bits" 7423 10.6.1. bit-is-set() 7425 boolean bit-is-set(node-set nodes, string bit-name) 7427 The bit-is-set() function returns true if the first node in document 7428 order in the argument "nodes" is a node of type bits, and its value 7429 has the bit "'bit-name" set; otherwise it returns false. 7431 10.6.1.1. Usage Example 7433 If an interface has this leaf: 7435 leaf flags { 7436 type bits { 7437 bit UP; 7438 bit PROMISCUOUS 7439 bit DISABLED; 7440 } 7441 } 7443 the following XPath expression can be used to select all interfaces 7444 with the UP flag set: 7446 /interface[bit-is-set(flags, "UP")] 7448 11. Updating a Module 7450 As experience is gained with a module, it may be desirable to revise 7451 that module. However, changes to published modules are not allowed 7452 if they have any potential to cause interoperability problems between 7453 a client using an original specification and a server using an 7454 updated specification. 7456 For any published change, a new "revision" statement (Section 7.1.9) 7457 MUST be included in front of the existing "revision" statements. If 7458 there are no existing "revision" statements, then one MUST be added 7459 to identify the new revision. Furthermore, any necessary changes 7460 MUST be applied to any meta-data statements, including the 7461 "organization" and "contact" statements (Section 7.1.7, 7462 Section 7.1.8). 7464 Note that definitions contained in a module are available to be 7465 imported by any other module, and are referenced in "import" 7466 statements via the module name. Thus, a module name MUST NOT be 7467 changed. Furthermore, the "namespace" statement MUST NOT be changed, 7468 since all XML elements are qualified by the namespace. 7470 Obsolete definitions MUST NOT be removed from published modules since 7471 their identifiers may still be referenced by other modules. 7473 A definition in a published module may be revised in any of the 7474 following ways: 7476 o An "enumeration" type may have new enums added, provided the old 7477 enums's values do not change. Note that inserting a new enum 7478 before an existing enum or reordering existing enums will result 7479 in new values for the existing enums, unless they have explicit 7480 values assigned to them. 7482 o A "bits" type may have new bits added, provided the old bit 7483 positions do not change. Note that inserting a new bit before an 7484 existing bit or reordering existing bit will result in new 7485 positions for the existing bits, unless they have explicit 7486 positions assigned to them. 7488 o A "range", "length", or "pattern" statement may expand the allowed 7489 value space. 7491 o A "default" statement may be added to a leaf that does not have a 7492 default value (either directly or indirectly through its type). 7494 o A "units" statement may be added. 7496 o A "reference" statement may be added or updated. 7498 o A "must" statement may be removed or its constraint relaxed. 7500 o A "when" statement may be removed or its constraint relaxed. 7502 o A "mandatory" statement may be removed or changed from "true" to 7503 "false". 7505 o A "min-elements" statement may be removed, or changed to require 7506 fewer elements. 7508 o A "max-elements" statement may be removed, or changed to allow 7509 more elements. 7511 o A "description" statement may be added or clarified without 7512 changing the semantics of the definition. 7514 o A "base" statement may be added to an "identity" statement. 7516 o A "base" statement may be removed from an "identityref" type, 7517 provided there is at least one "base" statement left. 7519 o New typedefs, groupings, rpcs, notifications, extensions, 7520 features, and identities may be added. 7522 o New data definition statements may be added if they do not add 7523 mandatory nodes (Section 3) to existing nodes or at the top level 7524 in a module or submodule, or if they are conditionally dependent 7525 on a new feature (i.e., have an "if-feature" statement that refers 7526 to a new feature). 7528 o A new "case" statement may be added. 7530 o A node that represented state data may be changed to represent 7531 configuration, provided it is not mandatory (Section 3). 7533 o An "if-feature" statement may be removed, provided its node is not 7534 mandatory (Section 3). 7536 o A "status" statement may be added, or changed from "current" to 7537 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 7539 o A "type" statement may be replaced with another "type" statement 7540 that does not change the syntax or semantics of the type. For 7541 example, an inline type definition may be replaced with a typedef, 7542 but an int8 type cannot be replaced by an int16, since the syntax 7543 would change. 7545 o Any set of data definition nodes may be replaced with another set 7546 of syntactically and semantically equivalent nodes. For example, 7547 a set of leafs may be replaced by a uses of a grouping with the 7548 same leafs. 7550 o A module may be split into a set of submodules, or a submodule may 7551 be removed, provided the definitions in the module do not change 7552 in any other way than allowed here. 7554 o The "prefix" statement may be changed, provided all local uses of 7555 the prefix also are changed. 7557 Otherwise, if the semantics of any previous definition are changed 7558 (i.e., if a non-editorial change is made to any definition other than 7559 those specifically allowed above), then this MUST be achieved by a 7560 new definition with a new identifier. 7562 In statements that have any data definition statements as 7563 substatements, those data definition substatements MUST NOT be 7564 reordered. If new data definition statements are added, they can be 7565 added anywhere in the sequence of existing substatement. 7567 12. Coexistence with YANG version 1 7569 A YANG version 1.1 module MUST NOT include a YANG version 1 7570 submodule, and a YANG version 1 module MUST NOT include a YANG 7571 version 1.1 submodule. 7573 A YANG version 1 module or submodule MUST NOT import a YANG version 7574 1.1 module by revision. 7576 A YANG version 1.1 module or submodule MAY import a YANG version 1 7577 module by revision. 7579 If a YANG version 1 module A imports module B without revision, and 7580 module B is updated to YANG version 1.1, a server MAY implement both 7581 these modules (A and B) at the same time. In such cases, a NETCONF 7582 server MUST advertise both modules using the rules defined in 7583 Section 5.6.4, and SHOULD advertise module A and the latest revision 7584 of module B that is specified with YANG version 1 according to the 7585 rules defined in [RFC6020]. 7587 This rule exists in order to allow implementations of existing YANG 7588 version 1 modules together with YANG version 1.1 modules. Without 7589 this rule, updating a single module to YANG version 1.1 would have a 7590 cascading effect on modules that import it, requiring all of them to 7591 also be updated to YANG version 1.1, and so on. 7593 13. YIN 7595 A YANG module can be translated into an alternative XML-based syntax 7596 called YIN. The translated module is called a YIN module. This 7597 section describes symmetric mapping rules between the two formats. 7599 The YANG and YIN formats contain equivalent information using 7600 different notations. The YIN notation enables developers to 7601 represent YANG data models in XML and therefore use the rich set of 7602 XML-based tools for data filtering and validation, automated 7603 generation of code and documentation, and other tasks. Tools like 7604 XSLT or XML validators can be utilized. 7606 The mapping between YANG and YIN does not modify the information 7607 content of the model. Comments and whitespace are not preserved. 7609 13.1. Formal YIN Definition 7611 There is a one-to-one correspondence between YANG keywords and YIN 7612 elements. The local name of a YIN element is identical to the 7613 corresponding YANG keyword. This means, in particular, that the 7614 document element (root) of a YIN document is always or 7615 . 7617 YIN elements corresponding to the YANG keywords belong to the 7618 namespace whose associated URI is 7619 "urn:ietf:params:xml:ns:yang:yin:1". 7621 YIN elements corresponding to extension keywords belong to the 7622 namespace of the YANG module where the extension keyword is declared 7623 via the "extension" statement. 7625 The names of all YIN elements MUST be properly qualified with their 7626 namespaces specified above using the standard mechanisms of 7627 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 7629 The argument of a YANG statement is represented in YIN either as an 7630 XML attribute or a subelement of the keyword element. Table 1 7631 defines the mapping for the set of YANG keywords. For extensions, 7632 the argument mapping is specified within the "extension" statement 7633 (see Section 7.19). The following rules hold for arguments: 7635 o If the argument is represented as an attribute, this attribute has 7636 no namespace. 7638 o If the argument is represented as an element, it is qualified by 7639 the same namespace as its parent keyword element. 7641 o If the argument is represented as an element, it MUST be the first 7642 child of the keyword element. 7644 Substatements of a YANG statement are represented as (additional) 7645 children of the keyword element and their relative order MUST be the 7646 same as the order of substatements in YANG. 7648 Comments in YANG MAY be mapped to XML comments. 7650 +------------------+---------------+-------------+ 7651 | keyword | argument name | yin-element | 7652 +------------------+---------------+-------------+ 7653 | action | name | false | 7654 | anydata | name | false | 7655 | anyxml | name | false | 7656 | argument | name | false | 7657 | augment | target-node | false | 7658 | base | name | false | 7659 | belongs-to | module | false | 7660 | bit | name | false | 7661 | case | name | false | 7662 | choice | name | false | 7663 | config | value | false | 7664 | contact | text | true | 7665 | container | name | false | 7666 | default | value | false | 7667 | description | text | true | 7668 | deviate | value | false | 7669 | deviation | target-node | false | 7670 | enum | name | false | 7671 | error-app-tag | value | false | 7672 | error-message | value | true | 7673 | extension | name | false | 7674 | feature | name | false | 7675 | fraction-digits | value | false | 7676 | grouping | name | false | 7677 | identity | name | false | 7678 | if-feature | name | false | 7679 | import | module | false | 7680 | include | module | false | 7681 | input | | n/a | 7682 | key | value | false | 7683 | leaf | name | false | 7684 | leaf-list | name | false | 7685 | length | value | false | 7686 | list | name | false | 7687 | mandatory | value | false | 7688 | max-elements | value | false | 7689 | min-elements | value | false | 7690 | modifier | value | false | 7691 | module | name | false | 7692 | must | condition | false | 7693 | namespace | uri | false | 7694 | notification | name | false | 7695 | ordered-by | value | false | 7696 | organization | text | true | 7697 | output | | n/a | 7698 | path | value | false | 7699 | pattern | value | false | 7700 | position | value | false | 7701 | prefix | value | false | 7702 | presence | value | false | 7703 | range | value | false | 7704 | reference | text | true | 7705 | refine | target-node | false | 7706 | require-instance | value | false | 7707 | revision | date | false | 7708 | revision-date | date | false | 7709 | rpc | name | false | 7710 | status | value | false | 7711 | submodule | name | false | 7712 | type | name | false | 7713 | typedef | name | false | 7714 | unique | tag | false | 7715 | units | name | false | 7716 | uses | name | false | 7717 | value | value | false | 7718 | when | condition | false | 7719 | yang-version | value | false | 7720 | yin-element | value | false | 7721 +------------------+---------------+-------------+ 7723 Table 1: Mapping of arguments of the YANG statements. 7725 13.1.1. Usage Example 7727 The following YANG module: 7729 module example-foo { 7730 yang-version 1.1; 7731 namespace "urn:example:foo"; 7732 prefix "foo"; 7734 import example-extensions { 7735 prefix "myext"; 7736 } 7738 list interface { 7739 key "name"; 7740 leaf name { 7741 type string; 7742 } 7744 leaf mtu { 7745 type uint32; 7746 description "The MTU of the interface."; 7747 myext:c-define "MY_MTU"; 7748 } 7749 } 7750 } 7752 where the extension "c-define" is defined in Section 7.19.3, is 7753 translated into the following YIN: 7755 7760 7761 7763 7764 7765 7767 7768 7769 7770 7771 7772 7773 7774 7775 The MTU of the interface. 7776 7777 7778 7779 7780 7782 14. YANG ABNF Grammar 7784 In YANG, almost all statements are unordered. The ABNF grammar 7785 [RFC5234] [RFC7405] defines the canonical order. To improve module 7786 readability, it is RECOMMENDED that clauses be entered in this order. 7788 Within the ABNF grammar, unordered statements are marked with 7789 comments. 7791 This grammar assumes that the scanner replaces YANG comments with a 7792 single space character. 7794 file "yang.abnf" 7796 module-stmt = optsep module-keyword sep identifier-arg-str 7797 optsep 7798 "{" stmtsep 7799 module-header-stmts 7800 linkage-stmts 7801 meta-stmts 7802 revision-stmts 7803 body-stmts 7804 "}" optsep 7806 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 7807 optsep 7808 "{" stmtsep 7809 submodule-header-stmts 7810 linkage-stmts 7811 meta-stmts 7812 revision-stmts 7813 body-stmts 7814 "}" optsep 7816 module-header-stmts = ;; these stmts can appear in any order 7817 yang-version-stmt 7818 namespace-stmt 7819 prefix-stmt 7821 submodule-header-stmts = 7822 ;; these stmts can appear in any order 7823 yang-version-stmt 7824 belongs-to-stmt 7826 meta-stmts = ;; these stmts can appear in any order 7827 [organization-stmt] 7828 [contact-stmt] 7829 [description-stmt] 7830 [reference-stmt] 7832 linkage-stmts = ;; these stmts can appear in any order 7833 *import-stmt 7834 *include-stmt 7836 revision-stmts = *revision-stmt 7838 body-stmts = *(extension-stmt / 7839 feature-stmt / 7840 identity-stmt / 7841 typedef-stmt / 7842 grouping-stmt / 7843 data-def-stmt / 7844 augment-stmt / 7845 rpc-stmt / 7846 notification-stmt / 7847 deviation-stmt) 7849 data-def-stmt = container-stmt / 7850 leaf-stmt / 7851 leaf-list-stmt / 7852 list-stmt / 7853 choice-stmt / 7854 anydata-stmt / 7855 anyxml-stmt / 7856 uses-stmt 7858 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 7859 stmtend 7861 yang-version-arg-str = < a string that matches the rule > 7862 < yang-version-arg > 7864 yang-version-arg = "1.1" 7866 import-stmt = import-keyword sep identifier-arg-str optsep 7867 "{" stmtsep 7868 ;; these stmts can appear in any order 7869 prefix-stmt 7870 [revision-date-stmt] 7871 [description-stmt] 7872 [reference-stmt] 7873 "}" stmtsep 7875 include-stmt = include-keyword sep identifier-arg-str optsep 7876 (";" / 7877 "{" stmtsep 7878 ;; these stmts can appear in any order 7879 [revision-date-stmt] 7880 [description-stmt] 7881 [reference-stmt] 7882 "}") stmtsep 7884 namespace-stmt = namespace-keyword sep uri-str stmtend 7886 uri-str = < a string that matches the rule > 7887 < URI in RFC 3986 > 7889 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 7891 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 7892 optsep 7893 "{" stmtsep 7894 prefix-stmt 7895 "}" stmtsep 7897 organization-stmt = organization-keyword sep string stmtend 7898 contact-stmt = contact-keyword sep string stmtend 7900 description-stmt = description-keyword sep string stmtend 7902 reference-stmt = reference-keyword sep string stmtend 7904 units-stmt = units-keyword sep string stmtend 7906 revision-stmt = revision-keyword sep revision-date optsep 7907 (";" / 7908 "{" stmtsep 7909 ;; these stmts can appear in any order 7910 [description-stmt] 7911 [reference-stmt] 7912 "}") stmtsep 7914 revision-date = date-arg-str 7916 revision-date-stmt = revision-date-keyword sep revision-date stmtend 7918 extension-stmt = extension-keyword sep identifier-arg-str optsep 7919 (";" / 7920 "{" stmtsep 7921 ;; these stmts can appear in any order 7922 [argument-stmt] 7923 [status-stmt] 7924 [description-stmt] 7925 [reference-stmt] 7926 "}") stmtsep 7928 argument-stmt = argument-keyword sep identifier-arg-str optsep 7929 (";" / 7930 "{" stmtsep 7931 [yin-element-stmt] 7932 "}") stmtsep 7934 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 7935 stmtend 7937 yin-element-arg-str = < a string that matches the rule > 7938 < yin-element-arg > 7940 yin-element-arg = true-keyword / false-keyword 7942 identity-stmt = identity-keyword sep identifier-arg-str optsep 7943 (";" / 7944 "{" stmtsep 7945 ;; these stmts can appear in any order 7946 *if-feature-stmt 7947 *base-stmt 7948 [status-stmt] 7949 [description-stmt] 7950 [reference-stmt] 7951 "}") stmtsep 7953 base-stmt = base-keyword sep identifier-ref-arg-str 7954 stmtend 7956 feature-stmt = feature-keyword sep identifier-arg-str optsep 7957 (";" / 7958 "{" stmtsep 7959 ;; these stmts can appear in any order 7960 *if-feature-stmt 7961 [status-stmt] 7962 [description-stmt] 7963 [reference-stmt] 7964 "}") stmtsep 7966 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 7967 stmtend 7969 if-feature-expr-str = < a string that matches the rule > 7970 < if-feature-expr > 7972 if-feature-expr = "(" if-feature-expr ")" / 7973 if-feature-expr sep boolean-operator sep 7974 if-feature-expr / 7975 not-keyword sep if-feature-expr / 7976 identifier-ref-arg 7978 boolean-operator = and-keyword / or-keyword 7980 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 7981 "{" stmtsep 7982 ;; these stmts can appear in any order 7983 type-stmt 7984 [units-stmt] 7985 [default-stmt] 7986 [status-stmt] 7987 [description-stmt] 7988 [reference-stmt] 7989 "}" stmtsep 7991 type-stmt = type-keyword sep identifier-ref-arg-str optsep 7992 (";" / 7993 "{" stmtsep 7995 [type-body-stmts] 7996 "}") stmtsep 7998 type-body-stmts = numerical-restrictions / 7999 decimal64-specification / 8000 string-restrictions / 8001 enum-specification / 8002 leafref-specification / 8003 identityref-specification / 8004 instance-identifier-specification / 8005 bits-specification / 8006 union-specification / 8007 binary-specification 8009 numerical-restrictions = range-stmt 8011 range-stmt = range-keyword sep range-arg-str optsep 8012 (";" / 8013 "{" stmtsep 8014 ;; these stmts can appear in any order 8015 [error-message-stmt] 8016 [error-app-tag-stmt] 8017 [description-stmt] 8018 [reference-stmt] 8019 "}") stmtsep 8021 decimal64-specification = ;; these stmts can appear in any order 8022 fraction-digits-stmt 8023 [range-stmt] 8025 fraction-digits-stmt = fraction-digits-keyword sep 8026 fraction-digits-arg-str stmtend 8028 fraction-digits-arg-str = < a string that matches the rule > 8029 < fraction-digits-arg > 8031 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 8032 "5" / "6" / "7" / "8"]) 8033 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 8035 string-restrictions = ;; these stmts can appear in any order 8036 [length-stmt] 8037 *pattern-stmt 8039 length-stmt = length-keyword sep length-arg-str optsep 8040 (";" / 8041 "{" stmtsep 8042 ;; these stmts can appear in any order 8044 [error-message-stmt] 8045 [error-app-tag-stmt] 8046 [description-stmt] 8047 [reference-stmt] 8048 "}") stmtsep 8050 pattern-stmt = pattern-keyword sep string optsep 8051 (";" / 8052 "{" stmtsep 8053 ;; these stmts can appear in any order 8054 [modifier-stmt] 8055 [error-message-stmt] 8056 [error-app-tag-stmt] 8057 [description-stmt] 8058 [reference-stmt] 8059 "}") stmtsep 8061 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 8063 modifier-arg-str = < a string that matches the rule > 8064 < modifier-arg > 8066 modifier-arg = invert-match-keyword 8068 default-stmt = default-keyword sep string stmtend 8070 enum-specification = 1*enum-stmt 8072 enum-stmt = enum-keyword sep string optsep 8073 (";" / 8074 "{" stmtsep 8075 ;; these stmts can appear in any order 8076 *if-feature-stmt 8077 [value-stmt] 8078 [status-stmt] 8079 [description-stmt] 8080 [reference-stmt] 8081 "}") stmtsep 8083 leafref-specification = 8084 ;; these stmts can appear in any order 8085 path-stmt 8086 [require-instance-stmt] 8088 path-stmt = path-keyword sep path-arg-str stmtend 8090 require-instance-stmt = require-instance-keyword sep 8091 require-instance-arg-str stmtend 8093 require-instance-arg-str = < a string that matches the rule > 8094 < require-instance-arg > 8096 require-instance-arg = true-keyword / false-keyword 8098 instance-identifier-specification = 8099 [require-instance-stmt] 8101 identityref-specification = 8102 1*base-stmt 8104 union-specification = 1*type-stmt 8106 binary-specification = [length-stmt] 8108 bits-specification = 1*bit-stmt 8110 bit-stmt = bit-keyword sep identifier-arg-str optsep 8111 (";" / 8112 "{" stmtsep 8113 ;; these stmts can appear in any order 8114 *if-feature-stmt 8115 [position-stmt] 8116 [status-stmt] 8117 [description-stmt] 8118 [reference-stmt] 8119 "}") stmtsep 8121 position-stmt = position-keyword sep 8122 position-value-arg-str stmtend 8124 position-value-arg-str = < a string that matches the rule > 8125 < position-value-arg > 8127 position-value-arg = non-negative-integer-value 8129 status-stmt = status-keyword sep status-arg-str stmtend 8131 status-arg-str = < a string that matches the rule > 8132 < status-arg > 8134 status-arg = current-keyword / 8135 obsolete-keyword / 8136 deprecated-keyword 8138 config-stmt = config-keyword sep 8139 config-arg-str stmtend 8141 config-arg-str = < a string that matches the rule > 8142 < config-arg > 8144 config-arg = true-keyword / false-keyword 8146 mandatory-stmt = mandatory-keyword sep 8147 mandatory-arg-str stmtend 8149 mandatory-arg-str = < a string that matches the rule > 8150 < mandatory-arg > 8152 mandatory-arg = true-keyword / false-keyword 8154 presence-stmt = presence-keyword sep string stmtend 8156 ordered-by-stmt = ordered-by-keyword sep 8157 ordered-by-arg-str stmtend 8159 ordered-by-arg-str = < a string that matches the rule > 8160 < ordered-by-arg > 8162 ordered-by-arg = user-keyword / system-keyword 8164 must-stmt = must-keyword sep string optsep 8165 (";" / 8166 "{" stmtsep 8167 ;; these stmts can appear in any order 8168 [error-message-stmt] 8169 [error-app-tag-stmt] 8170 [description-stmt] 8171 [reference-stmt] 8172 "}") stmtsep 8174 error-message-stmt = error-message-keyword sep string stmtend 8176 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 8178 min-elements-stmt = min-elements-keyword sep 8179 min-value-arg-str stmtend 8181 min-value-arg-str = < a string that matches the rule > 8182 < min-value-arg > 8184 min-value-arg = non-negative-integer-value 8186 max-elements-stmt = max-elements-keyword sep 8187 max-value-arg-str stmtend 8189 max-value-arg-str = < a string that matches the rule > 8190 < max-value-arg > 8192 max-value-arg = unbounded-keyword / 8193 positive-integer-value 8195 value-stmt = value-keyword sep integer-value-str stmtend 8197 integer-value-str = < a string that matches the rule > 8198 < integer-value > 8200 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 8201 (";" / 8202 "{" stmtsep 8203 ;; these stmts can appear in any order 8204 [status-stmt] 8205 [description-stmt] 8206 [reference-stmt] 8207 *(typedef-stmt / grouping-stmt) 8208 *data-def-stmt 8209 *action-stmt 8210 *notification-stmt 8211 "}") stmtsep 8213 container-stmt = container-keyword sep identifier-arg-str optsep 8214 (";" / 8215 "{" stmtsep 8216 ;; these stmts can appear in any order 8217 [when-stmt] 8218 *if-feature-stmt 8219 *must-stmt 8220 [presence-stmt] 8221 [config-stmt] 8222 [status-stmt] 8223 [description-stmt] 8224 [reference-stmt] 8225 *(typedef-stmt / grouping-stmt) 8226 *data-def-stmt 8227 *action-stmt 8228 *notification-stmt 8229 "}") stmtsep 8231 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 8232 "{" stmtsep 8233 ;; these stmts can appear in any order 8234 [when-stmt] 8235 *if-feature-stmt 8236 type-stmt 8238 [units-stmt] 8239 *must-stmt 8240 [default-stmt] 8241 [config-stmt] 8242 [mandatory-stmt] 8243 [status-stmt] 8244 [description-stmt] 8245 [reference-stmt] 8246 "}" stmtsep 8248 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 8249 "{" stmtsep 8250 ;; these stmts can appear in any order 8251 [when-stmt] 8252 *if-feature-stmt 8253 type-stmt stmtsep 8254 [units-stmt] 8255 *must-stmt 8256 *default-stmt 8257 [config-stmt] 8258 [min-elements-stmt] 8259 [max-elements-stmt] 8260 [ordered-by-stmt] 8261 [status-stmt] 8262 [description-stmt] 8263 [reference-stmt] 8264 "}" stmtsep 8266 list-stmt = list-keyword sep identifier-arg-str optsep 8267 "{" stmtsep 8268 ;; these stmts can appear in any order 8269 [when-stmt] 8270 *if-feature-stmt 8271 *must-stmt 8272 [key-stmt] 8273 *unique-stmt 8274 [config-stmt] 8275 [min-elements-stmt] 8276 [max-elements-stmt] 8277 [ordered-by-stmt] 8278 [status-stmt] 8279 [description-stmt] 8280 [reference-stmt] 8281 *(typedef-stmt / grouping-stmt) 8282 1*data-def-stmt 8283 *action-stmt 8284 *notification-stmt 8285 "}" stmtsep 8287 key-stmt = key-keyword sep key-arg-str stmtend 8289 key-arg-str = < a string that matches the rule > 8290 < key-arg > 8292 key-arg = node-identifier *(sep node-identifier) 8294 unique-stmt = unique-keyword sep unique-arg-str stmtend 8296 unique-arg-str = < a string that matches the rule > 8297 < unique-arg > 8299 unique-arg = descendant-schema-nodeid 8300 *(sep descendant-schema-nodeid) 8302 choice-stmt = choice-keyword sep identifier-arg-str optsep 8303 (";" / 8304 "{" stmtsep 8305 ;; these stmts can appear in any order 8306 [when-stmt] 8307 *if-feature-stmt 8308 [default-stmt] 8309 [config-stmt] 8310 [mandatory-stmt] 8311 [status-stmt] 8312 [description-stmt] 8313 [reference-stmt] 8314 *(short-case-stmt / case-stmt) 8315 "}") stmtsep 8317 short-case-stmt = choice-stmt / 8318 container-stmt / 8319 leaf-stmt / 8320 leaf-list-stmt / 8321 list-stmt / 8322 anydata-stmt / 8323 anyxml-stmt 8325 case-stmt = case-keyword sep identifier-arg-str optsep 8326 (";" / 8327 "{" stmtsep 8328 ;; these stmts can appear in any order 8329 [when-stmt] 8330 *if-feature-stmt 8331 [status-stmt] 8332 [description-stmt] 8333 [reference-stmt] 8334 *data-def-stmt 8336 "}") stmtsep 8338 anydata-stmt = anydata-keyword sep identifier-arg-str optsep 8339 (";" / 8340 "{" stmtsep 8341 ;; these stmts can appear in any order 8342 [when-stmt] 8343 *if-feature-stmt 8344 *must-stmt 8345 [config-stmt] 8346 [mandatory-stmt] 8347 [status-stmt] 8348 [description-stmt] 8349 [reference-stmt] 8350 "}") stmtsep 8352 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 8353 (";" / 8354 "{" stmtsep 8355 ;; these stmts can appear in any order 8356 [when-stmt] 8357 *if-feature-stmt 8358 *must-stmt 8359 [config-stmt] 8360 [mandatory-stmt] 8361 [status-stmt] 8362 [description-stmt] 8363 [reference-stmt] 8364 "}") stmtsep 8366 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 8367 (";" / 8368 "{" stmtsep 8369 ;; these stmts can appear in any order 8370 [when-stmt] 8371 *if-feature-stmt 8372 [status-stmt] 8373 [description-stmt] 8374 [reference-stmt] 8375 *refine-stmt 8376 *uses-augment-stmt 8377 "}") stmtsep 8379 refine-stmt = refine-keyword sep refine-arg-str optsep 8380 "{" stmtsep 8381 ;; these stmts can appear in any order 8382 *if-feature-stmt 8383 *must-stmt 8385 [presence-stmt] 8386 *default-stmt 8387 [config-stmt] 8388 [mandatory-stmt] 8389 [min-elements-stmt] 8390 [max-elements-stmt] 8391 [description-stmt] 8392 [reference-stmt] 8393 "}" stmtsep 8395 refine-arg-str = < a string that matches the rule > 8396 < refine-arg > 8398 refine-arg = descendant-schema-nodeid 8400 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 8401 "{" stmtsep 8402 ;; these stmts can appear in any order 8403 [when-stmt] 8404 *if-feature-stmt 8405 [status-stmt] 8406 [description-stmt] 8407 [reference-stmt] 8408 1*(data-def-stmt / case-stmt / 8409 action-stmt / notification-stmt) 8410 "}" stmtsep 8412 uses-augment-arg-str = < a string that matches the rule > 8413 < uses-augment-arg > 8415 uses-augment-arg = descendant-schema-nodeid 8417 augment-stmt = augment-keyword sep augment-arg-str optsep 8418 "{" stmtsep 8419 ;; these stmts can appear in any order 8420 [when-stmt] 8421 *if-feature-stmt 8422 [status-stmt] 8423 [description-stmt] 8424 [reference-stmt] 8425 1*(data-def-stmt / case-stmt / 8426 action-stmt / notification-stmt) 8427 "}" stmtsep 8429 augment-arg-str = < a string that matches the rule > 8430 < augment-arg > 8432 augment-arg = absolute-schema-nodeid 8433 when-stmt = when-keyword sep string optsep 8434 (";" / 8435 "{" stmtsep 8436 ;; these stmts can appear in any order 8437 [description-stmt] 8438 [reference-stmt] 8439 "}") stmtsep 8441 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 8442 (";" / 8443 "{" stmtsep 8444 ;; these stmts can appear in any order 8445 *if-feature-stmt 8446 [status-stmt] 8447 [description-stmt] 8448 [reference-stmt] 8449 *(typedef-stmt / grouping-stmt) 8450 [input-stmt] 8451 [output-stmt] 8452 "}") stmtsep 8454 action-stmt = action-keyword sep identifier-arg-str optsep 8455 (";" / 8456 "{" stmtsep 8457 ;; these stmts can appear in any order 8458 *if-feature-stmt 8459 [status-stmt] 8460 [description-stmt] 8461 [reference-stmt] 8462 *(typedef-stmt / grouping-stmt) 8463 [input-stmt] 8464 [output-stmt] 8465 "}") stmtsep 8467 input-stmt = input-keyword optsep 8468 "{" stmtsep 8469 ;; these stmts can appear in any order 8470 *must-stmt 8471 *(typedef-stmt / grouping-stmt) 8472 1*data-def-stmt 8473 "}" stmtsep 8475 output-stmt = output-keyword optsep 8476 "{" stmtsep 8477 ;; these stmts can appear in any order 8478 *must-stmt 8479 *(typedef-stmt / grouping-stmt) 8480 1*data-def-stmt 8482 "}" stmtsep 8484 notification-stmt = notification-keyword sep 8485 identifier-arg-str optsep 8486 (";" / 8487 "{" stmtsep 8488 ;; these stmts can appear in any order 8489 *if-feature-stmt 8490 *must-stmt 8491 [status-stmt] 8492 [description-stmt] 8493 [reference-stmt] 8494 *(typedef-stmt / grouping-stmt) 8495 *data-def-stmt 8496 "}") stmtsep 8498 deviation-stmt = deviation-keyword sep 8499 deviation-arg-str optsep 8500 "{" stmtsep 8501 ;; these stmts can appear in any order 8502 [description-stmt] 8503 [reference-stmt] 8504 (deviate-not-supported-stmt / 8505 1*(deviate-add-stmt / 8506 deviate-replace-stmt / 8507 deviate-delete-stmt)) 8508 "}" stmtsep 8510 deviation-arg-str = < a string that matches the rule > 8511 < deviation-arg > 8513 deviation-arg = absolute-schema-nodeid 8515 deviate-not-supported-stmt = 8516 deviate-keyword sep 8517 not-supported-keyword-str stmtend 8519 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 8520 (";" / 8521 "{" stmtsep 8522 ;; these stmts can appear in any order 8523 [units-stmt] 8524 *must-stmt 8525 *unique-stmt 8526 *default-stmt 8527 [config-stmt] 8528 [mandatory-stmt] 8529 [min-elements-stmt] 8531 [max-elements-stmt] 8532 "}") stmtsep 8534 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 8535 (";" / 8536 "{" stmtsep 8537 ;; these stmts can appear in any order 8538 [units-stmt] 8539 *must-stmt 8540 *unique-stmt 8541 *default-stmt 8542 "}") stmtsep 8544 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 8545 (";" / 8546 "{" stmtsep 8547 ;; these stmts can appear in any order 8548 [type-stmt] 8549 [units-stmt] 8550 [default-stmt] 8551 [config-stmt] 8552 [mandatory-stmt] 8553 [min-elements-stmt] 8554 [max-elements-stmt] 8555 "}") stmtsep 8557 not-supported-keyword-str = < a string that matches the rule > 8558 < not-supported-keyword > 8560 add-keyword-str = < a string that matches the rule > 8561 < add-keyword > 8563 delete-keyword-str = < a string that matches the rule > 8564 < delete-keyword > 8566 replace-keyword-str = < a string that matches the rule > 8567 < replace-keyword > 8569 ;; represents the usage of an extension statement 8570 unknown-statement = prefix ":" identifier [sep string] optsep 8571 (";" / 8572 "{" optsep 8573 *((yang-stmt / unknown-statement) optsep) 8574 "}") stmtsep 8576 yang-stmt = action-stmt / 8577 anydata-stmt / 8578 anyxml-stmt / 8579 argument-stmt / 8580 augment-stmt / 8581 base-stmt / 8582 belongs-to-stmt / 8583 bit-stmt / 8584 case-stmt / 8585 choice-stmt / 8586 config-stmt / 8587 contact-stmt / 8588 container-stmt / 8589 default-stmt / 8590 description-stmt / 8591 deviate-add-stmt / 8592 deviate-delete-stmt / 8593 deviate-not-supported-stmt / 8594 deviate-replace-stmt / 8595 deviation-stmt / 8596 enum-stmt / 8597 error-app-tag-stmt / 8598 error-message-stmt / 8599 extension-stmt / 8600 feature-stmt / 8601 fraction-digits-stmt / 8602 grouping-stmt / 8603 identity-stmt / 8604 if-feature-stmt / 8605 import-stmt / 8606 include-stmt / 8607 input-stmt / 8608 key-stmt / 8609 leaf-list-stmt / 8610 leaf-stmt / 8611 length-stmt / 8612 list-stmt / 8613 mandatory-stmt / 8614 max-elements-stmt / 8615 min-elements-stmt / 8616 modifier-stmt / 8617 module-stmt / 8618 must-stmt / 8619 namespace-stmt / 8620 notification-stmt / 8621 ordered-by-stmt / 8622 organization-stmt / 8623 output-stmt / 8624 path-stmt / 8625 pattern-stmt / 8626 position-stmt / 8627 prefix-stmt / 8628 presence-stmt / 8629 range-stmt / 8630 reference-stmt / 8631 refine-stmt / 8632 require-instance-stmt / 8633 revision-date-stmt / 8634 revision-stmt / 8635 rpc-stmt / 8636 status-stmt / 8637 submodule-stmt / 8638 typedef-stmt / 8639 type-stmt / 8640 unique-stmt / 8641 units-stmt / 8642 uses-augment-stmt / 8643 uses-stmt / 8644 value-stmt / 8645 when-stmt / 8646 yang-version-stmt / 8647 yin-element-stmt 8649 ;; Ranges 8651 range-arg-str = < a string that matches the rule > 8652 < range-arg > 8654 range-arg = range-part *(optsep "|" optsep range-part) 8656 range-part = range-boundary 8657 [optsep ".." optsep range-boundary] 8659 range-boundary = min-keyword / max-keyword / 8660 integer-value / decimal-value 8662 ;; Lengths 8664 length-arg-str = < a string that matches the rule > 8665 < length-arg > 8667 length-arg = length-part *(optsep "|" optsep length-part) 8669 length-part = length-boundary 8670 [optsep ".." optsep length-boundary] 8672 length-boundary = min-keyword / max-keyword / 8673 non-negative-integer-value 8675 ;; Date 8677 date-arg-str = < a string that matches the rule > 8678 < date-arg > 8680 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 8682 ;; Schema Node Identifiers 8684 schema-nodeid = absolute-schema-nodeid / 8685 descendant-schema-nodeid 8687 absolute-schema-nodeid = 1*("/" node-identifier) 8689 descendant-schema-nodeid = 8690 node-identifier 8691 [absolute-schema-nodeid] 8693 node-identifier = [prefix ":"] identifier 8695 ;; Instance Identifiers 8697 instance-identifier = 1*("/" (node-identifier 8698 [1*key-predicate / 8699 leaf-list-predicate / 8700 pos])) 8702 key-predicate = "[" *WSP key-predicate-expr *WSP "]" 8704 key-predicate-expr = node-identifier *WSP "=" *WSP quoted-string 8706 leaf-list-predicate = "[" *WSP leaf-list-predicate-expr *WSP "]" 8708 leaf-list-predicate-expr = "." *WSP "=" *WSP quoted-string 8710 pos = "[" *WSP positive-integer-value *WSP "]" 8712 quoted-string = (DQUOTE string DQUOTE) / (SQUOTE string SQUOTE) 8714 ;; leafref path 8716 path-arg-str = < a string that matches the rule > 8717 < path-arg > 8719 path-arg = absolute-path / relative-path 8721 absolute-path = 1*("/" (node-identifier *path-predicate)) 8722 relative-path = 1*("../") descendant-path 8724 descendant-path = node-identifier 8725 [*path-predicate absolute-path] 8727 path-predicate = "[" *WSP path-equality-expr *WSP "]" 8729 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 8731 path-key-expr = current-function-invocation *WSP "/" *WSP 8732 rel-path-keyexpr 8734 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 8735 *(node-identifier *WSP "/" *WSP) 8736 node-identifier 8738 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 8740 ;; statement keywords 8741 action-keyword = %s"action" 8742 anydata-keyword = %s"anydata" 8743 anyxml-keyword = %s"anyxml" 8744 argument-keyword = %s"argument" 8745 augment-keyword = %s"augment" 8746 base-keyword = %s"base" 8747 belongs-to-keyword = %s"belongs-to" 8748 bit-keyword = %s"bit" 8749 case-keyword = %s"case" 8750 choice-keyword = %s"choice" 8751 config-keyword = %s"config" 8752 contact-keyword = %s"contact" 8753 container-keyword = %s"container" 8754 default-keyword = %s"default" 8755 description-keyword = %s"description" 8756 enum-keyword = %s"enum" 8757 error-app-tag-keyword = %s"error-app-tag" 8758 error-message-keyword = %s"error-message" 8759 extension-keyword = %s"extension" 8760 deviation-keyword = %s"deviation" 8761 deviate-keyword = %s"deviate" 8762 feature-keyword = %s"feature" 8763 fraction-digits-keyword = %s"fraction-digits" 8764 grouping-keyword = %s"grouping" 8765 identity-keyword = %s"identity" 8766 if-feature-keyword = %s"if-feature" 8767 import-keyword = %s"import" 8768 include-keyword = %s"include" 8769 input-keyword = %s"input" 8770 key-keyword = %s"key" 8771 leaf-keyword = %s"leaf" 8772 leaf-list-keyword = %s"leaf-list" 8773 length-keyword = %s"length" 8774 list-keyword = %s"list" 8775 mandatory-keyword = %s"mandatory" 8776 max-elements-keyword = %s"max-elements" 8777 min-elements-keyword = %s"min-elements" 8778 modifier-keyword = %s"modifier" 8779 module-keyword = %s"module" 8780 must-keyword = %s"must" 8781 namespace-keyword = %s"namespace" 8782 notification-keyword = %s"notification" 8783 ordered-by-keyword = %s"ordered-by" 8784 organization-keyword = %s"organization" 8785 output-keyword = %s"output" 8786 path-keyword = %s"path" 8787 pattern-keyword = %s"pattern" 8788 position-keyword = %s"position" 8789 prefix-keyword = %s"prefix" 8790 presence-keyword = %s"presence" 8791 range-keyword = %s"range" 8792 reference-keyword = %s"reference" 8793 refine-keyword = %s"refine" 8794 require-instance-keyword = %s"require-instance" 8795 revision-keyword = %s"revision" 8796 revision-date-keyword = %s"revision-date" 8797 rpc-keyword = %s"rpc" 8798 status-keyword = %s"status" 8799 submodule-keyword = %s"submodule" 8800 type-keyword = %s"type" 8801 typedef-keyword = %s"typedef" 8802 unique-keyword = %s"unique" 8803 units-keyword = %s"units" 8804 uses-keyword = %s"uses" 8805 value-keyword = %s"value" 8806 when-keyword = %s"when" 8807 yang-version-keyword = %s"yang-version" 8808 yin-element-keyword = %s"yin-element" 8810 ;; other keywords 8812 add-keyword = %s"add" 8813 current-keyword = %s"current" 8814 delete-keyword = %s"delete" 8815 deprecated-keyword = %s"deprecated" 8816 false-keyword = %s"false" 8817 invert-match-keyword = %s"invert-match" 8818 max-keyword = %s"max" 8819 min-keyword = %s"min" 8820 not-supported-keyword = %s"not-supported" 8821 obsolete-keyword = %s"obsolete" 8822 replace-keyword = %s"replace" 8823 system-keyword = %s"system" 8824 true-keyword = %s"true" 8825 unbounded-keyword = %s"unbounded" 8826 user-keyword = %s"user" 8828 and-keyword = %s"and" 8829 or-keyword = %s"or" 8830 not-keyword = %s"not" 8832 current-function-invocation = current-keyword *WSP "(" *WSP ")" 8834 ;;; Basic Rules 8836 prefix-arg-str = < a string that matches the rule > 8837 < prefix-arg > 8839 prefix-arg = prefix 8841 prefix = identifier 8843 identifier-arg-str = < a string that matches the rule > 8844 < identifier-arg > 8846 identifier-arg = identifier 8848 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 8849 identifier = (ALPHA / "_") 8850 *(ALPHA / DIGIT / "_" / "-" / ".") 8852 identifier-ref-arg-str = < a string that matches the rule > 8853 < identifier-ref-arg > 8855 identifier-ref-arg = identifier-ref 8857 identifier-ref = [prefix ":"] identifier 8859 string = < an unquoted string as returned by > 8860 < the scanner, that matches the rule > 8861 < yang-string > 8863 yang-string = *yang-char 8865 ;; any Unicode or ISO/IEC 10646 character including tab, carriage 8866 ;; return, and line feed, but excluding the other C0 control 8867 ;; characters, the surrogate blocks, and the noncharacters. 8868 yang-char = %x09 / %x0A / %x0D / %x20-D7FF / 8869 ; exclude surrogate blocks %xD800-DFFF 8870 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 8871 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 8872 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 8873 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 8874 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 8875 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 8876 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 8877 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 8878 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 8879 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 8880 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 8881 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 8882 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 8883 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 8884 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 8885 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 8886 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 8887 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 8889 integer-value = ("-" non-negative-integer-value) / 8890 non-negative-integer-value 8892 non-negative-integer-value = "0" / positive-integer-value 8894 positive-integer-value = (non-zero-digit *DIGIT) 8896 zero-integer-value = 1*DIGIT 8898 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 8900 sep = 1*(WSP / line-break) 8901 ; unconditional separator 8903 optsep = *(WSP / line-break) 8905 stmtsep = *(WSP / line-break / unknown-statement) 8907 line-break = CRLF / LF 8909 non-zero-digit = %x31-39 8911 decimal-value = integer-value ("." zero-integer-value) 8913 SQUOTE = %x27 8914 ; single quote 8916 ;;; RFC 5234 core rules. 8918 ALPHA = %x41-5A / %x61-7A 8919 ; A-Z / a-z 8921 CR = %x0D 8922 ; carriage return 8924 CRLF = CR LF 8925 ; Internet standard new line 8927 DIGIT = %x30-39 8928 ; 0-9 8930 DQUOTE = %x22 8931 ; double quote 8933 HTAB = %x09 8934 ; horizontal tab 8936 LF = %x0A 8937 ; linefeed 8939 SP = %x20 8940 ; space 8942 WSP = SP / HTAB 8943 ; whitespace 8945 8947 15. NETCONF Error Responses for YANG Related Errors 8949 A number of NETCONF error responses are defined for error cases 8950 related to the data-model handling. If the relevant YANG statement 8951 has an "error-app-tag" substatement, that overrides the default value 8952 specified below. 8954 15.1. Error Message for Data That Violates a unique Statement 8956 If a NETCONF operation would result in configuration data where a 8957 unique constraint is invalidated, the following error is returned: 8959 error-tag: operation-failed 8960 error-app-tag: data-not-unique 8961 error-info: : Contains an instance identifier that 8962 points to a leaf that invalidates the unique 8963 constraint. This element is present once for each 8964 non-unique leaf. 8966 The element is in the YANG 8967 namespace ("urn:ietf:params:xml:ns:yang:1"). 8969 15.2. Error Message for Data That Violates a max-elements Statement 8971 If a NETCONF operation would result in configuration data where a 8972 list or a leaf-list would have too many entries the following error 8973 is returned: 8975 error-tag: operation-failed 8976 error-app-tag: too-many-elements 8978 This error is returned once, with the error-path identifying the list 8979 node, even if there are more than one extra child present. 8981 15.3. Error Message for Data That Violates a min-elements Statement 8983 If a NETCONF operation would result in configuration data where a 8984 list or a leaf-list would have too few entries the following error is 8985 returned: 8987 error-tag: operation-failed 8988 error-app-tag: too-few-elements 8990 This error is returned once, with the error-path identifying the list 8991 node, even if there are more than one child missing. 8993 15.4. Error Message for Data That Violates a must Statement 8995 If a NETCONF operation would result in configuration data where the 8996 restrictions imposed by a "must" statement is violated the following 8997 error is returned, unless a specific "error-app-tag" substatement is 8998 present for the "must" statement. 9000 error-tag: operation-failed 9001 error-app-tag: must-violation 9003 15.5. Error Message for Data That Violates a require-instance Statement 9005 If a NETCONF operation would result in configuration data where a 9006 leaf of type "instance-identifier" or "leafref" marked with require- 9007 instance "true" refers to a non-existing instance, the following 9008 error is returned: 9010 error-tag: data-missing 9011 error-app-tag: instance-required 9012 error-path: Path to the instance-identifier or leafref leaf. 9014 15.6. Error Message for Data That Violates a mandatory choice Statement 9016 If a NETCONF operation would result in configuration data where no 9017 nodes exists in a mandatory choice, the following error is returned: 9019 error-tag: data-missing 9020 error-app-tag: missing-choice 9021 error-path: Path to the element with the missing choice. 9022 error-info: : Contains the name of the missing 9023 mandatory choice. 9025 The element is in the YANG 9026 namespace ("urn:ietf:params:xml:ns:yang:1"). 9028 15.7. Error Message for the "insert" Operation 9030 If the "insert" and "key" or "value" attributes are used in an 9031 for a list or leaf-list node, and the "key" or "value" 9032 refers to a non-existing instance, the following error is returned: 9034 error-tag: bad-attribute 9035 error-app-tag: missing-instance 9037 16. IANA Considerations 9039 This document registers one capability identifier URN from the 9040 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 9042 Index Capability Identifier 9043 ------------- --------------------------------------------------- 9044 :yang-library urn:ietf:params:netconf:capability:yang-library:1.0 9046 17. Security Considerations 9048 This document defines a language with which to write and read 9049 descriptions of management information. The language itself has no 9050 security impact on the Internet. 9052 The same considerations are relevant as for the base NETCONF protocol 9053 (see [RFC6241], Section 9). 9055 Data modeled in YANG might contain sensitive information. RPCs or 9056 notifications defined in YANG might transfer sensitive information. 9058 Security issues are related to the usage of data modeled in YANG. 9059 Such issues shall be dealt with in documents describing the data 9060 models and documents about the interfaces used to manipulate the data 9061 e.g., the NETCONF documents. 9063 Data modeled in YANG is dependent upon: 9065 o the security of the transmission infrastructure used to send 9066 sensitive information. 9068 o the security of applications that store or release such sensitive 9069 information. 9071 o adequate authentication and access control mechanisms to restrict 9072 the usage of sensitive data. 9074 YANG parsers need to be robust with respect to malformed documents. 9075 Reading malformed documents from unknown or untrusted sources could 9076 result in an attacker gaining privileges of the user running the YANG 9077 parser. In an extreme situation, the entire machine could be 9078 compromised. 9080 18. Contributors 9082 The following people all contributed significantly to the initial 9083 YANG document: 9085 - Andy Bierman (YumaWorks) 9086 - Balazs Lengyel (Ericsson) 9087 - David Partain (Ericsson) 9088 - Juergen Schoenwaelder (Jacobs University Bremen) 9089 - Phil Shafer (Juniper Networks) 9091 19. Acknowledgements 9093 The editor wishes to thank the following individuals, who all 9094 provided helpful comments on various versions of this document: 9095 Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, 9096 Ladislav Lhotka, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy 9097 Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert Wijnen, and 9098 Robert Wilton. 9100 20. ChangeLog 9102 RFC Editor: remove this section upon publication as an RFC. 9104 20.1. Version -10 9106 o Made single and double quote characters illegal in unquoted 9107 strings. 9109 o Allow "description" and "reference" in "import" and "include". 9111 o Removed redundant NETCONF Error Message subsection. 9113 o Editorial fixes and clarifications after second WGLC reviews. 9115 20.2. Version -09 9117 o Editorial fixes and clarifications after WGLC reviews. 9119 o when statement context clarification. 9121 o Allow "augment" to add conditionally mandatory nodes (see 9122 Section 7.17). 9124 o Allow non-unique config false leaf-lists. 9126 o Made handling of choice and false "when" expressions non-NETCONF 9127 specific. 9129 o Changed the function signatures for "derived-from" and 9130 "derived-from-or-self". 9132 20.3. Version -08 9134 o Fixes after WGLC reviews. 9136 20.4. Version -07 9138 o Fixes after WG review. 9140 o Included solution Y60-01. 9142 20.5. Version -06 9144 o Included solution Y45-05. 9146 20.6. Version -05 9148 o Included solution Y18-01. 9150 o Included solution Y25-02 (parts of it was included in -04). 9152 o Included solution Y34-05. 9154 o Included solution Y36-03. 9156 20.7. Version -04 9158 o Incorporated changes to ABNF grammar after review and errata for 9159 RFC 6020. 9161 o Included solution Y16-03. 9163 o Included solution Y49-04. 9165 o Included solution Y58-01. 9167 o Included solution Y59-01. 9169 20.8. Version -03 9171 o Incorporated changes from WG reviews. 9173 o Included solution Y05-01. 9175 o Included solution Y10-01. 9177 o Included solution Y13-01. 9179 o Included solution Y28-02. 9181 o Included solution Y55-01 (parts of it was included in -01). 9183 20.9. Version -02 9185 o Included solution Y02-01. 9187 o Included solution Y04-02. 9189 o Included solution Y11-01. 9191 o Included solution Y41-01. 9193 o Included solution Y56-01. 9195 20.10. Version -01 9197 o Included solution Y01-01. 9199 o Included solution Y03-01. 9201 o Included solution Y06-02. 9203 o Included solution Y07-01. 9205 o Included solution Y14-01. 9207 o Included solution Y20-01. 9209 o Included solution Y23-01. 9211 o Included solution Y29-01. 9213 o Included solution Y30-01. 9215 o Included solution Y31-01. 9217 o Included solution Y35-01. 9219 20.11. Version -00 9221 o Applied all reported errata for RFC 6020. 9223 o Updated YANG version to 1.1, and made the "yang-version" statement 9224 mandatory. 9226 21. References 9228 21.1. Normative References 9230 [I-D.ietf-netconf-yang-library] 9231 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 9232 Library", draft-ietf-netconf-yang-library-06 (work in 9233 progress), April 2016. 9235 [ISO.10646] 9236 International Organization for Standardization, 9237 "Information Technology - Universal Multiple-Octet Coded 9238 Character Set (UCS)", ISO Standard 10646:2003, 2003. 9240 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9241 Requirement Levels", BCP 14, RFC 2119, 9242 DOI 10.17487/RFC2119, March 1997, 9243 . 9245 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 9246 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 9247 2003, . 9249 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9250 Resource Identifier (URI): Generic Syntax", STD 66, 9251 RFC 3986, DOI 10.17487/RFC3986, January 2005, 9252 . 9254 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9255 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9256 . 9258 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9259 Specifications: ABNF", STD 68, RFC 5234, 9260 DOI 10.17487/RFC5234, January 2008, 9261 . 9263 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 9264 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 9265 . 9267 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 9268 and A. Bierman, Ed., "Network Configuration Protocol 9269 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 9270 . 9272 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9273 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9274 . 9276 [XML-NAMES] 9277 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 9278 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 9279 Wide Web Consortium Recommendation REC-xml-names-20091208, 9280 December 2009, 9281 . 9283 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 9284 Version 1.0", World Wide Web Consortium Recommendation 9285 REC-xpath-19991116, November 1999, 9286 . 9288 [XSD-TYPES] 9289 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 9290 Second Edition", World Wide Web Consortium Recommendation 9291 REC-xmlschema-2-20041028, October 2004, 9292 . 9294 21.2. Informative References 9296 [I-D.ietf-netconf-restconf] 9297 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 9298 Protocol", draft-ietf-netconf-restconf-13 (work in 9299 progress), April 2016. 9301 [I-D.ietf-netmod-yang-json] 9302 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 9303 draft-ietf-netmod-yang-json-10 (work in progress), March 9304 2016. 9306 [I-D.vanderstok-core-comi] 9307 Stok, P. and A. Bierman, "CoAP Management Interface", 9308 draft-vanderstok-core-comi-09 (work in progress), March 9309 2016. 9311 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9312 Schoenwaelder, Ed., "Structure of Management Information 9313 Version 2 (SMIv2)", STD 58, RFC 2578, 9314 DOI 10.17487/RFC2578, April 1999, 9315 . 9317 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9318 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 9319 STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 9320 . 9322 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 9323 Structure of Management Information", RFC 3780, 9324 DOI 10.17487/RFC3780, May 2004, 9325 . 9327 [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC 9328 Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, 9329 July 2007, . 9331 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 9332 the Network Configuration Protocol (NETCONF)", RFC 6020, 9333 DOI 10.17487/RFC6020, October 2010, 9334 . 9336 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 9337 Information Version 2 (SMIv2) MIB Modules to YANG 9338 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 9339 . 9341 [RFC6691] Borman, D., "TCP Options and Maximum Segment Size (MSS)", 9342 RFC 6691, DOI 10.17487/RFC6691, July 2012, 9343 . 9345 [XPATH2.0] 9346 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 9347 Kay, M., Robie, J., and J. Simeon, "XML Path Language 9348 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 9349 Recommendation REC-xpath20-20101214, December 2010, 9350 . 9352 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 9353 Wide Web Consortium Recommendation REC-xslt-19991116, 9354 November 1999, 9355 . 9357 Author's Address 9359 Martin Bjorklund (editor) 9360 Tail-f Systems 9362 Email: mbj@tail-f.com