--- 1/draft-ietf-netmod-yang-12.txt 2010-06-02 01:12:18.000000000 +0200 +++ 2/draft-ietf-netmod-yang-13.txt 2010-06-02 01:12:18.000000000 +0200 @@ -1,18 +1,19 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track April 14, 2010 -Expires: October 16, 2010 +Intended status: Standards Track June 1, 2010 +Expires: December 3, 2010 - YANG - A data modeling language for NETCONF - draft-ietf-netmod-yang-12 + YANG - A data modeling language for the Network Configuration Protocol + (NETCONF) + draft-ietf-netmod-yang-13 Abstract YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF notifications. Status of this Memo @@ -28,21 +29,21 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on October 16, 2010. + This Internet-Draft will expire on December 3, 2010. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -93,21 +94,21 @@ 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 5.6.4. Announcing Conformance Information in the Message . . . . . . . . . . . . . . . . . . . . . . . 34 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 36 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 37 - 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 37 + 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 37 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 37 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 37 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 37 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 39 6.2.1. Identifiers and their namespaces . . . . . . . . . . 39 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 40 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 40 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 40 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 41 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 41 @@ -117,21 +118,21 @@ 7.1.2. The yang-version Statement . . . . . . . . . . . . . 45 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 45 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 46 7.1.5. The import Statement . . . . . . . . . . . . . . . . 46 7.1.6. The include Statement . . . . . . . . . . . . . . . . 47 7.1.7. The organization Statement . . . . . . . . . . . . . 48 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 48 7.1.9. The revision Statement . . . . . . . . . . . . . . . 48 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 49 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 49 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 50 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 51 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 51 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 52 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 52 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 53 7.3.2. The typedef's type Statement . . . . . . . . . . . . 53 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 53 7.3.4. The typedef's default Statement . . . . . . . . . . . 53 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 54 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 54 7.4.1. The type's Substatements . . . . . . . . . . . . . . 54 @@ -216,152 +217,155 @@ 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 7.18. Conformance-related Statements . . . . . . . . . . . . . 103 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 103 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 105 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 105 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 108 7.19.1. The config Statement . . . . . . . . . . . . . . . . 108 7.19.2. The status Statement . . . . . . . . . . . . . . . . 108 7.19.3. The description Statement . . . . . . . . . . . . . . 109 7.19.4. The reference Statement . . . . . . . . . . . . . . . 109 - 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 109 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 111 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 111 - 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 111 - 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 111 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 112 - 8.3.2. NETCONF Processing . . . . . . . . . . 112 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 113 - 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 114 - 9.1. Canonical representation . . . . . . . . . . . . . . . . 114 - 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 114 - 9.2.1. Lexicographic Representation . . . . . . . . . . . . 115 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 116 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 - 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 117 - 9.3.1. Lexicographic Representation . . . . . . . . . . . . 117 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 118 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 - 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 119 - 9.4.1. Lexicographic Representation . . . . . . . . . . . . 119 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 119 - 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 - 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 121 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 121 - 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 122 - 9.5.1. Lexicographic Representation . . . . . . . . . . . . 122 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 - 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 122 - 9.6.1. Lexicographic Representation . . . . . . . . . . . . 122 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 122 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 - 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 124 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 - 9.7.2. Lexicographic Representation . . . . . . . . . . . . 124 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 124 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 124 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 125 - 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 125 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126 - 9.8.2. Lexicographic Representation . . . . . . . . . . . . 126 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 126 - 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 126 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 126 - 9.9.3. Lexicographic Representation . . . . . . . . . . . . 127 - 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 127 - 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 127 - 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 131 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 - 9.10.2. The identityref's base Statement . . . . . . . . . . 131 - 9.10.3. Lexicographic Representation . . . . . . . . . . . . 132 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 132 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 132 - 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 133 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 133 - 9.11.2. Lexicographic Representation . . . . . . . . . . . . 133 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 133 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 133 - 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 134 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 - 9.12.2. Lexicographic Representation . . . . . . . . . . . . 134 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 - 9.13. The instance-identifier Built-in Type . . . . . . . . . . 135 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 - 9.13.2. The require-instance Statement . . . . . . . . . . . 136 - 9.13.3. Lexicographic Representation . . . . . . . . . . . . 136 - 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 136 - 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 - 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 138 - 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 - 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 141 - 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 143 + 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 110 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 112 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 112 + 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 112 + 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 112 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 113 + 8.3.2. NETCONF Processing . . . . . . . . . . 113 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 114 + 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 115 + 9.1. Canonical representation . . . . . . . . . . . . . . . . 115 + 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 115 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 116 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 117 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 118 + 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 118 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 118 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 119 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 + 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 120 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 120 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 120 + 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 + 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 122 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 122 + 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 123 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 123 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 + 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 123 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 123 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 123 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124 + 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 125 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 125 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 125 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 125 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 + 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 126 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 127 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 127 + 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 127 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 127 + 9.9.3. Lexical Representation . . . . . . . . . . . . . . . 128 + 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 128 + 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 + 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 132 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 + 9.10.2. The identityref's base Statement . . . . . . . . . . 132 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 133 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 133 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 + 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 134 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 134 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 134 + 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 135 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 135 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 + 9.13. The instance-identifier Built-in Type . . . . . . . . . . 136 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 + 9.13.2. The require-instance Statement . . . . . . . . . . . 137 + 9.13.3. Lexical Representation . . . . . . . . . . . . . . . 137 + 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 137 + 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 + 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 139 + 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 + 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 142 + 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 144 - 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 146 - 13. Error Responses for YANG Related Errors . . . . . . . . . . . 168 - 13.1. Error Message for Data that Violates a unique Statement . 168 + 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 147 + 13. Error Responses for YANG Related Errors . . . . . . . . . . . 169 + 13.1. Error Message for Data that Violates a unique Statement . 169 13.2. Error Message for Data that Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . . 168 + Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 13.3. Error Message for Data that Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . . 168 - 13.4. Error Message for Data that Violates a must Statement . . 169 + Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 + 13.4. Error Message for Data that Violates a must Statement . . 170 13.5. Error Message for Data that Violates a - require-instance Statement . . . . . . . . . . . . . . . 169 + require-instance Statement . . . . . . . . . . . . . . . 170 13.6. Error Message for Data that does not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 169 + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 170 13.7. Error Message for Data that Violates a mandatory - choice Statement . . . . . . . . . . . . . . . . . . . . 169 - 13.8. Error Message for the "insert" Operation . . . . . . . . 170 - 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 171 - 15. Security Considerations . . . . . . . . . . . . . . . . . . . 172 - 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 173 - 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 174 - 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 175 - 18.1. Normative References . . . . . . . . . . . . . . . . . . 175 - 18.2. Non-Normative References . . . . . . . . . . . . . . . . 176 - Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 177 - A.1. Version -12 . . . . . . . . . . . . . . . . . . . . . . . 177 - A.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 177 - A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 177 - A.4. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 177 - A.5. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 178 - A.6. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 178 - A.7. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 178 - A.8. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 178 - A.9. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 179 - A.10. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 179 - A.11. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 180 - A.12. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 180 - A.13. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 181 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 182 + choice Statement . . . . . . . . . . . . . . . . . . . . 170 + 13.8. Error Message for the "insert" Operation . . . . . . . . 171 + 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 172 + 14.1. Media type application/yang . . . . . . . . . . . . . . . 173 + 14.2. Media type application/yin+xml . . . . . . . . . . . . . 173 + 15. Security Considerations . . . . . . . . . . . . . . . . . . . 175 + 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 176 + 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 177 + 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 178 + 18.1. Normative References . . . . . . . . . . . . . . . . . . 178 + 18.2. Non-Normative References . . . . . . . . . . . . . . . . 179 + Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 180 + A.1. Version -12 . . . . . . . . . . . . . . . . . . . . . . . 180 + A.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 180 + A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 180 + A.4. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 180 + A.5. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 181 + A.6. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 181 + A.7. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 181 + A.8. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 181 + A.9. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 182 + A.10. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 182 + A.11. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 183 + A.12. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 183 + A.13. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 184 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 185 1. Introduction YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF notifications. YANG is used to model the operations and content layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], section 1.1). This document describes the syntax and semantics of the YANG language, how the data model defined in a YANG module is represented - in XML, and how NETCONF operations are used to manipulate the data. + in the Extensible Markup Language (XML), and how NETCONF operations + are used to manipulate the data. 2. Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119]. 3. Terminology @@ -510,21 +514,21 @@ can import data from other external modules, and include data from submodules. The hierarchy can be augmented, allowing one module to add data nodes to the hierarchy defined in another module. This augmentation can be conditional, with new nodes appearing only if certain conditions are met. YANG models can describe constraints to be enforced on the data, restricting the appearance or value of nodes based on the presence or value of other nodes in the hierarchy. These constraints are enforceable by either the client or the server, and valid content - must abide by them. + MUST abide by them. YANG defines a set of built-in types, and has a type mechanism through which additional types may be defined. Derived types can restrict their base type's set of valid values using mechanisms like range or pattern restrictions that can be enforced by clients or servers. They can also define usage conventions for use of the derived type, such as a string-based type that contains a host name. YANG permits the definition of reusable grouping of nodes. The instantiation of these groupings can refine or augment the nodes, @@ -935,22 +939,22 @@ sets of schema nodes that cannot appear together. Each "case" may contain multiple nodes, but each node may appear in only one "case" under a "choice". When an element from one case is created, all elements from all other cases are implicitly deleted. The device handles the enforcement of the constraint, preventing incompatibilities from existing in the configuration. The choice and case nodes appear only in the schema tree, not in the - data tree or NETCONF PDUs. The additional levels of hierarchy are - not needed beyond the conceptual schema. + data tree or NETCONF messages. The additional levels of hierarchy + are not needed beyond the conceptual schema. YANG Example: container food { choice snack { case sports-arena { leaf pretzel { type empty; } leaf beer { @@ -1190,22 +1194,22 @@ 5.1.2. Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may have more than one top-level node. Models that have multiple top- level nodes are sometimes convenient, and are supported by YANG. NETCONF is capable of carrying any XML content as the payload in the and elements. The top-level nodes of YANG modules are encoded as child elements, in any order, within these elements. - This encapsulation guarantees that the corresponding NETCONF PDUs are - always well-formed XML documents. + This encapsulation guarantees that the corresponding NETCONF messages + are always well-formed XML documents. For example: module my-config { namespace "http://example.com/schema/config"; prefix "co"; container system { ... } container routing { ... } } @@ -1494,21 +1498,21 @@ 6. YANG syntax The YANG syntax is similar to that of SMIng [RFC3780] and programming languages like C and C++. This C-like syntax was chosen specifically for its readability, since YANG values the time and effort of the readers of models above those of modules writers and YANG tool-chain developers. This section introduces the YANG syntax. YANG modules use the UTF-8 [RFC3629] character encoding. -6.1. Lexicographical Tokenization +6.1. Lexical Tokenization YANG modules are parsed as a series of tokens. This section details the rules for recognizing tokens from an input stream. YANG tokenization rules are both simple and powerful. The simplicity is driven by a need to keep the parsers easy to implement, while the power is driven by the fact that modelers need to express their models in readable formats. 6.1.1. Comments @@ -1528,21 +1532,22 @@ 6.1.3. Quoting If a string contains any space or tab characters, a semicolon (";"), braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then it MUST be enclosed within double or single quotes. If the double quoted string contains a line break followed by space or tab characters which are used to indent the text according to the layout in the YANG file, this leading whitespace is stripped from the string, up to and including the column of the double quote character, - or to the first non-whitespace character, whichever occurs first. + or to the first non-whitespace character, whichever occurs first. In + this process, a tab character is treated as 8 space characters. If the double quoted string contains space or tab characters before a line break, this trailing whitespace is stripped from the string. A single quoted string (enclosed within ' ') preserves each character within the quotes. A single quote character cannot occur in a single quoted string, even when preceded by a backslash. Within a double quoted string (enclosed within " "), a backslash character introduces a special character, which depends on the @@ -1763,21 +1768,21 @@ Names of modules published in RFC streams [RFC4844] MUST be assigned by IANA, see Section 14. Private module names are assigned by the organization owning the module without a central registry. It is RECOMMENDED to choose module names that will have a low probability of colliding with standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix for the module name. - A module SHOULD have the following layout: + A module typically has the following layout: module { // header information // linkage statements @@ -1828,27 +1833,32 @@ | yang-version | 7.1.2 | 0..1 | +--------------+---------+-------------+ 7.1.2. The yang-version Statement The optional "yang-version" statement specifies which version of the YANG language was used in developing the module. The statement's argument is a string. If present, it MUST contain the value "1", which is the current YANG version and the default value. + Handling of the "yang-version" statement for versions other than "1" + (the version defined here) is out of scope for this specification. + Any document that defines a higher version will need to define the + backward compatibility of such a higher version. + 7.1.3. The namespace Statement - The "namespace" statement defines the XML namespace to which all - identifiers defined by the module belong, with the exception of data - node identifiers defined inside a grouping (see Section 7.12 for - details). The argument to the "namespace" statement is the URI of - the namespace. + The "namespace" statement defines the XML namespace which all + identifiers defined by the module are qualified by, with the + exception of data node identifiers defined inside a grouping (see + Section 7.12 for details). The argument to the "namespace" statement + is the URI of the namespace. See also Section 5.3. 7.1.4. The prefix Statement The "prefix" statement is used to define the prefix associated with the module and its namespace. The "prefix" statement's argument is the prefix string which is used as a prefix to access a module. The prefix string MAY be used to refer to definitions contained in the module, e.g., "if:ifName". A prefix follows the same rules as an @@ -1860,21 +1870,23 @@ which generates XML or XPath that use prefixes SHOULD use the prefix defined by the module, unless there is a conflict. When used inside the "import" statement, the "prefix" statement defines the prefix to be used when accessing definitions inside the imported module. When a reference to an identifier from the imported module is used, the prefix string for the imported module is used in combination with a colon (":") and the identifier, e.g., "if: ifIndex". To improve readability of YANG modules, the prefix defined by a module SHOULD be used when the module is imported, unless there - is a conflict. + is a conflict. If there is a conflict, i.e., two different modules + which both have defined the same prefix are imported, at least one of + them MUST be imported with a different prefix. All prefixes, including the prefix for the module itself MUST be unique within the module or submodule. 7.1.5. The import Statement The "import" statement makes definitions from one module available inside another module or submodule. The argument is the name of the module to import, and the statement is followed by a block of substatements that holds detailed import information. When a module @@ -1891,22 +1903,24 @@ "augment" statement The mandatory "prefix" substatement assigns a prefix for the imported module which is scoped to the importing module or submodule. Multiple "import" statements may be specified to import from different modules. When the optional "revision-date" substatement is present, any typedef, grouping, extension, feature, and identity referenced by definitions in the local module are taken from the specified revision - of the imported module. Otherwise, it is undefined from which - revision of the module they are taken. + of the imported module. It is an error if the specified revision of + the imported module does not exist. If no "revision-date" + substatement is present, it is undefined from which revision of the + module they are taken. Multiple revisions of the same module MUST NOT be imported. The import's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | prefix | 7.1.4 | 1 | | revision-date | 7.1.5.1 | 0..1 | @@ -1926,23 +1940,25 @@ name of the submodule to include. Modules are only allowed to include submodules that belong to that module, as defined by the "belongs-to" statement (see Section 7.2.2). Submodules are only allowed to include other submodules belonging to the same module. When a module includes a submodule, it incorporates the contents of the submodule into the node hierarchy of the module. When a submodule includes another submodule, the target submodule's definitions are made available to the current submodule. - When the optional "revision-date" is present, the specified revision - of the submodule is included in the module. Otherwise, it is - undefined which revision of the submodule is included. + When the optional "revision-date" substatement is present, the + specified revision of the submodule is included in the module. It is + an error if the specified revision of the submodule does not exist. + If no "revision-date" substatement is present, it is undefined which + revision of the submodule is included. Multiple revisions of the same submodule MUST NOT be included. The includes's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | revision-date | 7.1.5.1 | 0..1 | +---------------+---------+-------------+ @@ -2035,21 +2051,21 @@ Names of submodules published in RFC streams [RFC4844] MUST be assigned by IANA, see Section 14. Private submodule names are assigned by the organization owning the submodule without a central registry. It is RECOMMENDED to choose submodule names that will have a low probability of colliding with standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix for the submodule name. - A submodule SHOULD have the following layout: + A submodule typically has the following layout: submodule { // module identification // linkage statements @@ -2310,23 +2327,23 @@ | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | | when | 7.19.5 | 0..1 | +--------------+---------+-------------+ 7.5.3. The must Statement The "must" statement, which is optional, takes as an argument a - string which contains an XPath expression. It is used to formally - declare a constraint on valid data. The constraint is enforced - according to the rules in Section 8. + string which contains an XPath expression (see Section 6.4). It is + used to formally declare a constraint on valid data. The constraint + is enforced according to the rules in Section 8. When a datastore is validated, all "must" constraints are conceptually evaluated once for each data node in the data tree, and for all leafs with default values in use (see Section 7.6.1). If a data node does not exist in the data tree, and it does not have a default value, its "must" statements are not evaluated. All such constraints MUST evaluate to true for the data to be valid. The XPath expression is conceptually evaluated in the following @@ -2555,22 +2572,22 @@ be used if any node from the case exists in the data tree, or if the case node is the choice's default case, and no nodes from any other case exist in the data tree. o Otherwise, the default value MUST be used if the ancestor node exists in the data tree. In these cases, the default value is said to be in use. When the default value is in use, the server MUST operationally - behave as is if the leaf was present in the data tree with the - default value as its value. + behave as if the leaf was present in the data tree with the default + value as its value. If a leaf has a "default" statement, the leaf's default value is the value of the "default" statement. Otherwise, if the leaf's type has a default value, and the leaf is not mandatory, then the leaf's default value is the type's default value. In all other cases, the leaf does not have a default value. 7.6.2. The leaf's Substatements +--------------+---------+-------------+ @@ -2713,23 +2730,23 @@ If the type referenced by the leaf-list has a default value, it has no effect in the leaf-list. 7.7.1. Ordering YANG supports two styles for ordering the entries within lists and leaf-lists. In many lists, the order of list entries does not impact the implementation of the list's configuration, and the device is free to sort the list entries in any reasonable order. The - "description" string for the list may suggest an order. YANG calls - this style of list "system ordered" and they are indicated with the - statement "ordered-by system". + "description" string for the list may suggest an order to the device + implementor. YANG calls this style of list "system ordered" and they + are indicated with the statement "ordered-by system". For example, a list of valid users would typically be sorted alphabetically, since the order in which the users appeared in the configuration would not impact the creation of those users' accounts. In the other style of lists, the order of list entries matters for the implementation of the list's configuration and the user is responsible for ordering the entries, while the device maintains that order. YANG calls this style of list "user ordered" and they are indicated with the statement "ordered-by user". @@ -2962,23 +2979,20 @@ The "list" statement is used to define an interior data node in the schema tree. A list node may exist in multiple instances in the data tree. Each such instance is known as a list entry. The "list" statement takes one argument which is an identifier, followed by a block of substatements that holds detailed list information. A list entry is uniquely identified by the values of the list's keys, if defined. - A list is similar to a table where each list entry is a row in the - table. - 7.8.1. The list's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | | choice | 7.9 | 0..n | | config | 7.19.1 | 0..1 | | container | 7.5 | 0..n | | description | 7.19.3 | 0..1 | @@ -3152,22 +3166,26 @@ same request, the entries are modified one at the time, in the order of the XML elements in the request. In a , or an with a "replace" operation which covers the entire list, the list entry order is the same as the order of the XML elements in the request. When a NETCONF server processes an request, the elements of procedure for a list node are: - If the operation is "merge" or "replace" the list entry is created - if it does not exist. + If the operation is "merge" or "replace", the list entry is + created if it does not exist. If the list entry already exists + and the "insert" and "key" attributes are present, the list entry + is moved according to the values of the "insert" and "key" + attributes. If the list entry exists and the "insert" and "key" + attributes are not present, the list entry is not moved. If the operation is "create" the list entry is created if it does not exist. If the list entry already exists, a "data-exists" error is returned. If the operation is "delete" the entry is deleted from the list if it exists. If the list entry does not exist, a "data-missing" error is returned. 7.8.7. Usage Example @@ -3551,21 +3569,21 @@ The "anyxml" statement defines an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed anyxml information. The anyxml statement is used to represent an unknown chunk of XML. No restrictions are placed on the XML. This can be useful, for example, in RPC replies. An example is the parameter in the operation. - An anyxml node cannot be augmented. + An anyxml node cannot be augmented (see Section 7.15). Since the use of anyxml limits the manipulation of the content, it is RECOMMENDED that the anyxml statement not be used to represent configuration data. An anyxml node exists in zero or one instances in the data tree. 7.10.1. The anyxml's Substatements +--------------+---------+-------------+ @@ -4381,25 +4399,25 @@ This section defines statements related to conformance, as described in Section 5.6. 7.18.1. The feature Statement The "feature" statement is used to define a mechanism by which portions of the schema are marked as conditional. A feature name is defined that can later be referenced using the "if-feature" statement (see Section 7.18.2). Schema nodes tagged with a feature are ignored - unless the device supports the given feature. This allows portions - of the YANG module to be conditional based on conditions on the - device. The model can represent the abilities of the device within - the model, giving a richer model that allows for differing device - abilities and roles. + by the device unless the device supports the given feature. This + allows portions of the YANG module to be conditional based on + conditions on the device. The model can represent the abilities of + the device within the model, giving a richer model that allows for + differing device abilities and roles. The argument to the "feature" statement is the name of the new feature, and follows the rules for identifiers in Section 6.2. This name is used by the "if-feature" statement to tie the schema nodes to the feature. In this example, a feature called "local-storage" represents the ability for a device to store syslog messages on local storage of some sort. This feature is used to make the "local-storage-limit" leaf conditional on the presence of some sort of local storage. If @@ -4428,23 +4446,24 @@ } } The "if-feature" statement can be used in many places within the YANG syntax. Definitions tagged with "if-feature" are ignored when the device does not support that feature. A feature MUST NOT reference itself, neither directly nor indirectly through a chain of other features. - If a feature is dependent on any other features (i.e., the feature - has one or more "if-feature" sub-statements), then all of features it - depends on MUST also be implemented by the device. + In order for a device to implement a feature that is dependent on any + other features (i.e., the feature has one or more "if-feature" sub- + statements), the device MUST also implement all the dependant + features. 7.18.1.1. The feature's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | | status | 7.19.2 | 0..1 | | reference | 7.19.4 | 0..1 | @@ -4475,23 +4494,25 @@ contents of the deviation statement give details about the deviation. The argument string is an absolute schema node identifier (see Section 6.5). Deviations define the way a device or class of devices deviate from a standard. This means that deviations MUST never be part of a published standard, since they are the mechanism for learning how implementations vary from the standards. - Device deviations are strongly discouraged and SHOULD only be used as - a last resort. Telling the application how a device fails to follow - a standard is no substitute for implementing the standard correctly. + Device deviations are strongly discouraged and MUST only be used as a + last resort. Telling the application how a device fails to follow a + standard is no substitute for implementing the standard correctly. A + device that deviates from a module is not fully compliant with the + module. However in some cases a particular device may not have the hardware or software ability to support parts of a standard module. When this occurs, the device makes a choice to treat attempts to configure unsupported parts of the module as either an error that is reported back to the unsuspecting application, or ignore those incoming requests. Neither choice is acceptable. Instead, YANG allows devices to document portions of a base module which are not supported or supported but with different syntax, by @@ -4597,21 +4618,22 @@ 7.19.1. The config Statement The "config" statement takes as an argument the string "true" or "false". If "config" is "true", the definition represents configuration. Data nodes representing configuration will be part of the reply to a request, and can be sent in a or request. If "config" is "false", the definition represents state data. Data nodes representing state data will be part of the reply to a , - but not to a request. + but not to a request, and cannot be sent in a + or request. If "config" is not specified, the default is the same as the parent schema node's "config" value. If the parent node is a "case" node, the value is the same as the "case" node's parent "choice" node. If the top node does not specify a "config" statement, the default is "true". If a node has "config" "false", no node underneath it can have "config" set to "true". @@ -4631,43 +4653,64 @@ implemented and/or can be removed from implementations. If no status is specified, the default is "current". If a definition is "current", it MUST NOT reference a "deprecated" or "obsolete" definition within the same module. If a definition is "deprecated", it MUST NOT reference an "obsolete" definition within the same module. + For example, the following is illegal: + + typedef my-type { + status deprecated; + type int32; + } + + leaf my-leaf { + status current; + type my-type; // illegal, since my-type is deprecated + } + 7.19.3. The description Statement The "description" statement takes as an argument a string which contains a high-level textual description of this definition. 7.19.4. The reference Statement The "reference" statement takes as an argument a string which is used to specify a textual cross-reference to an external document, either another module which defines related management information, or a document which provides additional information relevant to this definition. + For example, a typedef for a "uri" data type could look like: + + typedef uri { + type string; + reference + "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; + ... + } + 7.19.5. The when Statement The "when" statement makes its parent data definition statement conditional. The node defined by the parent data definition statement is only valid when the condition specified by the "when" statement is satisfied. The statement's argument is an XPath - expression, which is used to formally specify this condition. If the - XPath expression conceptually evaluates to "true" for a particular - instance, then the node defined by the parent data definition - statement is valid, otherwise it is not. + expression (see Section 6.4), which is used to formally specify this + condition. If the XPath expression conceptually evaluates to "true" + for a particular instance, then the node defined by the parent data + definition statement is valid, otherwise it is not. See Section 8.3.2 for additional information. The XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o If the "when" statement is a child of an "augment" statement, then the context node is the augment's target node in the data tree, if the target node is a data node. Otherwise, the context node is the closest ancestor node to the target node which is also a data @@ -4755,21 +4798,21 @@ container location { if-feature has-gps; leaf longitude { mandatory true; ... } } 8.3. Constraint Enforcement Model - For configuration data, there are three windows when constraints can + For configuration data, there are three windows when constraints MUST be enforced: o during parsing of RPC payloads o during processing of NETCONF operations o during validation Each of these scenarios are considered in the following sections. @@ -4860,30 +4903,31 @@ Additional types may be defined, derived from those built-in types or from other derived types. Derived types may use subtyping to formally restrict the set of possible values. The different built-in types and their derived types allow different kinds of subtyping, namely length and regular expression restrictions of strings (Section 9.4.4, Section 9.4.6) and range restrictions of numeric types (Section 9.2.4). - The lexicographic representation of a value of a certain type is used - in the NETCONF PDUs, and when specifying default values and numerical - ranges in YANG modules. + The lexical representation of a value of a certain type is used in + the NETCONF messages, and when specifying default values and + numerical ranges in YANG modules. 9.1. Canonical representation For most types, there is a single canonical representation of the - type's values. Some types allow multiple lexicographic - representations of the same value, for example the positive integer - "17" can be represented as "+17" or "17". + type's values. Some types allow multiple lexical representations of + the same value, for example the positive integer "17" can be + represented as "+17" or "17". Implementations MUST support all + lexical representations specified in this document. When a NETCONF server sends data, it MUST be in the canonical form. Some types have a lexical representation that depends on the XML context in which they occur. These types do not have a canonical form. 9.2. The Integer Built-in Types The integer built-in types are int8, int16, int32, int64, uint8, @@ -4904,29 +4948,29 @@ uint8 represents integer values between 0 and 255, inclusively. uint16 represents integer values between 0 and 65535, inclusively. uint32 represents integer values between 0 and 4294967295, inclusively. uint64 represents integer values between 0 and 18446744073709551615, inclusively. -9.2.1. Lexicographic Representation +9.2.1. Lexical Representation - An integer value is lexicographically represented as an optional sign - ("+" or "-"), followed by a sequence of decimal digits. If no sign - is specified, "+" is assumed. + An integer value is lexically represented as an optional sign ("+" or + "-"), followed by a sequence of decimal digits. If no sign is + specified, "+" is assumed. For convenience, when specifying a default value for an integer in a - YANG module, an alternative lexicographic representation can be used, - which represents the value in a hexadecimal or octal notation. The + YANG module, an alternative lexical representation can be used, which + represents the value in a hexadecimal or octal notation. The hexadecimal notation consists of an optional sign ("+" or "-"), the characters "0x" followed a number of hexadecimal digits, where letters may be upper- or lowercase. The octal notation consists of an optional sign ("+" or "-"), the character "0" followed a number of octal digits. Note that if a default value in a YANG module has a leading zero ("0"), it is interpreted as an octal number. In the XML instance documents, an integer is always interpreted as a decimal number, and leading zeros are allowed. @@ -5014,26 +5058,26 @@ 9.3. The decimal64 Built-in Type The decimal64 type represents a subset of the real numbers, which can be represented by decimal numerals. The value space of decimal64 is the set of numbers that can be obtained by multiplying a 64 bit signed integer by a negative power of ten, i.e., expressible as "i x 10^-n" where i is an integer64 and n is an integer between 1 and 18, inclusively. -9.3.1. Lexicographic Representation +9.3.1. Lexical Representation - A decimal64 value is lexicographically represented as an optional - sign ("+" or "-"), followed by a sequence of decimal digits, - optionally followed by a period ('.') as a decimal indicator and a - sequence of decimal digits. If no sign is specified, "+" is assumed. + A decimal64 value is lexically represented as an optional sign ("+" + or "-"), followed by a sequence of decimal digits, optionally + followed by a period ('.') as a decimal indicator and a sequence of + decimal digits. If no sign is specified, "+" is assumed. 9.3.2. Canonical Form The canonical form of a positive decimal64 does not include the sign "+". The decimal point is required. Leading and trailing zeros are prohibited, subject to the rule that there MUST be at least one digit before and after the decimal point. The value zero is represented as "0.0". 9.3.3. Restrictions @@ -5087,47 +5131,47 @@ 9.4. The string Built-in Type The string built-in type represents human readable strings in YANG. Legal characters are tab, carriage return, line feed, and the legal characters of Unicode and ISO/IEC 10646 [ISO.10646]: ;; any Unicode character, excluding the surrogate blocks, ;; FFFE, and FFFF. string = *char - char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / + char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD / %x10000-10FFFF -9.4.1. Lexicographic Representation +9.4.1. Lexical Representation - A string value is lexicographically represented as character data in - the XML instance documents. + A string value is lexically represented as character data in the XML + instance documents. 9.4.2. Canonical Form - The canonical form is the same as the lexicographical representation. - No Unicode normalization is performed of string values. + The canonical form is the same as the lexical representation. No + Unicode normalization is performed of string values. 9.4.3. Restrictions A string can be restricted with the "length" (Section 9.4.4) and "pattern" (Section 9.4.6) statements. 9.4.4. The length Statement The "length" statement, which is an optional substatement to the "type" statement, takes as an argument a length expression string. It is used to restrict the built-in type "string", or types derived from "string". - A "length" statement restricts the number of characters in the - string. + A "length" statement restricts the number of Unicode characters in + the string. A length range consists of an explicit value, or a lower bound, two consecutive dots "..", and an upper bound. Multiple values or ranges can be given, separated by "|". Length restricting values MUST NOT be negative. If multiple values or ranges are given, they all MUST be disjoint and MUST be in ascending order. If a length restriction is applied to an already length restricted type, the new restriction MUST be equal or more limiting, that is, raising the lower bounds, reducing the upper bounds, removing explicit length values or ranges, or splitting ranges into multiple ranges with intermediate gaps. A @@ -5211,59 +5255,60 @@ and the following strings do not match: 00ABAB // illegal, too long xx00 // illegal, bad characters 9.5. The boolean Built-in Type The boolean built-in type represents a boolean value. -9.5.1. Lexicographic Representation +9.5.1. Lexical Representation - The lexicographical representation of a boolean value is a string - with a value of "true" or "false". + The lexical representation of a boolean value is a string with a + value of "true" or "false". These values MUST be in lowercase. 9.5.2. Canonical Form - The canonical form is the same as the lexicographical representation. + The canonical form is the same as the lexical representation. 9.5.3. Restrictions A boolean cannot be restricted. 9.6. The enumeration Built-in Type The enumeration built-in type represents values from a set of assigned names. -9.6.1. Lexicographic Representation +9.6.1. Lexical Representation - The lexicographical representation of an enumeration value is the - assigned name string. + The lexical representation of an enumeration value is the assigned + name string. 9.6.2. Canonical Form The canonical form is the assigned name string. 9.6.3. Restrictions An enumeration cannot be restricted. 9.6.4. The enum Statement The "enum" statement, which is a substatement to the "type" statement, MUST be present if the type is "enumeration". It is repeatedly used to specify each assigned name of an enumeration type. It takes as an argument a string which is the assigned name. The string MUST NOT be empty and MUST NOT have any leading or trailing - whitespace characters. The use of control codes SHOULD be avoided. + whitespace characters. The use of Unicode control codes SHOULD be + avoided. The statement is optionally followed by a block of substatements which holds detailed enum information. All assigned names in an enumeration MUST be unique. 9.6.4.1. The enum's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | @@ -5296,40 +5341,40 @@ leaf myenum { type enumeration { enum zero; enum one; enum seven { value 7; } } } - The lexicographic representation of the leaf "myenum" with value - "seven" is: + The lexical representation of the leaf "myenum" with value "seven" + is: seven 9.7. The bits Built-in Type The bits built-in type represents a bit set. That is, a bits value is a set of flags identified by small integer position numbers starting at 0. Each bit number has an assigned name. 9.7.1. Restrictions A bits type cannot be restricted. -9.7.2. Lexicographic Representation +9.7.2. Lexical Representation - The lexicographical representation of the bits type is a space - separated list of the individual bit values that are set. An empty - string thus represents a value where no bits are set. + The lexical representation of the bits type is a space separated list + of the individual bit values that are set. An empty string thus + represents a value where no bits are set. 9.7.3. Canonical Form In the canonical form, the bit values are separated by a single space character and they appear ordered by their position (see Section 9.7.4.2). 9.7.4. The bit Statement The "bit" statement, which is a substatement to the "type" statement, @@ -5352,21 +5397,21 @@ | status | 7.19.2 | 0..1 | | position | 9.7.4.2 | 0..1 | +--------------+---------+-------------+ 9.7.4.2. The position Statement The "position" statement, which is optional, takes as an argument a non-negative integer value which specifies the bit's position within a hypothetical bit field. The position value MUST be in the range 0 to 4294967295, and it MUST be unique within the bits type. The value - is unused by YANG and the NETCONF PDUs, but is carried as a + is unused by YANG and the NETCONF messages, but is carried as a convenience to implementors. If a bit position is not specified, then one will be automatically assigned. If the bit sub-statement is the first one defined, the assigned value is zero (0), otherwise the assigned value is one greater than the current highest bit position. If the current highest bit position value is equal to 4294967295, then a position value MUST be specified for bit sub-statements following the one with the current highest position value. @@ -5383,39 +5428,40 @@ bit auto-sense-speed { position 1; } bit 10-Mb-only { position 2; } } default "auto-sense-speed"; } - The lexicographic representation of this leaf with bit values - disable-nagle and 10-Mb-only set would be: + The lexical representation of this leaf with bit values disable-nagle + and 10-Mb-only set would be: disable-nagle 10-Mb-only 9.8. The binary Built-in Type The binary built-in type represents any binary data, i.e., a sequence of octets. 9.8.1. Restrictions A binary can be restricted with the "length" (Section 9.4.4) statement. The length of a binary value is the number of octets it contains. -9.8.2. Lexicographic Representation +9.8.2. Lexical Representation - Binary values are encoded with the base64 encoding scheme [RFC4648]. + Binary values are encoded with the base64 encoding scheme (see + [RFC4648], section 4). 9.8.3. Canonical Form The canonical form of a binary value follow the rules in [RFC4648]. 9.9. The leafref Built-in Type The leafref type is used to reference a particular leaf instance in the data tree. The "path" substatement (Section 9.9.2) selects a set of leaf instances, and the leafref value space is the set of values @@ -5472,21 +5518,21 @@ o If the context node represents configuration data, the tree is the data in the NETCONF datastore where the context node exists. The XPath root node has all top-level configuration data nodes in all modules as children. o Otherwise the tree is all state data on the device, and the datastore. The XPath root node has all top-level data nodes in all modules as children. -9.9.3. Lexicographic Representation +9.9.3. Lexical Representation A leafref value is encoded the same way as the leaf it references. 9.9.4. Canonical Form The canonical form of a leafref is the same as the canonical form of the leaf it references. 9.9.5. Usage Example @@ -5654,38 +5700,38 @@ statement. If a prefix is present on the identity name, it refers to an identity defined in the module which was imported with that prefix. Otherwise an identity with the matching name MUST be defined in the current module or an included submodule. Valid values for an identityref are any identities derived from the identityref's base identity. On a particular server, the valid values are further restricted to the set of identities defined in the modules supported by the server. -9.10.3. Lexicographic Representation +9.10.3. Lexical Representation An identityref is encoded as the referred identity's Qualified Name as defined in [XML-NAMES]. If the Prefix is not present, the namespace of the identityref is the default namespace in effect on the element which contains the identityref value. When an identityref is given a default value using the "default" statement, the identity name in the default value MAY have a prefix. If a prefix is present on the identity name, it refers to an identity defined in the module which was imported with that prefix. Otherwise an identity with the matching name MUST be defined in the current module or an included submodule. 9.10.4. Canonical Form - Since the lexicographic form depends on the XML context in which the - value occurs, this type does not have a canonical form. + Since the lexical form depends on the XML context in which the value + occurs, this type does not have a canonical form. 9.10.5. Usage Example With the identity definitions in Section 7.16.3, and the following module: module my-crypto { namespace "http://example.com/my-crypto"; prefix mc; @@ -5730,21 +5776,21 @@ The empty built-in type represents a leaf that does not have any value, it conveys information by its presence or absence. An empty type cannot have a default value. 9.11.1. Restrictions An empty type cannot be restricted. -9.11.2. Lexicographic Representation +9.11.2. Lexical Representation Not applicable. 9.11.3. Canonical Form Not applicable. 9.11.4. Usage Example The following leaf @@ -5786,24 +5832,24 @@ type enumeration { enum "unbounded"; } } 9.12.1. Restrictions A union cannot be restricted. However, each member type can be restricted, based on the rules defined in Section 9. -9.12.2. Lexicographic Representation +9.12.2. Lexical Representation - The lexicographical representation of an union is a value that - corresponds to the representation of any one of the member types. + The lexical representation of an union is a value that corresponds to + the representation of any one of the member types. 9.12.3. Canonical Form The canonical form of a union value is the same as the canonical form of the member type of the value. 9.13. The instance-identifier Built-in Type The instance-identifier built-in type is used to uniquely identify a particular instance node in the data tree. @@ -5856,36 +5902,35 @@ "instance-identifier". It takes as an argument the string "true" or "false". If this statement is not present, it defaults to "true". If "require-instance" is "true", it means that the instance being referred MUST exist for the data to be valid. This constraint is enforced according to the rules in Section 8. If "require-instance" is "false", it means that the instance being referred MAY exist in valid data. -9.13.3. Lexicographic Representation +9.13.3. Lexical Representation - An instance-identifier value is lexicographically represented as a - string. All node names in an instance-identifier value MUST be - qualified with explicit namespace prefixes and these prefixes MUST be - declared in the XML namespace scope in the instance-identifier's XML - element. + An instance-identifier value is lexically represented as a string. + All node names in an instance-identifier value MUST be qualified with + explicit namespace prefixes and these prefixes MUST be declared in + the XML namespace scope in the instance-identifier's XML element. Any prefixes used in the encoding are local to each instance encoding. This means that the same instance-identifier may be encoded differently by different implementations. 9.13.4. Canonical Form - Since the lexicographic form depends on the XML context in which the - value occurs, this type does not have a canonical form. + Since the lexical form depends on the XML context in which the value + occurs, this type does not have a canonical form. 9.13.5. Usage Example The following are examples of instance identifiers: /* instance-identifier for a container */ /ex:system/ex:services/ex:ssh /* instance-identifier for a leaf */ /ex:system/ex:services/ex:ssh/ex:port @@ -5917,21 +5962,21 @@ MUST be included in front of the existing revision statements. If there are no existing revision statements, then one MUST be added to identify the new revision. Furthermore, any necessary changes MUST be applied to any meta data statements, including the "organization" and "contact" statements (Section 7.1.7, Section 7.1.8). Note that definitions contained in a module are available to be imported by any other module, and are referenced in "import" statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, - since all XML elements are encoded in the namespace. + since all XML elements are qualified by the namespace. Obsolete definitions MUST NOT be removed from modules since their identifiers may still be referenced by other modules. A definition may be revised in any of the following ways: o An "enumeration" type may have new enums added, provided the old enums's values do not change. o A "bits" type may have new bits added, provided the old bit @@ -5946,21 +5991,21 @@ o A "units" statement may be added. o A "reference" statement may be added or updated. o A "must" statement may be removed or its constraint relaxed. o A "mandatory" statement may be removed or changed from "true" to "false". o A "min-elements" statement may be removed, or changed to require - less elements. + fewer elements. o A "max-elements" statement may be removed, or changed to allow more elements. o A "description" statement may be added or clarified without changing the semantics of the definition. o New typedefs, groupings, rpc, notifications, extensions, features, and identities may be added. @@ -6008,26 +6053,25 @@ substatements, those data definition substatements MUST NOT be reordered. 11. YIN A YANG module can be translated into an alternative XML-based syntax called YIN. The translated module is called a YIN module. This section describes symmetric mapping rules between the two formats. The YANG and YIN formats contain equivalent information using - different notations. The purpose of the YIN notation is to allow the - user to translate YANG into YIN, use the rich set of XML based tools - on the YIN format to transform, or filter the model information. - Tools like XSLT or XML validators can be utilized. After this the - model can be transformed back to the YANG format if needed, which - provides a more concise and readable format. + different notations. The YIN notation enables developers to + represent YANG data models in XML and therefore use the rich set of + XML-based tools for data filtering and validation, automated + generation of code and documentation, and other tasks. Tools like + XSLT or XML validators can be utilized. The mapping between YANG and YIN does not modify the information content of the model. Comments and whitespace are not preserved. 11.1. Formal YIN Definition There is a one-to-one correspondence between YANG keywords and YIN elements. The local name of a YIN element is identical to the corresponding YANG keyword. This means in particular that the document element (root) of a YIN document is always or @@ -6038,36 +6082,36 @@ "urn:ietf:params:xml:ns:yang:yin:1". YIN elements corresponding to extension keywords belong to the namespace of the YANG module where the extension keyword is declared via the "extension" statement. The names of all YIN elements MUST be properly qualified with their namespaces specified above using the standard mechanisms of [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. - The argument of a YANG statement is encoded in YIN either as an XML - attribute or a subelement of the keyword element. Table 1 defines - the encoding for the set of YANG keywords. For extensions, the - argument encoding is specified within the "extension" statement (see - Section 7.17). The following rules hold for arguments: + The argument of a YANG statement is represented in YIN either as an + XML attribute or a subelement of the keyword element. Table 1 + defines the mapping for the set of YANG keywords. For extensions, + the argument mapping is specified within the "extension" statement + (see Section 7.17). The following rules hold for arguments: - o If the argument is encoded as an attribute, this attribute has no - namespace. + o If the argument is represented as an attribute, this attribute has + no namespace. - o If the argument is encoded as an element, it is placed to the same - namespace as its parent keyword element. + o If the argument is represented as an element, it is qualified by + the same namespace as its parent keyword element. - o If the argument is encoded as an element, it MUST be the first + o If the argument is represented as an element, it MUST be the first child of the keyword element. - Substatements of a YANG statement are encoded as (additional) + Substatements of a YANG statement are represented as (additional) children of the keyword element and their relative order MUST be the same as the order of substatements in YANG. Comments in YANG MAY be mapped to XML comments. Mapping of arguments of the YANG statements. +------------------+---------------+-------------+ | keyword | argument name | yin-element | +------------------+---------------+-------------+ @@ -7034,21 +7078,21 @@ path-key-expr = current-function-invocation *WSP "/" *WSP rel-path-keyexpr rel-path-keyexpr = 1*(".." *WSP "/" *WSP) *(node-identifier *WSP "/" *WSP) node-identifier ;;; Keywords, using abnfgen's syntax for case-sensitive strings - ;; statment keywords + ;; statement keywords anyxml-keyword = 'anyxml' argument-keyword = 'argument' augment-keyword = 'augment' base-keyword = 'base' belongs-to-keyword = 'belongs-to' bit-keyword = 'bit' case-keyword = 'case' choice-keyword = 'choice' config-keyword = 'config' contact-keyword = 'contact' @@ -7172,21 +7216,21 @@ line-break = CRLF / LF non-zero-digit = %x31-39 decimal-value = integer-value ("." zero-integer-value) SQUOTE = %x27 ; ' (Single Quote) ;; - ;; RFC 4234 core rules. + ;; RFC 5234 core rules. ;; ALPHA = %x41-5A / %x61-7A ; A-Z / a-z CR = %x0D ; carriage return CRLF = CR LF ; Internet standard newline @@ -7223,179 +7267,283 @@ A number of NETCONF error responses are defined for error cases related to the data-model handling. If the relevant YANG statement has an "error-app-tag" substatement, that overrides the default value specified below. 13.1. Error Message for Data that Violates a unique Statement If a NETCONF operation would result in configuration data where a unique constraint is invalidated, the following error is returned: - Tag: operation-failed - Error-app-tag: data-not-unique - Error-info: : Contains an instance identifier which + error-tag: operation-failed + error-app-tag: data-not-unique + error-info: : Contains an instance identifier which points to a leaf which invalidates the unique constraint. This element is present once for each non-unique leaf. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). 13.2. Error Message for Data that Violates a max-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too many entries the following error is returned: - Tag: operation-failed - Error-app-tag: too-many-elements + error-tag: operation-failed + error-app-tag: too-many-elements This error is returned once, with the error-path identifying the list node, even if there are more than one extra child present. 13.3. Error Message for Data that Violates a min-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too few entries the following error is returned: - Tag: operation-failed - Error-app-tag: too-few-elements + error-tag: operation-failed + error-app-tag: too-few-elements This error is returned once, with the error-path identifying the list node, even if there are more than one child missing. 13.4. Error Message for Data that Violates a must Statement If a NETCONF operation would result in configuration data where the restrictions imposed by a "must" statement is violated the following error is returned, unless a specific "error-app-tag" substatement is present for the "must" statement. - Tag: operation-failed - Error-app-tag: must-violation + error-tag: operation-failed + error-app-tag: must-violation 13.5. Error Message for Data that Violates a require-instance Statement If a NETCONF operation would result in configuration data where a leaf of type "instance-identifier" marked with require-instance "true" refers to a non-existing instance, the following error is returned: - Tag: data-missing - Error-app-tag: instance-required - Error-path: Path to the instance-identifier leaf. + error-tag: data-missing + error-app-tag: instance-required + error-path: Path to the instance-identifier leaf. 13.6. Error Message for Data that does not Match a leafref Type If a NETCONF operation would result in configuration data where a leaf of type "leafref" refers to a non-existing instance, the following error is returned: - Tag: data-missing - Error-app-tag: instance-required - Error-path: Path to the leafref leaf. + error-tag: data-missing + error-app-tag: instance-required + error-path: Path to the leafref leaf. 13.7. Error Message for Data that Violates a mandatory choice Statement If a NETCONF operation would result in configuration data where no nodes exists in a mandatory choice, the following error is returned: - Tag: data-missing - Error-app-tag: missing-choice - Error-path: Path to the element with the missing choice. - Error-info: : Contains the name of the missing + error-tag: data-missing + error-app-tag: missing-choice + error-path: Path to the element with the missing choice. + error-info: : Contains the name of the missing mandatory choice. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). 13.8. Error Message for the "insert" Operation 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 to a non-existing instance, the following error is returned: - Tag: bad-attribute - Error-app-tag: missing-instance + error-tag: bad-attribute + error-app-tag: missing-instance 14. IANA Considerations This document defines a registry for YANG module and submodule names. The name of the registry is "YANG Module Names". The registry shall record for each entry: o the name of the module or submodule o for modules, the assigned XML namespace o for modules, the prefix of the module o for submodules, the name of the module it belongs to - o a reference to the (sub)module's documentation (the RFC number) + o a reference to the (sub)module's documentation (e.g., the RFC + number) + + There are no initial assignments. For allocation, RFC publication is required as per RFC 5226 - [RFC5226]. All registered YANG module names must comply with the - rules for identifiers stated in Section 6.2. There are no initial - assignments. + [RFC5226]. All registered YANG module names MUST comply with the + rules for identifiers stated in Section 6.2, and MUST have a module + name prefix. The module name prefix 'ietf-' is reserved for IETF stream documents [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF - stream documents. Modules published in other RFC streams must have a - similar suitable prefix. The prefix 'iana-' is reserved for modules - maintained by IANA. + stream documents. Modules published in other RFC streams MUST have a + similar suitable prefix. All module and submodule names in the registry MUST be unique. All XML namespaces in the registry MUST be unique. This document registers two URIs for the YANG and YIN XML namespaces in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registration is requested. URI: urn:ietf:params:xml:ns:yang:yin:1 URI: urn:ietf:params:xml:ns:yang:1 Registrant Contact: The IESG. XML: N/A, the requested URIs are XML namespaces. + This document registers two new media types as defined in the + following sections. + +14.1. Media type application/yang + + MIME media type name: application + + MIME subtype name: yang + + Mandatory parameters: none + + Optional parameters: none + + Encoding considerations: 8bit + + Security considerations: See section 15 in RFC XXXX + + Interoperability considerations: None + + Published specification: RFC XXXX (currently draft-ietf-netmod-yang) + + Applications that use this media type: + + YANG module validators, web servers used for downloading YANG + modules, email clients etc. + + Additional information: + + Magic Number: None + + File Extension: .yang + + Macintosh file type code: 'TEXT' + + Personal and email address for further information: + Martin Bjorklund + + Intended usage: COMMON + + Author: + This specification is a work item of the IETF NETMOD working group, + with mailing list address . + + Change controller: + The IESG + +14.2. Media type application/yin+xml + MIME media type name: application + + MIME subtype name: yin+xml + + Mandatory parameters: none + + Optional parameters: + + "charset": This parameter has identical semantics to the charset + parameter of the "application/xml" media type as specified in + [RFC3023]. + + Encoding considerations: + + Identical to those of "application/xml" as + described in [RFC3023], Section 3.2. + + Security considerations: See section 15 in RFC XXXX + + Interoperability considerations: None + + Published specification: RFC XXXX (currently draft-ietf-netmod-yang) + + Applications that use this media type: + + YANG module validators, web servers used for downloading YANG + modules, email clients etc. + + Additional information: + + Magic Number: As specified for "application/xml" in [RFC3023], + Section 3.2. + + File Extension: .yin + + Macintosh file type code: 'TEXT' + + Personal and email address for further information: + Martin Bjorklund + + Intended usage: COMMON + + Author: + This specification is a work item of the IETF NETMOD working group, + with mailing list address . + + Change controller: + The IESG + 15. Security Considerations This document defines a language with which to write and read descriptions of management information. The language itself has no security impact on the Internet. The same considerations are relevant as for the base NETCONF protocol - (See [RFC4741], section 9). + (see [RFC4741], section 9). Data modeled in YANG might contain sensitive information. RPCs or notifications defined in YANG might transfer sensitive information. Security issues are related to the usage of data modeled in YANG. Such issues shall be dealt with in documents describing the data models and documents about the interfaces used to manipulate the data e.g., the NETCONF documents. Data modeled in YANG is dependent upon: o the security of the transmission infrastructure used to send sensitive information o the security of applications which store or release such sensitive information. o adequate authentication and access control mechanisms to restrict the usage of sensitive data. + YANG parsers need to be robust with respect to malformed documents. + Reading malformed documents from unknown or untrusted sources could + result in an attacker gaining privileges of the user running the YANG + parser. In an extreme situation, the entire machine could be + compromised. + 16. Contributors The following people all contributed significantly to the initial YANG draft: - Andy Bierman (Netconf Central) - Balazs Lengyel (Ericsson) - David Partain (Ericsson) - Juergen Schoenwaelder (Jacobs University Bremen) - Phil Shafer (Juniper Networks) @@ -7407,23 +7555,22 @@ Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert Wijnen. 18. References 18.1. Normative References [ISO.10646] International Organization for Standardization, - "Information Technology - Universal Multiple-octet coded - Character Set (UCS) - Part 1: Architecture and Basic - Multilingual Plane", ISO Standard 10646-1, May 1993. + "Information Technology - Universal Multiple-Octet Coded + Character Set (UCS)", ISO Standard 10646:2003, 2003. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.