idnits 2.17.1 draft-ietf-netmod-rfc6020bis-11.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 8989 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 (February 16, 2016) is 2991 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 7128 == Outdated reference: A later version (-06) exists of draft-ietf-netconf-yang-library-04 -- 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-09 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-07 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-08 -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track February 16, 2016 5 Expires: August 19, 2016 7 The YANG 1.1 Data Modeling Language 8 draft-ietf-netmod-rfc6020bis-11 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 like the Network Configuration Protocol 15 (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 August 19, 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 . . . . . . . . . . . . 8 65 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 69 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 70 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 71 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 72 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19 73 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20 74 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 75 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 76 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 77 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 78 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25 79 4.2.10. Notification Definitions . . . . . . . . . . . . . . 28 80 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 81 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 82 5.1.1. Import and Include by Revision . . . . . . . . . . . 29 83 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 31 84 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 32 85 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 32 86 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 32 87 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 32 88 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 33 89 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 33 90 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 34 91 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 34 92 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 34 93 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 35 94 5.6.5. Announcing Conformance Information in NETCONF . . . . 38 95 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 39 96 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 39 97 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 39 98 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 39 99 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 40 100 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 40 101 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 41 102 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 42 103 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 43 104 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 43 105 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 43 106 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 44 107 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 49 108 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 49 109 7.1. The module Statement . . . . . . . . . . . . . . . . . . 50 110 7.1.1. The module's Substatements . . . . . . . . . . . . . 50 111 7.1.2. The yang-version Statement . . . . . . . . . . . . . 51 112 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 52 113 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 52 114 7.1.5. The import Statement . . . . . . . . . . . . . . . . 52 115 7.1.6. The include Statement . . . . . . . . . . . . . . . . 54 116 7.1.7. The organization Statement . . . . . . . . . . . . . 54 117 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 54 118 7.1.9. The revision Statement . . . . . . . . . . . . . . . 55 119 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 55 120 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 56 121 7.2.1. The submodule's Substatements . . . . . . . . . . . . 57 122 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 58 123 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 59 124 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 59 125 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 60 126 7.3.2. The typedef's type Statement . . . . . . . . . . . . 60 127 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 60 128 7.3.4. The typedef's default Statement . . . . . . . . . . . 60 129 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 61 130 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 61 131 7.4.1. The type's Substatements . . . . . . . . . . . . . . 61 132 7.5. The container Statement . . . . . . . . . . . . . . . . . 61 133 7.5.1. Containers with Presence . . . . . . . . . . . . . . 62 134 7.5.2. The container's Substatements . . . . . . . . . . . . 62 135 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 63 136 7.5.4. The must's Substatements . . . . . . . . . . . . . . 64 137 7.5.5. The presence Statement . . . . . . . . . . . . . . . 65 138 7.5.6. The container's Child Node Statements . . . . . . . . 65 139 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 65 140 7.5.8. NETCONF Operations . . . . . . . . . . 66 141 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 66 142 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 67 143 7.6.1. The leaf's default value . . . . . . . . . . . . . . 67 144 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 68 145 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 69 146 7.6.4. The leaf's default Statement . . . . . . . . . . . . 69 147 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 69 148 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 70 149 7.6.7. NETCONF Operations . . . . . . . . . . 70 150 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 70 151 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 71 152 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 71 153 7.7.2. The leaf-list's default values . . . . . . . . . . . 72 154 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 73 155 7.7.4. The leaf-list's default Statement . . . . . . . . . . 73 156 7.7.5. The min-elements Statement . . . . . . . . . . . . . 74 157 7.7.6. The max-elements Statement . . . . . . . . . . . . . 74 158 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 74 159 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 75 160 7.7.9. NETCONF Operations . . . . . . . . . . 75 161 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 76 162 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 78 163 7.8.1. The list's Substatements . . . . . . . . . . . . . . 78 164 7.8.2. The list's key Statement . . . . . . . . . . . . . . 79 165 7.8.3. The list's unique Statement . . . . . . . . . . . . . 80 166 7.8.4. The list's Child Node Statements . . . . . . . . . . 81 167 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 81 168 7.8.6. NETCONF Operations . . . . . . . . . . 82 169 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 83 170 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 86 171 7.9.1. The choice's Substatements . . . . . . . . . . . . . 86 172 7.9.2. The choice's case Statement . . . . . . . . . . . . . 87 173 7.9.3. The choice's default Statement . . . . . . . . . . . 88 174 7.9.4. The choice's mandatory Statement . . . . . . . . . . 90 175 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 90 176 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 90 177 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 91 178 7.10.1. The anydata's Substatements . . . . . . . . . . . . 92 179 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 180 7.10.3. NETCONF Operations . . . . . . . . . . 92 181 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 93 182 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 93 183 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 94 184 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 94 185 7.11.3. NETCONF Operations . . . . . . . . . . 94 186 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 95 187 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 95 188 7.12.1. The grouping's Substatements . . . . . . . . . . . . 96 189 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 97 190 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 97 191 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 97 192 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 98 193 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 99 194 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 99 195 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 100 196 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 100 197 7.14.2. The input Statement . . . . . . . . . . . . . . . . 101 198 7.14.3. The output Statement . . . . . . . . . . . . . . . . 102 199 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 103 200 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 103 201 7.15. The action Statement . . . . . . . . . . . . . . . . . . 104 202 7.15.1. The action's Substatements . . . . . . . . . . . . . 104 203 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 105 204 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 105 205 7.16. The notification Statement . . . . . . . . . . . . . . . 107 206 7.16.1. The notification's Substatements . . . . . . . . . . 108 207 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 208 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 209 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 110 210 7.17.1. The augment's Substatements . . . . . . . . . . . . 112 211 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 113 212 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 113 213 7.18. The identity Statement . . . . . . . . . . . . . . . . . 115 214 7.18.1. The identity's Substatements . . . . . . . . . . . . 115 215 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 115 216 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 217 7.19. The extension Statement . . . . . . . . . . . . . . . . . 118 218 7.19.1. The extension's Substatements . . . . . . . . . . . 118 219 7.19.2. The argument Statement . . . . . . . . . . . . . . . 118 220 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 221 7.20. Conformance-Related Statements . . . . . . . . . . . . . 120 222 7.20.1. The feature Statement . . . . . . . . . . . . . . . 120 223 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 122 224 7.20.3. The deviation Statement . . . . . . . . . . . . . . 122 225 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 126 226 7.21.1. The config Statement . . . . . . . . . . . . . . . . 126 227 7.21.2. The status Statement . . . . . . . . . . . . . . . . 126 228 7.21.3. The description Statement . . . . . . . . . . . . . 127 229 7.21.4. The reference Statement . . . . . . . . . . . . . . 127 230 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 128 231 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 129 232 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 129 233 8.2. Configuration Data Modifications . . . . . . . . . . . . 130 234 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 130 235 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 130 236 8.3.2. NETCONF Processing . . . . . . . . . . 131 237 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 132 238 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 132 239 9.1. Canonical Representation . . . . . . . . . . . . . . . . 132 240 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 133 241 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 133 242 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 243 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 244 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 134 245 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 135 246 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 135 247 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 136 248 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 136 249 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 136 250 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 136 251 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 252 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 137 253 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 137 254 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 138 255 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 256 9.4.4. The length Statement . . . . . . . . . . . . . . . . 138 257 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 139 258 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 139 259 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 139 260 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 141 261 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 141 262 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 263 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 264 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 141 265 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 141 266 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 267 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 268 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 141 269 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 143 270 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 144 271 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 144 272 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 144 273 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 274 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 145 275 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 276 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 147 277 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 278 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 147 279 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 147 280 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 147 281 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 282 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 148 283 9.9.3. The require-instance Statement . . . . . . . . . . . 148 284 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 149 285 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 149 286 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 149 287 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 153 288 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 153 289 9.10.2. The identityref's base Statement . . . . . . . . . . 153 290 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 153 291 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 154 292 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 154 293 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 155 294 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 155 295 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 155 296 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 155 297 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 155 298 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 156 299 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 300 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 156 301 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 156 302 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 156 303 9.13. The instance-identifier Built-In Type . . . . . . . . . . 157 304 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 305 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 158 306 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 307 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 308 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 159 309 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 159 310 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 159 311 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 160 312 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 160 313 10.3. Functions for the YANG Types "leafref" and "instance- 314 identifier" . . . . . . . . . . . . . . . . . . . . . . 161 315 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 161 316 10.4. Functions for the YANG Type "identityref" . . . . . . . 162 317 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 162 318 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 163 319 10.5. Functions for the YANG Type "enumeration" . . . . . . . 164 320 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 164 321 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 165 322 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 165 323 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 166 324 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 168 325 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 326 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 169 327 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 172 328 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 173 329 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 197 330 15.1. Error Message for Data That Violates a unique Statement 197 331 15.2. Error Message for Data That Violates a max-elements 332 Statement . . . . . . . . . . . . . . . . . . . . . . . 198 333 15.3. Error Message for Data That Violates a min-elements 334 Statement . . . . . . . . . . . . . . . . . . . . . . . 198 335 15.4. Error Message for Data That Violates a must Statement . 198 336 15.5. Error Message for Data That Violates a require-instance 337 Statement . . . . . . . . . . . . . . . . . . . . . . . 199 338 15.6. Error Message for Data That Violates a mandatory choice 339 Statement . . . . . . . . . . . . . . . . . . . . . . . 199 340 15.7. Error Message for the "insert" Operation . . . . . . . . 199 341 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 199 342 17. Security Considerations . . . . . . . . . . . . . . . . . . . 199 343 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 200 344 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 200 345 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 201 346 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 201 347 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 201 348 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 201 349 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 201 350 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 201 351 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 202 352 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 202 353 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 202 354 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 202 355 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 203 356 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 203 357 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 203 358 21.1. Normative References . . . . . . . . . . . . . . . . . . 203 359 21.2. Informative References . . . . . . . . . . . . . . . . . 205 360 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 206 362 1. Introduction 364 YANG is a data modeling language originally designed to model 365 configuration and state data manipulated by the Network Configuration 366 Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF 367 notifications [RFC6241]. Since the publication of YANG version 1 368 [RFC6020], YANG has been used or proposed to be used for other 369 protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI 370 [I-D.vanderstok-core-comi]). Further, other encodings than XML have 371 been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). 373 This document describes the syntax and semantics of version 1.1 of 374 the YANG language. It also describes how a data model defined in a 375 YANG module is encoded in the Extensible Markup Language (XML), and 376 how NETCONF operations are used to manipulate the data. Other 377 protocols and encodings are possible, but out of scope for this 378 specification. 380 1.1. Summary of Changes from RFC 6020 382 This document defines version 1.1 of the YANG language. YANG version 383 1.1 is a maintenance release of the YANG language, addressing 384 ambiguities and defects in the original specification [RFC6020]. 386 o Changed the YANG version from "1" to "1.1". 388 o Made the "yang-version" statement mandatory. 390 o Made noncharacters illegal in the built-in type "string". 392 o Defined the legal characters in YANG modules. 394 o Changed the rules for the interpretation of escaped characters in 395 double quoted strings. This is an backwards incompatible change 396 from YANG version 1. A module that uses a character sequence that 397 is now illegal must change the string to match the new rules. See 398 Section 6.1.3 for details. 400 o An unquoted string cannot contain any single or double quote 401 characters. This is an backwards incompatible change from YANG 402 version 1. 404 o Extended the "if-feature" syntax to be a boolean expression over 405 feature names. 407 o Allow "if-feature" in "bit", "enum", and "identity". 409 o Allow "if-feature" in "refine". 411 o Made "when" and "if-feature" illegal on list keys. 413 o Allow "choice" as a shorthand case statement (see Section 7.9). 415 o Added a new substatement "modifier" to pattern (see 416 Section 9.4.6). 418 o Allow "must" in "input", "output", and "notification". 420 o Allow "require-instance" in leafref. 422 o Allow "augment" to add conditionally mandatory nodes (see 423 Section 7.17). 425 o Added a set of new XPath functions in Section 10. 427 o Clarified the XPath context's tree in Section 6.4.1. 429 o Defined the string value of an identityref in XPath expressions 430 (see Section 9.10). 432 o Clarified what unprefixed names mean in leafrefs in typedefs (see 433 Section 9.9.2). 435 o Allow identities to be derived from multiple base identities (see 436 Section 7.18 and Section 9.10). 438 o Allow enumerations and bits to be subtyped (see Section 9.6 and 439 Section 9.7). 441 o Allow leaf-lists to have default values (see Section 7.7.2). 443 o Allow non-unique values in non-configuration leaf-lists (see 444 Section 7.7). 446 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 448 o Changed the module advertisement mechanism (see Section 5.6.5). 450 o Changed the scoping rules for definitions in submodules. A 451 submodule can now reference all definitions in all submodules that 452 belong to the same module, without using the "include" statement. 454 o Added a new statement "action" that is used to define operations 455 tied to data nodes. 457 o Allow notifications to be tied to data nodes. 459 o Added a new data definition statement "anydata" (see 460 Section 7.10). 462 o Allow types empty and leafref in unions. 464 o Allow type empty in a key. 466 2. Keywords 468 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 469 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 470 "OPTIONAL" in this document are to be interpreted as described in BCP 471 14, [RFC2119]. 473 3. Terminology 475 The following terms are used within this document: 477 o action: An operation defined for a node in the data tree. 479 o anydata: A data node that can contain an unknown set of nodes that 480 can be modelled by YANG. 482 o anyxml: A data node that can contain an unknown chunk of XML data. 484 o augment: Adds new schema nodes to a previously defined schema 485 node. 487 o base type: The type from which a derived type was derived, which 488 may be either a built-in type or another derived type. 490 o built-in type: A YANG data type defined in the YANG language, such 491 as uint32 or string. 493 o choice: A schema node where only one of a number of identified 494 alternatives is valid. 496 o client: An entity that can access YANG-defined data on a server, 497 over some network management protocol. 499 o conformance: A measure of how accurately a server follows a data 500 model. 502 o container: An interior data node that exists in at most one 503 instance in the data tree. A container has no value, but rather a 504 set of child nodes. 506 o data definition statement: A statement that defines new data 507 nodes. One of container, leaf, leaf-list, list, choice, case, 508 augment, uses, anydata, and anyxml. 510 o data model: A data model describes how data is represented and 511 accessed. 513 o data node: A node in the schema tree that can be instantiated in a 514 data tree. One of container, leaf, leaf-list, list, anydata, and 515 anyxml. 517 o data tree: An instantiated tree of any data modeled with YANG, 518 e.g., configuration data, state data, combined configuration and 519 state data, RPC or action input, RPC or action output, or 520 notification. 522 o derived type: A type that is derived from a built-in type (such as 523 uint32), or another derived type. 525 o extension: An extension attaches non-YANG semantics to statements. 526 The extension statement defines new statements to express these 527 semantics. 529 o feature: A mechanism for marking a portion of the model as 530 optional. Definitions can be tagged with a feature name and are 531 only valid on servers that support that feature. 533 o grouping: A reusable set of schema nodes, which may be used 534 locally in the module and by other modules that import from it. 535 The grouping statement is not a data definition statement and, as 536 such, does not define any nodes in the schema tree. 538 o identifier: Used to identify different kinds of YANG items by 539 name. 541 o identity: A globally unique, abstract, and untyped name. 543 o instance identifier: A mechanism for identifying a particular node 544 in a data tree. 546 o interior node: Nodes within a hierarchy that are not leaf nodes. 548 o leaf: A data node that exists in at most one instance in the data 549 tree. A leaf has a value but no child nodes. 551 o leaf-list: Like the leaf node but defines a set of uniquely 552 identifiable nodes rather than a single node. Each node has a 553 value but no child nodes. 555 o list: An interior data node that may exist in multiple instances 556 in the data tree. A list has no value, but rather a set of child 557 nodes. 559 o mandatory node: A mandatory node is one of: 561 * A leaf, choice, anydata, or anyxml node with a "mandatory" 562 statement with the value "true". 564 * A list or leaf-list node with a "min-elements" statement with a 565 value greater than zero. 567 * A container node without a "presence" statement, which has at 568 least one mandatory node as a child. 570 o module: A YANG module defines a hierarchy of schema nodes. With 571 its definitions and the definitions it imports or includes from 572 elsewhere, a module is self-contained and "compilable". 574 o RPC: A Remote Procedure Call. 576 o RPC operation: A specific Remote Procedure Call. 578 o schema node: A node in the schema tree. One of action, container, 579 leaf, leaf-list, list, choice, case, rpc, input, output, 580 notification, anydata, and anyxml. 582 o schema node identifier: A mechanism for identifying a particular 583 node in the schema tree. 585 o schema tree: The definition hierarchy specified within a module. 587 o server: An entity that provides access to YANG-defined data to a 588 client, over some network management protocol. 590 o server deviation: A failure of the server to implement a module 591 faithfully. 593 o submodule: A partial module definition that contributes derived 594 types, groupings, data nodes, RPCs, actions, and notifications to 595 a module. A YANG module can be constructed from a number of 596 submodules. 598 o top-level data node: A data node where there is no other data node 599 between it and a module or submodule statement. 601 o uses: The "uses" statement is used to instantiate the set of 602 schema nodes defined in a grouping statement. The instantiated 603 nodes may be refined and augmented to tailor them to any specific 604 needs. 606 The following terms are defined in [RFC6241]: 608 o configuration data 610 o configuration datastore: a configuration datastore is an 611 instantiated data tree with configuration data 613 o datastore: an instantiated data tree 615 o running configuration datastore 617 o state data 619 4. YANG Overview 621 This non-normative section is intended to give a high-level overview 622 of YANG to first-time readers. 624 4.1. Functional Overview 626 YANG is a language originally designed to model data for the NETCONF 627 protocol. A YANG module defines a hierarchy of data that can be used 628 for NETCONF-based operations, including configuration, state data, 629 Remote Procedure Calls (RPCs), and notifications. This allows a 630 complete description of all data sent between a NETCONF client and 631 server. Although out of scope for this specification, YANG can also 632 be used with other protocols than NETCONF. 634 YANG models the hierarchical organization of data as a tree in which 635 each node has a name, and either a value or a set of child nodes. 636 YANG provides clear and concise descriptions of the nodes, as well as 637 the interaction between those nodes. 639 YANG structures data models into modules and submodules. A module 640 can import data from other external modules, and include data from 641 submodules. The hierarchy can be augmented, allowing one module to 642 add data nodes to the hierarchy defined in another module. This 643 augmentation can be conditional, with new nodes appearing only if 644 certain conditions are met. 646 YANG models can describe constraints to be enforced on the data, 647 restricting the appearance or value of nodes based on the presence or 648 value of other nodes in the hierarchy. These constraints are 649 enforceable by either the client or the server, and valid content 650 MUST abide by them. 652 YANG defines a set of built-in types, and has a type mechanism 653 through which additional types may be defined. Derived types can 654 restrict their base type's set of valid values using mechanisms like 655 range or pattern restrictions that can be enforced by clients or 656 servers. They can also define usage conventions for use of the 657 derived type, such as a string-based type that contains a host name. 659 YANG permits the definition of reusable groupings of nodes. The 660 instantiation of these groupings can refine or augment the nodes, 661 allowing it to tailor the nodes to its particular needs. Derived 662 types and groupings can be defined in one module and used in either 663 the same module or in another module that imports it. 665 YANG data hierarchy constructs include defining lists where list 666 entries are identified by keys that distinguish them from each other. 667 Such lists may be defined as either sorted by user or automatically 668 sorted by the system. For user-sorted lists, operations are defined 669 for manipulating the order of the list entries. 671 YANG modules can be translated into an equivalent XML syntax called 672 YANG Independent Notation (YIN) (Section 13), allowing applications 673 using XML parsers and Extensible Stylesheet Language Transformations 674 (XSLT) scripts to operate on the models. The conversion from YANG to 675 YIN is lossless, so content in YIN can be round-tripped back into 676 YANG. 678 YANG strikes a balance between high-level data modeling and low-level 679 bits-on-the-wire encoding. The reader of a YANG module can see the 680 high-level view of the data model while understanding how the data 681 will be encoded on-the-wire. 683 YANG is an extensible language, allowing extension statements to be 684 defined by standards bodies, vendors, and individuals. The statement 685 syntax allows these extensions to coexist with standard YANG 686 statements in a natural way, while extensions in a YANG module stand 687 out sufficiently for the reader to notice them. 689 YANG resists the tendency to solve all possible problems, limiting 690 the problem space to allow expression of data models for network 691 management protocols such as NETCONF, not arbitrary XML documents or 692 arbitrary data models. 694 To the extent possible, YANG maintains compatibility with Simple 695 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 696 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 697 can be automatically translated into YANG modules for read-only 698 access [RFC6643]. However, YANG is not concerned with reverse 699 translation from YANG to SMIv2. 701 4.2. Language Overview 703 This section introduces some important constructs used in YANG that 704 will aid in the understanding of the language specifics in later 705 sections. 707 4.2.1. Modules and Submodules 709 A module contains three types of statements: module-header 710 statements, revision statements, and definition statements. The 711 module header statements describe the module and give information 712 about the module itself, the revision statements give information 713 about the history of the module, and the definition statements are 714 the body of the module where the data model is defined. 716 A server may implement a number of modules, allowing multiple views 717 of the same data, or multiple views of disjoint subsections of the 718 server's data. Alternatively, the server may implement only one 719 module that defines all available data. 721 A module may be divided into submodules, based on the needs of the 722 module owner. The external view remains that of a single module, 723 regardless of the presence or size of its submodules. 725 The "import" statement allows a module or submodule to reference 726 material defined in other modules. 728 The "include" statement is used by a module to incorporate the 729 contents of its submodules into the module. 731 4.2.2. Data Modeling Basics 733 YANG defines four main types of data nodes for data modeling. In 734 each of the following subsections, the examples show the YANG syntax 735 as well as a corresponding XML encoding. 737 4.2.2.1. Leaf Nodes 739 A leaf instance contains simple data like an integer or a string. It 740 has exactly one value of a particular type and no child nodes. 742 YANG Example: 744 leaf host-name { 745 type string; 746 description 747 "Hostname for this system"; 748 } 750 XML Encoding Example: 752 my.example.com 754 The "leaf" statement is covered in Section 7.6. 756 4.2.2.2. Leaf-List Nodes 758 A leaf-list defines a sequence of values of a particular type. 760 YANG Example: 762 leaf-list domain-search { 763 type string; 764 description 765 "List of domain names to search"; 766 } 768 XML Encoding Example: 770 high.example.com 771 low.example.com 772 everywhere.example.com 774 The "leaf-list" statement is covered in Section 7.7. 776 4.2.2.3. Container Nodes 778 A container is used to group related nodes in a subtree. A container 779 has only child nodes and no value. A container may contain any 780 number of child nodes of any type (leafs, lists, containers, leaf- 781 lists, and actions). 783 YANG Example: 785 container system { 786 container login { 787 leaf message { 788 type string; 789 description 790 "Message given at start of login session"; 791 } 792 } 793 } 795 XML Encoding Example: 797 798 799 Good morning 800 801 803 The "container" statement is covered in Section 7.5. 805 4.2.2.4. List Nodes 807 A list defines a sequence of list entries. Each entry is like a 808 structure or a record instance, and is uniquely identified by the 809 values of its key leafs. A list can define multiple key leafs and 810 may contain any number of child nodes of any type (including leafs, 811 lists, containers etc.). 813 YANG Example: 815 list user { 816 key "name"; 817 leaf name { 818 type string; 819 } 820 leaf full-name { 821 type string; 822 } 823 leaf class { 824 type string; 825 } 826 } 828 XML Encoding Example: 830 831 glocks 832 Goldie Locks 833 intruder 834 835 836 snowey 837 Snow White 838 free-loader 839 840 841 rzell 842 Rapun Zell 843 tower 844 846 The "list" statement is covered in Section 7.8. 848 4.2.2.5. Example Module 850 These statements are combined to define the module: 852 // Contents of "example-system.yang" 853 module example-system { 854 yang-version 1.1; 855 namespace "urn:example:system"; 856 prefix "sys"; 858 organization "Example Inc."; 859 contact "joe@example.com"; 860 description 861 "The module for entities implementing the Example system."; 863 revision 2007-06-09 { 864 description "Initial revision."; 865 } 867 container system { 868 leaf host-name { 869 type string; 870 description 871 "Hostname for this system"; 872 } 874 leaf-list domain-search { 875 type string; 876 description 877 "List of domain names to search"; 878 } 880 container login { 881 leaf message { 882 type string; 883 description 884 "Message given at start of login session"; 885 } 887 list user { 888 key "name"; 889 leaf name { 890 type string; 891 } 892 leaf full-name { 893 type string; 894 } 895 leaf class { 896 type string; 897 } 898 } 899 } 900 } 901 } 903 4.2.3. State Data 905 YANG can model state data, as well as configuration data, based on 906 the "config" statement. When a node is tagged with "config false", 907 its subhierarchy is flagged as state data. In NETCONF, state data is 908 reported using the operation, not the operation. 909 Parent containers, lists, and key leafs are reported also, giving the 910 context for the state data. 912 In this example, two leafs are defined for each interface, a 913 configured speed and an observed speed. The observed speed is not 914 configuration, so it can be returned with NETCONF operations, 915 but not with operations. The observed speed is not 916 configuration data, and it cannot be manipulated using . 918 list interface { 919 key "name"; 921 leaf name { 922 type string; 923 } 924 leaf speed { 925 type enumeration { 926 enum 10m; 927 enum 100m; 928 enum auto; 929 } 930 } 931 leaf observed-speed { 932 type uint32; 933 config false; 934 } 935 } 937 4.2.4. Built-In Types 939 YANG has a set of built-in types, similar to those of many 940 programming languages, but with some differences due to special 941 requirements from the management domain. The following table 942 summarizes the built-in types discussed in Section 9: 944 +---------------------+-------------------------------------+ 945 | Name | Description | 946 +---------------------+-------------------------------------+ 947 | binary | Any binary data | 948 | bits | A set of bits or flags | 949 | boolean | "true" or "false" | 950 | decimal64 | 64-bit signed decimal number | 951 | empty | A leaf that does not have any value | 952 | enumeration | Enumerated strings | 953 | identityref | A reference to an abstract identity | 954 | instance-identifier | References a data tree node | 955 | int8 | 8-bit signed integer | 956 | int16 | 16-bit signed integer | 957 | int32 | 32-bit signed integer | 958 | int64 | 64-bit signed integer | 959 | leafref | A reference to a leaf instance | 960 | string | Human-readable string | 961 | uint8 | 8-bit unsigned integer | 962 | uint16 | 16-bit unsigned integer | 963 | uint32 | 32-bit unsigned integer | 964 | uint64 | 64-bit unsigned integer | 965 | union | Choice of member types | 966 +---------------------+-------------------------------------+ 968 The "type" statement is covered in Section 7.4. 970 4.2.5. Derived Types (typedef) 972 YANG can define derived types from base types using the "typedef" 973 statement. A base type can be either a built-in type or a derived 974 type, allowing a hierarchy of derived types. 976 A derived type can be used as the argument for the "type" statement. 978 YANG Example: 980 typedef percent { 981 type uint8 { 982 range "0 .. 100"; 983 } 984 } 986 leaf completed { 987 type percent; 988 } 990 XML Encoding Example: 992 20 994 The "typedef" statement is covered in Section 7.3. 996 4.2.6. Reusable Node Groups (grouping) 998 Groups of nodes can be assembled into reusable collections using the 999 "grouping" statement. A grouping defines a set of nodes that are 1000 instantiated with the "uses" statement: 1002 grouping target { 1003 leaf address { 1004 type inet:ip-address; 1005 description "Target IP address"; 1006 } 1007 leaf port { 1008 type inet:port-number; 1009 description "Target port number"; 1010 } 1011 } 1013 container peer { 1014 container destination { 1015 uses target; 1016 } 1017 } 1019 XML Encoding Example: 1021 1022 1023
192.0.2.1
1024 830 1025 1026 1028 The grouping can be refined as it is used, allowing certain 1029 statements to be overridden. In this example, the description is 1030 refined: 1032 container connection { 1033 container source { 1034 uses target { 1035 refine "address" { 1036 description "Source IP address"; 1037 } 1038 refine "port" { 1039 description "Source port number"; 1040 } 1041 } 1042 } 1043 container destination { 1044 uses target { 1045 refine "address" { 1046 description "Destination IP address"; 1047 } 1048 refine "port" { 1049 description "Destination port number"; 1050 } 1051 } 1052 } 1053 } 1055 The "grouping" statement is covered in Section 7.12. 1057 4.2.7. Choices 1059 YANG allows the data model to segregate incompatible nodes into 1060 distinct choices using the "choice" and "case" statements. The 1061 "choice" statement contains a set of "case" statements that define 1062 sets of schema nodes that cannot appear together. Each "case" may 1063 contain multiple nodes, but each node may appear in only one "case" 1064 under a "choice". 1066 When a node from one case is created in the data tree, all nodes from 1067 all other cases are implicitly deleted. The server handles the 1068 enforcement of the constraint, preventing incompatibilities from 1069 existing in the configuration. 1071 The choice and case nodes appear only in the schema tree but not in 1072 the data tree. The additional levels of hierarchy are not needed 1073 beyond the conceptual schema. 1075 YANG Example: 1077 container food { 1078 choice snack { 1079 case sports-arena { 1080 leaf pretzel { 1081 type empty; 1082 } 1083 leaf beer { 1084 type empty; 1085 } 1086 } 1087 case late-night { 1088 leaf chocolate { 1089 type enumeration { 1090 enum dark; 1091 enum milk; 1092 enum first-available; 1093 } 1094 } 1095 } 1096 } 1097 } 1099 XML Encoding Example: 1101 1102 1103 1104 1106 The "choice" statement is covered in Section 7.9. 1108 4.2.8. Extending Data Models (augment) 1110 YANG allows a module to insert additional nodes into data models, 1111 including both the current module (and its submodules) or an external 1112 module. This is useful for example for vendors to add vendor- 1113 specific parameters to standard data models in an interoperable way. 1115 The "augment" statement defines the location in the data model 1116 hierarchy where new nodes are inserted, and the "when" statement 1117 defines the conditions when the new nodes are valid. 1119 YANG Example: 1121 augment /system/login/user { 1122 when "class != 'wheel'"; 1123 leaf uid { 1124 type uint16 { 1125 range "1000 .. 30000"; 1126 } 1127 } 1128 } 1130 This example defines a "uid" node that only is valid when the user's 1131 "class" is not "wheel". 1133 If a module augments another module, the XML encoding of the data 1134 will reflect the prefix of the augmenting module. For example, if 1135 the above augmentation were in a module with prefix "other", the XML 1136 would look like: 1138 XML Encoding Example: 1140 1141 alicew 1142 Alice N. Wonderland 1143 drop-out 1144 1024 1145 1147 The "augment" statement is covered in Section 7.17. 1149 4.2.9. Operation Definitions 1151 YANG allows the definition of operations. The operations' name, 1152 input parameters, and output parameters are modeled using YANG data 1153 definition statements. Operations on the top-level in a module are 1154 defined with the "rpc" statement. Operations can also be tied to a 1155 data node. Such operations are defined with the "action" statement. 1157 YANG Example: 1159 rpc activate-software-image { 1160 input { 1161 leaf image-name { 1162 type string; 1163 } 1164 } 1165 output { 1166 leaf status { 1167 type string; 1168 } 1169 } 1170 } 1172 NETCONF XML Example: 1174 1176 1177 example-fw-2.3 1178 1179 1181 1183 1184 The image example-fw-2.3 is being installed. 1185 1186 1188 YANG Example: 1190 list interface { 1191 key "name"; 1193 leaf name { 1194 type string; 1195 } 1197 action ping { 1198 input { 1199 leaf destination { 1200 type inet:ip-address; 1201 } 1202 } 1203 output { 1204 leaf packet-loss { 1205 type uint8; 1206 } 1207 } 1208 } 1209 } 1211 NETCONF XML Example: 1213 1215 1216 1217 eth1 1218 1219 192.0.2.1 1220 1221 1222 1223 1225 1228 60 1229 1231 The "rpc" statement is covered in Section 7.14, and the "action" 1232 statement in Section 7.15. 1234 4.2.10. Notification Definitions 1236 YANG allows the definition of notifications. YANG data definition 1237 statements are used to model the content of the notification. 1239 YANG Example: 1241 notification link-failure { 1242 description 1243 "A link failure has been detected"; 1244 leaf if-name { 1245 type leafref { 1246 path "/interface/name"; 1247 } 1248 } 1249 leaf if-admin-status { 1250 type admin-status; 1251 } 1252 leaf if-oper-status { 1253 type oper-status; 1254 } 1255 } 1257 NETCONF XML Example: 1259 1261 2007-09-01T10:00:00Z 1262 1263 so-1/2/3.0 1264 up 1265 down 1266 1267 1269 The "notification" statement is covered in Section 7.16. 1271 5. Language Concepts 1273 5.1. Modules and Submodules 1275 The module is the base unit of definition in YANG. A module defines 1276 a single data model. A module can define a complete, cohesive model, 1277 or augment an existing data model with additional nodes. 1279 Submodules are partial modules that contribute definitions to a 1280 module. A module may include any number of submodules, but each 1281 submodule may belong to only one module. 1283 Developers of YANG modules and submodules are RECOMMENDED to choose 1284 names for their modules that will have a low probability of colliding 1285 with standard or other enterprise modules, e.g., by using the 1286 enterprise or organization name as a prefix for the module name. 1287 Within a server, all module names MUST be unique. 1289 A module uses the "include" statement to include all its submodules, 1290 and the "import" statement to reference external modules. Similarly, 1291 a submodule uses the "import" statement to reference other modules. 1293 For backward compatibility with YANG version 1, a submodule is 1294 allowed to use the "include" statement to reference other submodules 1295 within its module, but this is not necessary in YANG version 1.1. A 1296 submodule can reference any definition in the module it belongs to 1297 and in all submodules included by the module. 1299 A module or submodule MUST NOT include submodules from other modules, 1300 and a submodule MUST NOT import its own module. 1302 The import and include statements are used to make definitions 1303 available from other modules: 1305 o For a module or submodule to reference definitions in an external 1306 module, the external module MUST be imported. 1308 o A module MUST include all its submodules. 1310 o A module or submodule belonging to that module can reference 1311 definitions in the module and all submodules included by the 1312 module. 1314 There MUST NOT be any circular chains of imports. For example, if 1315 module "a" imports module "b", "b" cannot import "a". 1317 When a definition in an external module is referenced, a locally 1318 defined prefix MUST be used, followed by ":", and then the external 1319 identifier. References to definitions in the local module MAY use 1320 the prefix notation. Since built-in data types do not belong to any 1321 module and have no prefix, references to built-in data types (e.g., 1322 int32) cannot use the prefix notation. The syntax for a reference to 1323 a definition is formally defined by the rule "identifier-ref" in 1324 Section 14. 1326 5.1.1. Import and Include by Revision 1328 Published modules evolve independently over time. In order to allow 1329 for this evolution, modules need to be imported using specific 1330 revisions. When a module is written, it uses the current revisions 1331 of other modules, based on what is available at the time. As future 1332 revisions of the imported modules are published, the importing module 1333 is unaffected and its contents are unchanged. When the author of the 1334 module is prepared to move to the most recently published revision of 1335 an imported module, the module is republished with an updated 1336 "import" statement. By republishing with the new revision, the 1337 authors explicitly indicate their acceptance of any changes in the 1338 imported module. 1340 For submodules, the issue is related but simpler. A module or 1341 submodule that includes submodules needs to specify the revision of 1342 the included submodules. If a submodule changes, any module or 1343 submodule that includes it needs to be updated. 1345 For example, module "b" imports module "a". 1347 module a { 1348 yang-version 1.1; 1349 namespace "urn:example:a"; 1350 prefix "a"; 1352 revision 2008-01-01 { ... } 1353 grouping a { 1354 leaf eh { .... } 1355 } 1356 } 1358 module b { 1359 yang-version 1.1; 1360 namespace "urn:example:b"; 1361 prefix "b"; 1363 import a { 1364 prefix "p"; 1365 revision-date 2008-01-01; 1366 } 1368 container bee { 1369 uses p:a; 1370 } 1371 } 1373 When the author of "a" publishes a new revision, the changes may not 1374 be acceptable to the author of "b". If the new revision is 1375 acceptable, the author of "b" can republish with an updated revision 1376 in the "import" statement. 1378 5.1.2. Module Hierarchies 1380 YANG allows modeling of data in multiple hierarchies, where data may 1381 have more than one top-level node. Models that have multiple top- 1382 level nodes are sometimes convenient, and are supported by YANG. 1384 5.1.2.1. NETCONF XML Encoding 1386 NETCONF is capable of carrying any XML content as the payload in the 1387 and elements. The top-level nodes of YANG modules 1388 are encoded as child elements, in any order, within these elements. 1389 This encapsulation guarantees that the corresponding NETCONF messages 1390 are always well-formed XML documents. 1392 For example: 1394 module example-config { 1395 yang-version 1.1; 1396 namespace "urn:example:config"; 1397 prefix "co"; 1399 container system { ... } 1400 container routing { ... } 1401 } 1403 could be encoded in NETCONF as: 1405 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1423 5.2. File Layout 1425 YANG modules and submodules are typically stored in files, one module 1426 or submodule per file. The name of the file SHOULD be of the form: 1428 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1430 YANG parsers can find imported modules and included submodules via 1431 this convention. 1433 5.3. XML Namespaces 1435 All YANG definitions are specified within a module that is bound to a 1436 particular XML namespace [XML-NAMES], which is a globally unique URI 1437 [RFC3986]. A NETCONF client or server uses the namespace during XML 1438 encoding of data. 1440 XML namespaces for modules published in RFC streams [RFC4844] MUST be 1441 assigned by IANA, see section 14 in [RFC6020]. 1443 XML namespaces for private modules are assigned by the organization 1444 owning the module without a central registry. Namespace URIs MUST be 1445 chosen so they cannot collide with standard or other enterprise 1446 namespaces, for example by using the enterprise or organization name 1447 in the namespace. 1449 The "namespace" statement is covered in Section 7.1.3. 1451 5.3.1. YANG XML Namespace 1453 YANG defines an XML namespace for NETCONF operations, 1454 content, and the element. The name of this 1455 namespace is "urn:ietf:params:xml:ns:yang:1". 1457 5.4. Resolving Grouping, Type, and Identity Names 1459 Grouping, type, and identity names are resolved in the context in 1460 which they are defined, rather than the context in which they are 1461 used. Users of groupings, typedefs, and identities are not required 1462 to import modules or include submodules to satisfy all references 1463 made by the original definition. This behaves like static scoping in 1464 a conventional programming language. 1466 For example, if a module defines a grouping in which a type is 1467 referenced, when the grouping is used in a second module, the type is 1468 resolved in the context of the original module, not the second 1469 module. There is no worry over conflicts if both modules define the 1470 type, since there is no ambiguity. 1472 5.5. Nested Typedefs and Groupings 1474 Typedefs and groupings may appear nested under many YANG statements, 1475 allowing these to be lexically scoped by the hierarchy under which 1476 they appear. This allows types and groupings to be defined near 1477 where they are used, rather than placing them at the top level of the 1478 hierarchy. The close proximity increases readability. 1480 Scoping also allows types to be defined without concern for naming 1481 conflicts between types in different submodules. Type names can be 1482 specified without adding leading strings designed to prevent name 1483 collisions within large modules. 1485 Finally, scoping allows the module author to keep types and groupings 1486 private to their module or submodule, preventing their reuse. Since 1487 only top-level types and groupings (i.e., those appearing as 1488 substatements to a module or submodule statement) can be used outside 1489 the module or submodule, the developer has more control over what 1490 pieces of their module are presented to the outside world, supporting 1491 the need to hide internal information and maintaining a boundary 1492 between what is shared with the outside world and what is kept 1493 private. 1495 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1496 type or grouping cannot be defined if a higher level in the schema 1497 hierarchy has a definition with a matching identifier. 1499 A reference to an unprefixed type or grouping, or one which uses the 1500 prefix of the current module, is resolved by locating the matching 1501 "typedef" or "grouping" statement among the immediate substatements 1502 of each ancestor statement. 1504 5.6. Conformance 1506 Conformance is a measure of how accurately a server follows the 1507 model. Generally speaking, servers are responsible for implementing 1508 the model faithfully, allowing applications to treat servers which 1509 implement the model identically. Deviations from the model can 1510 reduce the utility of the model and increase fragility of 1511 applications that use it. 1513 YANG modelers have three mechanisms for conformance: 1515 o the basic behavior of the model 1517 o optional features that are part of the model 1519 o deviations from the model 1520 We will consider each of these in sequence. 1522 5.6.1. Basic Behavior 1524 The model defines a contract between a YANG-based client and server, 1525 which allows both parties to have faith the other knows the syntax 1526 and semantics behind the modeled data. The strength of YANG lies in 1527 the strength of this contract. 1529 5.6.2. Optional Features 1531 In many models, the modeler will allow sections of the model to be 1532 conditional. The server controls whether these conditional portions 1533 of the model are supported or valid for that particular server. 1535 For example, a syslog data model may choose to include the ability to 1536 save logs locally, but the modeler will realize that this is only 1537 possible if the server has local storage. If there is no local 1538 storage, an application should not tell the server to save logs. 1540 YANG supports this conditional mechanism using a construct called 1541 "feature". Features give the modeler a mechanism for making portions 1542 of the module conditional in a manner that is controlled by the 1543 server. The model can express constructs that are not universally 1544 present in all servers. These features are included in the model 1545 definition, allowing a consistent view and allowing applications to 1546 learn which features are supported and tailor their behavior to the 1547 server. 1549 A module may declare any number of features, identified by simple 1550 strings, and may make portions of the module optional based on those 1551 features. If the server supports a feature, then the corresponding 1552 portions of the module are valid for that server. If the server 1553 doesn't support the feature, those parts of the module are not valid, 1554 and applications should behave accordingly. 1556 Features are defined using the "feature" statement. Definitions in 1557 the module that are conditional to the feature are noted by the 1558 "if-feature" statement. 1560 Further details are available in Section 7.20.1. 1562 5.6.3. Deviations 1564 In an ideal world, all servers would be required to implement the 1565 model exactly as defined, and deviations from the model would not be 1566 allowed. But in the real world, servers are often not able or 1567 designed to implement the model as written. For YANG-based 1568 automation to deal with these server deviations, a mechanism must 1569 exist for servers to inform applications of the specifics of such 1570 deviations. 1572 For example, a BGP module may allow any number of BGP peers, but a 1573 particular server may only support 16 BGP peers. Any application 1574 configuring the 17th peer will receive an error. While an error may 1575 suffice to let the application know it cannot add another peer, it 1576 would be far better if the application had prior knowledge of this 1577 limitation and could prevent the user from starting down the path 1578 that could not succeed. 1580 Server deviations are declared using the "deviation" statement, which 1581 takes as its argument a string that identifies a node in the schema 1582 tree. The contents of the statement details the manner in which the 1583 server implementation deviates from the contract as defined in the 1584 module. 1586 Further details are available in Section 7.20.3. 1588 5.6.4. Implementing a Module 1590 A server implements a module if it implements the module's data 1591 nodes, rpcs, actions, notifications, and deviations. 1593 A server MUST NOT implement more than one revision of a module. 1595 If a server implements a module A that imports a module B, and A uses 1596 any node from B in an "augment" or "path" statement that the server 1597 supports, then the server MUST implement a revision of module B that 1598 has these nodes defined. This is regardless of if module B is 1599 imported by revision or not. 1601 If a server implements a module A that imports a module C without 1602 specifying the revision date of module C, and the server does not 1603 implement C (e.g., if C only defines some typedefs), the server MUST 1604 list module C in the "/modules-state/module" list from 1605 "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set 1606 the leaf "conformance-type" to "import" for this module. 1608 If a server lists a module C in the "/modules-state/module" list from 1609 "ietf-yang-library", and there are other modules Ms listed that 1610 import C without specifying the revision date of module C, the server 1611 MUST use the definitions from the most recent revision of C listed 1612 for modules Ms. 1614 The reason for these rules is that clients need to be able to know 1615 the exact data model structure and types of all leafs and leaf-lists 1616 implemented in a server. 1618 For example, with these modules: 1620 module a { 1621 yang-version 1.1; 1622 namespace "urn:example:a"; 1623 prefix "a"; 1625 import b { 1626 revision-date 2015-01-01; 1627 } 1628 import c; 1630 revision 2015-01-01; 1632 feature foo; 1634 augment "/b:x" { 1635 if-feature foo; 1636 leaf y { 1637 type b:myenum; 1638 } 1639 } 1641 container a { 1642 leaf x { 1643 type c:bar; 1644 } 1645 } 1646 } 1648 module b { 1649 yang-version 1.1; 1650 namespace "urn:example:b"; 1651 prefix "b"; 1653 revision 2015-04-04; 1654 revision 2015-01-01; 1656 typedef myenum { 1657 type enumeration { 1658 enum zero; // added in 2015-01-01 1659 enum one; // added in 2015-04-04 1660 } 1661 } 1662 container x { // added in 2015-01-01 1663 container y; // added in 2015-04-04 1664 } 1665 } 1667 module c { 1668 yang-version 1.1; 1669 namespace "urn:example:c"; 1670 prefix "c"; 1672 revision 2015-03-03; 1673 revision 2015-02-02; 1675 typedef bar { 1676 ... 1677 } 1678 } 1680 A server that implements revision "2015-01-01" of module "a" and 1681 supports feature "foo" can implement revision "2015-01-01" or 1682 "2015-04-04" of module "b". Since "b" was imported by revision, the 1683 type of leaf "/b:x/a:y" is the same regardless of which revision of 1684 "b" the server implements. 1686 A server that implements module "a", but does not support feature 1687 "foo" does not have to implement module "b". 1689 A server that implements revision "2015-01-01" of module "a" must 1690 pick a revision of module "c", and list it in the "/modules-state/ 1691 module" list from "ietf-yang-library". 1693 The following XML encoding example shows valid data for the 1694 "/modules-state/module" list for a server that implements module "a": 1696 1698 ee1ecb017370cafd 1699 1700 a 1701 2015-01-01 1702 urn:example:a 1703 foo 1704 implement 1705 1706 1707 b 1708 2015-04-04 1709 urn:example:b 1710 implement 1711 1712 1713 c 1714 2015-02-02 1715 urn:example:c 1716 import 1717 1718 1720 5.6.5. Announcing Conformance Information in NETCONF 1722 This document defines the following mechanism for announcing 1723 conformance information. Other mechanisms may be defined by future 1724 specifications. 1726 A NETCONF server announces the modules it implements by implementing 1727 the YANG module "ietf-yang-library" defined in 1728 [I-D.ietf-netconf-yang-library], and listing all implemented modules 1729 in the "/modules-state/module" list. 1731 The server also advertises the following capability in the 1732 message (line-breaks and whitespaces are used for formatting reasons 1733 only): 1735 urn:ietf:params:netconf:capability:yang-library:1.0? 1736 module-set-id= 1738 The parameter "module-set-id" has the same value as the leaf 1739 "/modules-state/module-set-id" from "ietf-yang-library". This 1740 parameter MUST be present. 1742 With this mechanism, a client can cache the supported modules for a 1743 server, and only update the cache if the "module-set-id" value in the 1744 message changes. 1746 5.7. Datastore Modification 1748 Data models may allow the server to alter the configuration datastore 1749 in ways not explicitly directed via network management protocol 1750 messages. For example, a data model may define leafs that are 1751 assigned system-generated values when the client does not provide 1752 one. A formal mechanism for specifying the circumstances where these 1753 changes are allowed is out of scope for this specification. 1755 6. YANG Syntax 1757 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1758 languages like C and C++. This C-like syntax was chosen specifically 1759 for its readability, since YANG values the time and effort of the 1760 readers of models above those of modules writers and YANG tool-chain 1761 developers. This section introduces the YANG syntax. 1763 YANG modules use the UTF-8 [RFC3629] character encoding. 1765 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1766 [ISO.10646] characters, including tab, carriage return, and line feed 1767 but excluding the other C0 control characters, the surrogate blocks, 1768 and the noncharacters. The character syntax is formally defined by 1769 the rule "yang-char" in Section 14. 1771 6.1. Lexical Tokenization 1773 YANG modules are parsed as a series of tokens. This section details 1774 the rules for recognizing tokens from an input stream. YANG 1775 tokenization rules are both simple and powerful. The simplicity is 1776 driven by a need to keep the parsers easy to implement, while the 1777 power is driven by the fact that modelers need to express their 1778 models in readable formats. 1780 6.1.1. Comments 1782 Comments are C++ style. A single line comment starts with "//" and 1783 ends at the end of the line. A block comment is enclosed within "/*" 1784 and "*/". 1786 Note that inside a quoted string (Section 6.1.3), these character 1787 pairs are never interpreted as the start or end of a comment. 1789 6.1.2. Tokens 1791 A token in YANG is either a keyword, a string, a semicolon (";"), or 1792 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1793 is either one of the YANG keywords defined in this document, or a 1794 prefix identifier, followed by ":", followed by a language extension 1795 keyword. Keywords are case sensitive. See Section 6.2 for a formal 1796 definition of identifiers. 1798 6.1.3. Quoting 1800 If a string contains any space, tab, or newline characters, a single 1801 or double quote character, a semicolon (";"), braces ("{" or "}"), or 1802 comment sequences ("//", "/*", or "*/"), then it MUST be enclosed 1803 within double or single quotes. 1805 Within an unquoted string, every character is preserved. Note that 1806 this means that the backslash character does not have any special 1807 meaning in an unquoted string. 1809 If a double-quoted string contains a line break followed by space or 1810 tab characters that are used to indent the text according to the 1811 layout in the YANG file, this leading whitespace is stripped from the 1812 string, up to and including the column of the double quote character, 1813 or to the first non-whitespace character, whichever occurs first. In 1814 this process, a tab character is treated as 8 space characters. 1816 If a double-quoted string contains space or tab characters before a 1817 line break, this trailing whitespace is stripped from the string. 1819 A single-quoted string (enclosed within ' ') preserves each character 1820 within the quotes. A single quote character cannot occur in a 1821 single-quoted string, even when preceded by a backslash. 1823 Within a double-quoted string (enclosed within " "), a backslash 1824 character introduces a special character, which depends on the 1825 character that immediately follows the backslash: 1827 \n new line 1828 \t a tab character 1829 \" a double quote 1830 \\ a single backslash 1832 It is an error if any other character follows the backslash 1833 character. 1835 If a quoted string is followed by a plus character ("+"), followed by 1836 another quoted string, the two strings are concatenated into one 1837 string, allowing multiple concatenations to build one string. 1838 Whitespace trimming is done before substitution of backslash-escaped 1839 characters in double-quoted strings. Concatenation is performed as 1840 the last step. 1842 6.1.3.1. Quoting Examples 1844 The following strings are equivalent: 1846 hello 1847 "hello" 1848 'hello' 1849 "hel" + "lo" 1850 'hel' + "lo" 1852 The following examples show some special strings: 1854 "\"" - string containing a double quote 1855 '"' - string containing a double quote 1856 "\n" - string containing a new line character 1857 '\n' - string containing a backslash followed 1858 by the character n 1860 The following examples show some illegal strings: 1862 '''' - a single-quoted string cannot contain single quotes 1863 """ - a double quote must be escaped in a double-quoted string 1865 The following strings are equivalent: 1867 "first line 1868 second line" 1870 "first line\n" + " second line" 1872 6.2. Identifiers 1874 Identifiers are used to identify different kinds of YANG items by 1875 name. Each identifier starts with an uppercase or lowercase ASCII 1876 letter or an underscore character, followed by zero or more ASCII 1877 letters, digits, underscore characters, hyphens, and dots. 1878 Implementations MUST support identifiers up to 64 characters in 1879 length, and MAY support longer identifiers. Identifiers are case 1880 sensitive. The identifier syntax is formally defined by the rule 1881 "identifier" in Section 14. Identifiers can be specified as quoted 1882 or unquoted strings. 1884 6.2.1. Identifiers and Their Namespaces 1886 Each identifier is valid in a namespace that depends on the type of 1887 the YANG item being defined. All identifiers defined in a namespace 1888 MUST be unique. 1890 o All module and submodule names share the same global module 1891 identifier namespace. 1893 o All extension names defined in a module and its submodules share 1894 the same extension identifier namespace. 1896 o All feature names defined in a module and its submodules share the 1897 same feature identifier namespace. 1899 o All identity names defined in a module and its submodules share 1900 the same identity identifier namespace. 1902 o All derived type names defined within a parent node or at the top 1903 level of the module or its submodules share the same type 1904 identifier namespace. This namespace is scoped to all descendant 1905 nodes of the parent node or module. This means that any 1906 descendent node may use that typedef, and it MUST NOT define a 1907 typedef with the same name. 1909 o All grouping names defined within a parent node or at the top 1910 level of the module or its submodules share the same grouping 1911 identifier namespace. This namespace is scoped to all descendant 1912 nodes of the parent node or module. This means that any 1913 descendent node may use that grouping, and it MUST NOT define a 1914 grouping with the same name. 1916 o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 1917 notifications, anydatas, and anyxmls defined (directly or through 1918 a uses statement) within a parent node or at the top level of the 1919 module or its submodules share the same identifier namespace. 1920 This namespace is scoped to the parent node or module, unless the 1921 parent node is a case node. In that case, the namespace is scoped 1922 to the closest ancestor node that is not a case or choice node. 1924 o All cases within a choice share the same case identifier 1925 namespace. This namespace is scoped to the parent choice node. 1927 Forward references are allowed in YANG. 1929 6.3. Statements 1931 A YANG module contains a sequence of statements. Each statement 1932 starts with a keyword, followed by zero or one argument, followed 1933 either by a semicolon (";") or a block of substatements enclosed 1934 within braces ("{ }"): 1936 statement = keyword [argument] (";" / "{" *statement "}") 1938 The argument is a string, as defined in Section 6.1.2. 1940 6.3.1. Language Extensions 1942 A module can introduce YANG extensions by using the "extension" 1943 keyword (see Section 7.19). The extensions can be imported by other 1944 modules with the "import" statement (see Section 7.1.5). When an 1945 imported extension is used, the extension's keyword MUST be qualified 1946 using the prefix with which the extension's module was imported. If 1947 an extension is used in the module where it is defined, the 1948 extension's keyword MUST be qualified with the module's prefix. 1950 The processing of extensions depends on whether support for those 1951 extensions is claimed for a given YANG parser or the tool set in 1952 which it is embedded. An unsupported extension, appearing in a YANG 1953 module as an unknown-statement (see Section 14) MAY be ignored in its 1954 entirety. Any supported extension MUST be processed in accordance 1955 with the specification governing that extension. 1957 Care must be taken when defining extensions so that modules that use 1958 the extensions are meaningful also for applications that do not 1959 support the extensions. 1961 6.4. XPath Evaluations 1963 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 1964 for specifying many inter-node references and dependencies. An 1965 implementation is not required to implement an XPath interpreter, but 1966 MUST ensure that the requirements encoded in the data model are 1967 enforced. The manner of enforcement is an implementation decision. 1968 The XPath expressions MUST be syntactically correct, and all prefixes 1969 used MUST be present in the XPath context (see Section 6.4.1). An 1970 implementation may choose to implement them by hand, rather than 1971 using the XPath expression directly. 1973 The data model used in the XPath expressions is the same as that used 1974 in XPath 1.0 [XPATH], with the same extension for root node children 1975 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 1976 that the root node may have any number of element nodes as its 1977 children. 1979 The data tree has no concept of document order. An implementation 1980 needs to choose some document order but how it is done is an 1981 implementation decision. This means that XPath expressions in YANG 1982 modules SHOULD NOT rely on any specific document order. 1984 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 1985 values, see Section 3.5 in [XPATH]. This means that some values of 1986 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 1987 cannot be exactly represented in XPath expressions. Therefore, due 1988 caution should be exercised when using nodes with 64-bit numeric 1989 values in XPath expressions. In particular, numerical comparisons 1990 involving equality may yield unexpected results. 1992 For example, consider the following definition: 1994 leaf lxiv { 1995 type decimal64 { 1996 fraction-digits 18; 1997 } 1998 must ". <= 10"; 1999 } 2001 An instance of the "lxiv" leaf having the value of 2002 10.0000000000000001 will then successfully pass validation. 2004 6.4.1. XPath Context 2006 All YANG XPath expressions share the following XPath context 2007 definition: 2009 o The set of namespace declarations is the set of all "import" 2010 statements' prefix and namespace pairs in the module where the 2011 XPath expression is specified, and the "prefix" statement's prefix 2012 for the "namespace" statement's URI. 2014 o Names without a namespace prefix belong to the same namespace as 2015 the identifier of the current node. Inside a grouping, that 2016 namespace is affected by where the grouping is used (see 2017 Section 7.13). Inside a typedef, that namespace is affected by 2018 where the typedef is referenced. If a typedef is defined and 2019 referenced within a grouping, the namespace is affected by where 2020 the grouping is used (see Section 7.13). 2022 o The function library is the core function library defined in 2023 [XPATH], and the functions defined in Section 10. 2025 o The set of variable bindings is empty. 2027 The mechanism for handling unprefixed names is adopted from XPath 2.0 2028 [XPATH2.0], and helps simplify XPath expressions in YANG. No 2029 ambiguity may ever arise because YANG node identifiers are always 2030 qualified names with a non-null namespace URI. 2032 The accessible tree depends on where the statement with the XPath 2033 expression is defined: 2035 o If the XPath expression is defined in substatement to a data node 2036 that represents configuration, the accessible tree is the data in 2037 the datastore where the context node exists. The root node has 2038 all top-level configuration data nodes in all modules as children. 2040 o If the XPath expression is defined in a substatement to a data 2041 node that represents state data, the accessible tree is all state 2042 data in the server, and the running configuration datastore. The 2043 root node has all top-level data nodes in all modules as children. 2045 o If the XPath expression is defined in a substatement to a 2046 "notification" statement, the accessible tree is the notification 2047 instance, all state data in the server, and the running 2048 configuration datastore. If the notification is defined on the 2049 top-level in a module, then the root node has the node 2050 representing the notification being defined and all top-level data 2051 nodes in all modules as children. Otherwise, the root node has 2052 all top-level data nodes in all modules as children. 2054 o If the XPath expression is defined in a substatement to an "input" 2055 statement in an "rpc" or "action" statement, the accessible tree 2056 is the RPC or action operation instance, all state data in the 2057 server, and the running configuration datastore. The root node 2058 has top-level data nodes in all modules as children. 2059 Additionally, for an RPC, the root node also has the node 2060 representing the RPC operation being defined as a child. The node 2061 representing the operation being defined has the operation's input 2062 parameters as children. 2064 o If the XPath expression is defined in a substatement to an 2065 "output" statement in an "rpc" or "action" statement, the 2066 accessible tree is the RPC or action operation instance, all state 2067 data in the server, and the running configuration datastore. The 2068 root node has top-level data nodes in all modules as children. 2069 Additionally, for an RPC, the root node also has the node 2070 representing the RPC operation being defined as a child. The node 2071 representing the operation being defined has the operation's 2072 output parameters as children. 2074 In the accessible tree, all leafs and leaf-lists with default values 2075 in use exist (See Section 7.6.1 and Section 7.7.2). 2077 If a node that exists in the accessible tree has a non-presence 2078 container as a child, then the non-presence container also exists in 2079 the tree. 2081 The context node varies with the YANG XPath expression, and is 2082 specified where the YANG statement with the XPath expression is 2083 defined. 2085 6.4.1.1. Examples 2087 Given the following module: 2089 module example-a { 2090 namespace urn:example:a; 2091 prefix a; 2093 container a { 2094 list b { 2095 key id; 2096 leaf id { 2097 type string; 2098 } 2099 notification down { 2100 leaf reason { 2101 type string; 2102 } 2103 } 2104 action reset { 2105 input { 2106 leaf delay { 2107 type uint32; 2108 } 2109 } 2110 output { 2111 leaf result { 2112 type string; 2113 } 2114 } 2115 } 2116 } 2117 } 2118 notification failure { 2119 leaf b-ref { 2120 type leafref { 2121 path "/a/b/id"; 2122 } 2123 } 2124 } 2125 } 2127 And given the following data tree, specified in XML: 2129 2130 2131 1 2132 2133 2134 2 2135 2136 2138 The accessible tree for a notification "down" on /a/b[id="2"] is: 2140 2141 2142 1 2143 2144 2145 2 2146 2147 error 2148 2149 2150 2151 // possibly other top-level nodes here 2153 The accessible tree for an action invocation of "reset" on /a/ 2154 b[id="1"] with the "when" parameter set to "10" would be: 2156 2157 2158 1 2159 2160 10 2161 2162 2163 2164 2 2165 2166 2167 // possibly other top-level nodes here 2169 The accessible tree for the action output of this action is: 2171 2172 2173 1 2174 2175 ok 2176 2177 2178 2179 2 2180 2181 2182 // possibly other top-level nodes here 2184 The accessible tree for a notification "failure" could be: 2186 2187 2188 1 2189 2190 2191 2 2192 2193 2194 2195 2 2196 2197 // possibly other top-level nodes here 2199 6.5. Schema Node Identifier 2201 A schema node identifier is a string that identifies a node in the 2202 schema tree. It has two forms, "absolute" and "descendant", defined 2203 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 2204 in Section 14, respectively. A schema node identifier consists of a 2205 path of identifiers, separated by slashes ("/"). In an absolute 2206 schema node identifier, the first identifier after the leading slash 2207 is any top-level schema node in the local module or in all imported 2208 modules. 2210 References to identifiers defined in external modules MUST be 2211 qualified with appropriate prefixes, and references to identifiers 2212 defined in the current module and its submodules MAY use a prefix. 2214 For example, to identify the child node "b" of top-level node "a", 2215 the string "/a/b" can be used. 2217 7. YANG Statements 2219 The following sections describe all of the YANG statements. 2221 Note that even a statement that does not have any substatements 2222 defined in YANG can have vendor-specific extensions as substatements. 2223 For example, the "description" statement does not have any 2224 substatements defined in YANG, but the following is legal: 2226 description "some text" { 2227 ex:documentation-flag 5; 2228 } 2230 7.1. The module Statement 2232 The "module" statement defines the module's name, and groups all 2233 statements that belong to the module together. The "module" 2234 statement's argument is the name of the module, followed by a block 2235 of substatements that hold detailed module information. The module 2236 name follows the rules for identifiers in Section 6.2. 2238 Names of modules published in RFC streams [RFC4844] MUST be assigned 2239 by IANA, see section 14 in [RFC6020]. 2241 Private module names are assigned by the organization owning the 2242 module without a central registry. See Section 5.1 for 2243 recommendations on how to name modules. 2245 A module typically has the following layout: 2247 module { 2249 // header information 2250 2251 2252 2254 // linkage statements 2255 2256 2258 // meta information 2259 2260 2261 2262 2264 // revision history 2265 2267 // module definitions 2268 2269 } 2271 7.1.1. The module's Substatements 2272 +--------------+---------+-------------+ 2273 | substatement | section | cardinality | 2274 +--------------+---------+-------------+ 2275 | anydata | 7.10 | 0..n | 2276 | anyxml | 7.11 | 0..n | 2277 | augment | 7.17 | 0..n | 2278 | choice | 7.9 | 0..n | 2279 | contact | 7.1.8 | 0..1 | 2280 | container | 7.5 | 0..n | 2281 | description | 7.21.3 | 0..1 | 2282 | deviation | 7.20.3 | 0..n | 2283 | extension | 7.19 | 0..n | 2284 | feature | 7.20.1 | 0..n | 2285 | grouping | 7.12 | 0..n | 2286 | identity | 7.18 | 0..n | 2287 | import | 7.1.5 | 0..n | 2288 | include | 7.1.6 | 0..n | 2289 | leaf | 7.6 | 0..n | 2290 | leaf-list | 7.7 | 0..n | 2291 | list | 7.8 | 0..n | 2292 | namespace | 7.1.3 | 1 | 2293 | notification | 7.16 | 0..n | 2294 | organization | 7.1.7 | 0..1 | 2295 | prefix | 7.1.4 | 1 | 2296 | reference | 7.21.4 | 0..1 | 2297 | revision | 7.1.9 | 0..n | 2298 | rpc | 7.14 | 0..n | 2299 | typedef | 7.3 | 0..n | 2300 | uses | 7.13 | 0..n | 2301 | yang-version | 7.1.2 | 1 | 2302 +--------------+---------+-------------+ 2304 7.1.2. The yang-version Statement 2306 The "yang-version" statement specifies which version of the YANG 2307 language was used in developing the module. The statement's argument 2308 is a string. It MUST contain the value "1.1", which is the current 2309 YANG version. 2311 A module or submodule that doesn't contain the "yang-version" 2312 statement, or one that contains the value "1", is developed for YANG 2313 version 1, defined in [RFC6020]. 2315 Handling of the "yang-version" statement for versions other than 2316 "1.1" (the version defined here) is out of scope for this 2317 specification. Any document that defines a higher version will need 2318 to define the backward compatibility of such a higher version. 2320 For compatibility between YANG version 1 and 1.1, see Section 12. 2322 7.1.3. The namespace Statement 2324 The "namespace" statement defines the XML namespace that all 2325 identifiers defined by the module are qualified by in the XML 2326 encoding, with the exception of identifiers for data nodes, action 2327 nodes, and notification nodes defined inside a grouping (see 2328 Section 7.13 for details). The argument to the "namespace" statement 2329 is the URI of the namespace. 2331 See also Section 5.3. 2333 7.1.4. The prefix Statement 2335 The "prefix" statement is used to define the prefix associated with 2336 the module and its namespace. The "prefix" statement's argument is 2337 the prefix string that is used as a prefix to access a module. The 2338 prefix string MAY be used to refer to definitions contained in the 2339 module, e.g., "if:ifName". A prefix follows the same rules as an 2340 identifier (see Section 6.2). 2342 When used inside the "module" statement, the "prefix" statement 2343 defines the prefix to be used when this module is imported. To 2344 improve readability of the NETCONF XML, a NETCONF client or server 2345 that generates XML or XPath that use prefixes SHOULD use the prefix 2346 defined by the module, unless there is a conflict. 2348 When used inside the "import" statement, the "prefix" statement 2349 defines the prefix to be used when accessing definitions inside the 2350 imported module. When a reference to an identifier from the imported 2351 module is used, the prefix string for the imported module is used in 2352 combination with a colon (":") and the identifier, e.g., 2353 "if:ifIndex". To improve readability of YANG modules, the prefix 2354 defined by a module SHOULD be used when the module is imported, 2355 unless there is a conflict. If there is a conflict, i.e., two 2356 different modules that both have defined the same prefix are 2357 imported, at least one of them MUST be imported with a different 2358 prefix. 2360 All prefixes, including the prefix for the module itself MUST be 2361 unique within the module or submodule. 2363 7.1.5. The import Statement 2365 The "import" statement makes definitions from one module available 2366 inside another module or submodule. The argument is the name of the 2367 module to import, and the statement is followed by a block of 2368 substatements that holds detailed import information. When a module 2369 is imported, the importing module may: 2371 o use any grouping and typedef defined at the top level in the 2372 imported module or its submodules. 2374 o use any extension, feature, and identity defined in the imported 2375 module or its submodules. 2377 o use any node in the imported module's schema tree in "must", 2378 "path", and "when" statements, or as the target node in "augment" 2379 and "deviation" statements. 2381 The mandatory "prefix" substatement assigns a prefix for the imported 2382 module that is scoped to the importing module or submodule. Multiple 2383 "import" statements may be specified to import from different 2384 modules. 2386 When the optional "revision-date" substatement is present, any 2387 typedef, grouping, extension, feature, and identity referenced by 2388 definitions in the local module are taken from the specified revision 2389 of the imported module. It is an error if the specified revision of 2390 the imported module does not exist. If no "revision-date" 2391 substatement is present, it is undefined from which revision of the 2392 module they are taken. 2394 Multiple revisions of the same module can be imported, provided that 2395 different prefixes are used. 2397 +---------------+---------+-------------+ 2398 | substatement | section | cardinality | 2399 +---------------+---------+-------------+ 2400 | prefix | 7.1.4 | 1 | 2401 | revision-date | 7.1.5.1 | 0..1 | 2402 | description | 7.21.3 | 0..1 | 2403 | reference | 7.21.4 | 0..1 | 2404 +---------------+---------+-------------+ 2406 The import's Substatements 2408 7.1.5.1. The import's revision-date Statement 2410 The import's "revision-date" statement is used to specify the exact 2411 version of the module to import. 2413 7.1.6. The include Statement 2415 The "include" statement is used to make content from a submodule 2416 available to that submodule's parent module. The argument is an 2417 identifier that is the name of the submodule to include. Modules are 2418 only allowed to include submodules that belong to that module, as 2419 defined by the "belongs-to" statement (see Section 7.2.2). 2421 When a module includes a submodule, it incorporates the contents of 2422 the submodule into the node hierarchy of the module. 2424 For backward compatibility with YANG version 1, a submodule is 2425 allowed to include another submodule belonging to the same module, 2426 but this is not necessary in YANG version 1.1. 2428 When the optional "revision-date" substatement is present, the 2429 specified revision of the submodule is included in the module. It is 2430 an error if the specified revision of the submodule does not exist. 2431 If no "revision-date" substatement is present, it is undefined which 2432 revision of the submodule is included. 2434 Multiple revisions of the same submodule MUST NOT be included. 2436 +---------------+---------+-------------+ 2437 | substatement | section | cardinality | 2438 +---------------+---------+-------------+ 2439 | revision-date | 7.1.5.1 | 0..1 | 2440 | description | 7.21.3 | 0..1 | 2441 | reference | 7.21.4 | 0..1 | 2442 +---------------+---------+-------------+ 2444 The includes's Substatements 2446 7.1.7. The organization Statement 2448 The "organization" statement defines the party responsible for this 2449 module. The argument is a string that is used to specify a textual 2450 description of the organization(s) under whose auspices this module 2451 was developed. 2453 7.1.8. The contact Statement 2455 The "contact" statement provides contact information for the module. 2456 The argument is a string that is used to specify contact information 2457 for the person or persons to whom technical queries concerning this 2458 module should be sent, such as their name, postal address, telephone 2459 number, and electronic mail address. 2461 7.1.9. The revision Statement 2463 The "revision" statement specifies the editorial revision history of 2464 the module, including the initial revision. A series of revision 2465 statements detail the changes in the module's definition. The 2466 argument is a date string in the format "YYYY-MM-DD", followed by a 2467 block of substatements that holds detailed revision information. A 2468 module SHOULD have at least one "revision" statement. For every 2469 published editorial change, a new one SHOULD be added in front of the 2470 revisions sequence, so that all revisions are in reverse 2471 chronological order. 2473 7.1.9.1. The revision's Substatement 2475 +--------------+---------+-------------+ 2476 | substatement | section | cardinality | 2477 +--------------+---------+-------------+ 2478 | description | 7.21.3 | 0..1 | 2479 | reference | 7.21.4 | 0..1 | 2480 +--------------+---------+-------------+ 2482 7.1.10. Usage Example 2483 module example-system { 2484 yang-version 1.1; 2485 namespace "urn:example:system"; 2486 prefix "sys"; 2488 import ietf-yang-types { 2489 prefix "yang"; 2490 } 2492 include example-types; 2494 organization "Example Inc."; 2495 contact 2496 "Joe L. User 2498 Example Inc. 2499 42 Anywhere Drive 2500 Nowhere, CA 95134 2501 USA 2503 Phone: +1 800 555 0100 2504 EMail: joe@example.com"; 2506 description 2507 "The module for entities implementing the Example system."; 2509 revision 2007-06-09 { 2510 description "Initial revision."; 2511 } 2513 // definitions follow... 2514 } 2516 7.2. The submodule Statement 2518 While the primary unit in YANG is a module, a YANG module can itself 2519 be constructed out of several submodules. Submodules allow a module 2520 designer to split a complex model into several pieces where all the 2521 submodules contribute to a single namespace, which is defined by the 2522 module that includes the submodules. 2524 The "submodule" statement defines the submodule's name, and groups 2525 all statements that belong to the submodule together. The 2526 "submodule" statement's argument is the name of the submodule, 2527 followed by a block of substatements that hold detailed submodule 2528 information. The submodule name follows the rules for identifiers in 2529 Section 6.2. 2531 Names of submodules published in RFC streams [RFC4844] MUST be 2532 assigned by IANA, see section 14 in [RFC6020]. 2534 Private submodule names are assigned by the organization owning the 2535 submodule without a central registry. See Section 5.1 for 2536 recommendations on how to name submodules. 2538 A submodule typically has the following layout: 2540 submodule { 2542 2544 // module identification 2545 2547 // linkage statements 2548 2550 // meta information 2551 2552 2553 2554 2556 // revision history 2557 2559 // module definitions 2560 2561 } 2563 7.2.1. The submodule's Substatements 2564 +--------------+---------+-------------+ 2565 | substatement | section | cardinality | 2566 +--------------+---------+-------------+ 2567 | anydata | 7.10 | 0..n | 2568 | anyxml | 7.11 | 0..n | 2569 | augment | 7.17 | 0..n | 2570 | belongs-to | 7.2.2 | 1 | 2571 | choice | 7.9 | 0..n | 2572 | contact | 7.1.8 | 0..1 | 2573 | container | 7.5 | 0..n | 2574 | description | 7.21.3 | 0..1 | 2575 | deviation | 7.20.3 | 0..n | 2576 | extension | 7.19 | 0..n | 2577 | feature | 7.20.1 | 0..n | 2578 | grouping | 7.12 | 0..n | 2579 | identity | 7.18 | 0..n | 2580 | import | 7.1.5 | 0..n | 2581 | include | 7.1.6 | 0..n | 2582 | leaf | 7.6 | 0..n | 2583 | leaf-list | 7.7 | 0..n | 2584 | list | 7.8 | 0..n | 2585 | notification | 7.16 | 0..n | 2586 | organization | 7.1.7 | 0..1 | 2587 | reference | 7.21.4 | 0..1 | 2588 | revision | 7.1.9 | 0..n | 2589 | rpc | 7.14 | 0..n | 2590 | typedef | 7.3 | 0..n | 2591 | uses | 7.13 | 0..n | 2592 | yang-version | 7.1.2 | 1 | 2593 +--------------+---------+-------------+ 2595 7.2.2. The belongs-to Statement 2597 The "belongs-to" statement specifies the module to which the 2598 submodule belongs. The argument is an identifier that is the name of 2599 the module. 2601 A submodule MUST only be included by the module to which it belongs, 2602 or by another submodule that belongs to that module. 2604 The mandatory "prefix" substatement assigns a prefix for the module 2605 to which the submodule belongs. All definitions in the module that 2606 the submodule belongs to and all its submodules can be accessed by 2607 using the prefix. 2609 +--------------+---------+-------------+ 2610 | substatement | section | cardinality | 2611 +--------------+---------+-------------+ 2612 | prefix | 7.1.4 | 1 | 2613 +--------------+---------+-------------+ 2615 The belongs-to's Substatements 2617 7.2.3. Usage Example 2619 submodule example-types { 2620 yang-version 1.1; 2621 belongs-to "example-system" { 2622 prefix "sys"; 2623 } 2625 import ietf-yang-types { 2626 prefix "yang"; 2627 } 2629 organization "Example Inc."; 2630 contact 2631 "Joe L. User 2633 Example Inc. 2634 42 Anywhere Drive 2635 Nowhere, CA 95134 2636 USA 2638 Phone: +1 800 555 0100 2639 EMail: joe@example.com"; 2641 description 2642 "This submodule defines common Example types."; 2644 revision "2007-06-09" { 2645 description "Initial revision."; 2646 } 2648 // definitions follows... 2649 } 2651 7.3. The typedef Statement 2653 The "typedef" statement defines a new type that may be used locally 2654 in the module or submodule, and by other modules that import from it, 2655 according to the rules in Section 5.5. The new type is called the 2656 "derived type", and the type from which it was derived is called the 2657 "base type". All derived types can be traced back to a YANG built-in 2658 type. 2660 The "typedef" statement's argument is an identifier that is the name 2661 of the type to be defined, and MUST be followed by a block of 2662 substatements that holds detailed typedef information. 2664 The name of the type MUST NOT be one of the YANG built-in types. If 2665 the typedef is defined at the top level of a YANG module or 2666 submodule, the name of the type to be defined MUST be unique within 2667 the module. 2669 7.3.1. The typedef's Substatements 2671 +--------------+---------+-------------+ 2672 | substatement | section | cardinality | 2673 +--------------+---------+-------------+ 2674 | default | 7.3.4 | 0..1 | 2675 | description | 7.21.3 | 0..1 | 2676 | reference | 7.21.4 | 0..1 | 2677 | status | 7.21.2 | 0..1 | 2678 | type | 7.3.2 | 1 | 2679 | units | 7.3.3 | 0..1 | 2680 +--------------+---------+-------------+ 2682 7.3.2. The typedef's type Statement 2684 The "type" statement, which MUST be present, defines the base type 2685 from which this type is derived. See Section 7.4 for details. 2687 7.3.3. The units Statement 2689 The "units" statement, which is optional, takes as an argument a 2690 string that contains a textual definition of the units associated 2691 with the type. 2693 7.3.4. The typedef's default Statement 2695 The "default" statement takes as an argument a string that contains a 2696 default value for the new type. 2698 The value of the "default" statement MUST be valid according to the 2699 type specified in the "type" statement. 2701 If the base type has a default value, and the new derived type does 2702 not specify a new default value, the base type's default value is 2703 also the default value of the new derived type. 2705 If the type's default value is not valid according to the new 2706 restrictions specified in a derived type or leaf definition, the 2707 derived type or leaf definition MUST specify a new default value 2708 compatible with the restrictions. 2710 7.3.5. Usage Example 2712 typedef listen-ipv4-address { 2713 type inet:ipv4-address; 2714 default "0.0.0.0"; 2715 } 2717 7.4. The type Statement 2719 The "type" statement takes as an argument a string that is the name 2720 of a YANG built-in type (see Section 9) or a derived type (see 2721 Section 7.3), followed by an optional block of substatements that are 2722 used to put further restrictions on the type. 2724 The restrictions that can be applied depend on the type being 2725 restricted. The restriction statements for all built-in types are 2726 described in the subsections of Section 9. 2728 7.4.1. The type's Substatements 2730 +------------------+---------+-------------+ 2731 | substatement | section | cardinality | 2732 +------------------+---------+-------------+ 2733 | base | 7.18.2 | 0..n | 2734 | bit | 9.7.4 | 0..n | 2735 | enum | 9.6.4 | 0..n | 2736 | fraction-digits | 9.3.4 | 0..1 | 2737 | length | 9.4.4 | 0..1 | 2738 | path | 9.9.2 | 0..1 | 2739 | pattern | 9.4.5 | 0..n | 2740 | range | 9.2.4 | 0..1 | 2741 | require-instance | 9.9.3 | 0..1 | 2742 | type | 7.4 | 0..n | 2743 +------------------+---------+-------------+ 2745 7.5. The container Statement 2747 The "container" statement is used to define an interior data node in 2748 the schema tree. It takes one argument, which is an identifier, 2749 followed by a block of substatements that holds detailed container 2750 information. 2752 A container node does not have a value, but it has a list of child 2753 nodes in the data tree. The child nodes are defined in the 2754 container's substatements. 2756 7.5.1. Containers with Presence 2758 YANG supports two styles of containers, those that exist only for 2759 organizing the hierarchy of data nodes, and those whose presence in 2760 the data tree has an explicit meaning. 2762 In the first style, the container has no meaning of its own, existing 2763 only to contain child nodes. This is the default style. 2765 For example, the set of scrambling options for Synchronous Optical 2766 Network (SONET) interfaces may be placed inside a "scrambling" 2767 container to enhance the organization of the configuration hierarchy, 2768 and to keep these nodes together. The "scrambling" node itself has 2769 no meaning, so removing the node when it becomes empty relieves the 2770 user from performing this task. 2772 In the second style, the presence of the container itself carries 2773 some meaning, representing a single bit of data. 2775 In configuration data, the container acts as both a configuration 2776 knob and a means of organizing related configuration. These 2777 containers are explicitly created and deleted. 2779 YANG calls this style a "presence container" and it is indicated 2780 using the "presence" statement, which takes as its argument a text 2781 string indicating what the presence of the node means. 2783 For example, an "ssh" container may turn on the ability to log into 2784 the server using ssh, but can also contain any ssh-related 2785 configuration knobs, such as connection rates or retry limits. 2787 The "presence" statement (see Section 7.5.5) is used to give 2788 semantics to the existence of the container in the data tree. 2790 7.5.2. The container's Substatements 2791 +--------------+---------+-------------+ 2792 | substatement | section | cardinality | 2793 +--------------+---------+-------------+ 2794 | action | 7.15 | 0..n | 2795 | anydata | 7.10 | 0..n | 2796 | anyxml | 7.11 | 0..n | 2797 | choice | 7.9 | 0..n | 2798 | config | 7.21.1 | 0..1 | 2799 | container | 7.5 | 0..n | 2800 | description | 7.21.3 | 0..1 | 2801 | grouping | 7.12 | 0..n | 2802 | if-feature | 7.20.2 | 0..n | 2803 | leaf | 7.6 | 0..n | 2804 | leaf-list | 7.7 | 0..n | 2805 | list | 7.8 | 0..n | 2806 | must | 7.5.3 | 0..n | 2807 | notification | 7.16 | 0..n | 2808 | presence | 7.5.5 | 0..1 | 2809 | reference | 7.21.4 | 0..1 | 2810 | status | 7.21.2 | 0..1 | 2811 | typedef | 7.3 | 0..n | 2812 | uses | 7.13 | 0..n | 2813 | when | 7.21.5 | 0..1 | 2814 +--------------+---------+-------------+ 2816 7.5.3. The must Statement 2818 The "must" statement, which is optional, takes as an argument a 2819 string that contains an XPath expression (see Section 6.4). It is 2820 used to formally declare a constraint on valid data. The constraint 2821 is enforced according to the rules in Section 8. 2823 When a datastore is validated, all "must" constraints are 2824 conceptually evaluated once for each node in the accessible tree (see 2825 Section 6.4.1). 2827 All such constraints MUST evaluate to true for the data to be valid. 2829 The XPath expression is conceptually evaluated in the following 2830 context, in addition to the definition in Section 6.4.1: 2832 o The context node is the node in the accessible tree for which the 2833 "must" statement is defined. 2835 The result of the XPath expression is converted to a boolean value 2836 using the standard XPath rules. 2838 Note that since all leaf values in the data tree are conceptually 2839 stored in their canonical form (see Section 9.1), any XPath 2840 comparisons are done on the canonical value. 2842 Also note that the XPath expression is conceptually evaluated. This 2843 means that an implementation does not have to use an XPath evaluator 2844 in the server. How the evaluation is done in practice is an 2845 implementation decision. 2847 7.5.4. The must's Substatements 2849 +---------------+---------+-------------+ 2850 | substatement | section | cardinality | 2851 +---------------+---------+-------------+ 2852 | description | 7.21.3 | 0..1 | 2853 | error-app-tag | 7.5.4.2 | 0..1 | 2854 | error-message | 7.5.4.1 | 0..1 | 2855 | reference | 7.21.4 | 0..1 | 2856 +---------------+---------+-------------+ 2858 7.5.4.1. The error-message Statement 2860 The "error-message" statement, which is optional, takes a string as 2861 an argument. If the constraint evaluates to false, the string is 2862 passed as in the in NETCONF. 2864 7.5.4.2. The error-app-tag Statement 2866 The "error-app-tag" statement, which is optional, takes a string as 2867 an argument. If the constraint evaluates to false, the string is 2868 passed as in the in NETCONF. 2870 7.5.4.3. Usage Example of must and error-message 2871 container interface { 2872 leaf ifType { 2873 type enumeration { 2874 enum ethernet; 2875 enum atm; 2876 } 2877 } 2878 leaf ifMTU { 2879 type uint32; 2880 } 2881 must "ifType != 'ethernet' or " + 2882 "(ifType = 'ethernet' and ifMTU = 1500)" { 2883 error-message "An ethernet MTU must be 1500"; 2884 } 2885 must "ifType != 'atm' or " + 2886 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2887 error-message "An atm MTU must be 64 .. 17966"; 2888 } 2889 } 2891 7.5.5. The presence Statement 2893 The "presence" statement assigns a meaning to the presence of a 2894 container in the data tree. It takes as an argument a string that 2895 contains a textual description of what the node's presence means. 2897 If a container has the "presence" statement, the container's 2898 existence in the data tree carries some meaning. Otherwise, the 2899 container is used to give some structure to the data, and it carries 2900 no meaning by itself. 2902 See Section 7.5.1 for additional information. 2904 7.5.6. The container's Child Node Statements 2906 Within a container, the "container", "leaf", "list", "leaf-list", 2907 "uses", "choice", "anydata", and "anyxml" statements can be used to 2908 define child nodes to the container. 2910 7.5.7. XML Encoding Rules 2912 A container node is encoded as an XML element. The element's local 2913 name is the container's identifier, and its namespace is the module's 2914 XML namespace (see Section 7.1.3). 2916 The container's child nodes are encoded as subelements to the 2917 container element. If the container defines RPC or action input or 2918 output parameters, these subelements are encoded in the same order as 2919 they are defined within the "container" statement. Otherwise, the 2920 subelements are encoded in any order. 2922 If a non-presence container does not have any child nodes, the 2923 container may or may not be present in the XML encoding. 2925 7.5.8. NETCONF Operations 2927 Containers can be created, deleted, replaced, and modified through 2928 , by using the "operation" attribute (see [RFC6241], 2929 Section 7.2) in the container's XML element. 2931 If a container does not have a "presence" statement and the last 2932 child node is deleted, the NETCONF server MAY delete the container. 2934 When a NETCONF server processes an request, the 2935 elements of procedure for the container node are: 2937 If the operation is "merge" or "replace", the node is created if 2938 it does not exist. 2940 If the operation is "create", the node is created if it does not 2941 exist. If the node already exists, a "data-exists" error is 2942 returned. 2944 If the operation is "delete", the node is deleted if it exists. 2945 If the node does not exist, a "data-missing" error is returned. 2947 7.5.9. Usage Example 2949 Given the following container definition: 2951 container system { 2952 description 2953 "Contains various system parameters"; 2954 container services { 2955 description 2956 "Configure externally available services"; 2957 container "ssh" { 2958 presence "Enables SSH"; 2959 description 2960 "SSH service specific configuration"; 2961 // more leafs, containers and stuff here... 2962 } 2963 } 2964 } 2966 A corresponding XML instance example: 2968 2969 2970 2971 2972 2974 Since the element is present, ssh is enabled. 2976 To delete a container with an : 2978 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2995 7.6. The leaf Statement 2997 The "leaf" statement is used to define a leaf node in the schema 2998 tree. It takes one argument, which is an identifier, followed by a 2999 block of substatements that holds detailed leaf information. 3001 A leaf node has a value, but no child nodes in the data tree. 3002 Conceptually, the value in the data tree is always in the canonical 3003 form (see Section 9.1). 3005 A leaf node exists in zero or one instances in the data tree. 3007 The "leaf" statement is used to define a scalar variable of a 3008 particular built-in or derived type. 3010 7.6.1. The leaf's default value 3012 The default value of a leaf is the value that the server uses if the 3013 leaf does not exist in the data tree. The usage of the default value 3014 depends on the leaf's closest ancestor node in the schema tree that 3015 is not a non-presence-container (see Section 7.5.1): 3017 o If no such ancestor exists in the schema tree, the default value 3018 MUST be used. 3020 o Otherwise, if this ancestor is a case node, the default value MUST 3021 be used if any node from the case exists in the data tree, or if 3022 the case node is the choice's default case, and no nodes from any 3023 other case exist in the data tree. 3025 o Otherwise, the default value MUST be used if the ancestor node 3026 exists in the data tree. 3028 In these cases, the default value is said to be in use. 3030 Note that if the leaf or any of its ancestors has a "when" condition 3031 or "if-feature" expression that evaluates to "false", then the 3032 default value is not in use. 3034 When the default value is in use, the server MUST operationally 3035 behave as if the leaf was present in the data tree with the default 3036 value as its value. 3038 If a leaf has a "default" statement, the leaf's default value is the 3039 value of the "default" statement. Otherwise, if the leaf's type has 3040 a default value, and the leaf is not mandatory, then the leaf's 3041 default value is the type's default value. In all other cases, the 3042 leaf does not have a default value. 3044 7.6.2. The leaf's Substatements 3046 +--------------+---------+-------------+ 3047 | substatement | section | cardinality | 3048 +--------------+---------+-------------+ 3049 | config | 7.21.1 | 0..1 | 3050 | default | 7.6.4 | 0..1 | 3051 | description | 7.21.3 | 0..1 | 3052 | if-feature | 7.20.2 | 0..n | 3053 | mandatory | 7.6.5 | 0..1 | 3054 | must | 7.5.3 | 0..n | 3055 | reference | 7.21.4 | 0..1 | 3056 | status | 7.21.2 | 0..1 | 3057 | type | 7.6.3 | 1 | 3058 | units | 7.3.3 | 0..1 | 3059 | when | 7.21.5 | 0..1 | 3060 +--------------+---------+-------------+ 3062 7.6.3. The leaf's type Statement 3064 The "type" statement, which MUST be present, takes as an argument the 3065 name of an existing built-in or derived type. The optional 3066 substatements specify restrictions on this type. See Section 7.4 for 3067 details. 3069 7.6.4. The leaf's default Statement 3071 The "default" statement, which is optional, takes as an argument a 3072 string that contains a default value for the leaf. 3074 The value of the "default" statement MUST be valid according to the 3075 type specified in the leaf's "type" statement. 3077 The "default" statement MUST NOT be present on nodes where 3078 "mandatory" is true. 3080 The default value MUST NOT be marked with an "if-feature" statement. 3081 For example, the following is illegal: 3083 leaf color { 3084 type enumeration { 3085 enum blue { if-feature blue; } 3086 ... 3087 } 3088 default blue; // illegal - enum value is conditional 3089 } 3091 7.6.5. The leaf's mandatory Statement 3093 The "mandatory" statement, which is optional, takes as an argument 3094 the string "true" or "false", and puts a constraint on valid data. 3095 If not specified, the default is "false". 3097 If "mandatory" is "true", the behavior of the constraint depends on 3098 the type of the leaf's closest ancestor node in the schema tree that 3099 is not a non-presence-container (see Section 7.5.1): 3101 o If no such ancestor exists in the schema tree, the leaf MUST 3102 exist. 3104 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 3105 any node from the case exists in the data tree. 3107 o Otherwise, the leaf MUST exist if the ancestor node exists in the 3108 data tree. 3110 This constraint is enforced according to the rules in Section 8. 3112 7.6.6. XML Encoding Rules 3114 A leaf node is encoded as an XML element. The element's local name 3115 is the leaf's identifier, and its namespace is the module's XML 3116 namespace (see Section 7.1.3). 3118 The value of the leaf node is encoded to XML according to the type, 3119 and sent as character data in the element. 3121 See Section 7.6.8 for an example. 3123 7.6.7. NETCONF Operations 3125 When a NETCONF server processes an request, the 3126 elements of procedure for the leaf node are: 3128 If the operation is "merge" or "replace", the node is created if 3129 it does not exist, and its value is set to the value found in the 3130 XML RPC data. 3132 If the operation is "create", the node is created if it does not 3133 exist. If the node already exists, a "data-exists" error is 3134 returned. 3136 If the operation is "delete", the node is deleted if it exists. 3137 If the node does not exist, a "data-missing" error is returned. 3139 7.6.8. Usage Example 3141 Given the following "leaf" statement, placed in the previously 3142 defined "ssh" container (see Section 7.5.9): 3144 leaf port { 3145 type inet:port-number; 3146 default 22; 3147 description 3148 "The port to which the SSH server listens" 3149 } 3151 A corresponding XML instance example: 3153 2022 3155 To set the value of a leaf with an : 3157 3160 3161 3162 3163 3164 3165 3166 3167 3168 2022 3169 3170 3171 3172 3173 3174 3176 7.7. The leaf-list Statement 3178 Where the "leaf" statement is used to define a simple scalar variable 3179 of a particular type, the "leaf-list" statement is used to define an 3180 array of a particular type. The "leaf-list" statement takes one 3181 argument, which is an identifier, followed by a block of 3182 substatements that holds detailed leaf-list information. 3184 In configuration data, the values in a leaf-list MUST be unique. 3186 The default values MUST NOT be marked with an "if-feature" statement. 3188 Conceptually, the values in the data tree are always in the canonical 3189 form (see Section 9.1). 3191 7.7.1. Ordering 3193 YANG supports two styles for ordering the entries within lists and 3194 leaf-lists. In many lists, the order of list entries does not impact 3195 the implementation of the list's configuration, and the server is 3196 free to sort the list entries in any reasonable order. The 3197 "description" string for the list may suggest an order to the server 3198 implementor. YANG calls this style of list "system ordered" and they 3199 are indicated with the statement "ordered-by system". 3201 For example, a list of valid users would typically be sorted 3202 alphabetically, since the order in which the users appeared in the 3203 configuration would not impact the creation of those users' accounts. 3205 In the other style of lists, the order of list entries matters for 3206 the implementation of the list's configuration and the user is 3207 responsible for ordering the entries, while the server maintains that 3208 order. YANG calls this style of list "user ordered" and they are 3209 indicated with the statement "ordered-by user". 3211 For example, the order in which packet filters entries are applied to 3212 incoming traffic may affect how that traffic is filtered. The user 3213 would need to decide if the filter entry that discards all TCP 3214 traffic should be applied before or after the filter entry that 3215 allows all traffic from trusted interfaces. The choice of order 3216 would be crucial. 3218 YANG provides a rich set of facilities within NETCONF's 3219 operation that allows the order of list entries in user-ordered lists 3220 to be controlled. List entries may be inserted or rearranged, 3221 positioned as the first or last entry in the list, or positioned 3222 before or after another specific entry. 3224 The "ordered-by" statement is covered in Section 7.7.7. 3226 7.7.2. The leaf-list's default values 3228 The default values of a leaf-list are the values that the server uses 3229 if the leaf-list does not exist in the data tree. The usage of the 3230 default values depends on the leaf-list's closest ancestor node in 3231 the schema tree that is not a non-presence-container (see 3232 Section 7.5.1): 3234 o If no such ancestor exists in the schema tree, the default values 3235 MUST be used. 3237 o Otherwise, if this ancestor is a case node, the default values 3238 MUST be used if any node from the case exists in the data tree, or 3239 if the case node is the choice's default case, and no nodes from 3240 any other case exist in the data tree. 3242 o Otherwise, the default values MUST be used if the ancestor node 3243 exists in the data tree. 3245 In these cases, the default values are said to be in use. 3247 Note that if the leaf-list or any of its ancestors has a "when" 3248 condition or "if-feature" expression that evaluates to "false", then 3249 the default values are not in use. 3251 When the default values are in use, the server MUST operationally 3252 behave as if the leaf-list was present in the data tree with the 3253 default values as its values. 3255 If a leaf-list has one or more "default" statement, the leaf-list's 3256 default value are the values of the "default" statements, and if the 3257 leaf-list is user-ordered, the default values are used in the order 3258 of the "default" statements. Otherwise, if the leaf-list's type has 3259 a default value, and the leaf-list does not have a "min-elements" 3260 statement with a value greater than or equal to one, then the leaf- 3261 list's default value is the type's default value. In all other 3262 cases, the leaf-list does not have any default values. 3264 7.7.3. The leaf-list's Substatements 3266 +--------------+---------+-------------+ 3267 | substatement | section | cardinality | 3268 +--------------+---------+-------------+ 3269 | config | 7.21.1 | 0..1 | 3270 | default | 7.7.4 | 0..n | 3271 | description | 7.21.3 | 0..1 | 3272 | if-feature | 7.20.2 | 0..n | 3273 | max-elements | 7.7.6 | 0..1 | 3274 | min-elements | 7.7.5 | 0..1 | 3275 | must | 7.5.3 | 0..n | 3276 | ordered-by | 7.7.7 | 0..1 | 3277 | reference | 7.21.4 | 0..1 | 3278 | status | 7.21.2 | 0..1 | 3279 | type | 7.4 | 1 | 3280 | units | 7.3.3 | 0..1 | 3281 | when | 7.21.5 | 0..1 | 3282 +--------------+---------+-------------+ 3284 7.7.4. The leaf-list's default Statement 3286 The "default" statement, which is optional, takes as an argument a 3287 string that contains a default value for the leaf-list. 3289 The value of the "default" statement MUST be valid according to the 3290 type specified in the leaf-list's "type" statement. 3292 The "default" statement MUST NOT be present on nodes where 3293 "min-elements" has a value greater than or equal to one. 3295 7.7.5. The min-elements Statement 3297 The "min-elements" statement, which is optional, takes as an argument 3298 a non-negative integer that puts a constraint on valid list entries. 3299 A valid leaf-list or list MUST have at least min-elements entries. 3301 If no "min-elements" statement is present, it defaults to zero. 3303 The behavior of the constraint depends on the type of the leaf-list's 3304 or list's closest ancestor node in the schema tree that is not a non- 3305 presence-container (see Section 7.5.1): 3307 o If this ancestor is a case node, the constraint is enforced if any 3308 other node from the case exists. 3310 o Otherwise, it is enforced if the ancestor node exists. 3312 The constraint is further enforced according to the rules in 3313 Section 8. 3315 7.7.6. The max-elements Statement 3317 The "max-elements" statement, which is optional, takes as an argument 3318 a positive integer or the string "unbounded", which puts a constraint 3319 on valid list entries. A valid leaf-list or list always has at most 3320 max-elements entries. 3322 If no "max-elements" statement is present, it defaults to 3323 "unbounded". 3325 The "max-elements" constraint is enforced according to the rules in 3326 Section 8. 3328 7.7.7. The ordered-by Statement 3330 The "ordered-by" statement defines whether the order of entries 3331 within a list are determined by the user or the system. The argument 3332 is one of the strings "system" or "user". If not present, order 3333 defaults to "system". 3335 This statement is ignored if the list represents state data, RPC 3336 output parameters, or notification content. 3338 See Section 7.7.1 for additional information. 3340 7.7.7.1. ordered-by system 3342 The entries in the list are sorted according to an order determined 3343 by the system. The "description" string for the list may suggest an 3344 order to the server implementor. If not, an implementation is free 3345 to sort the entries in the most appropriate order. An implementation 3346 SHOULD use the same order for the same data, regardless of how the 3347 data were created. Using a deterministic order will make comparisons 3348 possible using simple tools like "diff". 3350 This is the default order. 3352 7.7.7.2. ordered-by user 3354 The entries in the list are sorted according to an order defined by 3355 the user. This order is controlled by using special XML attributes 3356 in the request. See Section 7.7.9 for details. 3358 7.7.8. XML Encoding Rules 3360 A leaf-list node is encoded as a series of XML elements. Each 3361 element's local name is the leaf-list's identifier, and its namespace 3362 is the module's XML namespace (see Section 7.1.3). 3364 The value of each leaf-list entry is encoded to XML according to the 3365 type, and sent as character data in the element. 3367 The XML elements representing leaf-list entries MUST appear in the 3368 order specified by the user if the leaf-list is "ordered-by user"; 3369 otherwise, the order is implementation-dependent. The XML elements 3370 representing leaf-list entries MAY be interleaved with other sibling 3371 elements, unless the leaf-list defines RPC or action input or output 3372 parameters. 3374 See Section 7.7.10 for an example. 3376 7.7.9. NETCONF Operations 3378 Leaf-list entries can be created and deleted, but not modified, 3379 through , by using the "operation" attribute in the 3380 leaf-list entry's XML element. 3382 In an "ordered-by user" leaf-list, the attributes "insert" and 3383 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3384 control where in the leaf-list the entry is inserted. These can be 3385 used during "create" operations to insert a new leaf-list entry, or 3386 during "merge" or "replace" operations to insert a new leaf-list 3387 entry or move an existing one. 3389 The "insert" attribute can take the values "first", "last", "before", 3390 and "after". If the value is "before" or "after", the "value" 3391 attribute MUST also be used to specify an existing entry in the leaf- 3392 list. 3394 If no "insert" attribute is present in the "create" operation, it 3395 defaults to "last". 3397 If several entries in an "ordered-by user" leaf-list are modified in 3398 the same request, the entries are modified one at the 3399 time, in the order of the XML elements in the request. 3401 In a , or an with a "replace" operation 3402 that covers the entire leaf-list, the leaf-list order is the same as 3403 the order of the XML elements in the request. 3405 When a NETCONF server processes an request, the 3406 elements of procedure for a leaf-list node are: 3408 If the operation is "merge" or "replace", the leaf-list entry is 3409 created if it does not exist. 3411 If the operation is "create", the leaf-list entry is created if it 3412 does not exist. If the leaf-list entry already exists, a 3413 "data-exists" error is returned. 3415 If the operation is "delete", the entry is deleted from the leaf- 3416 list if it exists. If the leaf-list entry does not exist, a 3417 "data-missing" error is returned. 3419 7.7.10. Usage Example 3421 leaf-list allow-user { 3422 type string; 3423 description 3424 "A list of user name patterns to allow"; 3425 } 3427 A corresponding XML instance example: 3429 alice 3430 bob 3432 To create a new element in this list, using the default 3433 operation "merge": 3435 3438 3439 3440 3441 3442 3443 3444 3445 3446 eric 3447 3448 3449 3450 3451 3452 3454 Given the following ordered-by user leaf-list: 3456 leaf-list cipher { 3457 type string; 3458 ordered-by user; 3459 description 3460 "A list of ciphers"; 3461 } 3463 The following would be used to insert a new cipher "blowfish-cbc" 3464 after "3des-cbc": 3466 3470 3471 3472 3473 3474 3475 3476 3477 3478 blowfish-cbc 3481 3482 3483 3484 3485 3486 3488 7.8. The list Statement 3490 The "list" statement is used to define an interior data node in the 3491 schema tree. A list node may exist in multiple instances in the data 3492 tree. Each such instance is known as a list entry. The "list" 3493 statement takes one argument, which is an identifier, followed by a 3494 block of substatements that holds detailed list information. 3496 A list entry is uniquely identified by the values of the list's keys, 3497 if defined. 3499 7.8.1. The list's Substatements 3500 +--------------+---------+-------------+ 3501 | substatement | section | cardinality | 3502 +--------------+---------+-------------+ 3503 | action | 7.15 | 0..n | 3504 | anydata | 7.10 | 0..n | 3505 | anyxml | 7.11 | 0..n | 3506 | choice | 7.9 | 0..n | 3507 | config | 7.21.1 | 0..1 | 3508 | container | 7.5 | 0..n | 3509 | description | 7.21.3 | 0..1 | 3510 | grouping | 7.12 | 0..n | 3511 | if-feature | 7.20.2 | 0..n | 3512 | key | 7.8.2 | 0..1 | 3513 | leaf | 7.6 | 0..n | 3514 | leaf-list | 7.7 | 0..n | 3515 | list | 7.8 | 0..n | 3516 | max-elements | 7.7.6 | 0..1 | 3517 | min-elements | 7.7.5 | 0..1 | 3518 | must | 7.5.3 | 0..n | 3519 | notification | 7.16 | 0..n | 3520 | ordered-by | 7.7.7 | 0..1 | 3521 | reference | 7.21.4 | 0..1 | 3522 | status | 7.21.2 | 0..1 | 3523 | typedef | 7.3 | 0..n | 3524 | unique | 7.8.3 | 0..n | 3525 | uses | 7.13 | 0..n | 3526 | when | 7.21.5 | 0..1 | 3527 +--------------+---------+-------------+ 3529 7.8.2. The list's key Statement 3531 The "key" statement, which MUST be present if the list represents 3532 configuration, and MAY be present otherwise, takes as an argument a 3533 string that specifies a space-separated list of leaf identifiers of 3534 this list. A leaf identifier MUST NOT appear more than once in the 3535 key. Each such leaf identifier MUST refer to a child leaf of the 3536 list. The leafs can be defined directly in substatements to the 3537 list, or in groupings used in the list. 3539 The combined values of all the leafs specified in the key are used to 3540 uniquely identify a list entry. All key leafs MUST be given values 3541 when a list entry is created. Thus, any default values in the key 3542 leafs or their types are ignored. It also implies that any mandatory 3543 statement in the key leafs are ignored. 3545 A leaf that is part of the key can be of any built-in or derived 3546 type. 3548 All key leafs in a list MUST have the same value for their "config" 3549 as the list itself. 3551 The key string syntax is formally defined by the rule "key-arg" in 3552 Section 14. 3554 7.8.3. The list's unique Statement 3556 The "unique" statement is used to put constraints on valid list 3557 entries. It takes as an argument a string that contains a space- 3558 separated list of schema node identifiers, which MUST be given in the 3559 descendant form (see the rule "descendant-schema-nodeid" in 3560 Section 14). Each such schema node identifier MUST refer to a leaf. 3562 If one of the referenced leafs represents configuration data, then 3563 all of the referenced leafs MUST represent configuration data. 3565 The "unique" constraint specifies that the combined values of all the 3566 leaf instances specified in the argument string, including leafs with 3567 default values, MUST be unique within all list entry instances in 3568 which all referenced leafs exist. The constraint is enforced 3569 according to the rules in Section 8. 3571 The unique string syntax is formally defined by the rule "unique-arg" 3572 in Section 14. 3574 7.8.3.1. Usage Example 3576 With the following list: 3578 list server { 3579 key "name"; 3580 unique "ip port"; 3581 leaf name { 3582 type string; 3583 } 3584 leaf ip { 3585 type inet:ip-address; 3586 } 3587 leaf port { 3588 type inet:port-number; 3589 } 3590 } 3592 The following configuration is not valid: 3594 3595 smtp 3596 192.0.2.1 3597 25 3598 3600 3601 http 3602 192.0.2.1 3603 25 3604 3606 The following configuration is valid, since the "http" and "ftp" list 3607 entries do not have a value for all referenced leafs, and are thus 3608 not taken into account when the "unique" constraint is enforced: 3610 3611 smtp 3612 192.0.2.1 3613 25 3614 3616 3617 http 3618 192.0.2.1 3619 3621 3622 ftp 3623 192.0.2.1 3624 3626 7.8.4. The list's Child Node Statements 3628 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3629 "choice", "anydata", and "anyxml" statements can be used to define 3630 child nodes to the list. 3632 7.8.5. XML Encoding Rules 3634 A list is encoded as a series of XML elements, one for each entry in 3635 the list. Each element's local name is the list's identifier, and 3636 its namespace is the module's XML namespace (see Section 7.1.3). 3638 The list's key nodes are encoded as subelements to the list's 3639 identifier element, in the same order as they are defined within the 3640 "key" statement. 3642 The rest of the list's child nodes are encoded as subelements to the 3643 list element, after the keys. If the list defines RPC or action 3644 input or output parameters, the subelements are encoded in the same 3645 order as they are defined within the "list" statement. Otherwise, 3646 the subelements are encoded in any order. 3648 The XML elements representing list entries MUST appear in the order 3649 specified by the user if the list is "ordered-by user", otherwise the 3650 order is implementation-dependent. The XML elements representing 3651 list entries MAY be interleaved with other sibling elements, unless 3652 the list defines RPC or action input or output parameters. 3654 7.8.6. NETCONF Operations 3656 List entries can be created, deleted, replaced, and modified through 3657 , by using the "operation" attribute in the list's XML 3658 element. In each case, the values of all keys are used to uniquely 3659 identify a list entry. If all keys are not specified for a list 3660 entry, a "missing-element" error is returned. 3662 In an "ordered-by user" list, the attributes "insert" and "key" in 3663 the YANG XML namespace (Section 5.3.1) can be used to control where 3664 in the list the entry is inserted. These can be used during "create" 3665 operations to insert a new list entry, or during "merge" or "replace" 3666 operations to insert a new list entry or move an existing one. 3668 The "insert" attribute can take the values "first", "last", "before", 3669 and "after". If the value is "before" or "after", the "key" 3670 attribute MUST also be used, to specify an existing element in the 3671 list. The value of the "key" attribute is the key predicates of the 3672 full instance identifier (see Section 9.13) for the list entry. 3674 If no "insert" attribute is present in the "create" operation, it 3675 defaults to "last". 3677 If several entries in an "ordered-by user" list are modified in the 3678 same request, the entries are modified one at the time, 3679 in the order of the XML elements in the request. 3681 In a , or an with a "replace" operation 3682 that covers the entire list, the list entry order is the same as the 3683 order of the XML elements in the request. 3685 When a NETCONF server processes an request, the 3686 elements of procedure for a list node are: 3688 If the operation is "merge" or "replace", the list entry is 3689 created if it does not exist. If the list entry already exists 3690 and the "insert" and "key" attributes are present, the list entry 3691 is moved according to the values of the "insert" and "key" 3692 attributes. If the list entry exists and the "insert" and "key" 3693 attributes are not present, the list entry is not moved. 3695 If the operation is "create", the list entry is created if it does 3696 not exist. If the list entry already exists, a "data-exists" 3697 error is returned. 3699 If the operation is "delete", the entry is deleted from the list 3700 if it exists. If the list entry does not exist, a "data-missing" 3701 error is returned. 3703 7.8.7. Usage Example 3705 Given the following list: 3707 list user { 3708 key "name"; 3709 config true; 3710 description 3711 "This is a list of users in the system."; 3713 leaf name { 3714 type string; 3715 } 3716 leaf type { 3717 type string; 3718 } 3719 leaf full-name { 3720 type string; 3721 } 3722 } 3724 A corresponding XML instance example: 3726 3727 fred 3728 admin 3729 Fred Flintstone 3730 3732 To create a new user "barney": 3734 3737 3738 3739 3740 3741 3742 3743 3744 barney 3745 admin 3746 Barney Rubble 3747 3748 3749 3750 3751 3753 To change the type of "fred" to "superuser": 3755 3758 3759 3760 3761 3762 3763 3764 3765 fred 3766 superuser 3767 3768 3769 3770 3771 3773 Given the following ordered-by user list: 3775 list user { 3776 description 3777 "This is a list of users in the system."; 3778 ordered-by user; 3779 config true; 3781 key "first-name surname"; 3783 leaf first-name { 3784 type string; 3785 } 3786 leaf surname { 3787 type string; 3788 } 3789 leaf type { 3790 type string; 3791 } 3792 } 3794 The following would be used to insert a new user "barney rubble" 3795 after the user "fred flintstone": 3797 3801 3802 3803 3804 3805 3806 3808 3812 barney 3813 rubble 3814 admin 3815 3816 3817 3818 3819 3821 The following would be used to move the user "barney rubble" before 3822 the user "fred flintstone": 3824 3828 3829 3830 3831 3832 3833 3835 3839 barney 3840 rubble 3841 3842 3843 3844 3845 3847 7.9. The choice Statement 3849 The "choice" statement defines a set of alternatives, only one of 3850 which may exist at any one time. The argument is an identifier, 3851 followed by a block of substatements that holds detailed choice 3852 information. The identifier is used to identify the choice node in 3853 the schema tree. A choice node does not exist in the data tree. 3855 A choice consists of a number of branches, defined with the "case" 3856 substatement. Each branch contains a number of child nodes. The 3857 nodes from at most one of the choice's branches exist at the same 3858 time. 3860 Since only one of the choice's cases can be valid at any time, the 3861 creation of a node from one case implicitly deletes all nodes from 3862 all other cases. If a request creates a node from a case, the server 3863 will delete any existing nodes that are defined in other cases inside 3864 the choice. 3866 7.9.1. The choice's Substatements 3867 +--------------+---------+-------------+ 3868 | substatement | section | cardinality | 3869 +--------------+---------+-------------+ 3870 | anydata | 7.10 | 0..n | 3871 | anyxml | 7.11 | 0..n | 3872 | case | 7.9.2 | 0..n | 3873 | choice | 7.9 | 0..n | 3874 | config | 7.21.1 | 0..1 | 3875 | container | 7.5 | 0..n | 3876 | default | 7.9.3 | 0..1 | 3877 | description | 7.21.3 | 0..1 | 3878 | if-feature | 7.20.2 | 0..n | 3879 | leaf | 7.6 | 0..n | 3880 | leaf-list | 7.7 | 0..n | 3881 | list | 7.8 | 0..n | 3882 | mandatory | 7.9.4 | 0..1 | 3883 | reference | 7.21.4 | 0..1 | 3884 | status | 7.21.2 | 0..1 | 3885 | when | 7.21.5 | 0..1 | 3886 +--------------+---------+-------------+ 3888 7.9.2. The choice's case Statement 3890 The "case" statement is used to define branches of the choice. It 3891 takes as an argument an identifier, followed by a block of 3892 substatements that holds detailed case information. 3894 The identifier is used to identify the case node in the schema tree. 3895 A case node does not exist in the data tree. 3897 Within a "case" statement, the "anydata", "anyxml", "choice", 3898 "container", "leaf", "list", "leaf-list", and "uses" statements can 3899 be used to define child nodes to the case node. The identifiers of 3900 all these child nodes MUST be unique within all cases in a choice. 3901 For example, the following is illegal: 3903 choice interface-type { // This example is illegal YANG 3904 case a { 3905 leaf ethernet { ... } 3906 } 3907 case b { 3908 container ethernet { ...} 3909 } 3910 } 3912 As a shorthand, the "case" statement can be omitted if the branch 3913 contains a single "anydata", "anyxml", "choice", "container", "leaf", 3914 "list", or "leaf-list" statement. In this case, the case node still 3915 exists in the schema tree, and its identifier is the same as the 3916 identifier in the branch statement. Schema node identifiers 3917 (Section 6.5) MUST always explicitly include case node identifiers. 3918 The following example: 3920 choice interface-type { 3921 container ethernet { ... } 3922 } 3924 is equivalent to: 3926 choice interface-type { 3927 case ethernet { 3928 container ethernet { ... } 3929 } 3930 } 3932 The case identifier MUST be unique within a choice. 3934 7.9.2.1. The case's Substatements 3936 +--------------+---------+-------------+ 3937 | substatement | section | cardinality | 3938 +--------------+---------+-------------+ 3939 | anydata | 7.10 | 0..n | 3940 | anyxml | 7.11 | 0..n | 3941 | choice | 7.9 | 0..n | 3942 | container | 7.5 | 0..n | 3943 | description | 7.21.3 | 0..1 | 3944 | if-feature | 7.20.2 | 0..n | 3945 | leaf | 7.6 | 0..n | 3946 | leaf-list | 7.7 | 0..n | 3947 | list | 7.8 | 0..n | 3948 | reference | 7.21.4 | 0..1 | 3949 | status | 7.21.2 | 0..1 | 3950 | uses | 7.13 | 0..n | 3951 | when | 7.21.5 | 0..1 | 3952 +--------------+---------+-------------+ 3954 7.9.3. The choice's default Statement 3956 The "default" statement indicates if a case should be considered as 3957 the default if no child nodes from any of the choice's cases exist. 3958 The argument is the identifier of the "case" statement. If the 3959 "default" statement is missing, there is no default case. 3961 The "default" statement MUST NOT be present on choices where 3962 "mandatory" is true. 3964 The default case is only important when considering the default 3965 statements of nodes under the cases (i.e., default values of leafs 3966 and leaf-lists, and default cases of nested choices). The default 3967 values and nested default cases under the default case are used if 3968 none of the nodes under any of the cases are present. 3970 There MUST NOT be any mandatory nodes (Section 3) directly under the 3971 default case. 3973 Default values for child nodes under a case are only used if one of 3974 the nodes under that case is present, or if that case is the default 3975 case. If none of the nodes under a case are present and the case is 3976 not the default case, the default values of the cases' child nodes 3977 are ignored. 3979 In this example, the choice defaults to "interval", and the default 3980 value will be used if none of "daily", "time-of-day", or "manual" are 3981 present. If "daily" is present, the default value for "time-of-day" 3982 will be used. 3984 container transfer { 3985 choice how { 3986 default interval; 3987 case interval { 3988 leaf interval { 3989 type uint16; 3990 units minutes; 3991 default 30; 3992 } 3993 } 3994 case daily { 3995 leaf daily { 3996 type empty; 3997 } 3998 leaf time-of-day { 3999 type string; 4000 units 24-hour-clock; 4001 default "01.00"; 4002 } 4003 } 4004 case manual { 4005 leaf manual { 4006 type empty; 4007 } 4008 } 4009 } 4010 } 4012 7.9.4. The choice's mandatory Statement 4014 The "mandatory" statement, which is optional, takes as an argument 4015 the string "true" or "false", and puts a constraint on valid data. 4016 If "mandatory" is "true", at least one node from exactly one of the 4017 choice's case branches MUST exist. 4019 If not specified, the default is "false". 4021 The behavior of the constraint depends on the type of the choice's 4022 closest ancestor node in the schema tree that is not a non-presence- 4023 container (see Section 7.5.1): 4025 o If this ancestor is a case node, the constraint is enforced if any 4026 other node from the case exists. 4028 o Otherwise, it is enforced if the ancestor node exists. 4030 The constraint is further enforced according to the rules in 4031 Section 8. 4033 7.9.5. XML Encoding Rules 4035 The choice and case nodes are not visible in XML. 4037 The child nodes of the selected "case" statement MUST be encoded in 4038 the same order as they are defined in the "case" statement if they 4039 are part of an RPC or action input or output parameter definition. 4040 Otherwise, the subelements are encoded in any order. 4042 7.9.6. Usage Example 4044 Given the following choice: 4046 container protocol { 4047 choice name { 4048 case a { 4049 leaf udp { 4050 type empty; 4051 } 4052 } 4053 case b { 4054 leaf tcp { 4055 type empty; 4056 } 4057 } 4058 } 4059 } 4061 A corresponding XML instance example: 4063 4064 4065 4067 To change the protocol from tcp to udp: 4069 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4086 7.10. The anydata Statement 4088 The "anydata" statement defines an interior node in the schema tree. 4089 It takes one argument, which is an identifier, followed by a block of 4090 substatements that holds detailed anydata information. 4092 The "anydata" statement is used to represent an unknown set of nodes 4093 that can be modelled with YANG, except anyxml, but for which the data 4094 model is not known at module design time. It is possible, though not 4095 required, for the data model for "anydata" content to become known 4096 through protocol signalling or other means that are outside the scope 4097 of this document. 4099 An example of where anydata can be useful is a list of received 4100 notifications, where the exact notifications are not known at design 4101 time. 4103 An anydata node cannot be augmented (see Section 7.17). 4105 An anydata node exists in zero or one instances in the data tree. 4107 An implementation may or may not know the data model used to model a 4108 specific instance of an anydata node. 4110 Since the use of anydata limits the manipulation of the content, it 4111 is RECOMMENDED that the "anydata" statement not be used to define 4112 configuration data. 4114 7.10.1. The anydata's Substatements 4116 +--------------+---------+-------------+ 4117 | substatement | section | cardinality | 4118 +--------------+---------+-------------+ 4119 | config | 7.21.1 | 0..1 | 4120 | description | 7.21.3 | 0..1 | 4121 | if-feature | 7.20.2 | 0..n | 4122 | mandatory | 7.6.5 | 0..1 | 4123 | must | 7.5.3 | 0..n | 4124 | reference | 7.21.4 | 0..1 | 4125 | status | 7.21.2 | 0..1 | 4126 | when | 7.21.5 | 0..1 | 4127 +--------------+---------+-------------+ 4129 7.10.2. XML Encoding Rules 4131 An anydata node is encoded as an XML element. The element's local 4132 name is the anydata's identifier, and its namespace is the module's 4133 XML namespace (see Section 7.1.3). The value of the anydata node is 4134 a set of nodes, which are encoded as XML subelements to the anydata 4135 element. 4137 7.10.3. NETCONF Operations 4139 An anydata node is treated as an opaque chunk of data. This data can 4140 be modified in its entirety only. 4142 Any "operation" attributes present on subelements of an anydata node 4143 are ignored by the NETCONF server. 4145 When a NETCONF server processes an request, the 4146 elements of procedure for the anydata node are: 4148 If the operation is "merge" or "replace", the node is created if 4149 it does not exist, and its value is set to the subelements of the 4150 anydata node found in the XML RPC data. 4152 If the operation is "create", the node is created if it does not 4153 exist, and its value is set to the subelements of the anydata node 4154 found in the XML RPC data. If the node already exists, a 4155 "data-exists" error is returned. 4157 If the operation is "delete", the node is deleted if it exists. 4158 If the node does not exist, a "data-missing" error is returned. 4160 7.10.4. Usage Example 4162 Given the following "anydata" statement: 4164 list logged-notification { 4165 key time; 4166 leaf time { 4167 type yang:date-and-time; 4168 } 4169 anydata data; 4170 } 4172 The following is a valid encoding of such a list instance: 4174 4175 4176 4177 4179 2014-07-29T13:43:01Z 4180 4181 fault 4182 4183 Ethernet0 4184 4185 major 4186 4187 4188 4190 7.11. The anyxml Statement 4192 The "anyxml" statement defines an interior node in the schema tree. 4193 It takes one argument, which is an identifier, followed by a block of 4194 substatements that holds detailed anyxml information. 4196 The "anyxml" statement is used to represent an unknown chunk of XML. 4197 No restrictions are placed on the XML. This can be useful, for 4198 example, in RPC replies. An example is the parameter in the 4199 operation in NETCONF. 4201 An anyxml node cannot be augmented (see Section 7.17). 4203 An anyxml node exists in zero or one instances in the data tree. 4205 Since the use of anyxml limits the manipulation of the content, it is 4206 RECOMMENDED that the "anyxml" statement not be used to define 4207 configuration data. 4209 It should be noted that in YANG version 1, anyxml was the only 4210 statement that could model an unknown hierarchy of data. In many 4211 cases this unknown hierarchy of data is actually modelled in YANG, 4212 but the exact YANG model is not known at design time. In these 4213 situations, it is RECOMMENDED to use anydata (Section 7.10) instead 4214 of anyxml. 4216 7.11.1. The anyxml's Substatements 4218 +--------------+---------+-------------+ 4219 | substatement | section | cardinality | 4220 +--------------+---------+-------------+ 4221 | config | 7.21.1 | 0..1 | 4222 | description | 7.21.3 | 0..1 | 4223 | if-feature | 7.20.2 | 0..n | 4224 | mandatory | 7.6.5 | 0..1 | 4225 | must | 7.5.3 | 0..n | 4226 | reference | 7.21.4 | 0..1 | 4227 | status | 7.21.2 | 0..1 | 4228 | when | 7.21.5 | 0..1 | 4229 +--------------+---------+-------------+ 4231 7.11.2. XML Encoding Rules 4233 An anyxml node is encoded as an XML element. The element's local 4234 name is the anyxml's identifier, and its namespace is the module's 4235 XML namespace (see Section 7.1.3). The value of the anyxml node is 4236 encoded as XML content of this element. 4238 Note that any XML prefixes used in the encoding are local to each 4239 instance encoding. This means that the same XML may be encoded 4240 differently by different implementations. 4242 7.11.3. NETCONF Operations 4244 An anyxml node is treated as an opaque chunk of data. This data can 4245 be modified in its entirety only. 4247 Any "operation" attributes present on subelements of an anyxml node 4248 are ignored by the NETCONF server. 4250 When a NETCONF server processes an request, the 4251 elements of procedure for the anyxml node are: 4253 If the operation is "merge" or "replace", the node is created if 4254 it does not exist, and its value is set to the XML content of the 4255 anyxml node found in the XML RPC data. 4257 If the operation is "create", the node is created if it does not 4258 exist, and its value is set to the XML content of the anyxml node 4259 found in the XML RPC data. If the node already exists, a 4260 "data-exists" error is returned. 4262 If the operation is "delete", the node is deleted if it exists. 4263 If the node does not exist, a "data-missing" error is returned. 4265 7.11.4. Usage Example 4267 Given the following "anyxml" statement: 4269 anyxml html-info; 4271 The following are two valid encodings of the same anyxml value: 4273 4274

4275 This is very cool. 4276

4277 4279 4280 4281 This is very cool. 4282 4283 4285 7.12. The grouping Statement 4287 The "grouping" statement is used to define a reusable block of nodes, 4288 which may be used locally in the module or submodule, and by other 4289 modules that import from it, according to the rules in Section 5.5. 4290 It takes one argument, which is an identifier, followed by a block of 4291 substatements that holds detailed grouping information. 4293 The "grouping" statement is not a data definition statement and, as 4294 such, does not define any nodes in the schema tree. 4296 A grouping is like a "structure" or a "record" in conventional 4297 programming languages. 4299 Once a grouping is defined, it can be referenced in a "uses" 4300 statement (see Section 7.13). A grouping MUST NOT reference itself, 4301 neither directly nor indirectly through a chain of other groupings. 4303 If the grouping is defined at the top level of a YANG module or 4304 submodule, the grouping's identifier MUST be unique within the 4305 module. 4307 A grouping is more than just a mechanism for textual substitution, 4308 but defines a collection of nodes. Identifiers appearing inside the 4309 grouping are resolved relative to the scope in which the grouping is 4310 defined, not where it is used. Prefix mappings, type names, grouping 4311 names, and extension usage are evaluated in the hierarchy where the 4312 "grouping" statement appears. For extensions, this means that 4313 extensions defined as direct children to a "grouping" statement are 4314 applied to the grouping itself. 4316 Note that if a grouping defines an "action" or a "notification" node 4317 in its hierarchy, then it cannot be used in all contexts. For 4318 example, it cannot be used in an rpc definition. See Section 7.15 4319 and Section 7.16. 4321 7.12.1. The grouping's Substatements 4323 +--------------+---------+-------------+ 4324 | substatement | section | cardinality | 4325 +--------------+---------+-------------+ 4326 | action | 7.15 | 0..n | 4327 | anydata | 7.10 | 0..n | 4328 | anyxml | 7.11 | 0..n | 4329 | choice | 7.9 | 0..n | 4330 | container | 7.5 | 0..n | 4331 | description | 7.21.3 | 0..1 | 4332 | grouping | 7.12 | 0..n | 4333 | leaf | 7.6 | 0..n | 4334 | leaf-list | 7.7 | 0..n | 4335 | list | 7.8 | 0..n | 4336 | notification | 7.16 | 0..n | 4337 | reference | 7.21.4 | 0..1 | 4338 | status | 7.21.2 | 0..1 | 4339 | typedef | 7.3 | 0..n | 4340 | uses | 7.13 | 0..n | 4341 +--------------+---------+-------------+ 4343 7.12.2. Usage Example 4345 import ietf-inet-types { 4346 prefix "inet"; 4347 } 4349 grouping endpoint { 4350 description "A reusable endpoint group."; 4351 leaf ip { 4352 type inet:ip-address; 4353 } 4354 leaf port { 4355 type inet:port-number; 4356 } 4357 } 4359 7.13. The uses Statement 4361 The "uses" statement is used to reference a "grouping" definition. 4362 It takes one argument, which is the name of the grouping. 4364 The effect of a "uses" reference to a grouping is that the nodes 4365 defined by the grouping are copied into the current schema tree, and 4366 then updated according to the "refine" and "augment" statements. 4368 The identifiers defined in the grouping are not bound to a namespace 4369 until the contents of the grouping are added to the schema tree via a 4370 "uses" statement that does not appear inside a "grouping" statement, 4371 at which point they are bound to the namespace of the current module. 4373 7.13.1. The uses's Substatements 4375 +--------------+---------+-------------+ 4376 | substatement | section | cardinality | 4377 +--------------+---------+-------------+ 4378 | augment | 7.17 | 0..n | 4379 | description | 7.21.3 | 0..1 | 4380 | if-feature | 7.20.2 | 0..n | 4381 | refine | 7.13.2 | 0..n | 4382 | reference | 7.21.4 | 0..1 | 4383 | status | 7.21.2 | 0..1 | 4384 | when | 7.21.5 | 0..1 | 4385 +--------------+---------+-------------+ 4387 7.13.2. The refine Statement 4389 Some of the properties of each node in the grouping can be refined 4390 with the "refine" statement. The argument is a string that 4391 identifies a node in the grouping. This node is called the refine's 4392 target node. If a node in the grouping is not present as a target 4393 node of a "refine" statement, it is not refined, and thus used 4394 exactly as it was defined in the grouping. 4396 The argument string is a descendant schema node identifier (see 4397 Section 6.5). 4399 The following refinements can be done: 4401 o A leaf or choice node may get a default value, or a new default 4402 value if it already had one. 4404 o A leaf-list node may get a set of default values, or a new set of 4405 default values if it already had defaults; i.e., the set of 4406 refined default values replaces the defaults already given. 4408 o Any node may get a specialized "description" string. 4410 o Any node may get a specialized "reference" string. 4412 o Any node may get a different "config" statement. 4414 o A leaf, anydata, anyxml, or choice node may get a different 4415 "mandatory" statement. 4417 o A container node may get a "presence" statement. 4419 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4420 get additional "must" expressions. 4422 o A leaf-list or list node may get a different "min-elements" or 4423 "max-elements" statement. 4425 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4426 get additional "if-feature" expressions. 4428 o Any node can get refined extensions, if the extension allows 4429 refinement. See Section 7.19 for details. 4431 7.13.3. XML Encoding Rules 4433 Each node in the grouping is encoded as if it was defined inline, 4434 even if it is imported from another module with another XML 4435 namespace. 4437 7.13.4. Usage Example 4439 To use the "endpoint" grouping defined in Section 7.12.2 in a 4440 definition of an HTTP server in some other module, we can do: 4442 import example-system { 4443 prefix "sys"; 4444 } 4446 container http-server { 4447 leaf name { 4448 type string; 4449 } 4450 uses sys:endpoint; 4451 } 4453 A corresponding XML instance example: 4455 4456 extern-web 4457 192.0.2.1 4458 80 4459 4461 If port 80 should be the default for the HTTP server, default can be 4462 added: 4464 container http-server { 4465 leaf name { 4466 type string; 4467 } 4468 uses sys:endpoint { 4469 refine port { 4470 default 80; 4471 } 4472 } 4473 } 4475 If we want to define a list of servers, and each server has the ip 4476 and port as keys, we can do: 4478 list server { 4479 key "ip port"; 4480 leaf name { 4481 type string; 4482 } 4483 uses sys:endpoint; 4484 } 4486 The following is an error: 4488 container http-server { 4489 uses sys:endpoint; 4490 leaf ip { // illegal - same identifier "ip" used twice 4491 type string; 4492 } 4493 } 4495 7.14. The rpc Statement 4497 The "rpc" statement is used to define an RPC operation. It takes one 4498 argument, which is an identifier, followed by a block of 4499 substatements that holds detailed rpc information. This argument is 4500 the name of the RPC. 4502 The "rpc" statement defines an rpc node in the schema tree. Under 4503 the rpc node, a schema node with the name "input", and a schema node 4504 with the name "output" are also defined. The nodes "input" and 4505 "output" are defined in the module's namespace. 4507 7.14.1. The rpc's Substatements 4509 +--------------+---------+-------------+ 4510 | substatement | section | cardinality | 4511 +--------------+---------+-------------+ 4512 | description | 7.21.3 | 0..1 | 4513 | grouping | 7.12 | 0..n | 4514 | if-feature | 7.20.2 | 0..n | 4515 | input | 7.14.2 | 0..1 | 4516 | output | 7.14.3 | 0..1 | 4517 | reference | 7.21.4 | 0..1 | 4518 | status | 7.21.2 | 0..1 | 4519 | typedef | 7.3 | 0..n | 4520 +--------------+---------+-------------+ 4522 7.14.2. The input Statement 4524 The "input" statement, which is optional, is used to define input 4525 parameters to the operation. It does not take an argument. The 4526 substatements to "input" define nodes under the operation's input 4527 node. 4529 If a leaf in the input tree has a "mandatory" statement with the 4530 value "true", the leaf MUST be present in an RPC invocation. 4532 If a leaf in the input tree has a default value, the server MUST use 4533 this value in the same cases as described in Section 7.6.1. In these 4534 cases, the server MUST operationally behave as if the leaf was 4535 present in the RPC invocation with the default value as its value. 4537 If a leaf-list in the input tree has one or more default values, the 4538 server MUST use these values in the same cases as described in 4539 Section 7.7.2. In these cases, the server MUST operationally behave 4540 as if the leaf-list was present in the RPC invocation with the 4541 default values as its values. 4543 If a "config" statement is present for any node in the input tree, 4544 the "config" statement is ignored. 4546 If any node has a "when" statement that would evaluate to false, then 4547 this node MUST NOT be present in the input tree. 4549 7.14.2.1. The input's Substatements 4551 +--------------+---------+-------------+ 4552 | substatement | section | cardinality | 4553 +--------------+---------+-------------+ 4554 | anydata | 7.10 | 0..n | 4555 | anyxml | 7.11 | 0..n | 4556 | choice | 7.9 | 0..n | 4557 | container | 7.5 | 0..n | 4558 | grouping | 7.12 | 0..n | 4559 | leaf | 7.6 | 0..n | 4560 | leaf-list | 7.7 | 0..n | 4561 | list | 7.8 | 0..n | 4562 | must | 7.5.3 | 0..n | 4563 | typedef | 7.3 | 0..n | 4564 | uses | 7.13 | 0..n | 4565 +--------------+---------+-------------+ 4567 7.14.3. The output Statement 4569 The "output" statement, which is optional, is used to define output 4570 parameters to the RPC operation. It does not take an argument. The 4571 substatements to "output" define nodes under the operation's output 4572 node. 4574 If a leaf in the output tree has a "mandatory" statement with the 4575 value "true", the leaf MUST be present in an RPC reply. 4577 If a leaf in the output tree has a default value, the client MUST use 4578 this value in the same cases as described in Section 7.6.1. In these 4579 cases, the client MUST operationally behave as if the leaf was 4580 present in the RPC reply with the default value as its value. 4582 If a leaf-list in the output tree has one or more default values, the 4583 client MUST use these values in the same cases as described in 4584 Section 7.7.2. In these cases, the client MUST operationally behave 4585 as if the leaf-list was present in the RPC reply with the default 4586 values as its values. 4588 If a "config" statement is present for any node in the output tree, 4589 the "config" statement is ignored. 4591 If any node has a "when" statement that would evaluate to false, then 4592 this node MUST NOT be present in the output tree. 4594 7.14.3.1. The output's Substatements 4596 +--------------+---------+-------------+ 4597 | substatement | section | cardinality | 4598 +--------------+---------+-------------+ 4599 | anydata | 7.10 | 0..n | 4600 | anyxml | 7.11 | 0..n | 4601 | choice | 7.9 | 0..n | 4602 | container | 7.5 | 0..n | 4603 | grouping | 7.12 | 0..n | 4604 | leaf | 7.6 | 0..n | 4605 | leaf-list | 7.7 | 0..n | 4606 | list | 7.8 | 0..n | 4607 | must | 7.5.3 | 0..n | 4608 | typedef | 7.3 | 0..n | 4609 | uses | 7.13 | 0..n | 4610 +--------------+---------+-------------+ 4612 7.14.4. NETCONF XML Encoding Rules 4614 An rpc node is encoded as a child XML element to the element, 4615 as designated by the substitution group "rpcOperation" in [RFC6241]. 4616 The element's local name is the rpc's identifier, and its namespace 4617 is the module's XML namespace (see Section 7.1.3). 4619 Input parameters are encoded as child XML elements to the rpc node's 4620 XML element, in the same order as they are defined within the "input" 4621 statement. 4623 If the RPC operation invocation succeeded, and no output parameters 4624 are returned, the contains a single element defined 4625 in [RFC6241]. If output parameters are returned, they are encoded as 4626 child elements to the element defined in [RFC6241], in 4627 the same order as they are defined within the "output" statement. 4629 7.14.5. Usage Example 4631 The following example defines an RPC operation: 4633 module example-rock { 4634 yang-version 1.1; 4635 namespace "urn:example:rock"; 4636 prefix "rock"; 4638 rpc rock-the-house { 4639 input { 4640 leaf zip-code { 4641 type string; 4642 } 4643 } 4644 } 4645 } 4647 A corresponding XML instance example of the complete rpc and rpc- 4648 reply: 4650 4652 4653 27606-0100 4654 4655 4657 4659 4660 4662 7.15. The action Statement 4664 The "action" statement is used to define an operation connected to a 4665 specific container or list data node. It takes one argument, which 4666 is an identifier, followed by a block of substatements that holds 4667 detailed action information. The argument is the name of the action. 4669 The "action" statement defines an action node in the schema tree. 4670 Under the action node, a schema node with the name "input", and a 4671 schema node with the name "output" are also defined. The nodes 4672 "input" and "output" are defined in the module's namespace. 4674 An action MUST NOT be defined within an rpc, another action or a 4675 notification, i.e., an action node MUST NOT have an rpc, action, or a 4676 notification node as one of its ancestors in the schema tree. For 4677 example, this means that it is an error if a grouping that contains 4678 an action somewhere in its node hierarchy is used in a notification 4679 definition. 4681 Since an action cannot be defined an the top-level of a module or in 4682 a case statement, it is an error if a grouping that contains an 4683 action at the top of its node hierarchy is used at the top-level of a 4684 module or in a case definition. 4686 The difference between an action and an rpc is that an action is tied 4687 to a node in the datastore, whereas an rpc is not. When an action is 4688 invoked, the node in the datastore is specified along with the name 4689 of the action and the input parameters. 4691 7.15.1. The action's Substatements 4692 +--------------+---------+-------------+ 4693 | substatement | section | cardinality | 4694 +--------------+---------+-------------+ 4695 | description | 7.21.3 | 0..1 | 4696 | grouping | 7.12 | 0..n | 4697 | if-feature | 7.20.2 | 0..n | 4698 | input | 7.14.2 | 0..1 | 4699 | output | 7.14.3 | 0..1 | 4700 | reference | 7.21.4 | 0..1 | 4701 | status | 7.21.2 | 0..1 | 4702 | typedef | 7.3 | 0..n | 4703 +--------------+---------+-------------+ 4705 7.15.2. NETCONF XML Encoding Rules 4707 When an action is invoked, an element with the local name "action" in 4708 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4709 encoded as a child XML element to the element defined in 4710 [RFC6241], as designated by the substitution group "rpcOperation" in 4711 [RFC6241]. 4713 The "action" element contains an hierarchy of nodes that identifies 4714 the node in the datastore. It MUST contain all containers and list 4715 nodes from the top level down to the list or container containing the 4716 action. For lists, all key leafs MUST also be included. The last 4717 container or list contains an XML element that carries the name of 4718 the defined action. Within this element the input parameters are 4719 encoded as child XML elements, in the same order as they are defined 4720 within the "input" statement. 4722 Only one action can be invoked in one . If more than one action 4723 is present in the , the server MUST reply with an "bad-element" 4724 error-tag in the . 4726 If the action operation invocation succeeded, and no output 4727 parameters are returned, the contains a single 4728 element defined in [RFC6241]. If output parameters are returned, 4729 they are encoded as child elements to the element defined 4730 in [RFC6241], in the same order as they are defined within the 4731 "output" statement. 4733 7.15.3. Usage Example 4735 The following example defines an action to reset one server at a 4736 server farm: 4738 module example-server-farm { 4739 yang-version 1.1; 4740 namespace "urn:example:server-farm"; 4741 prefix "sfarm"; 4743 import ietf-yang-types { 4744 prefix "yang"; 4745 } 4747 list server { 4748 key name; 4749 leaf name { 4750 type string; 4751 } 4752 action reset { 4753 input { 4754 leaf reset-at { 4755 type yang:date-and-time; 4756 mandatory true; 4757 } 4758 } 4759 output { 4760 leaf reset-finished-at { 4761 type yang:date-and-time; 4762 mandatory true; 4763 } 4764 } 4765 } 4766 } 4767 } 4769 A corresponding XML instance example of the complete rpc and rpc- 4770 reply: 4772 4774 4775 4776 apache-1 4777 4778 2014-07-29T13:42:00Z 4779 4780 4781 4782 4784 4786 4787 2014-07-29T13:42:12Z 4788 4789 4791 7.16. The notification Statement 4793 The "notification" statement is used to define a notification. It 4794 takes one argument, which is an identifier, followed by a block of 4795 substatements that holds detailed notification information. The 4796 "notification" statement defines a notification node in the schema 4797 tree. 4799 A notification can be defined at the top-level of a module, or 4800 connected to a specific container or list data node in the schema 4801 tree. 4803 A notification MUST NOT be defined within an rpc, action or another 4804 notification, i.e., a notification node MUST NOT have an rpc, action, 4805 or a notification node as one of its ancestors in the schema tree. 4806 For example, this means that it is an error if a grouping that 4807 contains an notification somewhere in its node hierarchy is used in 4808 an rpc definition. 4810 Since a notification cannot be defined in a case statement, it is an 4811 error if a grouping that contains a notification at the top of its 4812 node hierarchy is used in a case definition. 4814 If a leaf in the notification tree has a "mandatory" statement with 4815 the value "true", the leaf MUST be present in a notification 4816 instance. 4818 If a leaf in the notification tree has a default value, the client 4819 MUST use this value in the same cases as described in Section 7.6.1. 4821 In these cases, the client MUST operationally behave as if the leaf 4822 was present in the notification instance with the default value as 4823 its value. 4825 If a leaf-list in the notification tree has one or more default 4826 values, the client MUST use these values in the same cases as 4827 described in Section 7.7.2. In these cases, the client MUST 4828 operationally behave as if the leaf-list was present in the 4829 notification instance with the default values as its values. 4831 If a "config" statement is present for any node in the notification 4832 tree, the "config" statement is ignored. 4834 7.16.1. The notification's Substatements 4836 +--------------+---------+-------------+ 4837 | substatement | section | cardinality | 4838 +--------------+---------+-------------+ 4839 | anydata | 7.10 | 0..n | 4840 | anyxml | 7.11 | 0..n | 4841 | choice | 7.9 | 0..n | 4842 | container | 7.5 | 0..n | 4843 | description | 7.21.3 | 0..1 | 4844 | grouping | 7.12 | 0..n | 4845 | if-feature | 7.20.2 | 0..n | 4846 | leaf | 7.6 | 0..n | 4847 | leaf-list | 7.7 | 0..n | 4848 | list | 7.8 | 0..n | 4849 | must | 7.5.3 | 0..n | 4850 | reference | 7.21.4 | 0..1 | 4851 | status | 7.21.2 | 0..1 | 4852 | typedef | 7.3 | 0..n | 4853 | uses | 7.13 | 0..n | 4854 +--------------+---------+-------------+ 4856 7.16.2. NETCONF XML Encoding Rules 4858 A notification node that is defined on the top-level of a module is 4859 encoded as a child XML element to the element defined 4860 in NETCONF Event Notifications [RFC5277]. The element's local name 4861 is the notification's identifier, and its namespace is the module's 4862 XML namespace (see Section 7.1.3). 4864 When a notification node is defined as a child to a data node, the 4865 element defined in NETCONF Event Notifications 4866 [RFC5277] contains an hierarchy of nodes that identifies the node in 4867 the datastore. It MUST contain all containers and list nodes from 4868 the top level down to the list or container containing the 4869 notification. For lists, all key leafs MUST also be included. The 4870 last container or list contains an XML element that carries the name 4871 of the defined notification. 4873 The notification's child nodes are encoded as subelements to the 4874 notification node's XML element, in any order. 4876 7.16.3. Usage Example 4878 The following example defines a notification at the top-level of a 4879 module: 4881 module example-event { 4882 yang-version 1.1; 4883 namespace "urn:example:event"; 4884 prefix "ev"; 4886 notification event { 4887 leaf event-class { 4888 type string; 4889 } 4890 leaf reporting-entity { 4891 type instance-identifier; 4892 } 4893 leaf severity { 4894 type string; 4895 } 4896 } 4897 } 4899 A corresponding XML instance example of the complete notification: 4901 4903 2008-07-08T00:01:00Z 4904 4905 fault 4906 4907 /ex:interface[ex:name='Ethernet0'] 4908 4909 major 4910 4911 4913 The following example defines a notification in a data node: 4915 module example-interface-module { 4916 yang-version 1.1; 4917 namespace "urn:example:interface-module"; 4918 prefix "if"; 4920 container interfaces { 4921 list interface { 4922 key "name"; 4923 leaf name { 4924 type string; 4925 } 4926 notification interface-enabled { 4927 leaf by-user { 4928 type string; 4929 } 4930 } 4931 } 4932 } 4933 } 4935 A corresponding XML instance example of the complete notification: 4937 4939 2008-07-08T00:01:00Z 4940 4941 4942 eth1 4943 4944 fred 4945 4946 4947 4948 4950 7.17. The augment Statement 4952 The "augment" statement allows a module or submodule to add to the 4953 schema tree defined in an external module, or the current module and 4954 its submodules, and to add to the nodes from a grouping in a "uses" 4955 statement. The argument is a string that identifies a node in the 4956 schema tree. This node is called the augment's target node. The 4957 target node MUST be either a container, list, choice, case, input, 4958 output, or notification node. It is augmented with the nodes defined 4959 in the substatements that follow the "augment" statement. 4961 The argument string is a schema node identifier (see Section 6.5). 4962 If the "augment" statement is on the top level in a module or 4963 submodule, the absolute form (defined by the rule 4964 "absolute-schema-nodeid" in Section 14) of a schema node identifier 4965 MUST be used. If the "augment" statement is a substatement to the 4966 "uses" statement, the descendant form (defined by the rule 4967 "descendant-schema-nodeid" in Section 14) MUST be used. 4969 If the target node is a container, list, case, input, output, or 4970 notification node, the "container", "leaf", "list", "leaf-list", 4971 "uses", and "choice" statements can be used within the "augment" 4972 statement. 4974 If the target node is a container or list node, the "action" and 4975 "notification" statements can be used within the "augment" statement. 4977 If the target node is a choice node, the "case" statement, or a case 4978 shorthand statement (see Section 7.9.2) can be used within the 4979 "augment" statement. 4981 The "augment" statement MUST NOT add multiple nodes with the same 4982 name from the same module to the target node. 4984 If the augmentation adds mandatory configuration nodes (see 4985 Section 3) to a target node in another module, the augmentation MUST 4986 be conditional with a "when" statement. Care must be taken when 4987 defining the "when" expression, so that clients that do not know 4988 about the augmenting module do not break. 4990 In the following example, it is OK to augment the "interface" entry 4991 with "mandatory-leaf" because the augmentation depends on support for 4992 "some-new-iftype". The old client does not know about this type so 4993 it would never select this type, and therefore not be adding a 4994 mandatory data node. 4996 module example-augment { 4997 namespace "urn:example:augment"; 4998 prefix mymod; 5000 import ietf-interfaces { 5001 prefix if; 5002 } 5004 identity some-new-iftype { 5005 base if:interface-type; 5006 } 5008 augment "/if:interfaces/if:interface" { 5009 when "if:type = 'mymod:some-new-iftype'"; 5011 leaf mandatory-leaf { 5012 mandatory true; 5013 type string; 5014 } 5015 } 5016 } 5018 7.17.1. The augment's Substatements 5020 +--------------+---------+-------------+ 5021 | substatement | section | cardinality | 5022 +--------------+---------+-------------+ 5023 | action | 7.15 | 0..n | 5024 | anydata | 7.10 | 0..n | 5025 | anyxml | 7.11 | 0..n | 5026 | case | 7.9.2 | 0..n | 5027 | choice | 7.9 | 0..n | 5028 | container | 7.5 | 0..n | 5029 | description | 7.21.3 | 0..1 | 5030 | if-feature | 7.20.2 | 0..n | 5031 | leaf | 7.6 | 0..n | 5032 | leaf-list | 7.7 | 0..n | 5033 | list | 7.8 | 0..n | 5034 | notification | 7.16 | 0..n | 5035 | reference | 7.21.4 | 0..1 | 5036 | status | 7.21.2 | 0..1 | 5037 | uses | 7.13 | 0..n | 5038 | when | 7.21.5 | 0..1 | 5039 +--------------+---------+-------------+ 5041 7.17.2. XML Encoding Rules 5043 All data nodes defined in the "augment" statement are defined as XML 5044 elements in the XML namespace of the module where the "augment" is 5045 specified. 5047 When a node is augmented, the augmenting child nodes are encoded as 5048 subelements to the augmented node, in any order. 5050 7.17.3. Usage Example 5052 In namespace urn:example:interface-module, we have: 5054 container interfaces { 5055 list ifEntry { 5056 key "ifIndex"; 5058 leaf ifIndex { 5059 type uint32; 5060 } 5061 leaf ifDescr { 5062 type string; 5063 } 5064 leaf ifType { 5065 type iana:IfType; 5066 } 5067 leaf ifMtu { 5068 type int32; 5069 } 5070 } 5071 } 5073 Then, in namespace urn:example:ds0, we have: 5075 import example-interface-module { 5076 prefix "if"; 5077 } 5078 augment "/if:interfaces/if:ifEntry" { 5079 when "if:ifType='ds0'"; 5080 leaf ds0ChannelNumber { 5081 type ChannelNumber; 5082 } 5083 } 5085 A corresponding XML instance example: 5087 5089 5090 1 5091 Flintstone Inc Ethernet A562 5092 ethernetCsmacd 5093 1500 5094 5095 5096 2 5097 Flintstone Inc DS0 5098 ds0 5099 1 5100 5101 5103 As another example, suppose we have the choice defined in 5104 Section 7.9.6. The following construct can be used to extend the 5105 protocol definition: 5107 augment /ex:system/ex:protocol/ex:name { 5108 case c { 5109 leaf smtp { 5110 type empty; 5111 } 5112 } 5113 } 5115 A corresponding XML instance example: 5117 5118 5119 5120 5121 5123 or 5125 5126 5127 5128 5129 5131 7.18. The identity Statement 5133 The "identity" statement is used to define a new globally unique, 5134 abstract, and untyped identity. Its only purpose is to denote its 5135 name, semantics, and existence. An identity can either be defined 5136 from scratch or derived from one or more base identities. The 5137 identity's argument is an identifier that is the name of the 5138 identity. It is followed by a block of substatements that holds 5139 detailed identity information. 5141 The built-in datatype "identityref" (see Section 9.10) can be used to 5142 reference identities within a data model. 5144 7.18.1. The identity's Substatements 5146 +--------------+---------+-------------+ 5147 | substatement | section | cardinality | 5148 +--------------+---------+-------------+ 5149 | base | 7.18.2 | 0..n | 5150 | description | 7.21.3 | 0..1 | 5151 | if-feature | 7.20.2 | 0..n | 5152 | reference | 7.21.4 | 0..1 | 5153 | status | 7.21.2 | 0..1 | 5154 +--------------+---------+-------------+ 5156 7.18.2. The base Statement 5158 The "base" statement, which is optional, takes as an argument a 5159 string that is the name of an existing identity, from which the new 5160 identity is derived. If no "base" statement is present, the identity 5161 is defined from scratch. If multiple "base" statements are present, 5162 the identity is derived from all of them. 5164 If a prefix is present on the base name, it refers to an identity 5165 defined in the module that was imported with that prefix, or the 5166 local module if the prefix matches the local module's prefix. 5167 Otherwise, an identity with the matching name MUST be defined in the 5168 current module or an included submodule. 5170 An identity MUST NOT reference itself, neither directly nor 5171 indirectly through a chain of other identities. 5173 The derivation of identities has the following properties: 5175 o It is irreflexive, which means that an identity is not derived 5176 from itself. 5178 o It is transitive, which means that if identity B is derived from A 5179 and C is derived from B, then C is also derived from A. 5181 7.18.3. Usage Example 5182 module example-crypto-base { 5183 yang-version 1.1; 5184 namespace "urn:example:crypto-base"; 5185 prefix "crypto"; 5187 identity crypto-alg { 5188 description 5189 "Base identity from which all crypto algorithms 5190 are derived."; 5191 } 5193 identity symmetric-key { 5194 description 5195 "Base identity used to identify symmetric-key crypto 5196 algorithms."; 5197 } 5199 identity public-key { 5200 description 5201 "Base identity used to identify public-key crypto 5202 algorithms."; 5203 } 5204 } 5206 module example-des { 5207 yang-version 1.1; 5208 namespace "urn:example:des"; 5209 prefix "des"; 5211 import "example-crypto-base" { 5212 prefix "crypto"; 5213 } 5215 identity des { 5216 base "crypto:crypto-alg"; 5217 base "crypto:symmetric-key"; 5218 description "DES crypto algorithm"; 5219 } 5221 identity des3 { 5222 base "crypto:crypto-alg"; 5223 base "crypto:symmetric-key"; 5224 description "Triple DES crypto algorithm"; 5225 } 5226 } 5228 7.19. The extension Statement 5230 The "extension" statement allows the definition of new statements 5231 within the YANG language. This new statement definition can be 5232 imported and used by other modules. 5234 The statement's argument is an identifier that is the new keyword for 5235 the extension and must be followed by a block of substatements that 5236 holds detailed extension information. The purpose of the "extension" 5237 statement is to define a keyword, so that it can be imported and used 5238 by other modules. 5240 The extension can be used like a normal YANG statement, with the 5241 statement name followed by an argument if one is defined by the 5242 "extension" statement, and an optional block of substatements. The 5243 statement's name is created by combining the prefix of the module in 5244 which the extension was defined, a colon (":"), and the extension's 5245 keyword, with no interleaving whitespace. The substatements of an 5246 extension are defined by the "extension" statement, using some 5247 mechanism outside the scope of this specification. Syntactically, 5248 the substatements MUST be YANG statements, or also extensions defined 5249 using "extension" statements. YANG statements in extensions MUST 5250 follow the syntactical rules in Section 14. 5252 An extension can allow refinement (see Section 7.13.2) and deviations 5253 (Section 7.20.3.2), but the mechanism for how this is defined is 5254 outside the scope of this specification. 5256 7.19.1. The extension's Substatements 5258 +--------------+---------+-------------+ 5259 | substatement | section | cardinality | 5260 +--------------+---------+-------------+ 5261 | argument | 7.19.2 | 0..1 | 5262 | description | 7.21.3 | 0..1 | 5263 | reference | 7.21.4 | 0..1 | 5264 | status | 7.21.2 | 0..1 | 5265 +--------------+---------+-------------+ 5267 7.19.2. The argument Statement 5269 The "argument" statement, which is optional, takes as an argument a 5270 string that is the name of the argument to the keyword. If no 5271 argument statement is present, the keyword expects no argument when 5272 it is used. 5274 The argument's name is used in the YIN mapping, where it is used as 5275 an XML attribute or element name, depending on the argument's 5276 "yin-element" statement. 5278 7.19.2.1. The argument's Substatements 5280 +--------------+----------+-------------+ 5281 | substatement | section | cardinality | 5282 +--------------+----------+-------------+ 5283 | yin-element | 7.19.2.2 | 0..1 | 5284 +--------------+----------+-------------+ 5286 7.19.2.2. The yin-element Statement 5288 The "yin-element" statement, which is optional, takes as an argument 5289 the string "true" or "false". This statement indicates if the 5290 argument is mapped to an XML element in YIN or to an XML attribute 5291 (see Section 13). 5293 If no "yin-element" statement is present, it defaults to "false". 5295 7.19.3. Usage Example 5297 To define an extension: 5299 module example-extensions { 5300 yang-version 1.1; 5301 ... 5303 extension c-define { 5304 description 5305 "Takes as argument a name string. 5306 Makes the code generator use the given name in the 5307 #define."; 5308 argument "name"; 5309 } 5310 } 5312 To use the extension: 5314 module example-interfaces { 5315 yang-version 1.1; 5317 ... 5318 import example-extensions { 5319 prefix "myext"; 5320 } 5321 ... 5323 container interfaces { 5324 ... 5325 myext:c-define "MY_INTERFACES"; 5326 } 5327 } 5329 7.20. Conformance-Related Statements 5331 This section defines statements related to conformance, as described 5332 in Section 5.6. 5334 7.20.1. The feature Statement 5336 The "feature" statement is used to define a mechanism by which 5337 portions of the schema are marked as conditional. A feature name is 5338 defined that can later be referenced using the "if-feature" statement 5339 (see Section 7.20.2). Schema nodes tagged with an "if-feature" 5340 statement are ignored by the server unless the server supports the 5341 given feature expression. This allows portions of the YANG module to 5342 be conditional based on conditions in the server. The model can 5343 represent the abilities of the server within the model, giving a 5344 richer model that allows for differing server abilities and roles. 5346 The argument to the "feature" statement is the name of the new 5347 feature, and follows the rules for identifiers in Section 6.2. This 5348 name is used by the "if-feature" statement to tie the schema nodes to 5349 the feature. 5351 In this example, a feature called "local-storage" represents the 5352 ability for a server to store syslog messages on local storage of 5353 some sort. This feature is used to make the "local-storage-limit" 5354 leaf conditional on the presence of some sort of local storage. If 5355 the server does not report that it supports this feature, the 5356 "local-storage-limit" node is not supported. 5358 module example-syslog { 5359 yang-version 1.1; 5361 ... 5362 feature local-storage { 5363 description 5364 "This feature means the server supports local 5365 storage (memory, flash or disk) that can be used to 5366 store syslog messages."; 5367 } 5369 container syslog { 5370 leaf local-storage-limit { 5371 if-feature local-storage; 5372 type uint64; 5373 units "kilobyte"; 5374 config false; 5375 description 5376 "The amount of local storage that can be 5377 used to hold syslog messages."; 5378 } 5379 } 5380 } 5382 The "if-feature" statement can be used in many places within the YANG 5383 syntax. Definitions tagged with "if-feature" are ignored when the 5384 server does not support that feature. 5386 A feature MUST NOT reference itself, neither directly nor indirectly 5387 through a chain of other features. 5389 In order for a server to implement a feature that is dependent on any 5390 other features (i.e., the feature has one or more "if-feature" 5391 substatements), the server MUST also implement all the dependant 5392 features. 5394 7.20.1.1. The feature's Substatements 5396 +--------------+---------+-------------+ 5397 | substatement | section | cardinality | 5398 +--------------+---------+-------------+ 5399 | description | 7.21.3 | 0..1 | 5400 | if-feature | 7.20.2 | 0..n | 5401 | status | 7.21.2 | 0..1 | 5402 | reference | 7.21.4 | 0..1 | 5403 +--------------+---------+-------------+ 5405 7.20.2. The if-feature Statement 5407 The "if-feature" statement makes its parent statement conditional. 5408 The argument is a boolean expression over feature names. In this 5409 expression, a feature name evaluates to "true" if and only if the 5410 feature is implemented by the server. The parent statement is 5411 implemented by servers where the boolean expression evaluates to 5412 "true". 5414 The if-feature boolean expression syntax is formally defined by the 5415 rule "if-feature-expr" in Section 14. Parenthesis are used to group 5416 expressions. When the expression is evaluated, the order of 5417 precedence is (highest precedence first): grouping (parenthesis), 5418 "not", "and", "or". 5420 If a prefix is present on a feature name in the boolean expression, 5421 the prefixed name refers to a feature defined in the module that was 5422 imported with that prefix, or the local module if the prefix matches 5423 the local module's prefix. Otherwise, a feature with the matching 5424 name MUST be defined in the current module or an included submodule. 5426 A leaf that is a list key MUST NOT have any "if-feature" statements. 5428 7.20.2.1. Usage Example 5430 In this example, the container "target" is implemented if any of the 5431 features "outbound-tls" or "outbound-ssh" is implemented by the 5432 server. 5434 container target { 5435 if-feature "outbound-tls or outbound-ssh"; 5436 ... 5437 } 5439 The following examples are equivalent: 5441 if-feature "not foo or bar and baz"; 5443 if-feature "(not foo) or (bar and baz)"; 5445 7.20.3. The deviation Statement 5447 The "deviation" statement defines a hierarchy of a module that the 5448 server does not implement faithfully. The argument is a string that 5449 identifies the node in the schema tree where a deviation from the 5450 module occurs. This node is called the deviation's target node. The 5451 contents of the "deviation" statement give details about the 5452 deviation. 5454 The argument string is an absolute schema node identifier (see 5455 Section 6.5). 5457 Deviations define the way a server or class of servers deviate from a 5458 standard. This means that deviations MUST never be part of a 5459 published standard, since they are the mechanism for learning how 5460 implementations vary from the standards. 5462 Server deviations are strongly discouraged and MUST only be used as a 5463 last resort. Telling the application how a server fails to follow a 5464 standard is no substitute for implementing the standard correctly. A 5465 server that deviates from a module is not fully compliant with the 5466 module. 5468 However, in some cases, a particular device may not have the hardware 5469 or software ability to support parts of a standard module. When this 5470 occurs, the server makes a choice either to treat attempts to 5471 configure unsupported parts of the module as an error that is 5472 reported back to the unsuspecting application or ignore those 5473 incoming requests. Neither choice is acceptable. 5475 Instead, YANG allows servers to document portions of a base module 5476 that are not supported or supported but with different syntax, by 5477 using the "deviation" statement. 5479 7.20.3.1. The deviation's Substatements 5481 +--------------+----------+-------------+ 5482 | substatement | section | cardinality | 5483 +--------------+----------+-------------+ 5484 | description | 7.21.3 | 0..1 | 5485 | deviate | 7.20.3.2 | 1..n | 5486 | reference | 7.21.4 | 0..1 | 5487 +--------------+----------+-------------+ 5489 7.20.3.2. The deviate Statement 5491 The "deviate" statement defines how the server's implementation of 5492 the target node deviates from its original definition. The argument 5493 is one of the strings "not-supported", "add", "replace", or "delete". 5495 The argument "not-supported" indicates that the target node is not 5496 implemented by this server. 5498 The argument "add" adds properties to the target node. The 5499 properties to add are identified by substatements to the "deviate" 5500 statement. If a property can only appear once, the property MUST NOT 5501 exist in the target node. 5503 The argument "replace" replaces properties of the target node. The 5504 properties to replace are identified by substatements to the 5505 "deviate" statement. The properties to replace MUST exist in the 5506 target node. 5508 The argument "delete" deletes properties from the target node. The 5509 properties to delete are identified by substatements to the "delete" 5510 statement. The substatement's keyword MUST match a corresponding 5511 keyword in the target node, and the argument's string MUST be equal 5512 to the corresponding keyword's argument string in the target node. 5514 +--------------+-------------+-------------+ 5515 | substatement | section | cardinality | 5516 +--------------+-------------+-------------+ 5517 | config | 7.21.1 | 0..1 | 5518 | default | 7.6.4 7.7.4 | 0..n | 5519 | mandatory | 7.6.5 | 0..1 | 5520 | max-elements | 7.7.6 | 0..1 | 5521 | min-elements | 7.7.5 | 0..1 | 5522 | must | 7.5.3 | 0..n | 5523 | type | 7.4 | 0..1 | 5524 | unique | 7.8.3 | 0..n | 5525 | units | 7.3.3 | 0..1 | 5526 +--------------+-------------+-------------+ 5528 The deviate's Substatements 5530 If the target node has a property defined by an extension, this 5531 property can be deviated if the extension allows deviations. See 5532 Section 7.19 for details. 5534 7.20.3.3. Usage Example 5536 In this example, the server is informing client applications that it 5537 does not support the "daytime" service in the style of RFC 867. 5539 module example-deviations { 5540 yang-version 1.1; 5541 namespace "urn:example:deviations"; 5542 prefix md; 5544 import example-base { 5545 prefix base; 5546 } 5548 deviation /base:system/base:daytime { 5549 deviate not-supported; 5550 } 5551 ... 5552 } 5554 A server would advertise both modules "example-base" and 5555 "example-deviations". 5557 The following example sets a server-specific default value to a leaf 5558 that does not have a default value defined: 5560 deviation /base:system/base:user/base:type { 5561 deviate add { 5562 default "admin"; // new users are 'admin' by default 5563 } 5564 } 5566 In this example, the server limits the number of name servers to 3: 5568 deviation /base:system/base:name-server { 5569 deviate replace { 5570 max-elements 3; 5571 } 5572 } 5574 If the original definition is: 5576 container system { 5577 must "daytime or time"; 5578 ... 5579 } 5581 a server might remove this must constraint by doing: 5583 deviation /base:system { 5584 deviate delete { 5585 must "daytime or time"; 5586 } 5587 } 5589 7.21. Common Statements 5591 This section defines substatements common to several other 5592 statements. 5594 7.21.1. The config Statement 5596 The "config" statement takes as an argument the string "true" or 5597 "false". If "config" is "true", the definition represents 5598 configuration. Data nodes representing configuration are part of 5599 configuration datastores. 5601 If "config" is "false", the definition represents state data. Data 5602 nodes representing state data are not part of configuration 5603 datastores. 5605 If "config" is not specified, the default is the same as the parent 5606 schema node's "config" value. If the parent node is a "case" node, 5607 the value is the same as the "case" node's parent "choice" node. 5609 If the top node does not specify a "config" statement, the default is 5610 "true". 5612 If a node has "config" set to "false", no node underneath it can have 5613 "config" set to "true". 5615 7.21.2. The status Statement 5617 The "status" statement takes as an argument one of the strings 5618 "current", "deprecated", or "obsolete". 5620 o "current" means that the definition is current and valid. 5622 o "deprecated" indicates an obsolete definition, but it permits new/ 5623 continued implementation in order to foster interoperability with 5624 older/existing implementations. 5626 o "obsolete" means the definition is obsolete and SHOULD NOT be 5627 implemented and/or can be removed from implementations. 5629 If no status is specified, the default is "current". 5631 If a definition is "current", it MUST NOT reference a "deprecated" or 5632 "obsolete" definition within the same module. 5634 If a definition is "deprecated", it MUST NOT reference an "obsolete" 5635 definition within the same module. 5637 For example, the following is illegal: 5639 typedef my-type { 5640 status deprecated; 5641 type int32; 5642 } 5644 leaf my-leaf { 5645 status current; 5646 type my-type; // illegal, since my-type is deprecated 5647 } 5649 7.21.3. The description Statement 5651 The "description" statement takes as an argument a string that 5652 contains a human-readable textual description of this definition. 5653 The text is provided in a language (or languages) chosen by the 5654 module developer; for the sake of interoperability, it is RECOMMENDED 5655 to choose a language that is widely understood among the community of 5656 network administrators who will use the module. 5658 7.21.4. The reference Statement 5660 The "reference" statement takes as an argument a string that is used 5661 to specify a textual cross-reference to an external document, either 5662 another module that defines related management information, or a 5663 document that provides additional information relevant to this 5664 definition. 5666 For example, a typedef for a "uri" data type could look like: 5668 typedef uri { 5669 type string; 5670 reference 5671 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5672 ... 5673 } 5675 7.21.5. The when Statement 5677 The "when" statement makes its parent data definition statement 5678 conditional. The node defined by the parent data definition 5679 statement is only valid when the condition specified by the "when" 5680 statement is satisfied. The statement's argument is an XPath 5681 expression (see Section 6.4), which is used to formally specify this 5682 condition. If the XPath expression conceptually evaluates to "true" 5683 for a particular instance, then the node defined by the parent data 5684 definition statement is valid; otherwise, it is not. 5686 A leaf that is a list key MUST NOT have a "when" statement. 5688 If a leaf key is defined in a grouping that is used in a list, the 5689 "uses" statement MUST NOT have a "when" statement. 5691 See Section 8.3.2 for additional information. 5693 The XPath expression is conceptually evaluated in the following 5694 context, in addition to the definition in Section 6.4.1: 5696 o If the "when" statement is a child of an "augment" statement, then 5697 the context node is the augment's target node in the data tree, if 5698 the target node is a data node. Otherwise, the context node is 5699 the closest ancestor node to the target node that is also a data 5700 node. If no such node exists, the context node is the root node. 5701 The accessible tree is tentatively altered during the processing 5702 of the XPath expression by removing all instances (if any) of the 5703 nodes added by the "augment" statement. 5705 o If the "when" statement is a child of a "uses", "choice", or 5706 "case" statement, then the context node is the closest ancestor 5707 node to the "uses", "choice", or "case" node that is also a data 5708 node. If no such node exists, the context node is the root node. 5709 The accessible tree is tentatively altered during the processing 5710 of the XPath expression by removing all instances (if any) of the 5711 nodes added by the "uses", "choice", or "case" statement. 5713 o If the "when" statement is a child of any other data definition 5714 statement, the accessible tree is tentatively altered during the 5715 processing of the XPath expression by replacing all instances of 5716 the data node for which the "when" statement is defined with a 5717 single dummy node with the same name, but with no value and no 5718 children. If no such instance exists, the dummy node is 5719 tentatively created. The context node is this dummy node. 5721 The result of the XPath expression is converted to a boolean value 5722 using the standard XPath rules. 5724 If the XPath expression references any node that also has associated 5725 "when" statements, these "when" expressions MUST be evaluated first. 5726 There MUST NOT be any circular dependencies in these "when" 5727 expressions. 5729 Note that the XPath expression is conceptually evaluated. This means 5730 that an implementation does not have to use an XPath evaluator in the 5731 server. The "when" statement can very well be implemented with 5732 specially written code. 5734 8. Constraints 5736 8.1. Constraints on Data 5738 Several YANG statements define constraints on valid data. These 5739 constraints are enforced in different ways, depending on what type of 5740 data the statement defines. 5742 o If the constraint is defined on configuration data, it MUST be 5743 true in a valid configuration data tree. 5745 o If the constraint is defined on state data, it MUST be true in a 5746 valid state data tree. 5748 o If the constraint is defined on notification content, it MUST be 5749 true in any notification data tree. 5751 o If the constraint is defined on RPC or action input parameters, it 5752 MUST be true in an invocation of the RPC or action operation. 5754 o If the constraint is defined on RPC or action output parameters, 5755 it MUST be true in the RPC or action reply. 5757 The following properties are true in all data trees: 5759 o All leaf data values MUST match the type constraints for the leaf, 5760 including those defined in the type's "range", "length", and 5761 "pattern" properties. 5763 o All key leafs MUST be present for all list entries. 5765 o Nodes MUST be present for at most one case branch in all choices. 5767 o There MUST be no nodes tagged with "if-feature" present if the 5768 "if-feature" expression evaluates to "false" in the server. 5770 o There MUST be no nodes tagged with "when" present if the "when" 5771 condition evaluates to "false" in the data tree. 5773 The following properties are true in a valid data tree: 5775 o All "must" constraints MUST evaluate to "true". 5777 o All referential integrity constraints defined via the "path" 5778 statement MUST be satisfied. 5780 o All "unique" constraints on lists MUST be satisfied. 5782 o The "mandatory" constraint is enforced for leafs and choices, 5783 unless the node or any of its ancestors has a "when" condition or 5784 "if-feature" expression that evaluates to "false". 5786 o The "min-elements" and "max-elements" constraints are enforced for 5787 lists and leaf-lists, unless the node or any of its ancestors has 5788 a "when" condition or "if-feature" expression that evaluates to 5789 "false". 5791 The running configuration datastore MUST always be valid. 5793 8.2. Configuration Data Modifications 5795 o If a request creates configuration data nodes under a "choice", 5796 any existing nodes from other "case" branches are deleted by the 5797 server. 5799 o If a request modifies a configuration data node such that any 5800 node's "when" expression becomes false, then the node with the 5801 "when" expression is deleted by the server. 5803 8.3. NETCONF Constraint Enforcement Model 5805 For configuration data, there are three windows when constraints MUST 5806 be enforced: 5808 o during parsing of RPC payloads 5810 o during processing of NETCONF operations 5812 o during validation 5814 Each of these scenarios is considered in the following sections. 5816 8.3.1. Payload Parsing 5818 When content arrives in RPC payloads, it MUST be well-formed XML, 5819 following the hierarchy and content rules defined by the set of 5820 models the server implements. 5822 o If a leaf data value does not match the type constraints for the 5823 leaf, including those defined in the type's "range", "length", and 5824 "pattern" properties, the server MUST reply with an 5825 "invalid-value" error-tag in the rpc-error, and with the error- 5826 app-tag and error-message associated with the constraint, if any 5827 exist. 5829 o If all keys of a list entry are not present, the server MUST reply 5830 with a "missing-element" error-tag in the rpc-error. 5832 o If data for more than one case branch of a choice is present, the 5833 server MUST reply with a "bad-element" in the rpc-error. 5835 o If data for a node tagged with "if-feature" is present, and the 5836 if-feature expression evaluates to "false" in the server, the 5837 server MUST reply with an "unknown-element" error-tag in the rpc- 5838 error. 5840 o If data for a node tagged with "when" is present, and the "when" 5841 condition evaluates to "false", the server MUST reply with an 5842 "unknown-element" error-tag in the rpc-error. 5844 o For insert handling, if the value for the attributes "before" and 5845 "after" are not valid for the type of the appropriate key leafs, 5846 the server MUST reply with a "bad-attribute" error-tag in the rpc- 5847 error. 5849 o If the attributes "before" and "after" appears in any element that 5850 is not a list whose "ordered-by" property is "user", the server 5851 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 5853 8.3.2. NETCONF Processing 5855 After the incoming data is parsed, the NETCONF server performs the 5856 operation by applying the data to the configuration 5857 datastore. During this processing, the following errors MUST be 5858 detected: 5860 o Delete requests for non-existent data. 5862 o Create requests for existent data. 5864 o Insert requests with "before" or "after" parameters that do not 5865 exist. 5867 o Modification requests for nodes tagged with "when", and the "when" 5868 condition evaluates to "false". In this case the server MUST 5869 reply with an "unknown-element" error-tag in the rpc-error. 5871 8.3.3. Validation 5873 When datastore processing is complete, the final contents MUST obey 5874 all validation constraints. This validation processing is performed 5875 at differing times according to the datastore. If the datastore is 5876 "running" or "startup", these constraints MUST be enforced at the end 5877 of the or operation. If the datastore is 5878 "candidate", the constraint enforcement is delayed until a 5879 or operation. 5881 9. Built-In Types 5883 YANG has a set of built-in types, similar to those of many 5884 programming languages, but with some differences due to special 5885 requirements from the management information model. 5887 Additional types may be defined, derived from those built-in types or 5888 from other derived types. Derived types may use subtyping to 5889 formally restrict the set of possible values. 5891 The different built-in types and their derived types allow different 5892 kinds of subtyping, namely length and regular expression restrictions 5893 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 5894 numeric types (Section 9.2.4). 5896 The lexical representation of a value of a certain type is used in 5897 the XML encoding and when specifying default values and numerical 5898 ranges in YANG modules. 5900 9.1. Canonical Representation 5902 For most types, there is a single canonical representation of the 5903 type's values. Some types allow multiple lexical representations of 5904 the same value, for example, the positive integer "17" can be 5905 represented as "+17" or "17". Implementations MUST support all 5906 lexical representations specified in this document. 5908 When a server sends data encoded in XML, it MUST use the canonical 5909 form defined in this section. Other encodings may introduce 5910 alternate representations. Note, however, that values in the data 5911 tree are conceptually stored in the canonical representation as 5912 defined in this section. In particular, any XPath expression 5913 evaluations are done using the canonical form, if the data type has a 5914 canonical form. If the data type does not have a canonical form, the 5915 format of the value MUST match the data type's lexical 5916 representation, but the exact format is implementation dependent. 5918 Some types have a lexical representation that depends on the 5919 encoding, e.g., the XML context in which they occur. These types do 5920 not have a canonical form. 5922 9.2. The Integer Built-In Types 5924 The integer built-in types are int8, int16, int32, int64, uint8, 5925 uint16, uint32, and uint64. They represent signed and unsigned 5926 integers of different sizes: 5928 int8 represents integer values between -128 and 127, inclusively. 5930 int16 represents integer values between -32768 and 32767, 5931 inclusively. 5933 int32 represents integer values between -2147483648 and 2147483647, 5934 inclusively. 5936 int64 represents integer values between -9223372036854775808 and 5937 9223372036854775807, inclusively. 5939 uint8 represents integer values between 0 and 255, inclusively. 5941 uint16 represents integer values between 0 and 65535, inclusively. 5943 uint32 represents integer values between 0 and 4294967295, 5944 inclusively. 5946 uint64 represents integer values between 0 and 18446744073709551615, 5947 inclusively. 5949 9.2.1. Lexical Representation 5951 An integer value is lexically represented as an optional sign ("+" or 5952 "-"), followed by a sequence of decimal digits. If no sign is 5953 specified, "+" is assumed. 5955 For convenience, when specifying a default value for an integer in a 5956 YANG module, an alternative lexical representation can be used, which 5957 represents the value in a hexadecimal or octal notation. The 5958 hexadecimal notation consists of an optional sign ("+" or "-"), the 5959 characters "0x" followed a number of hexadecimal digits, where 5960 letters may be uppercase or lowercase. The octal notation consists 5961 of an optional sign ("+" or "-"), the character "0" followed a number 5962 of octal digits. 5964 Note that if a default value in a YANG module has a leading zero 5965 ("0"), it is interpreted as an octal number. In the XML encoding, an 5966 integer is always interpreted as a decimal number, and leading zeros 5967 are allowed. 5969 Examples: 5971 // legal values 5972 +4711 // legal positive value 5973 4711 // legal positive value 5974 -123 // legal negative value 5975 0xf00f // legal positive hexadecimal value 5976 -0xf // legal negative hexadecimal value 5977 052 // legal positive octal value 5979 // illegal values 5980 - 1 // illegal intermediate space 5982 9.2.2. Canonical Form 5984 The canonical form of a positive integer does not include the sign 5985 "+". Leading zeros are prohibited. The value zero is represented as 5986 "0". 5988 9.2.3. Restrictions 5990 All integer types can be restricted with the "range" statement 5991 (Section 9.2.4). 5993 9.2.4. The range Statement 5995 The "range" statement, which is an optional substatement to the 5996 "type" statement, takes as an argument a range expression string. It 5997 is used to restrict integer and decimal built-in types, or types 5998 derived from those. 6000 A range consists of an explicit value, or a lower-inclusive bound, 6001 two consecutive dots "..", and an upper-inclusive bound. Multiple 6002 values or ranges can be given, separated by "|". If multiple values 6003 or ranges are given, they all MUST be disjoint and MUST be in 6004 ascending order. If a range restriction is applied to an already 6005 range-restricted type, the new restriction MUST be equal or more 6006 limiting, that is raising the lower bounds, reducing the upper 6007 bounds, removing explicit values or ranges, or splitting ranges into 6008 multiple ranges with intermediate gaps. Each explicit value and 6009 range boundary value given in the range expression MUST match the 6010 type being restricted, or be one of the special values "min" or 6011 "max". "min" and "max" mean the minimum and maximum value accepted 6012 for the type being restricted, respectively. 6014 The range expression syntax is formally defined by the rule 6015 "range-arg" in Section 14. 6017 9.2.4.1. The range's Substatements 6019 +---------------+---------+-------------+ 6020 | substatement | section | cardinality | 6021 +---------------+---------+-------------+ 6022 | description | 7.21.3 | 0..1 | 6023 | error-app-tag | 7.5.4.2 | 0..1 | 6024 | error-message | 7.5.4.1 | 0..1 | 6025 | reference | 7.21.4 | 0..1 | 6026 +---------------+---------+-------------+ 6028 9.2.5. Usage Example 6030 typedef my-base-int32-type { 6031 type int32 { 6032 range "1..4 | 10..20"; 6033 } 6034 } 6036 typedef my-type1 { 6037 type my-base-int32-type { 6038 // legal range restriction 6039 range "11..max"; // 11..20 6040 } 6041 } 6043 typedef my-type2 { 6044 type my-base-int32-type { 6045 // illegal range restriction 6046 range "11..100"; 6047 } 6048 } 6050 9.3. The decimal64 Built-In Type 6052 The decimal64 type represents a subset of the real numbers, which can 6053 be represented by decimal numerals. The value space of decimal64 is 6054 the set of numbers that can be obtained by multiplying a 64-bit 6055 signed integer by a negative power of ten, i.e., expressible as "i x 6056 10^-n" where i is an integer64 and n is an integer between 1 and 18, 6057 inclusively. 6059 9.3.1. Lexical Representation 6061 A decimal64 value is lexically represented as an optional sign ("+" 6062 or "-"), followed by a sequence of decimal digits, optionally 6063 followed by a period ('.') as a decimal indicator and a sequence of 6064 decimal digits. If no sign is specified, "+" is assumed. 6066 9.3.2. Canonical Form 6068 The canonical form of a positive decimal64 does not include the sign 6069 "+". The decimal point is required. Leading and trailing zeros are 6070 prohibited, subject to the rule that there MUST be at least one digit 6071 before and after the decimal point. The value zero is represented as 6072 "0.0". 6074 9.3.3. Restrictions 6076 A decimal64 type can be restricted with the "range" statement 6077 (Section 9.2.4). 6079 9.3.4. The fraction-digits Statement 6081 The "fraction-digits" statement, which is a substatement to the 6082 "type" statement, MUST be present if the type is "decimal64". It 6083 takes as an argument an integer between 1 and 18, inclusively. It 6084 controls the size of the minimum difference between values of a 6085 decimal64 type, by restricting the value space to numbers that are 6086 expressible as "i x 10^-n" where n is the fraction-digits argument. 6088 The following table lists the minimum and maximum value for each 6089 fraction-digit value: 6091 +----------------+-----------------------+----------------------+ 6092 | fraction-digit | min | max | 6093 +----------------+-----------------------+----------------------+ 6094 | 1 | -922337203685477580.8 | 922337203685477580.7 | 6095 | 2 | -92233720368547758.08 | 92233720368547758.07 | 6096 | 3 | -9223372036854775.808 | 9223372036854775.807 | 6097 | 4 | -922337203685477.5808 | 922337203685477.5807 | 6098 | 5 | -92233720368547.75808 | 92233720368547.75807 | 6099 | 6 | -9223372036854.775808 | 9223372036854.775807 | 6100 | 7 | -922337203685.4775808 | 922337203685.4775807 | 6101 | 8 | -92233720368.54775808 | 92233720368.54775807 | 6102 | 9 | -9223372036.854775808 | 9223372036.854775807 | 6103 | 10 | -922337203.6854775808 | 922337203.6854775807 | 6104 | 11 | -92233720.36854775808 | 92233720.36854775807 | 6105 | 12 | -9223372.036854775808 | 9223372.036854775807 | 6106 | 13 | -922337.2036854775808 | 922337.2036854775807 | 6107 | 14 | -92233.72036854775808 | 92233.72036854775807 | 6108 | 15 | -9223.372036854775808 | 9223.372036854775807 | 6109 | 16 | -922.3372036854775808 | 922.3372036854775807 | 6110 | 17 | -92.23372036854775808 | 92.23372036854775807 | 6111 | 18 | -9.223372036854775808 | 9.223372036854775807 | 6112 +----------------+-----------------------+----------------------+ 6114 9.3.5. Usage Example 6116 typedef my-decimal { 6117 type decimal64 { 6118 fraction-digits 2; 6119 range "1 .. 3.14 | 10 | 20..max"; 6120 } 6121 } 6123 9.4. The string Built-In Type 6125 The string built-in type represents human-readable strings in YANG. 6126 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 6127 characters, including tab, carriage return, and line feed but 6128 excluding the other C0 control characters, the surrogate blocks, and 6129 the noncharacters. The string syntax is formally defined by the rule 6130 "yang-string" in Section 14. 6132 9.4.1. Lexical Representation 6134 A string value is lexically represented as character data in the XML 6135 encoding. 6137 9.4.2. Canonical Form 6139 The canonical form is the same as the lexical representation. No 6140 Unicode normalization is performed of string values. 6142 9.4.3. Restrictions 6144 A string can be restricted with the "length" (Section 9.4.4) and 6145 "pattern" (Section 9.4.5) statements. 6147 9.4.4. The length Statement 6149 The "length" statement, which is an optional substatement to the 6150 "type" statement, takes as an argument a length expression string. 6151 It is used to restrict the built-in types "string" and "binary" or 6152 types derived from them. 6154 A "length" statement restricts the number of Unicode characters in 6155 the string. 6157 A length range consists of an explicit value, or a lower bound, two 6158 consecutive dots "..", and an upper bound. Multiple values or ranges 6159 can be given, separated by "|". Length-restricting values MUST NOT 6160 be negative. If multiple values or ranges are given, they all MUST 6161 be disjoint and MUST be in ascending order. If a length restriction 6162 is applied to an already length-restricted type, the new restriction 6163 MUST be equal or more limiting, that is, raising the lower bounds, 6164 reducing the upper bounds, removing explicit length values or ranges, 6165 or splitting ranges into multiple ranges with intermediate gaps. A 6166 length value is a non-negative integer, or one of the special values 6167 "min" or "max". "min" and "max" mean the minimum and maximum length 6168 accepted for the type being restricted, respectively. An 6169 implementation is not required to support a length value larger than 6170 18446744073709551615. 6172 The length expression syntax is formally defined by the rule 6173 "length-arg" in Section 14. 6175 9.4.4.1. The length's Substatements 6177 +---------------+---------+-------------+ 6178 | substatement | section | cardinality | 6179 +---------------+---------+-------------+ 6180 | description | 7.21.3 | 0..1 | 6181 | error-app-tag | 7.5.4.2 | 0..1 | 6182 | error-message | 7.5.4.1 | 0..1 | 6183 | reference | 7.21.4 | 0..1 | 6184 +---------------+---------+-------------+ 6186 9.4.5. The pattern Statement 6188 The "pattern" statement, which is an optional substatement to the 6189 "type" statement, takes as an argument a regular expression string, 6190 as defined in [XSD-TYPES]. It is used to restrict the built-in type 6191 "string", or types derived from "string", to values that match the 6192 pattern. 6194 If the type has multiple "pattern" statements, the expressions are 6195 ANDed together, i.e., all such expressions have to match. 6197 If a pattern restriction is applied to an already pattern-restricted 6198 type, values must match all patterns in the base type, in addition to 6199 the new patterns. 6201 9.4.5.1. The pattern's Substatements 6203 +---------------+---------+-------------+ 6204 | substatement | section | cardinality | 6205 +---------------+---------+-------------+ 6206 | description | 7.21.3 | 0..1 | 6207 | error-app-tag | 7.5.4.2 | 0..1 | 6208 | error-message | 7.5.4.1 | 0..1 | 6209 | modifier | 9.4.6 | 0..1 | 6210 | reference | 7.21.4 | 0..1 | 6211 +---------------+---------+-------------+ 6213 9.4.6. The modifier Statement 6215 The "modifier" statement, which is an optional substatement to the 6216 "pattern" statement, takes as an argument the string "invert-match". 6218 If a pattern has the "invert-match" modifier present, the type is 6219 restricted to values that do not match the pattern. 6221 9.4.7. Usage Example 6223 With the following typedef: 6225 typedef my-base-str-type { 6226 type string { 6227 length "1..255"; 6228 } 6229 } 6231 the following refinement is legal: 6233 type my-base-str-type { 6234 // legal length refinement 6235 length "11 | 42..max"; // 11 | 42..255 6236 } 6238 and the following refinement is illegal: 6240 type my-base-str-type { 6241 // illegal length refinement 6242 length "1..999"; 6243 } 6245 With the following type: 6247 type string { 6248 length "0..4"; 6249 pattern "[0-9a-fA-F]*"; 6250 } 6252 the following strings match: 6254 AB // legal 6255 9A00 // legal 6257 and the following strings do not match: 6259 00ABAB // illegal, too long 6260 xx00 // illegal, bad characters 6262 With the following type: 6264 typedef yang-identifier { 6265 type string { 6266 length "1..max"; 6267 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 6268 pattern '[xX][mM][lL].*' { 6269 modifier invert-match; 6270 } 6271 } 6272 } 6274 the following string match: 6276 enabled // legal 6278 and the following strings do not match: 6280 10-mbit // illegal, starts with a number 6281 xml-element // illegal, starts with illegal sequence 6283 9.5. The boolean Built-In Type 6285 The boolean built-in type represents a boolean value. 6287 9.5.1. Lexical Representation 6289 The lexical representation of a boolean value is a string with a 6290 value of "true" or "false". These values MUST be in lowercase. 6292 9.5.2. Canonical Form 6294 The canonical form is the same as the lexical representation. 6296 9.5.3. Restrictions 6298 A boolean cannot be restricted. 6300 9.6. The enumeration Built-In Type 6302 The enumeration built-in type represents values from a set of 6303 assigned names. 6305 9.6.1. Lexical Representation 6307 The lexical representation of an enumeration value is the assigned 6308 name string. 6310 9.6.2. Canonical Form 6312 The canonical form is the assigned name string. 6314 9.6.3. Restrictions 6316 An enumeration can be restricted with the "enum" (Section 9.6.4) 6317 statement. 6319 9.6.4. The enum Statement 6321 The "enum" statement, which is a substatement to the "type" 6322 statement, MUST be present if the type is "enumeration". It is 6323 repeatedly used to specify each assigned name of an enumeration type. 6324 It takes as an argument a string which is the assigned name. The 6325 string MUST NOT be zero-length and MUST NOT have any leading or 6326 trailing whitespace characters (any Unicode character with the 6327 "White_Space" property). The use of Unicode control codes SHOULD be 6328 avoided. 6330 The statement is optionally followed by a block of substatements that 6331 holds detailed enum information. 6333 All assigned names in an enumeration MUST be unique. 6335 When an existing enumeration type is restricted, the set of assigned 6336 names in the new type MUST be a subset of the base type's set of 6337 assigned names. The value of such an assigned name MUST NOT be 6338 changed. 6340 9.6.4.1. The enum's Substatements 6342 +--------------+---------+-------------+ 6343 | substatement | section | cardinality | 6344 +--------------+---------+-------------+ 6345 | description | 7.21.3 | 0..1 | 6346 | if-feature | 7.20.2 | 0..n | 6347 | reference | 7.21.4 | 0..1 | 6348 | status | 7.21.2 | 0..1 | 6349 | value | 9.6.4.2 | 0..1 | 6350 +--------------+---------+-------------+ 6352 9.6.4.2. The value Statement 6354 The "value" statement, which is optional, is used to associate an 6355 integer value with the assigned name for the enum. This integer 6356 value MUST be in the range -2147483648 to 2147483647, and it MUST be 6357 unique within the enumeration type. 6359 If a value is not specified, then one will be automatically assigned. 6360 If the "enum" substatement is the first one defined, the assigned 6361 value is zero (0); otherwise, the assigned value is one greater than 6362 the current highest enum value (i.e., the highest enum value, 6363 implicit or explicit, prior to the current "enum" substatement in the 6364 parent "type" statement). 6366 Note that the the presence of an "if-feature" statement in an "enum" 6367 statement does not affect the automatically assigned value. 6369 If the current highest value is equal to 2147483647, then an enum 6370 value MUST be specified for "enum" substatements following the one 6371 with the current highest value. 6373 When an existing enumeration type is restricted, the "value" 6374 statement MUST either have the same value as in the base type or not 6375 be present, in which case the value is the same as in the base type. 6377 9.6.5. Usage Example 6379 leaf myenum { 6380 type enumeration { 6381 enum zero; 6382 enum one; 6383 enum seven { 6384 value 7; 6385 } 6386 } 6387 } 6389 The lexical representation of the leaf "myenum" with value "seven" 6390 is: 6392 seven 6394 With the following typedef: 6396 typedef my-base-enumeration-type { 6397 type enumeration { 6398 enum white { 6399 value 1; 6400 } 6401 enum yellow { 6402 value 2; 6403 } 6404 enum red { 6405 value 3; 6406 } 6407 } 6408 } 6410 the following refinement is legal: 6412 type my-base-enumeration-type { 6413 // legal enum refinement 6414 enum yellow; 6415 enum red { 6416 value 3; 6417 } 6418 } 6420 and the following refinement is illegal: 6422 type my-base-enumeration-type { 6423 // illegal enum refinement 6424 enum yellow { 6425 value 4; // illegal value change 6426 } 6427 enum black; // illegal addition of new name 6428 } 6430 The following example shows how an "enum" can be tagged with 6431 "if-feature", making the value legal only on servers that advertise 6432 the corresponding feature: 6434 type enumeration { 6435 enum tcp; 6436 enum ssh { 6437 if-feature ssh; 6438 } 6439 enum tls { 6440 if-feature tls; 6441 } 6442 } 6444 9.7. The bits Built-In Type 6446 The bits built-in type represents a bit set. That is, a bits value 6447 is a set of flags identified by small integer position numbers 6448 starting at 0. Each bit number has an assigned name. 6450 When an existing bits type is restricted, the set of assigned names 6451 in the new type MUST be a subset of the base type's set of assigned 6452 names. The bit position of such an assigned name MUST NOT be 6453 changed. 6455 9.7.1. Restrictions 6457 A bits type can be restricted with the "bit" (Section 9.7.4) 6458 statement. 6460 9.7.2. Lexical Representation 6462 The lexical representation of the bits type is a space-separated list 6463 of the individual bit values that are set. A zero-length string thus 6464 represents a value where no bits are set. 6466 9.7.3. Canonical Form 6468 In the canonical form, the bit values are separated by a single space 6469 character and they appear ordered by their position (see 6470 Section 9.7.4.2). 6472 9.7.4. The bit Statement 6474 The "bit" statement, which is a substatement to the "type" statement, 6475 MUST be present if the type is "bits". It is repeatedly used to 6476 specify each assigned named bit of a bits type. It takes as an 6477 argument a string that is the assigned name of the bit. It is 6478 followed by a block of substatements that holds detailed bit 6479 information. The assigned name follows the same syntax rules as an 6480 identifier (see Section 6.2). 6482 All assigned names in a bits type MUST be unique. 6484 9.7.4.1. The bit's Substatements 6486 +--------------+---------+-------------+ 6487 | substatement | section | cardinality | 6488 +--------------+---------+-------------+ 6489 | description | 7.21.3 | 0..1 | 6490 | if-feature | 7.20.2 | 0..n | 6491 | reference | 7.21.4 | 0..1 | 6492 | status | 7.21.2 | 0..1 | 6493 | position | 9.7.4.2 | 0..1 | 6494 +--------------+---------+-------------+ 6496 9.7.4.2. The position Statement 6498 The "position" statement, which is optional, takes as an argument a 6499 non-negative integer value that specifies the bit's position within a 6500 hypothetical bit field. The position value MUST be in the range 0 to 6501 4294967295, and it MUST be unique within the bits type. 6503 If a bit position is not specified, then one will be automatically 6504 assigned. If the "bit" substatement is the first one defined, the 6505 assigned value is zero (0); otherwise, the assigned value is one 6506 greater than the current highest bit position (i.e., the highest bit 6507 position, implicit or explicit, prior to the current "bit" 6508 substatement in the parent "type" statement). 6510 Note that the the presence of an "if-feature" statement in an "bit" 6511 statement does not affect the automatically assigned position. 6513 If the current highest bit position value is equal to 4294967295, 6514 then a position value MUST be specified for "bit" substatements 6515 following the one with the current highest position value. 6517 When an existing bits type is restricted, the "position" statement 6518 MUST either have the same value as in the base type or not be 6519 present, in which case the value is the same as in the base type. 6521 9.7.5. Usage Example 6523 Given the following typedef and leaf: 6525 typedef mybits-type { 6526 type bits { 6527 bit disable-nagle { 6528 position 0; 6529 } 6530 bit auto-sense-speed { 6531 position 1; 6532 } 6533 bit ten-mb-only { 6534 position 2; 6535 } 6536 } 6537 } 6539 leaf mybits { 6540 type mybits-type; 6541 default "auto-sense-speed"; 6542 } 6544 The lexical representation of this leaf with bit values disable-nagle 6545 and ten-mb-only set would be: 6547 disable-nagle ten-mb-only 6549 The following example shows a legal refinement of this type: 6551 type mybits-type { 6552 // legal bit refinement 6553 bit disable-nagle { 6554 position 0; 6555 } 6556 bit auto-sense-speed { 6557 position 1; 6558 } 6559 } 6561 and the following refinement is illegal: 6563 type mybits-type { 6564 // illegal bit refinement 6565 bit disable-nagle { 6566 position 2; // illegal position change 6567 } 6568 bit hundred-mb-only; // illegal addition of new name 6569 } 6571 9.8. The binary Built-In Type 6573 The binary built-in type represents any binary data, i.e., a sequence 6574 of octets. 6576 9.8.1. Restrictions 6578 A binary type can be restricted with the "length" (Section 9.4.4) 6579 statement. The length of a binary value is the number of octets it 6580 contains. 6582 9.8.2. Lexical Representation 6584 Binary values are encoded with the base64 encoding scheme (see 6585 [RFC4648], Section 4). 6587 9.8.3. Canonical Form 6589 The canonical form of a binary value follows the rules in [RFC4648]. 6591 9.9. The leafref Built-In Type 6593 The leafref type is used to declare a constraint on the value space 6594 of a leaf, based on a reference to a set of leaf instances in the 6595 data tree. The "path" substatement (Section 9.9.2) selects a set of 6596 leaf instances, and the leafref value space is the set of values of 6597 these leaf instances. 6599 If the leaf with the leafref type represents configuration data, and 6600 the "require-instance" property (Section 9.9.3) is "true", the leaf 6601 it refers to MUST also represent configuration. Such a leaf puts a 6602 constraint on valid data. All such nodes MUST reference existing 6603 leaf instances or leafs with default values in use (see Section 7.6.1 6604 and Section 7.7.2) for the data to be valid. This constraint is 6605 enforced according to the rules in Section 8. 6607 There MUST NOT be any circular chains of leafrefs. 6609 If the leaf that the leafref refers to is conditional based on one or 6610 more features (see Section 7.20.2), then the leaf with the leafref 6611 type MUST also be conditional based on at least the same set of 6612 features. 6614 9.9.1. Restrictions 6616 A leafref can be restricted with the "require-instance" statement 6617 (Section 9.9.3). 6619 9.9.2. The path Statement 6621 The "path" statement, which is a substatement to the "type" 6622 statement, MUST be present if the type is "leafref". It takes as an 6623 argument a string that MUST refer to a leaf or leaf-list node. 6625 The syntax for a path argument is a subset of the XPath abbreviated 6626 syntax. Predicates are used only for constraining the values for the 6627 key nodes for list entries. Each predicate consists of exactly one 6628 equality test per key, and multiple adjacent predicates MAY be 6629 present if a list has multiple keys. The syntax is formally defined 6630 by the rule "path-arg" in Section 14. 6632 The predicates are only used when more than one key reference is 6633 needed to uniquely identify a leaf instance. This occurs if a list 6634 has multiple keys, or a reference to a leaf other than the key in a 6635 list is needed. In these cases, multiple leafrefs are typically 6636 specified, and predicates are used to tie them together. 6638 The "path" expression evaluates to a node set consisting of zero, 6639 one, or more nodes. If the leaf with the leafref type represents 6640 configuration data, this node set MUST be non-empty. 6642 The "path" XPath expression is conceptually evaluated in the 6643 following context, in addition to the definition in Section 6.4.1: 6645 o If the "path" statement is defined within a typedef, the context 6646 node is the leaf or leaf-list node in the data tree that 6647 references the typedef. 6649 o Otherwise, the context node is the node in the data tree for which 6650 the "path" statement is defined. 6652 9.9.3. The require-instance Statement 6654 The "require-instance" statement, which is a substatement to the 6655 "type" statement, MAY be present if the type is "instance-identifier" 6656 or "leafref". It takes as an argument the string "true" or "false". 6657 If this statement is not present, it defaults to "true". 6659 If "require-instance" is "true", it means that the instance being 6660 referred MUST exist for the data to be valid. This constraint is 6661 enforced according to the rules in Section 8. 6663 If "require-instance" is "false", it means that the instance being 6664 referred MAY exist in valid data. 6666 9.9.4. Lexical Representation 6668 A leafref value is lexically represented the same way as the leaf it 6669 references. 6671 9.9.5. Canonical Form 6673 The canonical form of a leafref is the same as the canonical form of 6674 the leaf it references. 6676 9.9.6. Usage Example 6678 With the following list: 6680 list interface { 6681 key "name"; 6682 leaf name { 6683 type string; 6684 } 6685 leaf admin-status { 6686 type admin-status; 6687 } 6688 list address { 6689 key "ip"; 6690 leaf ip { 6691 type yang:ip-address; 6692 } 6693 } 6694 } 6696 The following leafref refers to an existing interface: 6698 leaf mgmt-interface { 6699 type leafref { 6700 path "../interface/name"; 6701 } 6702 } 6704 An example of a corresponding XML snippet: 6706 6707 eth0 6708 6709 6710 lo 6711 6713 eth0 6715 The following leafrefs refer to an existing address of an interface: 6717 container default-address { 6718 leaf ifname { 6719 type leafref { 6720 path "../../interface/name"; 6721 } 6722 } 6723 leaf address { 6724 type leafref { 6725 path "../../interface[name = current()/../ifname]" 6726 + "/address/ip"; 6727 } 6728 } 6729 } 6731 An example of a corresponding XML snippet: 6733 6734 eth0 6735 up 6736
6737 192.0.2.1 6738
6739
6740 192.0.2.2 6741
6742 6743 6744 lo 6745 up 6746
6747 127.0.0.1 6748
6749 6751 6752 eth0 6753
192.0.2.2
6754 6756 The following list uses a leafref for one of its keys. This is 6757 similar to a foreign key in a relational database. 6759 list packet-filter { 6760 key "if-name filter-id"; 6761 leaf if-name { 6762 type leafref { 6763 path "/interface/name"; 6764 } 6765 } 6766 leaf filter-id { 6767 type uint32; 6768 } 6769 ... 6770 } 6772 An example of a corresponding XML snippet: 6774 6775 eth0 6776 up 6777
6778 192.0.2.1 6779
6780
6781 192.0.2.2 6782
6783 6785 6786 eth0 6787 1 6788 ... 6789 6790 6791 eth0 6792 2 6793 ... 6794 6796 The following notification defines two leafrefs to refer to an 6797 existing admin-status: 6799 notification link-failure { 6800 leaf if-name { 6801 type leafref { 6802 path "/interface/name"; 6803 } 6804 } 6805 leaf admin-status { 6806 type leafref { 6807 path "/interface[name = current()/../if-name]" 6808 + "/admin-status"; 6809 } 6810 } 6811 } 6813 An example of a corresponding XML notification: 6815 6817 2008-04-01T00:01:00Z 6818 6819 eth0 6820 up 6821 6822 6824 9.10. The identityref Built-In Type 6826 The identityref type is used to reference an existing identity (see 6827 Section 7.18). 6829 9.10.1. Restrictions 6831 An identityref cannot be restricted. 6833 9.10.2. The identityref's base Statement 6835 The "base" statement, which is a substatement to the "type" 6836 statement, MUST be present at least once if the type is 6837 "identityref". The argument is the name of an identity, as defined 6838 by an "identity" statement. If a prefix is present on the identity 6839 name, it refers to an identity defined in the module that was 6840 imported with that prefix. Otherwise, an identity with the matching 6841 name MUST be defined in the current module or an included submodule. 6843 Valid values for an identityref are any identities derived from all 6844 the identityref's base identities. On a particular server, the valid 6845 values are further restricted to the set of identities defined in the 6846 modules implemented by the server. 6848 9.10.3. Lexical Representation 6850 An identityref is lexically represented as the referred identity's 6851 qualified name as defined in [XML-NAMES]. If the prefix is not 6852 present, the namespace of the identityref is the default namespace in 6853 effect on the element that contains the identityref value. 6855 When an identityref is given a default value using the "default" 6856 statement, the identity name in the default value MAY have a prefix. 6857 If a prefix is present on the identity name, it refers to an identity 6858 defined in the module that was imported with that prefix, or the 6859 prefix for the current module if the identity is defined in the 6860 current module or one of its submodules. Otherwise, an identity with 6861 the matching name MUST be defined in the current module or one of its 6862 submodules. 6864 The string value of a node of type identityref in a "must" or "when" 6865 XPath expression is the referred identity's qualified name with the 6866 prefix present. If the referred identity is defined in an imported 6867 module, the prefix in the string value is the prefix defined in the 6868 corresponding "import" statement. Otherwise, the prefix in the 6869 string value is the prefix for the current module. 6871 9.10.4. Canonical Form 6873 Since the lexical form depends on the XML context in which the value 6874 occurs, this type does not have a canonical form. 6876 9.10.5. Usage Example 6878 With the identity definitions in Section 7.18.3 and the following 6879 module: 6881 module example-my-crypto { 6882 yang-version 1.1; 6883 namespace "urn:example:my-crypto"; 6884 prefix mc; 6886 import "example-crypto-base" { 6887 prefix "crypto"; 6888 } 6890 identity aes { 6891 base "crypto:crypto-alg"; 6892 } 6894 leaf crypto { 6895 type identityref { 6896 base "crypto:crypto-alg"; 6897 } 6898 } 6900 container aes-parameters { 6901 when "../crypto = 'mc:aes'"; 6902 ... 6903 } 6904 } 6906 the following is an example how the leaf "crypto" can be encoded, if 6907 the value is the "des3" identity defined in the "des" module: 6909 des:des3 6911 Any prefixes used in the encoding are local to each instance 6912 encoding. This means that the same identityref may be encoded 6913 differently by different implementations. For example, the following 6914 example encodes the same leaf as above: 6916 x:des3 6918 If the "crypto" leaf's value instead is "aes" defined in the 6919 "example-my-crypto" module, it can be encoded as: 6921 mc:aes 6923 or, using the default namespace: 6925 aes 6927 9.11. The empty Built-In Type 6929 The empty built-in type represents a leaf that does not have any 6930 value, it conveys information by its presence or absence. 6932 An empty type cannot have a default value. 6934 9.11.1. Restrictions 6936 An empty type cannot be restricted. 6938 9.11.2. Lexical Representation 6940 Not applicable. 6942 9.11.3. Canonical Form 6944 Not applicable. 6946 9.11.4. Usage Example 6948 With the following leaf 6950 leaf enable-qos { 6951 type empty; 6952 } 6954 the following is an example of a valid encoding 6956 6958 if the leaf exists. 6960 9.12. The union Built-In Type 6962 The union built-in type represents a value that corresponds to one of 6963 its member types. 6965 When the type is "union", the "type" statement (Section 7.4) MUST be 6966 present. It is used to repeatedly specify each member type of the 6967 union. It takes as an argument a string that is the name of a member 6968 type. 6970 A member type can be of any built-in or derived type. 6972 In the XML encoding, a value representing a union data type is 6973 validated consecutively against each member type, in the order they 6974 are specified in the "type" statement, until a match is found. The 6975 type that matched will be the type of the value for the node that was 6976 validated. 6978 Any default value or "units" property defined in the member types is 6979 not inherited by the union type. 6981 9.12.1. Restrictions 6983 A union cannot be restricted. However, each member type can be 6984 restricted, based on the rules defined in Section 9. 6986 9.12.2. Lexical Representation 6988 The lexical representation of a union is a value that corresponds to 6989 the representation of any one of the member types. 6991 9.12.3. Canonical Form 6993 The canonical form of a union value is the same as the canonical form 6994 of the member type of the value. 6996 9.12.4. Usage Example 6998 The following is a union of an int32 an enumeration: 7000 type union { 7001 type int32; 7002 type enumeration { 7003 enum "unbounded"; 7004 } 7005 } 7007 Care must be taken when a member type is a leafref where the 7008 "require-instance" property (Section 9.9.3) is "true". If a leaf of 7009 such a type refers to an existing instance, the leaf's value must be 7010 re-validated if the target instance is deleted. For example, with 7011 the following definitions: 7013 list filter { 7014 key name; 7015 leaf name { 7016 type string; 7017 } 7018 ... 7019 } 7021 leaf outbound-filter { 7022 type union { 7023 type leafref { 7024 path "/filter/name"; 7025 } 7026 type enumeration { 7027 enum default-filter; 7028 } 7029 } 7030 } 7032 assume that there exists an entry in the filter list with the name 7033 "http", and that the outbound-filter leaf has this value: 7035 7036 http 7037 7038 http 7040 If the filter entry "http" is removed, the outbound-filter leaf's 7041 value doesn't match the leafref, and the next member type is checked. 7042 The current value ("http") doesn't match the enumeration, so the 7043 resulting configuration is invalid. 7045 If the second member type in the union had been of type "string" 7046 instead of an enumeration, the current value would have matched, and 7047 the resulting configuration would have been valid. 7049 9.13. The instance-identifier Built-In Type 7051 The instance-identifier built-in type is used to uniquely identify a 7052 particular instance node in the data tree. 7054 The syntax for an instance-identifier is a subset of the XPath 7055 abbreviated syntax, formally defined by the rule 7056 "instance-identifier" in Section 14. It is used to uniquely identify 7057 a node in the data tree. Predicates are used only for specifying the 7058 values for the key nodes for list entries, a value of a leaf-list 7059 entry, or a positional index for a list without keys. For 7060 identifying list entries with keys, each predicate consists of one 7061 equality test per key, and each key MUST have a corresponding 7062 predicate. If a key is of type "empty", it is represented as a zero- 7063 length string (""). 7065 If the leaf with the instance-identifier type represents 7066 configuration data, and the "require-instance" property 7067 (Section 9.9.3) is "true", the node it refers to MUST also represent 7068 configuration. Such a leaf puts a constraint on valid data. All 7069 such leaf nodes MUST reference existing nodes or leaf or leaf-list 7070 nodes with their default value in use (see Section 7.6.1 and 7071 Section 7.7.2) for the data to be valid. This constraint is enforced 7072 according to the rules in Section 8. 7074 The "instance-identifier" XPath expression is conceptually evaluated 7075 in the following context, in addition to the definition in 7076 Section 6.4.1: 7078 o The context node is the root node in the accessible tree. 7080 9.13.1. Restrictions 7082 An instance-identifier can be restricted with the "require-instance" 7083 statement (Section 9.9.3). 7085 9.13.2. Lexical Representation 7087 An instance-identifier value is lexically represented as a string. 7088 All node names in an instance-identifier value MUST be qualified with 7089 explicit namespace prefixes, and these prefixes MUST be declared in 7090 the XML namespace scope in the instance-identifier's XML element. 7092 Any prefixes used in the encoding are local to each instance 7093 encoding. This means that the same instance-identifier may be 7094 encoded differently by different implementations. 7096 9.13.3. Canonical Form 7098 Since the lexical form depends on the XML context in which the value 7099 occurs, this type does not have a canonical form. 7101 9.13.4. Usage Example 7103 The following are examples of instance identifiers: 7105 /* instance-identifier for a container */ 7106 /ex:system/ex:services/ex:ssh 7108 /* instance-identifier for a leaf */ 7109 /ex:system/ex:services/ex:ssh/ex:port 7111 /* instance-identifier for a list entry */ 7112 /ex:system/ex:user[ex:name='fred'] 7114 /* instance-identifier for a leaf in a list entry */ 7115 /ex:system/ex:user[ex:name='fred']/ex:type 7117 /* instance-identifier for a list entry with two keys */ 7118 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 7120 /* instance-identifier for a list entry where the second 7121 key ("enabled") is of type empty */ 7122 /ex:system/ex:service[ex:name='foo'][ex:enabled=''] 7124 /* instance-identifier for a leaf-list entry */ 7125 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 7127 /* instance-identifier for a list entry without keys */ 7128 /ex:stats/ex:port[3] 7130 10. XPath Functions 7132 This document defines two generic XPath functions and four YANG type- 7133 specific XPath functions. The function signatures are specified with 7134 the syntax used in [XPATH]. 7136 10.1. Functions for Node Sets 7138 10.1.1. current() 7140 node-set current() 7142 The function current() takes no input parameters, and returns a node 7143 set with the initial context node as its only member. 7145 10.1.1.1. Usage Example 7147 With this list: 7149 list interface { 7150 key "name"; 7151 ... 7152 leaf enabled { 7153 type boolean; 7154 } 7155 ... 7156 } 7158 the following leaf defines a must expression that ensures that the 7159 referred interface is enabled: 7161 leaf outgoing-interface { 7162 type leafref { 7163 path "/interface/name"; 7164 } 7165 must '/interface[name=current()]/enabled = "true"'; 7166 } 7168 10.2. Functions for Strings 7170 10.2.1. re-match() 7172 boolean re-match(string subject, string pattern) 7174 The re-match() function returns true if the "subject" string matches 7175 the regular expression "pattern"; otherwise it returns false. 7177 The function "re-match" checks if a string matches a given regular 7178 expression. The regular expressions used are the XML Schema regular 7179 expressions [XSD-TYPES]. Note that this includes implicit anchoring 7180 of the regular expression at the head and tail. 7182 10.2.1.1. Usage Example 7184 The expression: 7186 re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') 7188 returns true. 7190 To count all logical interfaces called eth0., do: 7192 count(/interface[re-match(name, 'eth0\.\d+')]) 7194 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 7196 10.3.1. deref() 7198 node-set deref(node-set nodes) 7200 The deref() function follows the reference defined by the first node 7201 in document order in the argument "nodes", and returns the nodes it 7202 refers to. 7204 If the first argument node is of type instance-identifier, the 7205 function returns a node set that contains the single node that the 7206 instance identifier refers to, if it exists. If no such node exists, 7207 an empty node-set is returned. 7209 If the first argument node is of type leafref, the function returns a 7210 node set that contains the nodes that the leafref refers to. 7212 If the first argument node is of any other type, an empty node set is 7213 returned. 7215 10.3.1.1. Usage Example 7216 list interface { 7217 key "name type"; 7218 leaf name { ... } 7219 leaf type { ... } 7220 leaf enabled { 7221 type boolean; 7222 } 7223 ... 7224 } 7226 container mgmt-interface { 7227 leaf name { 7228 type leafref { 7229 path "/interface/name"; 7230 } 7231 } 7232 leaf type { 7233 type leafref { 7234 path "/interface[name=current()/../name]/type"; 7235 } 7236 must 'deref(.)/../enabled = "true"' { 7237 error-message 7238 "The management interface cannot be disabled."; 7239 } 7240 } 7241 } 7243 10.4. Functions for the YANG Type "identityref" 7245 10.4.1. derived-from() 7247 boolean derived-from(node-set nodes, string identity) 7249 The derived-from() function returns true if any node in the argument 7250 "nodes" is a node of type identityref, and its value is an identity 7251 that is derived from (see Section 7.18.2) the identity "identity"; 7252 otherwise it returns false. 7254 The parameter "identity" is a string matching the rule 7255 "identifier-ref" in Section 14. If a prefix is present on the 7256 identity, it refers to an identity defined in the module that was 7257 imported with that prefix, or the local module if the prefix matches 7258 the local module's prefix. If no prefix is present, the identity 7259 refers to an identity defined in the current module or an included 7260 submodule. 7262 10.4.1.1. Usage Example 7264 module example-interface { 7265 yang-version 1.1; 7267 ... 7268 identity interface-type; 7270 identity ethernet { 7271 base interface-type; 7272 } 7274 identity fast-ethernet { 7275 base ethernet; 7276 } 7278 identity gigabit-ethernet { 7279 base ethernet; 7280 } 7282 list interface { 7283 key name; 7284 ... 7285 leaf type { 7286 type identityref { 7287 base interface-type; 7288 } 7289 } 7290 ... 7291 } 7293 augment "/interface" { 7294 when 'derived-from(type, "exif:ethernet")'; 7295 // generic ethernet definitions here 7296 } 7297 ... 7298 } 7300 10.4.2. derived-from-or-self() 7302 boolean derived-from-or-self(node-set nodes, string identity) 7304 The derived-from-or-self() function returns true if any node in the 7305 argument "nodes" is a node of type identityref, and its value is an 7306 identity that is equal to or derived from (see Section 7.18.2) the 7307 identity "identity"; otherwise it returns false. 7309 The parameter "identity" is a string matching the rule 7310 "identifier-ref" in Section 14. If a prefix is present on the 7311 identity, it refers to an identity defined in the module that was 7312 imported with that prefix, or the local module if the prefix matches 7313 the local module's prefix. If no prefix is present, the identity 7314 refers to an identity defined in the current module or an included 7315 submodule. 7317 10.4.2.1. Usage Example 7319 The module defined in Section 10.4.1.1 might also have: 7321 augment "/interface" { 7322 when 'derived-from-or-self(type, "exif:fast-ethernet"); 7323 // fast-ethernet-specific definitions here 7324 } 7326 10.5. Functions for the YANG Type "enumeration" 7328 10.5.1. enum-value() 7330 number enum-value(node-set nodes) 7332 The enum-value() function checks if the first node in document order 7333 in the argument "nodes" is a node of type enumeration, and returns 7334 the enum's integer value. If the "nodes" node set is empty, or if 7335 the first node in "nodes" is not of type enumeration, it returns NaN. 7337 10.5.1.1. Usage Example 7339 With this data model: 7341 list alarm { 7342 ... 7343 leaf severity { 7344 type enumeration { 7345 enum cleared { 7346 value 1; 7347 } 7348 enum indeterminate { 7349 value 2; 7350 } 7351 enum minor { 7352 value 3; 7353 } 7354 enum warning { 7355 value 4; 7356 } 7357 enum major { 7358 value 5; 7359 } 7360 enum critical { 7361 value 6; 7362 } 7363 } 7364 } 7365 } 7367 the following XPath expression selects only alarms that are of 7368 severity "major" or higher: 7370 /alarm[enum-value(severity) >= 5] 7372 10.6. Functions for the YANG Type "bits" 7374 10.6.1. bit-is-set() 7376 boolean bit-is-set(node-set nodes, string bit-name) 7378 The bit-is-set() function returns true if the first node in document 7379 order in the argument "nodes" is a node of type bits, and its value 7380 has the bit "'bit-name" set; otherwise it returns false. 7382 10.6.1.1. Usage Example 7384 If an interface has this leaf: 7386 leaf flags { 7387 type bits { 7388 bit UP; 7389 bit PROMISCUOUS 7390 bit DISABLED; 7391 } 7392 } 7394 the following XPath expression can be used to select all interfaces 7395 with the UP flag set: 7397 /interface[bit-is-set(flags, "UP")] 7399 11. Updating a Module 7401 As experience is gained with a module, it may be desirable to revise 7402 that module. However, changes to published modules are not allowed 7403 if they have any potential to cause interoperability problems between 7404 a client using an original specification and a server using an 7405 updated specification. 7407 For any published change, a new "revision" statement (Section 7.1.9) 7408 MUST be included in front of the existing "revision" statements. If 7409 there are no existing "revision" statements, then one MUST be added 7410 to identify the new revision. Furthermore, any necessary changes 7411 MUST be applied to any meta-data statements, including the 7412 "organization" and "contact" statements (Section 7.1.7, 7413 Section 7.1.8). 7415 Note that definitions contained in a module are available to be 7416 imported by any other module, and are referenced in "import" 7417 statements via the module name. Thus, a module name MUST NOT be 7418 changed. Furthermore, the "namespace" statement MUST NOT be changed, 7419 since all XML elements are qualified by the namespace. 7421 Obsolete definitions MUST NOT be removed from published modules since 7422 their identifiers may still be referenced by other modules. 7424 A definition in a published module may be revised in any of the 7425 following ways: 7427 o An "enumeration" type may have new enums added, provided the old 7428 enums's values do not change. Note that inserting a new enum 7429 before an existing enum or reordering existing enums will result 7430 in new values for the existing enums, unless they have explicit 7431 values assigned to them. 7433 o A "bits" type may have new bits added, provided the old bit 7434 positions do not change. Note that inserting a new bit before an 7435 existing bit or reordering existing bit will result in new 7436 positions for the existing bits, unless they have explicit 7437 positions assigned to them. 7439 o A "range", "length", or "pattern" statement may expand the allowed 7440 value space. 7442 o A "default" statement may be added to a leaf that does not have a 7443 default value (either directly or indirectly through its type). 7445 o A "units" statement may be added. 7447 o A "reference" statement may be added or updated. 7449 o A "must" statement may be removed or its constraint relaxed. 7451 o A "when" statement may be removed or its constraint relaxed. 7453 o A "mandatory" statement may be removed or changed from "true" to 7454 "false". 7456 o A "min-elements" statement may be removed, or changed to require 7457 fewer elements. 7459 o A "max-elements" statement may be removed, or changed to allow 7460 more elements. 7462 o A "description" statement may be added or clarified without 7463 changing the semantics of the definition. 7465 o A "base" statement may be added to an "identity" statement. 7467 o A "base" statement may be removed from an "identityref" type, 7468 provided there is at least one "base" statement left. 7470 o New typedefs, groupings, rpcs, notifications, extensions, 7471 features, and identities may be added. 7473 o New data definition statements may be added if they do not add 7474 mandatory nodes (Section 3) to existing nodes or at the top level 7475 in a module or submodule, or if they are conditionally dependent 7476 on a new feature (i.e., have an "if-feature" statement that refers 7477 to a new feature). 7479 o A new "case" statement may be added. 7481 o A node that represented state data may be changed to represent 7482 configuration, provided it is not mandatory (Section 3). 7484 o An "if-feature" statement may be removed, provided its node is not 7485 mandatory (Section 3). 7487 o A "status" statement may be added, or changed from "current" to 7488 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 7490 o A "type" statement may be replaced with another "type" statement 7491 that does not change the syntax or semantics of the type. For 7492 example, an inline type definition may be replaced with a typedef, 7493 but an int8 type cannot be replaced by an int16, since the syntax 7494 would change. 7496 o Any set of data definition nodes may be replaced with another set 7497 of syntactically and semantically equivalent nodes. For example, 7498 a set of leafs may be replaced by a uses of a grouping with the 7499 same leafs. 7501 o A module may be split into a set of submodules, or a submodule may 7502 be removed, provided the definitions in the module do not change 7503 in any other way than allowed here. 7505 o The "prefix" statement may be changed, provided all local uses of 7506 the prefix also are changed. 7508 Otherwise, if the semantics of any previous definition are changed 7509 (i.e., if a non-editorial change is made to any definition other than 7510 those specifically allowed above), then this MUST be achieved by a 7511 new definition with a new identifier. 7513 In statements that have any data definition statements as 7514 substatements, those data definition substatements MUST NOT be 7515 reordered. If new data definition statements are added, they can be 7516 added anywhere in the sequence of existing substatement. 7518 12. Coexistence with YANG version 1 7520 A YANG version 1.1 module MUST NOT include a YANG version 1 7521 submodule, and a YANG version 1 module MUST NOT include a YANG 7522 version 1.1 submodule. 7524 A YANG version 1 module or submodule MUST NOT import a YANG version 7525 1.1 module by revision. 7527 A YANG version 1.1 module or submodule MAY import a YANG version 1 7528 module by revision. 7530 If a YANG version 1 module A imports module B without revision, and 7531 module B is updated to YANG version 1.1, a server MAY implement both 7532 these modules (A and B) at the same time. In such cases, a NETCONF 7533 server MUST advertise both modules using the rules defined in 7534 Section 5.6.5, and SHOULD advertise module A and the latest revision 7535 of module B that is specified with YANG version 1 according to the 7536 rules defined in [RFC6020]. 7538 This rule exists in order to allow implementations of existing YANG 7539 version 1 modules together with YANG version 1.1 modules. Without 7540 this rule, updating a single module to YANG version 1.1 would have a 7541 cascading effect on modules that import it, requiring all of them to 7542 also be updated to YANG version 1.1, and so on. 7544 13. YIN 7546 A YANG module can be translated into an alternative XML-based syntax 7547 called YIN. The translated module is called a YIN module. This 7548 section describes symmetric mapping rules between the two formats. 7550 The YANG and YIN formats contain equivalent information using 7551 different notations. The YIN notation enables developers to 7552 represent YANG data models in XML and therefore use the rich set of 7553 XML-based tools for data filtering and validation, automated 7554 generation of code and documentation, and other tasks. Tools like 7555 XSLT or XML validators can be utilized. 7557 The mapping between YANG and YIN does not modify the information 7558 content of the model. Comments and whitespace are not preserved. 7560 13.1. Formal YIN Definition 7562 There is a one-to-one correspondence between YANG keywords and YIN 7563 elements. The local name of a YIN element is identical to the 7564 corresponding YANG keyword. This means, in particular, that the 7565 document element (root) of a YIN document is always or 7566 . 7568 YIN elements corresponding to the YANG keywords belong to the 7569 namespace whose associated URI is 7570 "urn:ietf:params:xml:ns:yang:yin:1". 7572 YIN elements corresponding to extension keywords belong to the 7573 namespace of the YANG module where the extension keyword is declared 7574 via the "extension" statement. 7576 The names of all YIN elements MUST be properly qualified with their 7577 namespaces specified above using the standard mechanisms of 7578 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 7580 The argument of a YANG statement is represented in YIN either as an 7581 XML attribute or a subelement of the keyword element. Table 1 7582 defines the mapping for the set of YANG keywords. For extensions, 7583 the argument mapping is specified within the "extension" statement 7584 (see Section 7.19). The following rules hold for arguments: 7586 o If the argument is represented as an attribute, this attribute has 7587 no namespace. 7589 o If the argument is represented as an element, it is qualified by 7590 the same namespace as its parent keyword element. 7592 o If the argument is represented as an element, it MUST be the first 7593 child of the keyword element. 7595 Substatements of a YANG statement are represented as (additional) 7596 children of the keyword element and their relative order MUST be the 7597 same as the order of substatements in YANG. 7599 Comments in YANG MAY be mapped to XML comments. 7601 +------------------+---------------+-------------+ 7602 | keyword | argument name | yin-element | 7603 +------------------+---------------+-------------+ 7604 | action | name | false | 7605 | anydata | name | false | 7606 | anyxml | name | false | 7607 | argument | name | false | 7608 | augment | target-node | false | 7609 | base | name | false | 7610 | belongs-to | module | false | 7611 | bit | name | false | 7612 | case | name | false | 7613 | choice | name | false | 7614 | config | value | false | 7615 | contact | text | true | 7616 | container | name | false | 7617 | default | value | false | 7618 | description | text | true | 7619 | deviate | value | false | 7620 | deviation | target-node | false | 7621 | enum | name | false | 7622 | error-app-tag | value | false | 7623 | error-message | value | true | 7624 | extension | name | false | 7625 | feature | name | false | 7626 | fraction-digits | value | false | 7627 | grouping | name | false | 7628 | identity | name | false | 7629 | if-feature | name | false | 7630 | import | module | false | 7631 | include | module | false | 7632 | input | | n/a | 7633 | key | value | false | 7634 | leaf | name | false | 7635 | leaf-list | name | false | 7636 | length | value | false | 7637 | list | name | false | 7638 | mandatory | value | false | 7639 | max-elements | value | false | 7640 | min-elements | value | false | 7641 | modifier | value | false | 7642 | module | name | false | 7643 | must | condition | false | 7644 | namespace | uri | false | 7645 | notification | name | false | 7646 | ordered-by | value | false | 7647 | organization | text | true | 7648 | output | | n/a | 7649 | path | value | false | 7650 | pattern | value | false | 7651 | position | value | false | 7652 | prefix | value | false | 7653 | presence | value | false | 7654 | range | value | false | 7655 | reference | text | true | 7656 | refine | target-node | false | 7657 | require-instance | value | false | 7658 | revision | date | false | 7659 | revision-date | date | false | 7660 | rpc | name | false | 7661 | status | value | false | 7662 | submodule | name | false | 7663 | type | name | false | 7664 | typedef | name | false | 7665 | unique | tag | false | 7666 | units | name | false | 7667 | uses | name | false | 7668 | value | value | false | 7669 | when | condition | false | 7670 | yang-version | value | false | 7671 | yin-element | value | false | 7672 +------------------+---------------+-------------+ 7674 Table 1: Mapping of arguments of the YANG statements. 7676 13.1.1. Usage Example 7678 The following YANG module: 7680 module example-foo { 7681 yang-version 1.1; 7682 namespace "urn:example:foo"; 7683 prefix "foo"; 7685 import example-extensions { 7686 prefix "myext"; 7687 } 7689 list interface { 7690 key "name"; 7691 leaf name { 7692 type string; 7693 } 7695 leaf mtu { 7696 type uint32; 7697 description "The MTU of the interface."; 7698 myext:c-define "MY_MTU"; 7699 } 7700 } 7701 } 7703 where the extension "c-define" is defined in Section 7.19.3, is 7704 translated into the following YIN: 7706 7711 7712 7714 7715 7716 7718 7719 7720 7721 7722 7723 7724 7725 7726 The MTU of the interface. 7727 7728 7729 7730 7731 7733 14. YANG ABNF Grammar 7735 In YANG, almost all statements are unordered. The ABNF grammar 7736 [RFC5234] [RFC7405] defines the canonical order. To improve module 7737 readability, it is RECOMMENDED that clauses be entered in this order. 7739 Within the ABNF grammar, unordered statements are marked with 7740 comments. 7742 This grammar assumes that the scanner replaces YANG comments with a 7743 single space character. 7745 file "yang.abnf" 7747 module-stmt = optsep module-keyword sep identifier-arg-str 7748 optsep 7749 "{" stmtsep 7750 module-header-stmts 7751 linkage-stmts 7752 meta-stmts 7753 revision-stmts 7754 body-stmts 7755 "}" optsep 7757 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 7758 optsep 7759 "{" stmtsep 7760 submodule-header-stmts 7761 linkage-stmts 7762 meta-stmts 7763 revision-stmts 7764 body-stmts 7765 "}" optsep 7767 module-header-stmts = ;; these stmts can appear in any order 7768 yang-version-stmt 7769 namespace-stmt 7770 prefix-stmt 7772 submodule-header-stmts = 7773 ;; these stmts can appear in any order 7774 yang-version-stmt 7775 belongs-to-stmt 7777 meta-stmts = ;; these stmts can appear in any order 7778 [organization-stmt] 7779 [contact-stmt] 7780 [description-stmt] 7781 [reference-stmt] 7783 linkage-stmts = ;; these stmts can appear in any order 7784 *import-stmt 7785 *include-stmt 7787 revision-stmts = *revision-stmt 7789 body-stmts = *(extension-stmt / 7790 feature-stmt / 7791 identity-stmt / 7792 typedef-stmt / 7793 grouping-stmt / 7794 data-def-stmt / 7795 augment-stmt / 7796 rpc-stmt / 7797 notification-stmt / 7798 deviation-stmt) 7800 data-def-stmt = container-stmt / 7801 leaf-stmt / 7802 leaf-list-stmt / 7803 list-stmt / 7804 choice-stmt / 7805 anydata-stmt / 7806 anyxml-stmt / 7807 uses-stmt 7809 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 7810 stmtend 7812 yang-version-arg-str = < a string that matches the rule > 7813 < yang-version-arg > 7815 yang-version-arg = "1.1" 7817 import-stmt = import-keyword sep identifier-arg-str optsep 7818 "{" stmtsep 7819 ;; these stmts can appear in any order 7820 prefix-stmt 7821 [revision-date-stmt] 7822 [description-stmt] 7823 [reference-stmt] 7824 "}" stmtsep 7826 include-stmt = include-keyword sep identifier-arg-str optsep 7827 (";" / 7828 "{" stmtsep 7829 ;; these stmts can appear in any order 7830 [revision-date-stmt] 7831 [description-stmt] 7832 [reference-stmt] 7833 "}") stmtsep 7835 namespace-stmt = namespace-keyword sep uri-str stmtend 7837 uri-str = < a string that matches the rule > 7838 < URI in RFC 3986 > 7840 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 7842 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 7843 optsep 7844 "{" stmtsep 7845 prefix-stmt 7846 "}" stmtsep 7848 organization-stmt = organization-keyword sep string stmtend 7849 contact-stmt = contact-keyword sep string stmtend 7851 description-stmt = description-keyword sep string stmtend 7853 reference-stmt = reference-keyword sep string stmtend 7855 units-stmt = units-keyword sep string stmtend 7857 revision-stmt = revision-keyword sep revision-date optsep 7858 (";" / 7859 "{" stmtsep 7860 ;; these stmts can appear in any order 7861 [description-stmt] 7862 [reference-stmt] 7863 "}") stmtsep 7865 revision-date = date-arg-str 7867 revision-date-stmt = revision-date-keyword sep revision-date stmtend 7869 extension-stmt = extension-keyword sep identifier-arg-str optsep 7870 (";" / 7871 "{" stmtsep 7872 ;; these stmts can appear in any order 7873 [argument-stmt] 7874 [status-stmt] 7875 [description-stmt] 7876 [reference-stmt] 7877 "}") stmtsep 7879 argument-stmt = argument-keyword sep identifier-arg-str optsep 7880 (";" / 7881 "{" stmtsep 7882 [yin-element-stmt] 7883 "}") stmtsep 7885 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 7886 stmtend 7888 yin-element-arg-str = < a string that matches the rule > 7889 < yin-element-arg > 7891 yin-element-arg = true-keyword / false-keyword 7893 identity-stmt = identity-keyword sep identifier-arg-str optsep 7894 (";" / 7895 "{" stmtsep 7896 ;; these stmts can appear in any order 7897 *if-feature-stmt 7898 *base-stmt 7899 [status-stmt] 7900 [description-stmt] 7901 [reference-stmt] 7902 "}") stmtsep 7904 base-stmt = base-keyword sep identifier-ref-arg-str 7905 stmtend 7907 feature-stmt = feature-keyword sep identifier-arg-str optsep 7908 (";" / 7909 "{" stmtsep 7910 ;; these stmts can appear in any order 7911 *if-feature-stmt 7912 [status-stmt] 7913 [description-stmt] 7914 [reference-stmt] 7915 "}") stmtsep 7917 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 7918 stmtend 7920 if-feature-expr-str = < a string that matches the rule > 7921 < if-feature-expr > 7923 if-feature-expr = "(" if-feature-expr ")" / 7924 if-feature-expr sep boolean-operator sep 7925 if-feature-expr / 7926 not-keyword sep if-feature-expr / 7927 identifier-ref-arg 7929 boolean-operator = and-keyword / or-keyword 7931 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 7932 "{" stmtsep 7933 ;; these stmts can appear in any order 7934 type-stmt 7935 [units-stmt] 7936 [default-stmt] 7937 [status-stmt] 7938 [description-stmt] 7939 [reference-stmt] 7940 "}" stmtsep 7942 type-stmt = type-keyword sep identifier-ref-arg-str optsep 7943 (";" / 7944 "{" stmtsep 7946 [type-body-stmts] 7947 "}") stmtsep 7949 type-body-stmts = numerical-restrictions / 7950 decimal64-specification / 7951 string-restrictions / 7952 enum-specification / 7953 leafref-specification / 7954 identityref-specification / 7955 instance-identifier-specification / 7956 bits-specification / 7957 union-specification / 7958 binary-specification 7960 numerical-restrictions = range-stmt 7962 range-stmt = range-keyword sep range-arg-str optsep 7963 (";" / 7964 "{" stmtsep 7965 ;; these stmts can appear in any order 7966 [error-message-stmt] 7967 [error-app-tag-stmt] 7968 [description-stmt] 7969 [reference-stmt] 7970 "}") stmtsep 7972 decimal64-specification = ;; these stmts can appear in any order 7973 fraction-digits-stmt 7974 [range-stmt] 7976 fraction-digits-stmt = fraction-digits-keyword sep 7977 fraction-digits-arg-str stmtend 7979 fraction-digits-arg-str = < a string that matches the rule > 7980 < fraction-digits-arg > 7982 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 7983 "5" / "6" / "7" / "8"]) 7984 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 7986 string-restrictions = ;; these stmts can appear in any order 7987 [length-stmt] 7988 *pattern-stmt 7990 length-stmt = length-keyword sep length-arg-str optsep 7991 (";" / 7992 "{" stmtsep 7993 ;; these stmts can appear in any order 7995 [error-message-stmt] 7996 [error-app-tag-stmt] 7997 [description-stmt] 7998 [reference-stmt] 7999 "}") stmtsep 8001 pattern-stmt = pattern-keyword sep string optsep 8002 (";" / 8003 "{" stmtsep 8004 ;; these stmts can appear in any order 8005 [modifier-stmt] 8006 [error-message-stmt] 8007 [error-app-tag-stmt] 8008 [description-stmt] 8009 [reference-stmt] 8010 "}") stmtsep 8012 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 8014 modifier-arg-str = < a string that matches the rule > 8015 < modifier-arg > 8017 modifier-arg = invert-match-keyword 8019 default-stmt = default-keyword sep string stmtend 8021 enum-specification = 1*enum-stmt 8023 enum-stmt = enum-keyword sep string optsep 8024 (";" / 8025 "{" stmtsep 8026 ;; these stmts can appear in any order 8027 *if-feature-stmt 8028 [value-stmt] 8029 [status-stmt] 8030 [description-stmt] 8031 [reference-stmt] 8032 "}") stmtsep 8034 leafref-specification = 8035 ;; these stmts can appear in any order 8036 path-stmt 8037 [require-instance-stmt] 8039 path-stmt = path-keyword sep path-arg-str stmtend 8041 require-instance-stmt = require-instance-keyword sep 8042 require-instance-arg-str stmtend 8044 require-instance-arg-str = < a string that matches the rule > 8045 < require-instance-arg > 8047 require-instance-arg = true-keyword / false-keyword 8049 instance-identifier-specification = 8050 [require-instance-stmt] 8052 identityref-specification = 8053 1*base-stmt 8055 union-specification = 1*type-stmt 8057 binary-specification = [length-stmt] 8059 bits-specification = 1*bit-stmt 8061 bit-stmt = bit-keyword sep identifier-arg-str optsep 8062 (";" / 8063 "{" stmtsep 8064 ;; these stmts can appear in any order 8065 *if-feature-stmt 8066 [position-stmt] 8067 [status-stmt] 8068 [description-stmt] 8069 [reference-stmt] 8070 "}") stmtsep 8072 position-stmt = position-keyword sep 8073 position-value-arg-str stmtend 8075 position-value-arg-str = < a string that matches the rule > 8076 < position-value-arg > 8078 position-value-arg = non-negative-integer-value 8080 status-stmt = status-keyword sep status-arg-str stmtend 8082 status-arg-str = < a string that matches the rule > 8083 < status-arg > 8085 status-arg = current-keyword / 8086 obsolete-keyword / 8087 deprecated-keyword 8089 config-stmt = config-keyword sep 8090 config-arg-str stmtend 8092 config-arg-str = < a string that matches the rule > 8093 < config-arg > 8095 config-arg = true-keyword / false-keyword 8097 mandatory-stmt = mandatory-keyword sep 8098 mandatory-arg-str stmtend 8100 mandatory-arg-str = < a string that matches the rule > 8101 < mandatory-arg > 8103 mandatory-arg = true-keyword / false-keyword 8105 presence-stmt = presence-keyword sep string stmtend 8107 ordered-by-stmt = ordered-by-keyword sep 8108 ordered-by-arg-str stmtend 8110 ordered-by-arg-str = < a string that matches the rule > 8111 < ordered-by-arg > 8113 ordered-by-arg = user-keyword / system-keyword 8115 must-stmt = must-keyword sep string optsep 8116 (";" / 8117 "{" stmtsep 8118 ;; these stmts can appear in any order 8119 [error-message-stmt] 8120 [error-app-tag-stmt] 8121 [description-stmt] 8122 [reference-stmt] 8123 "}") stmtsep 8125 error-message-stmt = error-message-keyword sep string stmtend 8127 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 8129 min-elements-stmt = min-elements-keyword sep 8130 min-value-arg-str stmtend 8132 min-value-arg-str = < a string that matches the rule > 8133 < min-value-arg > 8135 min-value-arg = non-negative-integer-value 8137 max-elements-stmt = max-elements-keyword sep 8138 max-value-arg-str stmtend 8140 max-value-arg-str = < a string that matches the rule > 8141 < max-value-arg > 8143 max-value-arg = unbounded-keyword / 8144 positive-integer-value 8146 value-stmt = value-keyword sep integer-value-str stmtend 8148 integer-value-str = < a string that matches the rule > 8149 < integer-value > 8151 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 8152 (";" / 8153 "{" stmtsep 8154 ;; these stmts can appear in any order 8155 [status-stmt] 8156 [description-stmt] 8157 [reference-stmt] 8158 *(typedef-stmt / grouping-stmt) 8159 *data-def-stmt 8160 *action-stmt 8161 *notification-stmt 8162 "}") stmtsep 8164 container-stmt = container-keyword sep identifier-arg-str optsep 8165 (";" / 8166 "{" stmtsep 8167 ;; these stmts can appear in any order 8168 [when-stmt] 8169 *if-feature-stmt 8170 *must-stmt 8171 [presence-stmt] 8172 [config-stmt] 8173 [status-stmt] 8174 [description-stmt] 8175 [reference-stmt] 8176 *(typedef-stmt / grouping-stmt) 8177 *data-def-stmt 8178 *action-stmt 8179 *notification-stmt 8180 "}") stmtsep 8182 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 8183 "{" stmtsep 8184 ;; these stmts can appear in any order 8185 [when-stmt] 8186 *if-feature-stmt 8187 type-stmt 8189 [units-stmt] 8190 *must-stmt 8191 [default-stmt] 8192 [config-stmt] 8193 [mandatory-stmt] 8194 [status-stmt] 8195 [description-stmt] 8196 [reference-stmt] 8197 "}" stmtsep 8199 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 8200 "{" stmtsep 8201 ;; these stmts can appear in any order 8202 [when-stmt] 8203 *if-feature-stmt 8204 type-stmt stmtsep 8205 [units-stmt] 8206 *must-stmt 8207 *default-stmt 8208 [config-stmt] 8209 [min-elements-stmt] 8210 [max-elements-stmt] 8211 [ordered-by-stmt] 8212 [status-stmt] 8213 [description-stmt] 8214 [reference-stmt] 8215 "}" stmtsep 8217 list-stmt = list-keyword sep identifier-arg-str optsep 8218 "{" stmtsep 8219 ;; these stmts can appear in any order 8220 [when-stmt] 8221 *if-feature-stmt 8222 *must-stmt 8223 [key-stmt] 8224 *unique-stmt 8225 [config-stmt] 8226 [min-elements-stmt] 8227 [max-elements-stmt] 8228 [ordered-by-stmt] 8229 [status-stmt] 8230 [description-stmt] 8231 [reference-stmt] 8232 *(typedef-stmt / grouping-stmt) 8233 1*data-def-stmt 8234 *action-stmt 8235 *notification-stmt 8236 "}" stmtsep 8238 key-stmt = key-keyword sep key-arg-str stmtend 8240 key-arg-str = < a string that matches the rule > 8241 < key-arg > 8243 key-arg = node-identifier *(sep node-identifier) 8245 unique-stmt = unique-keyword sep unique-arg-str stmtend 8247 unique-arg-str = < a string that matches the rule > 8248 < unique-arg > 8250 unique-arg = descendant-schema-nodeid 8251 *(sep descendant-schema-nodeid) 8253 choice-stmt = choice-keyword sep identifier-arg-str optsep 8254 (";" / 8255 "{" stmtsep 8256 ;; these stmts can appear in any order 8257 [when-stmt] 8258 *if-feature-stmt 8259 [default-stmt] 8260 [config-stmt] 8261 [mandatory-stmt] 8262 [status-stmt] 8263 [description-stmt] 8264 [reference-stmt] 8265 *(short-case-stmt / case-stmt) 8266 "}") stmtsep 8268 short-case-stmt = choice-stmt / 8269 container-stmt / 8270 leaf-stmt / 8271 leaf-list-stmt / 8272 list-stmt / 8273 anydata-stmt / 8274 anyxml-stmt 8276 case-stmt = case-keyword sep identifier-arg-str optsep 8277 (";" / 8278 "{" stmtsep 8279 ;; these stmts can appear in any order 8280 [when-stmt] 8281 *if-feature-stmt 8282 [status-stmt] 8283 [description-stmt] 8284 [reference-stmt] 8285 *data-def-stmt 8287 "}") stmtsep 8289 anydata-stmt = anydata-keyword sep identifier-arg-str optsep 8290 (";" / 8291 "{" stmtsep 8292 ;; these stmts can appear in any order 8293 [when-stmt] 8294 *if-feature-stmt 8295 *must-stmt 8296 [config-stmt] 8297 [mandatory-stmt] 8298 [status-stmt] 8299 [description-stmt] 8300 [reference-stmt] 8301 "}") stmtsep 8303 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 8304 (";" / 8305 "{" stmtsep 8306 ;; these stmts can appear in any order 8307 [when-stmt] 8308 *if-feature-stmt 8309 *must-stmt 8310 [config-stmt] 8311 [mandatory-stmt] 8312 [status-stmt] 8313 [description-stmt] 8314 [reference-stmt] 8315 "}") stmtsep 8317 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 8318 (";" / 8319 "{" stmtsep 8320 ;; these stmts can appear in any order 8321 [when-stmt] 8322 *if-feature-stmt 8323 [status-stmt] 8324 [description-stmt] 8325 [reference-stmt] 8326 *refine-stmt 8327 *uses-augment-stmt 8328 "}") stmtsep 8330 refine-stmt = refine-keyword sep refine-arg-str optsep 8331 "{" stmtsep 8332 ;; these stmts can appear in any order 8333 *if-feature-stmt 8334 *must-stmt 8336 [presence-stmt] 8337 [default-stmt] 8338 [config-stmt] 8339 [mandatory-stmt] 8340 [min-elements-stmt] 8341 [max-elements-stmt] 8342 [description-stmt] 8343 [reference-stmt] 8344 "}" stmtsep 8346 refine-arg-str = < a string that matches the rule > 8347 < refine-arg > 8349 refine-arg = descendant-schema-nodeid 8351 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 8352 "{" stmtsep 8353 ;; these stmts can appear in any order 8354 [when-stmt] 8355 *if-feature-stmt 8356 [status-stmt] 8357 [description-stmt] 8358 [reference-stmt] 8359 1*(data-def-stmt / case-stmt / 8360 action-stmt / notification-stmt) 8361 "}" stmtsep 8363 uses-augment-arg-str = < a string that matches the rule > 8364 < uses-augment-arg > 8366 uses-augment-arg = descendant-schema-nodeid 8368 augment-stmt = augment-keyword sep augment-arg-str optsep 8369 "{" stmtsep 8370 ;; these stmts can appear in any order 8371 [when-stmt] 8372 *if-feature-stmt 8373 [status-stmt] 8374 [description-stmt] 8375 [reference-stmt] 8376 1*(data-def-stmt / case-stmt / 8377 action-stmt / notification-stmt) 8378 "}" stmtsep 8380 augment-arg-str = < a string that matches the rule > 8381 < augment-arg > 8383 augment-arg = absolute-schema-nodeid 8384 when-stmt = when-keyword sep string optsep 8385 (";" / 8386 "{" stmtsep 8387 ;; these stmts can appear in any order 8388 [description-stmt] 8389 [reference-stmt] 8390 "}") stmtsep 8392 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 8393 (";" / 8394 "{" stmtsep 8395 ;; these stmts can appear in any order 8396 *if-feature-stmt 8397 [status-stmt] 8398 [description-stmt] 8399 [reference-stmt] 8400 *(typedef-stmt / grouping-stmt) 8401 [input-stmt] 8402 [output-stmt] 8403 "}") stmtsep 8405 action-stmt = action-keyword sep identifier-arg-str optsep 8406 (";" / 8407 "{" stmtsep 8408 ;; these stmts can appear in any order 8409 *if-feature-stmt 8410 [status-stmt] 8411 [description-stmt] 8412 [reference-stmt] 8413 *(typedef-stmt / grouping-stmt) 8414 [input-stmt] 8415 [output-stmt] 8416 "}") stmtsep 8418 input-stmt = input-keyword optsep 8419 "{" stmtsep 8420 ;; these stmts can appear in any order 8421 *must-stmt 8422 *(typedef-stmt / grouping-stmt) 8423 1*data-def-stmt 8424 "}" stmtsep 8426 output-stmt = output-keyword optsep 8427 "{" stmtsep 8428 ;; these stmts can appear in any order 8429 *must-stmt 8430 *(typedef-stmt / grouping-stmt) 8431 1*data-def-stmt 8433 "}" stmtsep 8435 notification-stmt = notification-keyword sep 8436 identifier-arg-str optsep 8437 (";" / 8438 "{" stmtsep 8439 ;; these stmts can appear in any order 8440 *if-feature-stmt 8441 *must-stmt 8442 [status-stmt] 8443 [description-stmt] 8444 [reference-stmt] 8445 *(typedef-stmt / grouping-stmt) 8446 *data-def-stmt 8447 "}") stmtsep 8449 deviation-stmt = deviation-keyword sep 8450 deviation-arg-str optsep 8451 "{" stmtsep 8452 ;; these stmts can appear in any order 8453 [description-stmt] 8454 [reference-stmt] 8455 (deviate-not-supported-stmt / 8456 1*(deviate-add-stmt / 8457 deviate-replace-stmt / 8458 deviate-delete-stmt)) 8459 "}" stmtsep 8461 deviation-arg-str = < a string that matches the rule > 8462 < deviation-arg > 8464 deviation-arg = absolute-schema-nodeid 8466 deviate-not-supported-stmt = 8467 deviate-keyword sep 8468 not-supported-keyword-str stmtend 8470 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 8471 (";" / 8472 "{" stmtsep 8473 ;; these stmts can appear in any order 8474 [units-stmt] 8475 *must-stmt 8476 *unique-stmt 8477 [default-stmt] 8478 [config-stmt] 8479 [mandatory-stmt] 8480 [min-elements-stmt] 8482 [max-elements-stmt] 8483 "}") stmtsep 8485 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 8486 (";" / 8487 "{" stmtsep 8488 ;; these stmts can appear in any order 8489 [units-stmt] 8490 *must-stmt 8491 *unique-stmt 8492 [default-stmt] 8493 "}") stmtsep 8495 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 8496 (";" / 8497 "{" stmtsep 8498 ;; these stmts can appear in any order 8499 [type-stmt] 8500 [units-stmt] 8501 [default-stmt] 8502 [config-stmt] 8503 [mandatory-stmt] 8504 [min-elements-stmt] 8505 [max-elements-stmt] 8506 "}") stmtsep 8508 not-supported-keyword-str = < a string that matches the rule > 8509 < not-supported-keyword > 8511 add-keyword-str = < a string that matches the rule > 8512 < add-keyword > 8514 delete-keyword-str = < a string that matches the rule > 8515 < delete-keyword > 8517 replace-keyword-str = < a string that matches the rule > 8518 < replace-keyword > 8520 ;; represents the usage of an extension statement 8521 unknown-statement = prefix ":" identifier [sep string] optsep 8522 (";" / 8523 "{" optsep 8524 *((yang-stmt / unknown-statement) optsep) 8525 "}") stmtsep 8527 yang-stmt = action-stmt / 8528 anydata-stmt / 8529 anyxml-stmt / 8530 argument-stmt / 8531 augment-stmt / 8532 base-stmt / 8533 belongs-to-stmt / 8534 bit-stmt / 8535 case-stmt / 8536 choice-stmt / 8537 config-stmt / 8538 contact-stmt / 8539 container-stmt / 8540 default-stmt / 8541 description-stmt / 8542 deviate-add-stmt / 8543 deviate-delete-stmt / 8544 deviate-not-supported-stmt / 8545 deviate-replace-stmt / 8546 deviation-stmt / 8547 enum-stmt / 8548 error-app-tag-stmt / 8549 error-message-stmt / 8550 extension-stmt / 8551 feature-stmt / 8552 fraction-digits-stmt / 8553 grouping-stmt / 8554 identity-stmt / 8555 if-feature-stmt / 8556 import-stmt / 8557 include-stmt / 8558 input-stmt / 8559 key-stmt / 8560 leaf-list-stmt / 8561 leaf-stmt / 8562 length-stmt / 8563 list-stmt / 8564 mandatory-stmt / 8565 max-elements-stmt / 8566 min-elements-stmt / 8567 modifier-stmt / 8568 module-stmt / 8569 must-stmt / 8570 namespace-stmt / 8571 notification-stmt / 8572 ordered-by-stmt / 8573 organization-stmt / 8574 output-stmt / 8575 path-stmt / 8576 pattern-stmt / 8577 position-stmt / 8578 prefix-stmt / 8579 presence-stmt / 8580 range-stmt / 8581 reference-stmt / 8582 refine-stmt / 8583 require-instance-stmt / 8584 revision-date-stmt / 8585 revision-stmt / 8586 rpc-stmt / 8587 status-stmt / 8588 submodule-stmt / 8589 typedef-stmt / 8590 type-stmt / 8591 unique-stmt / 8592 units-stmt / 8593 uses-augment-stmt / 8594 uses-stmt / 8595 value-stmt / 8596 when-stmt / 8597 yang-version-stmt / 8598 yin-element-stmt 8600 ;; Ranges 8602 range-arg-str = < a string that matches the rule > 8603 < range-arg > 8605 range-arg = range-part *(optsep "|" optsep range-part) 8607 range-part = range-boundary 8608 [optsep ".." optsep range-boundary] 8610 range-boundary = min-keyword / max-keyword / 8611 integer-value / decimal-value 8613 ;; Lengths 8615 length-arg-str = < a string that matches the rule > 8616 < length-arg > 8618 length-arg = length-part *(optsep "|" optsep length-part) 8620 length-part = length-boundary 8621 [optsep ".." optsep length-boundary] 8623 length-boundary = min-keyword / max-keyword / 8624 non-negative-integer-value 8626 ;; Date 8628 date-arg-str = < a string that matches the rule > 8629 < date-arg > 8631 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 8633 ;; Schema Node Identifiers 8635 schema-nodeid = absolute-schema-nodeid / 8636 descendant-schema-nodeid 8638 absolute-schema-nodeid = 1*("/" node-identifier) 8640 descendant-schema-nodeid = 8641 node-identifier 8642 [absolute-schema-nodeid] 8644 node-identifier = [prefix ":"] identifier 8646 ;; Instance Identifiers 8648 instance-identifier = 1*("/" (node-identifier *predicate)) 8650 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 8652 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 8653 ((DQUOTE string DQUOTE) / 8654 (SQUOTE string SQUOTE)) 8656 pos = non-negative-integer-value 8658 ;; leafref path 8660 path-arg-str = < a string that matches the rule > 8661 < path-arg > 8663 path-arg = absolute-path / relative-path 8665 absolute-path = 1*("/" (node-identifier *path-predicate)) 8667 relative-path = 1*("../") descendant-path 8669 descendant-path = node-identifier 8670 [*path-predicate absolute-path] 8672 path-predicate = "[" *WSP path-equality-expr *WSP "]" 8674 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 8676 path-key-expr = current-function-invocation *WSP "/" *WSP 8677 rel-path-keyexpr 8679 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 8680 *(node-identifier *WSP "/" *WSP) 8681 node-identifier 8683 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 8685 ;; statement keywords 8686 action-keyword = %s"action" 8687 anydata-keyword = %s"anydata" 8688 anyxml-keyword = %s"anyxml" 8689 argument-keyword = %s"argument" 8690 augment-keyword = %s"augment" 8691 base-keyword = %s"base" 8692 belongs-to-keyword = %s"belongs-to" 8693 bit-keyword = %s"bit" 8694 case-keyword = %s"case" 8695 choice-keyword = %s"choice" 8696 config-keyword = %s"config" 8697 contact-keyword = %s"contact" 8698 container-keyword = %s"container" 8699 default-keyword = %s"default" 8700 description-keyword = %s"description" 8701 enum-keyword = %s"enum" 8702 error-app-tag-keyword = %s"error-app-tag" 8703 error-message-keyword = %s"error-message" 8704 extension-keyword = %s"extension" 8705 deviation-keyword = %s"deviation" 8706 deviate-keyword = %s"deviate" 8707 feature-keyword = %s"feature" 8708 fraction-digits-keyword = %s"fraction-digits" 8709 grouping-keyword = %s"grouping" 8710 identity-keyword = %s"identity" 8711 if-feature-keyword = %s"if-feature" 8712 import-keyword = %s"import" 8713 include-keyword = %s"include" 8714 input-keyword = %s"input" 8715 key-keyword = %s"key" 8716 leaf-keyword = %s"leaf" 8717 leaf-list-keyword = %s"leaf-list" 8718 length-keyword = %s"length" 8719 list-keyword = %s"list" 8720 mandatory-keyword = %s"mandatory" 8721 max-elements-keyword = %s"max-elements" 8722 min-elements-keyword = %s"min-elements" 8723 modifier-keyword = %s"modifier" 8724 module-keyword = %s"module" 8725 must-keyword = %s"must" 8726 namespace-keyword = %s"namespace" 8727 notification-keyword = %s"notification" 8728 ordered-by-keyword = %s"ordered-by" 8729 organization-keyword = %s"organization" 8730 output-keyword = %s"output" 8731 path-keyword = %s"path" 8732 pattern-keyword = %s"pattern" 8733 position-keyword = %s"position" 8734 prefix-keyword = %s"prefix" 8735 presence-keyword = %s"presence" 8736 range-keyword = %s"range" 8737 reference-keyword = %s"reference" 8738 refine-keyword = %s"refine" 8739 require-instance-keyword = %s"require-instance" 8740 revision-keyword = %s"revision" 8741 revision-date-keyword = %s"revision-date" 8742 rpc-keyword = %s"rpc" 8743 status-keyword = %s"status" 8744 submodule-keyword = %s"submodule" 8745 type-keyword = %s"type" 8746 typedef-keyword = %s"typedef" 8747 unique-keyword = %s"unique" 8748 units-keyword = %s"units" 8749 uses-keyword = %s"uses" 8750 value-keyword = %s"value" 8751 when-keyword = %s"when" 8752 yang-version-keyword = %s"yang-version" 8753 yin-element-keyword = %s"yin-element" 8755 ;; other keywords 8757 add-keyword = %s"add" 8758 current-keyword = %s"current" 8759 delete-keyword = %s"delete" 8760 deprecated-keyword = %s"deprecated" 8761 false-keyword = %s"false" 8762 invert-match-keyword = %s"invert-match" 8763 max-keyword = %s"max" 8764 min-keyword = %s"min" 8765 not-supported-keyword = %s"not-supported" 8766 obsolete-keyword = %s"obsolete" 8767 replace-keyword = %s"replace" 8768 system-keyword = %s"system" 8769 true-keyword = %s"true" 8770 unbounded-keyword = %s"unbounded" 8771 user-keyword = %s"user" 8773 and-keyword = %s"and" 8774 or-keyword = %s"or" 8775 not-keyword = %s"not" 8777 current-function-invocation = current-keyword *WSP "(" *WSP ")" 8779 ;;; Basic Rules 8781 prefix-arg-str = < a string that matches the rule > 8782 < prefix-arg > 8784 prefix-arg = prefix 8786 prefix = identifier 8788 identifier-arg-str = < a string that matches the rule > 8789 < identifier-arg > 8791 identifier-arg = identifier 8793 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 8794 identifier = (ALPHA / "_") 8795 *(ALPHA / DIGIT / "_" / "-" / ".") 8797 identifier-ref-arg-str = < a string that matches the rule > 8798 < identifier-ref-arg > 8800 identifier-ref-arg = identifier-ref 8802 identifier-ref = [prefix ":"] identifier 8804 string = < an unquoted string as returned by > 8805 < the scanner, that matches the rule > 8806 < yang-string > 8808 yang-string = *yang-char 8810 ;; any Unicode or ISO/IEC 10646 character including tab, carriage 8811 ;; return, and line feed, but excluding the other C0 control 8812 ;; characters, the surrogate blocks, and the noncharacters. 8813 yang-char = %x09 / %x0A / %x0D / %x20-D7FF / 8814 ; exclude surrogate blocks %xD800-DFFF 8815 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 8816 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 8817 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 8818 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 8819 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 8820 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 8821 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 8822 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 8823 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 8824 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 8825 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 8826 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 8827 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 8828 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 8829 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 8830 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 8831 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 8832 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 8834 integer-value = ("-" non-negative-integer-value) / 8835 non-negative-integer-value 8837 non-negative-integer-value = "0" / positive-integer-value 8839 positive-integer-value = (non-zero-digit *DIGIT) 8841 zero-integer-value = 1*DIGIT 8843 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 8845 sep = 1*(WSP / line-break) 8846 ; unconditional separator 8848 optsep = *(WSP / line-break) 8850 stmtsep = *(WSP / line-break / unknown-statement) 8852 line-break = CRLF / LF 8854 non-zero-digit = %x31-39 8856 decimal-value = integer-value ("." zero-integer-value) 8858 SQUOTE = %x27 8859 ; single quote 8861 ;;; RFC 5234 core rules. 8863 ALPHA = %x41-5A / %x61-7A 8864 ; A-Z / a-z 8866 CR = %x0D 8867 ; carriage return 8869 CRLF = CR LF 8870 ; Internet standard new line 8872 DIGIT = %x30-39 8873 ; 0-9 8875 DQUOTE = %x22 8876 ; double quote 8878 HTAB = %x09 8879 ; horizontal tab 8881 LF = %x0A 8882 ; linefeed 8884 SP = %x20 8885 ; space 8887 WSP = SP / HTAB 8888 ; whitespace 8890 8892 15. NETCONF Error Responses for YANG Related Errors 8894 A number of NETCONF error responses are defined for error cases 8895 related to the data-model handling. If the relevant YANG statement 8896 has an "error-app-tag" substatement, that overrides the default value 8897 specified below. 8899 15.1. Error Message for Data That Violates a unique Statement 8901 If a NETCONF operation would result in configuration data where a 8902 unique constraint is invalidated, the following error is returned: 8904 error-tag: operation-failed 8905 error-app-tag: data-not-unique 8906 error-info: : Contains an instance identifier that 8907 points to a leaf that invalidates the unique 8908 constraint. This element is present once for each 8909 non-unique leaf. 8911 The element is in the YANG 8912 namespace ("urn:ietf:params:xml:ns:yang:1"). 8914 15.2. Error Message for Data That Violates a max-elements Statement 8916 If a NETCONF operation would result in configuration data where a 8917 list or a leaf-list would have too many entries the following error 8918 is returned: 8920 error-tag: operation-failed 8921 error-app-tag: too-many-elements 8923 This error is returned once, with the error-path identifying the list 8924 node, even if there are more than one extra child present. 8926 15.3. Error Message for Data That Violates a min-elements Statement 8928 If a NETCONF operation would result in configuration data where a 8929 list or a leaf-list would have too few entries the following error is 8930 returned: 8932 error-tag: operation-failed 8933 error-app-tag: too-few-elements 8935 This error is returned once, with the error-path identifying the list 8936 node, even if there are more than one child missing. 8938 15.4. Error Message for Data That Violates a must Statement 8940 If a NETCONF operation would result in configuration data where the 8941 restrictions imposed by a "must" statement is violated the following 8942 error is returned, unless a specific "error-app-tag" substatement is 8943 present for the "must" statement. 8945 error-tag: operation-failed 8946 error-app-tag: must-violation 8948 15.5. Error Message for Data That Violates a require-instance Statement 8950 If a NETCONF operation would result in configuration data where a 8951 leaf of type "instance-identifier" or "leafref" marked with require- 8952 instance "true" refers to a non-existing instance, the following 8953 error is returned: 8955 error-tag: data-missing 8956 error-app-tag: instance-required 8957 error-path: Path to the instance-identifier or leafref leaf. 8959 15.6. Error Message for Data That Violates a mandatory choice Statement 8961 If a NETCONF operation would result in configuration data where no 8962 nodes exists in a mandatory choice, the following error is returned: 8964 error-tag: data-missing 8965 error-app-tag: missing-choice 8966 error-path: Path to the element with the missing choice. 8967 error-info: : Contains the name of the missing 8968 mandatory choice. 8970 The element is in the YANG 8971 namespace ("urn:ietf:params:xml:ns:yang:1"). 8973 15.7. Error Message for the "insert" Operation 8975 If the "insert" and "key" or "value" attributes are used in an 8976 for a list or leaf-list node, and the "key" or "value" 8977 refers to a non-existing instance, the following error is returned: 8979 error-tag: bad-attribute 8980 error-app-tag: missing-instance 8982 16. IANA Considerations 8984 This document registers one capability identifier URN from the 8985 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 8987 Index Capability Identifier 8988 ------------- --------------------------------------------------- 8989 :yang-library urn:ietf:params:netconf:capability:yang-library:1.0 8991 17. Security Considerations 8993 This document defines a language with which to write and read 8994 descriptions of management information. The language itself has no 8995 security impact on the Internet. 8997 The same considerations are relevant as for the base NETCONF protocol 8998 (see [RFC6241], Section 9). 9000 Data modeled in YANG might contain sensitive information. RPCs or 9001 notifications defined in YANG might transfer sensitive information. 9003 Security issues are related to the usage of data modeled in YANG. 9004 Such issues shall be dealt with in documents describing the data 9005 models and documents about the interfaces used to manipulate the data 9006 e.g., the NETCONF documents. 9008 Data modeled in YANG is dependent upon: 9010 o the security of the transmission infrastructure used to send 9011 sensitive information. 9013 o the security of applications that store or release such sensitive 9014 information. 9016 o adequate authentication and access control mechanisms to restrict 9017 the usage of sensitive data. 9019 YANG parsers need to be robust with respect to malformed documents. 9020 Reading malformed documents from unknown or untrusted sources could 9021 result in an attacker gaining privileges of the user running the YANG 9022 parser. In an extreme situation, the entire machine could be 9023 compromised. 9025 18. Contributors 9027 The following people all contributed significantly to the initial 9028 YANG document: 9030 - Andy Bierman (YumaWorks) 9031 - Balazs Lengyel (Ericsson) 9032 - David Partain (Ericsson) 9033 - Juergen Schoenwaelder (Jacobs University Bremen) 9034 - Phil Shafer (Juniper Networks) 9036 19. Acknowledgements 9038 The editor wishes to thank the following individuals, who all 9039 provided helpful comments on various versions of this document: 9040 Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, 9041 Ladislav Lhotka, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy 9042 Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert Wijnen, and 9043 Robert Wilton. 9045 20. ChangeLog 9047 RFC Editor: remove this section upon publication as an RFC. 9049 20.1. Version -10 9051 o Made single and double quote characters illegal in unquoted 9052 strings. 9054 o Allow "description" and "reference" in "import" and "include". 9056 o Removed redundant NETCONF Error Message subsection. 9058 o Editorial fixes and clarifications after second WGLC reviews. 9060 20.2. Version -09 9062 o Editorial fixes and clarifications after WGLC reviews. 9064 o when statement context clarification. 9066 o Allow "augment" to add conditionally mandatory nodes (see 9067 Section 7.17). 9069 o Allow non-unique config false leaf-lists. 9071 o Made handling of choice and false "when" expressions non-NETCONF 9072 specific. 9074 o Changed the function signatures for "derived-from" and 9075 "derived-from-or-self". 9077 20.3. Version -08 9079 o Fixes after WGLC reviews. 9081 20.4. Version -07 9083 o Fixes after WG review. 9085 o Included solution Y60-01. 9087 20.5. Version -06 9089 o Included solution Y45-05. 9091 20.6. Version -05 9093 o Included solution Y18-01. 9095 o Included solution Y25-02 (parts of it was included in -04). 9097 o Included solution Y34-05. 9099 o Included solution Y36-03. 9101 20.7. Version -04 9103 o Incorporated changes to ABNF grammar after review and errata for 9104 RFC 6020. 9106 o Included solution Y16-03. 9108 o Included solution Y49-04. 9110 o Included solution Y58-01. 9112 o Included solution Y59-01. 9114 20.8. Version -03 9116 o Incorporated changes from WG reviews. 9118 o Included solution Y05-01. 9120 o Included solution Y10-01. 9122 o Included solution Y13-01. 9124 o Included solution Y28-02. 9126 o Included solution Y55-01 (parts of it was included in -01). 9128 20.9. Version -02 9130 o Included solution Y02-01. 9132 o Included solution Y04-02. 9134 o Included solution Y11-01. 9136 o Included solution Y41-01. 9138 o Included solution Y56-01. 9140 20.10. Version -01 9142 o Included solution Y01-01. 9144 o Included solution Y03-01. 9146 o Included solution Y06-02. 9148 o Included solution Y07-01. 9150 o Included solution Y14-01. 9152 o Included solution Y20-01. 9154 o Included solution Y23-01. 9156 o Included solution Y29-01. 9158 o Included solution Y30-01. 9160 o Included solution Y31-01. 9162 o Included solution Y35-01. 9164 20.11. Version -00 9166 o Applied all reported errata for RFC 6020. 9168 o Updated YANG version to 1.1, and made the "yang-version" statement 9169 mandatory. 9171 21. References 9173 21.1. Normative References 9175 [I-D.ietf-netconf-yang-library] 9176 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 9177 Library", draft-ietf-netconf-yang-library-04 (work in 9178 progress), February 2016. 9180 [ISO.10646] 9181 International Organization for Standardization, 9182 "Information Technology - Universal Multiple-Octet Coded 9183 Character Set (UCS)", ISO Standard 10646:2003, 2003. 9185 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9186 Requirement Levels", BCP 14, RFC 2119, 9187 DOI 10.17487/RFC2119, March 1997, 9188 . 9190 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 9191 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 9192 2003, . 9194 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9195 Resource Identifier (URI): Generic Syntax", STD 66, 9196 RFC 3986, DOI 10.17487/RFC3986, January 2005, 9197 . 9199 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9200 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9201 . 9203 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9204 Specifications: ABNF", STD 68, RFC 5234, 9205 DOI 10.17487/RFC5234, January 2008, 9206 . 9208 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 9209 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 9210 . 9212 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 9213 and A. Bierman, Ed., "Network Configuration Protocol 9214 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 9215 . 9217 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9218 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9219 . 9221 [XML-NAMES] 9222 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 9223 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 9224 Wide Web Consortium Recommendation REC-xml-names-20091208, 9225 December 2009, 9226 . 9228 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 9229 Version 1.0", World Wide Web Consortium Recommendation 9230 REC-xpath-19991116, November 1999, 9231 . 9233 [XSD-TYPES] 9234 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 9235 Second Edition", World Wide Web Consortium Recommendation 9236 REC-xmlschema-2-20041028, October 2004, 9237 . 9239 21.2. Informative References 9241 [I-D.ietf-netconf-restconf] 9242 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 9243 Protocol", draft-ietf-netconf-restconf-09 (work in 9244 progress), December 2015. 9246 [I-D.ietf-netmod-yang-json] 9247 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 9248 draft-ietf-netmod-yang-json-07 (work in progress), January 9249 2016. 9251 [I-D.vanderstok-core-comi] 9252 Stok, P., Bierman, A., Schoenwaelder, J., and A. Sehgal, 9253 "CoAP Management Interface", draft-vanderstok-core-comi-08 9254 (work in progress), October 2015. 9256 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9257 Schoenwaelder, Ed., "Structure of Management Information 9258 Version 2 (SMIv2)", STD 58, RFC 2578, 9259 DOI 10.17487/RFC2578, April 1999, 9260 . 9262 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 9263 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 9264 STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 9265 . 9267 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 9268 Structure of Management Information", RFC 3780, 9269 DOI 10.17487/RFC3780, May 2004, 9270 . 9272 [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC 9273 Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, 9274 July 2007, . 9276 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 9277 the Network Configuration Protocol (NETCONF)", RFC 6020, 9278 DOI 10.17487/RFC6020, October 2010, 9279 . 9281 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 9282 Information Version 2 (SMIv2) MIB Modules to YANG 9283 Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, 9284 . 9286 [XPATH2.0] 9287 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 9288 Kay, M., Robie, J., and J. Simeon, "XML Path Language 9289 (XPath) 2.0 (Second Edition)", World Wide Web Consortium 9290 Recommendation REC-xpath20-20101214, December 2010, 9291 . 9293 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 9294 Wide Web Consortium Recommendation REC-xslt-19991116, 9295 November 1999, 9296 . 9298 Author's Address 9300 Martin Bjorklund (editor) 9301 Tail-f Systems 9303 Email: mbj@tail-f.com