--- 1/draft-ietf-netmod-yang-07.txt 2009-10-22 16:12:12.000000000 +0200 +++ 2/draft-ietf-netmod-yang-08.txt 2009-10-22 16:12:12.000000000 +0200 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track July 13, 2009 -Expires: January 14, 2010 +Intended status: Standards Track October 22, 2009 +Expires: April 25, 2010 YANG - A data modeling language for NETCONF - draft-ietf-netmod-yang-07 + draft-ietf-netmod-yang-08 Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. @@ -21,21 +21,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 January 14, 2010. + This Internet-Draft will expire on April 25, 2010. Copyright Notice Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights @@ -70,263 +70,263 @@ 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31 - 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 31 + 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 32 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 5.6.4. Announcing Conformance Information in the Message . . . . . . . . . . . . . . . . . . . . . . . 33 - 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 35 - 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 35 - 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 35 - 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 35 - 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 35 - 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 37 - 6.2.1. Identifiers and their namespaces . . . . . . . . . . 37 - 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 38 - 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 38 - 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 38 - 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 39 - 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 39 - 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 41 - 7.1. The module Statement . . . . . . . . . . . . . . . . . . 41 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 42 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 43 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 43 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 44 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 44 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 45 - 7.1.7. The organization Statement . . . . . . . . . . . . . 46 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 46 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 46 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 47 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 47 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 48 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 49 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 50 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 50 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 51 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 51 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 51 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 51 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 52 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 52 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 52 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 52 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 53 - 7.5.2. The container's Substatements . . . . . . . . . . . . 54 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 54 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 56 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 57 - 7.5.6. The container's Child Node Statements . . . . . . . . 57 - 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 57 - 7.5.8. NETCONF Operations . . . . . . . . . . 57 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 58 - 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 - 7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 60 - 7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 60 - 7.6.3. The leaf's default Statement . . . . . . . . . . . . 60 - 7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 60 - 7.6.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 - 7.6.6. NETCONF Operations . . . . . . . . . . 61 - 7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 62 - - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 62 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 63 - 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 64 - 7.7.3. The min-elements Statement . . . . . . . . . . . . . 64 - 7.7.4. The max-elements Statement . . . . . . . . . . . . . 64 - 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 65 - 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 65 - 7.7.7. NETCONF operations . . . . . . . . . . 65 - 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 68 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 69 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 69 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 70 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 71 - 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 71 - 7.8.6. NETCONF operations . . . . . . . . . . 72 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 72 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 76 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 76 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 76 - 7.9.3. The choice's default Statement . . . . . . . . . . . 78 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 79 - 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 80 - 7.9.6. NETCONF operations . . . . . . . . . . 80 - 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 80 - 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 81 - 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 82 - 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 - 7.10.3. NETCONF operations . . . . . . . . . . 82 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 83 - 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 83 - 7.11.1. The grouping's Substatements . . . . . . . . . . . . 84 - 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 84 - 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 84 - 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 85 - 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 85 - 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 86 - 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 86 - 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 87 - 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 88 - 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 88 - 7.13.3. The output Statement . . . . . . . . . . . . . . . . 89 - 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 90 - 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 90 - 7.14. The notification Statement . . . . . . . . . . . . . . . 91 - 7.14.1. The notification's Substatements . . . . . . . . . . 92 - 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 92 - 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 92 - - 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 93 - 7.15.1. The augment's Substatements . . . . . . . . . . . . . 94 - 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 94 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 94 - 7.16. The identity Statement . . . . . . . . . . . . . . . . . 96 - 7.16.1. The identity's Substatements . . . . . . . . . . . . 97 - 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 97 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 98 - 7.17. The extension Statement . . . . . . . . . . . . . . . . . 98 - 7.17.1. The extension's Substatements . . . . . . . . . . . . 99 - 7.17.2. The argument Statement . . . . . . . . . . . . . . . 99 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 100 - 7.18. Conformance-related Statements . . . . . . . . . . . . . 100 - 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 100 - 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 102 - 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 102 - 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 105 - 7.19.1. The config Statement . . . . . . . . . . . . . . . . 105 - 7.19.2. The status Statement . . . . . . . . . . . . . . . . 105 - 7.19.3. The description Statement . . . . . . . . . . . . . . 106 - 7.19.4. The reference Statement . . . . . . . . . . . . . . . 106 - 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 106 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 108 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 108 - 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 108 - 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 108 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 109 - 8.3.2. NETCONF Processing . . . . . . . . . . 109 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 110 - 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 111 - 9.1. Canonical representation . . . . . . . . . . . . . . . . 111 - 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 111 - 9.2.1. Lexicographic Representation . . . . . . . . . . . . 112 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 113 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 113 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 113 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 114 - 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 114 - 9.3.1. Lexicographic Representation . . . . . . . . . . . . 114 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 114 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 114 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 115 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 115 - 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 115 - 9.4.1. Lexicographic Representation . . . . . . . . . . . . 116 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 116 - 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 - 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 117 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 118 - 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 118 - 9.5.1. Lexicographic Representation . . . . . . . . . . . . 118 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 - 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 119 - 9.6.1. Lexicographic Representation . . . . . . . . . . . . 119 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 119 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 - 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 120 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120 - 9.7.2. Lexicographic Representation . . . . . . . . . . . . 121 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 121 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 121 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 122 - 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 122 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 122 - 9.8.2. Lexicographic Representation . . . . . . . . . . . . 122 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 122 - 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 123 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 123 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 123 - 9.9.3. Lexicographic Representation . . . . . . . . . . . . 124 - 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 124 - 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124 - 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 128 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 128 - 9.10.2. The identityref's base Statement . . . . . . . . . . 128 - 9.10.3. Lexicographic Representation . . . . . . . . . . . . 128 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 128 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 - 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 129 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 130 - 9.11.2. Lexicographic Representation . . . . . . . . . . . . 130 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 130 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 130 - 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 130 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 - 9.12.2. Lexicographic Representation . . . . . . . . . . . . 131 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 131 - 9.13. The instance-identifier Built-in Type . . . . . . . . . . 131 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 - 9.13.2. The require-instance Statement . . . . . . . . . . . 132 - 9.13.3. Lexicographic Representation . . . . . . . . . . . . 132 - 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 133 - 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 - 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 134 - 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 - 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 137 - 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 139 - 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 141 - 13. Error Responses for YANG Related Errors . . . . . . . . . . . 162 - 13.1. Error Message for Data that Violates a unique Statement . 162 + 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36 + 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36 + 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 + 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36 + 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38 + 6.2.1. Identifiers and their namespaces . . . . . . . . . . 38 + 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39 + 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39 + 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 40 + 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 40 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 42 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 42 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 43 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 44 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 44 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 45 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 45 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 46 + 7.1.7. The organization Statement . . . . . . . . . . . . . 47 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 47 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 47 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 48 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 48 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 49 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 50 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 51 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 51 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 52 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 52 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 52 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 52 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 53 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 53 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 53 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 53 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 54 + 7.5.2. The container's Substatements . . . . . . . . . . . . 55 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 55 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 57 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 58 + 7.5.6. The container's Child Node Statements . . . . . . . . 58 + 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 58 + 7.5.8. NETCONF Operations . . . . . . . . . . 58 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 59 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 60 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 60 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 61 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 61 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 61 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 61 + 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 62 + 7.6.7. NETCONF Operations . . . . . . . . . . 62 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 63 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 63 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 64 + 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 65 + 7.7.3. The min-elements Statement . . . . . . . . . . . . . 65 + 7.7.4. The max-elements Statement . . . . . . . . . . . . . 65 + 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 66 + 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 66 + 7.7.7. NETCONF operations . . . . . . . . . . 66 + 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 67 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 69 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 70 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 70 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 71 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 72 + 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 72 + 7.8.6. NETCONF operations . . . . . . . . . . 73 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 73 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 77 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 77 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 77 + 7.9.3. The choice's default Statement . . . . . . . . . . . 79 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 80 + 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 81 + 7.9.6. NETCONF operations . . . . . . . . . . 81 + 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 81 + 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 82 + 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 83 + 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 83 + 7.10.3. NETCONF operations . . . . . . . . . . 83 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 84 + 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 84 + 7.11.1. The grouping's Substatements . . . . . . . . . . . . 85 + 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 85 + 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 85 + 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 86 + 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 86 + 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 87 + 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 87 + 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 88 + 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 89 + 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 89 + 7.13.3. The output Statement . . . . . . . . . . . . . . . . 90 + 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 91 + 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 91 + 7.14. The notification Statement . . . . . . . . . . . . . . . 92 + 7.14.1. The notification's Substatements . . . . . . . . . . 93 + 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 + 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 93 + 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 94 + 7.15.1. The augment's Substatements . . . . . . . . . . . . . 95 + 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 95 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 + 7.16. The identity Statement . . . . . . . . . . . . . . . . . 97 + 7.16.1. The identity's Substatements . . . . . . . . . . . . 98 + 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 98 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 99 + 7.17. The extension Statement . . . . . . . . . . . . . . . . . 99 + 7.17.1. The extension's Substatements . . . . . . . . . . . . 100 + 7.17.2. The argument Statement . . . . . . . . . . . . . . . 100 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 + 7.18. Conformance-related Statements . . . . . . . . . . . . . 101 + 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 101 + 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 103 + 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 103 + 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 106 + 7.19.1. The config Statement . . . . . . . . . . . . . . . . 106 + 7.19.2. The status Statement . . . . . . . . . . . . . . . . 106 + 7.19.3. The description Statement . . . . . . . . . . . . . . 107 + 7.19.4. The reference Statement . . . . . . . . . . . . . . . 107 + 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 107 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 109 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 109 + 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 109 + 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 109 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 110 + 8.3.2. NETCONF Processing . . . . . . . . . . 110 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 111 + 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 112 + 9.1. Canonical representation . . . . . . . . . . . . . . . . 112 + 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 112 + 9.2.1. Lexicographic Representation . . . . . . . . . . . . 113 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 114 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 114 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 114 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 115 + 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 115 + 9.3.1. Lexicographic Representation . . . . . . . . . . . . 115 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 115 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 116 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 116 + 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 117 + 9.4.1. Lexicographic Representation . . . . . . . . . . . . 117 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 117 + 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 118 + 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 118 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 119 + 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 119 + 9.5.1. Lexicographic Representation . . . . . . . . . . . . 119 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 119 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 + 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 120 + 9.6.1. Lexicographic Representation . . . . . . . . . . . . 120 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 120 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 + 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 122 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 122 + 9.7.2. Lexicographic Representation . . . . . . . . . . . . 122 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 122 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 122 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 + 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 124 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124 + 9.8.2. Lexicographic Representation . . . . . . . . . . . . 124 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 124 + 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 124 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 125 + 9.9.3. Lexicographic Representation . . . . . . . . . . . . 126 + 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 126 + 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 + 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 129 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 129 + 9.10.2. The identityref's base Statement . . . . . . . . . . 129 + 9.10.3. Lexicographic Representation . . . . . . . . . . . . 130 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 130 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130 + 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 131 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 + 9.11.2. Lexicographic Representation . . . . . . . . . . . . 131 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 131 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 131 + 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 132 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 + 9.12.2. Lexicographic Representation . . . . . . . . . . . . 132 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 + 9.13. The instance-identifier Built-in Type . . . . . . . . . . 133 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 133 + 9.13.2. The require-instance Statement . . . . . . . . . . . 134 + 9.13.3. Lexicographic Representation . . . . . . . . . . . . 134 + 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 134 + 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 136 + 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 + 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 139 + 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 141 + 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 143 + 13. Error Responses for YANG Related Errors . . . . . . . . . . . 165 + 13.1. Error Message for Data that Violates a unique Statement . 165 13.2. Error Message for Data that Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . . 162 + Statement . . . . . . . . . . . . . . . . . . . . . . . . 165 13.3. Error Message for Data that Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . . 162 - 13.4. Error Message for Data that Violates a must Statement . . 163 + Statement . . . . . . . . . . . . . . . . . . . . . . . . 165 + 13.4. Error Message for Data that Violates a must Statement . . 166 13.5. Error Message for Data that Violates a - require-instance Statement . . . . . . . . . . . . . . . 163 + require-instance Statement . . . . . . . . . . . . . . . 166 13.6. Error Message for Data that does not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 163 + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 166 13.7. Error Message for Data that Violates a mandatory - choice Statement . . . . . . . . . . . . . . . . . . . . 163 - 13.8. Error Message for the "insert" Operation . . . . . . . . 164 - 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 165 - 15. Security Considerations . . . . . . . . . . . . . . . . . . . 166 - 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 167 - 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 168 - 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 169 - 18.1. Normative References . . . . . . . . . . . . . . . . . . 169 - 18.2. Non-Normative References . . . . . . . . . . . . . . . . 170 - Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 171 - A.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 172 - A.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 172 - A.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 173 - A.8. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 174 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 175 + choice Statement . . . . . . . . . . . . . . . . . . . . 166 + 13.8. Error Message for the "insert" Operation . . . . . . . . 167 + 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 168 + 15. Security Considerations . . . . . . . . . . . . . . . . . . . 169 + 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 170 + 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 171 + 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 172 + 18.1. Normative References . . . . . . . . . . . . . . . . . . 172 + 18.2. Non-Normative References . . . . . . . . . . . . . . . . 173 + Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 174 + A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 174 + A.2. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 174 + A.3. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 174 + A.4. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 174 + A.5. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 175 + A.6. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 175 + A.7. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 176 + A.8. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 176 + A.9. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 177 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 178 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). @@ -389,21 +389,23 @@ o extension: An extension attaches non-YANG semantics to nodes. The extension statement defines new statements to express these semantics. o feature: A mechanism for marking a portion of the model as optional. Definitions can be tagged with a feature name and are only valid on devices which support that feature. o grouping: A reusable set of nodes, which may be used locally in the module, in modules which include it, and by other modules - which import from it. + which import from it. The grouping statement is not a data + definition statement and, as such, does not define any nodes in + the schema tree. o identifier: Used to identify different kinds of YANG items by name. o instance identifier: A mechanism for identifying a particular node in a data tree. o interior node: Nodes within a hierarchy that are not leaf nodes. o leaf: A node in the data tree with a value but no child nodes. @@ -436,20 +438,23 @@ o schema tree: The definition hierarchy specified within a module. o state data: The additional data on a system that is not configuration data such as read-only status information and collected statistics [RFC4741]. o submodule: A partial module definition which contributes derived types, groupings, data nodes, RPCs, and notifications to a module. A YANG module can be constructed from a number of submodules. + o top-level data node: A data node where there is no other data node + between it and a module or submodule statement. + o uses: The "uses" statement is used to instantiate the set of nodes defined in a grouping statement. The instantiated nodes may be refined and augmented to tailor them to any specific needs. 3.1. Mandatory nodes A mandatory node is one of: o A leaf, choice, or anyxml node with a "mandatory" statement with the value "true". @@ -1077,21 +1082,21 @@ or augment an existing data model with additional nodes. Submodules are partial modules that contribute definitions to a module. A module may include any number of submodules, but each submodule may belong to only one module. The names of all standard modules and submodules MUST be unique. Developers of enterprise modules are RECOMMENDED to choose names for their modules that will have a low probability of colliding with standard or other enterprise modules, e.g., by using the enterprise - or organization name as a prefix. + or organization name as a prefix for the module name. A module uses the "include" statement to include its submodules, and the "import" statement to reference external modules. Similarly, a submodule uses the "import" statement to reference other modules, and uses the "include" statement to reference other submodules within its module. A module or submodule MUST NOT include submodules from other modules, and a submodule MUST NOT import its own module. The import and include statements are used to make definitions available to other modules and submodules: @@ -1264,34 +1269,36 @@ where they are used, rather than placing them at the top level of the hierarchy. The close proximity increases readability. Scoping also allows types to be defined without concern for naming conflicts between types in different submodules. Type names can be specified without adding leading strings designed to prevent name collisions within large modules. Finally, scoping allows the module author to keep types and groupings private to their module or submodule, preventing their reuse. Since - only top-level types and groupings can be used outside the module or - submodule, the developer has more control over what pieces of their - module are presented to the outside world, supporting the need to - hide internal information and maintaining a boundary between what is - shared with the outside world and what is kept private. + only top-level types and groupings (i.e., those appearing as + substatements to a module or submodule statement) can be used outside + the module or submodule, the developer has more control over what + pieces of their module are presented to the outside world, supporting + the need to hide internal information and maintaining a boundary + between what is shared with the outside world and what is kept + private. Scoped definitions MUST NOT shadow definitions at a higher scope. A - type or group cannot be defined if a higher level in the schema + type or grouping cannot be defined if a higher level in the schema hierarchy has a definition with a matching identifier. - When a YANG implementation resolves a reference to an unprefixed type - or grouping, or one which uses the prefix of the local module, it - searches up the levels of hierarchy in the schema tree, starting at - the current level, for the definition of the type or grouping. + A reference to an unprefixed type or grouping, or one which uses the + prefix of the current module, is resolved by locating the closest + matching "typedef" or "grouping" statement among the immediate + substatements of each ancestor statement. 5.6. Conformance Conformance is a measure of how accurately a device follows the model. Generally speaking, devices are responsible for implementing the model faithfully, allowing applications to treat devices which implement the model identically. Deviations from the model can reduce the utility of the model and increase fragility of applications that use it. @@ -1365,21 +1372,21 @@ that could not succeed. Device deviations are declared using the "deviation" statement, which takes as its argument a string which identifies a node in the schema tree. The contents of the statement details the manner in which the device implementation deviates from the contract as defined in the module. 5.6.4. Announcing Conformance Information in the Message - The namespace URI is advertised as a capability in the NETCONF + The namespace URI MUST be advertised as a capability in the NETCONF message to indicate support for the YANG module by a NETCONF server. The capability URI advertised MUST be on the form: capability-string = namespace-uri [ parameter-list ] parameter-list = "?" parameter *( "&" parameter ) parameter = revision-parameter / module-parameter / feature-parameter / deviation-parameter revision-parameter = "revision=" revision-date @@ -1393,83 +1400,81 @@ Section 7.1), "namespace-uri" is the namespace for the module as it appears in the "namespace" statement, "feature" is the name of an optional feature implemented by the device (see Section 7.18.1), and "deviation" is the name of a module defining device deviations (see Section 7.18.3). In the parameter list, each named parameter MUST occur at most once. 5.6.4.1. Modules - Devices indicate the names of supported modules via the + Servers indicate the names of supported modules via the message. Module namespaces are encoded as the base URI in the capability string, and the module name is encoded as the "module" parameter to the base URI. - Modules that do not contribute any data definitions, rpcs, - notifications, or deviations to the device MAY be advertised in the - message. + A server MUST advertise all revisions of all modules it implements. For example, this message advertises one module "syslog". - + http://example.com/syslog?module=syslog&revision=2008-04-01 5.6.4.2. Features - Devices indicate the names of supported features via the + Servers indicate the names of supported features via the message. In hello messages, the features are encoded in the "features" parameter within the URI. The value of this parameter is a comma-separated list of feature names which the device supports for the specific module. For example, this message advertises one module, informing the client that it supports the "local-storage" feature of module "syslog". - + http://example.com/syslog?module=syslog&features=local-storage 5.6.4.3. Deviations Device deviations are announced via the "deviations" parameter. The value of the deviations parameter is a comma-separated list of modules containing deviations from the capability's module. For example, this message advertises two modules, informing the client that it deviates from module "syslog" according to the deviations listed in the module "my-devs". - + http://example.com/syslog?module=syslog&deviations=my-devs http://example.com/my-deviations?module=my-devs 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 are written in the UTF-8 [RFC3629] character set. + YANG modules use the UTF-8 [RFC3629] character encoding. 6.1. Lexicographical 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. @@ -1488,23 +1493,24 @@ are case sensitive. See Section 6.2 for a formal definition of identifiers. 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 is used to indent the text according to the + 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 at most the column of the double quote character. + string, up to the column of the double quote character, or to the + first non-whitespace character, whichever occurs first. 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 @@ -1580,34 +1586,34 @@ o All identity names defined in a module and its submodules share the same identity identifier namespace. o All derived type names defined within a parent node or at the top- level of the module or its submodules share the same type identifier namespace. This namespace is scoped to all descendant nodes of the parent node or module. This means that any descendent node may use that typedef, and it MUST NOT define a typedef with the same name. - o All groupings defined within a parent node or at the top-level of - the module or its submodules share the same type identifier - namespace. This namespace is scoped to all descendant nodes of - the parent node or module. This means that any descendent node - may use that grouping, and it MUST NOT define a grouping with the - same name. + o All grouping names defined within a parent node or at the top- + level of the module or its submodules share the same grouping + identifier namespace. This namespace is scoped to all descendant + nodes of the parent node or module. This means that any + descendent node may use that grouping, and it MUST NOT define a + grouping with the same name. o All leafs, leaf-lists, lists, containers, choices, rpcs, - notifications, and anyxmls defined within a parent node or at the - top-level of the module or its submodules share the same - identifier namespace. This namespace is scoped to the parent node - or module, unless the parent node is a case node. In that case, - the namespace is scoped to the parent node of the case node's - parent choice node. + notifications, and anyxmls defined (directly or through a uses + statement) within a parent node or at the top-level of the module + or its submodules share the same identifier namespace. This + namespace is scoped to the parent node or module, unless the + parent node is a case node. In that case, the namespace is scoped + to the closest ancestor node which is not a case or choice node. o All cases within a choice share the same case identifier namespace. This namespace is scoped to the parent choice node. Forward references are allowed in YANG. 6.3. Statements A YANG module contains a sequence of statements. Each statement starts with a keyword, followed by zero or one argument, followed @@ -1626,67 +1632,68 @@ imported extension is used, the extension's keyword MUST be qualified using the prefix with which the extension's module was imported. If an extension is used in the module where it is defined, the extension's keyword MUST be qualified with the module's prefix. Since submodules cannot include the parent module, any extensions in the module which need to be exposed to submodules MUST be defined in a submodule. Submodules can then include this submodule to find the definition of the extension. + If a YANG compiler does not support a particular extension, which + appears in a YANG module as an unknown-statement (see Section 12), + the entire unknown statement MAY be ignored by the compiler. + 6.4. XPath Evaluations YANG relies on XPath 1.0 [XPATH] as a notation for specifying many inter-node references and dependencies. NETCONF clients and servers are not required to implement an XPath interpreter, but MUST ensure that the requirements encoded in the data model are enforced. The manner of enforcement is an implementation decision. The XPath - expressions MUST be valid, but any implementation may choose to - implement them by hand, rather than using the XPath expression - directly. - - XPath expressions are evaluated in the context of the current node. - The namespace URI of the current module is used for any unprefixed - node name appearing in an XPath expression. References to - identifiers defined in external modules MUST be qualified with - appropriate prefixes, and references to identifiers defined in the - current module and its submodules MAY use a prefix. - - The above concept of default namespace is adopted from XPath 2.0 - [XPATH2.0]. It helps simplify XPath expressions in YANG. No - ambiguity may ever arise because YANG node identifiers are always - qualified names with a non-null namespace URI. + expressions MUST be syntactically correct, and all prefixes used MUST + be present in the XPath context (see Section 6.4.1). An + implementation may choose to implement them by hand, rather than + using the XPath expression directly. The data model used in the XPath expressions is the same as that used in XPath 1.0 [XPATH], with the same extension for root node children as used by XSLT 1.0 [XSLT] (section 3.1). Specifically, it means that the root node may have any number of element nodes as its children. 6.4.1. XPath Context All YANG XPath expressions share the following XPath context definition: o The set of namespace declarations is the set of all "import" - statements' prefix and namespace pairs, and the "prefix" - statement's prefix for the "namespace" statement's URI. + statements' prefix and namespace pairs in the module where the + XPath expression is specified, and the "prefix" statement's prefix + for the "namespace" statement's URI. - o Elements without a namespace prefix refer to nodes in the - namespace of the current module. + o Names without a namespace prefix belong to the same namespace as + the identifier of the current node. Inside a grouping, that + namespace is affected by where the grouping is used (see + Section 7.12). o The function library is the core function library defined in [XPATH], and a function "current()" which returns a node set with the initial context node. o The set of variable bindings is empty. + The mechanism for handling unprefixed names is adopted from XPath 2.0 + [XPATH2.0], and helps simplify XPath expressions in YANG. No + ambiguity may ever arise because YANG node identifiers are always + qualified names with a non-null namespace URI. + The context node varies with the YANG XPath expression, and is specified where the YANG statement with the XPath expression is defined. 6.5. Schema Node Identifier A schema node identifier is a string that identifies a node in the schema tree. It has two forms, "absolute" and "descendant", defined by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" in Section 12, respectively. A schema node identifier consists of a @@ -1795,21 +1802,22 @@ 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. 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). Its argument is the URI of the namespace. + 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 @@ -1932,20 +1940,21 @@ every published editorial change, a new one SHOULD be added in front of the revisions sequence, so that all revisions are in reverse chronological order. 7.1.9.1. The revision's Substatement +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.19.3 | 0..1 | + | reference | 7.19.4 | 0..1 | +--------------+---------+-------------+ 7.1.10. Usage Example module acme-system { namespace "http://acme.example.com/system"; prefix "acme"; import ietf-yang-types { prefix "yang"; @@ -2157,23 +2166,26 @@ 7.3.4. The typedef's default Statement The "default" statement takes as an argument a string which contains a default value for the new type. The value of the "default" statement MUST be valid according to the type specified in the "type" statement. If the base type has a default value, and the new derived type does not specify a new default value, the base type's default value is - also the default value of the new derived type. If the base type's - default value is not valid according to the new restrictions, the - derived type MUST define a new default value. + also the default value of the new derived type. + + If the type's default value is not valid according to the new + restrictions specified in a derived type or leaf definition, the + derived type or leaf definition MUST specify a new default value + compatible with the restrictions. 7.3.5. Usage Example typedef listen-ipv4-address { type inet:ipv4-address; default "0.0.0.0"; } 7.4. The type Statement @@ -2271,40 +2283,42 @@ 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. When a data store is validated, all "must" constraints are conceptually evaluated once for each corresponding instance in the - data tree, and for all leafs with default values in effect. If an - instance does not exist in the data tree, and it does not have a - default value, its "must" statements are not evaluated. + data tree, and for all leafs with default values in use (see + Section 7.6.1). If an instance 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 context, in addition to the definition in Section 6.4.1: o The context node is the node in the data tree for which the "must" statement is defined. o The accessible tree is made up of all nodes in the data tree, and - all leafs with default values. + all leafs with default values in use (see Section 7.6.1). The accessible tree depends on the context node: o If the context node represents configuration, the tree is the data - in one of the NETCONF datastores. The XPath root node has all - top-level configuration data nodes in all modules as children. + 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 If the context node represents state data, 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. o If the context node represents notification content, the tree is the notification XML instance document. The XPath root node has the element representing the notification being defined as the only child. @@ -2475,122 +2489,144 @@ A leaf node has a value, but no child nodes in the data tree. Conceptually, the value in the data tree is always in the canonical form (see Section 9.1). A leaf node exists in zero or one instances in the data tree, depending on the value of the "mandatory" statement. The "leaf" statement is used to define a scalar variable of a particular built-in or derived type. - If a leaf has a "default" statement, the leaf's default value is set - to 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 set to the type's default value. In all - other cases, the leaf does not have a default value. +7.6.1. The leaf's default value - If the leaf has a default value, the server MUST use this value - internally if no value is provided by the NETCONF client when the - instance is created. + The default value of a leaf is the value that the server uses if the + leaf does not exist in the data tree. The usage of the default value + depends on the leaf's closest ancestor node in the schema tree which + is not a non-presence container: -7.6.1. The leaf's Substatements + o If no such ancestor exists in the schema tree, the default value + MUST be used. + + o Otherwise, if this ancestor is a case node, the default value MUST + 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. + + 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 +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | config | 7.19.1 | 0..1 | - | default | 7.6.3 | 0..1 | + | default | 7.6.4 | 0..1 | | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | - | mandatory | 7.6.4 | 0..1 | + | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | - | type | 7.6.2 | 1 | + | type | 7.6.3 | 1 | | units | 7.3.3 | 0..1 | | when | 7.19.5 | 0..1 | +--------------+---------+-------------+ -7.6.2. The leaf's type Statement +7.6.3. The leaf's type Statement The "type" statement, which MUST be present, takes as an argument the name of an existing built-in or derived type. The optional substatements specify restrictions on this type. See Section 7.4 for details. -7.6.3. The leaf's default Statement +7.6.4. The leaf's default Statement The "default" statement, which is optional, takes as an argument a string which contains a default value for the leaf. The value of the "default" statement MUST be valid according to the type specified in the leaf's "type" statement. The "default" statement MUST NOT be present on nodes where "mandatory" is true. -7.6.4. The leaf's mandatory Statement +7.6.5. The leaf's mandatory Statement The "mandatory" statement, which is optional, takes as an argument the string "true" or "false", and puts a constraint on valid data. If not specified, the default is "false". If "mandatory" is "true", the behavior of the constraint depends on the type of the leaf's closest ancestor node in the schema tree which is not a non-presence container (see Section 7.5.1): - o If no such ancestor exists, the leaf MUST exist. + o If no such ancestor exists in the schema tree, the leaf MUST + exist. o Otherwise, if this ancestor is a case node, the leaf MUST exist if - any node from the case exists. + any node from the case exists in the data tree. - o Otherwise, the leaf MUST exist if the ancestor node exists. + o Otherwise, the leaf MUST exist if the ancestor node exists in the + data tree. This constraint is enforced according to the rules in Section 8. -7.6.5. XML Mapping Rules +7.6.6. XML Mapping Rules A leaf node is encoded as an XML element. The element's name is the leaf's identifier, and its XML namespace is the module's XML namespace. The value of the leaf node is encoded to XML according to the type, and sent as character data in the element. A NETCONF server that replies to a or request MAY choose not to send the leaf element if its value is the default value. Thus, a client that receives an for a or request, MUST be prepared to handle the case that a leaf node with a default value is not present in the XML. In this case, the value used by the server is known to be the default value. - See Section 7.6.7 for an example. + See Section 7.6.8 for an example. -7.6.6. NETCONF Operations +7.6.7. NETCONF Operations When a NETCONF server processes an request, the elements of procedure for the leaf node are: If the operation is "merge", the node is created if it does not exist, and its value is set to the value found in the XML RPC data. If the operation is "replace", the node is created if it does not exist, and its value is set to the value found in the XML RPC data. If the operation is "create" the node is created if it does not exist. If the operation is "delete" the node is deleted if it exists. -7.6.7. Usage Example +7.6.8. Usage Example Given the following leaf statement, placed in the previously defined "ssh" container (See Section 7.5.9): leaf port { type inet:port-number; default 22; description "The port which the SSH server listens to" } @@ -2777,21 +2813,21 @@ The "insert" attribute can take the values "first", "last", "before", and "after". If the value is "before" or "after", the "value" attribute MUST also be used to specify an existing entry in the leaf- list. If no "insert" attribute is present in the "create" operation, it defaults to "last". If several entries in an "ordered-by user" leaf-list are modified in - the same request, the entires are modified one at the + the 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 leaf-list, the leaf-list 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 leaf-list node are: If the operation is "merge" or "replace" the leaf-list entry is @@ -3047,21 +3083,21 @@ The "insert" attribute can take the values "first", "last", "before", and "after". If the value is "before" or "after", the "key" attribute MUST also be used, to specify an existing element in the list. The value of the "key" attribute is the key predicates of the full instance identifier (see Section 9.13) for the list entry. If no "insert" attribute is present in the "create" operation, it defaults to "last". If several entries in an "ordered-by user" list are modified in the - same request, the entires are modified one at the time, + 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. 7.8.7. Usage Example Given the following list: @@ -3238,25 +3274,25 @@ 7.9.2. The choice's case Statement The "case" statement is used to define branches of the choice. It takes as an argument an identifier, followed by a block of substatements that holds detailed case information. The identifier is used to identify the case node in the schema tree. A case node does not exist in the data tree. - Within a "case" statement, the "anyxml", "container", "leaf", "list", - "leaf-list", and "uses" statements can be used to define child nodes - to the case node. The identifiers of all these child nodes MUST be - unique within all cases in a choice. For example, the following is - illegal: + Within a "case" statement, the "anyxml", "choice", "container", + "leaf", "list", "leaf-list", and "uses" statements can be used to + define child nodes to the case node. The identifiers of all these + child nodes MUST be unique within all cases in a choice. For + example, the following is illegal: choice interface-type { // This example is illegal YANG case a { leaf ethernet { ... } } case b { container ethernet { ...} } } @@ -3279,20 +3315,21 @@ } The case identifier MUST be unique within a choice. 7.9.2.1. The case's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | + | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | uses | 7.12 | 0..n | | when | 7.19.5 | 0..1 | @@ -3452,21 +3489,21 @@ An anyxml node exists in zero or one instances in the data tree. 7.10.1. The anyxml's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | config | 7.19.1 | 0..1 | | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | - | mandatory | 7.6.4 | 0..1 | + | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | when | 7.19.5 | 0..1 | +--------------+---------+-------------+ 7.10.2. XML Mapping Rules An anyxml node is encoded as an XML element. The element's name is the anyxml's identifier, and its XML namespace is the module's XML @@ -3588,23 +3625,25 @@ } 7.12. The uses Statement The "uses" statement is used to reference a "grouping" definition. It takes one argument, which is the name of the grouping. The effect of a "uses" reference to a grouping is that the nodes defined by the grouping are copied into the current schema tree, and then updated according to the refinement and augment statements. - Thus, the identifiers defined in the grouping are copied into the - current module's namespace, even if the grouping is imported from - some other module. + + The identifiers defined in the grouping are not bound to a namespace + until the contents of the grouping are added to the schema tree via a + "uses" statement that does not appear inside a "grouping" statement, + at which point they are bound to the namespace of the current module. 7.12.1. The uses's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | augment | 7.15 | 0..1 | | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | | refine | 7.12.2 | 0..1 | @@ -3629,26 +3668,27 @@ o A leaf or choice node may get a default value, or a new default value if it already had one. o Any node may get a specialized "description" string. o Any node may get a specialized "reference" string. o Any node may get a different "config" statement. - o A leaf or choice node may get a different "mandatory" statement. + o A leaf, anyxml, or choice node may get a different "mandatory" + statement. o A container node may get a "presence" statement. - o A leaf, leaf-list, list or container node may get additional - "must" expressions. + o A leaf, leaf-list, list, container, or anyxml node may get + additional "must" expressions. o A leaf-list or list node may get a different "min-elements" or "max-elements" statement. 7.12.3. XML Mapping Rules Each node in the grouping is encoded as if it was defined inline, even if it is imported from another module with another XML namespace. @@ -3740,24 +3781,27 @@ +--------------+---------+-------------+ 7.13.2. The input Statement The "input" statement, which is optional, is used to define input parameters to the RPC method. It does not take an argument. The substatements to "input" define nodes under the RPC's input node. If a leaf in the input tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF RPC invocation. + Otherwise, the server MUST return a "missing-element" error. If a leaf in the input tree has a default value, the NETCONF server - MUST internally use this default if the leaf is not present in a - NETCONF RPC invocation. + MUST use this value in the same cases as described in Section 7.6.1. + In these cases, the server MUST operationally behave as if the leaf + was present in the NETCONF RPC invocation with the default value as + its value. If a "config" statement is present for any node in the input tree, it is ignored. If any node has a "when" statement which would evaluate to false, then this node MUST NOT be present in the input tree. 7.13.2.1. The input's Substatements +--------------+---------+-------------+ @@ -3777,22 +3821,24 @@ 7.13.3. The output Statement The "output" statement, which is optional, is used to define output parameters to the RPC method. It does not take an argument. The substatements to "output" define nodes under the RPC's output node. If a leaf in the output tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF RPC reply. If a leaf in the output tree has a default value, the NETCONF client - MUST internally use this default if the leaf is not present in a - NETCONF RPC reply. + MUST use this value in the same cases as described in Section 7.6.1. + In these cases, the client MUST operationally behave as if the leaf + was present in the NETCONF RPC reply with the default value as its + value. If a "config" statement is present for any node in the output tree, it is ignored. If any node has a "when" statement which would evaluate to false, then this node MUST NOT be present in the output tree. 7.13.3.1. The output's Substatements +--------------+---------+-------------+ @@ -3865,22 +3911,24 @@ information. The "notification" statement defines a notification node in the schema tree. If a container in the notification tree has a "presence" statement, the container need not be present in a NETCONF notification. If a leaf in the notification tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF notification. If a leaf in the notification tree has a default value, the NETCONF - client MUST internally use this default if the leaf is not present in - a NETCONF notification. + client MUST use this value in the same cases as described in + Section 7.6.1. In these cases, the client MUST operationally behave + as if the leaf was present in the NETCONF notification with the + default value as its value. If a "config" statement is present for any node in the notification tree, it is ignored. 7.14.1. The notification's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | @@ -4409,22 +4457,22 @@ substatement's keyword MUST match a corresponding keyword in the target node, and the argument's string MUST be equal to the corresponding keyword's argument string in the target node. The deviates's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | config | 7.19.1 | 0..1 | - | default | 7.6.3 | 0..1 | - | mandatory | 7.6.4 | 0..1 | + | default | 7.6.4 | 0..1 | + | mandatory | 7.6.5 | 0..1 | | max-elements | 7.7.4 | 0..1 | | min-elements | 7.7.3 | 0..1 | | must | 7.5.3 | 0..n | | type | 7.4 | 0..1 | | unique | 7.8.3 | 0..n | | units | 7.3.3 | 0..1 | +--------------+---------+-------------+ 7.18.3.3. Usage Example @@ -4553,27 +4601,28 @@ o If the "when" statement is a child of a "choice" or "case" statement, then the context node is the closest ancestor node to the "choice" or "case" node which is also a data node. o If the "when" statement is a child of any other data definition statement, the context node is the data definition's node in the data tree. o The accessible tree is made up of all nodes in the data tree, and - all leafs with default values. + all leafs with default values in use (see Section 7.6.1). The accessible tree depends on the context node: o If the context node represents configuration, the tree is the data - in one of the NETCONF datastores. The XPath root node has all - top-level configuration data nodes in all modules as children. + 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 If the context node represents state data, 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. o If the context node represents notification content, the tree is the notification XML instance document. The XPath root node has the element representing the notification being defined as the only child. @@ -4870,29 +4919,33 @@ +---------------+---------+-------------+ 9.2.5. Usage Example typedef my-base-int32-type { type int32 { range "1..4 | 10..20"; } } + typedef my-type1 { type my-base-int32-type { // legal range restriction range "11..max"; // 11..20 } + } + typedef my-type2 { type my-base-int32-type { // illegal range restriction range "11..100"; } + } 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. @@ -5212,24 +5265,24 @@ 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, MUST be present if the type is "bits". It is repeatedly used to specify each assigned named bit of a bits type. It takes as an argument a string which is the assigned name of the bit. It is followed by a block of substatements which holds detailed bit - information. A bit name follows the same syntax rules as an + information. The assigned name follows the same syntax rules as an identifier (see Section 6.2). - All bit names in a bits type MUST be unique. + All assigned names in a bits type MUST be unique. 9.7.4.1. The bit's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.19.3 | 0..1 | | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | position | 9.7.4.2 | 0..1 | @@ -5299,25 +5352,31 @@ 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 of these leaf instances. If the leaf with the leafref type represents configuration data, the leaf it refers to MUST also represent configuration. Such a leaf puts a constraint on valid data. All leafref nodes MUST reference - existing leaf instances for the data to be valid. This constraint is - enforced according to the rules in Section 8. + existing leaf instances or leafs with default values in use (see + Section 7.6.1) for the data to be valid. This constraint is enforced + according to the rules in Section 8. There MUST NOT be any circular chains of leafrefs. + If the leaf that the leafref refers to is conditional based on one or + more feature (see Section 7.18.2), then the leaf with the leafref + type MUST also be conditional based on at least the same set of + features. + 9.9.1. Restrictions A leafref cannot be restricted. 9.9.2. The path Statement The "path" statement, which is a substatement to the "type" statement, MUST be present if the type is "leafref". It takes as an argument a string which MUST refer to a leaf or leaf-list node. @@ -5339,24 +5398,24 @@ configuration data, this node set MUST be non-empty. The "path" XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o The context node is the node in the data tree for which the "path" statement is defined. The accessible tree depends on the context node: - o If the leaf with the instance-identifier type represents - configuration data, the tree is the data in one of the NETCONF - datastores. The XPath root node has all top-level configuration - data nodes in all modules as children. + 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 A leafref value is encoded the same way as the leaf it references. 9.9.4. Canonical Form @@ -5526,29 +5585,38 @@ The "base" statement, which is a substatement to the "type" statement, MUST be present if the type is "identityref". The argument is the name of an identity, as defined by an "identity" 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. + 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 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. 9.10.5. Usage Example With the identity definitions in Section 7.16.3, and the following module: @@ -5681,36 +5749,38 @@ a node in the data tree. Predicates are used only for specifying the values for the key nodes for list entries, a value of a leaf-list entry, or a positional index for list without keys. For identifying list entries with keys, each predicate consists of one equality test per key, and each key MUST have a corresponding predicate. If the leaf with the instance-identifier type represents configuration data, and the "require-instance" property (Section 9.13.2) is "true", the node it refers to MUST also represent configuration. Such a leaf puts a constraint on valid data. All - such leaf nodes MUST reference existing nodes for the data to be + such leaf nodes MUST reference existing nodes or leaf nodes with + their default value in use (see Section 7.6.1) for the data to be valid. This constraint is enforced according to the rules in Section 8. The "instance-identifier" XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o The context node is the root node in the accessible tree. - The accessible tree depends on the context node: + The accessible tree depends on the leaf with the instance-identifier + type: - o If the leaf with the instance-identifier type represents - configuration data, the tree is the data in one of the NETCONF - datastores. The XPath root node has all top-level configuration - data nodes in all modules as children. + o If this leaf represents configuration data, the tree is the data + in the NETCONF datastore where the leaf 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.13.1. Restrictions An instance-identifier can be restricted with the "require-instance" statement (Section 9.13.2). @@ -5719,22 +5789,21 @@ The "require-instance" statement, which is a substatement to the "type" statement, MAY be present if the type is "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, and if it exists, its value MUST be - equal to the value of the referring leaf. + referred MAY exist in valid data. 9.13.3. Lexicographic 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. Any prefixes used in the encoding are local to each instance @@ -5798,22 +5867,20 @@ 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 positions do not change. o A "range", "length", or "pattern" statement may expand the allowed value space. - o A "default" statement may be added. - 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 @@ -6031,20 +6098,22 @@ In YANG, almost all statements are unordered. The ABNF grammar [RFC5234] defines the canonical order. To improve module readability, it is RECOMMENDED that clauses be entered in this order. Within the ABNF grammar, unordered statements are marked with comments. This grammar assumes that the scanner replaces YANG comments with a single space character. + == begin "yang.abnf" + module-stmt = optsep module-keyword sep identifier-arg-str optsep "{" stmtsep module-header-stmts linkage-stmts meta-stmts revision-stmts body-stmts "}" optsep @@ -6092,27 +6162,20 @@ deviation-stmt) stmtsep) data-def-stmt = container-stmt / leaf-stmt / leaf-list-stmt / list-stmt / choice-stmt / anyxml-stmt / uses-stmt - case-data-def-stmt = container-stmt / - leaf-stmt / - leaf-list-stmt / - list-stmt / - anyxml-stmt / - uses-stmt - yang-version-stmt = yang-version-keyword sep yang-version-arg-str optsep stmtend yang-version-arg-str = < a string which matches the rule yang-version-arg > yang-version-arg = "1" import-stmt = import-keyword sep identifier-arg-str optsep "{" stmtsep @@ -6149,20 +6211,21 @@ stmtend reference-stmt = reference-keyword sep string optsep stmtend units-stmt = units-keyword sep string optsep stmtend revision-stmt = revision-keyword sep revision-date optsep (";" / "{" stmtsep [description-stmt stmtsep] + [reference-stmt stmtsep] "}") revision-date = date-arg-str revision-date-stmt = revision-date-keyword sep revision-date stmtend extension-stmt = extension-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order @@ -6254,21 +6316,22 @@ "}") decimal64-specification = fraction-digits-stmt fraction-digits-stmt = fraction-digits-keyword sep fraction-digits-arg-str stmtend fraction-digits-arg-str = < a string which matches the rule fraction-digits-arg > - fraction-digits-arg = ("1" ["2" / "3" / "4" / "5" / "6" / "7" / "8"]) + fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / + "5" / "6" / "7" / "8"]) / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" string-restrictions = ;; these stmts can appear in any order [length-stmt stmtsep] *(pattern-stmt stmtsep) length-stmt = length-keyword sep length-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order @@ -6533,21 +6599,21 @@ case-stmt = case-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [when-stmt stmtsep] *(if-feature-stmt stmtsep) [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] - *(case-data-def-stmt stmtsep) + *(data-def-stmt stmtsep) "}") anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [when-stmt stmtsep] *(if-feature-stmt stmtsep) *(must-stmt stmtsep) [config-stmt stmtsep] @@ -6626,20 +6692,21 @@ [config-stmt stmtsep] [mandatory-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] refine-case-stmts = ;; these stmts can appear in any order [description-stmt stmtsep] [reference-stmt stmtsep] refine-anyxml-stmts = ;; these stmts can appear in any order + *(must-stmt stmtsep) [config-stmt stmtsep] [mandatory-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep "{" stmtsep ;; these stmts can appear in any order [when-stmt stmtsep] *(if-feature-stmt stmtsep) @@ -6665,21 +6732,24 @@ 1*((data-def-stmt stmtsep) / (case-stmt stmtsep)) "}" augment-arg-str = < a string which matches the rule augment-arg > augment-arg = absolute-schema-nodeid unknown-statement = prefix ":" identifier [sep string] optsep - (";" / "{" *unknown-statement "}") + (";" / "{" *unknown-statement2 "}") + + unknown-statement2 = [prefix ":"] identifier [sep string] optsep + (";" / "{" *unknown-statement2 "}") when-stmt = when-keyword sep string stmtend rpc-stmt = rpc-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(if-feature-stmt stmtsep) [status-stmt stmtsep] [description-stmt stmtsep] @@ -7030,20 +7102,22 @@ SP = %x20 ; space VCHAR = %x21-7E ; visible (printing) characters WSP = SP / HTAB ; white space + == end "yang.abnf" + 13. Error Responses for YANG Related Errors 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 @@ -7141,35 +7215,41 @@ 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) 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. The module name prefix 'ietf-' is reserved for IETF stream documents 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. + 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. @@ -7296,56 +7376,76 @@ [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999, . Appendix A. ChangeLog RFC Editor: remove this section upon publication as an RFC. -A.1. Version -07 +A.1. Version -08 + + o Clarified text on leaf deafults. + + o Added the term "top-level data node" to the terminology section. + + o Clarified how prefixes are mapped to namespaces in XPath + expressions. + + o Added "reference" as a substatement to "revision". + + o Added "choice" as a substatement to "case". + + o Clarified that a leafreaf must be conditional if the leaf it + refers to is conditional. + + o Clarified how identityref default values are represented. + + o Various bug fixes, clarifications and editorial fixes. + +A.2. Version -07 o The argument string of "augment", "refine", and "deviation" is described not as an XPath but as a "schema node identifier". o Clarified that there must be no circular references in a leafref. -A.2. Version -06 +A.3. Version -06 o Various bug fixes, clarifications and editorial fixes after WGLC. o Removed "require-instance" for leafref. o Allow leafrefs to refer to leaf-lists. o Clarified the XPath context in Section 6.4.1, and for "must", "when", "augment", "path" and "instance-identifier". -A.3. Version -05 +A.4. Version -05 o Replaced the data types "float32" and "float64" with "decimal64". o Specified that the elements in the XML encoding of configuration data can occur in any order. o Clarified that "augment" cannot add multiple nodes with the same name. o Clarified what "when" means in RPC input / output. o Wrote the IANA Considerations section. o Changed requirement for minimum identifier length to 64 characters. -A.4. Version -04 +A.5. Version -04 o Using "revision-date" substatement to "import" and "include". o Corrected grammar and text for instance-identifier. o Fixed bugs in some examples. o Rewrote the YIN description to use a declarative style. o Added two error codes in Section 13. @@ -7357,37 +7457,37 @@ o Corrected grammar for key-arg; now allowing optional prefix on each leaf identifier. o Clarified that "unique" constraints only check instances with values for all referenced leafs. o Clarified how mandatory and min-elements constraints are enforced. o Editorial fixes. -A.5. Version -03 +A.6. Version -03 o Added import by revision (yang-00413) o Changed type "keyref" to "leafref", and added the statement "require-instance" (yang-01253) o Clarified that data sent from the server must be in the canonical form. o Clarified when and how constraints in the models are enforced. o Many editorial fixes o Added more strict grammar for the "deviate" statement. -A.6. Version -02 +A.7. Version -02 o Added module update rules. (yang-00000) o Added "refine" statement as a substatement to "uses". (yang-00088) o Allow "augment" on top-level and in "uses" only. (yang-00088) o Allow "when" on all data defintion statements. (yang-00088) o Added section "Constraints" and clarified when constraints are @@ -7398,21 +7498,21 @@ o Added "prefix" as a substatement to "belongs-to". (yang-00755) o Added section on Conformance. (yang-01281) o Added "deviation" statement. (yang-01281) o Added "identity" statement and "identityref" type. (yang-01339) o Aligned grammar for "enum" with text. -A.7. Version -01 +A.8. Version -01 o Removed "Appendix A. Derived YANG Types". o Removed "Appendix C. XML Schema Considerations". o Removed "Appendix F. Why We Need a New Modeling Language". o Moved "Appendix B. YIN" to its own section. o Moved "Appendix D. YANG ABNF Grammar" to its own section. @@ -7443,21 +7543,21 @@ o Fixed whitespace issues in the ABNF grammar. o Added the term "mandatory node", and refer to it in the description of augment (see Section 7.15), and choice (see Section 7.9.3). o Added support for multiple "pattern" statements in "type". o Several clarifications and fixed typos. -A.8. Version -00 +A.9. Version -00 Changes from draft-bjorklund-netconf-yang-02.txt o Fixed bug in grammar for bit-stmt o Fixed bugs in example XPath expressions o Added keyword 'presence' to the YIN mapping table Author's Address