--- 1/draft-ietf-netmod-yang-05.txt 2009-06-25 23:12:12.000000000 +0200 +++ 2/draft-ietf-netmod-yang-06.txt 2009-06-25 23:12:12.000000000 +0200 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track April 20, 2009 -Expires: October 22, 2009 +Intended status: Standards Track June 25, 2009 +Expires: December 27, 2009 YANG - A data modeling language for NETCONF - draft-ietf-netmod-yang-05 + draft-ietf-netmod-yang-06 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,38 +21,39 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on October 22, 2009. + This Internet-Draft will expire on December 27, 2009. 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 and restrictions with respect to this document. Abstract YANG is a data modeling language used to model configuration and - state data manipulated by the NETCONF protocol, NETCONF remote - procedure calls, and NETCONF notifications. + state data manipulated by the Network Configuration Protocol + (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF + notifications. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 @@ -74,265 +75,263 @@ 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.2. Optional Features . . . . . . . . . . . . . . . . . . 32 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 5.6.4. Announcing Conformance Information in the Message . . . . . . . . . . . . . . . . . . . . . . . 33 - 5.6.5. Mapping to the NETCONF Schema Discovery Mechanism . . 35 - 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 - 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 + 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 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 40 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 41 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 42 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 42 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 43 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 43 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 44 7.1.7. The organization Statement . . . . . . . . . . . . . 45 - 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 Encoding 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 Encoding Rules . . . . . . . . . . . . . . . . . 61 - 7.6.6. NETCONF Operations . . . . . . . . . . 61 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 45 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 45 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 46 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 46 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 47 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 48 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 49 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 49 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 50 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 50 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 50 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 50 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 51 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 51 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 51 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 51 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 52 + 7.5.2. The container's Substatements . . . . . . . . . . . . 53 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 53 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 55 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 56 + 7.5.6. The container's Child Node Statements . . . . . . . . 56 + 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 56 + 7.5.8. NETCONF Operations . . . . . . . . . . 56 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 57 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 58 + 7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 59 + 7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 59 + 7.6.3. The leaf's default Statement . . . . . . . . . . . . 59 + 7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 59 + 7.6.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 60 + 7.6.6. NETCONF Operations . . . . . . . . . . 60 7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 61 - 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 Encoding 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 Encoding 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 Encoding 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 Encoding 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 Encoding 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 Encoding 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 Encoding Rules . . . . . . . . . . . . . . . . . 92 - 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 92 - 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 93 - 7.15.1. The augment's Substatements . . . . . . . . . . . . . 95 - 7.15.2. XML Encoding 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 . . . . . . . . . . . . . . . . . . . . . . . . . 110 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 110 - 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 110 - 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 110 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 111 - 8.3.2. NETCONF Processing . . . . . . . . . . 111 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 112 - 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 113 - 9.1. Canonical representation . . . . . . . . . . . . . . . . 113 - 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 113 - 9.2.1. Lexicographic Representation . . . . . . . . . . . . 114 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 115 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 115 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 115 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 116 - 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 116 - 9.3.1. Lexicographic Representation . . . . . . . . . . . . 116 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 117 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 - 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 . . . . . . . . . . . . . . . . . . . . 119 - 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 119 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 120 - 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 120 - 9.5.1. Lexicographic Representation . . . . . . . . . . . . 120 - 9.5.2. 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 . . . . . . . . . . . . . . . . . . . . 121 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 121 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 122 - 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. The require-instance Statement . . . . . . . . . . . 125 - 9.9.4. Lexicographic Representation . . . . . . . . . . . . 126 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 126 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 126 - 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 . . . . . . . . . . . . 129 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 129 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 - 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 130 - 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. Lexicographic Representation . . . . . . . . . . . . 132 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . . 132 - 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 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 61 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 62 + 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 63 + 7.7.3. The min-elements Statement . . . . . . . . . . . . . 63 + 7.7.4. The max-elements Statement . . . . . . . . . . . . . 63 + 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 64 + 7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 64 + 7.7.7. NETCONF operations . . . . . . . . . . 64 + 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 65 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 67 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 68 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 68 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 69 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 70 + 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 70 + 7.8.6. NETCONF operations . . . . . . . . . . 71 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 71 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 75 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 75 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 75 + 7.9.3. The choice's default Statement . . . . . . . . . . . 77 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 78 + 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 79 + 7.9.6. NETCONF operations . . . . . . . . . . 79 + 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 79 + 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 80 + 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 81 + 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 81 + 7.10.3. NETCONF operations . . . . . . . . . . 81 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 82 + 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 82 + 7.11.1. The grouping's Substatements . . . . . . . . . . . . 83 + 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 83 + 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 83 + 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 84 + 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 84 + 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 85 + 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 + 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 86 + 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 87 + 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 87 + 7.13.3. The output Statement . . . . . . . . . . . . . . . . 88 + 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 89 + 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 89 + 7.14. The notification Statement . . . . . . . . . . . . . . . 90 + 7.14.1. The notification's Substatements . . . . . . . . . . 91 + 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 91 + 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 91 + 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 92 + 7.15.1. The augment's Substatements . . . . . . . . . . . . . 93 + 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 93 + 7.16. The identity Statement . . . . . . . . . . . . . . . . . 95 + 7.16.1. The identity's Substatements . . . . . . . . . . . . 96 + 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 96 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 97 + 7.17. The extension Statement . . . . . . . . . . . . . . . . . 97 + 7.17.1. The extension's Substatements . . . . . . . . . . . . 98 + 7.17.2. The argument Statement . . . . . . . . . . . . . . . 98 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 99 + 7.18. Conformance-related Statements . . . . . . . . . . . . . 99 + 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 99 + 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 101 + 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 101 + 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 104 + 7.19.1. The config Statement . . . . . . . . . . . . . . . . 104 + 7.19.2. The status Statement . . . . . . . . . . . . . . . . 104 + 7.19.3. The description Statement . . . . . . . . . . . . . . 105 + 7.19.4. The reference Statement . . . . . . . . . . . . . . . 105 + 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 105 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 107 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 107 + 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 107 + 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 107 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 108 + 8.3.2. NETCONF Processing . . . . . . . . . . 108 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 109 + 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 110 + 9.1. Canonical representation . . . . . . . . . . . . . . . . 110 + 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 110 + 9.2.1. Lexicographic Representation . . . . . . . . . . . . 111 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 112 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 112 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 112 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 113 + 9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 113 + 9.3.1. Lexicographic Representation . . . . . . . . . . . . 113 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 113 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 113 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 114 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 114 + 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 114 + 9.4.1. Lexicographic Representation . . . . . . . . . . . . 115 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 115 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 115 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 115 + 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 116 + 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 116 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 117 + 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 117 + 9.5.1. Lexicographic Representation . . . . . . . . . . . . 117 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 + 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 118 + 9.6.1. Lexicographic Representation . . . . . . . . . . . . 118 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 118 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 + 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 119 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 119 + 9.7.2. Lexicographic Representation . . . . . . . . . . . . 120 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 120 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 120 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 + 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 121 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 121 + 9.8.2. Lexicographic Representation . . . . . . . . . . . . 121 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 121 + 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 122 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 122 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 122 + 9.9.3. Lexicographic Representation . . . . . . . . . . . . 123 + 9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 123 + 9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 + 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 126 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126 + 9.10.2. The identityref's base Statement . . . . . . . . . . 126 + 9.10.3. Lexicographic Representation . . . . . . . . . . . . 127 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 127 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 127 + 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 128 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 128 + 9.11.2. Lexicographic Representation . . . . . . . . . . . . 128 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 128 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 128 + 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 128 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 129 + 9.12.2. Lexicographic Representation . . . . . . . . . . . . 129 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 129 + 9.13. The instance-identifier Built-in Type . . . . . . . . . . 129 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 130 + 9.13.2. The require-instance Statement . . . . . . . . . . . 130 + 9.13.3. Lexicographic Representation . . . . . . . . . . . . 131 + 9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 131 + 9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 131 + 10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 132 + 11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 + 11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 135 + 11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 137 + 12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 139 + 13. Error Responses for YANG Related Errors . . . . . . . . . . . 160 + 13.1. Error Message for Data that Violates a unique Statement . 160 13.2. Error Message for Data that Violates a max-elements - Statement: . . . . . . . . . . . . . . . . . . . . . . . 162 + Statement . . . . . . . . . . . . . . . . . . . . . . . . 160 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 . . . . . . . . . . . . . . . . . . . . . . . . 160 + 13.4. Error Message for Data that Violates a must Statement . . 161 13.5. Error Message for Data that Violates a - require-instance statement: . . . . . . . . . . . . . . . 163 - 13.6. Error Message for Data that Violates a mandatory - choice statement: . . . . . . . . . . . . . . . . . . . . 163 - 13.7. Error Message for the "insert" Operation . . . . . . . . 163 - 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 164 - 15. Security Considerations . . . . . . . . . . . . . . . . . . . 165 - 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 166 - 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 167 - 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 168 - 18.1. Normative References . . . . . . . . . . . . . . . . . . 168 - 18.2. Non-Normative References . . . . . . . . . . . . . . . . 169 - Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 170 - A.1. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 170 - A.2. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 170 - A.3. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.4. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.5. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 171 - A.6. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 172 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 174 + require-instance Statement . . . . . . . . . . . . . . . 161 + 13.6. Error Message for Data that does not Match a leafref + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 161 + 13.7. Error Message for Data that Violates a mandatory + choice Statement . . . . . . . . . . . . . . . . . . . . 161 + 13.8. Error Message for the "insert" Operation . . . . . . . . 162 + 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 163 + 15. Security Considerations . . . . . . . . . . . . . . . . . . . 164 + 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 165 + 17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 166 + 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 167 + 18.1. Normative References . . . . . . . . . . . . . . . . . . 167 + 18.2. Non-Normative References . . . . . . . . . . . . . . . . 168 + Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 169 + A.1. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 169 + A.2. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 169 + A.3. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 169 + A.4. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 170 + A.5. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 170 + A.6. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 171 + A.7. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 172 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 173 1. Introduction - Today, the NETCONF protocol [RFC4741] lacks a standardized way to - create data models. Instead, vendors are forced to use proprietary - solutions. In order for NETCONF to be a interoperable protocol, - models must be defined in a vendor-neutral way. YANG provides the - language and rules for defining such models for use with NETCONF. - YANG is a data modeling language used to model configuration and - state data manipulated by the NETCONF protocol, NETCONF remote - procedure calls, and NETCONF notifications. YANG models the - operations and content layers of NETCONF (see the NETCONF protocol - [RFC4741], section 1.1). + state data manipulated by the Network Configuration Protocol + (NETCONF) protocol, NETCONF remote procedure calls, and NETCONF + notifications. YANG is used to model the operations and content + layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], + section 1.1). This document describes the syntax and semantics of the YANG language, how the data model defined in a YANG module is represented in XML, and how NETCONF operations are used to manipulate the data. 2. Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP @@ -364,24 +363,20 @@ most one instance. A container node has no value, but rather a set of child nodes. o data definition statement: A statement that defines new data nodes. One of container, leaf, leaf-list, list, choice, case, augment, uses, and anyxml. o data model: A data model describes how data is represented and accessed. - o data model object: A definition within a module that represents a - construct which can be accessed via a network management protocol. - Also called an object. - o data node: A node in the schema tree that can be instantiated in a data tree. One of container, leaf, leaf-list, list, and anyxml. o data tree: The instantiated tree of configuration and state data on a device. o derived type: A type which is derived from a built-in type (such as uint32), or another derived type. o device deviation: A failure of the device to implement the module @@ -410,23 +405,20 @@ o leaf: A node in the data tree with a value but no child nodes. o leaf-list: Like the leaf node but defines a set of uniquely identifiable nodes rather than a single node. Each node has a value but no child nodes. o list: Interior nodes in the data tree which may exist in multiple instances. A list node has no value, but rather a set of child nodes. - o MIB: A Management Information Base, traditionally referring to a - management information defined using SNMP's SMI. - o module: A YANG module defines a hierarchy of nodes which can be used for NETCONF-based operations. With its definitions and the definitions it imports or includes from elsewhere, a module is self-contained and "compilable". o RPC: A Remote Procedure Call, as used within the NETCONF protocol. o RPC method: A specific Remote Procedure Call, as used within the NETCONF protocol. Also called a protocol operation. @@ -448,47 +440,47 @@ A YANG module can be constructed from a number of submodules. 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 or choice node with a "mandatory" statement with the value - "true". + o A leaf, choice, or anyxml node with a "mandatory" statement with + the value "true". o A list or leaf-list node with a "min-elements" statement with a value greater than zero. - o A container node without a "presence" statement, which has has at + o A container node without a "presence" statement, which has at least one mandatory node as a child. 4. YANG Overview 4.1. Functional Overview YANG is a language used to model data for the NETCONF protocol. A YANG module defines a hierarchy of data which can be used for NETCONF-based operations, including configuration, state data, remote procedure calls (RPCs), and notifications. This allows a complete description of all data sent between a NETCONF client and server. YANG models the hierarchical organization of data as a tree in which each node has a name, and either a value or a set of child nodes. YANG provides clear and concise descriptions of the nodes, as well as the interaction between those nodes. YANG structures data models into modules and submodules. A module can import data from other external modules, and include data from - submodules. The hierarchy can be extended, allowing one module to + submodules. The hierarchy can be augmented, allowing one module to add data nodes to the hierarchy defined in another module. This augmentation can be conditional, with new nodes appearing only if certain conditions are met. YANG models can describe constraints to be enforced on the data, restricting the appearance or value of nodes based on the presence or value of other nodes in the hierarchy. These constraints are enforceable by either the client or the server, and valid content must abide by them. @@ -506,24 +498,25 @@ and used in either that location or in another module or submodule that imports or includes it. YANG organizational constructs include defining lists where list entries are identified by keys which distinguish them from each other. Such lists may be defined as either sorted by user or automatically sorted by the system. For user-sorted lists, operations are defined for manipulating the order of the list entries. - YANG modules can be translated into an XML format called YIN - (Section 11), allowing applications using XML parsers and XSLT - scripts to operate on the models. The conversion from YANG to YIN is - loss-less, so content in YIN can round-tripped back into YANG. + YANG modules can be translated into an XML format called YANG + Independent Notation (YIN) (Section 11), allowing applications using + XML parsers and XSLT scripts to operate on the models. The + conversion from YANG to YIN is loss-less, so content in YIN can be + round-tripped back into YANG. YANG strikes a balance between high-level data modeling and low-level bits-on-the-wire encoding. The reader of a YANG module can see the high-level view of the data model while understanding how the data will be encoded in NETCONF operations. YANG is an extensible language, allowing extension statements to be defined by standards bodies, vendors, and individuals. The statement syntax allows these extensions to coexist with standard YANG statements in a natural way, while making extensions stand out @@ -544,22 +537,22 @@ Like NETCONF, YANG targets smooth integration with device's native management infrastructure. This allows implementations to leverage their existing access control mechanisms to protect or expose elements of the data model. 4.2. Language Overview This section introduces some important constructs used in YANG that will aid in the understanding of the language specifics in later sections. This progressive approach handles the inter-related nature - of YANG concepts and statements. Specifics about YANG statements and - syntax begins in Section 7. + of YANG concepts and statements. A detailed description of YANG + statements and syntax begins in Section 7. 4.2.1. Modules and Submodules A module contains three types of statements: module-header statements, revision statements, and definition statements. The module header statements describe the module and give information about the module itself, the revision statements give information about the history of the module, and the definition statements are the body of the module where the data model is defined. @@ -587,39 +580,39 @@ A leaf node contains simple data like an integer or a string. It has exactly one value of a particular type, and no child nodes. YANG Example: leaf host-name { type string; description "Hostname for this system"; } - NETCONF XML Encoding: + NETCONF XML Example: my.example.com The "leaf" statement is covered in Section 7.6. 4.2.2.2. Leaf-list Nodes A leaf-list is a sequence of leaf nodes with exactly one value of a particular type per leaf. YANG Example: leaf-list domain-search { type string; description "List of domain names to search"; } - NETCONF XML Encoding: + NETCONF XML Example: high.example.com low.example.com everywhere.example.com The "leaf-list" statement is covered in Section 7.7. 4.2.2.3. Container Nodes A container node is used to group related nodes in a subtree. A @@ -632,21 +625,21 @@ container system { container login { leaf message { type string; description "Message given at start of login session"; } } } - NETCONF XML Encoding: + NETCONF XML Example: Good morning, Dave The "container" statement is covered in Section 7.5. 4.2.2.4. List Nodes @@ -665,21 +658,21 @@ type string; } leaf full-name { type string; } leaf class { type string; } } - NETCONF XML Encoding: + NETCONF XML Example: glocks Goldie Locks intruder snowey Snow White free-loader @@ -754,21 +747,20 @@ context for the state data. In this example, two leafs are defined for each interface, a configured speed and an observed speed. The observed speed is not configuration, so it can be returned with NETCONF operations, but not with operations. The observed speed is not configuration data, and cannot be manipulated using . list interface { key "name"; - config true; leaf name { type string; } leaf speed { type enumeration { enum 10m; enum 100m; enum auto; } @@ -807,44 +799,44 @@ | leafref | Text/Number | A reference to a leaf | | | | instance | | string | Text | Human readable string | | uint8 | Number | 8-bit unsigned integer | | uint16 | Number | 16-bit unsigned integer | | uint32 | Number | 32-bit unsigned integer | | uint64 | Number | 64-bit unsigned integer | | union | Text/Number | Choice of member types | +---------------------+-------------+-------------------------------+ - The "type" statement is covered in Section 9. + The "type" statement is covered in Section 7.4. 4.2.5. Derived Types (typedef) YANG can define derived types from base types using the "typedef" statement. A base type can be either a built-in type or a derived type, allowing a hierarchy of derived types. A derived type can be used as the argument for the "type" statement. YANG Example: typedef percent { - type uint16 { + type uint8 { range "0 .. 100"; } description "Percentage"; } leaf completed { type percent; } - NETCONF XML Encoding: + NETCONF XML Example: 20 The "typedef" statement is covered in Section 7.3. 4.2.6. Reusable Node Groups (grouping) Groups of nodes can be assembled into the equivalent of complex types using the "grouping" statement. "grouping" defines a set of nodes that are instantiated with the "uses" statement: @@ -859,21 +851,21 @@ description "Target port number"; } } container peer { container destination { uses target; } } - NETCONF XML Encoding: + NETCONF XML Example:
192.0.2.1
830 The grouping can be refined as it is used, allowing certain statements to be overridden. In this example, the description is refined: @@ -911,87 +903,87 @@ sets of schema nodes that cannot appear together. Each "case" may contain multiple nodes, but each node may appear in only one "case" under a "choice". When an element from one case is created, all elements from all other cases are implicitly deleted. The device handles the enforcement of the constraint, preventing incompatibilities from existing in the configuration. The choice and case nodes appear only in the schema tree, not in the - data tree or XML encoding. The additional levels of hierarchy are + data tree or NETCONF PDUs. The additional levels of hierarchy are not needed beyond the conceptual schema. YANG Example: container food { choice snack { - mandatory true; case sports-arena { leaf pretzel { type empty; } leaf beer { type empty; } } case late-night { leaf chocolate { type enumeration { enum dark; enum milk; enum first-available; } } } } } - NETCONF XML Encoding: + NETCONF XML Example: - first-available + + The "choice" statement is covered in Section 7.9. 4.2.8. Extending Data Models (augment) YANG allows a module to insert additional nodes into data models, including both the current module (and its submodules) or an external - module. This is useful e.g. for vendors to add vendor-specific - parameters to standard data models in an interoperable way. + module. This is useful for example for vendors to add vendor- + specific parameters to standard data models in an interoperable way. The "augment" statement defines the location in the data model hierarchy where new nodes are inserted, and the "when" statement defines the conditions when the new nodes are valid. YANG Example: - augment system/login/user { + augment /system/login/user { when "class != 'wheel'"; leaf uid { type uint16 { range "1000 .. 30000"; } } } This example defines a "uid" node that only is valid when the user's "class" is not "wheel". - If a module augments another model, the XML representation of the - data will reflect the prefix of the augmenting model. For example, + If a module augments another module, the XML representation of the + data will reflect the prefix of the augmenting module. For example, if the above augmentation were in a module with prefix "other", the XML would look like: - NETCONF XML Encoding: + NETCONF XML Example: alicew Alice N. Wonderland drop-out 1024 The "augment" statement is covered in Section 7.15. @@ -1008,26 +1000,26 @@ leaf image-name { type string; } } output { leaf status { type string; } } } - NETCONF XML Encoding: + NETCONF XML Example: - acmefw-2.3 + acmefw-2.3 The image acmefw-2.3 is being installed. @@ -1042,34 +1034,39 @@ YANG Example: notification link-failure { description "A link failure has been detected"; leaf if-name { type leafref { path "/interfaces/interface/name"; } } leaf if-admin-status { - type ifAdminStatus; + type admin-status; + } + leaf if-oper-status { + type oper-status; } } - NETCONF XML Encoding: + NETCONF XML Example: 2007-09-01T10:00:00Z so-1/2/3.0 up + down + The "notification" statement is covered in Section 7.14. 5. Language Concepts 5.1. Modules and Submodules The module is the base unit of definition in YANG. A module defines a single data model. A module can define a complete, cohesive model, or augment an existing data model with additional nodes. @@ -1066,29 +1063,29 @@ The "notification" statement is covered in Section 7.14. 5. Language Concepts 5.1. Modules and Submodules The module is the base unit of definition in YANG. A module defines a single data model. A module can define a complete, cohesive model, or augment an existing data model with additional nodes. - Submodule are partial modules that contribute definitions to a + 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. + standard or other enterprise modules, e.g., by using the enterprise + or organization name as a prefix. 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: @@ -1104,76 +1101,78 @@ submodule. There MUST NOT be any circular chains of imports or includes. For example, if submodule "a" includes submodule "b", "b" cannot include "a". When a definition in an external module is referenced, a locally defined prefix MUST be used, followed by ":", and then the external identifier. References to definitions in the local module MAY use the prefix notation. Since built-in data types do not belong to any - module and have no prefix, references to built-in data types (e.g. + module and have no prefix, references to built-in data types (e.g., int32) cannot use the prefix notation. 5.1.1. Import and Include by Revision Published modules evolve independently over time. In order to allow for this evolution, modules need to be imported using specific revisions. When a module is written, it uses the current revisions of other modules, based on what is available at the time. As future revisions of the imported modules are published, the importing module is unaffected and its contents are unchanged. When the author of the module is prepared to move to the most recently published revision of an imported module, the module is republished with an updated import - statement. By republishing with the new revision, the author is - explicitly indicating their acceptance of any changes in the imported + statement. By republishing with the new revision, the authors + explicitly indicate their acceptance of any changes in the imported module. For submodules, the issue is related but simpler. A module or submodule that includes submodules need to specify the revision of the included submodules. If a submodule changes, any module or submodule that includes it needs to be updated. For example, module "b" imports module "a". module a { revision 2008-01-01 { ... } grouping a { leaf eh { .... } } } module b { import a { - prefix a; + prefix p; revision-date 2008-01-01; } container bee { - uses a:a; + uses p:a; } } When the author of "a" publishes a new revision, the changes may not be acceptable to the author of "b". If the new revision is acceptable, the author of "b" can republish with an updated revision in the import statement. 5.1.2. Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may have more than one top-level node. Models that have multiple top- level nodes are sometimes convenient, and are supported by YANG. NETCONF is capable of carrying any XML content as the payload in the - element. The top-level nodes of YANG modules are encoded as - child elements within the element. + and elements. The top-level nodes of YANG modules + are encoded as child elements within these elements. This + encapsulation guarantees that the corresponding NETCONF PDUs are + always well-formed XML documents. For example: module my-config { namespace "http://example.com/schema/config"; prefix "co"; container system { ... } container routing { ... } } @@ -1194,21 +1193,21 @@ 5.2. File Layout YANG modules and submodules are typically stored in files, one module - or submodule per file. The name of the file SHOULD be on the form: + or submodule per file. The name of the file SHOULD be of the form: module-or-submodule-name ['.' revision-date] ( '.yang' / '.yin' ) YANG compilers can find imported modules and included submodules via this convention. While the YANG language defines modules, tools may compile submodules independently for performance and manageability reasons. Many errors and warnings that cannot be detected during submodule compilation may be delayed until the submodules are linked into a cohesive module. @@ -1216,31 +1215,32 @@ All YANG definitions are specified within a module that is bound to a particular XML Namespace [XML-NAMES], which is a globally unique URI [RFC3986]. A NETCONF client or server uses the namespace during XML encoding of data. Namespaces for modules published in RFC streams MUST be assigned by IANA, see Section 14. Namespaces for private modules are assigned by the organization - owning the module without a central registry. It is RECOMMENDED to - choose namespaces that will have a low probability of colliding with - standard or other enterprise modules, e.g. by using the enterprise or - organization name in the namespace. + owning the module without a central registry. Namespace URIs MUST be + choosen so they cannot collide with standard or other enterprise + namespaces, for example by using the enterprise or organization name + in the namespace. The "namespace" statement is covered in Section 7.1.3. 5.3.1. YANG XML Namespace - YANG defines its own XML namespace for NETCONF - operations. This namespace is "urn:ietf:params:xml:ns:yang:1". + YANG defines an XML namespace for NETCONF operations + and content. This namespace is + "urn:ietf:params:xml:ns:yang:1". 5.4. Resolving Grouping, Type, and Identity Names Grouping, type, and identity names are resolved in the context in which they are defined, rather than the context in which they are used. Users of groupings, typedefs, and identities are not required to import modules or include submodules to satisfy all references made by the original definition. This behaves like static scoping in a conventional programming language. @@ -1279,21 +1279,21 @@ 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. 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 into + reduce the utility of the model and increase fragility of applications that use it. YANG modelers have three mechanisms for conformance: o the basic behavior of the model o optional features that are part of the model o deviations from the model @@ -1313,31 +1313,31 @@ conditional, based on the device. The device controls whether these conditional portions of the model are supported or valid for that particular device. For example, a syslog data model may choose to include the ability to save logs locally, but the modeler will realize that this is only possible if the device has local storage. If there is no local storage, an application should not tell the device to save logs. YANG supports this conditional mechanism using a construct called - "features". Features give the modeler a mechanism for making - portions of the module conditional in a manner that is controlled by - the device. The model can express constructs which are not - universally present in all devices. These features are included in - the model definition, allowing a consistent view and allowing - applications to learn which features are supported and tailor their - behavior to the device. + "feature". Features give the modeler a mechanism for making portions + of the module conditional in a manner that is controlled by the + device. The model can express constructs which are not universally + present in all devices. These features are included in the model + definition, allowing a consistent view and allowing applications to + learn which features are supported and tailor their behavior to the + device. A module may declare any number of features, identified by simple strings, and may make portions of the module optional based on those - feature. If the device supports a feature, then the corresponding + features. If the device supports a feature, then the corresponding portions of the module are valid for that device. If the device doesn't support the feature, those parts of the module are not valid, and applications should behave accordingly. Features are defined using the "feature" statement. Definitions in the module that are conditional to the feature are noted by the "if-feature" statement with the name of the feature as its argument. Further details are available in Section 7.18.1. @@ -1383,20 +1383,22 @@ Where "revision-date" is the revision of the module (see Section 7.1.9) that the NETCONF server implements, "module-name" is the name of module as it appears in the "module" statement (see 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 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. @@ -1439,48 +1441,20 @@ http://example.com/syslog?module=syslog&deviations=my-devs http://example.com/my-deviations?module=my-devs -5.6.5. Mapping to the NETCONF Schema Discovery Mechanism - - +--------------------------------------------------------------+ - | Open Question | - +--------------------------------------------------------------+ - | Move this section to the monitoring spec? | - +--------------------------------------------------------------+ - - The NETCONF Schema Discovery process is defined in [TBD]. It - specifies a "schema" list where each entry is identified by - "identifier", "version", and "format". - - All revisions of all YANG modules and submodules supported by a - device SHOULD be present in the "schema" list, including modules with - only typedefs and groupings. - - The following table specifies how the fields in the "schema" list are - used for YANG modules and submodules: - - identifier - the name of the module or submodule. - version - the supported YANG revision string. - format - the string "YANG". - namespace - the module's namespace. if the list entry describes a - submodule, this field contains the namespace of the - module to which the submodule belongs. - - Note that the format is "YANG", even if the YIN syntax is used. - 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. @@ -1503,51 +1477,51 @@ A token in YANG is either a keyword, a string, ";", "{", or "}". A string can be quoted or unquoted. A keyword is either one of the core YANG keywords defined in this document, or a prefix identifier, followed by ":", followed by a language extension keyword. Keywords are case sensitive. See Section 6.2 for a formal definition of identifiers. 6.1.3. Quoting - If a string contains any whitespace characters, a semicolon (";"), + 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 - whitespace which is 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 same column of the double quote character. + 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 + layout in the YANG file, this leading whitespace is stripped from the + string, up to at most the column of the double quote character. - If the double quoted string contains whitespace before a line break, - this trailing whitespace is stripped from the string. + 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 can not occur in a - single quoted string, even when preceded by a backslash. - - If a quoted string is followed by a plus character ("+"), followed by - another quoted string, the two strings are concatenated into one - quoted string, allowing multiple concatenations to build one quoted - string. Whitespace trimming of double quoted strings is done before - concatenation. + 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 character that immediately follows the backslash: \n new line \t a tab character \" a double quote \\ a single backslash + If a quoted string is followed by a plus character ("+"), followed by + another quoted string, the two strings are concatenated into one + string, allowing multiple concatenations to build one string. + Whitespace trimming and substition of backslash-escaped characters in + double quoted strings is done before concatenation. + 6.1.3.1. Quoting Examples The following strings are equivalent: hello "hello" 'hello' "hel" + "lo" 'hel' + "lo" @@ -1578,55 +1552,60 @@ letter or an underscore character, followed by zero or more ASCII letters, digits, underscore characters, hyphens, and dots. Implementations MUST support identifiers up to 64 characters in length. Identifiers are case sensitive. The identifier syntax is formally defined by the rule "identifier" in Section 12. Identifiers can be specified as quoted or unquoted strings. 6.2.1. Identifiers and their namespaces Each identifier is valid in a namespace which depends on the type of - the YANG item being defined: + the YANG item being defined. All identifiers defined in a namespace + MUST be unique. o All module and submodule names share the same global module identifier namespace. o All extension names defined in a module and its submodules share the same extension identifier namespace. o All feature names defined in a module and its submodules share the same feature identifier namespace. 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 the parent node - or module. + 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 grouping identifier - namespace. This namespace is scoped to the parent node or module. + 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 leafs, leaf-lists, lists, containers, choices, rpcs, and - notifications 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. + 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. o All cases within a choice share the same case identifier namespace. This namespace is scoped to the parent choice node. - All identifiers defined in a namespace MUST be unique. - 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 either by a semicolon (";") or a block of substatements enclosed within braces ("{ }"): statement = keyword [argument] (";" / "{" *statement "}") @@ -1652,30 +1631,59 @@ 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, - with the namespace of the current module defined as the null - namespace. References to identifiers in external modules MUST be - qualified with appropriate prefixes, and references to the current - module and its submodules MAY use a prefix. + 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. 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 root node children. + 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. + + o Elements without a namespace prefix refer to nodes in the + namespace of the current module. + + 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 context node varies with the YANG XPath expression, and is + specified where the YANG statement with the XPath expression is + defined. 7. YANG Statements The following sections describe all of the YANG core statements. Note that even a statement which does not have any substatements defined in core YANG can have vendor-specific extensions as substatements. For example, the "description" statement does not have any substatements defined in core YANG, but the following is legal: @@ -1690,22 +1698,22 @@ statements which belong to the module together. The "module" statement's argument is the name of the module, followed by a block of substatements that hold detailed module information. The module name follows the rules for identifiers in Section 6.2. Names of modules published in RFC streams MUST be assigned by IANA, see Section 14. Private module names are assigned by the organization owning the module without a central registry. It is RECOMMENDED to choose - submodule names that will have a low probability of colliding with - standard or other enterprise modules and submodules, e.g. by using + module names that will have a low probability of colliding with + standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix. A module SHOULD have the following layout: module { // header information @@ -1734,130 +1742,146 @@ | anyxml | 7.10 | 0..n | | augment | 7.15 | 0..n | | choice | 7.9 | 0..n | | contact | 7.1.8 | 0..1 | | container | 7.5 | 0..n | | description | 7.19.3 | 0..1 | | deviation | 7.18.3 | 0..n | | extension | 7.17 | 0..n | | feature | 7.18.1 | 0..n | | grouping | 7.11 | 0..n | + | identity | 7.16 | 0..n | | import | 7.1.5 | 0..n | | include | 7.1.6 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | namespace | 7.1.3 | 1 | | notification | 7.14 | 0..n | | organization | 7.1.7 | 0..1 | | prefix | 7.1.4 | 1 | | reference | 7.19.4 | 0..1 | | revision | 7.1.9 | 0..n | | rpc | 7.13 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | | yang-version | 7.1.2 | 0..1 | +--------------+---------+-------------+ 7.1.2. The yang-version Statement - The "yang-version" statement specifies which version of the YANG - language was used in developing the module. The statement's argument - contains value "1", which is the current yang version and the default - value. + 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 for all XML - elements defined by the module. Its argument is the URI of the - namespace. + 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. 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 + module, e.g., "if:ifName". A prefix follows the same rules as an identifier (see Section 6.2). When used inside the "module" statement, the "prefix" statement defines the prefix to be used when this module is imported. To improve readability of the NETCONF XML, a NETCONF client or server which generates XML or XPath that use prefixes, the prefix defined by a module SHOULD be used, unless there is a conflict. When used inside the "import" statement, the "prefix" statement defines the prefix to be used when accessing definitions inside the imported module. When a reference to an identifier from the imported - module is used, the prefix string for the module from which objects - are being imported is used in combination with a colon (":") and the - identifier, e.g. "if:ifIndex". To improve readability of YANG - modules, the prefix defined by a module SHOULD be used when the - module is imported, unless there is a conflict. + module is used, the prefix string for the imported module is used in + combination with a colon (":") and the identifier, e.g., "if: + ifIndex". To improve readability of YANG modules, the prefix defined + by a module SHOULD be used when the module is imported, unless there + is a conflict. All prefixes, including the prefix for the module itself MUST be unique within the module or submodule. 7.1.5. The import Statement The "import" statement makes definitions from one module available inside another module or submodule. The argument is the name of the module to import, and the statement is followed by a block of - substatements that holds detailed import information. + substatements that holds detailed import information. When a module + is imported, the importing module may: + + o use any grouping and typedef defined at the top-level in the + imported module or its submodules + + o use any extension, feature, and identity defined in the imported + module or its submodules + + o use any node in the imported module's schema tree in augment, + must, path, and when statements The mandatory "prefix" substatement assigns a prefix for the imported module which is scoped to the importing module or submodule. Multiple "import" statements may be specified to import from different modules. When the optional "revision-date" substatement is present, any typedef, grouping, extension, feature, and identity referenced by definitions in the local module are taken from the specified revision - of the imported module. + of the imported module. Otherwise, it is undefined from which + revision of the module they are taken. - It is an error to import multiple revisions of the same module. + Multiple revisions of the same module MUST NOT be imported. The import's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | prefix | 7.1.4 | 1 | | revision-date | 7.1.5.1 | 0..1 | +---------------+---------+-------------+ 7.1.5.1. The import's revision-date Statement The import's "revision-date" statement is used to specify the exact version of the module to import. The "revision-date" statement MUST match the most recent "revision" statement in the imported module. 7.1.6. The include Statement The "include" statement is used to make content from a submodule - available to the module. The argument is an identifier which is the + available to that submodule's parent module, or to another submodule + of that parent module. The argument is an identifier which is the name of the submodule to include. Modules are only allowed to include submodules that belong to that module, as defined by the - "belongs-to" statement (see Section 7.2.2). + "belongs-to" statement (see Section 7.2.2). Submodules are only + allowed to include other submodules belonging to the same module. When a module includes a submodule, it incorporates the contents of the submodule into the node hierarchy of the module. When a submodule includes another submodule, the target submodule's definitions are made available to the current submodule. When the optional "revision-date" is present, the specified revision - of the submodule is included in the module. + of the submodule is included in the module. Otherwise, it is + undefined which revision of the submodule is included. - It is an error to include multiple revisions of the same submodule. + Multiple revisions of the same submodule MUST NOT be included. The includes's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | revision-date | 7.1.5.1 | 0..1 | +---------------+---------+-------------+ 7.1.7. The organization Statement @@ -1875,22 +1899,22 @@ to whom technical queries concerning this module should be sent. 7.1.9. The revision Statement The "revision" statement specifies the editorial revision history of the module, including the initial revision. A series of revisions statements detail the changes in the module's definition. The argument is a date string in the format "YYYY-MM-DD", followed by a block of substatements that holds detailed revision information. A module SHOULD have at least one initial "revision" statement. For - every editorial change, a new one SHOULD be added in front of the - revisions sequence, so that all revisions are in reverse + 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 | +--------------+---------+-------------+ @@ -1908,56 +1932,55 @@ organization "ACME Inc."; contact "Joe L. User ACME, Inc. 42 Anywhere Drive Nowhere, CA 95134 USA - Phone: +1 800 555 0815 + Phone: +1 800 555 0100 EMail: joe@acme.example.com"; description "The module for entities implementing the ACME protocol."; revision "2007-06-09" { description "Initial revision."; } // definitions follows... } 7.2. The submodule Statement While the primary unit in YANG is a module, a YANG module can itself - be constructed out of several submodules. Submodules allows a module + be constructed out of several submodules. Submodules allow a module designer to split a complex model into several pieces where all the submodules contribute to a single namespace, which is defined by the module that includes the submodules. - The "submodule" statement is used to give the submodule a name, and - to group all statements which belong to the submodule together. - - The "submodule" statement, which MUST be present at most once, takes - as an argument an identifier which is the name of the submodule, + The "submodule" statement defines the submodule's name, and groups + all statements which belong to the submodule together. The + "submodule" statement's argument is the name of the submodule, followed by a block of substatements that hold detailed submodule - information. + information. The submodule name follows the rules for identifiers in + Section 6.2. Names of submodules published in RFC streams MUST be assigned by IANA, see Section 14. Private submodule names are assigned by the organization owning the submodule without a central registry. It is RECOMMENDED to choose submodule names that will have a low probability of colliding with - standard or other enterprise modules and submodules, e.g. by using + standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix. A submodule SHOULD have the following layout: submodule { // module identification @@ -1987,20 +2010,21 @@ | augment | 7.15 | 0..n | | belongs-to | 7.2.2 | 1 | | choice | 7.9 | 0..n | | contact | 7.1.8 | 0..1 | | container | 7.5 | 0..n | | description | 7.19.3 | 0..1 | | deviation | 7.18.3 | 0..n | | extension | 7.17 | 0..n | | feature | 7.18.1 | 0..n | | grouping | 7.11 | 0..n | + | identity | 7.16 | 0..n | | import | 7.1.5 | 0..n | | include | 7.1.6 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | notification | 7.14 | 0..n | | organization | 7.1.7 | 0..1 | | reference | 7.19.4 | 0..1 | | revision | 7.1.9 | 0..n | | rpc | 7.13 | 0..n | @@ -2045,21 +2069,21 @@ organization "ACME Inc."; contact "Joe L. User ACME, Inc. 42 Anywhere Drive Nowhere, CA 95134 USA - Phone: +1 800 555 0815 + Phone: +1 800 555 0100 EMail: joe@acme.example.com"; description "This submodule defines common ACME types."; revision "2007-06-09" { description "Initial revision."; } // definitions follows... @@ -2129,36 +2153,37 @@ } 7.4. The type Statement The "type" statement takes as an argument a string which is the name of a YANG built-in type (see Section 9) or a derived type (see Section 7.3), followed by an optional block of substatements that are used to put further restrictions on the type. The restrictions that can be applied depend on the type being - restricted. The restriction statements are described in subsections - for each built-in type in Section 9. + restricted. The restriction statements for all built-in types are + described in the subsections of Section 9. 7.4.1. The type's Substatements - +--------------+---------+-------------+ + +------------------+---------+-------------+ | substatement | section | cardinality | - +--------------+---------+-------------+ + +------------------+---------+-------------+ | bit | 9.7.4 | 0..n | | enum | 9.6.4 | 0..n | | length | 9.4.4 | 0..1 | | path | 9.9.2 | 0..1 | | pattern | 9.4.6 | 0..n | | range | 9.2.4 | 0..1 | + | require-instance | 9.13.2 | 0..1 | | type | 7.4 | 0..n | - +--------------+---------+-------------+ + +------------------+---------+-------------+ 7.5. The container Statement The "container" statement is used to define an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed container information. A container node does not have a value, but it has a list of child nodes in the data tree. The child nodes are defined in the @@ -2230,44 +2255,33 @@ 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. All such constraints MUST evaluate to true for the data to be valid. The XPath expression is conceptually evaluated in the following - context: + 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. - 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. - - o Elements without a namespace refer to nodes in the current module. - - 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. - - The accessible data tree depends on the context node: + The accessible tree depends on the context node: o If the context node represents configuration, the tree is the data - in one of the datastores , , or . - The XPath root node has all top-level configuration data nodes in - all modules as children. + 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 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. @@ -2346,82 +2360,68 @@ If a container has the "presence" statement, the container's existence in the data tree carries some meaning. Otherwise, the container is used to give some structure to the data, and it carries no meaning by itself. See Section 7.5.1 for additional information. 7.5.6. The container's Child Node Statements Within a container, the "container", "leaf", "list", "leaf-list", - "uses", and "choice" statements can be used to define child nodes to - the container. + "uses", "choice", and "anyxml" statements can be used to define child + nodes to the container. -7.5.7. XML Encoding Rules +7.5.7. XML Mapping Rules A container node is encoded as an XML element. The element's name is the container's identifier, and its XML namespace is the module's XML namespace. The container's child nodes are encoded as subelements to the container element. If the container defines RPC input or output parameters, the subelements are encoded in the same order as they are defined within the container statement. Otherwise, the subelements are encoded in any order. A NETCONF server that replies to a or request MAY choose not to send a container element if the container node does not have the "presence" statement and no child nodes exist. Thus, a client that receives an for a or request, must be prepared to handle the case that a container node without a presence statement is not present in the XML. 7.5.8. NETCONF Operations - When a NETCONF server processes an request, the - elements of procedure for the container node are: - - If the operation is "merge" the node is created if it does not - exist. - - If the operation is "replace" and the node exists, all child nodes - not present in the XML are deleted, and child nodes present in the - XML but not present in the datastore are created. - - 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. - - If the container has a "presence" statement, it MAY be implicitly - created if it does not exist, even if the operation is "none". + Containers can be created, deleted, replaced and modified through + , by using the "operation" attribute (See [RFC4741], + section 7.2) in the container's XML element. - If a container has a "presence" statement and the last child node - is deleted, the NETCONF server MAY delete the container. + If a container does not have a "presence" statement and the last + child node is deleted, the NETCONF server MAY delete the container. 7.5.9. Usage Example Given the following container definition: container system { description "Contains various system parameters"; container services { description "Configure externally available services"; container "ssh" { presence "Enables SSH"; description "SSH service specific configuration"; // more leafs, containers and stuff here... } } } - A corresponding XML encoding would look like this: + A corresponding XML instance example: Since the element is present, ssh is enabled. To delete a container with an : @@ -2508,28 +2508,30 @@ 7.6.4. 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 this ancestor is a case node, the leaf MUST exist if any other - node from the case exists. + o If no such ancestor exists, the leaf MUST exist. + + o Otherwise, if this ancestor is a case node, the leaf MUST exist if + any node from the case exists. o Otherwise, the leaf MUST exist if the ancestor node exists. This constraint is enforced according to the rules in Section 8. -7.6.5. XML Encoding Rules +7.6.5. 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 @@ -2553,29 +2555,30 @@ 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 - Given the following leaf statement: + 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" } - A corresponding XML encoding: + A corresponding XML instance example: 2022 To create a leaf with an : @@ -2604,27 +2607,27 @@ The values in a leaf-list MUST be unique. Conceptually, the values in the data tree are always in the canonical form (see Section 9.1). If the type referenced by the leaf-list has a default value, it has no effect in the leaf-list. 7.7.1. Ordering - YANG supports two styles for ordering the entries within a list. In - many lists, the order of list entries does not impact the - implementation of the list's configuration, and the device is free to - sort the list entries in any reasonable order. The "description" - string for the list may suggest an order. YANG calls this style of - list "system ordered" and they are indicated with the statement - "ordered-by system". + YANG supports two styles for ordering the entries within lists and + leaf-lists. In many lists, the order of list entries does not impact + the implementation of the list's configuration, and the device is + free to sort the list entries in any reasonable order. The + "description" string for the list may suggest an order. YANG calls + this style of list "system ordered" and they are indicated with the + statement "ordered-by system". For example, a list of valid users would typically be sorted alphabetically, since the order in which the users appeared in the configuration would not impact the creation of those users' accounts. In the other style of lists, the order of list entries matters for the implementation of the list's configuration and the user is responsible for ordering the entries, while the device maintains that order. YANG calls this style of list "user ordered" and they are indicated with the statement "ordered-by user". @@ -2660,21 +2663,21 @@ | status | 7.19.2 | 0..1 | | type | 7.4 | 1 | | units | 7.3.3 | 0..1 | | when | 7.19.5 | 0..1 | +--------------+---------+-------------+ 7.7.3. The min-elements Statement The "min-elements" statement, which is optional, takes as an argument a non-negative integer which puts a constraint on valid list entries. - A valid leaf-list or list MUST have least min-elements entries. + A valid leaf-list or list MUST have at least min-elements entries. If no "min-elements" statement is present, it defaults to zero. The behavior of the constraint depends on the type of the leaf-list's or list's closest ancestor node in the schema tree which is not a non-presence container (see Section 7.5.1): o If this ancestor is a case node, the constraint is enforced if any other node from the case exists. @@ -2707,32 +2710,32 @@ output parameters, or notification content. See Section 7.7.1 for additional information. 7.7.5.1. ordered-by system The entries in the list are sorted according to an unspecified order. Thus an implementation is free to sort the entries in the most appropriate order. An implementation SHOULD use the same order for the same data, regardless of how the data were created. Using a - deterministic order will makes comparisons possible using simple - tools like "diff". + deterministic order will make comparisons possible using simple tools + like "diff". This is the default order. 7.7.5.2. ordered-by user The entries in the list are sorted according to an order defined by the user. This order is controlled by using special XML attributes in the request. See Section 7.7.7 for details. -7.7.6. XML Encoding Rules +7.7.6. XML Mapping Rules A leaf-list node is encoded as a series of XML elements. Each element's name is the leaf-list's identifier, and its XML namespace is the module's XML namespace. The value of the leaf-list node is encoded to XML according to the type, and sent as character data in the element. See Section 7.7.8 for an example. @@ -2750,20 +2753,24 @@ entry or move an existing one. 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 + 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 created if it does not exist. @@ -2773,21 +2780,21 @@ If the operation is "delete" the entry is deleted from the leaf- list if it exists. 7.7.8. Usage Example leaf-list allow-user { type string; description "A list of user name patterns to allow"; } - A corresponding XML encoding: + A corresponding XML instance example: alice bob To create a new element in the list: @@ -2840,21 +2847,22 @@ 7.8. The list Statement The "list" statement is used to define interior nodes in the schema tree. A list node may exist in multiple instances in the data tree. Each such instance is known as a list entry. The "list" statement takes one argument which is an identifier, followed by a block of substatements that holds detailed list information. - A list entry is uniquely identified by the values of the list's keys. + A list entry is uniquely identified by the values of the list's keys, + if defined. A list is similar to a table where each list entry is a row in the table. 7.8.1. The list's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | @@ -2880,21 +2888,22 @@ | when | 7.19.5 | 0..1 | +--------------+---------+-------------+ 7.8.2. The list's key Statement The "key" statement, which MUST be present if the list represents configuration, and MAY be present otherwise, takes as an argument a string which specifies a space separated list of leaf identifiers of this list. A leaf identifier MUST NOT appear more than once in the key. Each such leaf identifier MUST refer to a child leaf of the - list. + list. The leafs can be defined directly in substatements to the + list, or in groupings used in the list. The combined values of all the leafs specified in the key are used to uniquely identify a list entry. All key leafs MUST be given values when a list entry is created. Thus, any default values in the key leafs or their types are ignored. It also implies that any mandatory statement in the key leafs are ignored. A leaf that is part of the key can be of any built-in or derived type, except it MUST NOT be the built-in type "empty". @@ -2972,24 +2981,24 @@ ftp 192.0.2.1 7.8.4. The list's Child Node Statements Within a list, the "container", "leaf", "list", "leaf-list", "uses", - and "choice" statements can be used to define child nodes to the - list. + "choice", and "anyxml" statements can be used to define child nodes + to the list. -7.8.5. XML Encoding Rules +7.8.5. XML Mapping Rules A list is encoded as a series of XML elements, one for each entry in the list. Each element's name is the list's identifier, and its XML namespace is the module's XML namespace. The list's key nodes are encoded as subelements to the list's identifier element, in the same order as they are defined within the key statement. The rest of the list's child nodes are encoded as subelements to the @@ -3014,20 +3023,24 @@ 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, + 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: list user { key "name"; @@ -3038,21 +3051,21 @@ type string; } leaf type { type string; } leaf full-name { type string; } } - A corresponding XML encoding: + A corresponding XML instance example: fred admin Fred Flintstone To create a new user "barney": operations - Since only one of the choices cases can be valid at any time, the + Since only one of the choice's cases can be valid at any time, the creation of a node from one case implicitly deletes all nodes from all other cases. If an operation creates a node, the NETCONF server will delete any existing nodes that are defined in other cases inside the choice. 7.9.7. Usage Example Given the following choice: container protocol { @@ -3364,21 +3377,21 @@ } } case b { leaf tcp { type empty; } } } } - A corresponding XML encoding: + A corresponding XML instance example: To change the protocol from tcp to udp: @@ -3396,63 +3409,65 @@ 7.10. The anyxml Statement The "anyxml" statement defines an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed anyxml information. The anyxml statement is used to represent an unknown chunk of XML. - No restrictions are placed on the XML. This can be useful in e.g. - RPC replies. An example is the parameter in the + No restrictions are placed on the XML. This can be useful in for + example RPC replies. An example is the parameter in the operation. An anyxml node cannot be augmented. Since the use of anyxml limits the manipulation of the content, it is RECOMMENDED that the anyxml statement not be used to represent configuration data. + An anyxml node exists in zero or one instances in the data tree. + 7.10.1. The anyxml's Substatements +--------------+---------+-------------+ | 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 | | 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 Encoding Rules +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 namespace. The value of the anyxml node is encoded as XML content of this element. Note that any prefixes used in the encoding are local to each instance encoding. This means that the same XML may be encoded differently by different implementations. 7.10.3. NETCONF operations An anyxml node is treated as an opaque chunk of data. This data can be modified in its entirety only. - Any "operation" attributes within the XML value of an anyxml node are - ignored by the NETCONF server. + Any "operation" attributes present on subelements of an anyxml node + are ignored by the NETCONF server. When a NETCONF server processes an request, the elements of procedure for the anyxml node are: If the operation is "merge", the node is created if it does not exist, and its value is set to the XML content of the anyxml node 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 XML content of the anyxml node @@ -3500,26 +3515,26 @@ Once a grouping is defined, it can be referenced in a "uses" statement (see Section 7.12). A grouping MUST NOT reference itself, neither directly nor indirectly through a chain of other groupings. If the grouping is defined at the top level of a YANG module or submodule, the grouping's identifier MUST be unique within the module. A grouping is more than just a mechanism for textual substitution, - but defines a collection of nodes. References from inside the - grouping are relative to the scope in which the grouping is defined, - not where it is used. Prefix mappings, type names, grouping names, - and extension usage are evaluated in the hierarchy where the grouping - statement appears. For extensions, this means that extensions are - applied to the grouping node, not the use node. + but defines a collection of nodes. Identifiers appearing inside the + grouping are resolved relative to the scope in which the grouping is + defined, not where it is used. Prefix mappings, type names, grouping + names, and extension usage are evaluated in the hierarchy where the + grouping statement appears. For extensions, this means that + extensions are applied to the grouping node, not the uses node. 7.11.1. The grouping'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 | @@ -3549,24 +3564,24 @@ } } 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 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. + 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. 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 | @@ -3602,21 +3617,21 @@ o A leaf 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-list or list node may get a different "min-elements" or "max-elements" statement. -7.12.3. XML Encoding Rules +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. 7.12.4. Usage Example To use the "address" grouping defined in Section 7.11.2 in a definition of an HTTP server in some other module, we can do: @@ -3624,21 +3639,21 @@ prefix "acme"; } container http-server { leaf name { type string; } uses acme:address; } - A corresponding XML encoding: + A corresponding XML instance example: extern-web 192.0.2.1 80 If port 80 should be the default for the HTTP server, default can be added: @@ -3699,21 +3714,21 @@ | output | 7.13.3 | 0..1 | | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+ 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" defines nodes under the RPC's input node. + 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. 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. If a "config" statement is present for any node in the input tree, it is ignored. @@ -3734,21 +3749,21 @@ | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | +--------------+---------+-------------+ 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" defines nodes under the RPC's output node. + 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. If a "config" statement is present for any node in the output tree, it is ignored. @@ -3765,21 +3780,21 @@ | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | grouping | 7.11 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | +--------------+---------+-------------+ -7.13.4. XML Encoding Rules +7.13.4. XML Mapping Rules An rpc node is encoded as a child XML element to the element defined in [RFC4741]. The element's name is the rpc's identifier, and its XML namespace is the module's XML namespace. Input parameters are encoded as child XML elements to the rpc node's XML element, in the same order as they are defined within the input statement. If the RPC method invocation succeeded, and no output parameters are @@ -3797,50 +3812,51 @@ prefix "rock"; rpc rock-the-house { input { leaf zip-code { type string; } } } } - A corresponding XML encoding of the complete rpc and rpc-reply: + A corresponding XML instance example of the complete rpc and rpc- + reply: 27606-0100 7.14. The notification Statement The "notification" statement is used to define a NETCONF notification. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed notification - information. The notification "statement" defines a notification + 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 - server MUST internally use this default if the leaf is not present in + client MUST internally use this default if the leaf is not present in a NETCONF notification. 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 | +--------------+---------+-------------+ @@ -3852,52 +3868,48 @@ | 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 | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | +--------------+---------+-------------+ -7.14.2. XML Encoding Rules +7.14.2. XML Mapping Rules A notification node is encoded as a child XML element to the element defined in NETCONF Event Notifications [RFC5277]. The element's name is the notification's identifier, and its XML namespace is the module's XML namespace. - The notifications's child nodes are encoded as subelements to the - notification node's XML element, in the same order as they are - defined within the notification statement. - 7.14.3. Usage Example The following example defines a notification: module event { namespace "http://example.com/event"; prefix "ev"; notification event { leaf event-class { type string; } anyxml reporting-entity; leaf severity { type string; } } } - A corresponding XML encoding of the complete notification: + A corresponding XML instance example of the complete notification: 2008-07-08T00:01:00Z fault Ethernet0 major @@ -3908,68 +3920,74 @@ The "augment" statement allows a module or submodule to add to the schema tree defined in an external module, or the current module and its submodules, and to add to the nodes from a grouping in a "uses" statement. The argument is a string which identifies a node in the schema tree. This node is called the augment's target node. The target node MUST be either a container, list, choice, case, input, output, or notification node. It is augmented with the nodes defined in the substatements that follow the "augment" statement. - The argument string is a schema node identifier. The syntax is - formally defined by the rule "augment-arg" in Section 12. If the - "augment" statement is on the top-level in a module or submodule, the - absolute form (defined by the rule "absolute-schema-nodeid" in - Section 12) of a schema node identifier MUST be used. If the - "augment" statement is in a "uses" statement, the descendant form - (defined by the rule "descendant-schema-nodeid" in Section 12) MUST - be used. - - The syntax for a schema node identifier is a subset of the XPath - syntax. It is an absolute or relative XPath location path in - abbreviated syntax, where axes and predicates are not permitted. + The argument string is a schema node identifier. The syntax is a + subset of the XPath abbreviated syntax, formally defined by the rule + "augment-arg" in Section 12. If the "augment" statement is on the + top-level in a module or submodule, the absolute form (defined by the + rule "absolute-schema-nodeid" in Section 12) of a schema node + identifier MUST be used. If the "augment" statement is in a "uses" + statement, the descendant form (defined by the rule + "descendant-schema-nodeid" in Section 12) MUST be used. If the target node is a container, list, case, input, output, or notification node, the "container", "leaf", "list", "leaf-list", "uses", and "choice" statements can be used within the "augment" statement. - If the target node is a choice node, the "case" statement can be used - within the "augment" statement. + If the target node is a choice node, the "case" statement, or a case + shorthand statement (see Section 7.9.2) can be used within the + "augment" statement. If the target node is in another module, then nodes added by the augmentation MUST NOT be mandatory nodes (see Section 3.1). The augment statement MUST NOT add multiple nodes with the same name from the same module to the target node. + The "augment" 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 target node in the schema tree. + + o The accessible tree is made up of all nodes in the schema tree. + The XPath root node has all top-level schema nodes in all modules + as children. + 7.15.1. The augment's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | | case | 7.9.2 | 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 | +--------------+---------+-------------+ -7.15.2. XML Encoding Rules +7.15.2. XML Mapping Rules All data nodes defined in the "augment" statement are defined as XML elements in the XML namespace of the module where the "augment" is specified. When a node is augmented, the augmenting child nodes are encoded as subelements to the augmented node, in any order. 7.15.3. Usage Example @@ -3999,21 +4017,21 @@ import interface-module { prefix "if"; } augment "/if:interfaces/if:ifEntry" { when "if:ifType='ds0'"; leaf ds0ChannelNumber { type ChannelNumber; } } - A corresponding XML encoding: + A corresponding XML instance example: 1 Flintstone Inc Ethernet A562 ethernetCsmacd 1500 @@ -4028,21 +4046,21 @@ protocol definition: augment /ex:system/ex:protocol/ex:name { case c { leaf smtp { type empty; } } } - A corresponding XML encoding: + A corresponding XML instance example: or @@ -4273,20 +4291,24 @@ } } The "if-feature" statement can be used in many places within the YANG syntax. Definitions tagged with "if-feature" are ignored when the device does not support that feature. A feature MUST NOT reference itself, neither directly nor indirectly through a chain of other features. + If a feature is dependent on any other features (i.e., the feature + has one or more "if-feature" sub-statements), then all of features it + depends on MUST also be implemented by the device. + 7.18.1.1. The feature's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.19.3 | 0..1 | | if-feature | 7.18.2 | 0..n | | status | 7.19.2 | 0..1 | | reference | 7.19.4 | 0..1 | +--------------+---------+-------------+ @@ -4338,21 +4360,21 @@ Instead, YANG allows devices to document portions of the base module which are not supported or supported but with different syntax, by using the "deviation" statement. 7.18.3.1. The deviation's Substatements +--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ | description | 7.19.3 | 0..1 | - | deviate | 7.18.3.2 | 0..n | + | deviate | 7.18.3.2 | 1..n | | reference | 7.19.4 | 0..1 | +--------------+----------+-------------+ 7.18.3.2. The deviate Statement The "deviate" statement defines how the device's implementation of the target node deviates from its original definition. The argument is one of the strings "not-supported", "add", "replace", or "delete". The argument "not-supported" indicates that the target node is not @@ -4462,21 +4484,21 @@ The "status" statement takes as an argument one of the strings "current", "deprecated", or "obsolete". o "current" means that the definition is current and valid. o "deprecated" indicates an obsolete definition, but it permits new/ continued implementation in order to foster interoperability with older/existing implementations. o "obsolete" means the definition is obsolete and SHOULD NOT be - implemented and/or can be removed if previously implemented. + implemented and/or can be removed from implementations. If no status is specified, the default is "current". If a definition is "current", it MUST NOT reference a "deprecated" or "obsolete" definition within the same module. If a definition is "deprecated", it MUST NOT reference an "obsolete" definition within the same module. 7.19.3. The description Statement @@ -4499,55 +4521,44 @@ statement is only valid when the condition specified by the "when" statement is satisfied. The statement's argument is an XPath expression, which is used to formally specify this condition. If the XPath expression conceptually evaluates to "true" for a particular instance, then the node defined by the parent data definition statement is valid, otherwise it is not. See Section 8.3.2 for additional information. The XPath expression is conceptually evaluated in the following - context: + context, in addition to the definition in Section 6.4.1: o If the "when" statement is a child of an "augment" statement, then the context node is the augment's target node in the data tree, if the target node is a data node. Otherwise, the context node is the closest ancestor node to the target node which is also a data node. 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. - 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. - - o Elements without a namespace refer to nodes in the current module. - - 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. - - The accessible data tree depends on the context node: + The accessible tree depends on the context node: o If the context node represents configuration, the tree is the data - in one of the datastores , , or . - The XPath root node has all top-level configuration data nodes in - all modules as children. + 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 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. @@ -4596,21 +4607,21 @@ 8.2. Hierarchy of Constraints Conditions on parent nodes affect constraints on child nodes as a natural consequence of the hierarchy of nodes. "must", "mandatory", "min-elements", and "max-elements" constraints are not enforced if the parent node has a "when" or "if-feature" property that is not satisfied on the current device. In this example, the mandatory constraints on the "longitude" leaf is - not enforced on devices that lack the the "has-gps" feature: + not enforced on devices that lack the "has-gps" feature: container location { if-feature has-gps; leaf longitude { mandatory true; ... } } 8.3. Constraint Enforcement Model @@ -4629,21 +4640,21 @@ 8.3.1. Payload Parsing When content arrives in RPC payloads, it MUST be well-formed XML, following the hierarchy and content rules defined by the set of models the device implements. o If a leaf data value does not match the type constraints for the leaf, including those defined in the type's range, length, and pattern properties, the server MUST reply with an "invalid-value" error-tag in the rpc-error, and with the error-app-tag and error- - message assoicated with the constraint, if any exist. + message associated with the constraint, if any exist. o If all keys of a list entry are not present, the server MUST reply with a "missing-element" error-tag in the rpc-error. o If data for more than one case branch of a choice is present, the server MUST reply with a "bad-element" in the rpc-error. o If data for a node tagged with "if-feature" is present, and the feature is not supported by the device, the server MUST reply with an "unknown-element" error-tag in the rpc-error. @@ -4652,21 +4663,21 @@ condition evaluates to "false", the server MUST reply with an "unknown-element" error-tag in the rpc-error. o For insert handling, if the value for the attributes "before" and "after" are not valid for the type of the appropriate key leafs, the server MUST reply with a "bad-attribute" error-tag in the rpc- error. o If the attributes "before" and "after" appears in any element that is not a list whose "ordered-by" property is "user", the server - MUST reply with an "unkown-attribute" error-tag in the rpc-error. + MUST reply with an "unknown-attribute" error-tag in the rpc-error. 8.3.2. NETCONF Processing After the incoming data is parsed, the NETCONF server performs the operation by applying the data to the configuration datastore. During this processing the following errors MUST be detected: o Delete requests for non-existent data. @@ -4685,22 +4696,22 @@ "when" expression becomes false, then that node is deleted by the server. 8.3.3. Validation When datastore processing is complete, the final contents MUST obey all validation constraints. This validation processing is performed at differing time according to the datastore. If the datastore is or , these constraints MUST be enforced at the end of the or operation. If the - datastore is , the constraint enforcement is delayed until - a or operation. + datastore is , the constraint enforcement is delayed + until a or operation. o Any "must" constraints MUST evaluate to "true". o Any referential integrity constraints defined via the "path" statement MUST be satisfied. o Any "unique" constraints on lists MUST be satisfied. o The "min-elements" and "max-elements" constraints are enforced for lists and leaf-lists. @@ -4714,31 +4725,31 @@ Additional types may be defined, derived from those built-in types or from other derived types. Derived types may use subtyping to formally restrict the set of possible values. The different built-in types and their derived types allow different kinds of subtyping, namely length and regular expression restrictions of strings (Section 9.4.4, Section 9.4.6) and range restrictions of numeric types (Section 9.2.4). The lexicographic representation of a value of a certain type is used - in the XML encoding over NETCONF, and when specifying default values - in a YANG module. + in the NETCONF PDUs, and when specifying default values and numerical + ranges in YANG modules. 9.1. Canonical representation For most types, there is a single canonical representation of the type's values. Some types allow multiple lexicographic representations of the same value, for example the positive integer "17" can be represented as "+17" or "17". - When NETCONF servers sends data, it MUST be in the canonical form. + When a NETCONF server sends data, it MUST be in the canonical form. Some types have a lexical representation that depends on the XML context in which they occur. These types do not have a canonical form. 9.2. The Integer Built-in Types The integer built-in types are int8, int16, int32, int64, uint8, uint16, uint32, and uint64. They represent signed and unsigned integers of different sizes: @@ -4773,23 +4784,23 @@ For convenience, when specifying a default value for an integer in a YANG module, an alternative lexicographic representation can be used, which represents the value in a hexadecimal or octal notation. The hexadecimal notation consists of an optional sign ("+" or "-"), the characters "0x" followed a number of hexadecimal digits, where letters may be upper- or lowercase. The octal notation consists of an optional sign ("+" or "-"), the character "0" followed a number of octal digits. Note that if a default value in a YANG module has a leading zero - ("0"), it is interpreted as an octal number. In the XML encoding, an - integer is always interpreted as a decimal number, and leading zeros - are allowed. + ("0"), it is interpreted as an octal number. In the XML instance + documents, an integer is always interpreted as a decimal number, and + leading zeros are allowed. Examples: // legal values +4711 // legal positive value 4711 // legal positive value -123 // legal negative value 0xf00f // legal positive hexadecimal value -0xf // legal negative hexadecimal value 052 // legal positive octal value @@ -4859,53 +4870,79 @@ 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 + signed integer by a negative power of ten, i.e., expressible as "i x 10^-n" where i is an integer64 and n is an integer between 1 and 18, inclusively. 9.3.1. Lexicographic Representation A decimal64 value is lexicographically represented as an optional sign ("+" or "-"), followed by a sequence of decimal digits, - optionally followed by a period ('.') as a decmial indicator and a + optionally followed by a period ('.') as a decimal indicator and a sequence of decimal digits. If no sign is specified, "+" is assumed. 9.3.2. Canonical Form The canonical form of a positive decimal64 does not include the sign "+". The decimal point is required. Leading and trailing zeros are prohibited, subject to the rule that there MUST be at least one digit before and after the decimal point. The value zero is represented as "0.0". 9.3.3. Restrictions - A decmial64 type can be restricted with the "range" statement + A decimal64 type can be restricted with the "range" statement (Section 9.2.4). 9.3.4. The fraction-digits Statement The "fraction-digits" statement, which is a substatement to the "type" statement, MUST be present if the type is "decimal64". It takes as an argument an integer between 1 and 18, inclusively. It controls the size of the minimum difference between values of a decimal64 type, by restricting the value space to numbers that are expressible as "i x 10^-n" where n is the fraction-digits argument. + The following table lists the minimum and maximum value for each + fraction-digit value: + + +----------------+-----------------------+----------------------+ + | fraction-digit | min | max | + +----------------+-----------------------+----------------------+ + | 1 | -922337203685477580.8 | 922337203685477580.7 | + | 2 | -92233720368547758.08 | 92233720368547758.07 | + | 3 | -9223372036854775.808 | 9223372036854775.807 | + | 4 | -922337203685477.5808 | 922337203685477.5807 | + | 5 | -92233720368547.75808 | 92233720368547.75807 | + | 6 | -9223372036854.775808 | 9223372036854.775807 | + | 7 | -922337203685.4775808 | 922337203685.4775807 | + | 8 | -92233720368.54775808 | 92233720368.54775807 | + | 9 | -9223372036.854775808 | 9223372036.854775807 | + | 10 | -922337203.6854775808 | 922337203.6854775807 | + | 11 | -92233720.36854775808 | 92233720.36854775807 | + | 12 | -9223372.036854775808 | 9223372.036854775807 | + | 13 | -922337.2036854775808 | 922337.2036854775807 | + | 14 | -92233.72036854775808 | 92233.72036854775807 | + | 15 | -9223.372036854775808 | 9223.372036854775807 | + | 16 | -922.3372036854775808 | 922.3372036854775807 | + | 17 | -92.23372036854775808 | 92.23372036854775807 | + | 18 | -9.223372036854775808 | 9.223372036854775807 | + +----------------+-----------------------+----------------------+ + 9.3.5. Usage Example type decimal64 { fraction-digits 2; range "1 .. 3.14 | 10 | 20..max"; } 9.4. The string Built-in Type The string built-in type represents human readable strings in YANG. @@ -4914,21 +4951,21 @@ // any Unicode character, excluding the surrogate blocks, // FFFE, and FFFF. string = *char char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD / %x10000-10FFFF 9.4.1. Lexicographic Representation A string value is lexicographically represented as character data in - the XML encoding. + the XML instance documents. 9.4.2. Canonical Form The canonical form is the same as the lexicographical representation. No Unicode normalization is performed of string values. 9.4.3. Restrictions A string can be restricted with the "length" (Section 9.4.4) and "pattern" (Section 9.4.6) statements. @@ -4992,21 +5029,21 @@ 9.4.6. The pattern Statement The "pattern" statement, which is an optional substatement to the "type" statement, takes as an argument a regular expression string, as defined in [XSD-TYPES]. It is used to restrict the built-in type "string", or types derived from "string", to values that completely matches the pattern. If the type has multiple "pattern" statements, the expressions are - AND:ed together, i.e. all such expressions have to match. + ANDed together, i.e., all such expressions have to match. If a pattern restriction is applied to an already pattern restricted type, values must match all patterns in the base type, in addition to the new patterns. 9.4.6.1. The pattern's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ @@ -5025,33 +5062,37 @@ pattern "[0-9a-fA-F]*"; } the following strings match: AB // legal 9A00 // legal and the following strings do not match: - 00ABAB // illegal - xx00 // illegal + 00ABAB // illegal, too long + xx00 // illegal, bad characters 9.5. The boolean Built-in Type The boolean built-in type represents a boolean value. 9.5.1. Lexicographic Representation The lexicographical representation of a boolean value is the strings "true" and "false". -9.5.2. Restrictions +9.5.2. Canonical Form + + The canonical form is the same as the lexicographical representation. + +9.5.3. Restrictions A boolean cannot be restricted. 9.6. The enumeration Built-in Type The enumeration built-in type represents values from a set of assigned names. 9.6.1. Lexicographic Representation @@ -5089,21 +5130,22 @@ | reference | 7.19.4 | 0..1 | | status | 7.19.2 | 0..1 | | value | 9.6.4.2 | 0..1 | +--------------+---------+-------------+ 9.6.4.2. The value Statement The "value" statement, which is optional, is used to associate an integer value with the assigned name for the enum. This integer value MUST be in the range -2147483648 to 2147483647, and it MUST be - unique within the enumeration type. + unique within the enumeration type. The value is unused by YANG and + the XML encoding, but is carried as a convenience to implementors. If a value is not specified, then one will be automatically assigned. If the enum sub-statement is the first one defined, the assigned value is zero (0), otherwise the assigned value is one greater than the current highest enum value. If the current highest value is equal to 2147483647, then an enum value MUST be specified for enum sub-statements following the one with the current highest value. @@ -5111,27 +5153,34 @@ type enumeration { enum enabled { value 1; } enum disabled { value 2; } } + leaf myenum { type enumeration { enum zero; enum one; enum seven { value 7; } } + } + + The lexicographic representation of the leaf "myenum" with value + "seven" is: + + seven 9.7. The bits Built-in Type The bits built-in type represents a bit set. That is, a bits value is a set of flags identified by small integer position numbers starting at 0. Each bit number has an assigned name. 9.7.1. Restrictions A bits type cannot be restricted. @@ -5170,21 +5219,21 @@ | status | 7.19.2 | 0..1 | | position | 9.7.4.2 | 0..1 | +--------------+---------+-------------+ 9.7.4.2. The position Statement The "position" statement, which is optional, takes as an argument a non-negative integer value which specifies the bit's position within a hypothetical bit field. The position value MUST be in the range 0 to 4294967295, and it MUST be unique within the bits type. The value - is unused by YANG and the XML encoding, but is carried as a + is unused by YANG and the NETCONF PDUs, but is carried as a convenience to implementors. If a bit position is not specified, then one will be automatically assigned. If the bit sub-statement is the first one defined, the assigned value is zero (0), otherwise the assigned value is one greater than the current highest bit position. If the current highest bit position value is equal to 4294967295, then a position value MUST be specified for bit sub-statements following the one with the current highest position value. @@ -5208,111 +5257,114 @@ default "auto-sense-speed"; } The lexicographic representation of this leaf with bit values disable-nagle and 10-Mb-only set would be: disable-nagle 10-Mb-only 9.8. The binary Built-in Type - The binary built-in type represents any binary data, i.e. a sequence + The binary built-in type represents any binary data, i.e., a sequence of octets. 9.8.1. Restrictions A binary can be restricted with the "length" (Section 9.4.4) statement. The length of a binary value is the number of octets it contains. 9.8.2. Lexicographic Representation Binary values are encoded with the base64 encoding scheme [RFC4648]. 9.8.3. Canonical Form The canonical form of a binary value follow the rules in [RFC4648]. 9.9. The leafref Built-in Type The leafref type is used to reference a particular leaf instance in - the data tree. Its value is constrained to be the same as the value - of an existing leaf. + 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, and - the "require-instance" property (Section 9.9.3) is "true", 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. + 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. 9.9.1. Restrictions - A leafref can be restricted with the "require-instance" statement - (Section 9.9.3). + 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 node. The value of the - referring leaf MUST match the type of the referred leaf. + argument a string which MUST refer to a leaf or leaf-list node. - The syntax for a path argument is a subset of the XPath syntax. It - is an absolute or relative XPath location path in abbreviated syntax, - where axes are not permitted, and predicates are used only for - constraining the values for the key nodes for list entries. Each - predicate consists of exactly one equality test per key. + The syntax for a path argument is a subset of the XPath abbreviated + syntax. Predicates are used only for constraining the values for the + key nodes for list entries. Each predicate consists of exactly one + equality test per key, and multiple adjacent predicates MAY be + present if a list has multiple keys. The syntax is formally defined + by the rule "path-arg" in Section 12. The predicates are only used when more than one key reference is needed to uniquely identify a leaf instance. This occurs if a list has multiple keys, or a reference to a leaf other than the key in a list is needed. In these cases, multiple leafrefs are typically specified, and predicates are used to tie them together. - The syntax is formally defined by the rule "path-arg" in Section 12. + The "path" expression evaluates to a node set consisting of zero, one + or more nodes. If the leaf with the leafref type represents + configuration data, this node set MUST be non-empty. - For leafs of type "leafref", the "path" expression evaluates to a - node set consisting of zero, one or more nodes. If - "require-instance" is "true", the 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: -9.9.3. The require-instance Statement + o The context node is the node in the data tree for which the "path" + statement is defined. - The "require-instance" statement, which is a substatement to the - "type" statement, MAY be present if the type is "leafref" or - "instance-identifier". It takes as an argument the string "true" or - "false". If this statement is not present, it defaults to "true". + The accessible tree depends on the context node: - 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. + 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. -9.9.4. Lexicographic Representation + 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.5. Canonical Form +9.9.4. Canonical Form The canonical form of a leafref is the same as the canonical form of the leaf it references. -9.9.6. Usage Example +9.9.5. Usage Example With the following list: list interface { key "name"; leaf name { type string; } - leaf ifIndex { - type uint32; + leaf admin-status { + type admin-status; } list address { key "ip"; leaf ip { type yang:ip-address; } } } The following leafref refers to an existing interface: @@ -5346,67 +5399,107 @@ path "../../interface[name = current()/../ifname]" + "/address/ip"; } } } An example of a corresponding XML snippet: eth0 - 2 + up
192.0.2.1
192.0.2.2
lo - 1 + up
127.0.0.1
eth0
192.0.2.2
 + The following list uses a leafref for one of its keys. This is + similar to a foreign key in a relational database. + + list packet-filter { + key "if-name filter-id"; + leaf if-name { + type leafref { + path "/interfaces/interface/name"; + } + } + leaf filter-id { + type uint32; + } + ... + } + + An example of a corresponding XML anippet: + + + eth0 + up +
+ 192.0.2.1 +
+
+ 192.0.2.2 +
+ + + + eth0 + 1 + ... + + + eth0 + 2 + ... + + The following notification defines two leafrefs to refer to an - existing ifIndex: + existing admin-status: notification link-failure { leaf if-name { type leafref { path "/interfaces/interface/name"; } } - leaf index { + leaf admin-status { type leafref { path "/interfaces/interface[name = current()/../if-name]" - + "/ifIndex"; + + "/admin-status"; } } } An example of a corresponding XML notification: 2008-04-01T00:01:00Z eth0 - 2 + up 9.10. The identityref Built-in Type The identityref type is used to reference an existing identity (see Section 7.16). 9.10.1. Restrictions @@ -5525,20 +5618,23 @@ union. It takes as an argument a string which is the name of a member type. A member type can be of any built-in or derived type, except it MUST NOT be one of the built-in types "empty" or "leafref". When a string representing a union data type is validated, the string is validated against each member type, in the order they are specified in the type statement, until a match is found. + Any default values or units properties defined in the member types + are not inherited by the union type. + Example: type union { type int32; type enumeration { enum "unbounded"; } } 9.12.1. Restrictions @@ -5555,61 +5651,91 @@ The canonical form of a union value is the same as the canonical form of the member type of the value. 9.13. The instance-identifier Built-in Type The instance-identifier built-in type is used to uniquely identify a particular instance node in the data tree. The syntax for an instance-identifier is a subset of the XPath - syntax, which is used to uniquely identify a node in the data tree. - It is an absolute XPath location path in abbreviated syntax, where - axes are not permitted, and predicates are used only for specifying - the values for the key nodes for list entries, a value of a leaf-list + abbreviated syntax, formally defined by the rule + "instance-identifier" in Section 12. It is used to uniquely identify + 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.9.3) is "true", the node it refers to MUST also represent + (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 valid. This constraint is enforced according to the rules in Section 8. - The syntax is formally defined by the rule "instance-identifier" in - Section 12. + 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: + + 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 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.9.3). + statement (Section 9.13.2). -9.13.2. Lexicographic Representation +9.13.2. The require-instance Statement + + 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. + +9.13.3. Lexicographic Representation An instance-identifier value is lexicographically represented as a - string in the XML encoding. The namespace prefixes used in the - encoding MUST be declared in the XML namespace scope in the instance- - idenfitier's XML element. + string. All node names in an instance-identifier value MUST be + qualified with explicit namespace prefixes and these prefixes MUST be + declared in the XML namespace scope in the instance-identifier's XML + element. Any prefixes used in the encoding are local to each instance encoding. This means that the same instance-identifier may be encoded differently by different implementations. -9.13.3. Canonical Form +9.13.4. Canonical Form Since the lexicographic form depends on the XML context in which the value occurs, this type does not have a canonical form. -9.13.4. Usage Example +9.13.5. Usage Example The following are examples of instance identifiers: /* instance-identifier for a container */ /ex:system/ex:services/ex:ssh /* instance-identifier for a leaf */ /ex:system/ex:services/ex:ssh/ex:port /* instance-identifier for a list entry */ @@ -5630,39 +5756,39 @@ 10. Updating a Module As experience is gained with a module, it may be desirable to revise that module. However, changes are not allowed if they have any potential to cause interoperability problems between a client using an original specification and a server using an updated specification. For any published change, a new "revision" statement (Section 7.1.9) SHOULD be included in front of the existing revision statements. - Furthermore, any necessary changes MUST be applied to any meta + Furthermore, any necessary changes MUST be applied to any meta data statements, including the "organization" and "contact" statements (Section 7.1.7, Section 7.1.8). Note that definitions contained in a module are available to be imported by any other module, and are referenced in "import" statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, since all XML elements are encoded in the namespace. Obsolete definitions MUST NOT be removed from modules since their identifiers may still be referenced by other modules. A definition may be revised in any of the following ways: o An "enumeration" type may have new enums added, provided the old enums's values do not change. - o A "bits" type may have new bits added, provided the old bits's + 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. @@ -5680,21 +5806,21 @@ o A "description" statement may be added or clarified without changing the semantics of the definition. o New typedefs, groupings, rpc, notifications, extensions, features, and identities may be added. o New data definition statements may be added if they do not add mandatory nodes (Section 3.1) to existing nodes or at the top- level in a module or submodule, or if they are conditionally - dependent on a new feature (i.e. have a "if-feature" statement + dependent on a new feature (i.e., have a "if-feature" statement which refers to a new feature). o A new "case" statement may be added. o A node that represented state data may be changed to represent configuration, provided it is not mandatory (Section 3.1). o An "if-feature" statement may be removed, provided its node is not mandatory (Section 3.1). @@ -5709,25 +5835,25 @@ o Any set of data definition nodes may be replaced with another set of syntactically and semantically equivalent nodes. For example, a set of leafs may be replaced by a uses of a grouping with the same leafs. o A module may be split into a set of submodules, or submodule may be removed, provided the definitions in the module do not change in any other way than allowed here. - o The "prefix" statment may be changed, provided all local uses of + o The "prefix" statement may be changed, provided all local uses of the prefix also are changed. Otherwise, if the semantics of any previous definition are changed - (i.e. if a non-editorial change is made to any definition other than + (i.e., if a non-editorial change is made to any definition other than those specifically allowed above), then this MUST be achieved by a new definition with a new identifier. In statements which have any data definition statements as substatements, those data definition substatements MUST NOT be reordered. 11. YIN A YANG module can be specified in an alternative XML-based syntax @@ -5736,41 +5862,41 @@ The YANG and YIN formats contain equivalent information using different notations. The purpose of the YIN notation is to allow the user to translate YANG into YIN, use the rich set of XML based tools on the YIN format to transform, or filter the model information. Tools like XSLT or XML validators can be utilized. After this the model can be transformed back to the YANG format if needed, which provides a more concise and readable format. The mapping between YANG and YIN does not modify the information - content of the model. Comments and whitespaces are not preserved. + content of the model. Comments and whitespace are not preserved. 11.1. Formal YIN Definition There is a one-to-one correspondence between YANG keywords and YIN elements. The local name of a YIN element is identical to the corresponding YANG keyword. This means in particular that the document element (root) of a YIN document is always or . YIN elements corresponding to the core YANG keywords belong to the namespace whose associated URI is "urn:ietf:params:xml:ns:yang:yin:1". YIN elements corresponding to extension keywords belong to the namespace of the YANG module where the extension keyword is declared via the "extension" statement. The names of all YIN elements MUST be properly qualified with their namespaces specified above using the standard mechanisms of - [XML-NAMES], i.e. "xmlns" and "xmlns:xxx" attributes. + [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. The argument of a YANG statement is encoded in YIN either as an XML attribute or a subelement of the keyword element. Table 1 defines the encoding for the set of core YANG keywords. For extensions, the argument encoding is specified within the "extension" statement (see Section 7.17). The following rules hold for arguments of both core and extension statements: o If the argument is encoded as an attribute, this attribute has no namespace. @@ -6238,29 +6364,29 @@ [error-app-tag-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") error-message-stmt = error-message-keyword sep string stmtend error-app-tag-stmt = error-app-tag-keyword sep string stmtend min-elements-stmt = min-elements-keyword sep - min-value-arg-str stmtend; + min-value-arg-str stmtend min-value-arg-str = < a string which matches the rule min-value-arg > min-value-arg = non-negative-integer-value max-elements-stmt = max-elements-keyword sep - max-value-arg-str stmtend; + max-value-arg-str stmtend max-value-arg-str = < a string which matches the rule max-value-arg > max-value-arg = unbounded-keyword / positive-integer-value value-stmt = value-keyword sep integer-value stmtend grouping-stmt = grouping-keyword sep identifier-arg-str optsep (";" / @@ -6883,97 +7009,105 @@ WSP = SP / HTAB ; white space 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: +13.1. Error Message for Data that Violates a unique Statement If a NETCONF operation would result in configuration data where a unique constraint is invalidated, the following error is returned: Tag: operation-failed Error-app-tag: data-not-unique Error-info: : Contains an instance identifier which points to a leaf which invalidates the unique constraint. This element is present once for each leaf invalidating the unique constraint. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). -13.2. Error Message for Data that Violates a max-elements Statement: +13.2. Error Message for Data that Violates a max-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too many entries the following error is returned: Tag: operation-failed Error-app-tag: too-many-elements This error is returned once, with the error-path identifying the list node, even if there are more than one extra child present. -13.3. Error Message for Data that Violates a min-elements Statement: +13.3. Error Message for Data that Violates a min-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too few entries the following error is returned: Tag: operation-failed Error-app-tag: too-few-elements This error is returned once, with the error-path identifying the list node, even if there are more than one child missing. -13.4. Error Message for Data that Violates a must statement: +13.4. Error Message for Data that Violates a must Statement If a NETCONF operation would result in configuration data where the restrictions imposed by a "must" statement is violated the following error is returned, unless a specific "error-app-tag" substatement is present for the "must" statement. Tag: operation-failed Error-app-tag: must-violation -13.5. Error Message for Data that Violates a require-instance - statement: +13.5. Error Message for Data that Violates a require-instance Statement - If a NETCONF operation would result in configuration data where an - instance reference marked with require-instance "true" refers to a - non-existing instance, the following error is returned: + If a NETCONF operation would result in configuration data where a + leaf of type "instance-identifier" marked with require-instance + "true" refers to a non-existing instance, the following error is + returned: Tag: data-missing Error-app-tag: instance-required - Error-path: Path to the element with the require-instance - statement + Error-path: Path to the instance-identifier leaf. -13.6. Error Message for Data that Violates a mandatory choice - statement: +13.6. Error Message for Data that does not Match a leafref Type + + If a NETCONF operation would result in configuration data where a + leaf of type "leafref" refers to a non-existing instance, the + following error is returned: + + Tag: data-missing + Error-app-tag: instance-required + Error-path: Path to the leafref leaf. + +13.7. Error Message for Data that Violates a mandatory choice Statement If a NETCONF operation would result in configuration data where no nodes exists in a mandatory choice, the following error is returned: Tag: data-missing Error-app-tag: missing-choice Error-path: Path to the element with the missing choice. Error-info: : Contains the name of the missing mandatory choice. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). -13.7. Error Message for the "insert" Operation +13.8. Error Message for the "insert" Operation If the "insert" and "key" or "value" attributes are used in an for a list or leaf-list node, and the "key" or "value" refers to a non-existing instance, the following error is returned: Tag: bad-attribute Error-app-tag: missing-instance 14. IANA Considerations @@ -7017,50 +7151,50 @@ This document defines a language with which to write and read descriptions of management information. The language itself has no security impact on the Internet. Data modeled in YANG might contain sensitive information. RPCs or notifications defined in YANG might transfer sensitive information. Security issues are related to the usage of data modeled in YANG. Such issues shall be dealt with in documents describing the data models and documents about the interfaces used to manipulate the data - e.g. the NETCONF documents. + e.g., the NETCONF documents. - YANG is dependent upon: + Data modeled in YANG is dependent upon: o the security of the transmission infrastructure used to send sensitive information o the security of applications which store or release such sensitive information. o adequate authentication and access control mechanisms to restrict the usage of sensitive data. 16. Contributors The following people all contributed significantly to the initial YANG draft: - - Andy Bierman (andybierman.com) + - Andy Bierman (Netconf Central) - Balazs Lengyel (Ericsson) - David Partain (Ericsson) - Juergen Schoenwaelder (Jacobs University Bremen) - Phil Shafer (Juniper Networks) 17. Acknowledgements The editor wishes to thank the following individuals, who all provided helpful comments on various versions of this document: Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav - Lhotka, Gerhard Muenz, Tom Petch, Randy Preshun, David Reid, and Bert + Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert Wijnen. 18. References 18.1. Normative References [ISO.10646] International Organization for Standardization, "Information Technology - Universal Multiple-octet coded Character Set (UCS) - Part 1: Architecture and Basic @@ -7105,58 +7239,78 @@ [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . [XSD-TYPES] Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", W3C REC REC-xmlschema-2-20041028, October 2004. - [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World - Wide Web Consortium Recommendation REC-xslt-19991116, - November 1999, - . - 18.2. Non-Normative References [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation Structure of Management Information", RFC 3780, May 2004. + [XPATH2.0] + Chamberlin, D., Boag, S., Berglund, A., Robie, J., Simeon, + J., Fernandez, M., and M. Kay, "XML Path Language (XPath) + 2.0", World Wide Web Consortium Recommendation REC- + xpath20-20070123, January 2007, + . + + [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World + Wide Web Consortium Recommendation REC-xslt-19991116, + November 1999, + . + Appendix A. ChangeLog -A.1. Version -05 + RFC Editor: remove this section upon publication as an RFC. + +A.1. 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.2. 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.2. Version -04 +A.3. 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. @@ -7168,37 +7322,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.3. Version -03 +A.4. 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.4. Version -02 +A.5. 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 @@ -7204,26 +7358,25 @@ o Added section "Constraints" and clarified when constraints are enforced. (yang-00172) o Added "feature" and "if-feature" statements. (yang-00750) 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.5. Version -01 +A.6. 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. @@ -7254,25 +7407,26 @@ 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.6. Version -00 +A.7. 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 Martin Bjorklund (editor) Tail-f Systems Email: mbj@tail-f.com