idnits 2.17.1 draft-ietf-netmod-yang-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 5805. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 5816. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 5823. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 5829. 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 11 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 29, 2008) is 5717 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) == Missing Reference: 'XXX IANA' is mentioned on line 5572, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.754' ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Possible downref: Non-RFC (?) normative reference: ref. 'XSD-TYPES' Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund, Ed. 3 Internet-Draft Tail-f Systems 4 Intended status: Standards Track August 29, 2008 5 Expires: March 2, 2009 7 YANG - A data modeling language for NETCONF 8 draft-ietf-netmod-yang-01 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on March 2, 2009. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2008). 39 Abstract 41 YANG is a data modeling language used to model configuration and 42 state data manipulated by the NETCONF protocol, NETCONF remote 43 procedure calls, and NETCONF notifications. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 48 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 8 49 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 9 50 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 11 51 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 52 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 53 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 54 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 13 55 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 14 56 4.2.3. Operational Data . . . . . . . . . . . . . . . . . . 19 57 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19 58 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 59 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 60 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 61 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23 62 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 24 63 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25 64 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 65 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 66 5.1.1. Module Hierarchies . . . . . . . . . . . . . . . . . 27 67 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 27 68 5.3. Object Based View of YANG . . . . . . . . . . . . . . . . 28 69 5.4. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 28 70 5.4.1. YANG Namespace . . . . . . . . . . . . . . . . . . . 29 71 5.5. Ordering . . . . . . . . . . . . . . . . . . . . . . . . 29 72 5.6. Containers with Presence . . . . . . . . . . . . . . . . 30 73 5.7. Scoping . . . . . . . . . . . . . . . . . . . . . . . . . 30 74 5.8. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 75 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 32 76 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 32 77 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 32 78 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 32 79 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 32 80 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 34 81 6.2.1. Identifiers and their namespaces . . . . . . . . . . 34 82 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 34 83 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 35 84 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 35 85 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 36 86 7.1. The module Statement . . . . . . . . . . . . . . . . . . 36 87 7.1.1. The module's Substatements . . . . . . . . . . . . . 37 88 7.1.2. The yang-version Statement . . . . . . . . . . . . . 38 89 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 38 90 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 39 91 7.1.5. The import Statement . . . . . . . . . . . . . . . . 39 92 7.1.6. The include Statement . . . . . . . . . . . . . . . . 40 93 7.1.7. The organization Statement . . . . . . . . . . . . . 40 94 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 40 95 7.1.9. The revision Statement . . . . . . . . . . . . . . . 40 96 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 41 97 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 41 98 7.2.1. The submodule's Substatements . . . . . . . . . . . . 43 99 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 44 100 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 45 101 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 45 102 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 46 103 7.3.2. The typedef's type Statement . . . . . . . . . . . . 46 104 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 46 105 7.3.4. The typedef's default Statement . . . . . . . . . . . 46 106 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 47 107 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 47 108 7.4.1. The type's Substatements . . . . . . . . . . . . . . 47 109 7.5. The container Statement . . . . . . . . . . . . . . . . . 47 110 7.5.1. The container's Substatements . . . . . . . . . . . . 48 111 7.5.2. The must Statement . . . . . . . . . . . . . . . . . 48 112 7.5.3. The must's Substatements . . . . . . . . . . . . . . 49 113 7.5.4. The presence Statement . . . . . . . . . . . . . . . 50 114 7.5.5. The container's Child Node Statements . . . . . . . . 50 115 7.5.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 50 116 7.5.7. NETCONF Operations . . . . . . . . . . 51 117 7.5.8. Usage Example . . . . . . . . . . . . . . . . . . . . 51 118 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 52 119 7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 53 120 7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 53 121 7.6.3. The leaf's default Statement . . . . . . . . . . . . 53 122 7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 53 123 7.6.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 54 124 7.6.6. NETCONF Operations . . . . . . . . . . 54 125 7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 54 126 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 55 127 7.7.1. The leaf-list's Substatements . . . . . . . . . . . . 56 128 7.7.2. The min-elements Statement . . . . . . . . . . . . . 56 129 7.7.3. The max-elements Statement . . . . . . . . . . . . . 56 130 7.7.4. The ordered-by Statement . . . . . . . . . . . . . . 56 131 7.7.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 57 132 7.7.6. NETCONF operations . . . . . . . . . . 57 133 7.7.7. Usage Example . . . . . . . . . . . . . . . . . . . . 58 135 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 59 136 7.8.1. The list's Substatements . . . . . . . . . . . . . . 60 137 7.8.2. The list's key Statement . . . . . . . . . . . . . . 60 138 7.8.3. The lists's unique Statement . . . . . . . . . . . . 61 139 7.8.4. The list's Child Node Statements . . . . . . . . . . 62 140 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 62 141 7.8.6. NETCONF operations . . . . . . . . . . 62 142 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 63 143 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 66 144 7.9.1. The choice's Substatements . . . . . . . . . . . . . 66 145 7.9.2. The choice's case Statement . . . . . . . . . . . . . 66 146 7.9.3. The choice's default Statement . . . . . . . . . . . 68 147 7.9.4. The choice's mandatory Statement . . . . . . . . . . 69 148 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 69 149 7.9.6. NETCONF operations . . . . . . . . . . 69 150 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 70 151 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 71 152 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 71 153 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 71 154 7.10.3. NETCONF operations . . . . . . . . . . 71 155 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 72 156 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 72 157 7.11.1. The grouping's Substatements . . . . . . . . . . . . 74 158 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 74 159 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 74 160 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 75 161 7.12.2. The uses's Refinement Statements . . . . . . . . . . 75 162 7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 76 163 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 76 164 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 77 165 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 78 166 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 78 167 7.13.3. The output Statement . . . . . . . . . . . . . . . . 79 168 7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 80 169 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 80 170 7.14. The notification Statement . . . . . . . . . . . . . . . 81 171 7.14.1. The notification's Substatements . . . . . . . . . . 82 172 7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 173 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 82 174 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 83 175 7.15.1. The augment's Substatements . . . . . . . . . . . . . 84 176 7.15.2. The when Statement . . . . . . . . . . . . . . . . . 84 177 7.15.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 85 178 7.15.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 179 7.16. The extension Statement . . . . . . . . . . . . . . . . . 87 180 7.16.1. The extension's Substatements . . . . . . . . . . . . 88 181 7.16.2. The argument Statement . . . . . . . . . . . . . . . 88 182 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 88 184 7.17. Common Statements . . . . . . . . . . . . . . . . . . . . 89 185 7.17.1. The config Statement . . . . . . . . . . . . . . . . 89 186 7.17.2. The status Statement . . . . . . . . . . . . . . . . 90 187 7.17.3. The description Statement . . . . . . . . . . . . . . 90 188 7.17.4. The reference Statement . . . . . . . . . . . . . . . 90 189 8. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 91 190 8.1. The Integer Built-in Types . . . . . . . . . . . . . . . 91 191 8.1.1. Lexicographic Representation . . . . . . . . . . . . 92 192 8.1.2. Restrictions . . . . . . . . . . . . . . . . . . . . 92 193 8.1.3. The range Statement . . . . . . . . . . . . . . . . . 92 194 8.1.4. Usage Example . . . . . . . . . . . . . . . . . . . . 93 195 8.2. The Floating Point Built-in Types . . . . . . . . . . . . 93 196 8.2.1. Lexicographic Representation . . . . . . . . . . . . 94 197 8.2.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94 198 8.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 94 199 8.3. The string Built-in Type . . . . . . . . . . . . . . . . 94 200 8.3.1. Lexicographic Representation . . . . . . . . . . . . 94 201 8.3.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94 202 8.3.3. The length Statement . . . . . . . . . . . . . . . . 95 203 8.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 96 204 8.3.5. The pattern Statement . . . . . . . . . . . . . . . . 96 205 8.3.6. Usage Example . . . . . . . . . . . . . . . . . . . . 96 206 8.4. The boolean Built-in Type . . . . . . . . . . . . . . . . 97 207 8.4.1. Lexicographic Representation . . . . . . . . . . . . 97 208 8.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97 209 8.5. The enumeration Built-in Type . . . . . . . . . . . . . . 97 210 8.5.1. Lexicographic Representation . . . . . . . . . . . . 97 211 8.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97 212 8.5.3. The enum Statement . . . . . . . . . . . . . . . . . 97 213 8.5.4. Usage Example . . . . . . . . . . . . . . . . . . . . 98 214 8.6. The bits Built-in Type . . . . . . . . . . . . . . . . . 99 215 8.6.1. Restrictions . . . . . . . . . . . . . . . . . . . . 99 216 8.6.2. Lexicographic Representation . . . . . . . . . . . . 99 217 8.6.3. The bit Statement . . . . . . . . . . . . . . . . . . 99 218 8.6.4. Usage Example . . . . . . . . . . . . . . . . . . . . 100 219 8.7. The binary Built-in Type . . . . . . . . . . . . . . . . 100 220 8.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 100 221 8.7.2. Lexicographic Representation . . . . . . . . . . . . 100 222 8.8. The keyref Built-in Type . . . . . . . . . . . . . . . . 101 223 8.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 101 224 8.8.2. The path Statement . . . . . . . . . . . . . . . . . 101 225 8.8.3. Lexicographic Representation . . . . . . . . . . . . 101 226 8.8.4. Usage Example . . . . . . . . . . . . . . . . . . . . 101 227 8.9. The empty Built-in Type . . . . . . . . . . . . . . . . . 103 228 8.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 103 229 8.9.2. Lexicographic Representation . . . . . . . . . . . . 103 230 8.9.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 231 8.10. The union Built-in Type . . . . . . . . . . . . . . . . . 104 232 8.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 104 233 8.10.2. Lexicographic Representation . . . . . . . . . . . . 104 234 8.11. The instance-identifier Built-in Type . . . . . . . . . . 104 235 8.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 105 236 8.11.2. Lexicographic Representation . . . . . . . . . . . . 105 237 8.11.3. Usage Example . . . . . . . . . . . . . . . . . . . . 105 238 9. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 106 239 10. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 240 10.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 107 241 10.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 107 242 10.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 109 243 10.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 109 244 10.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 110 245 11. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 111 246 12. Error Responses for YANG Related Errors . . . . . . . . . . . 130 247 12.1. Error Message for Data that Violates a YANG unique 248 Statement: . . . . . . . . . . . . . . . . . . . . . . . 130 249 12.2. Error Message for Data that Violates a YANG 250 max-elements Statement: . . . . . . . . . . . . . . . . . 130 251 12.3. Error Message for Data that Violates a YANG 252 min-elements Statement: . . . . . . . . . . . . . . . . . 130 253 12.4. Error Message for Data that Violates a YANG must 254 statement: . . . . . . . . . . . . . . . . . . . . . . . 131 255 12.5. Error Message for the "insert" Operation . . . . . . . . 131 256 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 132 257 14. Security Considerations . . . . . . . . . . . . . . . . . . . 133 258 15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 134 259 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 135 260 16.1. Normative References . . . . . . . . . . . . . . . . . . 135 261 16.2. Non-Normative References . . . . . . . . . . . . . . . . 136 262 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 137 263 A.1. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 137 264 A.2. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 138 265 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 139 266 Intellectual Property and Copyright Statements . . . . . . . . . 140 268 1. Introduction 270 Today, the NETCONF protocol [RFC4741] lacks a standardized way to 271 create data models. Instead, vendors are forced to use proprietary 272 solutions. In order for NETCONF to be a interoperable protocol, 273 models must be defined in a vendor-neutral way. YANG provides the 274 language and rules for defining such models for use with NETCONF. 276 YANG is a data modeling language used to model configuration and 277 state data manipulated by the NETCONF protocol, NETCONF remote 278 procedure calls, and NETCONF notifications. This document describes 279 the syntax and semantics of the YANG language, how the data model 280 defined in a YANG module is represented in XML, and how NETCONF 281 operations are used to manipulate the data. 283 2. Key Words 285 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 286 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 287 "OPTIONAL" in this document are to be interpreted as described in BCP 288 14, [RFC2119]. 290 3. Terminology 292 o anyxml: A node which can contain an unknown chunk of XML data. 294 o augment: Adds new nodes to a previously defined node. 296 o base type: The type from which a derived type was derived, which 297 may be either a built-in type or another derived type. 299 o built-in type: A YANG data type defined in the YANG language, such 300 as uint32 or string. 302 o choice: A node where only one of a number of identified 303 alternative values is valid. 305 o configuration data: The set of writable data that is required to 306 transform a system from its initial default state into its current 307 state [RFC4741]. 309 o container: An interior node in the data tree which exist in at 310 most one instance. A container node has no value, but rather a 311 set of child nodes. 313 o data definition statement: A statement that defines new data 314 nodes. One of container, leaf, leaf-list, list, augment, uses, 315 and anyxml. 317 o data model: A data model describes how data is represented and 318 accessed. 320 o data model object: A definition within a module that represents a 321 construct which can be accessed via a network management protocol. 322 Also called an object. 324 o data node: A node in the schema tree that can be instantiated in a 325 data tree. One of container, leaf, leaf-list, list, and anyxml. 327 o data tree: The instantiated tree of configuration and state data 328 on a device. 330 o derived type: A type which is derived from a built-in type (such 331 as uint32), or another derived type. 333 o extension: An extension attaches non-YANG semantics to nodes. The 334 extension statement defines new statements to express these 335 semantics. 337 o grouping: A reusable set of nodes, which may be used locally in 338 the module, in modules which include it, and by other modules 339 which import from it. 341 o identifier: Used to identify different kinds of YANG items by 342 name. 344 o instance identifier: A mechanism for identifying a particular node 345 in a data tree. 347 o interior node: Nodes within a hierarchy that are not leaf nodes. 349 o leaf: A node in the data tree with a value but no child nodes. 351 o leaf-list: Like the leaf node but defines a set of uniquely 352 identifiable nodes rather than a single node. Each node has a 353 value but no child nodes. 355 o list: Interior nodes in the data tree which may exist in multiple 356 instances. A list node has no value, but rather a set of child 357 nodes. 359 o MIB: A Management Information Base, traditionally referring to a 360 management information defined using SNMP's SMI. 362 o module: A YANG module defines a hierarchy of nodes which can be 363 used for NETCONF-based operations. With its definitions and the 364 definitions it imports or includes from elsewhere, a module is 365 self-contained and "compilable". 367 o RPC: A Remote Procedure Call, as used within the NETCONF protocol. 369 o RPC method: A specific Remote Procedure Call, as used within the 370 NETCONF protocol. Also called a protocol operation. 372 o schema node: A node in the schema tree. One of container, leaf, 373 leaf-list, list, choice, case, rpc, input, output, and 374 notification. 376 o schema node identifier: A mechanism for identifying a particular 377 node in the schema tree. 379 o schema tree: The definition hierarchy specified within a module. 381 o state data: The additional data on a system that is not 382 configuration data such as read-only status information and 383 collected statistics [RFC4741]. 385 o submodule: A partial module definition which contributes derived 386 types, groupings, data nodes, RPCs, and notifications to a module. 387 A YANG module can be constructed from a number of submodules. 389 o uses: The "uses" statement is used to instantiate the set of nodes 390 defined in a grouping statement. The instantiated nodes may be 391 refined and augmented to tailor them to any specific needs. 393 3.1. Mandatory nodes 395 A mandatory node is one of: 397 o A leaf or choice node with a "mandatory" statement with the value 398 "true". 400 o A list or leaf-list node with a "min-elements" statement with a 401 value greater than zero. 403 o A container node without a "presence" statement, which has has at 404 least one mandatory node as a child. 406 4. YANG Overview 408 4.1. Functional Overview 410 YANG is a language used to model data for the NETCONF protocol. A 411 YANG module defines a hierarchy of nodes which can be used for 412 NETCONF-based operations, including configuration, state data, remote 413 procedure calls (RPCs), and notifications. This allows a complete 414 description of all data sent between a NETCONF client and server. 416 YANG models the hierarchical organization of data as a tree in which 417 each node has a name, and either a value or a set of child nodes. 418 YANG provides clear and concise descriptions of the nodes, as well as 419 the interaction between those nodes. 421 YANG structures data models into modules and submodules. A module 422 can import data from other external modules, and include data from 423 submodules. The hierarchy can be extended, allowing one module to 424 add data nodes to the hierarchy defined in another module. This 425 augmentation can be conditional, with new nodes to appearing only if 426 certain conditions are met. 428 YANG models can describe constraints to be enforced on the data, 429 restricting the appearance or value of nodes based the presence or 430 value of other nodes in the hierarchy. These constraints are 431 enforceable by either the client or the server, and valid content 432 must abide by them. 434 YANG defines a set of built-in types, and has a type mechanism 435 through which additional types may be defined. Derived types can 436 restrict their base type's set of valid values using mechanisms like 437 range or pattern restrictions that can be enforced by clients or 438 servers. They can also define usage conventions for use of the 439 derived type, such as a string-based type that contains a host name. 441 YANG permits the definition of complex types using reusable grouping 442 of nodes. The instantiation of these groupings can refine or augment 443 the nodes, allowing it to tailor the nodes to its particular needs. 444 Derived types and groupings can be defined in one module or submodule 445 and used in either that location or in another module or submodule 446 that imports or includes it. 448 YANG organizational constructs include defining lists of nodes with 449 the same names and identifying the keys which distinguish list 450 members from each other. Such lists may be defined as either sorted 451 by user or automatically sorted by the system. For user-sorted 452 lists, operations are defined for manipulating the order of the 453 nodes. 455 YANG modules can be translated into an XML format called YIN 456 (Section 10), allowing applications using XML parsers and XSLT 457 scripts to operate on the models. 459 YANG strikes a balance between high-level object-oriented modeling 460 and low-level bits-on-the-wire encoding. The reader of a YANG module 461 can easily see the high-level view of the data model while seeing how 462 the object will be encoded in NETCONF operations. 464 YANG is an extensible language, allowing extension statements to be 465 defined by standards bodies, vendors, and individuals. The statement 466 syntax allows these extensions to coexist with standard YANG 467 statements in a natural way, while making extensions stand out 468 sufficiently for the reader to notice them. 470 YANG resists the tendency to solve all possible problems, limiting 471 the problem space to allow expression of NETCONF data models, not 472 arbitrary XML documents or arbitrary data models. The data models 473 described by YANG are designed to be easily operated upon by NETCONF 474 operations. 476 To the extent possible, YANG maintains compatibility with SNMP's 477 SMIv2 (Structure of Management Information version 2 [RFC2578], 478 [RFC2579]). SMIv2-based MIB modules can be automatically translated 479 into YANG modules for read-only access. However YANG is not 480 concerned with reverse translation from YANG to SMIv2. 482 Like NETCONF, YANG targets smooth integration with device's native 483 management infrastructure. This allows implementations to leverage 484 their existing access control mechanisms to protect or expose 485 elements of the data model. 487 4.2. Language Overview 489 This section introduces some important constructs used in YANG that 490 will aid in the understanding of the language specifics in later 491 sections. 493 4.2.1. Modules and Submodules 495 YANG defines modules using the "module" statement. This statement 496 defines the name of the module, which is typically used as the base 497 name of the file containing the module. The file suffix ".yang" is 498 typically used for YANG files. A module contains three types of 499 statements: module-header statements, revision statements, and 500 definition statements. The module header statements describe the 501 module and give information about the module itself, the revision 502 statements give information about the history of the module, and the 503 definition statements are the body of the module where the data model 504 is defined. 506 Submodule are partial modules that contribute derived types, 507 groupings, data nodes, RPCs and notifications to a module. A module 508 may include a number of submodules, but each submodule may belong to 509 only one module. The "include" statement allows a module or 510 submodule to reference material in submodules, and the "import" 511 statement allows references to material defined in other modules. 513 To reference an item that is defined in an external module it MUST be 514 imported. Identifiers that are neither defined nor imported MUST NOT 515 be visible in the local module. 517 To reference an item that is defined in one of its submodules, the 518 module MUST include the submodule. 520 A submodule that needs to reference an item defined in another 521 submodule of the same module, MUST include this submodule. 523 There MUST NOT be any circular chains of imports or includes. For 524 example, if submodule "a" includes submodule "b", "b" cannot include 525 "a". 527 When a definition in an external module is referenced, a locally 528 defined prefix MUST be used, followed by ":", and then the external 529 identifier. References to definitions in the local module MAY use 530 the prefix notation. References to built-in data types (e.g., int32) 531 MUST NOT use the prefix notation. 533 Forward references are allowed in YANG. 535 4.2.2. Data Modeling Basics 537 YANG defines four types of nodes for data modeling. In each of the 538 following subsections, the example shows the YANG syntax as well as a 539 corresponding NETCONF XML representation. 541 4.2.2.1. Leaf Nodes 543 A leaf node contains simple data like an integer or a string. It has 544 exactly one value of a particular type, and no child nodes. 546 YANG Example: 548 leaf host-name { 549 type string; 550 description "Hostname for this system"; 552 } 554 NETCONF XML Encoding: 556 my.example.com 558 The "leaf" statement is covered in Section 7.6. 560 4.2.2.2. Leaf-list Nodes 562 A leaf-list is a sequence of leaf nodes with exactly one value of a 563 particular type per leaf. 565 YANG Example: 567 leaf-list domain-search { 568 type string; 569 description "List of domain names to search"; 570 } 572 NETCONF XML Encoding: 574 high.example.com 575 low.example.com 576 everywhere.example.com 578 The "leaf-list" statement is covered in Section 7.7. 580 4.2.2.3. Container Nodes 582 A container node is used to group related nodes in a subtree. A 583 container has only child nodes and no value. A container may contain 584 any number of child nodes of any type (including leafs, lists, 585 containers, and leaf-lists). 587 YANG Example: 589 container system { 590 container login { 591 leaf message { 592 type string; 593 description 594 "Message given at start of login session"; 595 } 596 } 597 } 599 NETCONF XML Encoding: 601 602 603 Good morning, Dave 604 605 607 The "container" statement is covered in Section 7.5. 609 4.2.2.4. List Nodes 611 A list is a sequence of list entries. An entry is like a structure 612 or a record. A list entry is uniquely identified by the values of 613 its key leafs. A list entry can have multiple keys. A list entry 614 may contain any number of child nodes of any type (including leafs, 615 lists, containers etc.). 617 YANG Example: 619 list user { 620 key "name"; 621 leaf name { 622 type string; 623 } 624 leaf full-name { 625 type string; 626 } 627 leaf class { 628 type string; 629 } 630 } 632 NETCONF XML Encoding: 634 635 glocks 636 Goldie Locks 637 intruder 638 639 640 snowey 641 Snow White 642 free-loader 643 644 645 rzull 646 Repun Zell 647 tower 648 650 The "list" statement is covered in Section 7.8. 652 4.2.2.5. Example Module 654 These statements are combined to define the module: 656 // Contents of "acme-system.yang" 657 module acme-system { 658 namespace "http://acme.example.com/system"; 659 prefix "acme"; 661 organization "ACME Inc."; 662 contact "joe@acme.example.com"; 663 description 664 "The module for entities implementing the ACME system."; 666 revision 2007-06-09 { 667 description "Initial revision."; 668 } 670 container system { 671 leaf host-name { 672 type string; 673 description "Hostname for this system"; 674 } 676 leaf-list domain-search { 677 type string; 678 description "List of domain names to search"; 679 } 681 container login { 682 leaf message { 683 type string; 684 description 685 "Message given at start of login session"; 686 } 688 list user { 689 key "name"; 690 leaf name { 691 type string; 692 } 693 leaf full-name { 694 type string; 695 } 696 leaf class { 697 type string; 698 } 699 } 700 } 701 } 702 } 704 4.2.3. Operational Data 706 YANG can model operational data, as well as configuration data, based 707 on the "config" statement. When a node is tagged with "config 708 false", its subhierarchy is flagged as operational data, to be 709 reported using NETCONF's operation, not the 710 operation. Parent containers, lists, and key leafs are reported 711 also, giving the context for the operational data. 713 In this example, two leafs are defined for each interface, a 714 configured speed and an observed speed. The observed speed is not 715 configuration, so it can be returned with NETCONF operations, 716 but not with operations. The observed speed is not 717 configuration data, and cannot be manipulated using . 719 list interface { 720 key "name"; 721 config true; 723 leaf name { 724 type string; 725 } 726 leaf speed { 727 type enumeration { 728 enum 10m; 729 enum 100m; 730 enum auto; 731 } 732 } 733 leaf observed-speed { 734 type uint32; 735 config false; 736 } 737 } 739 4.2.4. Built-in Types 741 YANG has a set of built-in types, similar to those of many 742 programming languages, but with some differences due to special 743 requirements from the management domain. The following table 744 summarizes the built-in types discussed in Section 8: 746 +---------------------+-------------+-------------------------------+ 747 | Name | Type | Description | 748 +---------------------+-------------+-------------------------------+ 749 | int8 | Number | 8-bit signed integer | 750 | int16 | Number | 16-bit signed integer | 751 | int32 | Number | 32-bit signed integer | 752 | int64 | Number | 64-bit signed integer | 753 | uint8 | Number | 8-bit unsigned integer | 754 | uint16 | Number | 16-bit unsigned integer | 755 | uint32 | Number | 32-bit unsigned integer | 756 | uint64 | Number | 64-bit unsigned integer | 757 | float32 | Number | 32-bit IEEE floating point | 758 | | | real number | 759 | float64 | Number | 64-bit IEEE floating point | 760 | | | real number | 761 | string | Text | Human readable string | 762 | boolean | Text | "true" or "false" | 763 | enumeration | Text/Number | Enumerated strings with | 764 | | | associated numeric values | 765 | bits | Text/Number | A set of bits or flags | 766 | binary | Text | Any binary data | 767 | keyref | Text/Number | A reference to a list's key | 768 | | | value | 769 | empty | Empty | A leaf that does not have any | 770 | | | value | 771 | union | Text/Number | Choice of member types | 772 | instance-identifier | Text | References a data tree node | 773 +---------------------+-------------+-------------------------------+ 775 The "type" statement is covered in Section 8. 777 4.2.5. Derived Types (typedef) 779 YANG can define derived types from base types using the "typedef" 780 statement. A base type can be either a built-in type or a derived 781 type, allowing a hierarchy of derived types. 783 A derived type can be used as the argument for the "type" statement. 785 YANG Example: 787 typedef percent { 788 type uint16 { 789 range "0 .. 100"; 790 } 791 description "Percentage"; 792 } 794 leaf completed { 795 type percent; 796 } 798 NETCONF XML Encoding: 800 20 802 The "typedef" statement is covered in Section 7.3. 804 4.2.6. Reusable Node Groups (grouping) 806 Groups of nodes can be assembled into the equivalent of complex types 807 using the "grouping" statement. "grouping" defines a set of nodes 808 that are instantiated with the "uses" statement: 810 grouping target { 811 leaf address { 812 type inet:ip-address; 813 description "Target IP address"; 814 } 815 leaf port { 816 type inet:port-number; 817 description "Target port number"; 818 } 819 } 821 container peer { 822 container destination { 823 uses target; 824 } 825 } 827 NETCONF XML Encoding: 829 830 831
192.0.2.1
832 830 833 834 836 The grouping can be refined as it is used, allowing certain 837 statements to be overridden. In this example the description is 838 refined: 840 container connection { 841 container source { 842 uses target { 843 leaf address { 844 description "Source IP address"; 845 } 846 leaf port { 847 description "Source port number"; 848 } 849 } 850 } 851 container destination { 852 uses target { 853 leaf address { 854 description "Destination IP address"; 855 } 856 leaf port { 857 description "Destination port number"; 858 } 859 } 860 } 861 } 863 The "grouping" statement is covered in Section 7.11. 865 4.2.7. Choices 867 YANG allows the data model to segregate incompatible nodes into 868 distinct choices using the "choice" and "case" statements. The 869 "choice" statement contains a set of "case" statements which define 870 sets of schema nodes that cannot appear together. Each "case" may 871 contain multiple nodes, but each node may appear in only one "case" 872 under a "choice". 874 When an element from one case is created, all elements from all other 875 cases are implicitly deleted. The device handles the enforcement of 876 the constraint, preventing incompatibilities from existing in the 877 configuration. 879 The choice and case nodes appear only in the schema tree, not in the 880 data tree or XML encoding. The additional levels of hierarchy are 881 not needed beyond the conceptual schema. 883 YANG Example: 885 container food { 886 choice snack { 887 mandatory true; 888 case sports-arena { 889 leaf pretzel { 890 type empty; 891 } 892 leaf beer { 893 type empty; 894 } 895 } 896 case late-night { 897 leaf chocolate { 898 type enumeration { 899 enum dark; 900 enum milk; 901 enum first-available; 902 } 903 } 904 } 905 } 906 } 908 NETCONF XML Encoding: 910 911 first-available 912 914 The "choice" statement is covered in Section 7.9. 916 4.2.8. Extending Data Models (augment) 918 YANG allows a module to insert additional nodes into data models, 919 including both the current module (and its submodules) or an external 920 module. This is useful e.g. for vendors to add vendor-specific 921 parameters to standard data models in an interoperable way. 923 The "augment" statement defines the location in the data model 924 hierarchy where new nodes are inserted, and the "when" statement 925 defines the conditions when the new nodes are valid. 927 YANG Example: 929 augment system/login/user { 930 when "class != 'wheel'"; 931 leaf uid { 932 type uint16 { 933 range "1000 .. 30000"; 934 } 935 } 936 } 938 This example defines a "uid" node that only is valid when the user's 939 "class" is not "wheel". 941 If a module augments another model, the XML representation of the 942 data will reflect the prefix of the augmenting model. For example, 943 if the above augmentation were in a module with prefix "other", the 944 XML would look like: 946 NETCONF XML Encoding: 948 949 alicew 950 Alice N. Wonderland 951 drop-out 952 1024 953 955 The "augment" statement is covered in Section 7.15. 957 4.2.9. RPC Definitions 959 YANG allows the definition of NETCONF RPCs. The method names, input 960 parameters and output parameters are modeled using YANG data 961 definition statements. 963 YANG Example: 965 rpc activate-software-image { 966 input { 967 leaf image-name { 968 type string; 969 } 970 } 971 output { 972 leaf status { 973 type string; 974 } 975 } 976 } 978 NETCONF XML Encoding: 980 982 983 acmefw-2.3 984 985 987 989 990 991 The image acmefw-2.3 is being installed. 992 993 994 996 The "rpc" statement is covered in Section 7.13. 998 4.2.10. Notification Definitions 1000 YANG allows the definition of notifications suitable for NETCONF. 1001 YANG data definition statements are used to model the content of the 1002 notification. 1004 YANG Example: 1006 notification link-failure { 1007 description "A link failure has been detected"; 1008 leaf if-index { 1009 type int32 { range "1 .. max"; } 1010 } 1011 leaf if-name { 1012 type keyref { 1013 path "/interfaces/interface/name"; 1014 } 1015 } 1016 } 1018 NETCONF XML Encoding: 1020 1022 2007-09-01T10:00:00Z 1023 1024 so-1/2/3.0 1025 1027 1029 The "notification" statement is covered in Section 7.14. 1031 5. Language Concepts 1033 5.1. Modules and Submodules 1035 The module is the base unit of definition in YANG. A module defines 1036 a single data model. A module can define a complete, cohesive model, 1037 or augment an existing data model with additional nodes. 1039 A NETCONF server may implement a number of modules, allowing multiple 1040 views of the same data, or multiple views of disjoint subsections of 1041 the device's data. Alternatively, the server may implement only one 1042 module that defines all available data. Any modules that are 1043 implemented MUST be available for all defined datastores. 1045 A module may be divided into submodules, based on the needs of the 1046 module owner. The external view remains that of a single module, 1047 regardless of the presence or size of its submodules. 1049 A module uses the "include" statement to include its submodules, and 1050 the "import" statement to reference external modules. Similarly, a 1051 submodule may use the "import" statement to reference other modules, 1052 and may use the "include" statement to reference other submodules 1053 within its module. A module or submodule may not include submodules 1054 from other modules, nor may a submodule import its own module. 1056 The names of all standard modules must be unique, but different 1057 revisions of the same module should have the same name. Developers 1058 of enterprise modules are encouraged to choose names for their 1059 modules that will have a low probability of colliding with standard 1060 or other enterprise modules, e.g., by using the enterprise or 1061 organization name as a prefix. 1063 5.1.1. Module Hierarchies 1065 YANG allows modeling of data in multiple hierarchies, where data may 1066 have more than one root node. Models that have multiple roots nodes 1067 are sometimes convenient, and are supported by YANG. 1069 5.2. File Layout 1071 YANG modules and submodules are typically stored in files, one module 1072 or submodule per file, with the name of the file given by the 1073 concatenation of the module or submodule name and the file suffix 1074 ".yang". YANG compilers can find imported modules and included 1075 submodules via this convention. While the YANG language defines 1076 modules, tools may compile submodules independently for performance 1077 and manageability reasons. Many errors and warnings that cannot be 1078 detected during submodule compilation may be delayed until the 1079 submodules are linked into a cohesive module. 1081 5.3. Object Based View of YANG 1083 While YANG models the configuration as a data tree, it can be used in 1084 an object-based manner as well. 1086 The configuration and state data of the device is modeled as a tree 1087 of object instances (objects for short). Each object in the tree has 1088 a type name (or managed object class name), a namespace, a (possibly 1089 empty) set of attributes and a (possibly empty) set of child objects. 1091 A managed object class could be defined as a grouping, containing 1092 just one list. Attributes should be defined as leafs inside the 1093 list. Child objects should be defined with the corresponding uses 1094 statements. 1096 A defined grouping unambiguously defines its properties, it has its 1097 own unique name, so when it is referred to in the "uses" statement it 1098 is always the same well defined set of properties that we are using. 1100 The data tree can be defined as one or more top level containers 1101 containing managed object classes defined as groupings. All further 1102 levels of the data tree are defined by managed object classes 1103 containing further managed objects. 1105 5.4. XML Namespaces 1107 All YANG definitions are specified within a particular XML Namespace. 1108 Each module defines an XML namespace as a globally unique URI 1109 [RFC3986]. A NETCONF client or server uses the namespace during XML 1110 encoding of data. 1112 The namespace URI is advertised as a capability in the NETCONF 1113 message to indicate support for the YANG module by a NETCONF 1114 server. The capability URI advertised SHOULD be on the form: 1116 namespace-uri "?" revision 1118 Where "revision" is the revision of the module (see Section 7.1.9) 1119 that the server implements. 1121 Namespaces for standard module names will be assigned by IANA. They 1122 MUST be unique (but different revisions of the same module should 1123 have the same namespace). 1125 Namespaces for private module names will be assigned by the 1126 organization owning the module without a central registry. It is 1127 recommended to choose namespaces that will have a low probability of 1128 colliding with standard or other enterprise modules, e.g. by using 1129 the enterprise or organization name in the namespace. 1131 The "namespace" statement is covered in Section 7.1.3. 1133 5.4.1. YANG Namespace 1135 YANG defines its own namespace for NETCONF operations. 1136 This namespace is "urn:ietf:params:xml:ns:yang:1" [XXX IANA]. 1138 5.5. Ordering 1140 YANG supports two styles for ordering the entries within a list. In 1141 many lists, the order of list entries does not impact the 1142 implementation of the list's configuration, and the device is free to 1143 sort the list entries in any reasonable order. The "description" 1144 string for the list may suggest an order. YANG calls this style of 1145 list "system ordered" and they are indicated with the statement 1146 "ordered-by system". 1148 For example, a list of valid users would typically be sorted 1149 alphabetically, since the order in which the users appeared in the 1150 configuration would not impact the creation of those users' accounts. 1152 In the other style of lists, the order of list entries matters for 1153 the implementation of the list's configuration and the user is 1154 responsible for ordering the entries, while the device maintains that 1155 order. YANG calls this style of list "user ordered" and they are 1156 indicated with the statement "ordered-by user". 1158 For example, the order in which firewall filters entries are applied 1159 to incoming traffic may affect how that traffic is filtered. The 1160 user would need to decide if the filter entry that discards all TCP 1161 traffic should be applied before or after the filter entry that 1162 allows all traffic from trusted interfaces. The choice of order 1163 would be crucial. 1165 YANG provides a rich set of facilities within NETCONF's 1166 operation which allow the order of list entries in user-ordered lists 1167 to be controlled. List entries may be inserted or rearranged, 1168 positioned as the first or last entry in the list, or positioned 1169 before or after another specific entry. 1171 The "ordered-by" statement is covered in Section 7.7.4. 1173 5.6. Containers with Presence 1175 YANG supports two styles of containers, those which exist only for 1176 organizing the hierarchy of data nodes, and those whose presence in 1177 the configuration has an explicit meaning. 1179 In the first style, the container has no meaning of its own, existing 1180 only to contain child nodes. The container data node is implicitly 1181 created when the first child data node is created. The data node is 1182 implicitly deleted when the last non-key child is deleted, since an 1183 empty container has no meaning. 1185 For example, the set of scrambling options for SONET interfaces may 1186 be placed inside a "scrambling" container to enhance the organization 1187 of the configuration hierarchy, and to keep these nodes together. 1188 The "scrambling" node itself has no meaning, so removing the node 1189 when it becomes empty relieves the user from the task of performing 1190 this task. 1192 In the second style, the presence of the container itself is 1193 configuration data, representing a single bit of configuration data. 1194 The container acts as both a configuration knob and a means of 1195 organizing related configuration. These containers are explicitly 1196 created and deleted. 1198 YANG calls this style a "presence container" and they are indicated 1199 using the "presence" statement, which takes as its argument a text 1200 string indicating what the presence of the node means. 1202 For example, an "ssh" container may turn on the ability to log into 1203 the device using ssh, but can also contain any ssh-related 1204 configuration knobs, such as connection rates or retry limits. 1206 The "presence" statement is covered in Section 7.5.4. 1208 5.7. Scoping 1210 YANG uses static scoping. Grouping definitions are resolved in the 1211 context in which they are defined, rather than the context in which 1212 they are used. Users of groupings are not required to import modules 1213 or include submodules to satisfy all references made by the grouping. 1215 For example, if a module defines a grouping in which a type is 1216 referenced, when the grouping is used in a second module, the type is 1217 resolved in the original module, not the second module. There is no 1218 worry over conflicts if both modules define the type, since there is 1219 no ambiguity. 1221 5.8. Nested Typedefs and Groupings 1223 Typedefs and groupings may appear nested under many YANG statements, 1224 allowing these to be lexically scoped by the hierarchy under which 1225 they appear. This allows types and groupings to be defined near 1226 where they are used, rather than placing them at the top level of the 1227 hierarchy. The close proximity increases readability. 1229 Scoping also allows types to be defined without concern for naming 1230 conflicts between types in different submodules. Type names can be 1231 specified without adding leading strings designed to prevent name 1232 collisions within large modules. 1234 Finally, scoping allows the module author to keep types and groupings 1235 private to their module or submodule, preventing their reuse. Since 1236 only top-level types and groupings can be used outside the module or 1237 submodule, the developer has more control over what pieces of their 1238 module are presented to the outside world, supporting the need to 1239 hide internal information and maintaining a boundary between what is 1240 shared with the outside world and what is kept private. 1242 Scoped definitions MUST NOT shadow definitions at a higher scope. A 1243 type or group cannot be defined if a higher level in the schema 1244 hierarchy has a definition with a matching identifier. 1246 When a YANG implementation resolves a reference to an unprefixed type 1247 or grouping, or one which uses the prefix of the local module, it 1248 searches up the levels of hierarchy in the schema tree, starting at 1249 the current level, for the definition of the type or grouping. 1251 6. YANG syntax 1253 The YANG syntax is similar to that of SMIng [RFC3780] and programming 1254 languages like C and C++. This C-like syntax was chosen specifically 1255 for its readability, since YANG values the time and effort of the 1256 readers of models above those of modules writers and YANG tool-chain 1257 developers. This section introduces the YANG syntax. 1259 YANG modules are written in the UTF-8 [RFC3629] character set. 1261 6.1. Lexicographical Tokenization 1263 YANG modules are parsed as a series of tokens. This section details 1264 the rules for recognizing tokens from an input stream. YANG 1265 tokenization rules are both simple and powerful. The simplicity is 1266 driven by a need to keep the parsers easy to implement, while the 1267 power is driven by the fact that modelers need to express their 1268 models in readable formats. 1270 6.1.1. Comments 1272 Comments are C++ style. A single line comment starts with "//" and 1273 ends at the end of the line. A block comment is enclosed within "/*" 1274 and "*/". 1276 6.1.2. Tokens 1278 A token in YANG is either a keyword, a string, ";", "{", or "}". A 1279 string can be quoted or unquoted. A keyword is either one of the 1280 core YANG keywords defined in this document, or a prefix identifier, 1281 followed by ":", followed by a language extension keyword. Keywords 1282 are case sensitive. See Section 6.2 for a formal definition of 1283 identifiers. 1285 6.1.3. Quoting 1287 If a string contains any whitespace characters, a semicolon (";"), 1288 curly braces ("{" or "}"), or comment sequences ("//", "/*", or 1289 "*/"), then it MUST be enclosed within double or single quotes. 1291 If the double quoted string contains a line break followed by 1292 whitespace which is used to indent the text according to the layout 1293 in the YANG file, this leading whitespace is stripped from the 1294 string, up to at most the same column of the double quote character. 1296 If the double quoted string contains whitespace before a line break, 1297 this trailing whitespace is stripped from the string. 1299 A single quoted string (enclosed within ' ') preserves each character 1300 within the quotes. A single quote character can not occur in a 1301 single quoted string, even when preceded by a backslash. 1303 If a quoted string is followed by a plus character ("+"), followed by 1304 another quoted string, the two strings are concatenated into one 1305 quoted string, allowing multiple concatenations to build one quoted 1306 string. Whitespace trimming of double quoted strings is done before 1307 concatenation. 1309 Within a double quoted string (enclosed within " "), a backslash 1310 character introduces a special character, which depends on the 1311 character that immediately follows the backslash: 1313 \n new line 1314 \t a tab character 1315 \" a double quote 1316 \\ a single backslash 1318 6.1.3.1. Quoting Examples 1320 The following strings are equivalent: 1322 hello 1323 "hello" 1324 'hello' 1325 "hel" + "lo" 1326 'hel' + "lo" 1328 The following examples show some special strings: 1330 "\"" - string containing a double quote 1331 '"' - string containing a double quote 1332 "\n" - string containing a newline character 1333 '\n' - string containing a backslash followed 1334 by the character n 1336 The following examples show some illegal strings: 1338 '''' - a single-quoted string cannot contain single quotes 1339 """ - a double quote must be escaped in a double quoted string 1341 The following strings are equivalent: 1343 "first line 1344 second line" 1346 "first line\n" + " second line" 1348 6.2. Identifiers 1350 Identifiers are used to identify different kinds of YANG items by 1351 name. Each identifier starts with an upper-case or lower-case ASCII 1352 letter or an underscore character, followed by zero or more ASCII 1353 letters, digits, underscore characters, hyphens, and dots. 1354 Implementations MUST support identifiers up to 63 characters in 1355 length. Identifiers are case sensitive. The identifier syntax is 1356 formally defined by the rule "identifier" in Section 11. Identifiers 1357 can be specified as quoted or unquoted strings. 1359 6.2.1. Identifiers and their namespaces 1361 Each identifier is valid in a namespace which depends on the type of 1362 the YANG item being defined: 1364 o All module and submodule names share the same global module 1365 identifier namespace. 1367 o All extension names defined in a module and its submodules share 1368 the same extension identifier namespace. 1370 o All derived type names defined within a parent node or at the top- 1371 level of the module or its submodules share the same type 1372 identifier namespace. This namespace is scoped to the parent node 1373 or module. 1375 o All groupings defined within a parent node or at the top-level of 1376 the module or its submodules share the same grouping identifier 1377 namespace. This namespace is scoped to the parent node or module. 1379 o All leafs, leaf-lists, lists, containers, choices, rpcs, and 1380 notifications defined within a parent node or at the top-level of 1381 the module or its submodules share the same identifier namespace. 1382 This namespace is scoped to the parent node or module, unless the 1383 parent node is a case node. In that case, the namespace is scoped 1384 to the parent node of the case node's parent choice node. 1386 o All cases within a choice share the same case identifier 1387 namespace. This namespace is scoped to the parent choice node. 1389 All identifiers defined in a namespace MUST be unique. 1391 6.3. Statements 1393 A YANG module contains a sequence of statements. Each statement 1394 starts with a keyword, followed by zero or one argument, followed 1395 either by a semicolon (";") or a block of substatements enclosed 1396 within curly braces ("{ }"): 1398 statement = keyword [argument] (";" / "{" *statement "}") 1400 The argument is a string, as defined in Section 6.1.2. 1402 6.3.1. Language Extensions 1404 A module can introduce YANG extensions by using the "extension" 1405 keyword (see Section 7.16). The extensions can be imported by other 1406 modules with the "import" statement (see Section 7.1.5). When an 1407 imported extension is used, the extension's keyword must be qualified 1408 using the prefix with which the extension's module was imported. If 1409 an extension is used in the module where it is defined, the 1410 extension's keyword must be qualified with the module's prefix. 1412 6.4. XPath Evaluations 1414 YANG relies on XPath 1.0 [XPATH] as a notation for specifying many 1415 inter-node references and dependencies. NETCONF clients and servers 1416 are not required to implement an XPath interpreter, but MUST ensure 1417 that the requirements encoded in the data model are enforced. The 1418 manner of enforcement is an implementation decision. The XPath 1419 expressions MUST be valid, but any implementation may choose to 1420 implement them by hand, rather than using the XPath expression 1421 directly. 1423 XPath expressions are evaluated in the context of the current node, 1424 with the namespace of the current module defined as the null 1425 namespace. References to identifiers in external modules MUST be 1426 qualified with appropriate prefixes, and references to the current 1427 module and its submodules MAY use a prefix. 1429 7. YANG Statements 1431 The following sections describe all of the YANG core statements. 1433 Note that even a statement which does not have any substatements 1434 defined in core YANG can have vendor-specific extensions as 1435 substatements. For example, the "description" statement does not 1436 have any substatements defined in core YANG, but the following is 1437 legal: 1439 description "some text" { 1440 acme:documentation-flag 5; 1441 } 1443 7.1. The module Statement 1445 The "module" statement defines the module's name, and groups all 1446 statements which belong to the module together. The "module" 1447 statement's argument is the name of the module, followed by a block 1448 of substatements that hold detailed module information. The module 1449 name follows the rules for identifiers in Section 6.2. 1451 Standard module names will be assigned by IANA. The names of all 1452 standard modules MUST be unique (but different revisions of the same 1453 module should have the same name). 1455 Private module names will be assigned by the organization owning the 1456 module without a central registry. It is recommended to choose names 1457 for their modules that will have a low probability of colliding with 1458 standard or other enterprise modules, e.g. by using the enterprise or 1459 organization name as a prefix. 1461 A module SHOULD have the following layout: 1463 module { 1465 // header information 1466 1467 1468 1470 // linkage statements 1471 1472 1474 // meta information 1475 1476 1477 1478 1480 // revision history 1481 1483 // module definitions 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 } 1498 7.1.1. The module's Substatements 1499 +--------------+---------+-------------+ 1500 | substatement | section | cardinality | 1501 +--------------+---------+-------------+ 1502 | anyxml | 7.10 | 0..n | 1503 | augment | 7.15 | 0..n | 1504 | choice | 7.9 | 0..n | 1505 | contact | 7.1.8 | 0..1 | 1506 | container | 7.5 | 0..n | 1507 | description | 7.17.3 | 0..1 | 1508 | extension | 7.16 | 0..n | 1509 | grouping | 7.11 | 0..n | 1510 | import | 7.1.5 | 0..n | 1511 | include | 7.1.6 | 0..n | 1512 | leaf | 7.6 | 0..n | 1513 | leaf-list | 7.7 | 0..n | 1514 | list | 7.8 | 0..n | 1515 | namespace | 7.1.3 | 1 | 1516 | notification | 7.14 | 0..n | 1517 | organization | 7.1.7 | 0..1 | 1518 | prefix | 7.1.4 | 1 | 1519 | reference | 7.17.4 | 0..1 | 1520 | revision | 7.1.9 | 0..n | 1521 | rpc | 7.13 | 0..n | 1522 | typedef | 7.3 | 0..n | 1523 | uses | 7.12 | 0..n | 1524 | yang-version | 7.1.2 | 0..1 | 1525 +--------------+---------+-------------+ 1527 7.1.2. The yang-version Statement 1529 The "yang-version" statement specifies which version of the YANG 1530 language was used in developing the module. The statement's argument 1531 contains value "1", which is the current yang version and the default 1532 value. 1534 This statement is intended for future-proofing the syntax of YANG 1535 against possible changes in later versions of YANG. Since the 1536 current version is the default value, the statement need not appear 1537 in YANG modules until a future version is defined. When a new 1538 version is defined, YANG modules can either use version 2 features 1539 and add the "yang-version 2" statement, or remain within the version 1540 1 feature set and continue to use the default setting of "yang- 1541 version 1". 1543 7.1.3. The namespace Statement 1545 The "namespace" statement defines the XML namespace for all XML 1546 elements defined by the module. Its argument is the URI of the 1547 namespace. 1549 See also Section 5.4. 1551 7.1.4. The prefix Statement 1553 The "prefix" statement is used to define the prefix associated with 1554 the namespace of a module. The "prefix" statement's argument is the 1555 prefix string which is used as a prefix to access a module. The 1556 prefix string may be used to refer to definitions contained in the 1557 module, e.g. "if:ifName". A prefix follows the same rules as an 1558 identifier (see Section 6.2). 1560 When used inside the "module" statement, the "prefix" statement 1561 defines the prefix to be used when this module is imported. To 1562 improve readability of the NETCONF XML, a NETCONF client or server 1563 which generates XML or XPath that use prefixes, the prefix defined by 1564 a module SHOULD be used, unless there is a conflict. 1566 When used inside the "import" statement, the "prefix" statement 1567 defines the prefix to be used when accessing data inside the imported 1568 module. When a reference to an identifier from the imported module 1569 is used, the prefix string for the module from which objects are 1570 being imported is used in combination with a colon (":") and the 1571 identifier, e.g. "if:ifIndex". To improve readability of YANG 1572 modules, the prefix defined by a module SHOULD be used when the 1573 module is imported, unless there is a conflict. 1575 All prefixes, including the prefix for the module itself MUST be 1576 unique within the module or submodule. 1578 7.1.5. The import Statement 1580 The "import" statement makes definitions from one module available 1581 inside another module or submodule. The argument is the name of the 1582 module to import, and the statement is followed by a block of 1583 substatements that holds detailed import information. 1585 All identifiers contained in an imported module are imported into the 1586 current module or submodule, so that they can be referenced by 1587 definitions in the current module or submodule. The mandatory 1588 "prefix" substatement assigns a prefix for the imported module which 1589 is scoped to the importing module or submodule. Multiple "import" 1590 statements may be specified to import from different modules. 1592 +--------------+---------+-------------+ 1593 | substatement | section | cardinality | 1594 +--------------+---------+-------------+ 1595 | prefix | 7.1.4 | 1 | 1596 +--------------+---------+-------------+ 1598 7.1.6. The include Statement 1600 The "include" statement is used to make content from a submodule 1601 available to the module. The argument is an identifier which is the 1602 name of the submodule to include. Modules are only allowed to 1603 include submodules that belong to that module, as defined by the 1604 "belongs-to" statement (see Section 7.2.2). 1606 When a module includes a submodule, it incorporates the contents of 1607 the submodule into the node hierarchy of the module. When a 1608 submodule includes another submodule, the target submodule's 1609 definitions are made available to the current submodule. 1611 7.1.7. The organization Statement 1613 The "organization" statement defines the party responsible for this 1614 module. The argument is a string which is used to specify a textual 1615 description of the organization(s) under whose auspices this module 1616 was developed. 1618 7.1.8. The contact Statement 1620 The "contact" statement provides contact information for the module. 1621 The argument is a string which is used to specify the name, postal 1622 address, telephone number, and electronic mail address of the person 1623 to whom technical queries concerning this module should be sent. 1625 7.1.9. The revision Statement 1627 The "revision" statement specifies the editorial revision history of 1628 the module, including the initial revision. A series of revisions 1629 statements detail the changes in the module's definition. The 1630 argument is a date string in the format "YYYY-MM-DD", followed by a 1631 block of substatements that holds detailed revision information. A 1632 module SHOULD have at least one initial "revision" statement. For 1633 every editorial change, a new one SHOULD be added in front of the 1634 revisions sequence, so that all revisions are in reverse 1635 chronological order. 1637 7.1.9.1. The revision's Substatement 1639 +--------------+---------+-------------+ 1640 | substatement | section | cardinality | 1641 +--------------+---------+-------------+ 1642 | description | 7.17.3 | 0..1 | 1643 +--------------+---------+-------------+ 1645 7.1.10. Usage Example 1647 module acme-system { 1648 namespace "http://acme.example.com/system"; 1649 prefix "acme"; 1651 import yang-types { 1652 prefix "yang"; 1653 } 1655 include acme-types; 1657 organization "ACME Inc."; 1658 contact 1659 "Joe L. User 1661 ACME, Inc. 1662 42 Anywhere Drive 1663 Nowhere, CA 95134 1664 USA 1666 Phone: +1 800 555 0815 1667 EMail: joe@acme.example.com"; 1669 description 1670 "The module for entities implementing the ACME protocol."; 1672 revision "2007-06-09" { 1673 description "Initial revision."; 1674 } 1676 // definitions follows... 1677 } 1679 7.2. The submodule Statement 1681 While the primary unit in YANG is a module, a YANG module can itself 1682 be constructed out of several submodules. Submodules allow to split 1683 a complex module in several pieces where all the submodules 1684 contribute to a single namespace, which is defined by the module 1685 including the submodules. 1687 The "submodule" statement is used to give the submodule a name, and 1688 to group all statements which belong to the submodule together. 1690 The "submodule" statement, which must be present at most once, takes 1691 as an argument an identifier which is the name of the submodule, 1692 followed by a block of substatements that hold detailed submodule 1693 information. 1695 Standard submodule names will be assigned by IANA. Name of all 1696 standard submodules must be unique and in addition not conflict with 1697 module names (but different revisions of the same submodule should 1698 have the same name). 1700 Private submodule names will be assigned by the organization owning 1701 the submodule without a central registry. It is recommended to 1702 choose names for their submodules that will have a low probability of 1703 colliding with standard or other enterprise modules and submodules, 1704 e.g. by using the enterprise or organization name as a prefix. 1706 A submodule SHOULD have the following layout: 1708 submodule { 1710 1711 // module identification 1712 1714 // linkage statements 1715 1716 1718 // meta information 1719 1720 1721 1722 1724 // revision history 1725 1727 // module definitions 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 } 1742 7.2.1. The submodule's Substatements 1743 +--------------+---------+-------------+ 1744 | substatement | section | cardinality | 1745 +--------------+---------+-------------+ 1746 | anyxml | 7.10 | 0..n | 1747 | augment | 7.15 | 0..n | 1748 | belongs-to | 7.2.2 | 1 | 1749 | choice | 7.9 | 0..n | 1750 | contact | 7.1.8 | 0..1 | 1751 | container | 7.5 | 0..n | 1752 | description | 7.17.3 | 0..1 | 1753 | extension | 7.16 | 0..n | 1754 | grouping | 7.11 | 0..n | 1755 | import | 7.1.5 | 0..n | 1756 | include | 7.1.6 | 0..n | 1757 | leaf | 7.6 | 0..n | 1758 | leaf-list | 7.7 | 0..n | 1759 | list | 7.8 | 0..n | 1760 | notification | 7.14 | 0..n | 1761 | organization | 7.1.7 | 0..1 | 1762 | reference | 7.17.4 | 0..1 | 1763 | revision | 7.1.9 | 0..n | 1764 | rpc | 7.13 | 0..n | 1765 | typedef | 7.3 | 0..n | 1766 | uses | 7.12 | 0..n | 1767 | yang-version | 7.1.2 | 0..1 | 1768 +--------------+---------+-------------+ 1770 7.2.2. The belongs-to Statement 1772 The "belongs-to" statement specifies the module to which the 1773 submodule belongs. The argument is an identifier which is the name 1774 of the module. Only the module to which a submodule belongs, or 1775 another submodule that belongs to the same module, are allowed to 1776 include that submodule. 1778 7.2.3. Usage Example 1780 submodule acme-types { 1782 belongs-to "acme-system"; 1784 import yang-types { 1785 prefix "yang"; 1786 } 1788 organization "ACME Inc."; 1789 contact 1790 "Joe L. User 1792 ACME, Inc. 1793 42 Anywhere Drive 1794 Nowhere, CA 95134 1795 USA 1797 Phone: +1 800 555 0815 1798 EMail: joe@acme.example.com"; 1800 description 1801 "This submodule defines common ACME types."; 1803 revision "2007-06-09" { 1804 description "Initial revision."; 1805 } 1807 // definitions follows... 1808 } 1810 7.3. The typedef Statement 1812 The "typedef" statement defines a new type which may be used locally 1813 in the module, in modules or submodules which include it, and by 1814 other modules which import from it. The new type is called the 1815 "derived type", and the type from which it was derived is called the 1816 "base type". All derived types can be traced back to a YANG built-in 1817 type. 1819 The "typedef" statement's argument is an identifier which is the name 1820 of the type to be defined, and MUST be followed by a block of 1821 substatements that holds detailed typedef information. 1823 The name of the type MUST NOT be one of the YANG built-in types. If 1824 the typedef is defined at the top level of a YANG module or 1825 submodule, the name of the type to be defined MUST be unique within 1826 the module. For details about scoping for nested typedef, see 1827 Section 5.8. 1829 7.3.1. The typedef's Substatements 1831 +--------------+---------+-------------+ 1832 | substatement | section | cardinality | 1833 +--------------+---------+-------------+ 1834 | default | 7.3.4 | 0..1 | 1835 | description | 7.17.3 | 0..1 | 1836 | reference | 7.17.4 | 0..1 | 1837 | status | 7.17.2 | 0..1 | 1838 | type | 7.3.2 | 1 | 1839 | units | 7.3.3 | 0..1 | 1840 +--------------+---------+-------------+ 1842 7.3.2. The typedef's type Statement 1844 The "type" statement, which must be present, defines the base type 1845 from which this type is derived. See Section 7.4 for details. 1847 7.3.3. The units Statement 1849 The "units" statement, which is optional, takes as an argument a 1850 string which contains a textual definition of the units associated 1851 with the type. 1853 7.3.4. The typedef's default Statement 1855 The "default" statement takes as an argument a string which contains 1856 a default value for the new type. 1858 The value of the "default" statement MUST correspond to the type 1859 specified in the "type" statement. 1861 If the base type has a default value, and the new derived type does 1862 not specify a new default value, the base type's default value is 1863 also the default value of the new derived type. The default value 1864 MUST correspond to any restrictions in the derived type. 1866 If the base type's default value does not correspond to the new 1867 restrictions, the derived type MUST define a new default value. 1869 7.3.5. Usage Example 1871 typedef listen-ipv4-address { 1872 type inet:ipv4-address; 1873 default "0.0.0.0"; 1874 } 1876 7.4. The type Statement 1878 The "type" statement takes as an argument a string which is the name 1879 of a YANG built-in type (see Section 8) or a derived type (see 1880 Section 7.3), followed by an optional block of substatements that are 1881 used to put further restrictions on the type. 1883 The restrictions that can be applied depends on the type being 1884 restricted. All restriction statements are described in conjunction 1885 with the built-in types in Section 8. 1887 7.4.1. The type's Substatements 1889 +--------------+---------+-------------+ 1890 | substatement | section | cardinality | 1891 +--------------+---------+-------------+ 1892 | bit | 8.6.3 | 0..n | 1893 | enum | 8.5.3 | 0..n | 1894 | length | 8.3.3 | 0..1 | 1895 | path | 8.8.2 | 0..1 | 1896 | pattern | 8.3.5 | 0..n | 1897 | range | 8.1.3 | 0..1 | 1898 | type | 7.4 | 0..n | 1899 +--------------+---------+-------------+ 1901 7.5. The container Statement 1903 The "container" statement is used to define an interior node in the 1904 schema tree. It takes one argument, which is an identifier, followed 1905 by a block of substatements that holds detailed container 1906 information. 1908 A container node does not have a value, but it has a list of child 1909 nodes in the data tree. The child nodes are defined in the 1910 container's substatements. 1912 By default, a container does not carry any information, but is used 1913 to organize and give structure to the data being defined. The 1914 "presence" statement (see Section 7.5.4) is used to give semantics to 1915 the existence of the container in the data tree. 1917 7.5.1. The container's Substatements 1919 +--------------+---------+-------------+ 1920 | substatement | section | cardinality | 1921 +--------------+---------+-------------+ 1922 | anyxml | 7.10 | 0..n | 1923 | augment | 7.15 | 0..n | 1924 | choice | 7.9 | 0..n | 1925 | config | 7.17.1 | 0..1 | 1926 | container | 7.5 | 0..n | 1927 | description | 7.17.3 | 0..1 | 1928 | grouping | 7.11 | 0..n | 1929 | leaf | 7.6 | 0..n | 1930 | leaf-list | 7.7 | 0..n | 1931 | list | 7.8 | 0..n | 1932 | must | 7.5.2 | 0..n | 1933 | presence | 7.5.4 | 0..1 | 1934 | reference | 7.17.4 | 0..1 | 1935 | status | 7.17.2 | 0..1 | 1936 | typedef | 7.3 | 0..n | 1937 | uses | 7.12 | 0..n | 1938 +--------------+---------+-------------+ 1940 7.5.2. The must Statement 1942 The "must" statement, which is optional, takes as an argument a 1943 string which contains an XPath expression. It is used to formally 1944 declare a constraint on the configuration data. When a configuration 1945 datastore is validated, all "must" constraints are conceptually 1946 evaluated once for each corresponding instance in the datastore's 1947 data tree, and for all leafs with default values in effect. If an 1948 instance does not exist in the data tree, and it does not have a 1949 default value, its "must" statements are not evaluated. 1951 All such constraints MUST evaluate to true for the configuration to 1952 be valid. 1954 The "must" statement is ignored if the data does not represent 1955 configuration. 1957 The XPath expression is conceptually evaluated in the following 1958 context: 1960 o The context node is the node in the data tree for which the "must" 1961 statement is defined. 1963 o The accessible tree is made up of all nodes in the data tree, and 1964 all leafs with default values. 1966 o The set of namespace declarations is the set of all "import" 1967 statements' prefix and namespace pairs, and the "prefix" 1968 statement's prefix for the "namespace" statement's URI. 1970 o Elements without a namespace refer to nodes in the current module. 1972 o The function library is the core function library defined in 1973 [XPATH], and a function "current()" which returns a node set with 1974 the initial context node. 1976 The result of the XPath expression is converted to a boolean value 1977 using the standard XPath rules. 1979 If the node with the must statement represents configuration data, 1980 any node referenced in the XPath expression MUST also represent 1981 configuration. 1983 Note that the XPath expression is conceptually evaluated. This means 1984 that an implementation does not have to use an XPath evaluator on the 1985 device. How the evaluation is done in practice is an implementation 1986 decision. 1988 7.5.3. The must's Substatements 1990 +---------------+---------+-------------+ 1991 | substatement | section | cardinality | 1992 +---------------+---------+-------------+ 1993 | description | 7.17.3 | 0..1 | 1994 | error-app-tag | 7.5.3.2 | 0..1 | 1995 | error-message | 7.5.3.1 | 0..1 | 1996 | reference | 7.17.4 | 0..1 | 1997 +---------------+---------+-------------+ 1999 7.5.3.1. The error-message Statement 2001 The "error-message" statement, which is optional, takes a string as 2002 an argument. If the constraint evaluates to false, the string is 2003 passed as in the . 2005 7.5.3.2. The error-app-tag Statement 2007 The "error-app-tag" statement, which is optional, takes a string as 2008 an argument. If the constraint evaluates to false, the string is 2009 passed as in the . 2011 7.5.3.3. Usage Example of must and error-message 2013 container interface { 2014 leaf ifType { 2015 type enumeration { 2016 enum ethernet; 2017 enum atm; 2018 } 2019 } 2020 leaf ifMTU { 2021 type uint32; 2022 } 2023 must "ifType != 'ethernet' or " + 2024 "(ifType = 'ethernet' and ifMTU = 1500)" { 2025 error-message "An ethernet MTU must be 1500"; 2026 } 2027 must "ifType != 'atm' or " + 2028 "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { 2029 error-message "An atm MTU must be 64 .. 17966"; 2030 } 2031 } 2033 7.5.4. The presence Statement 2035 The "presence" statement assigns a meaning to the presence of a 2036 container in the data tree. It takes as an argument a string which 2037 contains a textual description of what the node's presence means. 2039 If a container has the "presence" statement, the container's 2040 existence in the data tree carries some meaning. Otherwise, the 2041 container is used to give some structure to the data, and it carries 2042 no meaning by itself. 2044 See Section 5.6 for additional information. 2046 7.5.5. The container's Child Node Statements 2048 Within a container, the "container", "leaf", "list", "leaf-list", 2049 "uses", and "choice" statements can be used to define child nodes to 2050 the container. 2052 7.5.6. XML Encoding Rules 2054 A container node is encoded as an XML element. The element's name is 2055 the container's identifier, and its XML namespace is the module's XML 2056 namespace. 2058 The container's child nodes are encoded as subelements to the 2059 container element, in the same order as they are defined within the 2060 container statement. 2062 A NETCONF server that replies to a or request MAY 2063 choose not to send a container element if the container node does not 2064 have the "presence" statement and no child nodes exist. Thus, a 2065 client that receives an for a or 2066 request, must be prepared to handle the case that a container node 2067 without a presence statement is not present in the XML. 2069 7.5.7. NETCONF Operations 2071 When a NETCONF server processes an request, the 2072 elements of procedure for the container node are: 2074 If the operation is "merge" the node is created if it does not 2075 exist. 2077 If the operation is "replace" and the node exists, all child nodes 2078 not present in the XML are deleted, and child nodes present in the 2079 XML but not present in the datastore are created. 2081 If the operation is "create" the node is created if it does not 2082 exist. 2084 If the operation is "delete" the node is deleted if it exists. 2086 If the container has a "presence" statement, it may be implicitly 2087 created if it does not exist, even if the operation is "none". 2089 If a container has a "presence" statement and the last child node 2090 is deleted, the NETCONF server MAY delete the container. 2092 7.5.8. Usage Example 2094 Given the following container definition: 2096 container system { 2097 description "Contains various system parameters"; 2098 container services { 2099 description "Configure externally available services"; 2100 container "ssh" { 2101 presence "Enables SSH"; 2102 description "SSH service specific configuration"; 2103 // more leafs, containers and stuff here... 2104 } 2105 } 2106 } 2108 A corresponding XML encoding would look like this: 2110 2111 2112 2113 2114 2116 Since the element is present, ssh is enabled. 2118 To delete a container with an : 2120 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2137 7.6. The leaf Statement 2139 The "leaf" statement is used to define a leaf node in the schema 2140 tree. It takes one argument, which is an identifier, followed by a 2141 block of substatements that holds detailed leaf information. 2143 A leaf node has a value, but no child nodes in the data tree. 2145 A leaf node exists in zero or one instances in the data tree, 2146 depending on the value of the "mandatory" statement. 2148 The "leaf" statement is used to define a scalar variable of a 2149 particular built-in or derived type. 2151 If a leaf has a "default" statement, the leaf's default value is set 2152 to the value of the "default" statement. Otherwise, if the leaf's 2153 type has a default value, and the leaf is not mandatory, then the 2154 leaf's default value is set to the type's default value. In all 2155 other cases, the leaf does not have a default value. 2157 If the leaf has a default value, the server MUST use this value 2158 internally if no value is provided by the NETCONF client when the 2159 instance is created. 2161 7.6.1. The leaf's Substatements 2163 +--------------+---------+-------------+ 2164 | substatement | section | cardinality | 2165 +--------------+---------+-------------+ 2166 | config | 7.17.1 | 0..1 | 2167 | default | 7.6.3 | 0..1 | 2168 | description | 7.17.3 | 0..1 | 2169 | mandatory | 7.6.4 | 0..1 | 2170 | must | 7.5.2 | 0..n | 2171 | reference | 7.17.4 | 0..1 | 2172 | status | 7.17.2 | 0..1 | 2173 | type | 7.6.2 | 1 | 2174 | units | 7.3.3 | 0..1 | 2175 +--------------+---------+-------------+ 2177 7.6.2. The leaf's type Statement 2179 The "type" statement, which must be present, takes as an argument the 2180 name of an existing built-in or derived type. The optional 2181 substatements specify restrictions on this type. See Section 7.4 for 2182 details. 2184 7.6.3. The leaf's default Statement 2186 The "default" statement, which is optional, takes as an argument a 2187 string which contains a default value for the leaf. 2189 The value of the "default" statement MUST correspond to the type 2190 specified in the leaf's "type" statement. 2192 The "default" statement MUST NOT be present on nodes where 2193 "mandatory" is true. 2195 7.6.4. The leaf's mandatory Statement 2197 The "mandatory" statement, which is optional, takes as an argument 2198 the string "true" or "false". If "mandatory" is "true", the node 2199 must exist in a valid configuration if its parent node exists. Since 2200 containers without a "presence" statement are implicitly created and 2201 deleted when needed, they are ignored when performing mandatory tests 2202 for leafs. A mandatory leaf within such a container is mandatory 2203 even if the container's data node does not exist. 2205 If not specified, the default is "false". 2207 7.6.5. XML Encoding Rules 2209 A leaf node is encoded as an XML element. The element's name is the 2210 leaf's identifier, and its XML namespace is the module's XML 2211 namespace. 2213 The value of the leaf node is encoded to XML according to the type, 2214 and sent as character data in the element. 2216 A NETCONF server that replies to a or request MAY 2217 choose not to send the leaf element if its value is the default 2218 value. Thus, a client that receives an for a or 2219 request, must be prepared to handle the case that a leaf 2220 node with a default value is not present in the XML. In this case, 2221 the value used by the server is known to be the default value. 2223 See Section 7.6.7 for an example. 2225 7.6.6. NETCONF Operations 2227 When a NETCONF server processes an request, the 2228 elements of procedure for the leaf node are: 2230 If the operation is "merge", the node is created if it does not 2231 exist, and its value is set to the value found in the XML RPC 2232 data. 2234 If the operation is "replace", the node is created if it does not 2235 exist, and its value is set to the value found in the XML RPC 2236 data. 2238 If the operation is "create" the node is created if it does not 2239 exist. 2241 If the operation is "delete" the node is deleted if it exists. 2243 7.6.7. Usage Example 2245 Given the following leaf statement: 2247 leaf port { 2248 type inet:port-number; 2249 default 22; 2250 description "The port which the SSH server listens to" 2251 } 2253 A corresponding XML encoding: 2255 2022 2257 To create a leaf with an edit-config: 2259 2262 2263 2264 2265 2266 2267 2268 2269 2270 2022 2271 2272 2273 2274 2275 2276 2278 7.7. The leaf-list Statement 2280 Where the "leaf" statement is used to define a simple scalar variable 2281 of a particular type, the "leaf-list" statement is used to define an 2282 array of a particular type. The "leaf-list" statement takes one 2283 argument, which is an identifier, followed by a block of 2284 substatements that holds detailed leaf-list information. 2286 The values in a leaf-list MUST be unique. 2288 If the type referenced by the leaf-list has a default value, it has 2289 no effect in the leaf-list. 2291 7.7.1. The leaf-list's Substatements 2293 +--------------+---------+-------------+ 2294 | substatement | section | cardinality | 2295 +--------------+---------+-------------+ 2296 | config | 7.17.1 | 0..1 | 2297 | description | 7.17.3 | 0..1 | 2298 | max-elements | 7.7.3 | 0..1 | 2299 | min-elements | 7.7.2 | 0..1 | 2300 | must | 7.5.2 | 0..n | 2301 | ordered-by | 7.7.4 | 0..1 | 2302 | reference | 7.17.4 | 0..1 | 2303 | status | 7.17.2 | 0..1 | 2304 | type | 7.4 | 1 | 2305 | units | 7.3.3 | 0..1 | 2306 +--------------+---------+-------------+ 2308 7.7.2. The min-elements Statement 2310 The "min-elements" statement, which is optional, takes as an argument 2311 a non-negative integer which puts a constraint on a valid 2312 configuration. A valid configuration always has at least min- 2313 elements values in the leaf-list or list. 2315 If no "min-elements" statement is present, it defaults to zero. 2317 7.7.3. The max-elements Statement 2319 The "max-elements" statement, which is optional, takes as an argument 2320 a positive integer or the string "unbounded", which puts a constraint 2321 on a valid configuration. A valid configuration always has at most 2322 max-elements values in the leaf-list or list. 2324 If no "max-elements" statement is present, it defaults to 2325 "unbounded". 2327 7.7.4. The ordered-by Statement 2329 The "ordered-by" statement defines whether the order of entries 2330 within a list are determined by the user or the system. The argument 2331 is one of the strings "system" or "user". If not present, order 2332 defaults to "system". 2334 See Section 5.5 for additional information. 2336 7.7.4.1. ordered-by system 2338 The entries in the list are sorted according to an unspecified order. 2339 Thus an implementation is free to sort the entries in the most 2340 appropriate order. An implementation SHOULD use the same order for 2341 the same data, regardless of how the data were created. Using a 2342 deterministic order will makes comparisons possible using simple 2343 tools like "diff". 2345 This is the default order. 2347 7.7.4.2. ordered-by user 2349 The entries in the list are sorted according to an order defined by 2350 the user. This order is controlled by using special XML attributes 2351 in the request. See Section 7.7.6 for details. 2353 7.7.5. XML Encoding Rules 2355 A leaf-list node is encoded as a series of XML elements. Each 2356 element's name is the leaf-list's identifier, and its XML namespace 2357 is the module's XML namespace. 2359 The value of the leaf-list node is encoded to XML according to the 2360 type, and sent as character data in the element. 2362 See Section 7.7.7 for an example. 2364 7.7.6. NETCONF operations 2366 Leaf-list entries can be created and deleted, but not modified, 2367 through , by using the "operation" attribute in the 2368 leaf-list entry's XML element. 2370 In an "ordered-by user" leaf-list, the attributes "insert" and 2371 "value" in the YANG namespace (Section 5.4.1) can be used to control 2372 where in the leaf-list the entry is inserted. These can be used 2373 during "create" operations to insert a new leaf-list entry, or during 2374 "merge" or "replace" operations to insert a new leaf-list entry or 2375 move an existing one. 2377 The "insert" attribute can take the values "first", "last", "before", 2378 and "after". If the value is "before" or "after", the "value" 2379 attribute must also be used to specify an existing entry in the leaf- 2380 list. 2382 If no "insert" attribute is present in the "create" operation, it 2383 defaults to "last". 2385 In a , or an with a "replace" operation 2386 which covers the entire leaf-list, the leaf-list order is the same as 2387 the order of the XML elements in the request. 2389 When a NETCONF server processes an request, the 2390 elements of procedure for a leaf-list node are: 2392 If the operation is "merge" or "replace" the leaf-list entry is 2393 created if it does not exist. 2395 If the operation is "create" the leaf-list entry is created if it 2396 does not exist. 2398 If the operation is "delete" the entry is deleted from the leaf- 2399 list if it exists. 2401 7.7.7. Usage Example 2403 leaf-list allow-user { 2404 type string; 2405 description "A list of user name patterns to allow"; 2406 } 2408 A corresponding XML encoding: 2410 alice 2411 bob 2413 To create a new element in the list: 2415 2418 2419 2420 2421 2422 2423 2424 2425 2426 eric 2427 2428 2429 2430 2431 2432 2434 Given the following ordered-by user leaf-list: 2436 leaf-list ciphers { 2437 type string; 2438 ordered-by user; 2439 description "A list of ciphers"; 2440 } 2442 The following would be used to insert a new cipher "blowfish-cbc" 2443 after "3des-cbc": 2445 2449 2450 2451 2452 2453 2454 2455 2456 2457 blowfish-cbc 2460 2461 2462 2463 2464 2465 2467 7.8. The list Statement 2469 The "list" statement is used to define interior nodes in the schema 2470 tree. A list node may exist in multiple instances in the data tree. 2471 Each such instance is known as a list entry. The "list" statement 2472 takes one argument which is an identifier, followed by a block of 2473 substatements that holds detailed list information. 2475 A list entry is uniquely identified by the values of the list's keys. 2477 A list is similar to a table where each list entry is a row in the 2478 table. 2480 7.8.1. The list's Substatements 2482 +--------------+---------+-------------+ 2483 | substatement | section | cardinality | 2484 +--------------+---------+-------------+ 2485 | anyxml | 7.10 | 0..n | 2486 | augment | 7.15 | 0..n | 2487 | choice | 7.9 | 0..n | 2488 | config | 7.17.1 | 0..1 | 2489 | container | 7.5 | 0..n | 2490 | description | 7.17.3 | 0..1 | 2491 | grouping | 7.11 | 0..n | 2492 | key | 7.8.2 | 0..1 | 2493 | leaf | 7.6 | 0..n | 2494 | leaf-list | 7.7 | 0..n | 2495 | list | 7.8 | 0..n | 2496 | max-elements | 7.7.3 | 0..1 | 2497 | min-elements | 7.7.2 | 0..1 | 2498 | must | 7.5.2 | 0..n | 2499 | ordered-by | 7.7.4 | 0..1 | 2500 | reference | 7.17.4 | 0..1 | 2501 | status | 7.17.2 | 0..1 | 2502 | typedef | 7.3 | 0..n | 2503 | unique | 7.8.3 | 0..n | 2504 | uses | 7.12 | 0..n | 2505 +--------------+---------+-------------+ 2507 7.8.2. The list's key Statement 2509 The "key" statement, which MUST be present if the list represents 2510 configuration, and MAY be present otherwise, takes as an argument a 2511 string which specifies a space separated list of leaf identifiers of 2512 this list. A leaf identifier MUST NOT appear more than once in the 2513 key. Each such leaf identifier MUST refer to a child leaf of the 2514 list. 2516 The combined values of all the leafs specified in the key are used to 2517 uniquely identify a list entry. All key leafs MUST be given values 2518 when a list entry is created. Thus, any default values in the key 2519 leafs or their types are ignored. It also implies that any mandatory 2520 statement in the key leafs are ignored. 2522 A leaf that is part of the key can be of any built-in or derived 2523 type, except it MUST NOT be the built-in type "empty". 2525 All key leafs in a list MUST have the same value for their "config" 2526 as the list itself. 2528 The key string syntax is formally defined by the rule "key-arg" in 2529 Section 11. 2531 7.8.3. The lists's unique Statement 2533 The "unique" statement is used to put constraints on valid 2534 configurations. It takes as an argument a string which contains a 2535 space separated list of schema node identifiers, which MUST be given 2536 in the descendant form (see the rule "descendant-schema-nodeid" in 2537 Section 11). Each such schema node identifier MUST refer to a leaf. 2539 In a valid configuration, the combined values of all the leaf 2540 instances specified in the string MUST be unique within all list 2541 entry instances. 2543 The unique string syntax is formally defined by the rule "unique-arg" 2544 in Section 11. 2546 7.8.3.1. Usage Example 2548 With the following list: 2550 list server { 2551 key "name"; 2552 unique "ip port"; 2553 leaf name { 2554 type string; 2555 } 2556 leaf ip { 2557 type inet:ip-address; 2558 } 2559 leaf port { 2560 type inet:port-number; 2561 } 2562 } 2564 The following configuration is not valid: 2566 2567 smtp 2568 192.0.2.1 2569 25 2570 2572 2573 http 2574 192.0.2.1 2575 25 2577 2579 7.8.4. The list's Child Node Statements 2581 Within a list, the "container", "leaf", "list", "leaf-list", "uses", 2582 and "choice" statements can be used to define child nodes to the 2583 list. 2585 7.8.5. XML Encoding Rules 2587 A list is encoded as a series of XML elements, one for each entry in 2588 the list. Each element's name is the list's identifier, and its XML 2589 namespace is the module's XML namespace. 2591 The list's key nodes are encoded as subelements to the list's 2592 identifier element, in the same order as they are defined within the 2593 key statement. 2595 The rest of the list's child nodes are encoded as subelements to the 2596 list element, after the keys, in the same order as they are defined 2597 within the list statement. 2599 7.8.6. NETCONF operations 2601 List entries can be created, deleted, replaced and modified through 2602 , by using the "operation" attribute in the list's XML 2603 element. In each case, the values of all keys are used to uniquely 2604 identify a list entry. If all keys are not specified for a list 2605 entry, a "missing-element" error is returned. 2607 In an "ordered-by user" list, the attributes "insert" and "key" in 2608 the YANG namespace (Section 5.4.1) can be used to control where in 2609 the list the entry is inserted. These can be used during "create" 2610 operations to insert a new list entry, or during "merge" or "replace" 2611 operations to insert a new list entry or move an existing one. 2613 The "insert" attribute can take the values "first", "last", "before", 2614 and "after". If the value is "before" or "after", the "key" 2615 attribute must also be used, to specify an existing element in the 2616 list. The value of the "key" attribute is the key predicates of the 2617 full instance identifier (see Section 8.11) for the list entry. 2619 If no "insert" attribute is present in the "create" operation, it 2620 defaults to "last". 2622 In a , or an with a "replace" operation 2623 which covers the entire list, the list entry order is the same as the 2624 order of the XML elements in the request. 2626 7.8.7. Usage Example 2628 Given the following list: 2630 list user { 2631 key "name"; 2632 config true; 2633 description "This is a list of users in the system."; 2635 leaf name { 2636 type string; 2637 } 2638 leaf type { 2639 type string; 2640 } 2641 leaf full-name { 2642 type string; 2643 } 2644 } 2646 A corresponding XML encoding: 2648 2649 fred 2650 admin 2651 Fred Flintstone 2652 2654 To create a new user "barney": 2656 2659 2660 2661 2662 2663 2664 2665 2666 barney 2667 admin 2668 Barney Rubble 2669 2670 2671 2672 2673 2675 To change the type of "fred" to "superuser": 2677 2680 2681 2682 2683 2684 2685 2686 2687 fred 2688 superuser 2689 2690 2691 2692 2693 2695 Given the following ordered-by user list: 2697 list user { 2698 description "This is a list of users in the system."; 2699 ordered-by user; 2700 config true; 2702 key "name"; 2704 leaf name { 2705 type string; 2706 } 2707 leaf type { 2708 type string; 2709 } 2710 leaf full-name { 2711 type string; 2712 } 2713 } 2715 The following would be used to insert a new user "barney" after the 2716 user "fred": 2718 2722 2723 2724 2725 2726 2727 2729 2732 barney 2733 admin 2734 Barney Rubble 2735 2736 2737 2738 2739 2741 The following would be used to move the user "barney" before the user 2742 "fred": 2744 2748 2749 2750 2751 2752 2753 2755 2758 barney 2759 2760 2761 2762 2763 2765 7.9. The choice Statement 2767 The "choice" statement defines a set of alternatives, only one of 2768 which may exist at any one time. The argument is an identifier, 2769 followed by a block of substatements that holds detailed choice 2770 information. The identifier is used to identify the choice node in 2771 the schema tree. A choice node does not exist in the data tree. 2773 A choice consists of a number of branches, defined with the case 2774 substatement. Each branch contains a number of child nodes. The 2775 "choice" statement puts a constraint on a valid configuration. In a 2776 valid configuration, the nodes from at most one of the choice's 2777 branches exist at the same time. 2779 See Section 4.2.7 for additional information. 2781 7.9.1. The choice's Substatements 2783 +--------------+---------+-------------+ 2784 | substatement | section | cardinality | 2785 +--------------+---------+-------------+ 2786 | anyxml | 7.10 | 0..n | 2787 | case | 7.9.2 | 0..n | 2788 | config | 7.17.1 | 0..1 | 2789 | container | 7.5 | 0..n | 2790 | default | 7.9.3 | 0..1 | 2791 | description | 7.17.3 | 0..1 | 2792 | leaf | 7.6 | 0..n | 2793 | leaf-list | 7.7 | 0..n | 2794 | list | 7.8 | 0..n | 2795 | mandatory | 7.9.4 | 0..1 | 2796 | reference | 7.17.4 | 0..1 | 2797 | status | 7.17.2 | 0..1 | 2798 +--------------+---------+-------------+ 2800 7.9.2. The choice's case Statement 2802 The "case" statement is used to define branches of the choice. It 2803 takes as an argument an identifier, followed by a block of 2804 substatements that holds detailed case information. 2806 The identifier is used to identify the case node in the schema tree. 2807 A case node does not exist in the data tree. 2809 Within a "case" statement, the "anyxml", "container", "leaf", "list", 2810 "leaf-list", "uses", and "augment" statements can be used to define 2811 child nodes to the case node. The identifiers of all these child 2812 nodes must be unique within all cases in a choice. For example, the 2813 following is illegal: 2815 choice interface-type { // This example is illegal YANG 2816 case a { 2817 leaf ethernet { ... } 2818 } 2819 case b { 2820 container ethernet { ...} 2821 } 2822 } 2824 As a shorthand, the "case" statement can be omitted if the branch 2825 contains a single "anyxml", "container", "leaf", "list", or "leaf- 2826 list" statement. In this case, the identifier of the case node is 2827 the same as the identifier in the branch statement. The following 2828 example: 2830 choice interface-type { 2831 container ethernet { ... } 2832 } 2834 is equivalent to: 2836 choice interface-type { 2837 case ethernet { 2838 container ethernet { ... } 2839 } 2840 } 2842 The case identifier MUST be unique within a choice. 2844 7.9.2.1. The case's Substatements 2846 +--------------+---------+-------------+ 2847 | substatement | section | cardinality | 2848 +--------------+---------+-------------+ 2849 | anyxml | 7.10 | 0..n | 2850 | augment | 7.15 | 0..n | 2851 | container | 7.5 | 0..n | 2852 | description | 7.17.3 | 0..1 | 2853 | leaf | 7.6 | 0..n | 2854 | leaf-list | 7.7 | 0..n | 2855 | list | 7.8 | 0..n | 2856 | reference | 7.17.4 | 0..1 | 2857 | status | 7.17.2 | 0..1 | 2858 | uses | 7.12 | 0..n | 2859 +--------------+---------+-------------+ 2861 7.9.3. The choice's default Statement 2863 The "default" statement indicates if a case should be considered as 2864 the default if no child nodes from any of the choice's cases exists. 2865 The argument is the identifier of the "case" statement. If the 2866 "default" statement is missing, there is no default case. 2868 The "default" statement MUST NOT be present on choices where 2869 "mandatory" is true. 2871 The default case is only important when considering the default 2872 values of nodes under the cases. The default values for nodes under 2873 the default case are used if none of the nodes under any of the cases 2874 are present. 2876 There MUST NOT be any mandatory nodes (Section 3.1) under the default 2877 case. 2879 Default values for child nodes under a case are only used if one of 2880 the nodes under that case is present, or if that case is the default 2881 case. If none of the nodes under a case are present and the case is 2882 not the default case, the default values of the cases' child nodes 2883 are ignored. 2885 In this example, the choice defaults to "interval", and the default 2886 value will be used if none of "daily", "time-of-day", or "manual" are 2887 present. If "daily" is present, the default value for "time-of-day" 2888 will be used. 2890 container transfer { 2891 choice how { 2892 default interval; 2893 case interval { 2894 leaf interval { 2895 type uint16; 2896 default 30; 2897 units minutes; 2898 } 2899 } 2900 case daily { 2901 leaf daily { 2902 type empty; 2903 } 2904 leaf time-of-day { 2905 type string; 2906 units 24-hour-clock; 2907 default 1am; 2908 } 2909 } 2910 case manual { 2911 leaf manual { 2912 type empty; 2913 } 2914 } 2915 } 2916 } 2918 7.9.4. The choice's mandatory Statement 2920 The "mandatory" statement, which is optional, takes as an argument 2921 the string "true" or "false". If "mandatory" is "true", at least one 2922 node from exactly one of the choice's case branches MUST exist in a 2923 valid configuration. If "mandatory" is "false", a valid 2924 configuration MAY have no nodes from the choice's case branches 2925 present. 2927 If not specified, the default is "false". 2929 7.9.5. XML Encoding Rules 2931 The choice and case nodes are not visible in XML. 2933 7.9.6. NETCONF operations 2935 Since only one of the choices cases can be valid at any time, the 2936 creation of a node from one case implicitly deletes all nodes from 2937 all other cases. If an operation creates a node, the 2938 NETCONF server will delete any existing nodes that are defined in 2939 other cases inside the choice. 2941 7.9.7. Usage Example 2943 Given the following choice: 2945 container protocol { 2946 choice name { 2947 case a { 2948 leaf udp { 2949 type empty; 2950 } 2951 } 2952 case b { 2953 leaf tcp { 2954 type empty; 2955 } 2956 } 2957 } 2958 } 2960 A corresponding XML encoding: 2962 2963 2964 2966 To change the protocol from tcp to udp: 2968 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2985 7.10. The anyxml Statement 2987 The "anyxml" statement defines an interior node in the schema tree. 2988 It takes one argument, which is an identifier, followed by a block of 2989 substatements that holds detailed anyxml information. 2991 The anyxml statement is used to represent an unknown chunk of XML. 2992 No restrictions are placed on the XML. This can be useful in e.g. 2993 RPC replies. An example is the parameter in the operation. 2996 An anyxml node cannot be augmented. 2998 It is NOT RECOMMENDED that the anyxml statement is used to represent 2999 configuration data. 3001 7.10.1. The anyxml's Substatements 3003 +--------------+---------+-------------+ 3004 | substatement | section | cardinality | 3005 +--------------+---------+-------------+ 3006 | config | 7.17.1 | 0..1 | 3007 | description | 7.17.3 | 0..1 | 3008 | mandatory | 7.6.4 | 0..1 | 3009 | reference | 7.17.4 | 0..1 | 3010 | status | 7.17.2 | 0..1 | 3011 +--------------+---------+-------------+ 3013 7.10.2. XML Encoding Rules 3015 An anyxml node is encoded as an XML element. The element's name is 3016 the anyxml's identifier, and its XML namespace is the module's XML 3017 namespace. The value of the anyxml node is encoded as XML content of 3018 this element. 3020 Note that any prefixes used in the encoding are local to each 3021 instance encoding. This means that the same XML may be encoded 3022 differently by different implementations. 3024 7.10.3. NETCONF operations 3026 An anyxml node is treated as an opaque chunk of data. This data can 3027 be modified in its entirety only. 3029 Any "operation" attributes within the XML value of an anyxml node are 3030 ignored by the NETCONF server. 3032 When a NETCONF server processes an request, the 3033 elements of procedure for the anyxml node are: 3035 If the operation is "merge", the node is created if it does not 3036 exist, and its value is set to the XML content of the anyxml node 3037 found in the XML RPC data. 3039 If the operation is "replace", the node is created if it does not 3040 exist, and its value is set to the XML content of the anyxml node 3041 found in the XML RPC data. 3043 If the operation is "create" the node is created if it does not 3044 exist, and its value is set to the XML content of the anyxml node 3045 found in the XML RPC data. 3047 If the operation is "delete" the node is deleted if it exists. 3049 7.10.4. Usage Example 3051 Given the following anyxml statement: 3053 anyxml data; 3055 The following are two valid encodings of the same anyxml value: 3057 3058 3059 1 3060 3061 3063 3064 3065 1 3066 3067 3069 7.11. The grouping Statement 3071 The "grouping" statement is used to define a reusable block of nodes, 3072 which may be used locally in the module, in modules which include it, 3073 and by other modules which import from it. It takes one argument 3074 which is an identifier, followed by a block of substatements that 3075 holds detailed grouping information. 3077 The grouping statement is not a data definition statement and, as 3078 such, does not define any nodes in the schema tree. 3080 A grouping is like a "structure" or a "record" in conventional 3081 programming languages. 3083 Once a grouping is defined, it can be referenced in a "uses" 3084 statement (see Section 7.12). A grouping MUST NOT reference itself, 3085 neither directly nor indirectly through a chain of other groupings. 3087 If the grouping is defined at the top level of a YANG module or 3088 submodule, the grouping's identifier MUST be unique within the 3089 module. For details about scoping for nested groupings, see 3090 Section 5.8. 3092 A grouping is more than just a mechanism for textual substitution, 3093 but defines a collection of nodes. References from inside the 3094 grouping are relative to the scope in which the grouping is defined, 3095 not where it is used. Prefix mappings, type names, grouping names, 3096 and extension usage are evaluated in the hierarchy where the grouping 3097 statement appears. For extensions, this means that extensions are 3098 applied to the grouping node, not the use node. 3100 7.11.1. The grouping's Substatements 3102 +--------------+---------+-------------+ 3103 | substatement | section | cardinality | 3104 +--------------+---------+-------------+ 3105 | anyxml | 7.10 | 0..n | 3106 | augment | 7.15 | 0..n | 3107 | choice | 7.9 | 0..n | 3108 | container | 7.5 | 0..n | 3109 | description | 7.17.3 | 0..1 | 3110 | grouping | 7.11 | 0..n | 3111 | leaf | 7.6 | 0..n | 3112 | leaf-list | 7.7 | 0..n | 3113 | list | 7.8 | 0..n | 3114 | reference | 7.17.4 | 0..1 | 3115 | status | 7.17.2 | 0..1 | 3116 | typedef | 7.3 | 0..n | 3117 | uses | 7.12 | 0..n | 3118 +--------------+---------+-------------+ 3120 7.11.2. Usage Example 3122 import inet-types { 3123 prefix "inet"; 3124 } 3126 grouping address { 3127 description "A reusable address group."; 3128 leaf ip { 3129 type inet:ip-address; 3130 } 3131 leaf port { 3132 type inet:port-number; 3133 } 3134 } 3136 7.12. The uses Statement 3138 The "uses" statement is used to reference a "grouping" definition. 3139 It takes one argument, which is the name of the grouping. 3141 The effect of a "uses" reference to a grouping is that the nodes 3142 defined by the grouping are copied into the current schema tree, and 3143 then updated according to the refinement statements. Thus, the 3144 identifiers defined in the grouping are copied into the current 3145 module's namespace, even if the grouping is imported from some other 3146 module. 3148 7.12.1. The uses's Substatements 3150 +--------------+---------+-------------+ 3151 | substatement | section | cardinality | 3152 +--------------+---------+-------------+ 3153 | anyxml | 7.10 | 0..n | 3154 | choice | 7.9 | 0..n | 3155 | container | 7.5 | 0..n | 3156 | description | 7.17.3 | 0..1 | 3157 | leaf | 7.6 | 0..n | 3158 | leaf-list | 7.7 | 0..n | 3159 | list | 7.8 | 0..n | 3160 | reference | 7.17.4 | 0..1 | 3161 | status | 7.17.2 | 0..1 | 3162 | uses | 7.12 | 0..n | 3163 +--------------+---------+-------------+ 3165 7.12.2. The uses's Refinement Statements 3167 Some of the properties of each node in the grouping can be refined in 3168 substatements to "uses". If a node is not present in a substatement, 3169 it is not refined, and thus used exactly as it was defined in the 3170 "grouping". A node can be refined only once in "uses". 3172 The following refinements can be done: 3174 o A leaf or choice node may get a default value, or a new default 3175 value if it already had one. 3177 o Any node may get a specialized "description" string. 3179 o Any node may get a specialized "reference" string. 3181 o Any node may get a different "config" statement. 3183 o A leaf or choice node may get a different "mandatory" statement. 3185 o A container node may get a "presence" statement. 3187 o A leaf, leaf-list, list or container node may get additional 3188 "must" expressions. 3190 o A leaf-list or list node may get a different "min-elements" or 3191 "max-elements" statement. 3193 7.12.3. XML Encoding Rules 3195 Each node in the grouping is encoded as if it was defined inline, 3196 even if it is imported from another module with another XML 3197 namespace. 3199 7.12.4. Usage Example 3201 To use the "address" grouping defined in Section 7.11.2 in a 3202 definition of an HTTP server in some other module, we can do: 3204 import acme-system { 3205 prefix acme; 3206 } 3208 container http-server { 3209 leaf name { 3210 type string; 3211 } 3212 uses acme:address; 3213 } 3215 A corresponding XML encoding: 3217 3218 extern-web 3219 192.0.2.1 3220 80 3221 3223 If port 80 should be the default for the HTTP server, default can be 3224 added: 3226 container http-server { 3227 leaf name { 3228 type string; 3229 } 3230 uses acme:address { 3231 leaf port { 3232 default 80; 3233 } 3234 } 3235 } 3237 If we want to define a list of servers, and each server has the ip 3238 and port as keys, we can do: 3240 list server { 3241 key "ip port"; 3242 leaf name { 3243 type string; 3244 } 3245 uses acme:address; 3246 } 3248 The following is an error: 3250 container http-server { 3251 uses acme:address; 3252 leaf ip { // illegal - same identifier "ip" used twice 3253 type string; 3254 } 3255 } 3257 7.13. The rpc Statement 3259 The "rpc" statement is used to define a NETCONF RPC method. It takes 3260 one argument, which is an identifier, followed by a block of 3261 substatements that holds detailed rpc information. This argument is 3262 the name of the RPC, and is used as the element name directly under 3263 the element, as designated by the substitution group 3264 "rpcOperation" in [RFC4741]. 3266 The "rpc" statement defines an rpc node in the schema tree. Under 3267 the rpc node, an input node with the name "input", and an output node 3268 with the name "output" are also defined. The nodes "input" and 3269 "output" are defined in the module's namespace. 3271 7.13.1. The rpc's Substatements 3273 +--------------+---------+-------------+ 3274 | substatement | section | cardinality | 3275 +--------------+---------+-------------+ 3276 | description | 7.17.3 | 0..1 | 3277 | grouping | 7.11 | 0..n | 3278 | input | 7.13.2 | 0..1 | 3279 | output | 7.13.3 | 0..1 | 3280 | reference | 7.17.4 | 0..1 | 3281 | status | 7.17.2 | 0..1 | 3282 | typedef | 7.3 | 0..n | 3283 +--------------+---------+-------------+ 3285 7.13.2. The input Statement 3287 The "input" statement, which is optional, is used to define input 3288 parameters to the RPC method. It does not take an argument. The 3289 substatements to "input" defines nodes under the RPC's input node. 3291 If a container in the input tree has a "presence" statement, the 3292 container need not be present in a NETCONF RPC invocation. 3294 If a leaf in the input tree has a "mandatory" statement with the 3295 value "true", the leaf MUST be present in a NETCONF RPC invocation. 3297 If a leaf in the input tree has a default value, the NETCONF server 3298 MUST internally use this default if the leaf is not present in a 3299 NETCONF RPC invocation. 3301 If a "config" or "must" statement is present for any node in the 3302 input tree, it is ignored. 3304 7.13.2.1. The input's Substatements 3306 +--------------+---------+-------------+ 3307 | substatement | section | cardinality | 3308 +--------------+---------+-------------+ 3309 | anyxml | 7.10 | 0..n | 3310 | augment | 7.15 | 0..n | 3311 | choice | 7.9 | 0..n | 3312 | container | 7.5 | 0..n | 3313 | grouping | 7.11 | 0..n | 3314 | leaf | 7.6 | 0..n | 3315 | leaf-list | 7.7 | 0..n | 3316 | list | 7.8 | 0..n | 3317 | typedef | 7.3 | 0..n | 3318 | uses | 7.12 | 0..n | 3319 +--------------+---------+-------------+ 3321 7.13.3. The output Statement 3323 The "output" statement, which is optional, is used to define output 3324 parameters to the RPC method. It does not take an argument. The 3325 substatements to "output" defines nodes under the RPC's output node. 3327 If a container in the output tree has a "presence" statement, the 3328 container need not be present in a NETCONF RPC reply 3330 If a leaf in the output tree has a "mandatory" statement with the 3331 value "true", the leaf MUST be present in a NETCONF RPC reply. 3333 If a leaf in the output tree has a default value, the NETCONF client 3334 MUST internally use this default if the leaf is not present in a 3335 NETCONF RPC reply. 3337 If a "config" or "must" statement is present for any node in the 3338 output tree, it is ignored. 3340 7.13.3.1. The output's Substatements 3342 +--------------+---------+-------------+ 3343 | substatement | section | cardinality | 3344 +--------------+---------+-------------+ 3345 | anyxml | 7.10 | 0..n | 3346 | augment | 7.15 | 0..n | 3347 | choice | 7.9 | 0..n | 3348 | container | 7.5 | 0..n | 3349 | grouping | 7.11 | 0..n | 3350 | leaf | 7.6 | 0..n | 3351 | leaf-list | 7.7 | 0..n | 3352 | list | 7.8 | 0..n | 3353 | typedef | 7.3 | 0..n | 3354 | uses | 7.12 | 0..n | 3355 +--------------+---------+-------------+ 3357 7.13.4. XML Encoding Rules 3359 An rpc node is encoded as a child XML element to the element 3360 defined in [RFC4741]. The element's name is the rpc's identifier, 3361 and its XML namespace is the module's XML namespace. 3363 Input parameters are encoded as child XML elements to the rpc node's 3364 XML element, in the same order as they are defined within the input 3365 statement. 3367 If the rpc method invocation succeeded, and no output parameters are 3368 returned, the contains a single element defined in 3369 [RFC4741]. If output parameters are returned, they are encoded as 3370 child elements to the element defined in [RFC4741], in 3371 the same order as they are defined within the output statement. 3373 7.13.5. Usage Example 3375 The following example defines an RPC method: 3377 module rock { 3378 namespace "http://example.net/rock"; 3379 prefix rock; 3381 rpc rock-the-house { 3382 input { 3383 leaf zip-code { 3384 type string; 3385 } 3386 } 3387 } 3389 } 3391 A corresponding XML encoding of the complete rpc and rpc-reply: 3393 3395 3396 27606-0100 3397 3398 3400 3402 3403 3405 7.14. The notification Statement 3407 The "notification" statement is used to define a NETCONF 3408 notification. It takes one argument, which is an identifier, 3409 followed by a block of substatements that holds detailed notification 3410 information. The notification "statement" defines a notification 3411 node in the schema tree. 3413 If a container in the notification tree has a "presence" statement, 3414 the container need not be present in a NETCONF notification. 3416 If a leaf in the notification tree has a "mandatory" statement with 3417 the value "true", the leaf MUST be present in a NETCONF notification. 3419 If a leaf in the notification tree has a default value, the NETCONF 3420 server MUST internally use this default if the leaf is not present in 3421 a NETCONF notification. 3423 If a "config" or "must" statement is present for any node in the 3424 notification tree, it is ignored. 3426 7.14.1. The notification's Substatements 3428 +--------------+---------+-------------+ 3429 | substatement | section | cardinality | 3430 +--------------+---------+-------------+ 3431 | anyxml | 7.10 | 0..n | 3432 | augment | 7.15 | 0..n | 3433 | choice | 7.9 | 0..n | 3434 | container | 7.5 | 0..n | 3435 | description | 7.17.3 | 0..1 | 3436 | grouping | 7.11 | 0..n | 3437 | leaf | 7.6 | 0..n | 3438 | leaf-list | 7.7 | 0..n | 3439 | list | 7.8 | 0..n | 3440 | reference | 7.17.4 | 0..1 | 3441 | status | 7.17.2 | 0..1 | 3442 | typedef | 7.3 | 0..n | 3443 | uses | 7.12 | 0..n | 3444 +--------------+---------+-------------+ 3446 7.14.2. XML Encoding Rules 3448 A notification node is encoded as a child XML element to the 3449 element defined in [RFC5277]. The element's name is 3450 the notification's identifier, and its XML namespace is the module's 3451 XML namespace. 3453 The notifications's child nodes are encoded as subelements to the 3454 notification node's XML element, in the same order as they are 3455 defined within the notification statement. 3457 7.14.3. Usage Example 3459 The following example defines a notification: 3461 module event { 3463 namespace "http://example.com/event"; 3464 prefix ev; 3466 notification event { 3467 leaf event-class { 3468 type string; 3469 } 3470 anyxml reporting-entity; 3471 leaf severity { 3472 type string; 3473 } 3474 } 3475 } 3477 A corresponding XML encoding of the complete notification: 3479 3481 2008-07-08T00:01:00Z 3482 3483 fault 3484 3485 Ethernet0 3486 3487 major 3488 3489 3491 7.15. The augment Statement 3493 The "augment" statement allows a module or submodule to add to the 3494 schema tree defined in another module or submodule. The argument is 3495 a string which identifies a node in the schema tree. This node is 3496 called the augment's target node. The target node MUST be either a 3497 container, list, choice, case, input, output, or notification node. 3498 It is augmented with the nodes defined in the substatements that 3499 follow the "augment" statement. 3501 The augment string is a schema node identifier. The syntax is 3502 formally defined by the rule "augment-arg" in Section 11. If the 3503 "augment" statement is on the top-level in a module or submodule, the 3504 absolute form (defined by the rule "absolute-schema-nodeid" in 3505 Section 11) of a schema node identifier MAY be used. Otherwise, the 3506 descendant form (defined by the rule "descendant-schema-nodeid" in 3507 Section 11) MUST be used. 3509 The syntax for a schema node identifier is a subset of the XPath 3510 syntax. It is an absolute or relative XPath location path in 3511 abbreviated syntax, where axes and predicates are not permitted. 3513 If the target node is a container, list, case, input, output, or 3514 notification node, the "container", "leaf", "list", "leaf-list", 3515 "uses", and "choice" statements can be used within the "augment" 3516 statement. 3518 If the target node is a choice node, the "case" statement can be used 3519 within the "augment" statement. 3521 If the target node is in another module, then nodes added by the 3522 augmentation MUST NOT be mandatory nodes (see Section 3.1). 3524 7.15.1. The augment's Substatements 3526 +--------------+---------+-------------+ 3527 | substatement | section | cardinality | 3528 +--------------+---------+-------------+ 3529 | anyxml | 7.10 | 0..n | 3530 | augment | 7.15 | 0..n | 3531 | case | 7.9.2 | 0..n | 3532 | choice | 7.9 | 0..n | 3533 | container | 7.5 | 0..n | 3534 | description | 7.17.3 | 0..1 | 3535 | leaf | 7.6 | 0..n | 3536 | leaf-list | 7.7 | 0..n | 3537 | list | 7.8 | 0..n | 3538 | reference | 7.17.4 | 0..1 | 3539 | status | 7.17.2 | 0..1 | 3540 | uses | 7.12 | 0..n | 3541 | when | 7.15.2 | 0..1 | 3542 +--------------+---------+-------------+ 3544 7.15.2. The when Statement 3546 The "when" statement allows the augmentation to be conditional, with 3547 the nodes only being valid when a specific criteria is satisfied. 3548 The statement's argument is an XPath expression, which is used to 3549 formally specify constraints on which instances in the data tree will 3550 be augmented by this statement. If the XPath expression conceptually 3551 evaluates to "true" for a particular instance, then it is augmented, 3552 otherwise it is not. 3554 The XPath expression is conceptually evaluated in the following 3555 context: 3557 o The context node is the augment's target node in the data tree, if 3558 the target node is a data node. Otherwise, the context node is 3559 the closest ancestor node to the target node which is also a data 3560 node. 3562 o The accessible tree is made up of all nodes in the data tree, and 3563 all leafs with default values. 3565 o The set of namespace declarations is the set of all "import" 3566 statements' prefix and namespace pairs, and the "prefix" 3567 statement's prefix for the "namespace" statement's URI. 3569 o Elements without a namespace refer to nodes in the current module. 3571 o The function library is the core function library defined in 3572 [XPATH], and a function "current()" which returns a node set with 3573 the initial context node. 3575 The result of the XPath expression is converted to a boolean value 3576 using the standard XPath rules. 3578 Note that the XPath expression is conceptually evaluated. This means 3579 that an implementation does not have to use an XPath evaluator on the 3580 device. The augment can very well be implemented with specially 3581 written code. 3583 7.15.3. XML Encoding Rules 3585 All data nodes defined in the "augment" statement are defined as XML 3586 elements in the XML namespace of the module where the "augment" is 3587 specified. 3589 When a node is augmented, the augmented child nodes are encoded after 3590 all normal child nodes. If the node is augmented more than once, the 3591 blocks of augmented child nodes are sorted (in alphanumeric order) 3592 according to their namespace URI and name of the first child node in 3593 each block. 3595 7.15.4. Usage Example 3597 In namespace http://example.com/schema/interfaces, we have: 3599 container interfaces { 3600 list ifEntry { 3601 key "ifIndex"; 3603 leaf ifIndex { 3604 type uint32; 3605 } 3606 leaf ifDescr { 3607 type string; 3608 } 3609 leaf ifType { 3610 type iana:IfType; 3611 } 3612 leaf ifMtu { 3613 type int32; 3614 } 3615 } 3616 } 3618 Then in namespace http://example.com/schema/ds0, we have: 3620 import interface-module { 3621 prefix if; 3622 } 3623 augment "/if:interfaces/if:ifEntry" { 3624 when "if:ifType='ds0'"; 3625 leaf ds0ChannelNumber { 3626 type ChannelNumber; 3627 } 3628 } 3630 A corresponding XML encoding: 3632 3635 1 3636 Flintstone Inc Ethernet A562 3637 ethernetCsmacd 3638 1500 3639 3640 3641 2 3642 Flintstone Inc DS0 3643 ds0 3644 1 3645 3646 3648 As another example, suppose we have the choice defined in 3649 Section 7.9.7. The following construct can be used to extend the 3650 protocol definition: 3652 augment /ex:system/ex:protocol/ex:name { 3653 case c { 3654 leaf smtp { 3655 type empty; 3656 } 3657 } 3658 } 3660 A corresponding XML encoding: 3662 3663 3664 3665 3666 3668 or 3670 3671 3672 3673 3674 3676 7.16. The extension Statement 3678 The "extension" statement allows the definition of new statements 3679 within the YANG language. This new statement definition can be 3680 imported and used by other modules. 3682 The statement's argument is an identifier that is the new keyword for 3683 the extension and must be followed by a block of substatements that 3684 holds detailed extension information. The purpose of the extension 3685 statement is to define a keyword, so that it can be imported and used 3686 by other modules. 3688 The extension can be used like a normal YANG statement, with the 3689 statement name followed by an argument if one is defined by the 3690 extension, and an optional block of substatements. The statement's 3691 name is created by combining the the prefix of the module in which 3692 the extension was defined, a colon (":"), and the extension's 3693 keyword, with no interleaving whitespace. The substatements of an 3694 extension are defined by the extension, using some mechanism outside 3695 the scope of this specification. Syntactically, the substatements 3696 MUST be core YANG statements, or also defined using "extension" 3697 statements. Core YANG statements in extensions MUST follow the 3698 syntactical rules in Section 11. 3700 7.16.1. The extension's Substatements 3702 +--------------+---------+-------------+ 3703 | substatement | section | cardinality | 3704 +--------------+---------+-------------+ 3705 | argument | 7.16.2 | 0..1 | 3706 | description | 7.17.3 | 0..1 | 3707 | reference | 7.17.4 | 0..1 | 3708 | status | 7.17.2 | 0..1 | 3709 +--------------+---------+-------------+ 3711 7.16.2. The argument Statement 3713 The "argument" statement, which is optional, takes as an argument a 3714 string which is the name of the argument to the keyword. If no 3715 argument statement is present, the keyword expects no argument when 3716 it is used. 3718 The argument's name is used in the YIN mapping, where it is used as 3719 an XML attribute or element name, depending on the argument's text 3720 statement. 3722 7.16.2.1. The argument's Substatements 3724 +--------------+----------+-------------+ 3725 | substatement | section | cardinality | 3726 +--------------+----------+-------------+ 3727 | yin-element | 7.16.2.2 | 0..1 | 3728 +--------------+----------+-------------+ 3730 7.16.2.2. The yin-element Statement 3732 The "yin-element" statement, which is optional, takes as an argument 3733 the string "true" or "false". This statement indicates if the 3734 argument should be mapped to an XML element in YIN or to an XML 3735 attribute. (see Section 10). 3737 If no "yin-element" statement is present, it defaults to "false". 3739 7.16.3. Usage Example 3741 To define an extension: 3743 module my-extensions { 3744 ... 3746 extension c-define { 3747 description 3748 "Takes as argument a name string. 3749 Makes the code generator use the given name in the 3750 #define."; 3751 argument "name"; 3752 } 3753 } 3755 To use the extension: 3757 module my-interfaces { 3758 ... 3759 import my-extensions { 3760 prefix "myext"; 3761 } 3762 ... 3764 container interfaces { 3765 ... 3766 myext:c-define "MY_INTERFACES"; 3767 } 3768 } 3770 7.17. Common Statements 3772 This section defines sub-statements common to several other 3773 statements. 3775 7.17.1. The config Statement 3777 The "config" statement takes as an argument the string "true" or 3778 "false". If "config" is "true", the definition represents 3779 configuration, and will be part of the reply to a 3780 request, and may be sent in a or request. 3781 If "config" is "false", it represents state data, and will be part of 3782 the reply to a , but not to a request. 3784 If "config" is not specified, the default is the same as the parent 3785 node's (in the data model) "config" value. If the top node does not 3786 specify a "config" statement, the default is "true". 3788 If a node has "config" "false", no node underneath it can have 3789 "config" set to "true". 3791 7.17.2. The status Statement 3793 The "status" statement takes as an argument one of the strings 3794 "current", "deprecated", or "obsolete". 3796 o "current" means that the definition is current and valid. 3798 o "deprecated" indicates an obsolete definition, but it permits new/ 3799 continued implementation in order to foster interoperability with 3800 older/existing implementations. 3802 o "obsolete" means the definition is obsolete and should not be 3803 implemented and/or can be removed if previously implemented. 3805 If no status is specified, the default is "current". 3807 If a definition is "current", it MUST NOT reference a "deprecated" or 3808 "obsolete" definition within the same module. 3810 If a definition is "deprecated", it MUST NOT reference an "obsolete" 3811 definition within the same module. 3813 7.17.3. The description Statement 3815 The "description" statement takes as an argument a string which 3816 contains a high-level textual description of this definition. 3818 7.17.4. The reference Statement 3820 The "reference" statement takes as an argument a string which is used 3821 to specify a textual cross-reference to an external document, either 3822 another module which defines related management information, or a 3823 document which provides additional information relevant to this 3824 definition. 3826 8. Built-in Types 3828 YANG has a set of built-in types, similar to those of many 3829 programming languages, but with some differences due to special 3830 requirements from the management information model. 3832 Additional types may be defined, derived from those built-in types or 3833 from other derived types. Derived types may use subtyping to 3834 formally restrict the set of possible values. 3836 The different built-in types and their derived types allow different 3837 kinds of subtyping, namely length and regular expression restrictions 3838 of strings (Section 8.3.3, Section 8.3.5) and range restrictions of 3839 numeric types (Section 8.1.3). 3841 The lexicographic representation of a value of a certain type is used 3842 in the XML encoding over NETCONF, and when specifying default values 3843 in a YANG module. 3845 8.1. The Integer Built-in Types 3847 The integer built-in types are int8, int16, int32, int64, uint8, 3848 uint16, uint32, and uint64. They represent signed and unsigned 3849 integers of different sizes: 3851 int8 represents integer values between -128 and 127, inclusively. 3853 int16 represents integer values between -32768 and 32767, 3854 inclusively. 3856 int32 represents integer values between -2147483648 and 2147483647, 3857 inclusively. 3859 int64 represents integer values between -9223372036854775808 and 3860 9223372036854775807, inclusively. 3862 uint8 represents integer values between 0 and 255, inclusively. 3864 uint16 represents integer values between 0 and 65535, inclusively. 3866 uint32 represents integer values between 0 and 4294967295, 3867 inclusively. 3869 uint64 represents integer values between 0 and 18446744073709551615, 3870 inclusively. 3872 8.1.1. Lexicographic Representation 3874 An integer value is lexicographically represented as an optional sign 3875 ("+" or "-"), followed by a sequence of decimal digits. If no sign 3876 is specified, "+" is assumed. 3878 For convenience, when specifying a default value for an integer in a 3879 YANG module, an alternative lexicographic representation can be used, 3880 which represents the value in a hexadecimal or octal notation. The 3881 hexadecimal notation consists of an optional sign ("+" or "-"), the 3882 characters "0x" followed a number of hexadecimal digits, where 3883 letters may be upper- or lowercase. The octal notation consists of 3884 an optional sign ("+" or "-"), the character "0" followed a number of 3885 octal digits. 3887 Examples: 3889 // legal values 3890 +4711 // legal positive value 3891 4711 // legal positive value 3892 -123 // legal negative value 3893 0xf00f // legal positive hexadecimal value 3894 -0xf // legal negative hexadecimal value 3895 052 // legal positive octal value 3897 // illegal values 3898 - 1 // illegal intermediate space 3900 8.1.2. Restrictions 3902 All integer types can be restricted with the "range" statement 3903 (Section 8.1.3). 3905 8.1.3. The range Statement 3907 The "range" statement, which is an optional substatement to the 3908 "type" statement, takes as an argument a range expression string. It 3909 is used to restrict integer and floating point built-in types, or 3910 types derived from those. 3912 A range consists of an explicit value, or a lower inclusive bound, 3913 two consecutive dots "..", and an upper inclusive bound. Multiple 3914 values or ranges can be given, separated by "|". If multiple values 3915 or ranges are given they all MUST be disjoint and MUST be in 3916 ascending order. If a value restriction is applied to an already 3917 restricted type, the new restriction MUST be equal or more limiting, 3918 that is raising the lower bounds, reducing the upper bounds, removing 3919 explicit values or ranges, or splitting ranges into multiple ranges 3920 with intermediate gaps. Each explicit value and range boundary value 3921 given in the range expression MUST match the type being restricted, 3922 or be one of the special values "min" or "max". "min" and "max" means 3923 the minimum and maximum value accepted for the type being restricted, 3924 respectively. 3926 The range expression syntax is formally defined by the rule "range- 3927 arg" in Section 11. 3929 8.1.3.1. The range's Substatements 3931 +---------------+---------+-------------+ 3932 | substatement | section | cardinality | 3933 +---------------+---------+-------------+ 3934 | description | 7.17.3 | 0..1 | 3935 | error-app-tag | 7.5.3.2 | 0..1 | 3936 | error-message | 7.5.3.1 | 0..1 | 3937 | reference | 7.17.4 | 0..1 | 3938 +---------------+---------+-------------+ 3940 8.1.4. Usage Example 3942 typedef my-base-int32-type { 3943 type int32 { 3944 range "1..4 | 10..20"; 3945 } 3946 } 3948 type my-base-int32-type { 3949 // legal range restriction 3950 range "11..max"; // 11..20 3951 } 3953 type int32 { 3954 // illegal range restriction 3955 range "11..100"; 3956 } 3958 8.2. The Floating Point Built-in Types 3960 The floating point built-in types are float32 and float64. They 3961 represent floating point values of single and double precision as 3962 defined in [IEEE.754]. Special values are positive and negative 3963 infinity, and not-a-number. 3965 8.2.1. Lexicographic Representation 3967 A floating point value is lexicographically represented as consisting 3968 of a decimal mantissa followed, optionally, by the character "E" or 3969 "e", followed by an integer exponent. The special values positive 3970 and negative infinity and not-a-number have lexical representations 3971 INF, -INF and NaN, respectively. The minimal value accepted for a 3972 float is -INF, and the maximal value accepted for a float is INF. 3974 8.2.2. Restrictions 3976 All floating point types can be restricted with the "range" statement 3977 (Section 8.1.3). 3979 8.2.3. Usage Example 3981 type float32 { 3982 range "1..4.5 | 10 | 20..INF"; 3983 } 3985 is equivalent to 3987 type float32 { 3988 range "1..4.5 | 10 | 20..max"; 3989 } 3991 8.3. The string Built-in Type 3993 The string built-in type represents human readable strings in YANG. 3994 Legal characters are tab, carriage return, line feed, and the legal 3995 characters of Unicode and ISO/IEC 10646 [ISO.10646]: 3997 // any Unicode character, excluding the surrogate blocks, 3998 // FFFE, and FFFF. 3999 string = *char 4000 char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / 4001 %x10000-10FFFF 4003 8.3.1. Lexicographic Representation 4005 A string value is lexicographically represented as character data in 4006 the XML encoding. 4008 8.3.2. Restrictions 4010 A string can be restricted with the "length" (Section 8.3.3) and 4011 "pattern" (Section 8.3.5) statements. 4013 8.3.3. The length Statement 4015 The "length" statement, which is an optional substatement to the 4016 "type" statement, takes as an argument a length expression string. 4017 It is used to restrict the built-in type "string", or types derived 4018 from "string". 4020 A "length" statement restricts the number of characters in the 4021 string. 4023 A length range consists of an explicit value, or a lower bound, two 4024 consecutive dots "..", and an upper bound. Multiple values or ranges 4025 can be given, separated by "|". Length restricting values MUST NOT 4026 be negative. If multiple values or ranges are given, they all MUST 4027 be disjoint and MUST be in ascending order. If a length restriction 4028 is applied to an already length restricted type, the new restriction 4029 MUST be equal or more limiting, that is, raising the lower bounds, 4030 reducing the upper bounds, removing explicit length values or ranges, 4031 or splitting ranges into multiple ranges with intermediate gaps. A 4032 length value is a non-negative integer, or one of the special values 4033 "min" or "max". "min" and "max" means the minimum and maximum length 4034 accepted for the type being restricted, respectively. An 4035 implementation is not required to support a length value larger than 4036 18446744073709551615. 4038 The length expression syntax is formally defined by the rule "length- 4039 arg" in Section 11. 4041 8.3.3.1. The length's Substatements 4043 +---------------+---------+-------------+ 4044 | substatement | section | cardinality | 4045 +---------------+---------+-------------+ 4046 | description | 7.17.3 | 0..1 | 4047 | error-app-tag | 7.5.3.2 | 0..1 | 4048 | error-message | 7.5.3.1 | 0..1 | 4049 | reference | 7.17.4 | 0..1 | 4050 +---------------+---------+-------------+ 4052 8.3.4. Usage Example 4054 typedef my-base-str-type { 4055 type string { 4056 length "1..255"; 4057 } 4058 } 4060 type my-base-str-type { 4061 // legal length refinement 4062 length "11 | 42..max"; // 11 | 42..255 4063 } 4065 type my-base-str-type { 4066 // illegal length refinement 4067 length "1..999"; 4068 } 4070 8.3.5. The pattern Statement 4072 The "pattern" statement, which is an optional substatement to the 4073 "type" statement, takes as an argument a regular expression string, 4074 as defined in [XSD-TYPES]. It is used to restrict the built-in type 4075 "string", or types derived from "string", to values that completely 4076 matches the pattern. 4078 If the type has multiple "pattern" statements, the expressions are 4079 AND:ed together, i.e. all such expressions have to match. 4081 8.3.5.1. The pattern's Substatements 4083 +---------------+---------+-------------+ 4084 | substatement | section | cardinality | 4085 +---------------+---------+-------------+ 4086 | description | 7.17.3 | 0..1 | 4087 | error-app-tag | 7.5.3.2 | 0..1 | 4088 | error-message | 7.5.3.1 | 0..1 | 4089 | reference | 7.17.4 | 0..1 | 4090 +---------------+---------+-------------+ 4092 8.3.6. Usage Example 4094 With the following type: 4096 type string { 4097 length "0..4"; 4098 pattern "[0-9a-fA-F]*"; 4099 } 4101 the following strings match: 4103 AB // legal 4104 9A00 // legal 4106 and the following strings do not match: 4108 00ABAB // illegal 4109 xx00 // illegal 4111 8.4. The boolean Built-in Type 4113 The boolean built-in type represents a boolean value. 4115 8.4.1. Lexicographic Representation 4117 The lexicographical representation of a boolean value is the strings 4118 "true" and "false". 4120 8.4.2. Restrictions 4122 A boolean cannot be restricted. 4124 8.5. The enumeration Built-in Type 4126 The enumeration built-in type represents values from a set of 4127 assigned names. 4129 8.5.1. Lexicographic Representation 4131 The lexicographical representation of an enumeration value is the 4132 assigned name string. 4134 8.5.2. Restrictions 4136 An enumeration cannot be restricted. 4138 8.5.3. The enum Statement 4140 The "enum" statement, which is a substatement to the "type" 4141 statement, MUST be present if the type is "enumeration". It is 4142 repeatedly used to specify each assigned name of an enumeration type. 4143 It takes as an argument a string which is the assigned name. It is 4144 optionally followed by a block of substatements which holds detailed 4145 enum information. 4147 All assigned names in an enumeration MUST be unique. 4149 8.5.3.1. The enum's Substatements 4151 +--------------+---------+-------------+ 4152 | substatement | section | cardinality | 4153 +--------------+---------+-------------+ 4154 | description | 7.17.3 | 0..1 | 4155 | reference | 7.17.4 | 0..1 | 4156 | status | 7.17.2 | 0..1 | 4157 | value | 8.5.3.2 | 0..1 | 4158 +--------------+---------+-------------+ 4160 8.5.3.2. The value Statement 4162 The "value" statement, which is optional, is used to associate an 4163 integer value with the assigned name for the enum. This integer 4164 value MUST be in the range -2147483648 to 2147483647, and it MUST be 4165 unique within the enumeration type. 4167 If a value is not specified, then one will be automatically assigned. 4168 If the enum sub-statement is the first one defined, the assigned 4169 value is zero (0), otherwise the assigned value is one greater than 4170 the current highest enum value. 4172 If the current highest value is equal to 2147483647, then an enum 4173 value MUST be specified for enum sub-statements following the one 4174 with the current highest value. 4176 8.5.4. Usage Example 4178 type enumeration { 4179 enum enabled { 4180 value 1; 4181 } 4182 enum disabled { 4183 value 2; 4184 } 4185 } 4187 type enumeration { 4188 enum zero; 4189 enum one; 4190 enum seven { 4191 value 7; 4192 } 4193 } 4195 8.6. The bits Built-in Type 4197 The bits built-in type represents a bit set. That is, a bits value 4198 is a set of flags identified by small integer position numbers 4199 starting at 0. Each bit number has an assigned name. 4201 8.6.1. Restrictions 4203 A bits type cannot be restricted. 4205 8.6.2. Lexicographic Representation 4207 The lexicographical representation of the bits type is a space 4208 separated list of the individual bit values that are set. An empty 4209 string thus represents a value where no bits are set. 4211 8.6.3. The bit Statement 4213 The "bit" statement, which is a substatement to the "type" statement, 4214 MUST be present if the type is "bits". It is repeatedly used to 4215 specify each assigned named bit of a bits type. It takes as an 4216 argument a string which is the assigned name of the bit. It is 4217 followed by a block of substatements which holds detailed bit 4218 information. A bit name follows the same syntax rules as an 4219 identifier (see Section 6.2). 4221 All bit names in a bits type MUST be unique. 4223 8.6.3.1. The bit's Substatements 4225 +--------------+---------+-------------+ 4226 | substatement | section | cardinality | 4227 +--------------+---------+-------------+ 4228 | description | 7.17.3 | 0..1 | 4229 | reference | 7.17.4 | 0..1 | 4230 | status | 7.17.2 | 0..1 | 4231 | position | 8.6.3.2 | 0..1 | 4232 +--------------+---------+-------------+ 4234 8.6.3.2. The position Statement 4236 The "position" statement, which is optional, takes as an argument a 4237 non-negative integer value which specifies the bit's position within 4238 a hypothetical bit field. The position value MUST be in the range 0 4239 to 4294967295, and it MUST be unique within the bits type. The value 4240 is unused by YANG and the XML encoding, but is carried as a 4241 convenience to implementors. 4243 If a bit position is not specified, then one will be automatically 4244 assigned. If the bit sub-statement is the first one defined, the 4245 assigned value is zero (0), otherwise the assigned value is one 4246 greater than the current highest bit position. 4248 If the current highest bit position value is equal to 4294967295, 4249 then a position value MUST be specified for bit sub-statements 4250 following the one with the current highest position value. 4252 8.6.4. Usage Example 4254 Given the following type: 4256 leaf mybits { 4257 type bits { 4258 bit disable-nagle { 4259 position 0; 4260 } 4261 bit auto-sense-speed { 4262 position 1; 4263 } 4264 bit 10-Mb-only { 4265 position 2; 4266 } 4267 } 4268 default "auto-sense-speed"; 4269 } 4271 The lexicographic representation of this leaf with bit values 4272 disable-nagle and 10-Mb-only set would be: 4274 disable-nagle 10-Mb-only 4276 8.7. The binary Built-in Type 4278 The binary built-in type represents any binary data, i.e. a sequence 4279 of octets. 4281 8.7.1. Restrictions 4283 A binary can be restricted with the "length" (Section 8.3.3) 4284 statement. The length of a binary value is the number of octets it 4285 contains. 4287 8.7.2. Lexicographic Representation 4289 Binary values are encoded with the base64 encoding scheme [RFC4648]. 4291 8.8. The keyref Built-in Type 4293 The keyref type is used to reference a particular list entry in the 4294 data tree. Its value is constrained to be the same as the key of an 4295 existing list entry. 4297 If the leaf with the keyref type represents configuration, the list 4298 entry it refers to MUST also represent configuration. Such a leaf 4299 puts a constraint on a valid configuration. In a valid 4300 configuration, all keyref nodes MUST reference existing list entries. 4302 8.8.1. Restrictions 4304 A keyref cannot be restricted. 4306 8.8.2. The path Statement 4308 The "path" statement, which is a substatement to the "type" 4309 statement, MUST be present if the type is "keyref". It takes as an 4310 argument a string which MUST refer to one key node of a list entry. 4312 The syntax for a path argument is a subset of the XPath syntax. It 4313 is an absolute or relative XPath location path in abbreviated syntax, 4314 where axes are not permitted, and predicates are used only for 4315 constraining the values for the key nodes for list entries. Each 4316 predicate consists of at most one equality test per key. 4318 The predicates are only used when more than one key reference is 4319 needed to uniquely identify a list entry. This occurs if the list 4320 has multiple keys, or a reference to a list within a list is needed. 4321 In these cases, multiple keyref leafs are typically specified, and 4322 predicates are used to tie them together. 4324 The syntax is formally defined by the rule "path-arg" in Section 11. 4326 8.8.3. Lexicographic Representation 4328 A keyref value is encoded the same way as the key it references. 4330 8.8.4. Usage Example 4332 With the following list: 4334 list interface { 4335 key "name"; 4336 leaf name { 4337 type string; 4338 } 4339 list address { 4340 key "ip"; 4341 leaf ip { 4342 type yang:ip-address; 4343 } 4344 } 4345 } 4347 The following keyref refers to an existing interface: 4349 leaf mgmt-interface { 4350 type keyref { 4351 path "../interface/name"; 4352 } 4353 } 4355 A corresponding XML snippet is e.g.: 4357 4358 eth0 4359 4360 4361 lo 4362 4364 eth0 4366 The following keyrefs refer to an existing address of an interface: 4368 container default-address { 4369 leaf ifname { 4370 type keyref { 4371 path "../../interface/name"; 4372 } 4373 } 4374 leaf address { 4375 type keyref { 4376 path "../../interface[name = current()/../ifname]" 4377 + "/address/ip"; 4378 } 4379 } 4380 } 4382 A corresponding XML snippet is e.g.: 4384 4385 eth0 4386
4387 192.0.2.1 4388
4389
4390 192.0.2.2 4391
4392 4393 4394 lo 4395
4396 127.0.0.1 4397
4398 4400 4401 eth0 4402
192.0.2.2
4403 4405 8.9. The empty Built-in Type 4407 The empty built-in type represents a leaf that does not have any 4408 value, it conveys information by its presence or absence. 4410 An empty type cannot have a default value. 4412 8.9.1. Restrictions 4414 An empty type cannot be restricted. 4416 8.9.2. Lexicographic Representation 4418 Not applicable. 4420 8.9.3. Usage Example 4422 The following leaf 4424 leaf enable-qos { 4425 type empty; 4426 } 4428 will be encoded as 4429 4431 if it exists. 4433 8.10. The union Built-in Type 4435 The union built-in type represents a value that corresponds to one of 4436 its member types. 4438 When the type is "union", the "type" statement (Section 7.4) MUST be 4439 present. It is used to repeatedly specify each member type of the 4440 union. It takes as an argument a string which is the name of a 4441 member type. 4443 A member type can be of any built-in or derived type, except it MUST 4444 NOT be one of the built-in types "empty" or "keyref". 4446 Example: 4448 type union { 4449 type int32; 4450 type enumeration { 4451 enum "unbounded"; 4452 } 4453 } 4455 8.10.1. Restrictions 4457 A union can not be restricted. However, each member type can be 4458 restricted, based on the rules defined in Section 8 chapter. 4460 8.10.2. Lexicographic Representation 4462 The lexicographical representation of an union is a value that 4463 corresponds to the representation of any one of the member types. 4465 8.11. The instance-identifier Built-in Type 4467 The instance-identifier built-in type is used to uniquely identify a 4468 particular instance node in the data tree. 4470 The syntax for an instance-identifier is a subset of the XPath 4471 syntax, which is used to uniquely identify a node in the data tree. 4472 It is an absolute XPath location path in abbreviated syntax, where 4473 axes are not permitted, and predicates are used only for specifying 4474 the values for the key nodes for list entries, or a value of a leaf- 4475 list. Each predicate consists of one equality test per key. Each 4476 key MUST have a corresponding predicate. 4478 The syntax is formally defined by the rule "absolute-instid" in 4479 Section 11. 4481 8.11.1. Restrictions 4483 An instance-identifier cannot be restricted. 4485 8.11.2. Lexicographic Representation 4487 An instance-identifier value is lexicographically represented as a 4488 string in the XML encoding. The namespace prefixes used in the 4489 encoding MUST be declared in the XML namespace scope in the instance- 4490 idenfitier's XML element. 4492 Any prefixes used in the encoding are local to each instance 4493 encoding. This means that the same instance-identifier may be 4494 encoded differently by different implementations. 4496 8.11.3. Usage Example 4498 The following are examples of instance identifiers: 4500 /ex:system/ex:services/ex:ssh/ex:port 4502 /ex:system/ex:user[ex:name='fred'] 4504 /ex:system/ex:user[ex:name='fred']/ex:type 4506 /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] 4508 /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 4510 9. Updating a Module 4512 [Editor's Note: add versioning rules, i.e. what can be done w/o 4513 changing the module name and the namespace] 4515 10. YIN 4517 A YANG module can be specified in an alternative XML-based syntax 4518 called YIN. This appendix describes symmetric mapping rules between 4519 the two formats. 4521 The YANG and YIN formats contain equivalent information using 4522 different notations. The purpose of the YIN notation is to allow the 4523 user to translate YANG into YIN, use the rich set of XML based tools 4524 on the YIN format to transform, or filter the model information. 4525 Tools like XSLT or XML validators can be utilized. After this the 4526 model can be transformed back to the YANG format if needed, which 4527 provides a more concise and readable format. 4529 The YANG-2-YIN and the YIN-2-YANG transformations will not modify the 4530 information content of the model. 4532 10.1. Formal YIN Definition 4534 YIN is described by an algorithm that transforms YANG to YIN. 4536 10.2. Transformation Algorithm YANG-2-YIN 4538 Every keyword results in a new XML element. The name of the element 4539 is the keyword. All core YANG elements are defined in the namespace 4540 "urn:ietf:params:xml:ns:yang:yin:1". [XXX IANA] 4542 The top-level element is always or . 4544 Elements which represent keywords that are imported extensions from 4545 other modules MUST be properly namespace qualified, where the 4546 namespace is the namespace of the imported module. Translators 4547 SHOULD use the same prefix as used in the YANG module. 4549 If the keyword has an argument, its encoding depends on the value of 4550 the argument's "yin-element". If "yin-element" is false, the 4551 argument is encoded as an XML attribute to the keyword's element. If 4552 "yin-element" is true, the argument is encoded as a subelement to the 4553 keyword's element. The name of the attribute or element is the name 4554 of the argument. 4556 The core YANG keywords have arguments according to the table below. 4557 Extension keywords have arguments according to Section 7.16.2. 4559 YANG to YIN keyword map 4561 +---------------+---------------+-------------+ 4562 | keyword | argument name | yin-element | 4563 +---------------+---------------+-------------+ 4564 | anyxml | name | false | 4565 | argument | name | false | 4566 | augment | target-node | false | 4567 | belongs-to | module | false | 4568 | bit | name | false | 4569 | case | name | false | 4570 | choice | name | false | 4571 | config | value | false | 4572 | contact | info | true | 4573 | container | name | false | 4574 | default | value | false | 4575 | description | text | true | 4576 | enum | name | false | 4577 | error-app-tag | value | false | 4578 | error-message | value | true | 4579 | extension | name | false | 4580 | grouping | name | false | 4581 | import | module | false | 4582 | include | module | false | 4583 | input | | n/a | 4584 | key | value | false | 4585 | leaf | name | false | 4586 | leaf-list | name | false | 4587 | length | value | false | 4588 | list | name | false | 4589 | mandatory | value | false | 4590 | max-elements | value | false | 4591 | min-elements | value | false | 4592 | module | name | false | 4593 | must | condition | false | 4594 | namespace | uri | false | 4595 | notification | name | false | 4596 | ordered-by | value | false | 4597 | organization | info | true | 4598 | output | | n/a | 4599 | path | value | false | 4600 | pattern | value | false | 4601 | position | value | false | 4602 | prefix | value | false | 4603 | presence | value | false | 4604 | range | value | false | 4605 | reference | info | false | 4606 | revision | date | false | 4607 | rpc | name | false | 4608 | status | value | false | 4609 | submodule | name | false | 4610 | type | name | false | 4611 | typedef | name | false | 4612 | unique | tag | false | 4613 | units | name | false | 4614 | uses | name | false | 4615 | value | value | false | 4616 | when | condition | false | 4617 | yang-version | value | false | 4618 | yin-element | value | false | 4619 +---------------+---------------+-------------+ 4621 Table 30 4623 If a statement is followed by substatements, those substatements are 4624 subelements in the YIN mapping. 4626 Comments in YANG MAY be transformed into XML comments. 4628 10.2.1. Usage Example 4630 The following YANG snippet: 4632 leaf mtu { 4633 type uint32; 4634 description "The MTU of the interface."; 4635 } 4637 is translated into the following YIN snippet: 4639 4640 4641 4642 The MTU of the interface." 4643 4644 4646 10.3. Transformation Algorithm YIN-2-YANG 4648 The transformation is based on a recursive algorithm that is started 4649 on the or element. 4651 The element is transformed into a YANG keyword. If the keyword in 4652 Table 30 is marked as yin-element true, the subelement with the 4653 keyword's argument name in Table 30 contains the YANG keyword's 4654 argument as text content. If the keyword in Table 30 is marked as 4655 yin-element false, the element's attribute with keyword's argument 4656 name in Table 30 contains the YANG keyword's argument. 4658 If there are no other subelements to the element, the YANG statement 4659 is closed with a ";". Otherwise, each such subelement is 4660 transformed, according to the same algorithm, as substatements to the 4661 current YANG statement, enclosed within "{" and "}". 4663 XML comments in YIN MAY be transformed into YANG comments. 4665 10.3.1. Tabulation, Formatting 4667 To get a readable YANG module the YANG output will have to be 4668 indented with appropriate whitespace characters. 4670 11. YANG ABNF Grammar 4672 In YANG, almost all statements are unordered. The ABNF grammar 4673 [RFC5234] defines the canonical order. To improve module 4674 readability, it is RECOMMENDED that clauses be entered in this order. 4676 Within the ABNF grammar, unordered statements are marked with 4677 comments. 4679 This grammar assumes that the scanner replaces YANG comments with a 4680 single space character. 4682 module-stmt = optsep module-keyword sep identifier-arg-str 4683 optsep 4684 "{" stmtsep 4685 module-header-stmts 4686 linkage-stmts 4687 meta-stmts 4688 revision-stmts 4689 body-stmts 4690 "}" optsep 4692 submodule-stmt = optsep submodule-keyword sep identifier-arg-str 4693 optsep 4694 "{" stmtsep 4695 submodule-header-stmts 4696 linkage-stmts 4697 meta-stmts 4698 revision-stmts 4699 body-stmts 4700 "}" optsep 4702 module-header-stmts = ;; these stmts can appear in any order 4703 [yang-version-stmt stmtsep] 4704 namespace-stmt stmtsep 4705 prefix-stmt stmtsep 4707 submodule-header-stmts = ;; these stmts can appear in any order 4708 [yang-version-stmt stmtsep] 4709 belongs-to-stmt stmtsep 4711 meta-stmts = ;; these stmts can appear in any order 4712 [organization-stmt stmtsep] 4713 [contact-stmt stmtsep] 4714 [description-stmt stmtsep] 4715 [reference-stmt stmtsep] 4717 linkage-stmts = ;; these stmts can appear in any order 4718 *(import-stmt stmtsep) 4719 *(include-stmt stmtsep) 4721 revision-stmts = *(revision-stmt stmtsep) 4723 body-stmts = *((extension-stmt / 4724 typedef-stmt / 4725 grouping-stmt / 4726 data-def-stmt / 4727 rpc-stmt / 4728 notification-stmt) stmtsep) 4730 data-def-stmt = container-stmt / 4731 leaf-stmt / 4732 leaf-list-stmt / 4733 list-stmt / 4734 choice-stmt / 4735 anyxml-stmt / 4736 uses-stmt / 4737 augment-stmt 4739 case-data-def-stmt = container-stmt / 4740 leaf-stmt / 4741 leaf-list-stmt / 4742 list-stmt / 4743 anyxml-stmt / 4744 uses-stmt / 4745 augment-stmt 4747 yang-version-stmt = yang-version-keyword sep yang-version-arg-str 4748 optsep stmtend 4750 yang-version-arg-str = < a string which matches the rule 4751 yang-version-arg > 4753 yang-version-arg = "1" 4755 import-stmt = import-keyword sep identifier-arg-str optsep 4756 "{" stmtsep 4757 prefix-stmt stmtsep 4758 "}" 4760 include-stmt = include-keyword sep identifier-arg-str optsep 4761 stmtend 4763 namespace-stmt = namespace-keyword sep uri-str optsep stmtend 4765 uri-str = < a string which matches the rule 4766 URI in RFC 3986 > 4768 prefix-stmt = prefix-keyword sep prefix-arg-str 4769 optsep stmtend 4771 belongs-to-stmt = belongs-to-keyword sep identifier-arg-str 4772 optsep stmtend 4774 organization-stmt = organization-keyword sep string 4775 optsep stmtend 4777 contact-stmt = contact-keyword sep string optsep stmtend 4779 description-stmt = description-keyword sep string optsep 4780 stmtend 4782 reference-stmt = reference-keyword sep string optsep stmtend 4784 units-stmt = units-keyword sep string optsep stmtend 4786 revision-stmt = revision-keyword sep date-arg-str optsep 4787 (";" / 4788 "{" stmtsep 4789 [description-stmt stmtsep] 4790 "}") 4792 extension-stmt = extension-keyword sep identifier-arg-str optsep 4793 (";" / 4794 "{" stmtsep 4795 ;; these stmts can appear in any order 4796 [argument-stmt stmtsep] 4797 [status-stmt stmtsep] 4798 [description-stmt stmtsep] 4799 [reference-stmt stmtsep] 4800 "}") 4802 argument-stmt = argument-keyword sep identifier-arg-str optsep 4803 (";" / 4804 "{" stmtsep 4805 [yin-element-stmt stmtsep] 4806 "}") 4808 yin-element-stmt = yin-element-keyword sep yin-element-arg-str 4809 stmtend 4811 yin-element-arg-str = < a string which matches the rule 4812 yin-element-arg > 4814 yin-element-arg = true-keyword / false-keyword 4816 typedef-stmt = typedef-keyword sep identifier-arg-str optsep 4817 "{" stmtsep 4818 ;; these stmts can appear in any order 4819 type-stmt stmtsep 4820 [units-stmt stmtsep] 4821 [default-stmt stmtsep] 4822 [status-stmt stmtsep] 4823 [description-stmt stmtsep] 4824 [reference-stmt stmtsep] 4825 "}" 4827 type-stmt = type-keyword sep identifier-ref-arg-str optsep 4828 (";" / 4829 "{" stmtsep 4830 ( numerical-restrictions / 4831 string-restrictions / 4832 enum-specification / 4833 keyref-specification / 4834 bits-specification / 4835 union-specification ) 4836 stmtsep 4837 "}") 4839 numerical-restrictions = range-stmt stmtsep 4841 range-stmt = range-keyword sep range-arg-str optsep 4842 (";" / 4843 "{" stmtsep 4844 ;; these stmts can appear in any order 4845 [error-message-stmt stmtsep] 4846 [error-app-tag-stmt stmtsep] 4847 [description-stmt stmtsep] 4848 [reference-stmt stmtsep] 4849 "}") 4851 string-restrictions = ;; these stmts can appear in any order 4852 [length-stmt stmtsep] 4853 *(pattern-stmt stmtsep) 4855 length-stmt = length-keyword sep length-arg-str optsep 4856 (";" / 4857 "{" stmtsep 4858 ;; these stmts can appear in any order 4859 [error-message-stmt stmtsep] 4860 [error-app-tag-stmt stmtsep] 4861 [description-stmt stmtsep] 4863 [reference-stmt stmtsep] 4864 "}") 4866 pattern-stmt = pattern-keyword sep string optsep 4867 (";" / 4868 "{" stmtsep 4869 ;; these stmts can appear in any order 4870 [error-message-stmt stmtsep] 4871 [error-app-tag-stmt stmtsep] 4872 [description-stmt stmtsep] 4873 [reference-stmt stmtsep] 4874 "}") 4876 default-stmt = default-keyword sep string stmtend 4878 enum-specification = 1*(enum-stmt stmtsep) 4880 enum-stmt = enum-keyword sep identifier-arg-str optsep 4881 (";" / 4882 "{" stmtsep 4883 ;; these stmts can appear in any order 4884 [value-stmt stmtsep] 4885 [status-stmt stmtsep] 4886 [description-stmt stmtsep] 4887 [reference-stmt stmtsep] 4888 "}") 4890 keyref-specification = path-stmt stmtsep 4892 path-stmt = path-keyword sep path-arg-str stmtend 4894 union-specification = 1*(type-stmt stmtsep) 4896 bits-specification = 1*(bit-stmt stmtsep) 4898 bit-stmt = bit-keyword sep identifier-arg-str optsep 4899 (";" / 4900 "{" stmtsep 4901 ;; these stmts can appear in any order 4902 [position-stmt stmtsep] 4903 [status-stmt stmtsep] 4904 [description-stmt stmtsep] 4905 [reference-stmt stmtsep] 4906 "}" 4907 "}") 4909 position-stmt = position-keyword sep 4910 position-value-arg-str stmtend 4912 position-value-arg-str = < a string which matches the rule 4913 position-value-arg > 4915 position-value-arg = non-negative-decimal-value 4917 status-stmt = status-keyword sep status-arg-str stmtend 4919 status-arg-str = < a string which matches the rule 4920 status-arg > 4922 status-arg = current-keyword / 4923 obsolete-keyword / 4924 deprecated-keyword 4926 config-stmt = config-keyword sep 4927 config-arg-str stmtend 4929 config-arg-str = < a string which matches the rule 4930 config-arg > 4932 config-arg = true-keyword / false-keyword 4934 mandatory-stmt = mandatory-keyword sep 4935 mandatory-arg-str stmtend 4937 mandatory-arg-str = < a string which matches the rule 4938 mandatory-arg > 4940 mandatory-arg = true-keyword / false-keyword 4942 presence-stmt = presence-keyword sep string stmtend 4944 ordered-by-stmt = ordered-by-keyword sep 4945 ordered-by-arg-str stmtend 4947 ordered-by-arg-str = < a string which matches the rule 4948 ordered-by-arg > 4950 ordered-by-arg = user-keyword / system-keyword 4952 must-stmt = must-keyword sep string optsep 4953 (";" / 4954 "{" stmtsep 4955 ;; these stmts can appear in any order 4956 [error-message-stmt stmtsep] 4957 [error-app-tag-stmt stmtsep] 4958 [description-stmt stmtsep] 4959 [reference-stmt stmtsep] 4961 "}") 4963 error-message-stmt = error-message-keyword sep string stmtend 4965 error-app-tag-stmt = error-app-tag-keyword sep string stmtend 4967 min-elements-stmt = min-elements-keyword sep 4968 min-value-arg-str stmtend; 4970 min-value-arg-str = < a string which matches the rule 4971 min-value-arg > 4973 min-value-arg = non-negative-decimal-value 4975 max-elements-stmt = max-elements-keyword sep 4976 max-value-arg-str stmtend; 4978 max-value-arg-str = < a string which matches the rule 4979 max-value-arg > 4981 max-value-arg = unbounded-keyword / 4982 positive-decimal-value 4984 value-stmt = value-keyword sep decimal-value stmtend 4986 grouping-stmt = grouping-keyword sep identifier-arg-str optsep 4987 (";" / 4988 "{" stmtsep 4989 ;; these stmts can appear in any order 4990 [status-stmt stmtsep] 4991 [description-stmt stmtsep] 4992 [reference-stmt stmtsep] 4993 *((typedef-stmt / 4994 grouping-stmt) stmtsep) 4995 *(data-def-stmt stmtsep) 4996 "}") 4998 container-stmt = container-keyword sep identifier-arg-str optsep 4999 (";" / 5000 "{" stmtsep 5001 ;; these stmts can appear in any order 5002 *(must-stmt stmtsep) 5003 [presence-stmt stmtsep] 5004 [config-stmt stmtsep] 5005 [status-stmt stmtsep] 5006 [description-stmt stmtsep] 5007 [reference-stmt stmtsep] 5008 *((typedef-stmt / 5009 grouping-stmt) stmtsep) 5010 *(data-def-stmt stmtsep) 5011 "}") 5013 leaf-stmt = leaf-keyword sep identifier-arg-str optsep 5014 "{" stmtsep 5015 ;; these stmts can appear in any order 5016 type-stmt stmtsep 5017 [units-stmt stmtsep] 5018 *(must-stmt stmtsep) 5019 [default-stmt stmtsep] 5020 [config-stmt stmtsep] 5021 [mandatory-stmt stmtsep] 5022 [status-stmt stmtsep] 5023 [description-stmt stmtsep] 5024 [reference-stmt stmtsep] 5025 "}" 5027 leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 5028 "{" stmtsep 5029 ;; these stmts can appear in any order 5030 type-stmt stmtsep 5031 [units-stmt stmtsep] 5032 *(must-stmt stmtsep) 5033 [config-stmt stmtsep] 5034 [min-elements-stmt stmtsep] 5035 [max-elements-stmt stmtsep] 5036 [ordered-by-stmt stmtsep] 5037 [status-stmt stmtsep] 5038 [description-stmt stmtsep] 5039 [reference-stmt stmtsep] 5040 "}" 5042 list-stmt = list-keyword sep identifier-arg-str optsep 5043 "{" stmtsep 5044 ;; these stmts can appear in any order 5045 *(must-stmt stmtsep) 5046 [key-stmt stmtsep] 5047 *(unique-stmt stmtsep) 5048 [config-stmt stmtsep] 5049 [min-elements-stmt stmtsep] 5050 [max-elements-stmt stmtsep] 5051 [ordered-by-stmt stmtsep] 5052 [status-stmt stmtsep] 5053 [description-stmt stmtsep] 5054 [reference-stmt stmtsep] 5055 *((typedef-stmt / 5056 grouping-stmt) stmtsep) 5058 1*(data-def-stmt stmtsep) 5059 "}" 5061 key-stmt = key-keyword sep key-arg-str stmtend 5063 key-arg-str = < a string which matches the rule 5064 key-arg > 5066 key-arg = identifier *(sep identifier) 5068 unique-stmt = unique-keyword sep unique-arg-str stmtend 5070 unique-arg-str = < a string which matches the rule 5071 unique-arg > 5073 unique-arg = descendant-schema-nodeid 5074 *(sep descendant-schema-nodeid) 5076 choice-stmt = choice-keyword sep identifier-arg-str optsep 5077 (";" / 5078 "{" stmtsep 5079 ;; these stmts can appear in any order 5080 [default-stmt stmtsep] 5081 [config-stmt stmtsep] 5082 [mandatory-stmt stmtsep] 5083 [status-stmt stmtsep] 5084 [description-stmt stmtsep] 5085 [reference-stmt stmtsep] 5086 *((short-case-stmt / case-stmt) stmtsep) 5087 "}") 5089 short-case-stmt = container-stmt / 5090 leaf-stmt / 5091 leaf-list-stmt / 5092 list-stmt / 5093 anyxml-stmt 5095 case-stmt = case-keyword sep identifier-arg-str optsep 5096 (";" / 5097 "{" stmtsep 5098 ;; these stmts can appear in any order 5099 [status-stmt stmtsep] 5100 [description-stmt stmtsep] 5101 [reference-stmt stmtsep] 5102 *(case-data-def-stmt stmtsep) 5103 "}") 5105 anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 5106 (";" / 5107 "{" stmtsep 5108 ;; these stmts can appear in any order 5109 [config-stmt stmtsep] 5110 [mandatory-stmt stmtsep] 5111 [status-stmt stmtsep] 5112 [description-stmt stmtsep] 5113 [reference-stmt stmtsep] 5114 "}") 5116 uses-stmt = uses-keyword sep identifier-ref-arg-str optsep 5117 (";" / 5118 "{" stmtsep 5119 ;; these stmts can appear in any order 5120 [status-stmt stmtsep] 5121 [description-stmt stmtsep] 5122 [reference-stmt stmtsep] 5123 *(refinement-stmt stmtsep) 5124 "}") 5126 refinement-stmt = refine-container-stmt / 5127 refine-leaf-stmt / 5128 refine-leaf-list-stmt / 5129 refine-list-stmt / 5130 refine-choice-stmt / 5131 refine-anyxml-stmt 5133 refine-leaf-stmt = leaf-keyword sep identifier-arg-str optsep 5134 (";" / 5135 "{" stmtsep 5136 ;; these stmts can appear in any order 5137 *(must-stmt stmtsep) 5138 [default-stmt stmtsep] 5139 [config-stmt stmtsep] 5140 [mandatory-stmt stmtsep] 5141 [description-stmt stmtsep] 5142 [reference-stmt stmtsep] 5143 "}") 5145 refine-leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep 5146 (";" / 5147 "{" stmtsep 5148 ;; these stmts can appear in any order 5149 *(must-stmt stmtsep) 5150 [config-stmt stmtsep] 5151 [min-elements-stmt stmtsep] 5152 [max-elements-stmt stmtsep] 5153 [description-stmt stmtsep] 5155 [reference-stmt stmtsep] 5156 "}") 5158 refine-list-stmt = list-keyword sep identifier-arg-str optsep 5159 (";" / 5160 "{" stmtsep 5161 ;; these stmts can appear in any order 5162 *(must-stmt stmtsep) 5163 [config-stmt stmtsep] 5164 [min-elements-stmt stmtsep] 5165 [max-elements-stmt stmtsep] 5166 [description-stmt stmtsep] 5167 [reference-stmt stmtsep] 5168 *(refinement-stmt stmtsep) 5169 "}") 5171 refine-choice-stmt = choice-keyword sep identifier-arg-str optsep 5172 (";" / 5173 "{" stmtsep 5174 ;; these stmts can appear in any order 5175 [default-stmt stmtsep] 5176 [mandatory-stmt stmtsep] 5177 [description-stmt stmtsep] 5178 [reference-stmt stmtsep] 5179 *(refine-case-stmt stmtsep) 5180 "}") 5182 refine-case-stmt = case-keyword sep identifier-arg-str optsep 5183 (";" / 5184 "{" stmtsep 5185 ;; these stmts can appear in any order 5186 [description-stmt stmtsep] 5187 [reference-stmt stmtsep] 5188 *(refinement-stmt stmtsep) 5189 "}") 5191 refine-container-stmt = container-keyword sep identifier-arg-str optsep 5192 (";" / 5193 "{" stmtsep 5194 ;; these stmts can appear in any order 5195 *(must-stmt stmtsep) 5196 [presence-stmt stmtsep] 5197 [config-stmt stmtsep] 5198 [description-stmt stmtsep] 5199 [reference-stmt stmtsep] 5200 *(refinement-stmt stmtsep) 5201 "}") 5203 refine-anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep 5204 (";" / 5205 "{" stmtsep 5206 ;; these stmts can appear in any order 5207 [config-stmt stmtsep] 5208 [mandatory-stmt stmtsep] 5209 [description-stmt stmtsep] 5210 [reference-stmt stmtsep] 5211 "}") 5213 unknown-statement = prefix ":" identifier [sep string] optsep 5214 (";" / "{" *unknown-statement "}") 5216 augment-stmt = augment-keyword sep augment-arg-str optsep 5217 "{" stmtsep 5218 ;; these stmts can appear in any order 5219 [when-stmt stmtsep] 5220 [status-stmt stmtsep] 5221 [description-stmt stmtsep] 5222 [reference-stmt stmtsep] 5223 1*((data-def-stmt stmtsep) / 5224 (case-stmt stmtsep)) 5225 "}" 5227 augment-arg-str = < a string which matches the rule 5228 augment-arg > 5230 augment-arg = absolute-schema-nodeid / 5231 descendant-schema-nodeid 5233 when-stmt = when-keyword sep string stmtend 5235 rpc-stmt = rpc-keyword sep identifier-arg-str optsep 5236 (";" / 5237 "{" stmtsep 5238 ;; these stmts can appear in any order 5239 [status-stmt stmtsep] 5240 [description-stmt stmtsep] 5241 [reference-stmt stmtsep] 5242 *((typedef-stmt / 5243 grouping-stmt) stmtsep) 5244 [input-stmt stmtsep] 5245 [output-stmt stmtsep] 5246 "}") 5248 input-stmt = input-keyword optsep 5249 "{" stmtsep 5250 ;; these stmts can appear in any order 5252 *((typedef-stmt / 5253 grouping-stmt) stmtsep) 5254 1*(data-def-stmt stmtsep) 5255 "}" 5257 output-stmt = output-keyword optsep 5258 "{" stmtsep 5259 ;; these stmts can appear in any order 5260 *((typedef-stmt / 5261 grouping-stmt) stmtsep) 5262 1*(data-def-stmt stmtsep) 5263 "}" 5265 notification-stmt = notification-keyword sep 5266 identifier-arg-str optsep 5267 (";" / 5268 "{" stmtsep 5269 ;; these stmts can appear in any order 5270 [status-stmt stmtsep] 5271 [description-stmt stmtsep] 5272 [reference-stmt stmtsep] 5273 *((typedef-stmt / 5274 grouping-stmt) stmtsep) 5275 *(data-def-stmt stmtsep) 5276 "}") 5278 ;; Ranges 5280 range-arg-str = < a string which matches the rule 5281 range-arg > 5283 range-arg = range-part *(optsep "|" optsep range-part) 5285 range-part = range-boundary 5286 [optsep ".." optsep range-boundary] 5288 range-boundary = neginf-keyword / posinf-keyword / 5289 min-keyword / max-keyword / 5290 decimal-value / float-value 5292 ;; Lengths 5294 length-arg-str = < a string which matches the rule 5295 length-arg > 5297 length-arg = length-part *(optsep "|" optsep length-part) 5299 length-part = length-boundary 5301 [optsep ".." optsep length-boundary] 5303 length-boundary = min-keyword / max-keyword / 5304 non-negative-decimal-value 5306 ;; Date 5308 date-arg-str = < a string which matches the rule 5309 date-arg > 5311 date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT 5313 ;; Schema Node Identifiers 5315 schema-nodeid = absolute-schema-nodeid / 5316 relative-schema-nodeid 5318 absolute-schema-nodeid 5319 = 1*("/" node-identifier) 5321 relative-schema-nodeid 5322 = descendant-schema-nodeid / 5323 (("." / "..") "/" 5324 *relative-schema-nodeid) 5326 descendant-schema-nodeid 5327 = node-identifier 5328 absolute-schema-nodeid 5330 node-identifier = [prefix ":"] identifier 5332 ;; Instance Identifiers 5334 instance-identifier-str 5335 = < a string which matches the rule 5336 instance-identifier > 5338 instance-identifier = absolute-instid / relative-instid 5340 absolute-instid = 1*("/" (node-identifier *predicate)) 5342 relative-instid = descendant-instid / 5343 (("." / "..") "/" 5344 *relative-instid) 5346 descendant-instid = node-identifier *predicate 5347 absolute-instid 5349 predicate = "[" *WSP predicate-expr *WSP "]" 5351 predicate-expr = (node-identifier / ".") *WSP "=" *WSP 5352 ((DQUOTE string DQUOTE) / 5353 (SQUOTE string SQUOTE)) 5355 ;; keyref path 5357 path-arg-str = < a string which matches the rule 5358 path-arg > 5360 path-arg = absolute-path / relative-path 5362 absolute-path = 1*("/" (node-identifier *path-predicate)) 5364 relative-path = descendant-path / 5365 (".." "/" 5366 *relative-path) 5368 descendant-path = node-identifier *path-predicate 5369 absolute-path 5371 path-predicate = "[" *WSP path-equality-expr *WSP "]" 5373 path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr 5375 path-key-expr = this-variable-keyword "/" rel-path-keyexpr 5377 rel-path-keyexpr = 1*(".." "/") *(node-identifier "/") 5378 node-identifier 5380 ;;; Keywords, using abnfgen's syntax for case-sensitive strings 5382 ;; statment keywords 5383 anyxml-keyword = 'anyxml' 5384 argument-keyword = 'argument' 5385 augment-keyword = 'augment' 5386 belongs-to-keyword = 'belongs-to' 5387 bit-keyword = 'bit' 5388 case-keyword = 'case' 5389 choice-keyword = 'choice' 5390 config-keyword = 'config' 5391 contact-keyword = 'contact' 5392 container-keyword = 'container' 5393 default-keyword = 'default' 5394 description-keyword = 'description' 5395 enum-keyword = 'enum' 5396 error-app-tag-keyword = 'error-app-tag' 5397 error-message-keyword = 'error-message' 5398 extension-keyword = 'extension' 5399 grouping-keyword = 'grouping' 5400 import-keyword = 'import' 5401 include-keyword = 'include' 5402 input-keyword = 'input' 5403 key-keyword = 'key' 5404 leaf-keyword = 'leaf' 5405 leaf-list-keyword = 'leaf-list' 5406 length-keyword = 'length' 5407 list-keyword = 'list' 5408 mandatory-keyword = 'mandatory' 5409 max-elements-keyword = 'max-elements' 5410 min-elements-keyword = 'min-elements' 5411 module-keyword = 'module' 5412 must-keyword = 'must' 5413 namespace-keyword = 'namespace' 5414 notification-keyword = 'notification' 5415 ordered-by-keyword = 'ordered-by' 5416 organization-keyword = 'organization' 5417 output-keyword = 'output' 5418 path-keyword = 'path' 5419 pattern-keyword = 'pattern' 5420 position-keyword = 'position' 5421 prefix-keyword = 'prefix' 5422 presence-keyword = 'presence' 5423 range-keyword = 'range' 5424 reference-keyword = 'reference' 5425 revision-keyword = 'revision' 5426 rpc-keyword = 'rpc' 5427 status-keyword = 'status' 5428 submodule-keyword = 'submodule' 5429 type-keyword = 'type' 5430 typedef-keyword = 'typedef' 5431 unique-keyword = 'unique' 5432 units-keyword = 'units' 5433 uses-keyword = 'uses' 5434 value-keyword = 'value' 5435 when-keyword = 'when' 5436 yang-version-keyword = 'yang-version' 5437 yin-element-keyword = 'yin-element' 5439 ;; other keywords 5441 current-keyword = 'current' 5442 deprecated-keyword = 'deprecated' 5443 false-keyword = 'false' 5444 max-keyword = 'max' 5445 min-keyword = 'min' 5446 nan-keyword = 'NaN' 5447 neginf-keyword = '-INF' 5448 obsolete-keyword = 'obsolete' 5449 posinf-keyword = 'INF' 5450 system-keyword = 'system' 5451 this-variable-keyword = '$this' 5452 true-keyword = 'true' 5453 unbounded-keyword = 'unbounded' 5454 user-keyword = 'user' 5456 ;; Basic Rules 5458 keyword = [prefix ":"] identifier 5460 prefix-arg-str = < a string which matches the rule 5461 prefix-arg > 5463 prefix-arg = prefix 5465 prefix = identifier 5467 identifier-arg-str = < a string which matches the rule 5468 identifier-arg > 5470 identifier-arg = identifier 5472 identifier = (ALPHA / "_") 5473 *(ALPHA / DIGIT / "_" / "-" / ".") 5475 identifier-ref-arg-str = < a string which matches the rule 5476 identifier-ref-arg > 5478 identifier-ref-arg = [prefix ":"] identifier 5480 string = < an unquoted string as returned by 5481 the scanner > 5483 decimal-value = ("-" non-negative-decimal-value) / 5484 non-negative-decimal-value 5486 non-negative-decimal-value = "0" / positive-decimal-value 5488 positive-decimal-value = (non-zero-digit *DIGIT) 5490 zero-decimal-value = 1*DIGIT 5492 stmtend = ";" / "{" *unknown-statement "}" 5493 sep = 1*(WSP / line-break) 5494 ; unconditional separator 5496 optsep = *(WSP / line-break) 5498 stmtsep = *(WSP / line-break / unknown-statement) 5500 line-break = CRLF / LF 5502 non-zero-digit = %x31-39 5504 float-value = neginf-keyword / 5505 posinf-keyword / 5506 nan-keyword / 5507 decimal-value "." zero-decimal-value 5508 *1("E" ("+"/"-") zero-decimal-value) 5510 SQUOTE = %x27 5511 ; ' (Single Quote) 5513 ;; 5514 ;; RFC 4234 core rules. 5515 ;; 5517 ALPHA = %x41-5A / %x61-7A 5518 ; A-Z / a-z 5520 CR = %x0D 5521 ; carriage return 5523 CRLF = CR LF 5524 ; Internet standard newline 5526 DIGIT = %x30-39 5527 ; 0-9 5529 DQUOTE = %x22 5530 ; " (Double Quote) 5532 HEXDIG = DIGIT / 5533 %x61 / %x62 / %x63 / %x64 / %x65 / %x66 5534 ; only lower-case a..f 5536 HTAB = %x09 5537 ; horizontal tab 5539 LF = %x0A 5540 ; linefeed 5542 SP = %x20 5543 ; space 5545 VCHAR = %x21-7E 5546 ; visible (printing) characters 5548 WSP = SP / HTAB 5549 ; white space 5551 12. Error Responses for YANG Related Errors 5553 A number of NETCONF error responses are defined for error cases 5554 related to the data-model handling. If the relevant YANG statement 5555 has an "error-app-tag" substatement, that overrides the default value 5556 specified below. 5558 12.1. Error Message for Data that Violates a YANG unique Statement: 5560 If a NETCONF operation would result in configuration data where a 5561 unique constraint is invalidated, the following error is returned: 5563 Tag: operation-failed 5564 Error-app-tag: data-not-unique 5565 Error-info: : Contains an instance identifier which 5566 points to a leaf which invalidates the unique 5567 constraint. This element is present once for each 5568 leaf invalidating the unique constraint. 5570 The element is in the YANG 5571 namespace ("urn:ietf:params:xml:ns:yang:1" 5572 [XXX IANA]). 5574 12.2. Error Message for Data that Violates a YANG max-elements 5575 Statement: 5577 If a NETCONF operation would result in configuration data where a 5578 list or a leaf-list would have too many entries the following error 5579 is returned: 5581 Tag: operation-failed 5582 Error-app-tag: too-many-elements 5584 This error is returned once, with the error-path identifying the list 5585 node, even if there are more than one extra child present. 5587 12.3. Error Message for Data that Violates a YANG min-elements 5588 Statement: 5590 If a NETCONF operation would result in configuration data where a 5591 list or a leaf-list would have too few entries the following error is 5592 returned: 5594 Tag: operation-failed 5595 Error-app-tag: too-few-elements 5597 This error is returned once, with the error-path identifying the list 5598 node, even if there are more than one child missing. 5600 12.4. Error Message for Data that Violates a YANG must statement: 5602 If a NETCONF operation would result in configuration data where the 5603 restrictions imposed by a "must" statement is violated the following 5604 error is returned, unless a specific "error-app-tag" substatement is 5605 present for the "must" statement. 5607 Tag: operation-failed 5608 Error-app-tag: must-violation 5610 12.5. Error Message for the "insert" Operation 5612 If the "insert" and "key" or "value" attributes are used in an for a list or leaf-list node, and the "key" or "value" refers 5614 to a non-existing instance, the following error is returned: 5616 Tag: bad-attribute 5617 Error-app-tag: missing-instance 5619 13. IANA Considerations 5621 This document registers two URIs for the YANG XML namespace in the 5622 IETF XML registry [RFC3688]. 5624 URI: urn:ietf:params:xml:ns:yang:yin:1 5626 URI: urn:ietf:params:xml:ns:yang:1 5628 14. Security Considerations 5630 This document defines a language with which to write and read 5631 descriptions of management information. The language itself has no 5632 security impact on the Internet. 5634 Data modeled in YANG might contain sensitive information. RPCs or 5635 notifications defined in YANG might transfer sensitive information. 5637 Security issues are related to the usage of data modeled in YANG. 5638 Such issues shall be dealt with in documents describing the data 5639 models and documents about the interfaces used to manipulate the data 5640 e.g. the NETCONF documents. 5642 YANG is dependent upon: 5644 o the security of the transmission infrastructure used to send 5645 sensitive information 5647 o the security of applications which store or release such sensitive 5648 information. 5650 o adequate authentication and access control mechanisms to restrict 5651 the usage of sensitive data. 5653 15. Contributors 5655 The following people all contributed significantly to the initial 5656 YANG draft: 5658 - Andy Bierman (andybierman.com) 5659 - Balazs Lengyel (Ericsson) 5660 - David Partain (Ericsson) 5661 - Juergen Schoenwaelder (Jacobs University Bremen) 5662 - Phil Shafer (Juniper Networks) 5664 16. References 5666 16.1. Normative References 5668 [IEEE.754] 5669 Institute of Electrical and Electronics Engineers, 5670 "Standard for Binary Floating-Point Arithmetic", 5671 IEEE Standard 754, August 1985. 5673 [ISO.10646] 5674 International Organization for Standardization, 5675 "Information Technology - Universal Multiple-octet coded 5676 Character Set (UCS) - Part 1: Architecture and Basic 5677 Multilingual Plane", ISO Standard 10646-1, May 1993. 5679 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5680 Requirement Levels", BCP 14, RFC 2119, March 1997. 5682 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 5683 10646", STD 63, RFC 3629, November 2003. 5685 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 5686 January 2004. 5688 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 5689 Resource Identifier (URI): Generic Syntax", STD 66, 5690 RFC 3986, January 2005. 5692 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 5693 Encodings", RFC 4648, October 2006. 5695 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 5696 December 2006. 5698 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 5699 Specifications: ABNF", STD 68, RFC 5234, January 2008. 5701 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 5702 Notifications", RFC 5277, July 2008. 5704 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 5705 Version 1.0", World Wide Web Consortium 5706 Recommendation REC-xpath-19991116, November 1999, 5707 . 5709 [XSD-TYPES] 5710 Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes 5711 Second Edition", W3C REC REC-xmlschema-2-20041028, 5712 October 2004. 5714 16.2. Non-Normative References 5716 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 5717 Schoenwaelder, Ed., "Structure of Management Information 5718 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 5720 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 5721 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 5722 STD 58, RFC 2579, April 1999. 5724 [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation 5725 Structure of Management Information", RFC 3780, May 2004. 5727 Appendix A. ChangeLog 5729 A.1. Version -01 5731 o Removed "Appendix A. Derived YANG Types". 5733 o Removed "Appendix C. XML Schema Considerations". 5735 o Removed "Appendix F. Why We Need a New Modeling Language". 5737 o Moved "Appendix B. YIN" to its own section. 5739 o Moved "Appendix D. YANG ABNF Grammar" to its own section. 5741 o Moved "Appendix E. Error Responses for YANG Related Errors" into 5742 its own section. 5744 o The "input" and "output" nodes are now implicitly created by the 5745 "rpc" statement, in order for augmentation of these nodes to work 5746 correctly. 5748 o Allow "config" in "choice". 5750 o Added reference to XPath 1.0. 5752 o Using an XPath function "current()" instead of the variable 5753 "$this". 5755 o Clarified that a "must" expression in a configuration node must 5756 not reference non-configuration nodes. 5758 o Added XML encoding rules and usage examples for rpc and 5759 notification. 5761 o Removed requirement that refinements are specified in the same 5762 order as in the original grouping's definition. 5764 o Fixed whitespace issues in the ABNF grammar. 5766 o Added the term "mandatory node", and refer to it in the 5767 description of augment (see Section 7.15), and choice (see 5768 Section 7.9.3). 5770 o Added support for multiple "pattern" statements in "type". 5772 o Several clarifications and fixed typos. 5774 A.2. Version -00 5776 Changes from draft-bjorklund-netconf-yang-02.txt 5778 o Fixed bug in grammar for bit-stmt 5780 o Fixed bugs in example XPath expressions 5782 o Added keyword 'presence' to the YIN mapping table 5784 Author's Address 5786 Martin Bjorklund (editor) 5787 Tail-f Systems 5789 Email: mbj@tail-f.com 5791 Full Copyright Statement 5793 Copyright (C) The IETF Trust (2008). 5795 This document is subject to the rights, licenses and restrictions 5796 contained in BCP 78, and except as set forth therein, the authors 5797 retain all their rights. 5799 This document and the information contained herein are provided on an 5800 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 5801 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 5802 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 5803 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 5804 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 5805 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5807 Intellectual Property 5809 The IETF takes no position regarding the validity or scope of any 5810 Intellectual Property Rights or other rights that might be claimed to 5811 pertain to the implementation or use of the technology described in 5812 this document or the extent to which any license under such rights 5813 might or might not be available; nor does it represent that it has 5814 made any independent effort to identify any such rights. Information 5815 on the procedures with respect to rights in RFC documents can be 5816 found in BCP 78 and BCP 79. 5818 Copies of IPR disclosures made to the IETF Secretariat and any 5819 assurances of licenses to be made available, or the result of an 5820 attempt made to obtain a general license or permission for the use of 5821 such proprietary rights by implementers or users of this 5822 specification can be obtained from the IETF on-line IPR repository at 5823 http://www.ietf.org/ipr. 5825 The IETF invites any interested party to bring to its attention any 5826 copyrights, patents or patent applications, or other proprietary 5827 rights that may cover technology that may be required to implement 5828 this standard. Please address the information to the IETF at 5829 ietf-ipr@ietf.org. 5831 Acknowledgment 5833 Funding for the RFC Editor function is provided by the IETF 5834 Administrative Support Activity (IASA).