idnits 2.17.1 draft-ietf-netmod-rfc6020bis-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 14 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: When an existing enumeration type is restricted, the set of assigned names in the new type MUST be a subset of the base type's set of assigned names. The value of such an assigned name MUST not be changed. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 6, 2015) is 3210 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 6698 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML-NAMES' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Obsoletes: 6020 (if approved) July 6, 2015 5 Intended status: Standards Track 6 Expires: January 7, 2016 8 YANG - A Data Modeling Language for the Network Configuration Protocol 9 (NETCONF) 10 draft-ietf-netmod-rfc6020bis-06 12 Abstract 14 YANG is a data modeling language used to model configuration and 15 state data manipulated by the Network Configuration Protocol 16 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 17 This document obsoletes RFC 6020. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 7, 2016. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 66 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 67 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13 70 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 72 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 73 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 74 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 75 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 76 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20 77 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 78 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 79 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 80 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 81 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25 82 4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 83 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 84 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 85 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 86 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 87 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 88 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 89 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 90 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 91 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 92 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 93 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 94 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 95 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 96 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 34 97 5.6.5. Announcing Conformance Information in NETCONF . . . . 37 98 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 38 99 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38 100 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 38 101 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 38 102 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 38 103 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39 104 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 40 105 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 40 106 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 41 107 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 41 108 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 42 109 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 42 110 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 44 111 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 44 112 7.1. The module Statement . . . . . . . . . . . . . . . . . . 45 113 7.1.1. The module's Substatements . . . . . . . . . . . . . 46 114 7.1.2. The yang-version Statement . . . . . . . . . . . . . 47 115 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 48 116 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 48 117 7.1.5. The import Statement . . . . . . . . . . . . . . . . 48 118 7.1.6. The include Statement . . . . . . . . . . . . . . . . 49 119 7.1.7. The organization Statement . . . . . . . . . . . . . 50 120 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 50 121 7.1.9. The revision Statement . . . . . . . . . . . . . . . 50 122 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 51 123 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 52 124 7.2.1. The submodule's Substatements . . . . . . . . . . . . 53 125 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 54 126 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 55 127 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 55 128 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 56 129 7.3.2. The typedef's type Statement . . . . . . . . . . . . 56 130 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 56 131 7.3.4. The typedef's default Statement . . . . . . . . . . . 56 132 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 57 133 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 57 134 7.4.1. The type's Substatements . . . . . . . . . . . . . . 57 135 7.5. The container Statement . . . . . . . . . . . . . . . . . 57 136 7.5.1. Containers with Presence . . . . . . . . . . . . . . 58 137 7.5.2. The container's Substatements . . . . . . . . . . . . 58 138 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 59 139 7.5.4. The must's Substatements . . . . . . . . . . . . . . 60 140 7.5.5. The presence Statement . . . . . . . . . . . . . . . 61 141 7.5.6. The container's Child Node Statements . . . . . . . . 61 142 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 143 7.5.8. NETCONF Operations . . . . . . . . . . 62 144 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 62 145 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 63 146 7.6.1. The leaf's default value . . . . . . . . . . . . . . 64 147 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 64 148 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 65 149 7.6.4. The leaf's default Statement . . . . . . . . . . . . 65 150 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 65 151 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 65 152 7.6.7. NETCONF Operations . . . . . . . . . . 66 153 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 154 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 67 155 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 67 156 7.7.2. The leaf-list's default values . . . . . . . . . . . 68 157 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 69 158 7.7.4. The leaf-list's default Statement . . . . . . . . . . 69 159 7.7.5. The min-elements Statement . . . . . . . . . . . . . 69 160 7.7.6. The max-elements Statement . . . . . . . . . . . . . 70 161 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 70 162 7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 71 163 7.7.9. NETCONF Operations . . . . . . . . . . 71 164 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 72 165 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 74 166 7.8.1. The list's Substatements . . . . . . . . . . . . . . 74 167 7.8.2. The list's key Statement . . . . . . . . . . . . . . 75 168 7.8.3. The list's unique Statement . . . . . . . . . . . . . 76 169 7.8.4. The list's Child Node Statements . . . . . . . . . . 77 170 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 77 171 7.8.6. NETCONF Operations . . . . . . . . . . 78 172 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 79 173 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 82 174 7.9.1. The choice's Substatements . . . . . . . . . . . . . 82 175 7.9.2. The choice's case Statement . . . . . . . . . . . . . 83 176 7.9.3. The choice's default Statement . . . . . . . . . . . 84 177 7.9.4. The choice's mandatory Statement . . . . . . . . . . 86 178 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 86 179 7.9.6. NETCONF Operations . . . . . . . . . . 86 180 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 181 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 87 182 7.10.1. The anydata's Substatements . . . . . . . . . . . . 88 183 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 88 184 7.10.3. NETCONF Operations . . . . . . . . . . 88 185 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 89 186 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 89 187 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 90 188 7.11.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 90 189 7.11.3. NETCONF Operations . . . . . . . . . . 90 190 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 91 191 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 91 192 7.12.1. The grouping's Substatements . . . . . . . . . . . . 92 193 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 92 194 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 93 195 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 93 196 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 93 197 7.13.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 94 198 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 94 199 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 96 200 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 96 201 7.14.2. The input Statement . . . . . . . . . . . . . . . . 96 202 7.14.3. The output Statement . . . . . . . . . . . . . . . . 97 203 7.14.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 98 204 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 99 205 7.15. The action Statement . . . . . . . . . . . . . . . . . . 99 206 7.15.1. The action's Substatements . . . . . . . . . . . . . 100 207 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 100 208 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 101 209 7.16. The notification Statement . . . . . . . . . . . . . . . 102 210 7.16.1. The notification's Substatements . . . . . . . . . . 103 211 7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 103 212 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 104 213 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 105 214 7.17.1. The augment's Substatements . . . . . . . . . . . . 106 215 7.17.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 107 216 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 217 7.18. The identity Statement . . . . . . . . . . . . . . . . . 109 218 7.18.1. The identity's Substatements . . . . . . . . . . . . 109 219 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 109 220 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 110 221 7.19. The extension Statement . . . . . . . . . . . . . . . . . 110 222 7.19.1. The extension's Substatements . . . . . . . . . . . 111 223 7.19.2. The argument Statement . . . . . . . . . . . . . . . 111 224 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 225 7.20. Conformance-Related Statements . . . . . . . . . . . . . 112 226 7.20.1. The feature Statement . . . . . . . . . . . . . . . 112 227 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 114 228 7.20.3. The deviation Statement . . . . . . . . . . . . . . 115 229 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 117 230 7.21.1. The config Statement . . . . . . . . . . . . . . . . 117 231 7.21.2. The status Statement . . . . . . . . . . . . . . . . 118 232 7.21.3. The description Statement . . . . . . . . . . . . . 119 233 7.21.4. The reference Statement . . . . . . . . . . . . . . 119 234 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 119 235 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 120 236 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 120 237 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 121 238 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 121 239 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 121 240 8.3.2. NETCONF Processing . . . . . . . . . . 122 241 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 123 242 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 123 243 9.1. Canonical Representation . . . . . . . . . . . . . . . . 123 244 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 124 245 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 124 246 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 247 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 248 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 125 249 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 250 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 126 251 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 127 252 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 127 253 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 127 254 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 127 255 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 256 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 128 257 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 128 258 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 259 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 129 260 9.4.4. The length Statement . . . . . . . . . . . . . . . . 129 261 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 130 262 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 130 263 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 130 264 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 131 265 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 132 266 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 267 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 268 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 132 269 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 132 270 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 271 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 272 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 132 273 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 274 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 135 275 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 276 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 135 277 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 278 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 135 279 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 280 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 137 281 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 282 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 137 283 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 284 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 137 285 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 138 286 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 138 287 9.9.3. The require-instance Statement . . . . . . . . . . . 138 288 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 139 289 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 139 290 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 139 291 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 143 292 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 143 293 9.10.2. The identityref's base Statement . . . . . . . . . . 143 294 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 143 295 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 144 296 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 144 297 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 145 298 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 299 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 145 300 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 301 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 145 302 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 146 303 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 304 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 146 305 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 146 306 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 146 307 9.13. The instance-identifier Built-In Type . . . . . . . . . . 147 308 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 309 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 148 310 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 311 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 312 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 149 313 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 149 314 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 149 315 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 149 316 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 149 317 10.3. Functions for the YANG Types "leafref" and "instance- 318 identifier" . . . . . . . . . . . . . . . . . . . . . . 150 319 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 150 320 10.4. Functions for the YANG Type "identityref" . . . . . . . 151 321 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 151 322 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 151 323 10.5. Functions for the YANG Type "enumeration" . . . . . . . 152 324 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 152 325 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 153 326 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 153 327 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 154 328 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 329 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 157 330 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 159 331 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 160 332 14. Error Responses for YANG Related Errors . . . . . . . . . . . 184 333 14.1. Error Message for Data That Violates a unique Statement 184 334 14.2. Error Message for Data That Violates a max-elements 335 Statement . . . . . . . . . . . . . . . . . . . . . . . 185 337 14.3. Error Message for Data That Violates a min-elements 338 Statement . . . . . . . . . . . . . . . . . . . . . . . 185 339 14.4. Error Message for Data That Violates a must Statement . 185 340 14.5. Error Message for Data That Violates a require-instance 341 Statement . . . . . . . . . . . . . . . . . . . . . . . 186 342 14.6. Error Message for Data That Does Not Match a leafref 343 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 186 344 14.7. Error Message for Data That Violates a mandatory choice 345 Statement . . . . . . . . . . . . . . . . . . . . . . . 186 346 14.8. Error Message for the "insert" Operation . . . . . . . . 186 347 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 187 348 15.1. Media type application/yang . . . . . . . . . . . . . . 188 349 15.2. Media type application/yin+xml . . . . . . . . . . . . . 189 350 16. Security Considerations . . . . . . . . . . . . . . . . . . . 191 351 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191 352 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192 353 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192 354 19.1. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192 355 19.2. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192 356 19.3. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192 357 19.4. Version -03 . . . . . . . . . . . . . . . . . . . . . . 192 358 19.5. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193 359 19.6. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193 360 19.7. Version -00 . . . . . . . . . . . . . . . . . . . . . . 193 361 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 362 20.1. Normative References . . . . . . . . . . . . . . . . . . 194 363 20.2. Informative References . . . . . . . . . . . . . . . . . 195 364 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 196 366 1. Introduction 368 YANG is a data modeling language used to model configuration and 369 state data manipulated by the Network Configuration Protocol 370 (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. 371 YANG is used to model the operations and content layers of NETCONF 372 (see the NETCONF Configuration Protocol [RFC6241], Section 1.2). 374 This document describes the syntax and semantics of the YANG 375 language, how the data model defined in a YANG module is represented 376 in the Extensible Markup Language (XML), and how NETCONF operations 377 are used to manipulate the data. 379 1.1. Summary of Changes from RFC 6020 381 This document defines version 1.1 of the YANG language. YANG version 382 1.1 is a maintenance release of the YANG language, addressing 383 ambiguities and defects in the original specification [RFC6020]. 385 o Changed the YANG version from "1" to "1.1". 387 o Made the "yang-version" statement mandatory. 389 o Made noncharacters illegal in the built-in type "string". 391 o Defined the legal characters in YANG modules. 393 o Changed the rules for the interpretation of escaped characters in 394 double quoted strings. This is an backwards incompatible change 395 from YANG version 1. A module that uses a character sequence that 396 is now illegal must change the string to match the new rules. See 397 Section 6.1.3 for details. 399 o Extended the "if-feature" syntax to be a boolean expression over 400 feature names. 402 o Allow "if-feature" in "bit", "enum", and "identity". 404 o Allow "if-feature" in "refine". 406 o Made "when" and "if-feature" illegal on list keys, unless the 407 parent is also conditional, and the condition matches the parent's 408 condition. 410 o Allow "choice" as a shorthand case statement (see Section 7.9). 412 o Added a new substatement "modifier" to pattern (see 413 Section 9.4.6). 415 o Allow "must" in "input", "output", and "notification". 417 o Added a set of new XPath functions in Section 10. 419 o Clarified the XPath context's tree in Section 6.4.1. 421 o Defined the string value of an identityref in XPath expressions 422 (see Section 9.10). 424 o Clarified what unprefixed names means in leafrefs in typedefs (see 425 Section 9.9.2). 427 o Allow identities to be derived from multiple base identities (see 428 Section 7.18 and Section 9.10). 430 o Allow enumerations to be subtyped (see Section 9.6). 432 o Allow leaf-lists to have default values (see Section 7.7.2). 434 o Use [RFC7405] syntax for case-sensitive strings in the grammar. 436 o Changed the module advertisement mechanism (see Section 5.6.5). 438 o Changed the scoping rules for definitions in submodules. A 439 submodule can now reference all defintions in all submodules that 440 belong to the same module, without using the "include" statement. 442 o Added a new statement "action" that is used to define operations 443 tied to data nodes. 445 o Allow notifications to be tied to data nodes. 447 o Added a new data definition statement "anydata" (see 448 Section 7.10). 450 2. Keywords 452 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 453 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 454 "OPTIONAL" in this document are to be interpreted as described in BCP 455 14, [RFC2119]. 457 3. Terminology 459 o action: An operation defined for a node in the data tree. 461 o anydata: A data node that can contain an unknown set of nodes that 462 can be modelled by YANG. 464 o anyxml: A data node that can contain an unknown chunk of XML data. 466 o augment: Adds new schema nodes to a previously defined schema 467 node. 469 o base type: The type from which a derived type was derived, which 470 may be either a built-in type or another derived type. 472 o built-in type: A YANG data type defined in the YANG language, such 473 as uint32 or string. 475 o choice: A schema node where only one of a number of identified 476 alternatives is valid. 478 o configuration data: The set of writable data that is required to 479 transform a system from its initial default state into its current 480 state [RFC6241]. 482 o conformance: A measure of how accurately a device follows a data 483 model. 485 o container: An interior data node that exists in at most one 486 instance in the data tree. A container has no value, but rather a 487 set of child nodes. 489 o data definition statement: A statement that defines new data 490 nodes. One of container, leaf, leaf-list, list, choice, case, 491 augment, uses, anydata, and anyxml. 493 o data model: A data model describes how data is represented and 494 accessed. 496 o data node: A node in the schema tree that can be instantiated in a 497 data tree. One of container, leaf, leaf-list, list, anydata, and 498 anyxml. 500 o data tree: The instantiated tree of configuration and state data 501 on a device. 503 o derived type: A type that is derived from a built-in type (such as 504 uint32), or another derived type. 506 o device deviation: A failure of the device to implement the module 507 faithfully. 509 o extension: An extension attaches non-YANG semantics to statements. 510 The extension statement defines new statements to express these 511 semantics. 513 o feature: A mechanism for marking a portion of the model as 514 optional. Definitions can be tagged with a feature name and are 515 only valid on devices that support that feature. 517 o grouping: A reusable set of schema nodes, which may be used 518 locally in the module, in modules that include it, and by other 519 modules that import from it. The grouping statement is not a data 520 definition statement and, as such, does not define any nodes in 521 the schema tree. 523 o identifier: Used to identify different kinds of YANG items by 524 name. 526 o instance identifier: A mechanism for identifying a particular node 527 in a data tree. 529 o interior node: Nodes within a hierarchy that are not leaf nodes. 531 o leaf: A data node that exists in at most one instance in the data 532 tree. A leaf has a value but no child nodes. 534 o leaf-list: Like the leaf node but defines a set of uniquely 535 identifiable nodes rather than a single node. Each node has a 536 value but no child nodes. 538 o list: An interior data node that may exist in multiple instances 539 in the data tree. A list has no value, but rather a set of child 540 nodes. 542 o module: A YANG module defines a hierarchy of nodes that can be 543 used for NETCONF-based operations. With its definitions and the 544 definitions it imports or includes from elsewhere, a module is 545 self-contained and "compilable". 547 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 549 o RPC operation: A specific Remote Procedure Call, as used within 550 the NETCONF protocol. It is also called a protocol operation. 552 o schema node: A node in the schema tree. One of action, container, 553 leaf, leaf-list, list, choice, case, rpc, input, output, 554 notification, anydata, and anyxml. 556 o schema node identifier: A mechanism for identifying a particular 557 node in the schema tree. 559 o schema tree: The definition hierarchy specified within a module. 561 o state data: The additional data on a system that is not 562 configuration data such as read-only status information and 563 collected statistics [RFC6241]. 565 o submodule: A partial module definition that contributes derived 566 types, groupings, data nodes, RPCs, actions, and notifications to 567 a module. A YANG module can be constructed from a number of 568 submodules. 570 o top-level data node: A data node where there is no other data node 571 between it and a module or submodule statement. 573 o uses: The "uses" statement is used to instantiate the set of 574 schema nodes defined in a grouping statement. The instantiated 575 nodes may be refined and augmented to tailor them to any specific 576 needs. 578 3.1. Mandatory Nodes 580 A mandatory node is one of: 582 o A leaf, choice, anydata, or anyxml node with a "mandatory" 583 statement with the value "true". 585 o A list or leaf-list node with a "min-elements" statement with a 586 value greater than zero. 588 o A container node without a "presence" statement, which has at 589 least one mandatory node as a child. 591 4. YANG Overview 593 4.1. Functional Overview 595 YANG is a language used to model data for the NETCONF protocol. A 596 YANG module defines a hierarchy of data that can be used for NETCONF- 597 based operations, including configuration, state data, Remote 598 Procedure Calls (RPCs), and notifications. This allows a complete 599 description of all data sent between a NETCONF client and server. 601 YANG models the hierarchical organization of data as a tree in which 602 each node has a name, and either a value or a set of child nodes. 603 YANG provides clear and concise descriptions of the nodes, as well as 604 the interaction between those nodes. 606 YANG structures data models into modules and submodules. A module 607 can import data from other external modules, and include data from 608 submodules. The hierarchy can be augmented, allowing one module to 609 add data nodes to the hierarchy defined in another module. This 610 augmentation can be conditional, with new nodes appearing only if 611 certain conditions are met. 613 YANG models can describe constraints to be enforced on the data, 614 restricting the appearance or value of nodes based on the presence or 615 value of other nodes in the hierarchy. These constraints are 616 enforceable by either the client or the server, and valid content 617 MUST abide by them. 619 YANG defines a set of built-in types, and has a type mechanism 620 through which additional types may be defined. Derived types can 621 restrict their base type's set of valid values using mechanisms like 622 range or pattern restrictions that can be enforced by clients or 623 servers. They can also define usage conventions for use of the 624 derived type, such as a string-based type that contains a host name. 626 YANG permits the definition of reusable groupings of nodes. The 627 instantiation of these groupings can refine or augment the nodes, 628 allowing it to tailor the nodes to its particular needs. Derived 629 types and groupings can be defined in one module or submodule and 630 used in either that location or in another module or submodule that 631 imports or includes it. 633 YANG data hierarchy constructs include defining lists where list 634 entries are identified by keys that distinguish them from each other. 635 Such lists may be defined as either sorted by user or automatically 636 sorted by the system. For user-sorted lists, operations are defined 637 for manipulating the order of the list entries. 639 YANG modules can be translated into an equivalent XML syntax called 640 YANG Independent Notation (YIN) (Section 12), allowing applications 641 using XML parsers and Extensible Stylesheet Language Transformations 642 (XSLT) scripts to operate on the models. The conversion from YANG to 643 YIN is lossless, so content in YIN can be round-tripped back into 644 YANG. 646 YANG strikes a balance between high-level data modeling and low-level 647 bits-on-the-wire encoding. The reader of a YANG module can see the 648 high-level view of the data model while understanding how the data 649 will be encoded in NETCONF operations. 651 YANG is an extensible language, allowing extension statements to be 652 defined by standards bodies, vendors, and individuals. The statement 653 syntax allows these extensions to coexist with standard YANG 654 statements in a natural way, while extensions in a YANG module stand 655 out sufficiently for the reader to notice them. 657 YANG resists the tendency to solve all possible problems, limiting 658 the problem space to allow expression of NETCONF data models, not 659 arbitrary XML documents or arbitrary data models. The data models 660 described by YANG are designed to be easily operated upon by NETCONF 661 operations. 663 To the extent possible, YANG maintains compatibility with Simple 664 Network Management Protocol's (SNMP's) SMIv2 (Structure of Management 665 Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules 666 can be automatically translated into YANG modules for read-only 667 access. However, YANG is not concerned with reverse translation from 668 YANG to SMIv2. 670 Like NETCONF, YANG targets smooth integration with the device's 671 native management infrastructure. This allows implementations to 672 leverage their existing access control mechanisms to protect or 673 expose elements of the data model. 675 4.2. Language Overview 677 This section introduces some important constructs used in YANG that 678 will aid in the understanding of the language specifics in later 679 sections. This progressive approach handles the inter-related nature 680 of YANG concepts and statements. A detailed description of YANG 681 statements and syntax begins in Section 7. 683 4.2.1. Modules and Submodules 685 A module contains three types of statements: module-header 686 statements, revision statements, and definition statements. The 687 module header statements describe the module and give information 688 about the module itself, the revision statements give information 689 about the history of the module, and the definition statements are 690 the body of the module where the data model is defined. 692 A NETCONF server may implement a number of modules, allowing multiple 693 views of the same data, or multiple views of disjoint subsections of 694 the device's data. Alternatively, the server may implement only one 695 module that defines all available data. 697 A module may be divided into submodules, based on the needs of the 698 module owner. The external view remains that of a single module, 699 regardless of the presence or size of its submodules. 701 The "import" statement allows a module or submodule to reference 702 material defined in other modules. 704 The "include" statement is used by a module to incorporate the 705 contents of its submodules into the module. 707 4.2.2. Data Modeling Basics 709 YANG defines four types of nodes for data modeling. In each of the 710 following subsections, the example shows the YANG syntax as well as a 711 corresponding NETCONF XML representation. 713 4.2.2.1. Leaf Nodes 715 A leaf node contains simple data like an integer or a string. It has 716 exactly one value of a particular type and no child nodes. 718 YANG Example: 720 leaf host-name { 721 type string; 722 description "Hostname for this system"; 723 } 725 NETCONF XML Example: 727 my.example.com 729 The "leaf" statement is covered in Section 7.6. 731 4.2.2.2. Leaf-List Nodes 733 A leaf-list defines a sequence of values of a particular type. 735 YANG Example: 737 leaf-list domain-search { 738 type string; 739 description "List of domain names to search"; 740 } 742 NETCONF XML Example: 744 high.example.com 745 low.example.com 746 everywhere.example.com 748 The "leaf-list" statement is covered in Section 7.7. 750 4.2.2.3. Container Nodes 752 A container node is used to group related nodes in a subtree. A 753 container has only child nodes and no value. A container may contain 754 any number of child nodes of any type (including leafs, lists, 755 containers, and leaf-lists). 757 YANG Example: 759 container system { 760 container login { 761 leaf message { 762 type string; 763 description 764 "Message given at start of login session"; 765 } 766 } 767 } 769 NETCONF XML Example: 771 772 773 Good morning 774 775 777 The "container" statement is covered in Section 7.5. 779 4.2.2.4. List Nodes 781 A list defines a sequence of list entries. Each entry is like a 782 structure or a record instance, and is uniquely identified by the 783 values of its key leafs. A list can define multiple key leafs and 784 may contain any number of child nodes of any type (including leafs, 785 lists, containers etc.). 787 YANG Example: 789 list user { 790 key "name"; 791 leaf name { 792 type string; 793 } 794 leaf full-name { 795 type string; 796 } 797 leaf class { 798 type string; 799 } 800 } 802 NETCONF XML Example: 804 805 glocks 806 Goldie Locks 807 intruder 808 809 810 snowey 811 Snow White 812 free-loader 813 814 815 rzell 816 Rapun Zell 817 tower 818 820 The "list" statement is covered in Section 7.8. 822 4.2.2.5. Example Module 824 These statements are combined to define the module: 826 // Contents of "acme-system.yang" 827 module acme-system { 828 yang-version 1.1; 829 namespace "http://acme.example.com/system"; 830 prefix "acme"; 832 organization "ACME Inc."; 833 contact "joe@acme.example.com"; 834 description 835 "The module for entities implementing the ACME system."; 837 revision 2007-06-09 { 838 description "Initial revision."; 839 } 841 container system { 842 leaf host-name { 843 type string; 844 description "Hostname for this system"; 845 } 847 leaf-list domain-search { 848 type string; 849 description "List of domain names to search"; 850 } 852 container login { 853 leaf message { 854 type string; 855 description 856 "Message given at start of login session"; 857 } 859 list user { 860 key "name"; 861 leaf name { 862 type string; 863 } 864 leaf full-name { 865 type string; 866 } 867 leaf class { 868 type string; 869 } 870 } 871 } 872 } 873 } 875 4.2.3. State Data 877 YANG can model state data, as well as configuration data, based on 878 the "config" statement. When a node is tagged with "config false", 879 its subhierarchy is flagged as state data, to be reported using 880 NETCONF's operation, not the operation. Parent 881 containers, lists, and key leafs are reported also, giving the 882 context for the state data. 884 In this example, two leafs are defined for each interface, a 885 configured speed and an observed speed. The observed speed is not 886 configuration, so it can be returned with NETCONF operations, 887 but not with operations. The observed speed is not 888 configuration data, and it cannot be manipulated using . 890 list interface { 891 key "name"; 893 leaf name { 894 type string; 895 } 896 leaf speed { 897 type enumeration { 898 enum 10m; 899 enum 100m; 900 enum auto; 901 } 902 } 903 leaf observed-speed { 904 type uint32; 905 config false; 906 } 907 } 909 4.2.4. Built-In Types 911 YANG has a set of built-in types, similar to those of many 912 programming languages, but with some differences due to special 913 requirements from the management domain. The following table 914 summarizes the built-in types discussed in Section 9: 916 +---------------------+-------------------------------------+ 917 | Name | Description | 918 +---------------------+-------------------------------------+ 919 | binary | Any binary data | 920 | bits | A set of bits or flags | 921 | boolean | "true" or "false" | 922 | decimal64 | 64-bit signed decimal number | 923 | empty | A leaf that does not have any value | 924 | enumeration | Enumerated strings | 925 | identityref | A reference to an abstract identity | 926 | instance-identifier | References a data tree node | 927 | int8 | 8-bit signed integer | 928 | int16 | 16-bit signed integer | 929 | int32 | 32-bit signed integer | 930 | int64 | 64-bit signed integer | 931 | leafref | A reference to a leaf instance | 932 | string | Human-readable string | 933 | uint8 | 8-bit unsigned integer | 934 | uint16 | 16-bit unsigned integer | 935 | uint32 | 32-bit unsigned integer | 936 | uint64 | 64-bit unsigned integer | 937 | union | Choice of member types | 938 +---------------------+-------------------------------------+ 940 The "type" statement is covered in Section 7.4. 942 4.2.5. Derived Types (typedef) 944 YANG can define derived types from base types using the "typedef" 945 statement. A base type can be either a built-in type or a derived 946 type, allowing a hierarchy of derived types. 948 A derived type can be used as the argument for the "type" statement. 950 YANG Example: 952 typedef percent { 953 type uint8 { 954 range "0 .. 100"; 955 } 956 description "Percentage"; 957 } 959 leaf completed { 960 type percent; 961 } 963 NETCONF XML Example: 965 20 967 The "typedef" statement is covered in Section 7.3. 969 4.2.6. Reusable Node Groups (grouping) 971 Groups of nodes can be assembled into reusable collections using the 972 "grouping" statement. A grouping defines a set of nodes that are 973 instantiated with the "uses" statement: 975 grouping target { 976 leaf address { 977 type inet:ip-address; 978 description "Target IP address"; 979 } 980 leaf port { 981 type inet:port-number; 982 description "Target port number"; 983 } 984 } 986 container peer { 987 container destination { 988 uses target; 989 } 990 } 992 NETCONF XML Example: 994 995 996
192.0.2.1
997 830 998 999 1001 The grouping can be refined as it is used, allowing certain 1002 statements to be overridden. In this example, the description is 1003 refined: 1005 container connection { 1006 container source { 1007 uses target { 1008 refine "address" { 1009 description "Source IP address"; 1010 } 1011 refine "port" { 1012 description "Source port number"; 1013 } 1014 } 1015 } 1016 container destination { 1017 uses target { 1018 refine "address" { 1019 description "Destination IP address"; 1020 } 1021 refine "port" { 1022 description "Destination port number"; 1023 } 1024 } 1025 } 1026 } 1028 The "grouping" statement is covered in Section 7.12. 1030 4.2.7. Choices 1032 YANG allows the data model to segregate incompatible nodes into 1033 distinct choices using the "choice" and "case" statements. The 1034 "choice" statement contains a set of "case" statements that define 1035 sets of schema nodes that cannot appear together. Each "case" may 1036 contain multiple nodes, but each node may appear in only one "case" 1037 under a "choice". 1039 When a node from one case is created in the data tree, all nodes from 1040 all other cases are implicitly deleted. The device handles the 1041 enforcement of the constraint, preventing incompatibilities from 1042 existing in the configuration. 1044 The choice and case nodes appear only in the schema tree, not in the 1045 data tree or NETCONF messages. The additional levels of hierarchy 1046 are not needed beyond the conceptual schema. 1048 YANG Example: 1050 container food { 1051 choice snack { 1052 case sports-arena { 1053 leaf pretzel { 1054 type empty; 1055 } 1056 leaf beer { 1057 type empty; 1058 } 1059 } 1060 case late-night { 1061 leaf chocolate { 1062 type enumeration { 1063 enum dark; 1064 enum milk; 1065 enum first-available; 1066 } 1067 } 1068 } 1069 } 1070 } 1072 NETCONF XML Example: 1074 1075 1076 1077 1079 The "choice" statement is covered in Section 7.9. 1081 4.2.8. Extending Data Models (augment) 1083 YANG allows a module to insert additional nodes into data models, 1084 including both the current module (and its submodules) or an external 1085 module. This is useful for example for vendors to add vendor- 1086 specific parameters to standard data models in an interoperable way. 1088 The "augment" statement defines the location in the data model 1089 hierarchy where new nodes are inserted, and the "when" statement 1090 defines the conditions when the new nodes are valid. 1092 YANG Example: 1094 augment /system/login/user { 1095 when "class != 'wheel'"; 1096 leaf uid { 1097 type uint16 { 1098 range "1000 .. 30000"; 1099 } 1100 } 1101 } 1103 This example defines a "uid" node that only is valid when the user's 1104 "class" is not "wheel". 1106 If a module augments another module, the XML representation of the 1107 data will reflect the prefix of the augmenting module. For example, 1108 if the above augmentation were in a module with prefix "other", the 1109 XML would look like: 1111 NETCONF XML Example: 1113 1114 alicew 1115 Alice N. Wonderland 1116 drop-out 1117 1024 1118 1120 The "augment" statement is covered in Section 7.17. 1122 4.2.9. Operation Definitions 1124 YANG allows the definition of operations. The operations' names, 1125 input parameters, and output parameters are modeled using YANG data 1126 definition statements. Operations on the top-level in a module are 1127 defined with the "rpc" statement. Operations can also be tied to a 1128 node in the data hierarchy. Such operations are defined with the 1129 "action" statement. 1131 YANG Example: 1133 rpc activate-software-image { 1134 input { 1135 leaf image-name { 1136 type string; 1137 } 1138 } 1139 output { 1140 leaf status { 1141 type string; 1142 } 1143 } 1144 } 1146 NETCONF XML Example: 1148 1150 1151 acmefw-2.3 1152 1153 1155 1157 1158 The image acmefw-2.3 is being installed. 1159 1160 1162 The "rpc" statement is covered in Section 7.14, and the "action" 1163 statement in Section 7.15. 1165 4.2.10. Notification Definitions 1167 YANG allows the definition of notifications suitable for NETCONF. 1168 YANG data definition statements are used to model the content of the 1169 notification. 1171 YANG Example: 1173 notification link-failure { 1174 description "A link failure has been detected"; 1175 leaf if-name { 1176 type leafref { 1177 path "/interface/name"; 1178 } 1179 } 1180 leaf if-admin-status { 1181 type admin-status; 1182 } 1183 leaf if-oper-status { 1184 type oper-status; 1185 } 1186 } 1188 NETCONF XML Example: 1190 1192 2007-09-01T10:00:00Z 1193 1194 so-1/2/3.0 1195 up 1196 down 1197 1198 1200 The "notification" statement is covered in Section 7.16. 1202 5. Language Concepts 1204 5.1. Modules and Submodules 1206 The module is the base unit of definition in YANG. A module defines 1207 a single data model. A module can define a complete, cohesive model, 1208 or augment an existing data model with additional nodes. 1210 Submodules are partial modules that contribute definitions to a 1211 module. A module may include any number of submodules, but each 1212 submodule may belong to only one module. 1214 The names of all standard modules and submodules MUST be unique. 1215 Developers of enterprise modules are RECOMMENDED to choose names for 1216 their modules that will have a low probability of colliding with 1217 standard or other enterprise modules, e.g., by using the enterprise 1218 or organization name as a prefix for the module name. 1220 A module uses the "include" statement to include all its submodules, 1221 and the "import" statement to reference external modules. Similarly, 1222 a submodule uses the "import" statement to reference other modules. 1224 For backward compatibility with YANG version 1, a submodule is 1225 allowed it use the "include" statement to reference other submodules 1226 within its module, but this is not necessary in YANG version 1.1. A 1227 submodule can reference any definition in the module it belongs to 1228 and in all submodules included by the module. 1230 A module or submodule MUST NOT include submodules from other modules, 1231 and a submodule MUST NOT import its own module. 1233 The import and include statements are used to make definitions 1234 available from other modules: 1236 o For a module or submodule to reference definitions in an external 1237 module, the external module MUST be imported. 1239 o A module MUST include all its submodules. 1241 o A module or submodule belonging to that module can reference 1242 definitions in the module and all submodules included by the 1243 module. 1245 There MUST NOT be any circular chains of imports or includes. For 1246 example, if module "a" imports module "b", "b" cannot import "a". 1248 When a definition in an external module is referenced, a locally 1249 defined prefix MUST be used, followed by ":", and then the external 1250 identifier. References to definitions in the local module MAY use 1251 the prefix notation. Since built-in data types do not belong to any 1252 module and have no prefix, references to built-in data types (e.g., 1253 int32) cannot use the prefix notation. The syntax for a reference to 1254 a definition is formally defined by the rule "identifier-ref" in 1255 Section 13. 1257 5.1.1. Import and Include by Revision 1259 Published modules evolve independently over time. In order to allow 1260 for this evolution, modules need to be imported using specific 1261 revisions. When a module is written, it uses the current revisions 1262 of other modules, based on what is available at the time. As future 1263 revisions of the imported modules are published, the importing module 1264 is unaffected and its contents are unchanged. When the author of the 1265 module is prepared to move to the most recently published revision of 1266 an imported module, the module is republished with an updated 1267 "import" statement. By republishing with the new revision, the 1268 authors explicitly indicate their acceptance of any changes in the 1269 imported module. 1271 For submodules, the issue is related but simpler. A module or 1272 submodule that includes submodules needs to specify the revision of 1273 the included submodules. If a submodule changes, any module or 1274 submodule that includes it needs to be updated. 1276 For example, module "b" imports module "a". 1278 module a { 1279 yang-version 1.1; 1280 namespace "http://example.com/a"; 1281 prefix "a"; 1283 revision 2008-01-01 { ... } 1284 grouping a { 1285 leaf eh { .... } 1286 } 1287 } 1289 module b { 1290 yang-version 1.1; 1291 namespace "http://example.com/b"; 1292 prefix "b"; 1294 import a { 1295 prefix p; 1296 revision-date 2008-01-01; 1297 } 1299 container bee { 1300 uses p:a; 1301 } 1302 } 1304 When the author of "a" publishes a new revision, the changes may not 1305 be acceptable to the author of "b". If the new revision is 1306 acceptable, the author of "b" can republish with an updated revision 1307 in the "import" statement. 1309 5.1.2. Module Hierarchies 1311 YANG allows modeling of data in multiple hierarchies, where data may 1312 have more than one top-level node. Models that have multiple top- 1313 level nodes are sometimes convenient, and are supported by YANG. 1315 NETCONF is capable of carrying any XML content as the payload in the 1316 and elements. The top-level nodes of YANG modules 1317 are encoded as child elements, in any order, within these elements. 1318 This encapsulation guarantees that the corresponding NETCONF messages 1319 are always well-formed XML documents. 1321 For example: 1323 module my-config { 1324 yang-version 1.1; 1325 namespace "http://example.com/schema/config"; 1326 prefix "co"; 1328 container system { ... } 1329 container routing { ... } 1330 } 1332 could be encoded in NETCONF as: 1334 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1352 5.2. File Layout 1354 YANG modules and submodules are typically stored in files, one module 1355 or submodule per file. The name of the file SHOULD be of the form: 1357 module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) 1359 YANG compilers can find imported modules and included submodules via 1360 this convention. While the YANG language defines modules, tools may 1361 compile submodules independently for performance and manageability 1362 reasons. Errors and warnings that cannot be detected during 1363 submodule compilation may be delayed until the submodules are linked 1364 into a cohesive module. 1366 5.3. XML Namespaces 1368 All YANG definitions are specified within a module that is bound to a 1369 particular XML namespace [XML-NAMES], which is a globally unique URI 1370 [RFC3986]. A NETCONF client or server uses the namespace during XML 1371 encoding of data. 1373 Namespaces for modules published in RFC streams [RFC4844] MUST be 1374 assigned by IANA, see Section 15. 1376 Namespaces for private modules are assigned by the organization 1377 owning the module without a central registry. Namespace URIs MUST be 1378 chosen so they cannot collide with standard or other enterprise 1379 namespaces, for example by using the enterprise or organization name 1380 in the namespace. 1382 The "namespace" statement is covered in Section 7.1.3. 1384 5.3.1. YANG XML Namespace 1386 YANG defines an XML namespace for NETCONF operations, 1387 content, and the element. The name of this 1388 namespace is "urn:ietf:params:xml:ns:yang:1". 1390 5.4. Resolving Grouping, Type, and Identity Names 1392 Grouping, type, and identity names are resolved in the context in 1393 which they are defined, rather than the context in which they are 1394 used. Users of groupings, typedefs, and identities are not required 1395 to import modules or include submodules to satisfy all references 1396 made by the original definition. This behaves like static scoping in 1397 a conventional programming language. 1399 For example, if a module defines a grouping in which a type is 1400 referenced, when the grouping is used in a second module, the type is 1401 resolved in the context of the original module, not the second 1402 module. There is no worry over conflicts if both modules define the 1403 type, since there is no ambiguity. 1405 5.5. Nested Typedefs and Groupings 1407 Typedefs and groupings may appear nested under many YANG statements, 1408 allowing these to be lexically scoped by the hierarchy under which 1409 they appear. This allows types and groupings to be defined near 1410 where they are used, rather than placing them at the top level of the 1411 hierarchy. The close proximity increases readability. 1413 Scoping also allows types to be defined without concern for naming 1414 conflicts between types in different submodules. Type names can be 1415 specified without adding leading strings designed to prevent name 1416 collisions within large modules. 1418 Finally, scoping allows the module author to keep types and groupings 1419 private to their module or submodule, preventing their reuse. Since 1420 only top-level types and groupings (i.e., those appearing as 1421 substatements to a module or submodule statement) can be used outside 1422 the module or submodule, the developer has more control over what 1423 pieces of their module are presented to the outside world, supporting 1424 the need to hide internal information and maintaining a boundary 1425 between what is shared with the outside world and what is kept 1426 private. 1428 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1429 type or grouping cannot be defined if a higher level in the schema 1430 hierarchy has a definition with a matching identifier. 1432 A reference to an unprefixed type or grouping, or one which uses the 1433 prefix of the current module, is resolved by locating the closest 1434 matching "typedef" or "grouping" statement among the immediate 1435 substatements of each ancestor statement. 1437 5.6. Conformance 1439 Conformance is a measure of how accurately a device follows the 1440 model. Generally speaking, devices are responsible for implementing 1441 the model faithfully, allowing applications to treat devices which 1442 implement the model identically. Deviations from the model can 1443 reduce the utility of the model and increase fragility of 1444 applications that use it. 1446 YANG modelers have three mechanisms for conformance: 1448 o the basic behavior of the model 1450 o optional features that are part of the model 1452 o deviations from the model 1454 We will consider each of these in sequence. 1456 5.6.1. Basic Behavior 1458 The model defines a contract between the NETCONF client and server, 1459 which allows both parties to have faith the other knows the syntax 1460 and semantics behind the modeled data. The strength of YANG lies in 1461 the strength of this contract. 1463 5.6.2. Optional Features 1465 In many models, the modeler will allow sections of the model to be 1466 conditional. The device controls whether these conditional portions 1467 of the model are supported or valid for that particular device. 1469 For example, a syslog data model may choose to include the ability to 1470 save logs locally, but the modeler will realize that this is only 1471 possible if the device has local storage. If there is no local 1472 storage, an application should not tell the device to save logs. 1474 YANG supports this conditional mechanism using a construct called 1475 "feature". Features give the modeler a mechanism for making portions 1476 of the module conditional in a manner that is controlled by the 1477 device. The model can express constructs that are not universally 1478 present in all devices. These features are included in the model 1479 definition, allowing a consistent view and allowing applications to 1480 learn which features are supported and tailor their behavior to the 1481 device. 1483 A module may declare any number of features, identified by simple 1484 strings, and may make portions of the module optional based on those 1485 features. If the device supports a feature, then the corresponding 1486 portions of the module are valid for that device. If the device 1487 doesn't support the feature, those parts of the module are not valid, 1488 and applications should behave accordingly. 1490 Features are defined using the "feature" statement. Definitions in 1491 the module that are conditional to the feature are noted by the 1492 "if-feature" statement. 1494 Further details are available in Section 7.20.1. 1496 5.6.3. Deviations 1498 In an ideal world, all devices would be required to implement the 1499 model exactly as defined, and deviations from the model would not be 1500 allowed. But in the real world, devices are often not able or 1501 designed to implement the model as written. For YANG-based 1502 automation to deal with these device deviations, a mechanism must 1503 exist for devices to inform applications of the specifics of such 1504 deviations. 1506 For example, a BGP module may allow any number of BGP peers, but a 1507 particular device may only support 16 BGP peers. Any application 1508 configuring the 17th peer will receive an error. While an error may 1509 suffice to let the application know it cannot add another peer, it 1510 would be far better if the application had prior knowledge of this 1511 limitation and could prevent the user from starting down the path 1512 that could not succeed. 1514 Device deviations are declared using the "deviation" statement, which 1515 takes as its argument a string that identifies a node in the schema 1516 tree. The contents of the statement details the manner in which the 1517 device implementation deviates from the contract as defined in the 1518 module. 1520 Further details are available in Section 7.20.3. 1522 5.6.4. Implementing a Module 1524 A server implements a module if it implements the module's data 1525 nodes, rpcs, notifications, and deviations. 1527 A server MUST NOT implement more than one revision of a module. 1529 If a server implements a module A that imports a module B, and A uses 1530 any node from B in an "augment" or "path" statement that the server 1531 supports, then the server MUST implement a revision of module B that 1532 has these nodes defined. This is regardless of if module B is 1533 imported by revision or not. 1535 NOTE: The next paragraph needs to be aligned with 1536 ietf-yang-library. 1538 If a server implements a module A that imports a module C without 1539 specifying the revision date of module C, and the server does not 1540 implement C (e.g., if C only defines some typedefs), the server MUST 1541 list module C in the "/modules/module" list from "ietf-yang-library", 1542 and it MUST set the leaf "default-revision" to "true" for this 1543 module. 1545 The reason for these rules is that clients need to be able to know 1546 the exact data model structure and types of all leafs and leaf-lists 1547 implemented in a server. 1549 For example, with these modules: 1551 module a { 1552 yang-version 1.1; 1553 namespace "http://example.com/a"; 1554 prefix "a"; 1556 import b { 1557 revision-date 2015-01-01; 1558 } 1559 import c; 1561 revision 2015-01-01; 1563 feature foo; 1565 augement "/b:x" { 1566 if-feature foo; 1567 leaf y { 1568 type b:myenum; 1569 } 1570 } 1572 container a { 1573 leaf x { 1574 type c:bar; 1575 } 1576 } 1577 } 1579 module b { 1580 yang-version 1.1; 1581 namespace "http://example.com/b"; 1582 prefix "b"; 1584 revision 2015-04-04; 1585 revision 2015-01-01; 1587 typedef myenum { 1588 type enumeration { 1589 enum zero; // added in 2015-01-01 1590 enum one; // added in 2015-04-04 1591 } 1592 } 1594 container x { // added in 2015-01-01 1595 container y; // added in 2015-04-04 1596 } 1597 } 1598 module c { 1599 yang-version 1.1; 1600 namespace "http://example.com/c"; 1601 prefix "c"; 1603 revision 2015-03-03; 1604 revision 2015-02-02; 1606 typedef foo { 1607 ... 1608 } 1609 } 1611 A server that implements revision "2015-01-01" of module "a" and 1612 supports feature "foo" can implement revision "2015-01-01" or 1613 "2015-04-04" of module "b". Since "b" was imported by revision, the 1614 type of leaf "/b:x/a:y" is the same regardless of which revision of 1615 "b" the server implements. 1617 A server that implements module "a", but does not support feature 1618 "foo" does not have to implement module "b". 1620 A server that implements revision "2015-01-01" of module "a" must 1621 pick a revision of module "c", and list it in the "/modules/module" 1622 list from "ietf-yang-library". 1624 The following shows valid data for the "/modules/module" list for a 1625 server that implements module "a": 1627 1628 ee1ecb017370cafd 1629 1630 a 1631 2015-01-01 1632 foo 1633 implement 1634 1635 1636 b 1637 2015-04-04 1638 implement 1639 1640 1641 c 1642 2015-02-02 1643 import 1644 1645 1646 #}} 1648 5.6.5. Announcing Conformance Information in NETCONF 1650 This document defines the following mechanism for announcing 1651 conformance information. Other mechanisms may be defined by future 1652 specifications. 1654 A NETCONF server announces the modules it implements by implementing 1655 the YANG module "ietf-yang-library" defined in 1656 [I-D.ietf-netconf-yang-library], and listing all implemented modules 1657 in the "/modules/module" list. 1659 The server also advertises the following capability in the 1660 message (line-breaks and whitespaces are used for formatting reasons 1661 only): 1663 urn:ietf:params:netconf:capability:yang-library:1.0? 1664 module-set-id= 1666 The parameter "module-set-id" has the same value as the leaf 1667 "/modules/module-set-id" from "ietf-yang-library". This parameter 1668 MUST be present. 1670 With this mechanism, a client can cache the supported modules for a 1671 server, and only update the cache if the "module-set-id" value in the 1672 message changes. 1674 5.7. Data Store Modification 1676 Data models may allow the server to alter the configuration data 1677 store in ways not explicitly directed via NETCONF protocol messages. 1678 For example, a data model may define leafs that are assigned system- 1679 generated values when the client does not provide one. A formal 1680 mechanism for specifying the circumstances where these changes are 1681 allowed is out of scope for this specification. 1683 6. YANG Syntax 1685 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1686 languages like C and C++. This C-like syntax was chosen specifically 1687 for its readability, since YANG values the time and effort of the 1688 readers of models above those of modules writers and YANG tool-chain 1689 developers. This section introduces the YANG syntax. 1691 YANG modules use the UTF-8 [RFC3629] character encoding. 1693 Legal characters in YANG modules are the Unicode and ISO/IEC 10646 1694 [ISO.10646] characters, including tab, carriage return, and line feed 1695 but excluding the other C0 control characters, the surrogate blocks, 1696 and the noncharacters. The character syntax is formally defined by 1697 the rule "yang-char" in Section 13. 1699 6.1. Lexical Tokenization 1701 YANG modules are parsed as a series of tokens. This section details 1702 the rules for recognizing tokens from an input stream. YANG 1703 tokenization rules are both simple and powerful. The simplicity is 1704 driven by a need to keep the parsers easy to implement, while the 1705 power is driven by the fact that modelers need to express their 1706 models in readable formats. 1708 6.1.1. Comments 1710 Comments are C++ style. A single line comment starts with "//" and 1711 ends at the end of the line. A block comment is enclosed within "/*" 1712 and "*/". 1714 6.1.2. Tokens 1716 A token in YANG is either a keyword, a string, a semicolon (";"), or 1717 braces ("{" or "}"). A string can be quoted or unquoted. A keyword 1718 is either one of the YANG keywords defined in this document, or a 1719 prefix identifier, followed by ":", followed by a language extension 1720 keyword. Keywords are case sensitive. See Section 6.2 for a formal 1721 definition of identifiers. 1723 6.1.3. Quoting 1725 If a string contains any space or tab characters, a semicolon (";"), 1726 braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then 1727 it MUST be enclosed within double or single quotes. 1729 If the double-quoted string contains a line break followed by space 1730 or tab characters that are used to indent the text according to the 1731 layout in the YANG file, this leading whitespace is stripped from the 1732 string, up to and including the column of the double quote character, 1733 or to the first non-whitespace character, whichever occurs first. In 1734 this process, a tab character is treated as 8 space characters. 1736 If the double-quoted string contains space or tab characters before a 1737 line break, this trailing whitespace is stripped from the string. 1739 A single-quoted string (enclosed within ' ') preserves each character 1740 within the quotes. A single quote character cannot occur in a 1741 single-quoted string, even when preceded by a backslash. 1743 Within a double-quoted string (enclosed within " "), a backslash 1744 character introduces a special character, which depends on the 1745 character that immediately follows the backslash: 1747 \n new line 1748 \t a tab character 1749 \" a double quote 1750 \\ a single backslash 1752 It is an error if any other character follows the backslash 1753 character. 1755 If a quoted string is followed by a plus character ("+"), followed by 1756 another quoted string, the two strings are concatenated into one 1757 string, allowing multiple concatenations to build one string. 1758 Whitespace trimming and substitution of backslash-escaped characters 1759 in double-quoted strings is done before concatenation. 1761 6.1.3.1. Quoting Examples 1763 The following strings are equivalent: 1765 hello 1766 "hello" 1767 'hello' 1768 "hel" + "lo" 1769 'hel' + "lo" 1771 The following examples show some special strings: 1773 "\"" - string containing a double quote 1774 '"' - string containing a double quote 1775 "\n" - string containing a new line character 1776 '\n' - string containing a backslash followed 1777 by the character n 1779 The following examples show some illegal strings: 1781 '''' - a single-quoted string cannot contain single quotes 1782 """ - a double quote must be escaped in a double-quoted string 1784 The following strings are equivalent: 1786 "first line 1787 second line" 1789 "first line\n" + " second line" 1791 6.2. Identifiers 1793 Identifiers are used to identify different kinds of YANG items by 1794 name. Each identifier starts with an uppercase or lowercase ASCII 1795 letter or an underscore character, followed by zero or more ASCII 1796 letters, digits, underscore characters, hyphens, and dots. 1797 Implementations MUST support identifiers up to 64 characters in 1798 length. Identifiers are case sensitive. The identifier syntax is 1799 formally defined by the rule "identifier" in Section 13. Identifiers 1800 can be specified as quoted or unquoted strings. 1802 6.2.1. Identifiers and Their Namespaces 1804 Each identifier is valid in a namespace that depends on the type of 1805 the YANG item being defined. All identifiers defined in a namespace 1806 MUST be unique. 1808 o All module and submodule names share the same global module 1809 identifier namespace. 1811 o All extension names defined in a module and its submodules share 1812 the same extension identifier namespace. 1814 o All feature names defined in a module and its submodules share the 1815 same feature identifier namespace. 1817 o All identity names defined in a module and its submodules share 1818 the same identity identifier namespace. 1820 o All derived type names defined within a parent node or at the top 1821 level of the module or its submodules share the same type 1822 identifier namespace. This namespace is scoped to all descendant 1823 nodes of the parent node or module. This means that any 1824 descendent node may use that typedef, and it MUST NOT define a 1825 typedef with the same name. 1827 o All grouping names defined within a parent node or at the top 1828 level of the module or its submodules share the same grouping 1829 identifier namespace. This namespace is scoped to all descendant 1830 nodes of the parent node or module. This means that any 1831 descendent node may use that grouping, and it MUST NOT define a 1832 grouping with the same name. 1834 o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 1835 notifications, anydatas, and anyxmls defined (directly or through 1836 a uses statement) within a parent node or at the top level of the 1837 module or its submodules share the same identifier namespace. 1838 This namespace is scoped to the parent node or module, unless the 1839 parent node is a case node. In that case, the namespace is scoped 1840 to the closest ancestor node that is not a case or choice node. 1842 o All cases within a choice share the same case identifier 1843 namespace. This namespace is scoped to the parent choice node. 1845 Forward references are allowed in YANG. 1847 6.3. Statements 1849 A YANG module contains a sequence of statements. Each statement 1850 starts with a keyword, followed by zero or one argument, followed 1851 either by a semicolon (";") or a block of substatements enclosed 1852 within braces ("{ }"): 1854 statement = keyword [argument] (";" / "{" *statement "}") 1856 The argument is a string, as defined in Section 6.1.2. 1858 6.3.1. Language Extensions 1860 A module can introduce YANG extensions by using the "extension" 1861 keyword (see Section 7.19). The extensions can be imported by other 1862 modules with the "import" statement (see Section 7.1.5). When an 1863 imported extension is used, the extension's keyword MUST be qualified 1864 using the prefix with which the extension's module was imported. If 1865 an extension is used in the module where it is defined, the 1866 extension's keyword MUST be qualified with the module's prefix. 1868 If a YANG compiler does not support a particular extension, which 1869 appears in a YANG module as an unknown-statement (see Section 13), 1870 the entire unknown-statement MAY be ignored by the compiler. 1872 6.4. XPath Evaluations 1874 YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation 1875 for specifying many inter-node references and dependencies. NETCONF 1876 clients and servers are not required to implement an XPath 1877 interpreter, but MUST ensure that the requirements encoded in the 1878 data model are enforced. The manner of enforcement is an 1879 implementation decision. The XPath expressions MUST be syntactically 1880 correct, and all prefixes used MUST be present in the XPath context 1881 (see Section 6.4.1). An implementation may choose to implement them 1882 by hand, rather than using the XPath expression directly. 1884 The data model used in the XPath expressions is the same as that used 1885 in XPath 1.0 [XPATH], with the same extension for root node children 1886 as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means 1887 that the root node may have any number of element nodes as its 1888 children. 1890 Numbers in XPath 1.0 are IEEE 754 double-precision floating-point 1891 values, see Section 3.5 in [XPATH]. This means that some values of 1892 int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) 1893 cannot be exactly represented in XPath expressions. Therefore, due 1894 caution should be exercised when using nodes with 64-bit numeric 1895 values in XPath expressions. In particular, numerical comparisons 1896 involving equality may yield unexpected results. 1898 For example, consider the following definition: 1900 leaf lxiv { 1901 type decimal64 { 1902 fraction-digits 18; 1903 } 1904 must ". <= 10"; 1905 } 1907 An instance of the "lxiv" leaf having the value of 1908 10.0000000000000001 will then successfully pass validation. 1910 6.4.1. XPath Context 1912 All YANG XPath expressions share the following XPath context 1913 definition: 1915 o The set of namespace declarations is the set of all "import" 1916 statements' prefix and namespace pairs in the module where the 1917 XPath expression is specified, and the "prefix" statement's prefix 1918 for the "namespace" statement's URI. 1920 o Names without a namespace prefix belong to the same namespace as 1921 the identifier of the current node. Inside a grouping, that 1922 namespace is affected by where the grouping is used (see 1923 Section 7.13). Inside a typedef, that namespace is affected by 1924 where the typedef is referenced. If a typedef is defined and 1925 referenced within a grouping, the namespace is affected by where 1926 the grouping is used (see Section 7.13). 1928 o The function library is the core function library defined in 1929 [XPATH], and the functions defined in Section 10. 1931 o The set of variable bindings is empty. 1933 The mechanism for handling unprefixed names is adopted from XPath 2.0 1934 [XPATH2.0], and helps simplify XPath expressions in YANG. No 1935 ambiguity may ever arise because YANG node identifiers are always 1936 qualified names with a non-null namespace URI. 1938 The accessible tree depends on where the statement with the XPath 1939 expression is defined: 1941 o If the XPath expression is defined in substatement to a data node 1942 that represents configuration, the accessible tree is the data in 1943 the NETCONF datastore where the context node exists. The root 1944 node has all top-level configuration data nodes in all modules as 1945 children. 1947 o If the XPath expression is defined in a substatement to a data 1948 node that represents state data, the accessible tree is all all 1949 state data on the device, and the "running" datastore. The root 1950 node has all top-level data nodes in all modules as children. 1952 o If the XPath expression is defined in a substatement to a 1953 "notification" statement, the accessible tree is the notification 1954 instance, all state data on the device, and the "running" 1955 datastore. The root node has the node representing the 1956 notification being defined and all top-level data nodes in all 1957 modules as children. 1959 o If the XPath expression is defined in a substatement to an "input" 1960 statement in an "rpc" statement, the accessible tree is the RPC 1961 operation instance, all state data on the device, and the 1962 "running" datastore. The root node has the node representing the 1963 operation being defined and all top-level data nodes in all 1964 modules as children. The node representing the operation being 1965 defined has the operation's input parameters as children. 1967 o If the XPath expression is defined in a substatement to an 1968 "output" statement in an "rpc" statement, the accessible tree is 1969 the RPC operation's output, all state data on the device, and the 1970 "running" datastore. The root node has the node representing the 1971 operation being defined and all top-level data nodes in all 1972 modules as children. The node representing the operation being 1973 defined has the operation's output parameters as children. 1975 In the accessible tree, all leafs and leaf-lists with default values 1976 in use exist (See Section 7.6.1 and Section 7.7.2). 1978 If a node that exists in the accessible tree has a non-presence 1979 container as a child, then the non-presence container also exists in 1980 the tree. 1982 The context node varies with the YANG XPath expression, and is 1983 specified where the YANG statement with the XPath expression is 1984 defined. 1986 6.5. Schema Node Identifier 1988 A schema node identifier is a string that identifies a node in the 1989 schema tree. It has two forms, "absolute" and "descendant", defined 1990 by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" 1991 in Section 13, respectively. A schema node identifier consists of a 1992 path of identifiers, separated by slashes ("/"). In an absolute 1993 schema node identifier, the first identifier after the leading slash 1994 is any top-level schema node in the local module or in all imported 1995 modules. 1997 References to identifiers defined in external modules MUST be 1998 qualified with appropriate prefixes, and references to identifiers 1999 defined in the current module and its submodules MAY use a prefix. 2001 For example, to identify the child node "b" of top-level node "a", 2002 the string "/a/b" can be used. 2004 7. YANG Statements 2006 The following sections describe all of the YANG statements. 2008 Note that even a statement that does not have any substatements 2009 defined in YANG can have vendor-specific extensions as substatements. 2011 For example, the "description" statement does not have any 2012 substatements defined in YANG, but the following is legal: 2014 description "some text" { 2015 acme:documentation-flag 5; 2016 } 2018 7.1. The module Statement 2020 The "module" statement defines the module's name, and groups all 2021 statements that belong to the module together. The "module" 2022 statement's argument is the name of the module, followed by a block 2023 of substatements that hold detailed module information. The module 2024 name follows the rules for identifiers in Section 6.2. 2026 Names of modules published in RFC streams [RFC4844] MUST be assigned 2027 by IANA, see Section 15. 2029 Private module names are assigned by the organization owning the 2030 module without a central registry. It is RECOMMENDED to choose 2031 module names that will have a low probability of colliding with 2032 standard or other enterprise modules and submodules, e.g., by using 2033 the enterprise or organization name as a prefix for the module name. 2035 A module typically has the following layout: 2037 module { 2039 // header information 2040 2041 2042 2044 // linkage statements 2045 2046 2048 // meta information 2049 2050 2051 2052 2054 // revision history 2055 2057 // module definitions 2058 2059 } 2061 7.1.1. The module's Substatements 2062 +--------------+---------+-------------+ 2063 | substatement | section | cardinality | 2064 +--------------+---------+-------------+ 2065 | anydata | 7.10 | 0..n | 2066 | anyxml | 7.11 | 0..n | 2067 | augment | 7.17 | 0..n | 2068 | choice | 7.9 | 0..n | 2069 | contact | 7.1.8 | 0..1 | 2070 | container | 7.5 | 0..n | 2071 | description | 7.21.3 | 0..1 | 2072 | deviation | 7.20.3 | 0..n | 2073 | extension | 7.19 | 0..n | 2074 | feature | 7.20.1 | 0..n | 2075 | grouping | 7.12 | 0..n | 2076 | identity | 7.18 | 0..n | 2077 | import | 7.1.5 | 0..n | 2078 | include | 7.1.6 | 0..n | 2079 | leaf | 7.6 | 0..n | 2080 | leaf-list | 7.7 | 0..n | 2081 | list | 7.8 | 0..n | 2082 | namespace | 7.1.3 | 1 | 2083 | notification | 7.16 | 0..n | 2084 | organization | 7.1.7 | 0..1 | 2085 | prefix | 7.1.4 | 1 | 2086 | reference | 7.21.4 | 0..1 | 2087 | revision | 7.1.9 | 0..n | 2088 | rpc | 7.14 | 0..n | 2089 | typedef | 7.3 | 0..n | 2090 | uses | 7.13 | 0..n | 2091 | yang-version | 7.1.2 | 1 | 2092 +--------------+---------+-------------+ 2094 7.1.2. The yang-version Statement 2096 The "yang-version" statement specifies which version of the YANG 2097 language was used in developing the module. The statement's argument 2098 is a string. It MUST contain the value "1.1", which is the current 2099 YANG version. 2101 A module or submodule that doesn't contain the "yang-version" 2102 statement, or one that contains the value "1", is developed for YANG 2103 version 1, defined in [RFC6020]. 2105 Handling of the "yang-version" statement for versions other than 2106 "1.1" (the version defined here) is out of scope for this 2107 specification. Any document that defines a higher version will need 2108 to define the backward compatibility of such a higher version. 2110 7.1.3. The namespace Statement 2112 The "namespace" statement defines the XML namespace that all 2113 identifiers defined by the module are qualified by, with the 2114 exception of data node identifiers defined inside a grouping (see 2115 Section 7.13 for details). The argument to the "namespace" statement 2116 is the URI of the namespace. 2118 See also Section 5.3. 2120 7.1.4. The prefix Statement 2122 The "prefix" statement is used to define the prefix associated with 2123 the module and its namespace. The "prefix" statement's argument is 2124 the prefix string that is used as a prefix to access a module. The 2125 prefix string MAY be used to refer to definitions contained in the 2126 module, e.g., "if:ifName". A prefix follows the same rules as an 2127 identifier (see Section 6.2). 2129 When used inside the "module" statement, the "prefix" statement 2130 defines the prefix to be used when this module is imported. To 2131 improve readability of the NETCONF XML, a NETCONF client or server 2132 that generates XML or XPath that use prefixes SHOULD use the prefix 2133 defined by the module, unless there is a conflict. 2135 When used inside the "import" statement, the "prefix" statement 2136 defines the prefix to be used when accessing definitions inside the 2137 imported module. When a reference to an identifier from the imported 2138 module is used, the prefix string for the imported module is used in 2139 combination with a colon (":") and the identifier, e.g., 2140 "if:ifIndex". To improve readability of YANG modules, the prefix 2141 defined by a module SHOULD be used when the module is imported, 2142 unless there is a conflict. If there is a conflict, i.e., two 2143 different modules that both have defined the same prefix are 2144 imported, at least one of them MUST be imported with a different 2145 prefix. 2147 All prefixes, including the prefix for the module itself MUST be 2148 unique within the module or submodule. 2150 7.1.5. The import Statement 2152 The "import" statement makes definitions from one module available 2153 inside another module or submodule. The argument is the name of the 2154 module to import, and the statement is followed by a block of 2155 substatements that holds detailed import information. When a module 2156 is imported, the importing module may: 2158 o use any grouping and typedef defined at the top level in the 2159 imported module or its submodules. 2161 o use any extension, feature, and identity defined in the imported 2162 module or its submodules. 2164 o use any node in the imported module's schema tree in "must", 2165 "path", and "when" statements, or as the target node in "augment" 2166 and "deviation" statements. 2168 The mandatory "prefix" substatement assigns a prefix for the imported 2169 module that is scoped to the importing module or submodule. Multiple 2170 "import" statements may be specified to import from different 2171 modules. 2173 When the optional "revision-date" substatement is present, any 2174 typedef, grouping, extension, feature, and identity referenced by 2175 definitions in the local module are taken from the specified revision 2176 of the imported module. It is an error if the specified revision of 2177 the imported module does not exist. If no "revision-date" 2178 substatement is present, it is undefined from which revision of the 2179 module they are taken. 2181 Multiple revisions of the same module can be imported, provided that 2182 different prefixes are used. 2184 +---------------+---------+-------------+ 2185 | substatement | section | cardinality | 2186 +---------------+---------+-------------+ 2187 | prefix | 7.1.4 | 1 | 2188 | revision-date | 7.1.5.1 | 0..1 | 2189 +---------------+---------+-------------+ 2191 The import's Substatements 2193 7.1.5.1. The import's revision-date Statement 2195 The import's "revision-date" statement is used to specify the exact 2196 version of the module to import. The "revision-date" statement MUST 2197 match the most recent "revision" statement in the imported module. 2199 7.1.6. The include Statement 2201 The "include" statement is used to make content from a submodule 2202 available to that submodule's parent module. The argument is an 2203 identifier that is the name of the submodule to include. Modules are 2204 only allowed to include submodules that belong to that module, as 2205 defined by the "belongs-to" statement (see Section 7.2.2). 2207 Submodules are only allowed to include other submodules belonging to 2208 the same module. 2210 When a module includes a submodule, it incorporates the contents of 2211 the submodule into the node hierarchy of the module. 2213 For backward compatibility with YANG version 1, a submodule is 2214 allowed to include another submodule belonging to the same module, 2215 but this is not necessary in YANG version 1.1. 2217 When the optional "revision-date" substatement is present, the 2218 specified revision of the submodule is included in the module. It is 2219 an error if the specified revision of the submodule does not exist. 2220 If no "revision-date" substatement is present, it is undefined which 2221 revision of the submodule is included. 2223 Multiple revisions of the same submodule MUST NOT be included. 2225 +---------------+---------+-------------+ 2226 | substatement | section | cardinality | 2227 +---------------+---------+-------------+ 2228 | revision-date | 7.1.5.1 | 0..1 | 2229 +---------------+---------+-------------+ 2231 The includes's Substatements 2233 7.1.7. The organization Statement 2235 The "organization" statement defines the party responsible for this 2236 module. The argument is a string that is used to specify a textual 2237 description of the organization(s) under whose auspices this module 2238 was developed. 2240 7.1.8. The contact Statement 2242 The "contact" statement provides contact information for the module. 2243 The argument is a string that is used to specify contact information 2244 for the person or persons to whom technical queries concerning this 2245 module should be sent, such as their name, postal address, telephone 2246 number, and electronic mail address. 2248 7.1.9. The revision Statement 2250 The "revision" statement specifies the editorial revision history of 2251 the module, including the initial revision. A series of revision 2252 statements detail the changes in the module's definition. The 2253 argument is a date string in the format "YYYY-MM-DD", followed by a 2254 block of substatements that holds detailed revision information. A 2255 module SHOULD have at least one "revision" statement. For every 2256 published editorial change, a new one SHOULD be added in front of the 2257 revisions sequence, so that all revisions are in reverse 2258 chronological order. 2260 7.1.9.1. The revision's Substatement 2262 +--------------+---------+-------------+ 2263 | substatement | section | cardinality | 2264 +--------------+---------+-------------+ 2265 | description | 7.21.3 | 0..1 | 2266 | reference | 7.21.4 | 0..1 | 2267 +--------------+---------+-------------+ 2269 7.1.10. Usage Example 2271 module acme-system { 2272 yang-version 1.1; 2273 namespace "http://acme.example.com/system"; 2274 prefix "acme"; 2276 import ietf-yang-types { 2277 prefix "yang"; 2278 } 2280 include acme-types; 2282 organization "ACME Inc."; 2283 contact 2284 "Joe L. User 2286 ACME, Inc. 2287 42 Anywhere Drive 2288 Nowhere, CA 95134 2289 USA 2291 Phone: +1 800 555 0100 2292 EMail: joe@acme.example.com"; 2294 description 2295 "The module for entities implementing the ACME protocol."; 2297 revision "2007-06-09" { 2298 description "Initial revision."; 2299 } 2301 // definitions follow... 2302 } 2304 7.2. The submodule Statement 2306 While the primary unit in YANG is a module, a YANG module can itself 2307 be constructed out of several submodules. Submodules allow a module 2308 designer to split a complex model into several pieces where all the 2309 submodules contribute to a single namespace, which is defined by the 2310 module that includes the submodules. 2312 The "submodule" statement defines the submodule's name, and groups 2313 all statements that belong to the submodule together. The 2314 "submodule" statement's argument is the name of the submodule, 2315 followed by a block of substatements that hold detailed submodule 2316 information. The submodule name follows the rules for identifiers in 2317 Section 6.2. 2319 Names of submodules published in RFC streams [RFC4844] MUST be 2320 assigned by IANA, see Section 15. 2322 Private submodule names are assigned by the organization owning the 2323 submodule without a central registry. It is RECOMMENDED to choose 2324 submodule names that will have a low probability of colliding with 2325 standard or other enterprise modules and submodules, e.g., by using 2326 the enterprise or organization name as a prefix for the submodule 2327 name. 2329 A submodule typically has the following layout: 2331 submodule { 2333 2334 // module identification 2335 2337 // linkage statements 2338 2340 // meta information 2341 2342 2343 2344 2346 // revision history 2347 2349 // module definitions 2350 2351 } 2353 7.2.1. The submodule's Substatements 2354 +--------------+---------+-------------+ 2355 | substatement | section | cardinality | 2356 +--------------+---------+-------------+ 2357 | anydata | 7.10 | 0..n | 2358 | anyxml | 7.11 | 0..n | 2359 | augment | 7.17 | 0..n | 2360 | belongs-to | 7.2.2 | 1 | 2361 | choice | 7.9 | 0..n | 2362 | contact | 7.1.8 | 0..1 | 2363 | container | 7.5 | 0..n | 2364 | description | 7.21.3 | 0..1 | 2365 | deviation | 7.20.3 | 0..n | 2366 | extension | 7.19 | 0..n | 2367 | feature | 7.20.1 | 0..n | 2368 | grouping | 7.12 | 0..n | 2369 | identity | 7.18 | 0..n | 2370 | import | 7.1.5 | 0..n | 2371 | include | 7.1.6 | 0..n | 2372 | leaf | 7.6 | 0..n | 2373 | leaf-list | 7.7 | 0..n | 2374 | list | 7.8 | 0..n | 2375 | notification | 7.16 | 0..n | 2376 | organization | 7.1.7 | 0..1 | 2377 | reference | 7.21.4 | 0..1 | 2378 | revision | 7.1.9 | 0..n | 2379 | rpc | 7.14 | 0..n | 2380 | typedef | 7.3 | 0..n | 2381 | uses | 7.13 | 0..n | 2382 | yang-version | 7.1.2 | 1 | 2383 +--------------+---------+-------------+ 2385 7.2.2. The belongs-to Statement 2387 The "belongs-to" statement specifies the module to which the 2388 submodule belongs. The argument is an identifier that is the name of 2389 the module. 2391 A submodule MUST only be included by the module to which it belongs, 2392 or by another submodule that belongs to that module. 2394 The mandatory "prefix" substatement assigns a prefix for the module 2395 to which the submodule belongs. All definitions in the module that 2396 the submodule belongs to and all its submodules can be accessed by 2397 using the prefix. 2399 +--------------+---------+-------------+ 2400 | substatement | section | cardinality | 2401 +--------------+---------+-------------+ 2402 | prefix | 7.1.4 | 1 | 2403 +--------------+---------+-------------+ 2405 The belongs-to's Substatements 2407 7.2.3. Usage Example 2409 submodule acme-types { 2410 yang-version 1.1; 2411 belongs-to "acme-system" { 2412 prefix "acme"; 2413 } 2415 import ietf-yang-types { 2416 prefix "yang"; 2417 } 2419 organization "ACME Inc."; 2420 contact 2421 "Joe L. User 2423 ACME, Inc. 2424 42 Anywhere Drive 2425 Nowhere, CA 95134 2426 USA 2428 Phone: +1 800 555 0100 2429 EMail: joe@acme.example.com"; 2431 description 2432 "This submodule defines common ACME types."; 2434 revision "2007-06-09" { 2435 description "Initial revision."; 2436 } 2438 // definitions follows... 2439 } 2441 7.3. The typedef Statement 2443 The "typedef" statement defines a new type that may be used locally 2444 in the module or submodule, and by other modules that import from it, 2445 according to the rules in Section 5.5. The new type is called the 2446 "derived type", and the type from which it was derived is called the 2447 "base type". All derived types can be traced back to a YANG built-in 2448 type. 2450 The "typedef" statement's argument is an identifier that is the name 2451 of the type to be defined, and MUST be followed by a block of 2452 substatements that holds detailed typedef information. 2454 The name of the type MUST NOT be one of the YANG built-in types. If 2455 the typedef is defined at the top level of a YANG module or 2456 submodule, the name of the type to be defined MUST be unique within 2457 the module. 2459 7.3.1. The typedef's Substatements 2461 +--------------+---------+-------------+ 2462 | substatement | section | cardinality | 2463 +--------------+---------+-------------+ 2464 | default | 7.3.4 | 0..1 | 2465 | description | 7.21.3 | 0..1 | 2466 | reference | 7.21.4 | 0..1 | 2467 | status | 7.21.2 | 0..1 | 2468 | type | 7.3.2 | 1 | 2469 | units | 7.3.3 | 0..1 | 2470 +--------------+---------+-------------+ 2472 7.3.2. The typedef's type Statement 2474 The "type" statement, which MUST be present, defines the base type 2475 from which this type is derived. See Section 7.4 for details. 2477 7.3.3. The units Statement 2479 The "units" statement, which is optional, takes as an argument a 2480 string that contains a textual definition of the units associated 2481 with the type. 2483 7.3.4. The typedef's default Statement 2485 The "default" statement takes as an argument a string that contains a 2486 default value for the new type. 2488 The value of the "default" statement MUST be valid according to the 2489 type specified in the "type" statement. 2491 If the base type has a default value, and the new derived type does 2492 not specify a new default value, the base type's default value is 2493 also the default value of the new derived type. 2495 If the type's default value is not valid according to the new 2496 restrictions specified in a derived type or leaf definition, the 2497 derived type or leaf definition MUST specify a new default value 2498 compatible with the restrictions. 2500 7.3.5. Usage Example 2502 typedef listen-ipv4-address { 2503 type inet:ipv4-address; 2504 default "0.0.0.0"; 2505 } 2507 7.4. The type Statement 2509 The "type" statement takes as an argument a string that is the name 2510 of a YANG built-in type (see Section 9) or a derived type (see 2511 Section 7.3), followed by an optional block of substatements that are 2512 used to put further restrictions on the type. 2514 The restrictions that can be applied depend on the type being 2515 restricted. The restriction statements for all built-in types are 2516 described in the subsections of Section 9. 2518 7.4.1. The type's Substatements 2520 +------------------+---------+-------------+ 2521 | substatement | section | cardinality | 2522 +------------------+---------+-------------+ 2523 | base | 7.18.2 | 0..n | 2524 | bit | 9.7.4 | 0..n | 2525 | enum | 9.6.4 | 0..n | 2526 | fraction-digits | 9.3.4 | 0..1 | 2527 | length | 9.4.4 | 0..1 | 2528 | path | 9.9.2 | 0..1 | 2529 | pattern | 9.4.5 | 0..n | 2530 | range | 9.2.4 | 0..1 | 2531 | require-instance | 9.9.3 | 0..1 | 2532 | type | 7.4 | 0..n | 2533 +------------------+---------+-------------+ 2535 7.5. The container Statement 2537 The "container" statement is used to define an interior data node in 2538 the schema tree. It takes one argument, which is an identifier, 2539 followed by a block of substatements that holds detailed container 2540 information. 2542 A container node does not have a value, but it has a list of child 2543 nodes in the data tree. The child nodes are defined in the 2544 container's substatements. 2546 7.5.1. Containers with Presence 2548 YANG supports two styles of containers, those that exist only for 2549 organizing the hierarchy of data nodes, and those whose presence in 2550 the configuration has an explicit meaning. 2552 In the first style, the container has no meaning of its own, existing 2553 only to contain child nodes. This is the default style. 2555 For example, the set of scrambling options for Synchronous Optical 2556 Network (SONET) interfaces may be placed inside a "scrambling" 2557 container to enhance the organization of the configuration hierarchy, 2558 and to keep these nodes together. The "scrambling" node itself has 2559 no meaning, so removing the node when it becomes empty relieves the 2560 user from performing this task. 2562 In the second style, the presence of the container itself is 2563 configuration data, representing a single bit of configuration data. 2564 The container acts as both a configuration knob and a means of 2565 organizing related configuration. These containers are explicitly 2566 created and deleted. 2568 YANG calls this style a "presence container" and it is indicated 2569 using the "presence" statement, which takes as its argument a text 2570 string indicating what the presence of the node means. 2572 For example, an "ssh" container may turn on the ability to log into 2573 the device using ssh, but can also contain any ssh-related 2574 configuration knobs, such as connection rates or retry limits. 2576 The "presence" statement (see Section 7.5.5) is used to give 2577 semantics to the existence of the container in the data tree. 2579 7.5.2. The container's Substatements 2580 +--------------+---------+-------------+ 2581 | substatement | section | cardinality | 2582 +--------------+---------+-------------+ 2583 | action | 7.15 | 0..n | 2584 | anydata | 7.10 | 0..n | 2585 | anyxml | 7.11 | 0..n | 2586 | choice | 7.9 | 0..n | 2587 | config | 7.21.1 | 0..1 | 2588 | container | 7.5 | 0..n | 2589 | description | 7.21.3 | 0..1 | 2590 | grouping | 7.12 | 0..n | 2591 | if-feature | 7.20.2 | 0..n | 2592 | leaf | 7.6 | 0..n | 2593 | leaf-list | 7.7 | 0..n | 2594 | list | 7.8 | 0..n | 2595 | must | 7.5.3 | 0..n | 2596 | notification | 7.16 | 0..n | 2597 | presence | 7.5.5 | 0..1 | 2598 | reference | 7.21.4 | 0..1 | 2599 | status | 7.21.2 | 0..1 | 2600 | typedef | 7.3 | 0..n | 2601 | uses | 7.13 | 0..n | 2602 | when | 7.21.5 | 0..1 | 2603 +--------------+---------+-------------+ 2605 7.5.3. The must Statement 2607 The "must" statement, which is optional, takes as an argument a 2608 string that contains an XPath expression (see Section 6.4). It is 2609 used to formally declare a constraint on valid data. The constraint 2610 is enforced according to the rules in Section 8. 2612 When a datastore is validated, all "must" constraints are 2613 conceptually evaluated once for each node in the accessible tree (see 2614 Section 6.4.1). 2616 All such constraints MUST evaluate to true for the data to be valid. 2618 The XPath expression is conceptually evaluated in the following 2619 context, in addition to the definition in Section 6.4.1: 2621 o The context node is the node in the accessible tree for which the 2622 "must" statement is defined. 2624 The result of the XPath expression is converted to a boolean value 2625 using the standard XPath rules. 2627 Note that since all leaf values in the data tree are conceptually 2628 stored in their canonical form (see Section 7.6 and Section 7.7), any 2629 XPath comparisons are done on the canonical value. 2631 Also note that the XPath expression is conceptually evaluated. This 2632 means that an implementation does not have to use an XPath evaluator 2633 on the device. How the evaluation is done in practice is an 2634 implementation decision. 2636 7.5.4. The must's Substatements 2638 +---------------+---------+-------------+ 2639 | substatement | section | cardinality | 2640 +---------------+---------+-------------+ 2641 | description | 7.21.3 | 0..1 | 2642 | error-app-tag | 7.5.4.2 | 0..1 | 2643 | error-message | 7.5.4.1 | 0..1 | 2644 | reference | 7.21.4 | 0..1 | 2645 +---------------+---------+-------------+ 2647 7.5.4.1. The error-message Statement 2649 The "error-message" statement, which is optional, takes a string as 2650 an argument. If the constraint evaluates to false, the string is 2651 passed as in the . 2653 7.5.4.2. The error-app-tag Statement 2655 The "error-app-tag" statement, which is optional, takes a string as 2656 an argument. If the constraint evaluates to false, the string is 2657 passed as in the . 2659 7.5.4.3. Usage Example of must and error-message 2660 container interface { 2661 leaf ifType { 2662 type enumeration { 2663 enum ethernet; 2664 enum atm; 2665 } 2666 } 2667 leaf ifMTU { 2668 type uint32; 2669 } 2670 must "ifType != 'ethernet' or " + 2671 "(ifType = 'ethernet' and ifMTU = 1500)" { 2672 error-message "An ethernet MTU must be 1500"; 2673 } 2674 must "ifType != 'atm' or " + 2675 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2676 error-message "An atm MTU must be 64 .. 17966"; 2677 } 2678 } 2680 7.5.5. The presence Statement 2682 The "presence" statement assigns a meaning to the presence of a 2683 container in the data tree. It takes as an argument a string that 2684 contains a textual description of what the node's presence means. 2686 If a container has the "presence" statement, the container's 2687 existence in the data tree carries some meaning. Otherwise, the 2688 container is used to give some structure to the data, and it carries 2689 no meaning by itself. 2691 See Section 7.5.1 for additional information. 2693 7.5.6. The container's Child Node Statements 2695 Within a container, the "container", "leaf", "list", "leaf-list", 2696 "uses", "choice", "anydata", and "anyxml" statements can be used to 2697 define child nodes to the container. 2699 7.5.7. XML Mapping Rules 2701 A container node is encoded as an XML element. The element's local 2702 name is the container's identifier, and its namespace is the module's 2703 XML namespace (see Section 7.1.3). 2705 The container's child nodes are encoded as subelements to the 2706 container element. If the container defines RPC input or output 2707 parameters, these subelements are encoded in the same order as they 2708 are defined within the "container" statement. Otherwise, the 2709 subelements are encoded in any order. 2711 A NETCONF server that replies to a or request MAY 2712 choose not to send a container element if the container node does not 2713 have the "presence" statement and no child nodes exist. Thus, a 2714 client that receives an for a or 2715 request, must be prepared to handle the case that a container node 2716 without a "presence" statement is not present in the XML. 2718 7.5.8. NETCONF Operations 2720 Containers can be created, deleted, replaced, and modified through 2721 , by using the "operation" attribute (see [RFC6241], 2722 Section 7.2) in the container's XML element. 2724 If a container does not have a "presence" statement and the last 2725 child node is deleted, the NETCONF server MAY delete the container. 2727 When a NETCONF server processes an request, the 2728 elements of procedure for the container node are: 2730 If the operation is "merge" or "replace", the node is created if 2731 it does not exist. 2733 If the operation is "create", the node is created if it does not 2734 exist. If the node already exists, a "data-exists" error is 2735 returned. 2737 If the operation is "delete", the node is deleted if it exists. 2738 If the node does not exist, a "data-missing" error is returned. 2740 7.5.9. Usage Example 2742 Given the following container definition: 2744 container system { 2745 description "Contains various system parameters"; 2746 container services { 2747 description "Configure externally available services"; 2748 container "ssh" { 2749 presence "Enables SSH"; 2750 description "SSH service specific configuration"; 2751 // more leafs, containers and stuff here... 2752 } 2753 } 2754 } 2756 A corresponding XML instance example: 2758 2759 2760 2761 2762 2764 Since the element is present, ssh is enabled. 2766 To delete a container with an : 2768 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2785 7.6. The leaf Statement 2787 The "leaf" statement is used to define a leaf node in the schema 2788 tree. It takes one argument, which is an identifier, followed by a 2789 block of substatements that holds detailed leaf information. 2791 A leaf node has a value, but no child nodes in the data tree. 2792 Conceptually, the value in the data tree is always in the canonical 2793 form (see Section 9.1). 2795 A leaf node exists in zero or one instances in the data tree. 2797 The "leaf" statement is used to define a scalar variable of a 2798 particular built-in or derived type. 2800 7.6.1. The leaf's default value 2802 The default value of a leaf is the value that the server uses if the 2803 leaf does not exist in the data tree. The usage of the default value 2804 depends on the leaf's closest ancestor node in the schema tree that 2805 is not a non-presence container: 2807 o If no such ancestor exists in the schema tree, the default value 2808 MUST be used. 2810 o Otherwise, if this ancestor is a case node, the default value MUST 2811 be used if any node from the case exists in the data tree, or if 2812 the case node is the choice's default case, and no nodes from any 2813 other case exist in the data tree. 2815 o Otherwise, the default value MUST be used if the ancestor node 2816 exists in the data tree. 2818 In these cases, the default value is said to be in use. 2820 When the default value is in use, the server MUST operationally 2821 behave as if the leaf was present in the data tree with the default 2822 value as its value. 2824 If a leaf has a "default" statement, the leaf's default value is the 2825 value of the "default" statement. Otherwise, if the leaf's type has 2826 a default value, and the leaf is not mandatory, then the leaf's 2827 default value is the type's default value. In all other cases, the 2828 leaf does not have a default value. 2830 7.6.2. The leaf's Substatements 2832 +--------------+---------+-------------+ 2833 | substatement | section | cardinality | 2834 +--------------+---------+-------------+ 2835 | config | 7.21.1 | 0..1 | 2836 | default | 7.6.4 | 0..1 | 2837 | description | 7.21.3 | 0..1 | 2838 | if-feature | 7.20.2 | 0..n | 2839 | mandatory | 7.6.5 | 0..1 | 2840 | must | 7.5.3 | 0..n | 2841 | reference | 7.21.4 | 0..1 | 2842 | status | 7.21.2 | 0..1 | 2843 | type | 7.6.3 | 1 | 2844 | units | 7.3.3 | 0..1 | 2845 | when | 7.21.5 | 0..1 | 2846 +--------------+---------+-------------+ 2848 7.6.3. The leaf's type Statement 2850 The "type" statement, which MUST be present, takes as an argument the 2851 name of an existing built-in or derived type. The optional 2852 substatements specify restrictions on this type. See Section 7.4 for 2853 details. 2855 7.6.4. The leaf's default Statement 2857 The "default" statement, which is optional, takes as an argument a 2858 string that contains a default value for the leaf. 2860 The value of the "default" statement MUST be valid according to the 2861 type specified in the leaf's "type" statement. 2863 The "default" statement MUST NOT be present on nodes where 2864 "mandatory" is true. 2866 7.6.5. The leaf's mandatory Statement 2868 The "mandatory" statement, which is optional, takes as an argument 2869 the string "true" or "false", and puts a constraint on valid data. 2870 If not specified, the default is "false". 2872 If "mandatory" is "true", the behavior of the constraint depends on 2873 the type of the leaf's closest ancestor node in the schema tree that 2874 is not a non-presence container (see Section 7.5.1): 2876 o If no such ancestor exists in the schema tree, the leaf MUST 2877 exist. 2879 o Otherwise, if this ancestor is a case node, the leaf MUST exist if 2880 any node from the case exists in the data tree. 2882 o Otherwise, the leaf MUST exist if the ancestor node exists in the 2883 data tree. 2885 This constraint is enforced according to the rules in Section 8. 2887 7.6.6. XML Mapping Rules 2889 A leaf node is encoded as an XML element. The element's local name 2890 is the leaf's identifier, and its namespace is the module's XML 2891 namespace (see Section 7.1.3). 2893 The value of the leaf node is encoded to XML according to the type, 2894 and sent as character data in the element. 2896 A NETCONF server that replies to a or request MAY 2897 choose not to send the leaf element if its value is the default 2898 value. Thus, a client that receives an for a or 2899 request, MUST be prepared to handle the case that a leaf 2900 node with a default value is not present in the XML. In this case, 2901 the value used by the server is known to be the default value. 2903 See Section 7.6.8 for an example. 2905 7.6.7. NETCONF Operations 2907 When a NETCONF server processes an request, the 2908 elements of procedure for the leaf node are: 2910 If the operation is "merge" or "replace", the node is created if 2911 it does not exist, and its value is set to the value found in the 2912 XML RPC data. 2914 If the operation is "create", the node is created if it does not 2915 exist. If the node already exists, a "data-exists" error is 2916 returned. 2918 If the operation is "delete", the node is deleted if it exists. 2919 If the node does not exist, a "data-missing" error is returned. 2921 7.6.8. Usage Example 2923 Given the following "leaf" statement, placed in the previously 2924 defined "ssh" container (see Section 7.5.9): 2926 leaf port { 2927 type inet:port-number; 2928 default 22; 2929 description "The port to which the SSH server listens" 2930 } 2932 A corresponding XML instance example: 2934 2022 2936 To set the value of a leaf with an : 2938 2941 2942 2943 2944 2945 2946 2947 2948 2949 2022 2950 2951 2952 2953 2954 2955 2957 7.7. The leaf-list Statement 2959 Where the "leaf" statement is used to define a simple scalar variable 2960 of a particular type, the "leaf-list" statement is used to define an 2961 array of a particular type. The "leaf-list" statement takes one 2962 argument, which is an identifier, followed by a block of 2963 substatements that holds detailed leaf-list information. 2965 The values in a leaf-list MUST be unique. 2967 Conceptually, the values in the data tree are always in the canonical 2968 form (see Section 9.1). 2970 7.7.1. Ordering 2972 YANG supports two styles for ordering the entries within lists and 2973 leaf-lists. In many lists, the order of list entries does not impact 2974 the implementation of the list's configuration, and the device is 2975 free to sort the list entries in any reasonable order. The 2976 "description" string for the list may suggest an order to the device 2977 implementor. YANG calls this style of list "system ordered" and they 2978 are indicated with the statement "ordered-by system". 2980 For example, a list of valid users would typically be sorted 2981 alphabetically, since the order in which the users appeared in the 2982 configuration would not impact the creation of those users' accounts. 2984 In the other style of lists, the order of list entries matters for 2985 the implementation of the list's configuration and the user is 2986 responsible for ordering the entries, while the device maintains that 2987 order. YANG calls this style of list "user ordered" and they are 2988 indicated with the statement "ordered-by user". 2990 For example, the order in which firewall filters entries are applied 2991 to incoming traffic may affect how that traffic is filtered. The 2992 user would need to decide if the filter entry that discards all TCP 2993 traffic should be applied before or after the filter entry that 2994 allows all traffic from trusted interfaces. The choice of order 2995 would be crucial. 2997 YANG provides a rich set of facilities within NETCONF's 2998 operation that allows the order of list entries in user-ordered lists 2999 to be controlled. List entries may be inserted or rearranged, 3000 positioned as the first or last entry in the list, or positioned 3001 before or after another specific entry. 3003 The "ordered-by" statement is covered in Section 7.7.7. 3005 7.7.2. The leaf-list's default values 3007 The default values of a leaf-list are the values that the server uses 3008 if the leaf-list does not exist in the data tree. The usage of the 3009 default values depends on the leaf-list's closest ancestor node in 3010 the schema tree that is not a non-presence container: 3012 o If no such ancestor exists in the schema tree, the default values 3013 MUST be used. 3015 o Otherwise, if this ancestor is a case node, the default values 3016 MUST be used if any node from the case exists in the data tree, or 3017 if the case node is the choice's default case, and no nodes from 3018 any other case exist in the data tree. 3020 o Otherwise, the default values MUST be used if the ancestor node 3021 exists in the data tree. 3023 In these cases, the default values are said to be in use. 3025 When the default values are in use, the server MUST operationally 3026 behave as if the leaf-list was present in the data tree with the 3027 default values as its values. 3029 If a leaf-list has one or more "default" statement, the leaf-list's 3030 default value are the values of the "default" statements, and if the 3031 leaf-list is user-ordered, the default values are used in the order 3032 of the "default" statements. Otherwise, if the leaf-list's type has 3033 a default value, and the leaf-list does not have a "min-elements" 3034 statement with a value greater than or equal to one, then the leaf- 3035 list's default value is the type's default value. In all other 3036 cases, the leaf-list does not have any default values. 3038 7.7.3. The leaf-list's Substatements 3040 +--------------+---------+-------------+ 3041 | substatement | section | cardinality | 3042 +--------------+---------+-------------+ 3043 | config | 7.21.1 | 0..1 | 3044 | default | 7.7.4 | 0..n | 3045 | description | 7.21.3 | 0..1 | 3046 | if-feature | 7.20.2 | 0..n | 3047 | max-elements | 7.7.6 | 0..1 | 3048 | min-elements | 7.7.5 | 0..1 | 3049 | must | 7.5.3 | 0..n | 3050 | ordered-by | 7.7.7 | 0..1 | 3051 | reference | 7.21.4 | 0..1 | 3052 | status | 7.21.2 | 0..1 | 3053 | type | 7.4 | 1 | 3054 | units | 7.3.3 | 0..1 | 3055 | when | 7.21.5 | 0..1 | 3056 +--------------+---------+-------------+ 3058 7.7.4. The leaf-list's default Statement 3060 The "default" statement, which is optional, takes as an argument a 3061 string that contains a default value for the leaf-list. 3063 The value of the "default" statement MUST be valid according to the 3064 type specified in the leaf-list's "type" statement. 3066 The "default" statement MUST NOT be present on nodes where 3067 "min-elements" has a value greater than or equal to one. 3069 7.7.5. The min-elements Statement 3071 The "min-elements" statement, which is optional, takes as an argument 3072 a non-negative integer that puts a constraint on valid list entries. 3073 A valid leaf-list or list MUST have at least min-elements entries. 3075 If no "min-elements" statement is present, it defaults to zero. 3077 The behavior of the constraint depends on the type of the leaf-list's 3078 or list's closest ancestor node in the schema tree that is not a non- 3079 presence container (see Section 7.5.1): 3081 o If this ancestor is a case node, the constraint is enforced if any 3082 other node from the case exists. 3084 o Otherwise, it is enforced if the ancestor node exists. 3086 The constraint is further enforced according to the rules in 3087 Section 8. 3089 7.7.6. The max-elements Statement 3091 The "max-elements" statement, which is optional, takes as an argument 3092 a positive integer or the string "unbounded", which puts a constraint 3093 on valid list entries. A valid leaf-list or list always has at most 3094 max-elements entries. 3096 If no "max-elements" statement is present, it defaults to 3097 "unbounded". 3099 The "max-elements" constraint is enforced according to the rules in 3100 Section 8. 3102 7.7.7. The ordered-by Statement 3104 The "ordered-by" statement defines whether the order of entries 3105 within a list are determined by the user or the system. The argument 3106 is one of the strings "system" or "user". If not present, order 3107 defaults to "system". 3109 This statement is ignored if the list represents state data, RPC 3110 output parameters, or notification content. 3112 See Section 7.7.1 for additional information. 3114 7.7.7.1. ordered-by system 3116 The entries in the list are sorted according to an unspecified order. 3117 Thus, an implementation is free to sort the entries in the most 3118 appropriate order. An implementation SHOULD use the same order for 3119 the same data, regardless of how the data were created. Using a 3120 deterministic order will make comparisons possible using simple tools 3121 like "diff". 3123 This is the default order. 3125 7.7.7.2. ordered-by user 3127 The entries in the list are sorted according to an order defined by 3128 the user. This order is controlled by using special XML attributes 3129 in the request. See Section 7.7.9 for details. 3131 7.7.8. XML Mapping Rules 3133 A leaf-list node is encoded as a series of XML elements. Each 3134 element's local name is the leaf-list's identifier, and its namespace 3135 is the module's XML namespace (see Section 7.1.3). 3137 The value of each leaf-list entry is encoded to XML according to the 3138 type, and sent as character data in the element. 3140 The XML elements representing leaf-list entries MUST appear in the 3141 order specified by the user if the leaf-list is "ordered-by user"; 3142 otherwise, the order is implementation-dependent. The XML elements 3143 representing leaf-list entries MAY be interleaved with other sibling 3144 elements, unless the leaf-list defines RPC input or output 3145 parameters. 3147 See Section 7.7.10 for an example. 3149 7.7.9. NETCONF Operations 3151 Leaf-list entries can be created and deleted, but not modified, 3152 through , by using the "operation" attribute in the 3153 leaf-list entry's XML element. 3155 In an "ordered-by user" leaf-list, the attributes "insert" and 3156 "value" in the YANG XML namespace (Section 5.3.1) can be used to 3157 control where in the leaf-list the entry is inserted. These can be 3158 used during "create" operations to insert a new leaf-list entry, or 3159 during "merge" or "replace" operations to insert a new leaf-list 3160 entry or move an existing one. 3162 The "insert" attribute can take the values "first", "last", "before", 3163 and "after". If the value is "before" or "after", the "value" 3164 attribute MUST also be used to specify an existing entry in the leaf- 3165 list. 3167 If no "insert" attribute is present in the "create" operation, it 3168 defaults to "last". 3170 If several entries in an "ordered-by user" leaf-list are modified in 3171 the same request, the entries are modified one at the 3172 time, in the order of the XML elements in the request. 3174 In a , or an with a "replace" operation 3175 that covers the entire leaf-list, the leaf-list order is the same as 3176 the order of the XML elements in the request. 3178 When a NETCONF server processes an request, the 3179 elements of procedure for a leaf-list node are: 3181 If the operation is "merge" or "replace", the leaf-list entry is 3182 created if it does not exist. 3184 If the operation is "create", the leaf-list entry is created if it 3185 does not exist. If the leaf-list entry already exists, a 3186 "data-exists" error is returned. 3188 If the operation is "delete", the entry is deleted from the leaf- 3189 list if it exists. If the leaf-list entry does not exist, a 3190 "data-missing" error is returned. 3192 7.7.10. Usage Example 3194 leaf-list allow-user { 3195 type string; 3196 description "A list of user name patterns to allow"; 3197 } 3199 A corresponding XML instance example: 3201 alice 3202 bob 3204 To create a new element in this list, using the default 3205 operation "merge": 3207 3210 3211 3212 3213 3214 3215 3216 3217 3218 eric 3219 3220 3221 3222 3223 3224 3226 Given the following ordered-by user leaf-list: 3228 leaf-list cipher { 3229 type string; 3230 ordered-by user; 3231 description "A list of ciphers"; 3232 } 3234 The following would be used to insert a new cipher "blowfish-cbc" 3235 after "3des-cbc": 3237 3241 3242 3243 3244 3245 3246 3247 3248 3249 blowfish-cbc 3252 3253 3254 3255 3256 3257 3259 7.8. The list Statement 3261 The "list" statement is used to define an interior data node in the 3262 schema tree. A list node may exist in multiple instances in the data 3263 tree. Each such instance is known as a list entry. The "list" 3264 statement takes one argument, which is an identifier, followed by a 3265 block of substatements that holds detailed list information. 3267 A list entry is uniquely identified by the values of the list's keys, 3268 if defined. 3270 7.8.1. The list's Substatements 3271 +--------------+---------+-------------+ 3272 | substatement | section | cardinality | 3273 +--------------+---------+-------------+ 3274 | action | 7.15 | 0..n | 3275 | anydata | 7.10 | 0..n | 3276 | anyxml | 7.11 | 0..n | 3277 | choice | 7.9 | 0..n | 3278 | config | 7.21.1 | 0..1 | 3279 | container | 7.5 | 0..n | 3280 | description | 7.21.3 | 0..1 | 3281 | grouping | 7.12 | 0..n | 3282 | if-feature | 7.20.2 | 0..n | 3283 | key | 7.8.2 | 0..1 | 3284 | leaf | 7.6 | 0..n | 3285 | leaf-list | 7.7 | 0..n | 3286 | list | 7.8 | 0..n | 3287 | max-elements | 7.7.6 | 0..1 | 3288 | min-elements | 7.7.5 | 0..1 | 3289 | must | 7.5.3 | 0..n | 3290 | notification | 7.16 | 0..n | 3291 | ordered-by | 7.7.7 | 0..1 | 3292 | reference | 7.21.4 | 0..1 | 3293 | status | 7.21.2 | 0..1 | 3294 | typedef | 7.3 | 0..n | 3295 | unique | 7.8.3 | 0..n | 3296 | uses | 7.13 | 0..n | 3297 | when | 7.21.5 | 0..1 | 3298 +--------------+---------+-------------+ 3300 7.8.2. The list's key Statement 3302 The "key" statement, which MUST be present if the list represents 3303 configuration, and MAY be present otherwise, takes as an argument a 3304 string that specifies a space-separated list of leaf identifiers of 3305 this list. A leaf identifier MUST NOT appear more than once in the 3306 key. Each such leaf identifier MUST refer to a child leaf of the 3307 list. The leafs can be defined directly in substatements to the 3308 list, or in groupings used in the list. 3310 The combined values of all the leafs specified in the key are used to 3311 uniquely identify a list entry. All key leafs MUST be given values 3312 when a list entry is created. Thus, any default values in the key 3313 leafs or their types are ignored. It also implies that any mandatory 3314 statement in the key leafs are ignored. 3316 A leaf that is part of the key can be of any built-in or derived 3317 type. 3319 All key leafs in a list MUST have the same value for their "config" 3320 as the list itself. 3322 The key string syntax is formally defined by the rule "key-arg" in 3323 Section 13. 3325 7.8.3. The list's unique Statement 3327 The "unique" statement is used to put constraints on valid list 3328 entries. It takes as an argument a string that contains a space- 3329 separated list of schema node identifiers, which MUST be given in the 3330 descendant form (see the rule "descendant-schema-nodeid" in 3331 Section 13). Each such schema node identifier MUST refer to a leaf. 3333 If one of the referenced leafs represents configuration data, then 3334 all of the referenced leafs MUST represent configuration data. 3336 The "unique" constraint specifies that the combined values of all the 3337 leaf instances specified in the argument string, including leafs with 3338 default values, MUST be unique within all list entry instances in 3339 which all referenced leafs exist. The constraint is enforced 3340 according to the rules in Section 8. 3342 The unique string syntax is formally defined by the rule "unique-arg" 3343 in Section 13. 3345 7.8.3.1. Usage Example 3347 With the following list: 3349 list server { 3350 key "name"; 3351 unique "ip port"; 3352 leaf name { 3353 type string; 3354 } 3355 leaf ip { 3356 type inet:ip-address; 3357 } 3358 leaf port { 3359 type inet:port-number; 3360 } 3361 } 3363 The following configuration is not valid: 3365 3366 smtp 3367 192.0.2.1 3368 25 3369 3371 3372 http 3373 192.0.2.1 3374 25 3375 3377 The following configuration is valid, since the "http" and "ftp" list 3378 entries do not have a value for all referenced leafs, and are thus 3379 not taken into account when the "unique" constraint is enforced: 3381 3382 smtp 3383 192.0.2.1 3384 25 3385 3387 3388 http 3389 192.0.2.1 3390 3392 3393 ftp 3394 192.0.2.1 3395 3397 7.8.4. The list's Child Node Statements 3399 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 3400 "choice", "anydata", and "anyxml" statements can be used to define 3401 child nodes to the list. 3403 7.8.5. XML Mapping Rules 3405 A list is encoded as a series of XML elements, one for each entry in 3406 the list. Each element's local name is the list's identifier, and 3407 its namespace is the module's XML namespace (see Section 7.1.3). 3409 The list's key nodes are encoded as subelements to the list's 3410 identifier element, in the same order as they are defined within the 3411 "key" statement. 3413 The rest of the list's child nodes are encoded as subelements to the 3414 list element, after the keys. If the list defines RPC input or 3415 output parameters, the subelements are encoded in the same order as 3416 they are defined within the "list" statement. Otherwise, the 3417 subelements are encoded in any order. 3419 The XML elements representing list entries MUST appear in the order 3420 specified by the user if the list is "ordered-by user", otherwise the 3421 order is implementation-dependent. The XML elements representing 3422 list entries MAY be interleaved with other sibling elements, unless 3423 the list defines RPC input or output parameters. 3425 7.8.6. NETCONF Operations 3427 List entries can be created, deleted, replaced, and modified through 3428 , by using the "operation" attribute in the list's XML 3429 element. In each case, the values of all keys are used to uniquely 3430 identify a list entry. If all keys are not specified for a list 3431 entry, a "missing-element" error is returned. 3433 In an "ordered-by user" list, the attributes "insert" and "key" in 3434 the YANG XML namespace (Section 5.3.1) can be used to control where 3435 in the list the entry is inserted. These can be used during "create" 3436 operations to insert a new list entry, or during "merge" or "replace" 3437 operations to insert a new list entry or move an existing one. 3439 The "insert" attribute can take the values "first", "last", "before", 3440 and "after". If the value is "before" or "after", the "key" 3441 attribute MUST also be used, to specify an existing element in the 3442 list. The value of the "key" attribute is the key predicates of the 3443 full instance identifier (see Section 9.13) for the list entry. 3445 If no "insert" attribute is present in the "create" operation, it 3446 defaults to "last". 3448 If several entries in an "ordered-by user" list are modified in the 3449 same request, the entries are modified one at the time, 3450 in the order of the XML elements in the request. 3452 In a , or an with a "replace" operation 3453 that covers the entire list, the list entry order is the same as the 3454 order of the XML elements in the request. 3456 When a NETCONF server processes an request, the 3457 elements of procedure for a list node are: 3459 If the operation is "merge" or "replace", the list entry is 3460 created if it does not exist. If the list entry already exists 3461 and the "insert" and "key" attributes are present, the list entry 3462 is moved according to the values of the "insert" and "key" 3463 attributes. If the list entry exists and the "insert" and "key" 3464 attributes are not present, the list entry is not moved. 3466 If the operation is "create", the list entry is created if it does 3467 not exist. If the list entry already exists, a "data-exists" 3468 error is returned. 3470 If the operation is "delete", the entry is deleted from the list 3471 if it exists. If the list entry does not exist, a "data-missing" 3472 error is returned. 3474 7.8.7. Usage Example 3476 Given the following list: 3478 list user { 3479 key "name"; 3480 config true; 3481 description "This is a list of users in the system."; 3483 leaf name { 3484 type string; 3485 } 3486 leaf type { 3487 type string; 3488 } 3489 leaf full-name { 3490 type string; 3491 } 3492 } 3494 A corresponding XML instance example: 3496 3497 fred 3498 admin 3499 Fred Flintstone 3500 3502 To create a new user "barney": 3504 3507 3508 3509 3510 3511 3512 3513 3514 barney 3515 admin 3516 Barney Rubble 3517 3518 3519 3520 3521 3523 To change the type of "fred" to "superuser": 3525 3528 3529 3530 3531 3532 3533 3534 3535 fred 3536 superuser 3537 3538 3539 3540 3541 3543 Given the following ordered-by user list: 3545 list user { 3546 description "This is a list of users in the system."; 3547 ordered-by user; 3548 config true; 3550 key "name"; 3552 leaf name { 3553 type string; 3554 } 3555 leaf type { 3556 type string; 3557 } 3558 leaf full-name { 3559 type string; 3560 } 3561 } 3563 The following would be used to insert a new user "barney" after the 3564 user "fred": 3566 3570 3571 3572 3573 3574 3575 3577 3580 barney 3581 admin 3582 Barney Rubble 3583 3584 3585 3586 3587 3589 The following would be used to move the user "barney" before the user 3590 "fred": 3592 3596 3597 3598 3599 3600 3601 3603 3606 barney 3607 3608 3609 3610 3611 3613 7.9. The choice Statement 3615 The "choice" statement defines a set of alternatives, only one of 3616 which may exist at any one time. The argument is an identifier, 3617 followed by a block of substatements that holds detailed choice 3618 information. The identifier is used to identify the choice node in 3619 the schema tree. A choice node does not exist in the data tree. 3621 A choice consists of a number of branches, defined with the "case" 3622 substatement. Each branch contains a number of child nodes. The 3623 nodes from at most one of the choice's branches exist at the same 3624 time. 3626 See Section 8.3.2 for additional information. 3628 7.9.1. The choice's Substatements 3629 +--------------+---------+-------------+ 3630 | substatement | section | cardinality | 3631 +--------------+---------+-------------+ 3632 | anydata | 7.10 | 0..n | 3633 | anyxml | 7.11 | 0..n | 3634 | case | 7.9.2 | 0..n | 3635 | choice | 7.9 | 0..n | 3636 | config | 7.21.1 | 0..1 | 3637 | container | 7.5 | 0..n | 3638 | default | 7.9.3 | 0..1 | 3639 | description | 7.21.3 | 0..1 | 3640 | if-feature | 7.20.2 | 0..n | 3641 | leaf | 7.6 | 0..n | 3642 | leaf-list | 7.7 | 0..n | 3643 | list | 7.8 | 0..n | 3644 | mandatory | 7.9.4 | 0..1 | 3645 | reference | 7.21.4 | 0..1 | 3646 | status | 7.21.2 | 0..1 | 3647 | when | 7.21.5 | 0..1 | 3648 +--------------+---------+-------------+ 3650 7.9.2. The choice's case Statement 3652 The "case" statement is used to define branches of the choice. It 3653 takes as an argument an identifier, followed by a block of 3654 substatements that holds detailed case information. 3656 The identifier is used to identify the case node in the schema tree. 3657 A case node does not exist in the data tree. 3659 Within a "case" statement, the "anydata", "anyxml", "choice", 3660 "container", "leaf", "list", "leaf-list", and "uses" statements can 3661 be used to define child nodes to the case node. The identifiers of 3662 all these child nodes MUST be unique within all cases in a choice. 3663 For example, the following is illegal: 3665 choice interface-type { // This example is illegal YANG 3666 case a { 3667 leaf ethernet { ... } 3668 } 3669 case b { 3670 container ethernet { ...} 3671 } 3672 } 3674 As a shorthand, the "case" statement can be omitted if the branch 3675 contains a single "anydata", "anyxml", "choice", "container", "leaf", 3676 "list", or "leaf-list" statement. In this case, the identifier of 3677 the case node is the same as the identifier in the branch statement. 3678 The following example: 3680 choice interface-type { 3681 container ethernet { ... } 3682 } 3684 is equivalent to: 3686 choice interface-type { 3687 case ethernet { 3688 container ethernet { ... } 3689 } 3690 } 3692 The case identifier MUST be unique within a choice. 3694 7.9.2.1. The case's Substatements 3696 +--------------+---------+-------------+ 3697 | substatement | section | cardinality | 3698 +--------------+---------+-------------+ 3699 | anydata | 7.10 | 0..n | 3700 | anyxml | 7.11 | 0..n | 3701 | choice | 7.9 | 0..n | 3702 | container | 7.5 | 0..n | 3703 | description | 7.21.3 | 0..1 | 3704 | if-feature | 7.20.2 | 0..n | 3705 | leaf | 7.6 | 0..n | 3706 | leaf-list | 7.7 | 0..n | 3707 | list | 7.8 | 0..n | 3708 | reference | 7.21.4 | 0..1 | 3709 | status | 7.21.2 | 0..1 | 3710 | uses | 7.13 | 0..n | 3711 | when | 7.21.5 | 0..1 | 3712 +--------------+---------+-------------+ 3714 7.9.3. The choice's default Statement 3716 The "default" statement indicates if a case should be considered as 3717 the default if no child nodes from any of the choice's cases exist. 3718 The argument is the identifier of the "case" statement. If the 3719 "default" statement is missing, there is no default case. 3721 The "default" statement MUST NOT be present on choices where 3722 "mandatory" is true. 3724 The default case is only important when considering the default 3725 values of nodes under the cases. The default values for nodes under 3726 the default case are used if none of the nodes under any of the cases 3727 are present. 3729 There MUST NOT be any mandatory nodes (Section 3.1) directly under 3730 the default case. 3732 Default values for child nodes under a case are only used if one of 3733 the nodes under that case is present, or if that case is the default 3734 case. If none of the nodes under a case are present and the case is 3735 not the default case, the default values of the cases' child nodes 3736 are ignored. 3738 In this example, the choice defaults to "interval", and the default 3739 value will be used if none of "daily", "time-of-day", or "manual" are 3740 present. If "daily" is present, the default value for "time-of-day" 3741 will be used. 3743 container transfer { 3744 choice how { 3745 default interval; 3746 case interval { 3747 leaf interval { 3748 type uint16; 3749 default 30; 3750 units minutes; 3751 } 3752 } 3753 case daily { 3754 leaf daily { 3755 type empty; 3756 } 3757 leaf time-of-day { 3758 type string; 3759 units 24-hour-clock; 3760 default 1am; 3761 } 3762 } 3763 case manual { 3764 leaf manual { 3765 type empty; 3766 } 3767 } 3768 } 3769 } 3771 7.9.4. The choice's mandatory Statement 3773 The "mandatory" statement, which is optional, takes as an argument 3774 the string "true" or "false", and puts a constraint on valid data. 3775 If "mandatory" is "true", at least one node from exactly one of the 3776 choice's case branches MUST exist. 3778 If not specified, the default is "false". 3780 The behavior of the constraint depends on the type of the choice's 3781 closest ancestor node in the schema tree which is not a non-presence 3782 container (see Section 7.5.1): 3784 o If this ancestor is a case node, the constraint is enforced if any 3785 other node from the case exists. 3787 o Otherwise, it is enforced if the ancestor node exists. 3789 The constraint is further enforced according to the rules in 3790 Section 8. 3792 7.9.5. XML Mapping Rules 3794 The choice and case nodes are not visible in XML. 3796 The child nodes of the selected "case" statement MUST be encoded in 3797 the same order as they are defined in the "case" statement if they 3798 are part of an RPC input or output parameter definition. Otherwise, 3799 the subelements are encoded in any order. 3801 7.9.6. NETCONF Operations 3803 Since only one of the choice's cases can be valid at any time, the 3804 creation of a node from one case implicitly deletes all nodes from 3805 all other cases. If an operation creates a node from a 3806 case, the NETCONF server will delete any existing nodes that are 3807 defined in other cases inside the choice. 3809 7.9.7. Usage Example 3811 Given the following choice: 3813 container protocol { 3814 choice name { 3815 case a { 3816 leaf udp { 3817 type empty; 3818 } 3819 } 3820 case b { 3821 leaf tcp { 3822 type empty; 3823 } 3824 } 3825 } 3826 } 3828 A corresponding XML instance example: 3830 3831 3832 3834 To change the protocol from tcp to udp: 3836 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3853 7.10. The anydata Statement 3855 The "anydata" statement defines an interior node in the schema tree. 3856 It takes one argument, which is an identifier, followed by a block of 3857 substatements that holds detailed anydata information. 3859 The "anydata" statement is used to represent an unknown set of nodes 3860 that can be modelled with YANG. An example of where this can be 3861 useful is a list of received notifications, where the exact 3862 notifications are not known as design time. 3864 An anydata node cannot be augmented (see Section 7.17). 3866 An anydata node exists in zero or one instances in the data tree. 3868 Since the use of anydata limits the manipulation of the content, it 3869 is RECOMMENDED that the "anydata" statement not be used to define 3870 configuration data. 3872 7.10.1. The anydata's Substatements 3874 +--------------+---------+-------------+ 3875 | substatement | section | cardinality | 3876 +--------------+---------+-------------+ 3877 | config | 7.21.1 | 0..1 | 3878 | description | 7.21.3 | 0..1 | 3879 | if-feature | 7.20.2 | 0..n | 3880 | mandatory | 7.6.5 | 0..1 | 3881 | must | 7.5.3 | 0..n | 3882 | reference | 7.21.4 | 0..1 | 3883 | status | 7.21.2 | 0..1 | 3884 | when | 7.21.5 | 0..1 | 3885 +--------------+---------+-------------+ 3887 7.10.2. XML Mapping Rules 3889 An anydata node is encoded as an XML element. The element's local 3890 name is the anydata's identifier, and its namespace is the module's 3891 XML namespace (see Section 7.1.3). The value of the anydata node is 3892 a set of nodes, which are encoded as XML subelements to the anydata 3893 element. 3895 7.10.3. NETCONF Operations 3897 An anydata node is treated as an opaque chunk of data. This data can 3898 be modified in its entirety only. 3900 Any "operation" attributes present on subelements of an anydata node 3901 are ignored by the NETCONF server. 3903 When a NETCONF server processes an request, the 3904 elements of procedure for the anydata node are: 3906 If the operation is "merge" or "replace", the node is created if 3907 it does not exist, and its value is set to the subelements to the 3908 anydata node found in the XML RPC data. 3910 If the operation is "create", the node is created if it does not 3911 exist, and its value is set to the subelements to the anydata node 3912 found in the XML RPC data. If the node already exists, a 3913 "data-exists" error is returned. 3915 If the operation is "delete", the node is deleted if it exists. 3916 If the node does not exist, a "data-missing" error is returned. 3918 7.10.4. Usage Example 3920 Given the following "anydata" statement: 3922 list logged-notification { 3923 key time; 3924 leaf time { 3925 type yang:date-and-time; 3926 } 3927 anydata data; 3928 } 3930 The following is a valid encoding of such a list instance: 3932 3933 3934 3935 3937 2014-07-29T13:43:01Z 3938 3939 fault 3940 3941 Ethernet0 3942 3943 major 3944 3945 3946 3948 7.11. The anyxml Statement 3950 The "anyxml" statement defines an interior node in the schema tree. 3951 It takes one argument, which is an identifier, followed by a block of 3952 substatements that holds detailed anyxml information. 3954 The "anyxml" statement is used to represent an unknown chunk of XML. 3955 No restrictions are placed on the XML. This can be useful, for 3956 example, in RPC replies. An example is the parameter in the 3957 operation. 3959 An anyxml node cannot be augmented (see Section 7.17). 3961 An anyxml node exists in zero or one instances in the data tree. 3963 Since the use of anyxml limits the manipulation of the content, it is 3964 RECOMMENDED that the "anyxml" statement not be used to define 3965 configuration data. 3967 It should be noted that in YANG version 1, anyxml was the only 3968 statement that could model an unknown hierarchy of data. In many 3969 cases this unknown hierarchy of data is actually modelled in YANG, 3970 but the exact YANG model is not known at design time. In these 3971 situations, it is RECOMMENDED to use anydata (Section 7.10) instead 3972 of anyxml. 3974 7.11.1. The anyxml's Substatements 3976 +--------------+---------+-------------+ 3977 | substatement | section | cardinality | 3978 +--------------+---------+-------------+ 3979 | config | 7.21.1 | 0..1 | 3980 | description | 7.21.3 | 0..1 | 3981 | if-feature | 7.20.2 | 0..n | 3982 | mandatory | 7.6.5 | 0..1 | 3983 | must | 7.5.3 | 0..n | 3984 | reference | 7.21.4 | 0..1 | 3985 | status | 7.21.2 | 0..1 | 3986 | when | 7.21.5 | 0..1 | 3987 +--------------+---------+-------------+ 3989 7.11.2. XML Mapping Rules 3991 An anyxml node is encoded as an XML element. The element's local 3992 name is the anyxml's identifier, and its namespace is the module's 3993 XML namespace (see Section 7.1.3). The value of the anyxml node is 3994 encoded as XML content of this element. 3996 Note that any XML prefixes used in the encoding are local to each 3997 instance encoding. This means that the same XML may be encoded 3998 differently by different implementations. 4000 7.11.3. NETCONF Operations 4002 An anyxml node is treated as an opaque chunk of data. This data can 4003 be modified in its entirety only. 4005 Any "operation" attributes present on subelements of an anyxml node 4006 are ignored by the NETCONF server. 4008 When a NETCONF server processes an request, the 4009 elements of procedure for the anyxml node are: 4011 If the operation is "merge" or "replace", the node is created if 4012 it does not exist, and its value is set to the XML content of the 4013 anyxml node found in the XML RPC data. 4015 If the operation is "create", the node is created if it does not 4016 exist, and its value is set to the XML content of the anyxml node 4017 found in the XML RPC data. If the node already exists, a 4018 "data-exists" error is returned. 4020 If the operation is "delete", the node is deleted if it exists. 4021 If the node does not exist, a "data-missing" error is returned. 4023 7.11.4. Usage Example 4025 Given the following "anyxml" statement: 4027 anyxml data; 4029 The following are two valid encodings of the same anyxml value: 4031 4032 4033 1 4034 4035 4037 4038 4039 1 4040 4041 4043 7.12. The grouping Statement 4045 The "grouping" statement is used to define a reusable block of nodes, 4046 which may be used locally in the module or submodule, and by other 4047 modules that import from it, according to the rules in Section 5.5. 4048 It takes one argument, which is an identifier, followed by a block of 4049 substatements that holds detailed grouping information. 4051 The "grouping" statement is not a data definition statement and, as 4052 such, does not define any nodes in the schema tree. 4054 A grouping is like a "structure" or a "record" in conventional 4055 programming languages. 4057 Once a grouping is defined, it can be referenced in a "uses" 4058 statement (see Section 7.13). A grouping MUST NOT reference itself, 4059 neither directly nor indirectly through a chain of other groupings. 4061 If the grouping is defined at the top level of a YANG module or 4062 submodule, the grouping's identifier MUST be unique within the 4063 module. 4065 A grouping is more than just a mechanism for textual substitution, 4066 but defines a collection of nodes. Identifiers appearing inside the 4067 grouping are resolved relative to the scope in which the grouping is 4068 defined, not where it is used. Prefix mappings, type names, grouping 4069 names, and extension usage are evaluated in the hierarchy where the 4070 "grouping" statement appears. For extensions, this means that 4071 extensions are applied to the grouping node, not the uses node. 4073 7.12.1. The grouping's Substatements 4075 +--------------+---------+-------------+ 4076 | substatement | section | cardinality | 4077 +--------------+---------+-------------+ 4078 | action | 7.15 | 0..n | 4079 | anydata | 7.10 | 0..n | 4080 | anyxml | 7.11 | 0..n | 4081 | choice | 7.9 | 0..n | 4082 | container | 7.5 | 0..n | 4083 | description | 7.21.3 | 0..1 | 4084 | grouping | 7.12 | 0..n | 4085 | leaf | 7.6 | 0..n | 4086 | leaf-list | 7.7 | 0..n | 4087 | list | 7.8 | 0..n | 4088 | notification | 7.16 | 0..n | 4089 | reference | 7.21.4 | 0..1 | 4090 | status | 7.21.2 | 0..1 | 4091 | typedef | 7.3 | 0..n | 4092 | uses | 7.13 | 0..n | 4093 +--------------+---------+-------------+ 4095 7.12.2. Usage Example 4096 import ietf-inet-types { 4097 prefix "inet"; 4098 } 4100 grouping endpoint { 4101 description "A reusable endpoint group."; 4102 leaf ip { 4103 type inet:ip-address; 4104 } 4105 leaf port { 4106 type inet:port-number; 4107 } 4108 } 4110 7.13. The uses Statement 4112 The "uses" statement is used to reference a "grouping" definition. 4113 It takes one argument, which is the name of the grouping. 4115 The effect of a "uses" reference to a grouping is that the nodes 4116 defined by the grouping are copied into the current schema tree, and 4117 then updated according to the "refine" and "augment" statements. 4119 The identifiers defined in the grouping are not bound to a namespace 4120 until the contents of the grouping are added to the schema tree via a 4121 "uses" statement that does not appear inside a "grouping" statement, 4122 at which point they are bound to the namespace of the current module. 4124 7.13.1. The uses's Substatements 4126 +--------------+---------+-------------+ 4127 | substatement | section | cardinality | 4128 +--------------+---------+-------------+ 4129 | augment | 7.17 | 0..n | 4130 | description | 7.21.3 | 0..1 | 4131 | if-feature | 7.20.2 | 0..n | 4132 | refine | 7.13.2 | 0..n | 4133 | reference | 7.21.4 | 0..1 | 4134 | status | 7.21.2 | 0..1 | 4135 | when | 7.21.5 | 0..1 | 4136 +--------------+---------+-------------+ 4138 7.13.2. The refine Statement 4140 Some of the properties of each node in the grouping can be refined 4141 with the "refine" statement. The argument is a string that 4142 identifies a node in the grouping. This node is called the refine's 4143 target node. If a node in the grouping is not present as a target 4144 node of a "refine" statement, it is not refined, and thus used 4145 exactly as it was defined in the grouping. 4147 The argument string is a descendant schema node identifier (see 4148 Section 6.5). 4150 The following refinements can be done: 4152 o A leaf or choice node may get a default value, or a new default 4153 value if it already had one. 4155 o Any node may get a specialized "description" string. 4157 o Any node may get a specialized "reference" string. 4159 o Any node may get a different "config" statement. 4161 o A leaf, anydata, anyxml, or choice node may get a different 4162 "mandatory" statement. 4164 o A container node may get a "presence" statement. 4166 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4167 get additional "must" expressions. 4169 o A leaf-list or list node may get a different "min-elements" or 4170 "max-elements" statement. 4172 o A leaf, leaf-list, list, container, anydata, or anyxml node may 4173 get additional "if-feature" expressions. 4175 7.13.3. XML Mapping Rules 4177 Each node in the grouping is encoded as if it was defined inline, 4178 even if it is imported from another module with another XML 4179 namespace. 4181 7.13.4. Usage Example 4183 To use the "endpoint" grouping defined in Section 7.12.2 in a 4184 definition of an HTTP server in some other module, we can do: 4186 import acme-system { 4187 prefix "acme"; 4188 } 4190 container http-server { 4191 leaf name { 4192 type string; 4193 } 4194 uses acme:endpoint; 4195 } 4197 A corresponding XML instance example: 4199 4200 extern-web 4201 192.0.2.1 4202 80 4203 4205 If port 80 should be the default for the HTTP server, default can be 4206 added: 4208 container http-server { 4209 leaf name { 4210 type string; 4211 } 4212 uses acme:endpoint { 4213 refine port { 4214 default 80; 4215 } 4216 } 4217 } 4219 If we want to define a list of servers, and each server has the ip 4220 and port as keys, we can do: 4222 list server { 4223 key "ip port"; 4224 leaf name { 4225 type string; 4226 } 4227 uses acme:endpoint; 4228 } 4230 The following is an error: 4232 container http-server { 4233 uses acme:endpoint; 4234 leaf ip { // illegal - same identifier "ip" used twice 4235 type string; 4236 } 4237 } 4239 7.14. The rpc Statement 4241 The "rpc" statement is used to define an RPC operation. It takes one 4242 argument, which is an identifier, followed by a block of 4243 substatements that holds detailed rpc information. This argument is 4244 the name of the RPC, and is used as the element name directly under 4245 the element, as designated by the substitution group 4246 "rpcOperation" in [RFC6241]. 4248 The "rpc" statement defines an rpc node in the schema tree. Under 4249 the rpc node, a schema node with the name "input", and a schema node 4250 with the name "output" are also defined. The nodes "input" and 4251 "output" are defined in the module's namespace. 4253 7.14.1. The rpc's Substatements 4255 +--------------+---------+-------------+ 4256 | substatement | section | cardinality | 4257 +--------------+---------+-------------+ 4258 | description | 7.21.3 | 0..1 | 4259 | grouping | 7.12 | 0..n | 4260 | if-feature | 7.20.2 | 0..n | 4261 | input | 7.14.2 | 0..1 | 4262 | output | 7.14.3 | 0..1 | 4263 | reference | 7.21.4 | 0..1 | 4264 | status | 7.21.2 | 0..1 | 4265 | typedef | 7.3 | 0..n | 4266 +--------------+---------+-------------+ 4268 7.14.2. The input Statement 4270 The "input" statement, which is optional, is used to define input 4271 parameters to the operation. It does not take an argument. The 4272 substatements to "input" define nodes under the operation's input 4273 node. 4275 If a leaf in the input tree has a "mandatory" statement with the 4276 value "true", the leaf MUST be present in a NETCONF RPC invocation. 4277 Otherwise, the server MUST return a "missing-element" error. 4279 If a leaf in the input tree has a default value, the NETCONF server 4280 MUST use this value in the same cases as described in Section 7.6.1. 4281 In these cases, the server MUST operationally behave as if the leaf 4282 was present in the NETCONF RPC invocation with the default value as 4283 its value. 4285 If a leaf-list in the input tree has one or more default values, the 4286 NETCONF server MUST use these values in the same cases as described 4287 in Section 7.7.2. In these cases, the server MUST operationally 4288 behave as if the leaf-list was present in the NETCONF RPC invocation 4289 with the default values as its values. 4291 If a "config" statement is present for any node in the input tree, 4292 the "config" statement is ignored. 4294 If any node has a "when" statement that would evaluate to false, then 4295 this node MUST NOT be present in the input tree. 4297 7.14.2.1. The input's Substatements 4299 +--------------+---------+-------------+ 4300 | substatement | section | cardinality | 4301 +--------------+---------+-------------+ 4302 | anydata | 7.10 | 0..n | 4303 | anyxml | 7.11 | 0..n | 4304 | choice | 7.9 | 0..n | 4305 | container | 7.5 | 0..n | 4306 | grouping | 7.12 | 0..n | 4307 | leaf | 7.6 | 0..n | 4308 | leaf-list | 7.7 | 0..n | 4309 | list | 7.8 | 0..n | 4310 | must | 7.5.3 | 0..n | 4311 | typedef | 7.3 | 0..n | 4312 | uses | 7.13 | 0..n | 4313 +--------------+---------+-------------+ 4315 7.14.3. The output Statement 4317 The "output" statement, which is optional, is used to define output 4318 parameters to the RPC operation. It does not take an argument. The 4319 substatements to "output" define nodes under the operation's output 4320 node. 4322 If a leaf in the output tree has a "mandatory" statement with the 4323 value "true", the leaf MUST be present in a NETCONF RPC reply. 4325 If a leaf in the output tree has a default value, the NETCONF client 4326 MUST use this value in the same cases as described in Section 7.6.1. 4328 In these cases, the client MUST operationally behave as if the leaf 4329 was present in the NETCONF RPC reply with the default value as its 4330 value. 4332 If a leaf-list in the output tree has one or more default values, the 4333 NETCONF client MUST use these values in the same cases as described 4334 in Section 7.7.2. In these cases, the client MUST operationally 4335 behave as if the leaf-list was present in the NETCONF RPC reply with 4336 the default values as its values. 4338 If a "config" statement is present for any node in the output tree, 4339 the "config" statement is ignored. 4341 If any node has a "when" statement that would evaluate to false, then 4342 this node MUST NOT be present in the output tree. 4344 7.14.3.1. The output's Substatements 4346 +--------------+---------+-------------+ 4347 | substatement | section | cardinality | 4348 +--------------+---------+-------------+ 4349 | anydata | 7.10 | 0..n | 4350 | anyxml | 7.11 | 0..n | 4351 | choice | 7.9 | 0..n | 4352 | container | 7.5 | 0..n | 4353 | grouping | 7.12 | 0..n | 4354 | leaf | 7.6 | 0..n | 4355 | leaf-list | 7.7 | 0..n | 4356 | list | 7.8 | 0..n | 4357 | must | 7.5.3 | 0..n | 4358 | typedef | 7.3 | 0..n | 4359 | uses | 7.13 | 0..n | 4360 +--------------+---------+-------------+ 4362 7.14.4. XML Mapping Rules 4364 An rpc node is encoded as a child XML element to the element 4365 defined in [RFC6241]. The element's local name is the rpc's 4366 identifier, and its namespace is the module's XML namespace (see 4367 Section 7.1.3). 4369 Input parameters are encoded as child XML elements to the rpc node's 4370 XML element, in the same order as they are defined within the "input" 4371 statement. 4373 If the RPC operation invocation succeeded, and no output parameters 4374 are returned, the contains a single element defined 4375 in [RFC6241]. If output parameters are returned, they are encoded as 4376 child elements to the element defined in [RFC6241], in 4377 the same order as they are defined within the "output" statement. 4379 7.14.5. Usage Example 4381 The following example defines an RPC operation: 4383 module rock { 4384 yang-version 1.1; 4385 namespace "http://example.net/rock"; 4386 prefix "rock"; 4388 rpc rock-the-house { 4389 input { 4390 leaf zip-code { 4391 type string; 4392 } 4393 } 4394 } 4395 } 4397 A corresponding XML instance example of the complete rpc and rpc- 4398 reply: 4400 4402 4403 27606-0100 4404 4405 4407 4409 4410 4412 7.15. The action Statement 4414 The "action" statement is used to define an operation connected to a 4415 specific container or list data node. It takes one argument, which 4416 is an identifier, followed by a block of substatements that holds 4417 detailed action information. The argument is the name of the action. 4419 The "action" statement defines an action node in the schema tree. 4420 Under the action node, a schema node with the name "input", and a 4421 schema node with the name "output" are also defined. The nodes 4422 "input" and "output" are defined in the module's namespace. 4424 An action MUST NOT be defined within an rpc, another action or a 4425 notification, i.e., an action node MUST NOT have an rpc, action, or a 4426 notification node as one of its ancestors in the schema tree. For 4427 example, this means that it is an error if a grouping that contains 4428 an action somewhere in its node hierarchy is used in a notification 4429 definition. 4431 Since an action cannot be defined an the top-level of a module or in 4432 a case statement, it is an error if a grouping that contains an 4433 action at the top of its node hierarchy is used at the top-level of a 4434 module or in a case definition. 4436 The difference between an action and an rpc is that an action is tied 4437 to a node in the data tree, whereas an rpc is not. When an action is 4438 invoked, the node in the data tree is specified along with the name 4439 of the action and the input parameters. 4441 7.15.1. The action's Substatements 4443 +--------------+---------+-------------+ 4444 | substatement | section | cardinality | 4445 +--------------+---------+-------------+ 4446 | description | 7.21.3 | 0..1 | 4447 | grouping | 7.12 | 0..n | 4448 | if-feature | 7.20.2 | 0..n | 4449 | input | 7.14.2 | 0..1 | 4450 | output | 7.14.3 | 0..1 | 4451 | reference | 7.21.4 | 0..1 | 4452 | status | 7.21.2 | 0..1 | 4453 | typedef | 7.3 | 0..n | 4454 +--------------+---------+-------------+ 4456 7.15.2. XML Mapping Rules 4458 When an action is invoked, an element with the local name "action" in 4459 the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is 4460 encoded as a child XML element to the element defined in 4461 [RFC6241], as designated by the substitution group "rpcOperation" in 4462 [RFC6241]. 4464 The "action" element contains an hierarchy of nodes that identifies 4465 the node in the data tree. It MUST contain all containers and list 4466 nodes from the top level down to the list or container containing the 4467 action. For lists, all key leafs MUST also be included. The last 4468 container or list contains an XML element that carries the name of 4469 the defined action. Within this element the input parameters are 4470 encoded as child XML elements, in the same order as they are defined 4471 within the "input" statement. 4473 Only one action can be invoked in one . If more than one action 4474 is present in the , the server MUST reply with an "bad-element" 4475 error-tag in the . 4477 If the action operation invocation succeeded, and no output 4478 parameters are returned, the contains a single 4479 element defined in [RFC6241]. If output parameters are returned, 4480 they are encoded as child elements to the element defined 4481 in [RFC6241], in the same order as they are defined within the 4482 "output" statement. 4484 7.15.3. Usage Example 4486 The following example defines an action to reset one server at a 4487 server farm: 4489 module server-farm { 4490 yang-version 1.1; 4491 namespace "http://example.net/server-farm"; 4492 prefix "sfarm"; 4494 import ietf-yang-types { 4495 prefix "yang"; 4496 } 4498 list server { 4499 key name; 4500 leaf name { 4501 type string; 4502 } 4503 action reset { 4504 input { 4505 leaf reset-at { 4506 type yang:date-and-time; 4507 mandatory true; 4508 } 4509 } 4510 output { 4511 leaf reset-finished-at { 4512 type yang:date-and-time; 4513 mandatory true; 4514 } 4515 } 4516 } 4517 } 4518 } 4520 A corresponding XML instance example of the complete rpc and rpc- 4521 reply: 4523 4525 4526 4527 apache-1 4528 4529 2014-07-29T13:42:00Z 4530 4531 4532 4533 4535 4537 4538 2014-07-29T13:42:12Z 4539 4540 4542 7.16. The notification Statement 4544 The "notification" statement is used to define a NETCONF 4545 notification. It takes one argument, which is an identifier, 4546 followed by a block of substatements that holds detailed notification 4547 information. The "notification" statement defines a notification 4548 node in the schema tree. 4550 A notification can be defined at the top-level of a module, or 4551 connected to a specific container or list data node in the schema 4552 tree. 4554 A notification MUST NOT be defined within an rpc, action or another 4555 notification, i.e., a notification node MUST NOT have an rpc, action, 4556 or a notification node as one of its ancestors in the schema tree. 4557 For example, this means that it is an error if a grouping that 4558 contains an notification somewhere in its node hierarchy is used in 4559 an rpc definition. 4561 Since a notification cannot be defined in a case statement, it is an 4562 error if a grouping that contains a notification at the top of its 4563 node hierarchy is used in a case definition. 4565 If a leaf in the notification tree has a "mandatory" statement with 4566 the value "true", the leaf MUST be present in a NETCONF notification. 4568 If a leaf in the notification tree has a default value, the NETCONF 4569 client MUST use this value in the same cases as described in 4570 Section 7.6.1. In these cases, the client MUST operationally behave 4571 as if the leaf was present in the NETCONF notification with the 4572 default value as its value. 4574 If a leaf-list in the notification tree has one or more default 4575 values, the NETCONF client MUST use these values in the same cases as 4576 described in Section 7.7.2. In these cases, the client MUST 4577 operationally behave as if the leaf-list was present in the NETCONF 4578 notification with the default values as its values. 4580 If a "config" statement is present for any node in the notification 4581 tree, the "config" statement is ignored. 4583 7.16.1. The notification's Substatements 4585 +--------------+---------+-------------+ 4586 | substatement | section | cardinality | 4587 +--------------+---------+-------------+ 4588 | anydata | 7.10 | 0..n | 4589 | anyxml | 7.11 | 0..n | 4590 | choice | 7.9 | 0..n | 4591 | container | 7.5 | 0..n | 4592 | description | 7.21.3 | 0..1 | 4593 | grouping | 7.12 | 0..n | 4594 | if-feature | 7.20.2 | 0..n | 4595 | leaf | 7.6 | 0..n | 4596 | leaf-list | 7.7 | 0..n | 4597 | list | 7.8 | 0..n | 4598 | must | 7.5.3 | 0..n | 4599 | reference | 7.21.4 | 0..1 | 4600 | status | 7.21.2 | 0..1 | 4601 | typedef | 7.3 | 0..n | 4602 | uses | 7.13 | 0..n | 4603 +--------------+---------+-------------+ 4605 7.16.2. XML Mapping Rules 4607 A notification node that is defined on the top-level of a module is 4608 encoded as a child XML element to the element defined 4609 in NETCONF Event Notifications [RFC5277]. The element's local name 4610 is the notification's identifier, and its namespace is the module's 4611 XML namespace (see Section 7.1.3). 4613 When a notification node is defined as a child to a data node, the 4614 element defined in NETCONF Event Notifications 4615 [RFC5277] contains an hierarchy of nodes that identifies the node in 4616 the data tree. It MUST contain all containers and list nodes from 4617 the top level down to the list or container containing the 4618 notification. For lists, all key leafs MUST also be included. The 4619 last container or list contains an XML element that carries the name 4620 of the defined notification. 4622 The notification's child nodes are encoded as subelements to the 4623 notification node's XML element, in any order. 4625 7.16.3. Usage Example 4627 The following example defines a notification at the top-level of a 4628 module: 4630 module event { 4631 yang-version 1.1; 4632 namespace "http://example.com/event"; 4633 prefix "ev"; 4635 notification event { 4636 leaf event-class { 4637 type string; 4638 } 4639 leaf reporting-entity { 4640 type instance-identifier; 4641 } 4642 leaf severity { 4643 type string; 4644 } 4645 } 4646 } 4648 A corresponding XML instance example of the complete notification: 4650 4652 2008-07-08T00:01:00Z 4653 4654 fault 4655 4656 /ex:interface[ex:name='Ethernet0'] 4657 4658 major 4659 4660 4662 The following example defines a notification in a data node: 4664 module interface-module { 4665 yang-version 1.1; 4666 namespace "http://example.com/schema/interfaces"; 4667 prefix "if"; 4669 container interfaces { 4670 list interface { 4671 key "name"; 4672 leaf name { 4673 type string; 4674 } 4675 notification interface-enabled { 4676 leaf by-user { 4677 type string; 4678 } 4679 } 4680 } 4681 } 4682 } 4684 A corresponding XML instance example of the complete notification: 4686 4688 2008-07-08T00:01:00Z 4689 4690 4691 eth1 4692 4693 fred 4694 4695 4696 4697 4699 7.17. The augment Statement 4701 The "augment" statement allows a module or submodule to add to the 4702 schema tree defined in an external module, or the current module and 4703 its submodules, and to add to the nodes from a grouping in a "uses" 4704 statement. The argument is a string that identifies a node in the 4705 schema tree. This node is called the augment's target node. The 4706 target node MUST be either a container, list, choice, case, input, 4707 output, or notification node. It is augmented with the nodes defined 4708 in the substatements that follow the "augment" statement. 4710 The argument string is a schema node identifier (see Section 6.5). 4711 If the "augment" statement is on the top level in a module or 4712 submodule, the absolute form (defined by the rule 4713 "absolute-schema-nodeid" in Section 13) of a schema node identifier 4714 MUST be used. If the "augment" statement is a substatement to the 4715 "uses" statement, the descendant form (defined by the rule 4716 "descendant-schema-nodeid" in Section 13) MUST be used. 4718 If the target node is a container, list, case, input, output, or 4719 notification node, the "container", "leaf", "list", "leaf-list", 4720 "uses", and "choice" statements can be used within the "augment" 4721 statement. 4723 If the target node is a choice node, the "case" statement, or a case 4724 shorthand statement (see Section 7.9.2) can be used within the 4725 "augment" statement. 4727 If the target node is in another module, then nodes added by the 4728 augmentation MUST NOT be mandatory nodes (see Section 3.1). 4730 The "augment" statement MUST NOT add multiple nodes with the same 4731 name from the same module to the target node. 4733 7.17.1. The augment's Substatements 4735 +--------------+---------+-------------+ 4736 | substatement | section | cardinality | 4737 +--------------+---------+-------------+ 4738 | action | 7.15 | 0..n | 4739 | anydata | 7.10 | 0..n | 4740 | anyxml | 7.11 | 0..n | 4741 | case | 7.9.2 | 0..n | 4742 | choice | 7.9 | 0..n | 4743 | container | 7.5 | 0..n | 4744 | description | 7.21.3 | 0..1 | 4745 | if-feature | 7.20.2 | 0..n | 4746 | leaf | 7.6 | 0..n | 4747 | leaf-list | 7.7 | 0..n | 4748 | list | 7.8 | 0..n | 4749 | notification | 7.16 | 0..n | 4750 | reference | 7.21.4 | 0..1 | 4751 | status | 7.21.2 | 0..1 | 4752 | uses | 7.13 | 0..n | 4753 | when | 7.21.5 | 0..1 | 4754 +--------------+---------+-------------+ 4756 7.17.2. XML Mapping Rules 4758 All data nodes defined in the "augment" statement are defined as XML 4759 elements in the XML namespace of the module where the "augment" is 4760 specified. 4762 When a node is augmented, the augmenting child nodes are encoded as 4763 subelements to the augmented node, in any order. 4765 7.17.3. Usage Example 4767 In namespace http://example.com/schema/interfaces, we have: 4769 container interfaces { 4770 list ifEntry { 4771 key "ifIndex"; 4773 leaf ifIndex { 4774 type uint32; 4775 } 4776 leaf ifDescr { 4777 type string; 4778 } 4779 leaf ifType { 4780 type iana:IfType; 4781 } 4782 leaf ifMtu { 4783 type int32; 4784 } 4785 } 4786 } 4788 Then, in namespace http://example.com/schema/ds0, we have: 4790 import interface-module { 4791 prefix "if"; 4792 } 4793 augment "/if:interfaces/if:ifEntry" { 4794 when "if:ifType='ds0'"; 4795 leaf ds0ChannelNumber { 4796 type ChannelNumber; 4797 } 4798 } 4800 A corresponding XML instance example: 4802 4804 4805 1 4806 Flintstone Inc Ethernet A562 4807 ethernetCsmacd 4808 1500 4809 4810 4811 2 4812 Flintstone Inc DS0 4813 ds0 4814 1 4815 4816 4818 As another example, suppose we have the choice defined in 4819 Section 7.9.7. The following construct can be used to extend the 4820 protocol definition: 4822 augment /ex:system/ex:protocol/ex:name { 4823 case c { 4824 leaf smtp { 4825 type empty; 4826 } 4827 } 4828 } 4830 A corresponding XML instance example: 4832 4833 4834 4835 4836 4838 or 4840 4841 4842 4843 4844 4846 7.18. The identity Statement 4848 The "identity" statement is used to define a new globally unique, 4849 abstract, and untyped identity. Its only purpose is to denote its 4850 name, semantics, and existence. An identity can either be defined 4851 from scratch or derived from one or more base identities. The 4852 identity's argument is an identifier that is the name of the 4853 identity. It is followed by a block of substatements that holds 4854 detailed identity information. 4856 The built-in datatype "identityref" (see Section 9.10) can be used to 4857 reference identities within a data model. 4859 7.18.1. The identity's Substatements 4861 +--------------+---------+-------------+ 4862 | substatement | section | cardinality | 4863 +--------------+---------+-------------+ 4864 | base | 7.18.2 | 0..n | 4865 | description | 7.21.3 | 0..1 | 4866 | if-feature | 7.20.2 | 0..n | 4867 | reference | 7.21.4 | 0..1 | 4868 | status | 7.21.2 | 0..1 | 4869 +--------------+---------+-------------+ 4871 7.18.2. The base Statement 4873 The "base" statement, which is optional, takes as an argument a 4874 string that is the name of an existing identity, from which the new 4875 identity is derived. If no "base" statement is present, the identity 4876 is defined from scratch. If multiple "base" statements are present, 4877 the identity is derived from all of them. 4879 If a prefix is present on the base name, it refers to an identity 4880 defined in the module that was imported with that prefix, or the 4881 local module if the prefix matches the local module's prefix. 4882 Otherwise, an identity with the matching name MUST be defined in the 4883 current module or an included submodule. 4885 An identity MUST NOT reference itself, neither directly nor 4886 indirectly through a chain of other identities. 4888 The derivation of identities has the following properties: 4890 o It is irreflexive, which means that an identity is not derived 4891 from itself. 4893 o It is transitive, which means that if identity B is derived from A 4894 and C is derived from B, then C is also derived from A. 4896 7.18.3. Usage Example 4898 module crypto-base { 4899 yang-version 1.1; 4900 namespace "http://example.com/crypto-base"; 4901 prefix "crypto"; 4903 identity crypto-alg { 4904 description 4905 "Base identity from which all crypto algorithms 4906 are derived."; 4907 } 4908 } 4910 module des { 4911 yang-version 1.1; 4912 namespace "http://example.com/des"; 4913 prefix "des"; 4915 import "crypto-base" { 4916 prefix "crypto"; 4917 } 4919 identity des { 4920 base "crypto:crypto-alg"; 4921 description "DES crypto algorithm"; 4922 } 4924 identity des3 { 4925 base "crypto:crypto-alg"; 4926 description "Triple DES crypto algorithm"; 4927 } 4928 } 4930 7.19. The extension Statement 4932 The "extension" statement allows the definition of new statements 4933 within the YANG language. This new statement definition can be 4934 imported and used by other modules. 4936 The statement's argument is an identifier that is the new keyword for 4937 the extension and must be followed by a block of substatements that 4938 holds detailed extension information. The purpose of the "extension" 4939 statement is to define a keyword, so that it can be imported and used 4940 by other modules. 4942 The extension can be used like a normal YANG statement, with the 4943 statement name followed by an argument if one is defined by the 4944 "extension" statement, and an optional block of substatements. The 4945 statement's name is created by combining the prefix of the module in 4946 which the extension was defined, a colon (":"), and the extension's 4947 keyword, with no interleaving whitespace. The substatements of an 4948 extension are defined by the "extension" statement, using some 4949 mechanism outside the scope of this specification. Syntactically, 4950 the substatements MUST be YANG statements, or also extensions defined 4951 using "extension" statements. YANG statements in extensions MUST 4952 follow the syntactical rules in Section 13. 4954 7.19.1. The extension's Substatements 4956 +--------------+---------+-------------+ 4957 | substatement | section | cardinality | 4958 +--------------+---------+-------------+ 4959 | argument | 7.19.2 | 0..1 | 4960 | description | 7.21.3 | 0..1 | 4961 | reference | 7.21.4 | 0..1 | 4962 | status | 7.21.2 | 0..1 | 4963 +--------------+---------+-------------+ 4965 7.19.2. The argument Statement 4967 The "argument" statement, which is optional, takes as an argument a 4968 string that is the name of the argument to the keyword. If no 4969 argument statement is present, the keyword expects no argument when 4970 it is used. 4972 The argument's name is used in the YIN mapping, where it is used as 4973 an XML attribute or element name, depending on the argument's 4974 "yin-element" statement. 4976 7.19.2.1. The argument's Substatements 4978 +--------------+----------+-------------+ 4979 | substatement | section | cardinality | 4980 +--------------+----------+-------------+ 4981 | yin-element | 7.19.2.2 | 0..1 | 4982 +--------------+----------+-------------+ 4984 7.19.2.2. The yin-element Statement 4986 The "yin-element" statement, which is optional, takes as an argument 4987 the string "true" or "false". This statement indicates if the 4988 argument is mapped to an XML element in YIN or to an XML attribute 4989 (see Section 12). 4991 If no "yin-element" statement is present, it defaults to "false". 4993 7.19.3. Usage Example 4995 To define an extension: 4997 module my-extensions { 4998 ... 5000 extension c-define { 5001 description 5002 "Takes as argument a name string. 5003 Makes the code generator use the given name in the 5004 #define."; 5005 argument "name"; 5006 } 5007 } 5009 To use the extension: 5011 module my-interfaces { 5012 ... 5013 import my-extensions { 5014 prefix "myext"; 5015 } 5016 ... 5018 container interfaces { 5019 ... 5020 myext:c-define "MY_INTERFACES"; 5021 } 5022 } 5024 7.20. Conformance-Related Statements 5026 This section defines statements related to conformance, as described 5027 in Section 5.6. 5029 7.20.1. The feature Statement 5031 The "feature" statement is used to define a mechanism by which 5032 portions of the schema are marked as conditional. A feature name is 5033 defined that can later be referenced using the "if-feature" statement 5034 (see Section 7.20.2). Schema nodes tagged with an "if-feature" 5035 statement are ignored by the device unless the device supports the 5036 given feature expression. This allows portions of the YANG module to 5037 be conditional based on conditions on the device. The model can 5038 represent the abilities of the device within the model, giving a 5039 richer model that allows for differing device abilities and roles. 5041 The argument to the "feature" statement is the name of the new 5042 feature, and follows the rules for identifiers in Section 6.2. This 5043 name is used by the "if-feature" statement to tie the schema nodes to 5044 the feature. 5046 In this example, a feature called "local-storage" represents the 5047 ability for a device to store syslog messages on local storage of 5048 some sort. This feature is used to make the "local-storage-limit" 5049 leaf conditional on the presence of some sort of local storage. If 5050 the device does not report that it supports this feature, the 5051 "local-storage-limit" node is not supported. 5053 module syslog { 5054 ... 5055 feature local-storage { 5056 description 5057 "This feature means the device supports local 5058 storage (memory, flash or disk) that can be used to 5059 store syslog messages."; 5060 } 5062 container syslog { 5063 leaf local-storage-limit { 5064 if-feature local-storage; 5065 type uint64; 5066 units "kilobyte"; 5067 config false; 5068 description 5069 "The amount of local storage that can be 5070 used to hold syslog messages."; 5071 } 5072 } 5073 } 5075 The "if-feature" statement can be used in many places within the YANG 5076 syntax. Definitions tagged with "if-feature" are ignored when the 5077 device does not support that feature. 5079 A feature MUST NOT reference itself, neither directly nor indirectly 5080 through a chain of other features. 5082 In order for a device to implement a feature that is dependent on any 5083 other features (i.e., the feature has one or more "if-feature" 5084 substatements), the device MUST also implement all the dependant 5085 features. 5087 7.20.1.1. The feature's Substatements 5089 +--------------+---------+-------------+ 5090 | substatement | section | cardinality | 5091 +--------------+---------+-------------+ 5092 | description | 7.21.3 | 0..1 | 5093 | if-feature | 7.20.2 | 0..n | 5094 | status | 7.21.2 | 0..1 | 5095 | reference | 7.21.4 | 0..1 | 5096 +--------------+---------+-------------+ 5098 7.20.2. The if-feature Statement 5100 The "if-feature" statement makes its parent statement conditional. 5101 The argument is a boolean expression over feature names. In this 5102 expression, a feature name evaluates to "true" if and only if the 5103 feature is implemented by the server. The parent statement is 5104 implemented by servers where the boolean expression evaluates to 5105 "true". 5107 The if-feature boolean expression syntax is formally defined by the 5108 rule "if-feature-expr" in Section 13. When this boolean expression 5109 is evaluated, the operator order of precedence is (highest precedence 5110 first): "not", "and", "or". 5112 If a prefix is present on a feature name in the boolean expression, 5113 the prefixed name refers to a feature defined in the module that was 5114 imported with that prefix, or the local module if the prefix matches 5115 the local module's prefix. Otherwise, a feature with the matching 5116 name MUST be defined in the current module or an included submodule. 5118 A leaf that is a list key MUST NOT have any "if-feature" statements. 5120 7.20.2.1. Usage Example 5122 In this example, the container "target" is implemented if any of the 5123 features "outbound-tls" or "outbound-ssh" is implemented by the 5124 server. 5126 container target { 5127 if-feature "outbound-tls or outbound-ssh"; 5128 ... 5129 } 5131 7.20.3. The deviation Statement 5133 The "deviation" statement defines a hierarchy of a module that the 5134 device does not implement faithfully. The argument is a string that 5135 identifies the node in the schema tree where a deviation from the 5136 module occurs. This node is called the deviation's target node. The 5137 contents of the "deviation" statement give details about the 5138 deviation. 5140 The argument string is an absolute schema node identifier (see 5141 Section 6.5). 5143 Deviations define the way a device or class of devices deviate from a 5144 standard. This means that deviations MUST never be part of a 5145 published standard, since they are the mechanism for learning how 5146 implementations vary from the standards. 5148 Device deviations are strongly discouraged and MUST only be used as a 5149 last resort. Telling the application how a device fails to follow a 5150 standard is no substitute for implementing the standard correctly. A 5151 device that deviates from a module is not fully compliant with the 5152 module. 5154 However, in some cases, a particular device may not have the hardware 5155 or software ability to support parts of a standard module. When this 5156 occurs, the device makes a choice either to treat attempts to 5157 configure unsupported parts of the module as an error that is 5158 reported back to the unsuspecting application or ignore those 5159 incoming requests. Neither choice is acceptable. 5161 Instead, YANG allows devices to document portions of a base module 5162 that are not supported or supported but with different syntax, by 5163 using the "deviation" statement. 5165 7.20.3.1. The deviation's Substatements 5167 +--------------+----------+-------------+ 5168 | substatement | section | cardinality | 5169 +--------------+----------+-------------+ 5170 | description | 7.21.3 | 0..1 | 5171 | deviate | 7.20.3.2 | 1..n | 5172 | reference | 7.21.4 | 0..1 | 5173 +--------------+----------+-------------+ 5175 7.20.3.2. The deviate Statement 5177 The "deviate" statement defines how the device's implementation of 5178 the target node deviates from its original definition. The argument 5179 is one of the strings "not-supported", "add", "replace", or "delete". 5181 The argument "not-supported" indicates that the target node is not 5182 implemented by this device. 5184 The argument "add" adds properties to the target node. The 5185 properties to add are identified by substatements to the "deviate" 5186 statement. If a property can only appear once, the property MUST NOT 5187 exist in the target node. 5189 The argument "replace" replaces properties of the target node. The 5190 properties to replace are identified by substatements to the 5191 "deviate" statement. The properties to replace MUST exist in the 5192 target node. 5194 The argument "delete" deletes properties from the target node. The 5195 properties to delete are identified by substatements to the "delete" 5196 statement. The substatement's keyword MUST match a corresponding 5197 keyword in the target node, and the argument's string MUST be equal 5198 to the corresponding keyword's argument string in the target node. 5200 +--------------+-------------+-------------+ 5201 | substatement | section | cardinality | 5202 +--------------+-------------+-------------+ 5203 | config | 7.21.1 | 0..1 | 5204 | default | 7.6.4 7.7.4 | 0..n | 5205 | mandatory | 7.6.5 | 0..1 | 5206 | max-elements | 7.7.6 | 0..1 | 5207 | min-elements | 7.7.5 | 0..1 | 5208 | must | 7.5.3 | 0..n | 5209 | type | 7.4 | 0..1 | 5210 | unique | 7.8.3 | 0..n | 5211 | units | 7.3.3 | 0..1 | 5212 +--------------+-------------+-------------+ 5214 The deviate's Substatements 5216 7.20.3.3. Usage Example 5218 In this example, the device is informing client applications that it 5219 does not support the "daytime" service in the style of RFC 867. 5221 deviation /base:system/base:daytime { 5222 deviate not-supported; 5223 } 5225 The following example sets a device-specific default value to a leaf 5226 that does not have a default value defined: 5228 deviation /base:system/base:user/base:type { 5229 deviate add { 5230 default "admin"; // new users are 'admin' by default 5231 } 5232 } 5234 In this example, the device limits the number of name servers to 3: 5236 deviation /base:system/base:name-server { 5237 deviate replace { 5238 max-elements 3; 5239 } 5240 } 5242 If the original definition is: 5244 container system { 5245 must "daytime or time"; 5246 ... 5247 } 5249 a device might remove this must constraint by doing: 5251 deviation "/base:system" { 5252 deviate delete { 5253 must "daytime or time"; 5254 } 5255 } 5257 7.21. Common Statements 5259 This section defines substatements common to several other 5260 statements. 5262 7.21.1. The config Statement 5264 The "config" statement takes as an argument the string "true" or 5265 "false". If "config" is "true", the definition represents 5266 configuration. Data nodes representing configuration will be part of 5267 the reply to a request, and can be sent in a 5268 or request. 5270 If "config" is "false", the definition represents state data. Data 5271 nodes representing state data will be part of the reply to a , 5272 but not to a request, and cannot be sent in a 5273 or request. 5275 If "config" is not specified, the default is the same as the parent 5276 schema node's "config" value. If the parent node is a "case" node, 5277 the value is the same as the "case" node's parent "choice" node. 5279 If the top node does not specify a "config" statement, the default is 5280 "true". 5282 If a node has "config" set to "false", no node underneath it can have 5283 "config" set to "true". 5285 7.21.2. The status Statement 5287 The "status" statement takes as an argument one of the strings 5288 "current", "deprecated", or "obsolete". 5290 o "current" means that the definition is current and valid. 5292 o "deprecated" indicates an obsolete definition, but it permits new/ 5293 continued implementation in order to foster interoperability with 5294 older/existing implementations. 5296 o "obsolete" means the definition is obsolete and SHOULD NOT be 5297 implemented and/or can be removed from implementations. 5299 If no status is specified, the default is "current". 5301 If a definition is "current", it MUST NOT reference a "deprecated" or 5302 "obsolete" definition within the same module. 5304 If a definition is "deprecated", it MUST NOT reference an "obsolete" 5305 definition within the same module. 5307 For example, the following is illegal: 5309 typedef my-type { 5310 status deprecated; 5311 type int32; 5312 } 5314 leaf my-leaf { 5315 status current; 5316 type my-type; // illegal, since my-type is deprecated 5317 } 5319 7.21.3. The description Statement 5321 The "description" statement takes as an argument a string that 5322 contains a human-readable textual description of this definition. 5323 The text is provided in a language (or languages) chosen by the 5324 module developer; for the sake of interoperability, it is RECOMMENDED 5325 to choose a language that is widely understood among the community of 5326 network administrators who will use the module. 5328 7.21.4. The reference Statement 5330 The "reference" statement takes as an argument a string that is used 5331 to specify a textual cross-reference to an external document, either 5332 another module that defines related management information, or a 5333 document that provides additional information relevant to this 5334 definition. 5336 For example, a typedef for a "uri" data type could look like: 5338 typedef uri { 5339 type string; 5340 reference 5341 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; 5342 ... 5343 } 5345 7.21.5. The when Statement 5347 The "when" statement makes its parent data definition statement 5348 conditional. The node defined by the parent data definition 5349 statement is only valid when the condition specified by the "when" 5350 statement is satisfied. The statement's argument is an XPath 5351 expression (see Section 6.4), which is used to formally specify this 5352 condition. If the XPath expression conceptually evaluates to "true" 5353 for a particular instance, then the node defined by the parent data 5354 definition statement is valid; otherwise, it is not. 5356 A leaf that is a list key MUST NOT have a "when" statement. 5358 See Section 8.3.2 for additional information. 5360 The XPath expression is conceptually evaluated in the following 5361 context, in addition to the definition in Section 6.4.1: 5363 o If the "when" statement is a child of an "augment" statement, then 5364 the context node is the augment's target node in the data tree, if 5365 the target node is a data node. Otherwise, the context node is 5366 the closest ancestor node to the target node that is also a data 5367 node. 5369 o If the "when" statement is a child of a "uses", "choice", or 5370 "case" statement, then the context node is the closest ancestor 5371 node to the "uses", "choice", or "case" node that is also a data 5372 node. If no such node exists, the context node is the root node. 5374 o If the "when" statement is a child of any other data definition 5375 statement, the accessible tree is tentatively altered during the 5376 processing of the XPath expression by replacing all instances (if 5377 any) of the data node for which the "when" statement is defined 5378 with a single dummy node with the same name, but with no value and 5379 no children. The context node is this dummy node. 5381 The result of the XPath expression is converted to a boolean value 5382 using the standard XPath rules. 5384 If the XPath expression references any node that also has associated 5385 "when" statements, these "when" expressions MUST be evaluated first. 5386 There MUST NOT be any circular dependencies in these "when" 5387 expressions. 5389 Note that the XPath expression is conceptually evaluated. This means 5390 that an implementation does not have to use an XPath evaluator on the 5391 device. The "when" statement can very well be implemented with 5392 specially written code. 5394 8. Constraints 5396 8.1. Constraints on Data 5398 Several YANG statements define constraints on valid data. These 5399 constraints are enforced in different ways, depending on what type of 5400 data the statement defines. 5402 o If the constraint is defined on configuration data, it MUST be 5403 true in a valid configuration data tree. 5405 o If the constraint is defined on state data, it MUST be true in a 5406 reply to a operation without a filter. 5408 o If the constraint is defined on notification content, it MUST be 5409 true in any notification instance. 5411 o If the constraint is defined on RPC input parameters, it MUST be 5412 true in an invocation of the RPC operation. 5414 o If the constraint is defined on RPC output parameters, it MUST be 5415 true in the RPC reply. 5417 8.2. Hierarchy of Constraints 5419 Conditions on parent nodes affect constraints on child nodes as a 5420 natural consequence of the hierarchy of nodes. "must", "mandatory", 5421 "min-elements", and "max-elements" constraints are not enforced if 5422 the parent node has a "when" or "if-feature" property that is not 5423 satisfied on the current device. 5425 In this example, the "mandatory" constraint on the "longitude" leaf 5426 is not enforced on devices that lack the "has-gps" feature: 5428 container location { 5429 if-feature has-gps; 5430 leaf longitude { 5431 mandatory true; 5432 ... 5433 } 5434 } 5436 8.3. Constraint Enforcement Model 5438 For configuration data, there are three windows when constraints MUST 5439 be enforced: 5441 o during parsing of RPC payloads 5443 o during processing of NETCONF operations 5445 o during validation 5447 Each of these scenarios is considered in the following sections. 5449 8.3.1. Payload Parsing 5451 When content arrives in RPC payloads, it MUST be well-formed XML, 5452 following the hierarchy and content rules defined by the set of 5453 models the device implements. 5455 o If a leaf data value does not match the type constraints for the 5456 leaf, including those defined in the type's "range", "length", and 5457 "pattern" properties, the server MUST reply with an 5458 "invalid-value" error-tag in the rpc-error, and with the error- 5459 app-tag and error-message associated with the constraint, if any 5460 exist. 5462 o If all keys of a list entry are not present, the server MUST reply 5463 with a "missing-element" error-tag in the rpc-error. 5465 o If data for more than one case branch of a choice is present, the 5466 server MUST reply with a "bad-element" in the rpc-error. 5468 o If data for a node tagged with "if-feature" is present, and the 5469 if-feature expression evaluates to "false" on the device, the 5470 server MUST reply with an "unknown-element" error-tag in the rpc- 5471 error. 5473 o If data for a node tagged with "when" is present, and the "when" 5474 condition evaluates to "false", the server MUST reply with an 5475 "unknown-element" error-tag in the rpc-error. 5477 o For insert handling, if the value for the attributes "before" and 5478 "after" are not valid for the type of the appropriate key leafs, 5479 the server MUST reply with a "bad-attribute" error-tag in the rpc- 5480 error. 5482 o If the attributes "before" and "after" appears in any element that 5483 is not a list whose "ordered-by" property is "user", the server 5484 MUST reply with an "unknown-attribute" error-tag in the rpc-error. 5486 8.3.2. NETCONF Processing 5488 After the incoming data is parsed, the NETCONF server performs the 5489 operation by applying the data to the configuration 5490 datastore. During this processing, the following errors MUST be 5491 detected: 5493 o Delete requests for non-existent data. 5495 o Create requests for existent data. 5497 o Insert requests with "before" or "after" parameters that do not 5498 exist. 5500 During processing: 5502 o If the NETCONF operation creates data nodes under a "choice", any 5503 existing nodes from other "case" branches are deleted by the 5504 server. 5506 o If the NETCONF operation modifies a data node such that any node's 5507 "when" expression becomes false, then the node with the "when" 5508 expression is deleted by the server. 5510 8.3.3. Validation 5512 When datastore processing is complete, the final contents MUST obey 5513 all validation constraints. This validation processing is performed 5514 at differing times according to the datastore. If the datastore is 5515 "running" or "startup", these constraints MUST be enforced at the end 5516 of the or operation. If the datastore is 5517 "candidate", the constraint enforcement is delayed until a 5518 or operation. 5520 o Any "must" constraints MUST evaluate to "true". 5522 o Any referential integrity constraints defined via the "path" 5523 statement MUST be satisfied. 5525 o Any "unique" constraints on lists MUST be satisfied. 5527 o The "min-elements" and "max-elements" constraints are enforced for 5528 lists and leaf-lists. 5530 9. Built-In Types 5532 YANG has a set of built-in types, similar to those of many 5533 programming languages, but with some differences due to special 5534 requirements from the management information model. 5536 Additional types may be defined, derived from those built-in types or 5537 from other derived types. Derived types may use subtyping to 5538 formally restrict the set of possible values. 5540 The different built-in types and their derived types allow different 5541 kinds of subtyping, namely length and regular expression restrictions 5542 of strings (Section 9.4.4, Section 9.4.5) and range restrictions of 5543 numeric types (Section 9.2.4). 5545 The lexical representation of a value of a certain type is used in 5546 the NETCONF messages and when specifying default values and numerical 5547 ranges in YANG modules. 5549 9.1. Canonical Representation 5551 For most types, there is a single canonical representation of the 5552 type's values. Some types allow multiple lexical representations of 5553 the same value, for example, the positive integer "17" can be 5554 represented as "+17" or "17". Implementations MUST support all 5555 lexical representations specified in this document. 5557 When a NETCONF server sends data, it MUST be in the canonical form. 5559 Some types have a lexical representation that depends on the XML 5560 context in which they occur. These types do not have a canonical 5561 form. 5563 9.2. The Integer Built-In Types 5565 The integer built-in types are int8, int16, int32, int64, uint8, 5566 uint16, uint32, and uint64. They represent signed and unsigned 5567 integers of different sizes: 5569 int8 represents integer values between -128 and 127, inclusively. 5571 int16 represents integer values between -32768 and 32767, 5572 inclusively. 5574 int32 represents integer values between -2147483648 and 2147483647, 5575 inclusively. 5577 int64 represents integer values between -9223372036854775808 and 5578 9223372036854775807, inclusively. 5580 uint8 represents integer values between 0 and 255, inclusively. 5582 uint16 represents integer values between 0 and 65535, inclusively. 5584 uint32 represents integer values between 0 and 4294967295, 5585 inclusively. 5587 uint64 represents integer values between 0 and 18446744073709551615, 5588 inclusively. 5590 9.2.1. Lexical Representation 5592 An integer value is lexically represented as an optional sign ("+" or 5593 "-"), followed by a sequence of decimal digits. If no sign is 5594 specified, "+" is assumed. 5596 For convenience, when specifying a default value for an integer in a 5597 YANG module, an alternative lexical representation can be used, which 5598 represents the value in a hexadecimal or octal notation. The 5599 hexadecimal notation consists of an optional sign ("+" or "-"), the 5600 characters "0x" followed a number of hexadecimal digits, where 5601 letters may be uppercase or lowercase. The octal notation consists 5602 of an optional sign ("+" or "-"), the character "0" followed a number 5603 of octal digits. 5605 Note that if a default value in a YANG module has a leading zero 5606 ("0"), it is interpreted as an octal number. In the XML instance 5607 documents, an integer is always interpreted as a decimal number, and 5608 leading zeros are allowed. 5610 Examples: 5612 // legal values 5613 +4711 // legal positive value 5614 4711 // legal positive value 5615 -123 // legal negative value 5616 0xf00f // legal positive hexadecimal value 5617 -0xf // legal negative hexadecimal value 5618 052 // legal positive octal value 5620 // illegal values 5621 - 1 // illegal intermediate space 5623 9.2.2. Canonical Form 5625 The canonical form of a positive integer does not include the sign 5626 "+". Leading zeros are prohibited. The value zero is represented as 5627 "0". 5629 9.2.3. Restrictions 5631 All integer types can be restricted with the "range" statement 5632 (Section 9.2.4). 5634 9.2.4. The range Statement 5636 The "range" statement, which is an optional substatement to the 5637 "type" statement, takes as an argument a range expression string. It 5638 is used to restrict integer and decimal built-in types, or types 5639 derived from those. 5641 A range consists of an explicit value, or a lower-inclusive bound, 5642 two consecutive dots "..", and an upper-inclusive bound. Multiple 5643 values or ranges can be given, separated by "|". If multiple values 5644 or ranges are given, they all MUST be disjoint and MUST be in 5645 ascending order. If a range restriction is applied to an already 5646 range-restricted type, the new restriction MUST be equal or more 5647 limiting, that is raising the lower bounds, reducing the upper 5648 bounds, removing explicit values or ranges, or splitting ranges into 5649 multiple ranges with intermediate gaps. Each explicit value and 5650 range boundary value given in the range expression MUST match the 5651 type being restricted, or be one of the special values "min" or 5652 "max". "min" and "max" mean the minimum and maximum value accepted 5653 for the type being restricted, respectively. 5655 The range expression syntax is formally defined by the rule 5656 "range-arg" in Section 13. 5658 9.2.4.1. The range's Substatements 5660 +---------------+---------+-------------+ 5661 | substatement | section | cardinality | 5662 +---------------+---------+-------------+ 5663 | description | 7.21.3 | 0..1 | 5664 | error-app-tag | 7.5.4.2 | 0..1 | 5665 | error-message | 7.5.4.1 | 0..1 | 5666 | reference | 7.21.4 | 0..1 | 5667 +---------------+---------+-------------+ 5669 9.2.5. Usage Example 5671 typedef my-base-int32-type { 5672 type int32 { 5673 range "1..4 | 10..20"; 5674 } 5675 } 5677 typedef my-type1 { 5678 type my-base-int32-type { 5679 // legal range restriction 5680 range "11..max"; // 11..20 5681 } 5682 } 5684 typedef my-type2 { 5685 type my-base-int32-type { 5686 // illegal range restriction 5687 range "11..100"; 5688 } 5689 } 5691 9.3. The decimal64 Built-In Type 5693 The decimal64 type represents a subset of the real numbers, which can 5694 be represented by decimal numerals. The value space of decimal64 is 5695 the set of numbers that can be obtained by multiplying a 64-bit 5696 signed integer by a negative power of ten, i.e., expressible as "i x 5697 10^-n" where i is an integer64 and n is an integer between 1 and 18, 5698 inclusively. 5700 9.3.1. Lexical Representation 5702 A decimal64 value is lexically represented as an optional sign ("+" 5703 or "-"), followed by a sequence of decimal digits, optionally 5704 followed by a period ('.') as a decimal indicator and a sequence of 5705 decimal digits. If no sign is specified, "+" is assumed. 5707 9.3.2. Canonical Form 5709 The canonical form of a positive decimal64 does not include the sign 5710 "+". The decimal point is required. Leading and trailing zeros are 5711 prohibited, subject to the rule that there MUST be at least one digit 5712 before and after the decimal point. The value zero is represented as 5713 "0.0". 5715 9.3.3. Restrictions 5717 A decimal64 type can be restricted with the "range" statement 5718 (Section 9.2.4). 5720 9.3.4. The fraction-digits Statement 5722 The "fraction-digits" statement, which is a substatement to the 5723 "type" statement, MUST be present if the type is "decimal64". It 5724 takes as an argument an integer between 1 and 18, inclusively. It 5725 controls the size of the minimum difference between values of a 5726 decimal64 type, by restricting the value space to numbers that are 5727 expressible as "i x 10^-n" where n is the fraction-digits argument. 5729 The following table lists the minimum and maximum value for each 5730 fraction-digit value: 5732 +----------------+-----------------------+----------------------+ 5733 | fraction-digit | min | max | 5734 +----------------+-----------------------+----------------------+ 5735 | 1 | -922337203685477580.8 | 922337203685477580.7 | 5736 | 2 | -92233720368547758.08 | 92233720368547758.07 | 5737 | 3 | -9223372036854775.808 | 9223372036854775.807 | 5738 | 4 | -922337203685477.5808 | 922337203685477.5807 | 5739 | 5 | -92233720368547.75808 | 92233720368547.75807 | 5740 | 6 | -9223372036854.775808 | 9223372036854.775807 | 5741 | 7 | -922337203685.4775808 | 922337203685.4775807 | 5742 | 8 | -92233720368.54775808 | 92233720368.54775807 | 5743 | 9 | -9223372036.854775808 | 9223372036.854775807 | 5744 | 10 | -922337203.6854775808 | 922337203.6854775807 | 5745 | 11 | -92233720.36854775808 | 92233720.36854775807 | 5746 | 12 | -9223372.036854775808 | 9223372.036854775807 | 5747 | 13 | -922337.2036854775808 | 922337.2036854775807 | 5748 | 14 | -92233.72036854775808 | 92233.72036854775807 | 5749 | 15 | -9223.372036854775808 | 9223.372036854775807 | 5750 | 16 | -922.3372036854775808 | 922.3372036854775807 | 5751 | 17 | -92.23372036854775808 | 92.23372036854775807 | 5752 | 18 | -9.223372036854775808 | 9.223372036854775807 | 5753 +----------------+-----------------------+----------------------+ 5755 9.3.5. Usage Example 5757 typedef my-decimal { 5758 type decimal64 { 5759 fraction-digits 2; 5760 range "1 .. 3.14 | 10 | 20..max"; 5761 } 5762 } 5764 9.4. The string Built-In Type 5766 The string built-in type represents human-readable strings in YANG. 5767 Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] 5768 characters, including tab, carriage return, and line feed but 5769 excluding the other C0 control characters, the surrogate blocks, and 5770 the noncharacters. The string syntax is formally defined by the rule 5771 "yang-string" in Section 13. 5773 9.4.1. Lexical Representation 5775 A string value is lexically represented as character data in the XML 5776 instance documents. 5778 9.4.2. Canonical Form 5780 The canonical form is the same as the lexical representation. No 5781 Unicode normalization is performed of string values. 5783 9.4.3. Restrictions 5785 A string can be restricted with the "length" (Section 9.4.4) and 5786 "pattern" (Section 9.4.5) statements. 5788 9.4.4. The length Statement 5790 The "length" statement, which is an optional substatement to the 5791 "type" statement, takes as an argument a length expression string. 5792 It is used to restrict the built-in types "string" and "binary" or 5793 types derived from them. 5795 A "length" statement restricts the number of Unicode characters in 5796 the string. 5798 A length range consists of an explicit value, or a lower bound, two 5799 consecutive dots "..", and an upper bound. Multiple values or ranges 5800 can be given, separated by "|". Length-restricting values MUST NOT 5801 be negative. If multiple values or ranges are given, they all MUST 5802 be disjoint and MUST be in ascending order. If a length restriction 5803 is applied to an already length-restricted type, the new restriction 5804 MUST be equal or more limiting, that is, raising the lower bounds, 5805 reducing the upper bounds, removing explicit length values or ranges, 5806 or splitting ranges into multiple ranges with intermediate gaps. A 5807 length value is a non-negative integer, or one of the special values 5808 "min" or "max". "min" and "max" mean the minimum and maximum length 5809 accepted for the type being restricted, respectively. An 5810 implementation is not required to support a length value larger than 5811 18446744073709551615. 5813 The length expression syntax is formally defined by the rule 5814 "length-arg" in Section 13. 5816 9.4.4.1. The length's Substatements 5818 +---------------+---------+-------------+ 5819 | substatement | section | cardinality | 5820 +---------------+---------+-------------+ 5821 | description | 7.21.3 | 0..1 | 5822 | error-app-tag | 7.5.4.2 | 0..1 | 5823 | error-message | 7.5.4.1 | 0..1 | 5824 | reference | 7.21.4 | 0..1 | 5825 +---------------+---------+-------------+ 5827 9.4.5. The pattern Statement 5829 The "pattern" statement, which is an optional substatement to the 5830 "type" statement, takes as an argument a regular expression string, 5831 as defined in [XSD-TYPES]. It is used to restrict the built-in type 5832 "string", or types derived from "string", to values that match the 5833 pattern. 5835 If the type has multiple "pattern" statements, the expressions are 5836 ANDed together, i.e., all such expressions have to match. 5838 If a pattern restriction is applied to an already pattern-restricted 5839 type, values must match all patterns in the base type, in addition to 5840 the new patterns. 5842 9.4.5.1. The pattern's Substatements 5844 +---------------+---------+-------------+ 5845 | substatement | section | cardinality | 5846 +---------------+---------+-------------+ 5847 | description | 7.21.3 | 0..1 | 5848 | error-app-tag | 7.5.4.2 | 0..1 | 5849 | error-message | 7.5.4.1 | 0..1 | 5850 | modifier | 9.4.6 | 0..1 | 5851 | reference | 7.21.4 | 0..1 | 5852 +---------------+---------+-------------+ 5854 9.4.6. The modifier Statement 5856 9.4.7. Usage Example 5858 With the following typedef: 5860 typedef my-base-str-type { 5861 type string { 5862 length "1..255"; 5863 } 5864 } 5866 the following refinement is legal: 5868 type my-base-str-type { 5869 // legal length refinement 5870 length "11 | 42..max"; // 11 | 42..255 5871 } 5873 and the following refinement is illegal: 5875 type my-base-str-type { 5876 // illegal length refinement 5877 length "1..999"; 5878 } 5880 With the following type: 5882 type string { 5883 length "0..4"; 5884 pattern "[0-9a-fA-F]*"; 5885 } 5887 the following strings match: 5889 AB // legal 5890 9A00 // legal 5892 and the following strings do not match: 5894 00ABAB // illegal, too long 5895 xx00 // illegal, bad characters 5897 With the following type: 5899 typedef yang-identifier { 5900 type string { 5901 length "1..max"; 5902 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 5903 pattern '[xX][mM][lL].*' { 5904 modifier invert-match; 5905 } 5906 } 5907 } 5909 the following string match: 5911 enabled // legal 5913 and the following strings do not match: 5915 10-mbit // illegal, starts with a number 5916 xml-element // illegal, starts with illegal sequence 5918 9.5. The boolean Built-In Type 5920 The boolean built-in type represents a boolean value. 5922 9.5.1. Lexical Representation 5924 The lexical representation of a boolean value is a string with a 5925 value of "true" or "false". These values MUST be in lowercase. 5927 9.5.2. Canonical Form 5929 The canonical form is the same as the lexical representation. 5931 9.5.3. Restrictions 5933 A boolean cannot be restricted. 5935 9.6. The enumeration Built-In Type 5937 The enumeration built-in type represents values from a set of 5938 assigned names. 5940 9.6.1. Lexical Representation 5942 The lexical representation of an enumeration value is the assigned 5943 name string. 5945 9.6.2. Canonical Form 5947 The canonical form is the assigned name string. 5949 9.6.3. Restrictions 5951 An enumeration can be restricted with the "enum" (Section 9.6.4) 5952 statement. 5954 9.6.4. The enum Statement 5956 The "enum" statement, which is a substatement to the "type" 5957 statement, MUST be present if the type is "enumeration". It is 5958 repeatedly used to specify each assigned name of an enumeration type. 5959 It takes as an argument a string which is the assigned name. The 5960 string MUST NOT be empty and MUST NOT have any leading or trailing 5961 whitespace characters. The use of Unicode control codes SHOULD be 5962 avoided. 5964 The statement is optionally followed by a block of substatements that 5965 holds detailed enum information. 5967 All assigned names in an enumeration MUST be unique. 5969 When an existing enumeration type is restricted, the set of assigned 5970 names in the new type MUST be a subset of the base type's set of 5971 assigned names. The value of such an assigned name MUST not be 5972 changed. 5974 9.6.4.1. The enum's Substatements 5976 +--------------+---------+-------------+ 5977 | substatement | section | cardinality | 5978 +--------------+---------+-------------+ 5979 | description | 7.21.3 | 0..1 | 5980 | if-feature | 7.20.2 | 0..n | 5981 | reference | 7.21.4 | 0..1 | 5982 | status | 7.21.2 | 0..1 | 5983 | value | 9.6.4.2 | 0..1 | 5984 +--------------+---------+-------------+ 5986 9.6.4.2. The value Statement 5988 The "value" statement, which is optional, is used to associate an 5989 integer value with the assigned name for the enum. This integer 5990 value MUST be in the range -2147483648 to 2147483647, and it MUST be 5991 unique within the enumeration type. 5993 If a value is not specified, then one will be automatically assigned. 5994 If the "enum" substatement is the first one defined, the assigned 5995 value is zero (0); otherwise, the assigned value is one greater than 5996 the current highest enum value (i.e., the highest enum value, 5997 implicit or explicit, prior to the current "enum" substatement in the 5998 parent "type" statement). 6000 If the current highest value is equal to 2147483647, then an enum 6001 value MUST be specified for "enum" substatements following the one 6002 with the current highest value. 6004 When an existing enumeration type is restricted, the "value" 6005 statement MUST either have the same value as in the base type or not 6006 be present, in which case the value is the same as in the base type. 6008 9.6.5. Usage Example 6009 leaf myenum { 6010 type enumeration { 6011 enum zero; 6012 enum one; 6013 enum seven { 6014 value 7; 6015 } 6016 } 6017 } 6019 The lexical representation of the leaf "myenum" with value "seven" 6020 is: 6022 seven 6024 With the following typedef: 6026 typedef my-base-enumeration-type { 6027 type enumeration { 6028 enum white { 6029 value 1; 6030 } 6031 enum yellow { 6032 value 2; 6033 } 6034 enum red { 6035 value 3; 6036 } 6037 } 6038 } 6040 the following refinement is legal: 6042 type my-base-enumeration-type { 6043 // legal enum refinement 6044 enum yellow; 6045 enum red { 6046 value 3; 6047 } 6048 } 6050 and the following refinement is illegal: 6052 type my-base-enumeration-type { 6053 // illegal enum refinement 6054 enum yellow { 6055 value 4; // illegal value change 6056 } 6057 enum black; // illegal addition of new name 6058 } 6060 9.7. The bits Built-In Type 6062 The bits built-in type represents a bit set. That is, a bits value 6063 is a set of flags identified by small integer position numbers 6064 starting at 0. Each bit number has an assigned name. 6066 9.7.1. Restrictions 6068 A bits type cannot be restricted. 6070 9.7.2. Lexical Representation 6072 The lexical representation of the bits type is a space-separated list 6073 of the individual bit values that are set. An empty string thus 6074 represents a value where no bits are set. 6076 9.7.3. Canonical Form 6078 In the canonical form, the bit values are separated by a single space 6079 character and they appear ordered by their position (see 6080 Section 9.7.4.2). 6082 9.7.4. The bit Statement 6084 The "bit" statement, which is a substatement to the "type" statement, 6085 MUST be present if the type is "bits". It is repeatedly used to 6086 specify each assigned named bit of a bits type. It takes as an 6087 argument a string that is the assigned name of the bit. It is 6088 followed by a block of substatements that holds detailed bit 6089 information. The assigned name follows the same syntax rules as an 6090 identifier (see Section 6.2). 6092 All assigned names in a bits type MUST be unique. 6094 9.7.4.1. The bit's Substatements 6095 +--------------+---------+-------------+ 6096 | substatement | section | cardinality | 6097 +--------------+---------+-------------+ 6098 | description | 7.21.3 | 0..1 | 6099 | if-feature | 7.20.2 | 0..n | 6100 | reference | 7.21.4 | 0..1 | 6101 | status | 7.21.2 | 0..1 | 6102 | position | 9.7.4.2 | 0..1 | 6103 +--------------+---------+-------------+ 6105 9.7.4.2. The position Statement 6107 The "position" statement, which is optional, takes as an argument a 6108 non-negative integer value that specifies the bit's position within a 6109 hypothetical bit field. The position value MUST be in the range 0 to 6110 4294967295, and it MUST be unique within the bits type. 6112 If a bit position is not specified, then one will be automatically 6113 assigned. If the "bit" substatement is the first one defined, the 6114 assigned value is zero (0); otherwise, the assigned value is one 6115 greater than the current highest bit position (i.e., the highest bit 6116 position, implicit or explicit, prior to the current "bit" 6117 substatement in the parent "type" statement). 6119 If the current highest bit position value is equal to 4294967295, 6120 then a position value MUST be specified for "bit" substatements 6121 following the one with the current highest position value. 6123 9.7.5. Usage Example 6125 Given the following leaf: 6127 leaf mybits { 6128 type bits { 6129 bit disable-nagle { 6130 position 0; 6131 } 6132 bit auto-sense-speed { 6133 position 1; 6134 } 6135 bit ten-mb-only { 6136 position 2; 6137 } 6138 } 6139 default "auto-sense-speed"; 6140 } 6142 The lexical representation of this leaf with bit values disable-nagle 6143 and ten-mb-only set would be: 6145 disable-nagle ten-mb-only 6147 9.8. The binary Built-In Type 6149 The binary built-in type represents any binary data, i.e., a sequence 6150 of octets. 6152 9.8.1. Restrictions 6154 A binary can be restricted with the "length" (Section 9.4.4) 6155 statement. The length of a binary value is the number of octets it 6156 contains. 6158 9.8.2. Lexical Representation 6160 Binary values are encoded with the base64 encoding scheme (see 6161 [RFC4648], Section 4). 6163 9.8.3. Canonical Form 6165 The canonical form of a binary value follows the rules in [RFC4648]. 6167 9.9. The leafref Built-In Type 6169 The leafref type is used to declare a constraint on the value space 6170 of a leaf, based on a reference to a set of leaf instances in the 6171 data tree. The "path" substatement (Section 9.9.2) selects a set of 6172 leaf instances, and the leafref value space is the set of values of 6173 these leaf instances. 6175 If the leaf with the leafref type represents configuration data, and 6176 the "require-instance" property (Section 9.9.3) is "true", the leaf 6177 it refers to MUST also represent configuration. Such a leaf puts a 6178 constraint on valid data. All such nodes MUST reference existing 6179 leaf instances or leafs with default values in use (see Section 7.6.1 6180 and Section 7.7.2) for the data to be valid. This constraint is 6181 enforced according to the rules in Section 8. 6183 There MUST NOT be any circular chains of leafrefs. 6185 If the leaf that the leafref refers to is conditional based on one or 6186 more features (see Section 7.20.2), then the leaf with the leafref 6187 type MUST also be conditional based on at least the same set of 6188 features. 6190 9.9.1. Restrictions 6192 A leafref can be restricted with the "require-instance" statement 6193 (Section 9.9.3). 6195 9.9.2. The path Statement 6197 The "path" statement, which is a substatement to the "type" 6198 statement, MUST be present if the type is "leafref". It takes as an 6199 argument a string that MUST refer to a leaf or leaf-list node. 6201 The syntax for a path argument is a subset of the XPath abbreviated 6202 syntax. Predicates are used only for constraining the values for the 6203 key nodes for list entries. Each predicate consists of exactly one 6204 equality test per key, and multiple adjacent predicates MAY be 6205 present if a list has multiple keys. The syntax is formally defined 6206 by the rule "path-arg" in Section 13. 6208 The predicates are only used when more than one key reference is 6209 needed to uniquely identify a leaf instance. This occurs if a list 6210 has multiple keys, or a reference to a leaf other than the key in a 6211 list is needed. In these cases, multiple leafrefs are typically 6212 specified, and predicates are used to tie them together. 6214 The "path" expression evaluates to a node set consisting of zero, 6215 one, or more nodes. If the leaf with the leafref type represents 6216 configuration data, this node set MUST be non-empty. 6218 The "path" XPath expression is conceptually evaluated in the 6219 following context, in addition to the definition in Section 6.4.1: 6221 o If the "path" statement is defined within a typedef, the context 6222 node is the leaf or leaf-list node in the data tree that 6223 references the typedef. 6225 o Otherwise, the context node is the node in the data tree for which 6226 the "path" statement is defined. 6228 9.9.3. The require-instance Statement 6230 The "require-instance" statement, which is a substatement to the 6231 "type" statement, MAY be present if the type is "instance-identifier" 6232 or "leafref". It takes as an argument the string "true" or "false". 6233 If this statement is not present, it defaults to "true". 6235 If "require-instance" is "true", it means that the instance being 6236 referred MUST exist for the data to be valid. This constraint is 6237 enforced according to the rules in Section 8. 6239 If "require-instance" is "false", it means that the instance being 6240 referred MAY exist in valid data. 6242 9.9.4. Lexical Representation 6244 A leafref value is encoded the same way as the leaf it references. 6246 9.9.5. Canonical Form 6248 The canonical form of a leafref is the same as the canonical form of 6249 the leaf it references. 6251 9.9.6. Usage Example 6253 With the following list: 6255 list interface { 6256 key "name"; 6257 leaf name { 6258 type string; 6259 } 6260 leaf admin-status { 6261 type admin-status; 6262 } 6263 list address { 6264 key "ip"; 6265 leaf ip { 6266 type yang:ip-address; 6267 } 6268 } 6269 } 6271 The following leafref refers to an existing interface: 6273 leaf mgmt-interface { 6274 type leafref { 6275 path "../interface/name"; 6276 } 6277 } 6279 An example of a corresponding XML snippet: 6281 6282 eth0 6283 6284 6285 lo 6286 6288 eth0 6290 The following leafrefs refer to an existing address of an interface: 6292 container default-address { 6293 leaf ifname { 6294 type leafref { 6295 path "../../interface/name"; 6296 } 6297 } 6298 leaf address { 6299 type leafref { 6300 path "../../interface[name = current()/../ifname]" 6301 + "/address/ip"; 6302 } 6303 } 6304 } 6306 An example of a corresponding XML snippet: 6308 6309 eth0 6310 up 6311
6312 192.0.2.1 6313
6314
6315 192.0.2.2 6316
6317 6318 6319 lo 6320 up 6321
6322 127.0.0.1 6323
6324 6326 6327 eth0 6328
192.0.2.2
6329 6331 The following list uses a leafref for one of its keys. This is 6332 similar to a foreign key in a relational database. 6334 list packet-filter { 6335 key "if-name filter-id"; 6336 leaf if-name { 6337 type leafref { 6338 path "/interface/name"; 6339 } 6340 } 6341 leaf filter-id { 6342 type uint32; 6343 } 6344 ... 6345 } 6347 An example of a corresponding XML snippet: 6349 6350 eth0 6351 up 6352
6353 192.0.2.1 6354
6355
6356 192.0.2.2 6357
6358 6360 6361 eth0 6362 1 6363 ... 6364 6365 6366 eth0 6367 2 6368 ... 6369 6371 The following notification defines two leafrefs to refer to an 6372 existing admin-status: 6374 notification link-failure { 6375 leaf if-name { 6376 type leafref { 6377 path "/interface/name"; 6378 } 6379 } 6380 leaf admin-status { 6381 type leafref { 6382 path 6383 "/interface[name = current()/../if-name]" 6384 + "/admin-status"; 6385 } 6386 } 6387 } 6389 An example of a corresponding XML notification: 6391 6393 2008-04-01T00:01:00Z 6394 6395 eth0 6396 up 6397 6398 6400 9.10. The identityref Built-In Type 6402 The identityref type is used to reference an existing identity (see 6403 Section 7.18). 6405 9.10.1. Restrictions 6407 An identityref cannot be restricted. 6409 9.10.2. The identityref's base Statement 6411 The "base" statement, which is a substatement to the "type" 6412 statement, MUST be present at least once if the type is 6413 "identityref". The argument is the name of an identity, as defined 6414 by an "identity" statement. If a prefix is present on the identity 6415 name, it refers to an identity defined in the module that was 6416 imported with that prefix. Otherwise, an identity with the matching 6417 name MUST be defined in the current module or an included submodule. 6419 Valid values for an identityref are any identities derived from all 6420 the identityref's base identities. On a particular server, the valid 6421 values are further restricted to the set of identities defined in the 6422 modules supported by the server. 6424 9.10.3. Lexical Representation 6426 An identityref is encoded as the referred identity's qualified name 6427 as defined in [XML-NAMES]. If the prefix is not present, the 6428 namespace of the identityref is the default namespace in effect on 6429 the element that contains the identityref value. 6431 When an identityref is given a default value using the "default" 6432 statement, the identity name in the default value MAY have a prefix. 6433 If a prefix is present on the identity name, it refers to an identity 6434 defined in the module that was imported with that prefix, or the 6435 prefix for the current module if the identity is defined in the 6436 current module or one of its submodules. Otherwise, an identity with 6437 the matching name MUST be defined in the current module or one of its 6438 submodules. 6440 The string value of a node of type identityref in a "must" or "when" 6441 XPath expression is the referred identity's qualified name with the 6442 prefix present. If the referred identity is defined in an imported 6443 module, the prefix in the string value is the prefix defined in the 6444 corresponding "import" statement. Otherwise, the prefix in the 6445 string value is the prefix for the current module. 6447 9.10.4. Canonical Form 6449 Since the lexical form depends on the XML context in which the value 6450 occurs, this type does not have a canonical form. 6452 9.10.5. Usage Example 6454 With the identity definitions in Section 7.18.3 and the following 6455 module: 6457 module my-crypto { 6458 yang-version 1.1; 6459 namespace "http://example.com/my-crypto"; 6460 prefix mc; 6462 import "crypto-base" { 6463 prefix "crypto"; 6464 } 6466 identity aes { 6467 base "crypto:crypto-alg"; 6468 } 6470 leaf crypto { 6471 type identityref { 6472 base "crypto:crypto-alg"; 6473 } 6474 } 6476 container aes-parameters { 6477 when "../crypto = 'mc:aes'"; 6478 ... 6479 } 6480 } 6482 the following is an example how the leaf "crypto" can be encoded, if 6483 the value is the "des3" identity defined in the "des" module: 6485 des:des3 6487 Any prefixes used in the encoding are local to each instance 6488 encoding. This means that the same identityref may be encoded 6489 differently by different implementations. For example, the following 6490 example encodes the same leaf as above: 6492 x:des3 6494 If the "crypto" leaf's value instead is "aes" defined in the 6495 "my-crypto" module, it can be encoded as: 6497 mc:aes 6499 or, using the default namespace: 6501 aes 6503 9.11. The empty Built-In Type 6505 The empty built-in type represents a leaf that does not have any 6506 value, it conveys information by its presence or absence. 6508 An empty type cannot have a default value. 6510 9.11.1. Restrictions 6512 An empty type cannot be restricted. 6514 9.11.2. Lexical Representation 6516 Not applicable. 6518 9.11.3. Canonical Form 6520 Not applicable. 6522 9.11.4. Usage Example 6524 With the following leaf 6526 leaf enable-qos { 6527 type empty; 6528 } 6530 the following is an example of a valid encoding 6532 6534 if the leaf exists. 6536 9.12. The union Built-In Type 6538 The union built-in type represents a value that corresponds to one of 6539 its member types. 6541 When the type is "union", the "type" statement (Section 7.4) MUST be 6542 present. It is used to repeatedly specify each member type of the 6543 union. It takes as an argument a string that is the name of a member 6544 type. 6546 A member type can be of any built-in or derived type. 6548 A value representing a union data type is validated consecutively 6549 against each member type, in the order they are specified in the 6550 "type" statement, until a match is found. The type that matched will 6551 be the type of the value for the node that was validated. 6553 Any default value or "units" property defined in the member types is 6554 not inherited by the union type. 6556 9.12.1. Restrictions 6558 A union cannot be restricted. However, each member type can be 6559 restricted, based on the rules defined in Section 9. 6561 9.12.2. Lexical Representation 6563 The lexical representation of a union is a value that corresponds to 6564 the representation of any one of the member types. 6566 9.12.3. Canonical Form 6568 The canonical form of a union value is the same as the canonical form 6569 of the member type of the value. 6571 9.12.4. Usage Example 6573 The following is a union of an int32 an enumeration: 6575 type union { 6576 type int32; 6577 type enumeration { 6578 enum "unbounded"; 6579 } 6580 } 6582 Care must be taken when a member type is a leafref where the 6583 "require-instance" property (Section 9.9.3) is "true". If a leaf of 6584 such a type refers to an existing instance, the leaf's value must be 6585 re-validated if the target instance is deleted. For example, with 6586 the following definitions: 6588 list filter { 6589 key name; 6590 leaf name { 6591 type string; 6592 } 6593 ... 6594 } 6596 leaf outbound-filter { 6597 type union { 6598 type leafref { 6599 path "/filter/name"; 6600 } 6601 type enumeration { 6602 enum default-filter; 6603 } 6604 } 6605 } 6607 assume that there exists an entry in the filter list with the name 6608 "http", and that the outbound-filter leaf has this value: 6610 6611 http 6612 6613 http 6615 If the filter entry "http" is removed, the outbound-filter leaf's 6616 value doesn't match the leafref, and the next member type is checked. 6617 The current value ("http") doesn't match the enumeration, so the 6618 resulting configuration is invalid. 6620 If the second member type in the union had been of type "string" 6621 instead of an enumeration, the current value would have matched, and 6622 the resulting configuration would have been valid. 6624 9.13. The instance-identifier Built-In Type 6626 The instance-identifier built-in type is used to uniquely identify a 6627 particular instance node in the data tree. 6629 The syntax for an instance-identifier is a subset of the XPath 6630 abbreviated syntax, formally defined by the rule 6631 "instance-identifier" in Section 13. It is used to uniquely identify 6632 a node in the data tree. Predicates are used only for specifying the 6633 values for the key nodes for list entries, a value of a leaf-list 6634 entry, or a positional index for a list without keys. For 6635 identifying list entries with keys, each predicate consists of one 6636 equality test per key, and each key MUST have a corresponding 6637 predicate. 6639 If the leaf with the instance-identifier type represents 6640 configuration data, and the "require-instance" property 6641 (Section 9.9.3) is "true", the node it refers to MUST also represent 6642 configuration. Such a leaf puts a constraint on valid data. All 6643 such leaf nodes MUST reference existing nodes or leaf or leaf-list 6644 nodes with their default value in use (see Section 7.6.1 and 6645 Section 7.7.2) for the data to be valid. This constraint is enforced 6646 according to the rules in Section 8. 6648 The "instance-identifier" XPath expression is conceptually evaluated 6649 in the following context, in addition to the definition in 6650 Section 6.4.1: 6652 o The context node is the root node in the accessible tree. 6654 9.13.1. Restrictions 6656 An instance-identifier can be restricted with the "require-instance" 6657 statement (Section 9.9.3). 6659 9.13.2. Lexical Representation 6661 An instance-identifier value is lexically represented as a string. 6662 All node names in an instance-identifier value MUST be qualified with 6663 explicit namespace prefixes, and these prefixes MUST be declared in 6664 the XML namespace scope in the instance-identifier's XML element. 6666 Any prefixes used in the encoding are local to each instance 6667 encoding. This means that the same instance-identifier may be 6668 encoded differently by different implementations. 6670 9.13.3. Canonical Form 6672 Since the lexical form depends on the XML context in which the value 6673 occurs, this type does not have a canonical form. 6675 9.13.4. Usage Example 6677 The following are examples of instance identifiers: 6679 /* instance-identifier for a container */ 6680 /ex:system/ex:services/ex:ssh 6682 /* instance-identifier for a leaf */ 6683 /ex:system/ex:services/ex:ssh/ex:port 6685 /* instance-identifier for a list entry */ 6686 /ex:system/ex:user[ex:name='fred'] 6688 /* instance-identifier for a leaf in a list entry */ 6689 /ex:system/ex:user[ex:name='fred']/ex:type 6691 /* instance-identifier for a list entry with two keys */ 6692 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 6694 /* instance-identifier for a leaf-list entry */ 6695 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 6697 /* instance-identifier for a list entry without keys */ 6698 /ex:stats/ex:port[3] 6700 10. XPath Functions 6702 This document defines two generic XPath functions and four YANG type- 6703 specific XPath functions. The function signatures are specified with 6704 the syntax used in [XPATH]. 6706 10.1. Functions for Node Sets 6708 10.1.1. current() 6710 node-set current() 6712 The function current() takes no input parameters, and returns a node 6713 set with the initial context node as its only member. 6715 10.2. Functions for Strings 6717 10.2.1. re-match() 6719 boolean re-match(string subject, string pattern) 6721 The re-match() function returns true if the "subject" string matches 6722 the regular expression "pattern"; otherwise it returns false. 6724 The function "re-match" checks if a string matches a given regular 6725 expression. The regular expressions used are the XML Schema regular 6726 expressions [XSD-TYPES]. Note that this includes implicit anchoring 6727 of the regular expression at the head and tail. 6729 10.2.1.1. Usage Example 6731 The expression: 6733 re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') 6735 returns true. 6737 To count all logical interfaces called eth0., do: 6739 count(/interface[re-match(name, 'eth0\.\d+')]) 6741 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 6743 10.3.1. deref() 6745 node-set deref(node-set nodes) 6747 The deref() function follows the reference defined by the first node 6748 in document order in the argument "nodes", and returns the nodes it 6749 refers to. 6751 If the first argument node is of type instance-identifier, the 6752 function returns a node set that contains the single node that the 6753 instance identifier refers to, if it exists. If no such node exists, 6754 an empty node-set is returned. 6756 If the first argument node is of type leafref, the function returns a 6757 node set that contains the nodes that the leafref refers to. 6759 If the first argument node is of any other type, an empty node set is 6760 returned. 6762 10.3.1.1. Usage Example 6763 list interface { 6764 key name; 6765 leaf name { ... } 6766 leaf enabled { 6767 type boolean; 6768 } 6769 ... 6770 } 6772 leaf mgmt-interface { 6773 type leafref { 6774 path "/interface/name"; 6775 } 6776 must 'deref(.)/../enabled = "true"' { 6777 error-message 6778 "The management interface cannot be disabled."; 6779 } 6780 } 6782 10.4. Functions for the YANG Type "identityref" 6784 10.4.1. derived-from() 6786 boolean derived-from(node-set nodes, 6787 string module-name, 6788 string identity-name) 6790 The derived-from() function returns true if the first node in 6791 document order in the argument "nodes" is a node of type identityref, 6792 and its value is an identity that is derived from the identity 6793 "identity-name" defined in the YANG module "module-name"; otherwise 6794 it returns false. 6796 10.4.2. derived-from-or-self() 6798 boolean derived-from-or-self(node-set nodes, 6799 string module-name, 6800 string identity-name) 6802 The derived-from-or-self() function returns true if the first node in 6803 document order in the argument "nodes" is a node of type identityref, 6804 and its value is an identity that is equal to or derived from the 6805 identity "identity-name" defined in the YANG module "module-name"; 6806 otherwise it returns false. 6808 10.4.2.1. Usage Example 6810 module example-interface { 6811 ... 6813 identity interface-type; 6815 identity ethernet { 6816 base interface-type; 6817 } 6819 identity fast-ethernet { 6820 base ethernet; 6821 } 6823 identity gigabit-ethernet { 6824 base ethernet; 6825 } 6827 list interface { 6828 key name; 6829 ... 6830 leaf type { 6831 type identityref { 6832 base interface-type; 6833 } 6834 } 6835 ... 6836 } 6838 augment "/interface" { 6839 when 'derived-from(type, 6840 "example-interface", 6841 "ethernet")'; 6842 // ethernet-specific definitions here 6843 } 6844 } 6846 10.5. Functions for the YANG Type "enumeration" 6848 10.5.1. enum-value() 6850 number enum-value(node-set nodes) 6852 The enum-value() function checks if the first node in document order 6853 in the argument "nodes" is a node of type enumeration, and returns 6854 the enum's integer value. If the "nodes" node set is empty, or if 6855 the first node in "nodes" is not of type enumeration, it returns NaN. 6857 10.5.1.1. Usage Example 6859 With this data model: 6861 list alarm { 6862 ... 6863 leaf severity { 6864 type enumeration { 6865 enum cleared { 6866 value 1; 6867 } 6868 enum indeterminate { 6869 value 2; 6870 } 6871 enum minor { 6872 value 3; 6873 } 6874 enum warning { 6875 value 4; 6876 } 6877 enum major { 6878 value 5; 6879 } 6880 enum critical { 6881 value 6; 6882 } 6883 } 6884 } 6885 } 6887 the following XPath expression selects only alarms that are of 6888 severity "major" or higher: 6890 /alarm[enum-value(severity) >= 5] 6892 10.6. Functions for the YANG Type "bits" 6894 10.6.1. bit-is-set() 6896 boolean bit-is-set(node-set nodes, string bit-name) 6898 The bit-is-set() function returns true if the first node in document 6899 order in the argument "nodes" is a node of type bits, and its value 6900 has the bit "'bit-name" set; otherwise it returns false. 6902 10.6.1.1. Usage Example 6904 If an interface has this leaf: 6906 leaf flags { 6907 type bits { 6908 bit UP; 6909 bit PROMISCUOUS 6910 bit DISABLED; 6911 } 6912 } 6914 the following XPath expression can be used to select all interfaces 6915 with the UP flag set: 6917 /interface[bit-is-set(flags, "UP")] 6919 11. Updating a Module 6921 As experience is gained with a module, it may be desirable to revise 6922 that module. However, changes are not allowed if they have any 6923 potential to cause interoperability problems between a client using 6924 an original specification and a server using an updated 6925 specification. 6927 For any published change, a new "revision" statement (Section 7.1.9) 6928 MUST be included in front of the existing "revision" statements. If 6929 there are no existing "revision" statements, then one MUST be added 6930 to identify the new revision. Furthermore, any necessary changes 6931 MUST be applied to any meta-data statements, including the 6932 "organization" and "contact" statements (Section 7.1.7, 6933 Section 7.1.8). 6935 Note that definitions contained in a module are available to be 6936 imported by any other module, and are referenced in "import" 6937 statements via the module name. Thus, a module name MUST NOT be 6938 changed. Furthermore, the "namespace" statement MUST NOT be changed, 6939 since all XML elements are qualified by the namespace. 6941 Obsolete definitions MUST NOT be removed from modules since their 6942 identifiers may still be referenced by other modules. 6944 A definition may be revised in any of the following ways: 6946 o An "enumeration" type may have new enums added, provided the old 6947 enums's values do not change. 6949 o A "bits" type may have new bits added, provided the old bit 6950 positions do not change. 6952 o A "range", "length", or "pattern" statement may expand the allowed 6953 value space. 6955 o A "default" statement may be added to a leaf that does not have a 6956 default value (either directly or indirectly through its type). 6958 o A "units" statement may be added. 6960 o A "reference" statement may be added or updated. 6962 o A "must" statement may be removed or its constraint relaxed. 6964 o A "mandatory" statement may be removed or changed from "true" to 6965 "false". 6967 o A "min-elements" statement may be removed, or changed to require 6968 fewer elements. 6970 o A "max-elements" statement may be removed, or changed to allow 6971 more elements. 6973 o A "description" statement may be added or clarified without 6974 changing the semantics of the definition. 6976 o A "base" statement may be added to an "identity" statement. 6978 o A "base" statement may be removed from an "identityref" type, 6979 provided there is at least one "base" statement left. 6981 o New typedefs, groupings, rpcs, notifications, extensions, 6982 features, and identities may be added. 6984 o New data definition statements may be added if they do not add 6985 mandatory nodes (Section 3.1) to existing nodes or at the top 6986 level in a module or submodule, or if they are conditionally 6987 dependent on a new feature (i.e., have an "if-feature" statement 6988 that refers to a new feature). 6990 o A new "case" statement may be added. 6992 o A node that represented state data may be changed to represent 6993 configuration, provided it is not mandatory (Section 3.1). 6995 o An "if-feature" statement may be removed, provided its node is not 6996 mandatory (Section 3.1). 6998 o A "status" statement may be added, or changed from "current" to 6999 "deprecated" or "obsolete", or from "deprecated" to "obsolete". 7001 o A "type" statement may be replaced with another "type" statement 7002 that does not change the syntax or semantics of the type. For 7003 example, an inline type definition may be replaced with a typedef, 7004 but an int8 type cannot be replaced by an int16, since the syntax 7005 would change. 7007 o Any set of data definition nodes may be replaced with another set 7008 of syntactically and semantically equivalent nodes. For example, 7009 a set of leafs may be replaced by a uses of a grouping with the 7010 same leafs. 7012 o A module may be split into a set of submodules, or a submodule may 7013 be removed, provided the definitions in the module do not change 7014 in any other way than allowed here. 7016 o The "prefix" statement may be changed, provided all local uses of 7017 the prefix also are changed. 7019 Otherwise, if the semantics of any previous definition are changed 7020 (i.e., if a non-editorial change is made to any definition other than 7021 those specifically allowed above), then this MUST be achieved by a 7022 new definition with a new identifier. 7024 In statements that have any data definition statements as 7025 substatements, those data definition substatements MUST NOT be 7026 reordered. 7028 12. YIN 7030 A YANG module can be translated into an alternative XML-based syntax 7031 called YIN. The translated module is called a YIN module. This 7032 section describes symmetric mapping rules between the two formats. 7034 The YANG and YIN formats contain equivalent information using 7035 different notations. The YIN notation enables developers to 7036 represent YANG data models in XML and therefore use the rich set of 7037 XML-based tools for data filtering and validation, automated 7038 generation of code and documentation, and other tasks. Tools like 7039 XSLT or XML validators can be utilized. 7041 The mapping between YANG and YIN does not modify the information 7042 content of the model. Comments and whitespace are not preserved. 7044 12.1. Formal YIN Definition 7046 There is a one-to-one correspondence between YANG keywords and YIN 7047 elements. The local name of a YIN element is identical to the 7048 corresponding YANG keyword. This means, in particular, that the 7049 document element (root) of a YIN document is always or 7050 . 7052 YIN elements corresponding to the YANG keywords belong to the 7053 namespace whose associated URI is 7054 "urn:ietf:params:xml:ns:yang:yin:1". 7056 YIN elements corresponding to extension keywords belong to the 7057 namespace of the YANG module where the extension keyword is declared 7058 via the "extension" statement. 7060 The names of all YIN elements MUST be properly qualified with their 7061 namespaces specified above using the standard mechanisms of 7062 [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. 7064 The argument of a YANG statement is represented in YIN either as an 7065 XML attribute or a subelement of the keyword element. Table 1 7066 defines the mapping for the set of YANG keywords. For extensions, 7067 the argument mapping is specified within the "extension" statement 7068 (see Section 7.19). The following rules hold for arguments: 7070 o If the argument is represented as an attribute, this attribute has 7071 no namespace. 7073 o If the argument is represented as an element, it is qualified by 7074 the same namespace as its parent keyword element. 7076 o If the argument is represented as an element, it MUST be the first 7077 child of the keyword element. 7079 Substatements of a YANG statement are represented as (additional) 7080 children of the keyword element and their relative order MUST be the 7081 same as the order of substatements in YANG. 7083 Comments in YANG MAY be mapped to XML comments. 7085 +------------------+---------------+-------------+ 7086 | keyword | argument name | yin-element | 7087 +------------------+---------------+-------------+ 7088 | action | name | false | 7089 | anydata | 7.10 | 0..n | 7090 | anyxml | name | false | 7091 | argument | name | false | 7092 | augment | target-node | false | 7093 | base | name | false | 7094 | belongs-to | module | false | 7095 | bit | name | false | 7096 | case | name | false | 7097 | choice | name | false | 7098 | config | value | false | 7099 | contact | text | true | 7100 | container | name | false | 7101 | default | value | false | 7102 | description | text | true | 7103 | deviate | value | false | 7104 | deviation | target-node | false | 7105 | enum | name | false | 7106 | error-app-tag | value | false | 7107 | error-message | value | true | 7108 | extension | name | false | 7109 | feature | name | false | 7110 | fraction-digits | value | false | 7111 | grouping | name | false | 7112 | identity | name | false | 7113 | if-feature | name | false | 7114 | import | module | false | 7115 | include | module | false | 7116 | input | | n/a | 7117 | key | value | false | 7118 | leaf | name | false | 7119 | leaf-list | name | false | 7120 | length | value | false | 7121 | list | name | false | 7122 | mandatory | value | false | 7123 | max-elements | value | false | 7124 | min-elements | value | false | 7125 | module | name | false | 7126 | must | condition | false | 7127 | namespace | uri | false | 7128 | notification | name | false | 7129 | ordered-by | value | false | 7130 | organization | text | true | 7131 | output | | n/a | 7132 | path | value | false | 7133 | pattern | value | false | 7134 | position | value | false | 7135 | prefix | value | false | 7136 | presence | value | false | 7137 | range | value | false | 7138 | reference | text | true | 7139 | refine | target-node | false | 7140 | require-instance | value | false | 7141 | revision | date | false | 7142 | revision-date | date | false | 7143 | rpc | name | false | 7144 | status | value | false | 7145 | submodule | name | false | 7146 | type | name | false | 7147 | typedef | name | false | 7148 | unique | tag | false | 7149 | units | name | false | 7150 | uses | name | false | 7151 | value | value | false | 7152 | when | condition | false | 7153 | yang-version | value | false | 7154 | yin-element | value | false | 7155 +------------------+---------------+-------------+ 7157 Table 1: Mapping of arguments of the YANG statements. 7159 12.1.1. Usage Example 7161 The following YANG module: 7163 module acme-foo { 7164 yang-version 1.1; 7165 namespace "http://acme.example.com/foo"; 7166 prefix "acfoo"; 7168 import my-extensions { 7169 prefix "myext"; 7170 } 7172 list interface { 7173 key "name"; 7174 leaf name { 7175 type string; 7176 } 7178 leaf mtu { 7179 type uint32; 7180 description "The MTU of the interface."; 7181 myext:c-define "MY_MTU"; 7182 } 7183 } 7184 } 7186 where the extension "c-define" is defined in Section 7.19.3, is 7187 translated into the following YIN: 7189 7194 7195 7197 7198 7199 7201 7202 7203 7204 7205 7206 7207 7208 7209 The MTU of the interface. 7210 7211 7212 7213 7214 7216 13. YANG ABNF Grammar 7218 In YANG, almost all statements are unordered. The ABNF grammar 7219 [RFC5234] [RFC7405] defines the canonical order. To improve module 7220 readability, it is RECOMMENDED that clauses be entered in this order. 7222 Within the ABNF grammar, unordered statements are marked with 7223 comments. 7225 This grammar assumes that the scanner replaces YANG comments with a 7226 single space character. 7228 file "yang.abnf" 7230 module-stmt = optsep module-keyword sep identifier-arg-str 7231 optsep 7232 "{" stmtsep 7233 module-header-stmts 7234 linkage-stmts 7235 meta-stmts 7236 revision-stmts 7237 body-stmts 7238 "}" optsep 7240 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 7241 optsep 7242 "{" stmtsep 7243 submodule-header-stmts 7244 linkage-stmts 7245 meta-stmts 7246 revision-stmts 7247 body-stmts 7248 "}" optsep 7250 module-header-stmts = ;; these stmts can appear in any order 7251 yang-version-stmt 7252 namespace-stmt 7253 prefix-stmt 7255 submodule-header-stmts = 7256 ;; these stmts can appear in any order 7257 yang-version-stmt 7258 belongs-to-stmt 7260 meta-stmts = ;; these stmts can appear in any order 7261 [organization-stmt] 7262 [contact-stmt] 7263 [description-stmt] 7264 [reference-stmt] 7266 linkage-stmts = ;; these stmts can appear in any order 7267 *import-stmt 7268 *include-stmt 7270 revision-stmts = *revision-stmt 7272 body-stmts = *(extension-stmt / 7273 feature-stmt / 7274 identity-stmt / 7275 typedef-stmt / 7276 grouping-stmt / 7277 data-def-stmt / 7278 augment-stmt / 7279 rpc-stmt / 7280 notification-stmt / 7281 deviation-stmt) 7283 data-def-stmt = container-stmt / 7284 leaf-stmt / 7285 leaf-list-stmt / 7286 list-stmt / 7287 choice-stmt / 7288 anydata-stmt / 7289 anyxml-stmt / 7290 uses-stmt 7292 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 7293 stmtend 7295 yang-version-arg-str = < a string that matches the rule > 7296 < yang-version-arg > 7298 yang-version-arg = "1.1" 7300 import-stmt = import-keyword sep identifier-arg-str optsep 7301 "{" stmtsep 7302 prefix-stmt 7303 [revision-date-stmt] 7304 "}" stmtsep 7306 include-stmt = include-keyword sep identifier-arg-str optsep 7307 (";" / 7308 "{" stmtsep 7309 [revision-date-stmt] 7310 "}") stmtsep 7312 namespace-stmt = namespace-keyword sep uri-str stmtend 7314 uri-str = < a string that matches the rule > 7315 < URI in RFC 3986 > 7317 prefix-stmt = prefix-keyword sep prefix-arg-str stmtend 7319 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 7320 optsep 7321 "{" stmtsep 7322 prefix-stmt 7323 "}" stmtsep 7325 organization-stmt = organization-keyword sep string stmtend 7327 contact-stmt = contact-keyword sep string stmtend 7329 description-stmt = description-keyword sep string stmtend 7331 reference-stmt = reference-keyword sep string stmtend 7332 units-stmt = units-keyword sep string stmtend 7334 revision-stmt = revision-keyword sep revision-date optsep 7335 (";" / 7336 "{" stmtsep 7337 ;; these stmts can appear in any order 7338 [description-stmt] 7339 [reference-stmt] 7340 "}") stmtsep 7342 revision-date = date-arg-str 7344 revision-date-stmt = revision-date-keyword sep revision-date stmtend 7346 extension-stmt = extension-keyword sep identifier-arg-str optsep 7347 (";" / 7348 "{" stmtsep 7349 ;; these stmts can appear in any order 7350 [argument-stmt] 7351 [status-stmt] 7352 [description-stmt] 7353 [reference-stmt] 7354 "}") stmtsep 7356 argument-stmt = argument-keyword sep identifier-arg-str optsep 7357 (";" / 7358 "{" stmtsep 7359 [yin-element-stmt] 7360 "}") stmtsep 7362 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 7363 stmtend 7365 yin-element-arg-str = < a string that matches the rule > 7366 < yin-element-arg > 7368 yin-element-arg = true-keyword / false-keyword 7370 identity-stmt = identity-keyword sep identifier-arg-str optsep 7371 (";" / 7372 "{" stmtsep 7373 ;; these stmts can appear in any order 7374 *if-feature-stmt 7375 *base-stmt 7376 [status-stmt] 7377 [description-stmt] 7378 [reference-stmt] 7379 "}") stmtsep 7381 base-stmt = base-keyword sep identifier-ref-arg-str 7382 stmtend 7384 feature-stmt = feature-keyword sep identifier-arg-str optsep 7385 (";" / 7386 "{" stmtsep 7387 ;; these stmts can appear in any order 7388 *if-feature-stmt 7389 [status-stmt] 7390 [description-stmt] 7391 [reference-stmt] 7392 "}") stmtsep 7394 if-feature-stmt = if-feature-keyword sep if-feature-expr-str 7395 stmtend 7397 if-feature-expr-str = < a string that matches the rule > 7398 < if-feature-expr > 7400 if-feature-expr = "(" if-feature-expr ")" / 7401 if-feature-expr sep boolean-operator sep 7402 if-feature-expr / 7403 not-keyword sep if-feature-expr / 7404 identifier-ref-arg 7406 boolean-operator = and-keyword / or-keyword 7408 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 7409 "{" stmtsep 7410 ;; these stmts can appear in any order 7411 type-stmt 7412 [units-stmt] 7413 [default-stmt] 7414 [status-stmt] 7415 [description-stmt] 7416 [reference-stmt] 7417 "}" stmtsep 7419 type-stmt = type-keyword sep identifier-ref-arg-str optsep 7420 (";" / 7421 "{" stmtsep 7422 [type-body-stmts] 7423 "}") stmtsep 7425 type-body-stmts = numerical-restrictions / 7426 decimal64-specification / 7427 string-restrictions / 7428 enum-specification / 7429 leafref-specification / 7430 identityref-specification / 7431 instance-identifier-specification / 7432 bits-specification / 7433 union-specification / 7434 binary-specification 7436 numerical-restrictions = range-stmt 7438 range-stmt = range-keyword sep range-arg-str optsep 7439 (";" / 7440 "{" stmtsep 7441 ;; these stmts can appear in any order 7442 [error-message-stmt] 7443 [error-app-tag-stmt] 7444 [description-stmt] 7445 [reference-stmt] 7446 "}") stmtsep 7448 decimal64-specification = ;; these stmts can appear in any order 7449 fraction-digits-stmt 7450 [range-stmt] 7452 fraction-digits-stmt = fraction-digits-keyword sep 7453 fraction-digits-arg-str stmtend 7455 fraction-digits-arg-str = < a string that matches the rule > 7456 < fraction-digits-arg > 7458 fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / 7459 "5" / "6" / "7" / "8"]) 7460 / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 7462 string-restrictions = ;; these stmts can appear in any order 7463 [length-stmt] 7464 *pattern-stmt 7466 length-stmt = length-keyword sep length-arg-str optsep 7467 (";" / 7468 "{" stmtsep 7469 ;; these stmts can appear in any order 7470 [error-message-stmt] 7471 [error-app-tag-stmt] 7472 [description-stmt] 7473 [reference-stmt] 7474 "}") stmtsep 7476 pattern-stmt = pattern-keyword sep string optsep 7477 (";" / 7478 "{" stmtsep 7479 ;; these stmts can appear in any order 7480 [modifier-stmt] 7481 [error-message-stmt] 7482 [error-app-tag-stmt] 7483 [description-stmt] 7484 [reference-stmt] 7485 "}") stmtsep 7487 modifier-stmt = modifier-keyword sep modifier-arg-str stmtend 7489 modifier-arg-str = < a string that matches the rule > 7490 < modifier-arg > 7492 modifier-arg = invert-match-keyword 7494 default-stmt = default-keyword sep string stmtend 7496 enum-specification = 1*enum-stmt 7498 enum-stmt = enum-keyword sep string optsep 7499 (";" / 7500 "{" stmtsep 7501 ;; these stmts can appear in any order 7502 *if-feature-stmt 7503 [value-stmt] 7504 [status-stmt] 7505 [description-stmt] 7506 [reference-stmt] 7507 "}") stmtsep 7509 leafref-specification = 7510 ;; these stmts can appear in any order 7511 path-stmt 7512 [require-instance-stmt] 7514 path-stmt = path-keyword sep path-arg-str stmtend 7516 require-instance-stmt = require-instance-keyword sep 7517 require-instance-arg-str stmtend 7519 require-instance-arg-str = < a string that matches the rule > 7520 < require-instance-arg > 7522 require-instance-arg = true-keyword / false-keyword 7523 instance-identifier-specification = 7524 [require-instance-stmt] 7526 identityref-specification = 7527 1*base-stmt 7529 union-specification = 1*type-stmt 7531 binary-specification = [length-stmt] 7533 bits-specification = 1*bit-stmt 7535 bit-stmt = bit-keyword sep identifier-arg-str optsep 7536 (";" / 7537 "{" stmtsep 7538 ;; these stmts can appear in any order 7539 *if-feature-stmt 7540 [position-stmt] 7541 [status-stmt] 7542 [description-stmt] 7543 [reference-stmt] 7544 "}") stmtsep 7546 position-stmt = position-keyword sep 7547 position-value-arg-str stmtend 7549 position-value-arg-str = < a string that matches the rule > 7550 < position-value-arg > 7552 position-value-arg = non-negative-integer-value 7554 status-stmt = status-keyword sep status-arg-str stmtend 7556 status-arg-str = < a string that matches the rule > 7557 < status-arg > 7559 status-arg = current-keyword / 7560 obsolete-keyword / 7561 deprecated-keyword 7563 config-stmt = config-keyword sep 7564 config-arg-str stmtend 7566 config-arg-str = < a string that matches the rule > 7567 < config-arg > 7569 config-arg = true-keyword / false-keyword 7570 mandatory-stmt = mandatory-keyword sep 7571 mandatory-arg-str stmtend 7573 mandatory-arg-str = < a string that matches the rule > 7574 < mandatory-arg > 7576 mandatory-arg = true-keyword / false-keyword 7578 presence-stmt = presence-keyword sep string stmtend 7580 ordered-by-stmt = ordered-by-keyword sep 7581 ordered-by-arg-str stmtend 7583 ordered-by-arg-str = < a string that matches the rule > 7584 < ordered-by-arg > 7586 ordered-by-arg = user-keyword / system-keyword 7588 must-stmt = must-keyword sep string optsep 7589 (";" / 7590 "{" stmtsep 7591 ;; these stmts can appear in any order 7592 [error-message-stmt] 7593 [error-app-tag-stmt] 7594 [description-stmt] 7595 [reference-stmt] 7596 "}") stmtsep 7598 error-message-stmt = error-message-keyword sep string stmtend 7600 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 7602 min-elements-stmt = min-elements-keyword sep 7603 min-value-arg-str stmtend 7605 min-value-arg-str = < a string that matches the rule > 7606 < min-value-arg > 7608 min-value-arg = non-negative-integer-value 7610 max-elements-stmt = max-elements-keyword sep 7611 max-value-arg-str stmtend 7613 max-value-arg-str = < a string that matches the rule > 7614 < max-value-arg > 7616 max-value-arg = unbounded-keyword / 7617 positive-integer-value 7619 value-stmt = value-keyword sep integer-value-str stmtend 7621 integer-value-str = < a string that matches the rule > 7622 < integer-value > 7624 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 7625 (";" / 7626 "{" stmtsep 7627 ;; these stmts can appear in any order 7628 [status-stmt] 7629 [description-stmt] 7630 [reference-stmt] 7631 *(typedef-stmt / grouping-stmt) 7632 *data-def-stmt 7633 *action-stmt 7634 *notification-stmt 7635 "}") stmtsep 7637 container-stmt = container-keyword sep identifier-arg-str optsep 7638 (";" / 7639 "{" stmtsep 7640 ;; these stmts can appear in any order 7641 [when-stmt] 7642 *if-feature-stmt 7643 *must-stmt 7644 [presence-stmt] 7645 [config-stmt] 7646 [status-stmt] 7647 [description-stmt] 7648 [reference-stmt] 7649 *(typedef-stmt / grouping-stmt) 7650 *data-def-stmt 7651 *action-stmt 7652 *notification-stmt 7653 "}") stmtsep 7655 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 7656 "{" stmtsep 7657 ;; these stmts can appear in any order 7658 [when-stmt] 7659 *if-feature-stmt 7660 type-stmt 7661 [units-stmt] 7662 *must-stmt 7663 [default-stmt] 7664 [config-stmt] 7665 [mandatory-stmt] 7666 [status-stmt] 7668 [description-stmt] 7669 [reference-stmt] 7670 "}" stmtsep 7672 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 7673 "{" stmtsep 7674 ;; these stmts can appear in any order 7675 [when-stmt] 7676 *if-feature-stmt 7677 type-stmt stmtsep 7678 [units-stmt] 7679 *must-stmt 7680 *default-stmt 7681 [config-stmt] 7682 [min-elements-stmt] 7683 [max-elements-stmt] 7684 [ordered-by-stmt] 7685 [status-stmt] 7686 [description-stmt] 7687 [reference-stmt] 7688 "}" stmtsep 7690 list-stmt = list-keyword sep identifier-arg-str optsep 7691 "{" stmtsep 7692 ;; these stmts can appear in any order 7693 [when-stmt] 7694 *if-feature-stmt 7695 *must-stmt 7696 [key-stmt] 7697 *unique-stmt 7698 [config-stmt] 7699 [min-elements-stmt] 7700 [max-elements-stmt] 7701 [ordered-by-stmt] 7702 [status-stmt] 7703 [description-stmt] 7704 [reference-stmt] 7705 *(typedef-stmt / grouping-stmt) 7706 1*data-def-stmt 7707 *action-stmt 7708 *notification-stmt 7709 "}" stmtsep 7711 key-stmt = key-keyword sep key-arg-str stmtend 7713 key-arg-str = < a string that matches the rule > 7714 < key-arg > 7716 key-arg = node-identifier *(sep node-identifier) 7718 unique-stmt = unique-keyword sep unique-arg-str stmtend 7720 unique-arg-str = < a string that matches the rule > 7721 < unique-arg > 7723 unique-arg = descendant-schema-nodeid 7724 *(sep descendant-schema-nodeid) 7726 choice-stmt = choice-keyword sep identifier-arg-str optsep 7727 (";" / 7728 "{" stmtsep 7729 ;; these stmts can appear in any order 7730 [when-stmt] 7731 *if-feature-stmt 7732 [default-stmt] 7733 [config-stmt] 7734 [mandatory-stmt] 7735 [status-stmt] 7736 [description-stmt] 7737 [reference-stmt] 7738 *(short-case-stmt / case-stmt) 7739 "}") stmtsep 7741 short-case-stmt = choice-stmt / 7742 container-stmt / 7743 leaf-stmt / 7744 leaf-list-stmt / 7745 list-stmt / 7746 anydata-stmt / 7747 anyxml-stmt 7749 case-stmt = case-keyword sep identifier-arg-str optsep 7750 (";" / 7751 "{" stmtsep 7752 ;; these stmts can appear in any order 7753 [when-stmt] 7754 *if-feature-stmt 7755 [status-stmt] 7756 [description-stmt] 7757 [reference-stmt] 7758 *data-def-stmt 7759 "}") stmtsep 7761 anydata-stmt = anydata-keyword sep identifier-arg-str optsep 7762 (";" / 7763 "{" stmtsep 7764 ;; these stmts can appear in any order 7765 [when-stmt] 7766 *if-feature-stmt 7767 *must-stmt 7768 [config-stmt] 7769 [mandatory-stmt] 7770 [status-stmt] 7771 [description-stmt] 7772 [reference-stmt] 7773 "}") stmtsep 7775 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 7776 (";" / 7777 "{" stmtsep 7778 ;; these stmts can appear in any order 7779 [when-stmt] 7780 *if-feature-stmt 7781 *must-stmt 7782 [config-stmt] 7783 [mandatory-stmt] 7784 [status-stmt] 7785 [description-stmt] 7786 [reference-stmt] 7787 "}") stmtsep 7789 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 7790 (";" / 7791 "{" stmtsep 7792 ;; these stmts can appear in any order 7793 [when-stmt] 7794 *if-feature-stmt 7795 [status-stmt] 7796 [description-stmt] 7797 [reference-stmt] 7798 *refine-stmt 7799 *uses-augment-stmt 7800 "}") stmtsep 7802 refine-stmt = refine-keyword sep refine-arg-str optsep 7803 "{" stmtsep 7804 ;; these stmts can appear in any order 7805 *if-feature-stmt 7806 *must-stmt 7807 [presence-stmt] 7808 [default-stmt] 7809 [config-stmt] 7810 [mandatory-stmt] 7811 [min-elements-stmt] 7813 [max-elements-stmt] 7814 [description-stmt] 7815 [reference-stmt] 7816 "}" stmtsep 7818 refine-arg-str = < a string that matches the rule > 7819 < refine-arg > 7821 refine-arg = descendant-schema-nodeid 7823 uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep 7824 "{" stmtsep 7825 ;; these stmts can appear in any order 7826 [when-stmt] 7827 *if-feature-stmt 7828 [status-stmt] 7829 [description-stmt] 7830 [reference-stmt] 7831 1*(data-def-stmt / case-stmt / 7832 action-stmt / notification-stmt) 7833 "}" stmtsep 7835 uses-augment-arg-str = < a string that matches the rule > 7836 < uses-augment-arg > 7838 uses-augment-arg = descendant-schema-nodeid 7840 augment-stmt = augment-keyword sep augment-arg-str optsep 7841 "{" stmtsep 7842 ;; these stmts can appear in any order 7843 [when-stmt] 7844 *if-feature-stmt 7845 [status-stmt] 7846 [description-stmt] 7847 [reference-stmt] 7848 1*(data-def-stmt / case-stmt / 7849 action-stmt / notification-stmt) 7850 "}" stmtsep 7852 augment-arg-str = < a string that matches the rule > 7853 < augment-arg > 7855 augment-arg = absolute-schema-nodeid 7857 when-stmt = when-keyword sep string optsep 7858 (";" / 7859 "{" stmtsep 7860 ;; these stmts can appear in any order 7862 [description-stmt] 7863 [reference-stmt] 7864 "}") stmtsep 7866 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 7867 (";" / 7868 "{" stmtsep 7869 ;; these stmts can appear in any order 7870 *if-feature-stmt 7871 [status-stmt] 7872 [description-stmt] 7873 [reference-stmt] 7874 *(typedef-stmt / grouping-stmt) 7875 [input-stmt] 7876 [output-stmt] 7877 "}") stmtsep 7879 action-stmt = action-keyword sep identifier-arg-str optsep 7880 (";" / 7881 "{" stmtsep 7882 ;; these stmts can appear in any order 7883 *if-feature-stmt 7884 [status-stmt] 7885 [description-stmt] 7886 [reference-stmt] 7887 *(typedef-stmt / grouping-stmt) 7888 [input-stmt] 7889 [output-stmt] 7890 "}") stmtsep 7892 input-stmt = input-keyword optsep 7893 "{" stmtsep 7894 ;; these stmts can appear in any order 7895 *must-stmt 7896 *(typedef-stmt / grouping-stmt) 7897 1*data-def-stmt 7898 "}" stmtsep 7900 output-stmt = output-keyword optsep 7901 "{" stmtsep 7902 ;; these stmts can appear in any order 7903 *must-stmt 7904 *(typedef-stmt / grouping-stmt) 7905 1*data-def-stmt 7906 "}" stmtsep 7908 notification-stmt = notification-keyword sep 7909 identifier-arg-str optsep 7910 (";" / 7911 "{" stmtsep 7912 ;; these stmts can appear in any order 7913 *if-feature-stmt 7914 *must-stmt 7915 [status-stmt] 7916 [description-stmt] 7917 [reference-stmt] 7918 *(typedef-stmt / grouping-stmt) 7919 *data-def-stmt 7920 "}") stmtsep 7922 deviation-stmt = deviation-keyword sep 7923 deviation-arg-str optsep 7924 "{" stmtsep 7925 ;; these stmts can appear in any order 7926 [description-stmt] 7927 [reference-stmt] 7928 (deviate-not-supported-stmt / 7929 1*(deviate-add-stmt / 7930 deviate-replace-stmt / 7931 deviate-delete-stmt)) 7932 "}" stmtsep 7934 deviation-arg-str = < a string that matches the rule > 7935 < deviation-arg > 7937 deviation-arg = absolute-schema-nodeid 7939 deviate-not-supported-stmt = 7940 deviate-keyword sep 7941 not-supported-keyword-str stmtend 7943 deviate-add-stmt = deviate-keyword sep add-keyword-str optsep 7944 (";" / 7945 "{" stmtsep 7946 ;; these stmts can appear in any order 7947 [units-stmt] 7948 *must-stmt 7949 *unique-stmt 7950 [default-stmt] 7951 [config-stmt] 7952 [mandatory-stmt] 7953 [min-elements-stmt] 7954 [max-elements-stmt] 7955 "}") stmtsep 7957 deviate-delete-stmt = deviate-keyword sep delete-keyword-str optsep 7958 (";" / 7959 "{" stmtsep 7960 ;; these stmts can appear in any order 7961 [units-stmt] 7962 *must-stmt 7963 *unique-stmt 7964 [default-stmt] 7965 "}") stmtsep 7967 deviate-replace-stmt = deviate-keyword sep replace-keyword-str optsep 7968 (";" / 7969 "{" stmtsep 7970 ;; these stmts can appear in any order 7971 [type-stmt] 7972 [units-stmt] 7973 [default-stmt] 7974 [config-stmt] 7975 [mandatory-stmt] 7976 [min-elements-stmt] 7977 [max-elements-stmt] 7978 "}") stmtsep 7980 not-supported-keyword-str = < a string that matches the rule > 7981 < not-supported-keyword > 7983 add-keyword-str = < a string that matches the rule > 7984 < add-keyword > 7986 delete-keyword-str = < a string that matches the rule > 7987 < delete-keyword > 7989 replace-keyword-str = < a string that matches the rule > 7990 < replace-keyword > 7992 ;; represents the usage of an extension statement 7993 unknown-statement = prefix ":" identifier [sep string] optsep 7994 (";" / 7995 "{" optsep 7996 *((yang-stmt / unknown-statement) optsep) 7997 "}") stmtsep 7999 yang-stmt = action-stmt / 8000 anydata-stmt / 8001 anyxml-stmt / 8002 argument-stmt / 8003 augment-stmt / 8004 base-stmt / 8005 belongs-to-stmt / 8006 bit-stmt / 8007 case-stmt / 8008 choice-stmt / 8009 config-stmt / 8010 contact-stmt / 8011 container-stmt / 8012 default-stmt / 8013 description-stmt / 8014 deviate-add-stmt / 8015 deviate-delete-stmt / 8016 deviate-not-supported-stmt / 8017 deviate-replace-stmt / 8018 deviation-stmt / 8019 enum-stmt / 8020 error-app-tag-stmt / 8021 error-message-stmt / 8022 extension-stmt / 8023 feature-stmt / 8024 fraction-digits-stmt / 8025 grouping-stmt / 8026 identity-stmt / 8027 if-feature-stmt / 8028 import-stmt / 8029 include-stmt / 8030 input-stmt / 8031 key-stmt / 8032 leaf-list-stmt / 8033 leaf-stmt / 8034 length-stmt / 8035 list-stmt / 8036 mandatory-stmt / 8037 max-elements-stmt / 8038 min-elements-stmt / 8039 modifier-stmt / 8040 module-stmt / 8041 must-stmt / 8042 namespace-stmt / 8043 notification-stmt / 8044 ordered-by-stmt / 8045 organization-stmt / 8046 output-stmt / 8047 path-stmt / 8048 pattern-stmt / 8049 position-stmt / 8050 prefix-stmt / 8051 presence-stmt / 8052 range-stmt / 8053 reference-stmt / 8054 refine-stmt / 8055 require-instance-stmt / 8056 revision-date-stmt / 8057 revision-stmt / 8058 rpc-stmt / 8059 status-stmt / 8060 submodule-stmt / 8061 typedef-stmt / 8062 type-stmt / 8063 unique-stmt / 8064 units-stmt / 8065 uses-augment-stmt / 8066 uses-stmt / 8067 value-stmt / 8068 when-stmt / 8069 yang-version-stmt / 8070 yin-element-stmt 8072 ;; Ranges 8074 range-arg-str = < a string that matches the rule > 8075 < range-arg > 8077 range-arg = range-part *(optsep "|" optsep range-part) 8079 range-part = range-boundary 8080 [optsep ".." optsep range-boundary] 8082 range-boundary = min-keyword / max-keyword / 8083 integer-value / decimal-value 8085 ;; Lengths 8087 length-arg-str = < a string that matches the rule > 8088 < length-arg > 8090 length-arg = length-part *(optsep "|" optsep length-part) 8092 length-part = length-boundary 8093 [optsep ".." optsep length-boundary] 8095 length-boundary = min-keyword / max-keyword / 8096 non-negative-integer-value 8098 ;; Date 8100 date-arg-str = < a string that matches the rule > 8101 < date-arg > 8103 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 8105 ;; Schema Node Identifiers 8107 schema-nodeid = absolute-schema-nodeid / 8108 descendant-schema-nodeid 8110 absolute-schema-nodeid = 1*("/" node-identifier) 8112 descendant-schema-nodeid = 8113 node-identifier 8114 [absolute-schema-nodeid] 8116 node-identifier = [prefix ":"] identifier 8118 ;; Instance Identifiers 8120 instance-identifier = 1*("/" (node-identifier *predicate)) 8122 predicate = "[" *WSP (predicate-expr / pos) *WSP "]" 8124 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 8125 ((DQUOTE string DQUOTE) / 8126 (SQUOTE string SQUOTE)) 8128 pos = non-negative-integer-value 8130 ;; leafref path 8132 path-arg-str = < a string that matches the rule > 8133 < path-arg > 8135 path-arg = absolute-path / relative-path 8137 absolute-path = 1*("/" (node-identifier *path-predicate)) 8139 relative-path = 1*(".." "/") descendant-path 8141 descendant-path = node-identifier 8142 [*path-predicate absolute-path] 8144 path-predicate = "[" *WSP path-equality-expr *WSP "]" 8146 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 8148 path-key-expr = current-function-invocation *WSP "/" *WSP 8149 rel-path-keyexpr 8151 rel-path-keyexpr = 1*(".." *WSP "/" *WSP) 8152 *(node-identifier *WSP "/" *WSP) 8153 node-identifier 8155 ;;; Keywords, using RFC 7405 syntax for case-sensitive strings 8157 ;; statement keywords 8158 action-keyword = %s"action" 8159 anydata-keyword = %s"anydata" 8160 anyxml-keyword = %s"anyxml" 8161 argument-keyword = %s"argument" 8162 augment-keyword = %s"augment" 8163 base-keyword = %s"base" 8164 belongs-to-keyword = %s"belongs-to" 8165 bit-keyword = %s"bit" 8166 case-keyword = %s"case" 8167 choice-keyword = %s"choice" 8168 config-keyword = %s"config" 8169 contact-keyword = %s"contact" 8170 container-keyword = %s"container" 8171 default-keyword = %s"default" 8172 description-keyword = %s"description" 8173 enum-keyword = %s"enum" 8174 error-app-tag-keyword = %s"error-app-tag" 8175 error-message-keyword = %s"error-message" 8176 extension-keyword = %s"extension" 8177 deviation-keyword = %s"deviation" 8178 deviate-keyword = %s"deviate" 8179 feature-keyword = %s"feature" 8180 fraction-digits-keyword = %s"fraction-digits" 8181 grouping-keyword = %s"grouping" 8182 identity-keyword = %s"identity" 8183 if-feature-keyword = %s"if-feature" 8184 import-keyword = %s"import" 8185 include-keyword = %s"include" 8186 input-keyword = %s"input" 8187 key-keyword = %s"key" 8188 leaf-keyword = %s"leaf" 8189 leaf-list-keyword = %s"leaf-list" 8190 length-keyword = %s"length" 8191 list-keyword = %s"list" 8192 mandatory-keyword = %s"mandatory" 8193 max-elements-keyword = %s"max-elements" 8194 min-elements-keyword = %s"min-elements" 8195 modifier-keyword = %s"modifier" 8196 module-keyword = %s"module" 8197 must-keyword = %s"must" 8198 namespace-keyword = %s"namespace" 8199 notification-keyword= %s"notification" 8200 ordered-by-keyword = %s"ordered-by" 8201 organization-keyword= %s"organization" 8202 output-keyword = %s"output" 8203 path-keyword = %s"path" 8204 pattern-keyword = %s"pattern" 8205 position-keyword = %s"position" 8206 prefix-keyword = %s"prefix" 8207 presence-keyword = %s"presence" 8208 range-keyword = %s"range" 8209 reference-keyword = %s"reference" 8210 refine-keyword = %s"refine" 8211 require-instance-keyword = %s"require-instance" 8212 revision-keyword = %s"revision" 8213 revision-date-keyword = %s"revision-date" 8214 rpc-keyword = %s"rpc" 8215 status-keyword = %s"status" 8216 submodule-keyword = %s"submodule" 8217 type-keyword = %s"type" 8218 typedef-keyword = %s"typedef" 8219 unique-keyword = %s"unique" 8220 units-keyword = %s"units" 8221 uses-keyword = %s"uses" 8222 value-keyword = %s"value" 8223 when-keyword = %s"when" 8224 yang-version-keyword= %s"yang-version" 8225 yin-element-keyword = %s"yin-element" 8227 ;; other keywords 8229 add-keyword = %s"add" 8230 current-keyword = %s"current" 8231 delete-keyword = %s"delete" 8232 deprecated-keyword = %s"deprecated" 8233 false-keyword = %s"false" 8234 invert-match-keyword = %s"invert-match" 8235 max-keyword = %s"max" 8236 min-keyword = %s"min" 8237 not-supported-keyword = %s"not-supported" 8238 obsolete-keyword = %s"obsolete" 8239 replace-keyword = %s"replace" 8240 system-keyword = %s"system" 8241 true-keyword = %s"true" 8242 unbounded-keyword = %s"unbounded" 8243 user-keyword = %s"user" 8244 and-keyword = %s"and" 8245 or-keyword = %s"or" 8246 not-keyword = %s"not" 8248 current-function-invocation = current-keyword *WSP "(" *WSP ")" 8250 ;;; Basic Rules 8252 prefix-arg-str = < a string that matches the rule > 8253 < prefix-arg > 8255 prefix-arg = prefix 8257 prefix = identifier 8259 identifier-arg-str = < a string that matches the rule > 8260 < identifier-arg > 8262 identifier-arg = identifier 8264 ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) 8265 identifier = (ALPHA / "_") 8266 *(ALPHA / DIGIT / "_" / "-" / ".") 8268 identifier-ref-arg-str = < a string that matches the rule > 8269 < identifier-ref-arg > 8271 identifier-ref-arg = identifier-ref 8273 identifier-ref = [prefix ":"] identifier 8275 string = < an unquoted string as returned by > 8276 < the scanner, that matches the rule > 8277 < yang-string > 8279 yang-string = *yang-char 8281 ;; any Unicode character including tab, carriage return, and line 8282 ;; feed, but excluding the other C0 control characters, the surrogate 8283 ;; blocks, and the noncharacters. 8284 yang-char = %x9 / %xA / %xD / %x20-D7FF / 8285 ; exclude surrogate blocks %xD800-DFFF 8286 %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF 8287 %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF 8288 %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF 8289 %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF 8290 %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF 8291 %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF 8292 %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF 8293 %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF 8294 %x70000-7FFFD / ; exclude noncharacters %x7FFFE-7FFFF 8295 %x80000-8FFFD / ; exclude noncharacters %x8FFFE-8FFFF 8296 %x90000-9FFFD / ; exclude noncharacters %x9FFFE-9FFFF 8297 %xA0000-AFFFD / ; exclude noncharacters %xAFFFE-AFFFF 8298 %xB0000-BFFFD / ; exclude noncharacters %xBFFFE-BFFFF 8299 %xC0000-CFFFD / ; exclude noncharacters %xCFFFE-CFFFF 8300 %xD0000-DFFFD / ; exclude noncharacters %xDFFFE-DFFFF 8301 %xE0000-EFFFD / ; exclude noncharacters %xEFFFE-EFFFF 8302 %xF0000-FFFFD / ; exclude noncharacters %xFFFFE-FFFFF 8303 %x100000-10FFFD ; exclude noncharacters %x10FFFE-10FFFF 8305 integer-value = ("-" non-negative-integer-value) / 8306 non-negative-integer-value 8308 non-negative-integer-value = "0" / positive-integer-value 8310 positive-integer-value = (non-zero-digit *DIGIT) 8312 zero-integer-value = 1*DIGIT 8314 stmtend = optsep (";" / "{" stmtsep "}") stmtsep 8316 sep = 1*(WSP / line-break) 8317 ; unconditional separator 8319 optsep = *(WSP / line-break) 8321 stmtsep = *(WSP / line-break / unknown-statement) 8323 line-break = CRLF / LF 8325 non-zero-digit = %x31-39 8327 decimal-value = integer-value ("." zero-integer-value) 8329 SQUOTE = %x27 8330 ; ' (Single Quote) 8332 ;;; RFC 5234 core rules. 8334 ALPHA = %x41-5A / %x61-7A 8335 ; A-Z / a-z 8337 CR = %x0D 8338 ; carriage return 8340 CRLF = CR LF 8341 ; Internet standard new line 8343 DIGIT = %x30-39 8344 ; 0-9 8346 DQUOTE = %x22 8347 ; double quote 8349 HEXDIG = DIGIT / 8350 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 8351 ; only lower-case a..f 8353 HTAB = %x09 8354 ; horizontal tab 8356 LF = %x0A 8357 ; linefeed 8359 SP = %x20 8360 ; space 8362 VCHAR = %x21-7E 8363 ; visible (printing) characters 8365 WSP = SP / HTAB 8366 ; whitespace 8368 8370 14. Error Responses for YANG Related Errors 8372 A number of NETCONF error responses are defined for error cases 8373 related to the data-model handling. If the relevant YANG statement 8374 has an "error-app-tag" substatement, that overrides the default value 8375 specified below. 8377 14.1. Error Message for Data That Violates a unique Statement 8379 If a NETCONF operation would result in configuration data where a 8380 unique constraint is invalidated, the following error is returned: 8382 error-tag: operation-failed 8383 error-app-tag: data-not-unique 8384 error-info: : Contains an instance identifier that 8385 points to a leaf that invalidates the unique 8386 constraint. This element is present once for each 8387 non-unique leaf. 8389 The element is in the YANG 8390 namespace ("urn:ietf:params:xml:ns:yang:1"). 8392 14.2. Error Message for Data That Violates a max-elements Statement 8394 If a NETCONF operation would result in configuration data where a 8395 list or a leaf-list would have too many entries the following error 8396 is returned: 8398 error-tag: operation-failed 8399 error-app-tag: too-many-elements 8401 This error is returned once, with the error-path identifying the list 8402 node, even if there are more than one extra child present. 8404 14.3. Error Message for Data That Violates a min-elements Statement 8406 If a NETCONF operation would result in configuration data where a 8407 list or a leaf-list would have too few entries the following error is 8408 returned: 8410 error-tag: operation-failed 8411 error-app-tag: too-few-elements 8413 This error is returned once, with the error-path identifying the list 8414 node, even if there are more than one child missing. 8416 14.4. Error Message for Data That Violates a must Statement 8418 If a NETCONF operation would result in configuration data where the 8419 restrictions imposed by a "must" statement is violated the following 8420 error is returned, unless a specific "error-app-tag" substatement is 8421 present for the "must" statement. 8423 error-tag: operation-failed 8424 error-app-tag: must-violation 8426 14.5. Error Message for Data That Violates a require-instance Statement 8428 If a NETCONF operation would result in configuration data where a 8429 leaf of type "instance-identifier" or "leafref" marked with require- 8430 instance "true" refers to a non-existing instance, the following 8431 error is returned: 8433 error-tag: data-missing 8434 error-app-tag: instance-required 8435 error-path: Path to the instance-identifier or leafref leaf. 8437 14.6. Error Message for Data That Does Not Match a leafref Type 8439 If a NETCONF operation would result in configuration data where a 8440 leaf of type "leafref" refers to a non-existing instance, the 8441 following error is returned: 8443 error-tag: data-missing 8444 error-app-tag: instance-required 8445 error-path: Path to the leafref leaf. 8447 14.7. Error Message for Data That Violates a mandatory choice Statement 8449 If a NETCONF operation would result in configuration data where no 8450 nodes exists in a mandatory choice, the following error is returned: 8452 error-tag: data-missing 8453 error-app-tag: missing-choice 8454 error-path: Path to the element with the missing choice. 8455 error-info: : Contains the name of the missing 8456 mandatory choice. 8458 The element is in the YANG 8459 namespace ("urn:ietf:params:xml:ns:yang:1"). 8461 14.8. Error Message for the "insert" Operation 8463 If the "insert" and "key" or "value" attributes are used in an 8464 for a list or leaf-list node, and the "key" or "value" 8465 refers to a non-existing instance, the following error is returned: 8467 error-tag: bad-attribute 8468 error-app-tag: missing-instance 8470 15. IANA Considerations 8472 This document defines a registry for YANG module and submodule names. 8473 The name of the registry is "YANG Module Names". 8475 The registry shall record for each entry: 8477 o the name of the module or submodule 8479 o for modules, the assigned XML namespace 8481 o for modules, the prefix of the module 8483 o for submodules, the name of the module it belongs to 8485 o a reference to the (sub)module's documentation (e.g., the RFC 8486 number) 8488 There are no initial assignments. 8490 For allocation, RFC publication is required as per RFC 5226 8491 [RFC5226]. All registered YANG module names MUST comply with the 8492 rules for identifiers stated in Section 6.2, and MUST have a module 8493 name prefix. 8495 The module name prefix 'ietf-' is reserved for IETF stream documents 8496 [RFC4844], while the module name prefix 'irtf-' is reserved for IRTF 8497 stream documents. Modules published in other RFC streams MUST have a 8498 similar suitable prefix. 8500 All module and submodule names in the registry MUST be unique. 8502 All XML namespaces in the registry MUST be unique. 8504 This document registers two URIs for the YANG and YIN XML namespaces 8505 in the IETF XML registry [RFC3688]. Following the format in RFC 8506 3688, the following have been registered. 8508 URI: urn:ietf:params:xml:ns:yang:yin:1 8509 URI: urn:ietf:params:xml:ns:yang:1 8511 Registrant Contact: The IESG. 8513 XML: N/A, the requested URIs are XML namespaces. 8515 This document registers one capability identifier URN from the 8516 "Network Configuration Protocol (NETCONF) Capability URNs" registry: 8518 urn:ietf:params:netconf:capability:yang-library:1.0 8520 This document registers two new media types as defined in the 8521 following sections. 8523 15.1. Media type application/yang 8525 MIME media type name: application 8527 MIME subtype name: yang 8529 Mandatory parameters: none 8531 Optional parameters: none 8533 Encoding considerations: 8-bit 8535 Security considerations: See Section 15 in RFC XXXX 8537 Interoperability considerations: None 8539 Published specification: RFC XXXX 8541 Applications that use this media type: 8543 YANG module validators, web servers used for downloading YANG 8544 modules, email clients, etc. 8546 Additional information: 8548 Magic Number: None 8550 File Extension: .yang 8552 Macintosh file type code: 'TEXT' 8554 Personal and email address for further information: 8555 Martin Bjorklund 8557 Intended usage: COMMON 8559 Author: 8560 This specification is a work item of the IETF NETMOD working 8561 group, with mailing list address . 8563 Change controller: 8564 The IESG 8566 15.2. Media type application/yin+xml 8567 MIME media type name: application 8569 MIME subtype name: yin+xml 8571 Mandatory parameters: none 8573 Optional parameters: 8575 "charset": This parameter has identical semantics to the 8576 charset parameter of the "application/xml" media type as 8577 specified in [RFC3023]. 8579 Encoding considerations: 8581 Identical to those of "application/xml" as 8582 described in [RFC3023], Section 3.2. 8584 Security considerations: See Section 15 in RFC XXXX 8586 Interoperability considerations: None 8588 Published specification: RFC XXXX 8590 Applications that use this media type: 8592 YANG module validators, web servers used for downloading YANG 8593 modules, email clients, etc. 8595 Additional information: 8597 Magic Number: As specified for "application/xml" in [RFC3023], 8598 Section 3.2. 8600 File Extension: .yin 8602 Macintosh file type code: 'TEXT' 8604 Personal and email address for further information: 8605 Martin Bjorklund 8607 Intended usage: COMMON 8609 Author: 8610 This specification is a work item of the IETF NETMOD working 8611 group, with mailing list address . 8613 Change controller: 8614 The IESG 8616 16. Security Considerations 8618 This document defines a language with which to write and read 8619 descriptions of management information. The language itself has no 8620 security impact on the Internet. 8622 The same considerations are relevant as for the base NETCONF protocol 8623 (see [RFC6241], Section 9). 8625 Data modeled in YANG might contain sensitive information. RPCs or 8626 notifications defined in YANG might transfer sensitive information. 8628 Security issues are related to the usage of data modeled in YANG. 8629 Such issues shall be dealt with in documents describing the data 8630 models and documents about the interfaces used to manipulate the data 8631 e.g., the NETCONF documents. 8633 Data modeled in YANG is dependent upon: 8635 o the security of the transmission infrastructure used to send 8636 sensitive information. 8638 o the security of applications that store or release such sensitive 8639 information. 8641 o adequate authentication and access control mechanisms to restrict 8642 the usage of sensitive data. 8644 YANG parsers need to be robust with respect to malformed documents. 8645 Reading malformed documents from unknown or untrusted sources could 8646 result in an attacker gaining privileges of the user running the YANG 8647 parser. In an extreme situation, the entire machine could be 8648 compromised. 8650 17. Contributors 8652 The following people all contributed significantly to the initial 8653 YANG document: 8655 - Andy Bierman (Brocade) 8656 - Balazs Lengyel (Ericsson) 8657 - David Partain (Ericsson) 8658 - Juergen Schoenwaelder (Jacobs University Bremen) 8659 - Phil Shafer (Juniper Networks) 8661 18. Acknowledgements 8663 The editor wishes to thank the following individuals, who all 8664 provided helpful comments on various versions of this document: 8665 Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav 8666 Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert 8667 Wijnen. 8669 19. ChangeLog 8671 RFC Editor: remove this section upon publication as an RFC. 8673 19.1. Version -06 8675 o Included solution Y45-05. 8677 19.2. Version -05 8679 o Included solution Y18-01. 8681 o Included solution Y25-02 (parts of it was included in -04). 8683 o Included solution Y34-05. 8685 o Included solution Y36-03. 8687 19.3. Version -04 8689 o Incorporated changes to ABNF grammar after review and errata for 8690 RFC 6020. 8692 o Included solution Y16-03. 8694 o Included solution Y49-04. 8696 o Included solution Y58-01. 8698 o Included solution Y59-01. 8700 19.4. Version -03 8702 o Incorporated changes from WG reviews. 8704 o Included solution Y05-01. 8706 o Included solution Y10-01. 8708 o Included solution Y13-01. 8710 o Included solution Y28-02. 8712 o Included solution Y55-01 (parts of it was included in -01). 8714 19.5. Version -02 8716 o Included solution Y02-01. 8718 o Included solution Y04-02. 8720 o Included solution Y11-01. 8722 o Included solution Y41-01. 8724 o Included solution Y56-01. 8726 19.6. Version -01 8728 o Included solution Y01-01. 8730 o Included solution Y03-01. 8732 o Included solution Y06-02. 8734 o Included solution Y07-01. 8736 o Included solution Y14-01. 8738 o Included solution Y20-01. 8740 o Included solution Y23-01. 8742 o Included solution Y29-01. 8744 o Included solution Y30-01. 8746 o Included solution Y31-01. 8748 o Included solution Y35-01. 8750 19.7. Version -00 8752 o Applied all reported errata for RFC 6020. 8754 o Updated YANG version to 1.1, and made the "yang-version" statement 8755 mandatory. 8757 20. References 8759 20.1. Normative References 8761 [I-D.ietf-netconf-yang-library] 8762 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 8763 Library", draft-ietf-netconf-yang-library (work in 8764 progress), January 2015. 8766 [ISO.10646] 8767 International Organization for Standardization, 8768 "Information Technology - Universal Multiple-Octet Coded 8769 Character Set (UCS)", ISO Standard 10646:2003, 2003. 8771 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8772 Requirement Levels", BCP 14, RFC 2119, March 1997. 8774 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 8775 Types", RFC 3023, January 2001. 8777 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 8778 10646", STD 63, RFC 3629, November 2003. 8780 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 8781 January 2004. 8783 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8784 Resource Identifier (URI): Generic Syntax", STD 66, RFC 8785 3986, January 2005. 8787 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8788 Encodings", RFC 4648, October 2006. 8790 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 8791 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 8792 May 2008. 8794 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 8795 Specifications: ABNF", STD 68, RFC 5234, January 2008. 8797 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 8798 Notifications", RFC 5277, July 2008. 8800 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 8801 Bierman, "Network Configuration Protocol (NETCONF)", RFC 8802 6241, June 2011. 8804 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 8805 7405, December 2014. 8807 [XML-NAMES] 8808 Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. 8809 Layman, "Namespaces in XML 1.0 (Third Edition)", World 8810 Wide Web Consortium Recommendation REC-xml-names-20091208, 8811 December 2009, 8812 . 8814 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 8815 Version 1.0", World Wide Web Consortium Recommendation 8816 REC-xpath-19991116, November 1999, 8817 . 8819 [XSD-TYPES] 8820 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 8821 Second Edition", World Wide Web Consortium Recommendation 8822 REC-xmlschema-2-20041028, October 2004, 8823 . 8825 20.2. Informative References 8827 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8828 Schoenwaelder, Ed., "Structure of Management Information 8829 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 8831 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 8832 Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 8833 58, RFC 2579, April 1999. 8835 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 8836 Structure of Management Information", RFC 3780, May 2004. 8838 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 8839 Series and RFC Editor", RFC 4844, July 2007. 8841 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 8842 Network Configuration Protocol (NETCONF)", RFC 6020, 8843 October 2010. 8845 [XPATH2.0] 8846 Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., 8847 Kay, M., Robie, J., and J. Simeon, "XML Path Language 8848 (XPath) 2.0", World Wide Web Consortium Recommendation 8849 REC-xpath20-20070123, January 2007, 8850 . 8852 [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 8853 Wide Web Consortium Recommendation REC-xslt-19991116, 8854 November 1999, 8855 . 8857 Author's Address 8859 Martin Bjorklund (editor) 8860 Tail-f Systems 8862 Email: mbj@tail-f.com