--- 1/draft-ietf-netmod-yang-00.txt 2008-08-29 10:12:35.000000000 +0200 +++ 2/draft-ietf-netmod-yang-01.txt 2008-08-29 10:12:35.000000000 +0200 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track May 5, 2008 -Expires: November 6, 2008 +Intended status: Standards Track August 29, 2008 +Expires: March 2, 2009 YANG - A data modeling language for NETCONF - draft-ietf-netmod-yang-00 + draft-ietf-netmod-yang-01 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -23,37 +23,38 @@ 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 November 6, 2008. + This Internet-Draft will expire on March 2, 2009. Copyright Notice Copyright (C) The IETF Trust (2008). 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 11 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 13 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 14 4.2.3. Operational Data . . . . . . . . . . . . . . . . . . 19 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 @@ -145,189 +146,188 @@ 7.9.4. The choice's mandatory Statement . . . . . . . . . . 69 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 69 7.9.6. NETCONF operations . . . . . . . . . . 69 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 70 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 71 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 71 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 71 7.10.3. NETCONF operations . . . . . . . . . . 71 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 72 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 72 - 7.11.1. The grouping's Substatements . . . . . . . . . . . . 73 + 7.11.1. The grouping's Substatements . . . . . . . . . . . . 74 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 74 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 74 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 75 7.12.2. The uses's Refinement Statements . . . . . . . . . . 75 7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 76 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 76 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 77 - 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 77 - 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 77 - 7.13.3. The output Statement . . . . . . . . . . . . . . . . 78 - 7.14. The notification Statement . . . . . . . . . . . . . . . 79 - 7.14.1. The notification's Substatements . . . . . . . . . . 80 - 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 80 - 7.15.1. The augment's Substatements . . . . . . . . . . . . . 81 - 7.15.2. The when Statement . . . . . . . . . . . . . . . . . 81 - 7.15.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 - 7.15.4. Usage Example . . . . . . . . . . . . . . . . . . . . 82 - 7.16. The extension Statement . . . . . . . . . . . . . . . . . 84 - 7.16.1. The extension's Substatements . . . . . . . . . . . . 84 - 7.16.2. The argument Statement . . . . . . . . . . . . . . . 84 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 85 - 7.17. Common Statements . . . . . . . . . . . . . . . . . . . . 86 - 7.17.1. The config Statement . . . . . . . . . . . . . . . . 86 - 7.17.2. The status Statement . . . . . . . . . . . . . . . . 86 - 7.17.3. The description Statement . . . . . . . . . . . . . . 87 - 7.17.4. The reference Statement . . . . . . . . . . . . . . . 87 - 8. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 88 - 8.1. The Integer Built-in Types . . . . . . . . . . . . . . . 88 - 8.1.1. Lexicographic Representation . . . . . . . . . . . . 89 - 8.1.2. Restrictions . . . . . . . . . . . . . . . . . . . . 89 - 8.1.3. The range Statement . . . . . . . . . . . . . . . . . 89 - 8.1.4. Usage Example . . . . . . . . . . . . . . . . . . . . 90 - 8.2. The Floating Point Built-in Types . . . . . . . . . . . . 90 - 8.2.1. Lexicographic Representation . . . . . . . . . . . . 90 - 8.2.2. Restrictions . . . . . . . . . . . . . . . . . . . . 90 - 8.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 91 - 8.3. The string Built-in Type . . . . . . . . . . . . . . . . 91 - 8.3.1. Lexicographic Representation . . . . . . . . . . . . 91 - 8.3.2. Restrictions . . . . . . . . . . . . . . . . . . . . 91 - 8.3.3. The length Statement . . . . . . . . . . . . . . . . 91 - 8.3.4. The pattern Statement . . . . . . . . . . . . . . . . 92 - 8.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 93 - 8.4. The boolean Built-in Type . . . . . . . . . . . . . . . . 93 - 8.4.1. Lexicographic Representation . . . . . . . . . . . . 93 - 8.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . 93 - 8.5. The enumeration Built-in Type . . . . . . . . . . . . . . 93 - 8.5.1. Lexicographic Representation . . . . . . . . . . . . 93 - 8.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 93 - 8.5.3. The enum Statement . . . . . . . . . . . . . . . . . 94 - 8.5.4. Usage Example . . . . . . . . . . . . . . . . . . . . 95 - 8.6. The bits Built-in Type . . . . . . . . . . . . . . . . . 95 - 8.6.1. Restrictions . . . . . . . . . . . . . . . . . . . . 95 - 8.6.2. Lexicographic Representation . . . . . . . . . . . . 95 - 8.6.3. The bit Statement . . . . . . . . . . . . . . . . . . 95 - 8.6.4. Usage Example . . . . . . . . . . . . . . . . . . . . 96 - 8.7. The binary Built-in Type . . . . . . . . . . . . . . . . 97 - 8.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 97 - 8.7.2. Lexicographic Representation . . . . . . . . . . . . 97 - 8.8. The keyref Built-in Type . . . . . . . . . . . . . . . . 97 - 8.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 97 - 8.8.2. The path Statement . . . . . . . . . . . . . . . . . 97 - 8.8.3. Lexicographic Representation . . . . . . . . . . . . 98 - 8.8.4. Usage Example . . . . . . . . . . . . . . . . . . . . 98 - 8.9. The empty Built-in Type . . . . . . . . . . . . . . . . . 99 - 8.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 99 - 8.9.2. Lexicographic Representation . . . . . . . . . . . . 100 - 8.9.3. Usage Example . . . . . . . . . . . . . . . . . . . . 100 - 8.10. The union Built-in Type . . . . . . . . . . . . . . . . . 100 - 8.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 100 - 8.10.2. Lexicographic Representation . . . . . . . . . . . . 101 - 8.11. The instance-identifier Built-in Type . . . . . . . . . . 101 - 8.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 101 - 8.11.2. Lexicographic Representation . . . . . . . . . . . . 101 - 8.11.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 - 9. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 103 - 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 104 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 105 - 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 106 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 107 - 13.1. Normative References . . . . . . . . . . . . . . . . . . 107 - 13.2. Non-Normative References . . . . . . . . . . . . . . . . 108 - Appendix A. Derived YANG Types . . . . . . . . . . . . . . . . . 109 - A.1. Core YANG Derived Types . . . . . . . . . . . . . . . . . 109 - A.2. Internet Specific Derived Types . . . . . . . . . . . . . 114 - A.3. IEEE 802 Specific Derived Types . . . . . . . . . . . . . 120 - Appendix B. YIN . . . . . . . . . . . . . . . . . . . . . . . . 123 - B.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 123 - B.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 123 - B.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 125 - B.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 125 - B.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 126 - Appendix C. XML Schema Considerations . . . . . . . . . . . . . 127 - Appendix D. YANG ABNF Grammar . . . . . . . . . . . . . . . . . 128 - Appendix E. Error Responses for YANG Related Errors . . . . . . 146 - E.1. Error Message for Data that Violates a YANG unique - Statement: . . . . . . . . . . . . . . . . . . . . . . . 146 - E.2. Error Message for Data that Violates a YANG - max-elements Statement: . . . . . . . . . . . . . . . . . 146 - E.3. Error Message for Data that Violates a YANG - min-elements Statement: . . . . . . . . . . . . . . . . . 146 - E.4. Error Message for Data that Violates a YANG must or - when statement, a length, range or pattern restriction: . 146 - E.5. Error Message for the "insert" Operation . . . . . . . . 147 - Appendix F. Why We Need a New Modeling Language . . . . . . . . 148 - F.1. Why not XSD? . . . . . . . . . . . . . . . . . . . . . . 148 - F.2. Why not RelaxNG . . . . . . . . . . . . . . . . . . . . . 149 - F.3. Why not SMIng . . . . . . . . . . . . . . . . . . . . . . 149 - Appendix G. ChangeLog . . . . . . . . . . . . . . . . . . . . . 151 - G.1. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 151 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 152 - Intellectual Property and Copyright Statements . . . . . . . . . 153 + 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 78 + 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 78 + 7.13.3. The output Statement . . . . . . . . . . . . . . . . 79 + 7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 80 + 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 80 + 7.14. The notification Statement . . . . . . . . . . . . . . . 81 + 7.14.1. The notification's Substatements . . . . . . . . . . 82 + 7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 + 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 82 + 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 83 + 7.15.1. The augment's Substatements . . . . . . . . . . . . . 84 + 7.15.2. The when Statement . . . . . . . . . . . . . . . . . 84 + 7.15.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 85 + 7.15.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 + 7.16. The extension Statement . . . . . . . . . . . . . . . . . 87 + 7.16.1. The extension's Substatements . . . . . . . . . . . . 88 + 7.16.2. The argument Statement . . . . . . . . . . . . . . . 88 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 88 + 7.17. Common Statements . . . . . . . . . . . . . . . . . . . . 89 + 7.17.1. The config Statement . . . . . . . . . . . . . . . . 89 + 7.17.2. The status Statement . . . . . . . . . . . . . . . . 90 + 7.17.3. The description Statement . . . . . . . . . . . . . . 90 + 7.17.4. The reference Statement . . . . . . . . . . . . . . . 90 + 8. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 91 + 8.1. The Integer Built-in Types . . . . . . . . . . . . . . . 91 + 8.1.1. Lexicographic Representation . . . . . . . . . . . . 92 + 8.1.2. Restrictions . . . . . . . . . . . . . . . . . . . . 92 + 8.1.3. The range Statement . . . . . . . . . . . . . . . . . 92 + 8.1.4. Usage Example . . . . . . . . . . . . . . . . . . . . 93 + 8.2. The Floating Point Built-in Types . . . . . . . . . . . . 93 + 8.2.1. Lexicographic Representation . . . . . . . . . . . . 94 + 8.2.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94 + 8.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 94 + 8.3. The string Built-in Type . . . . . . . . . . . . . . . . 94 + 8.3.1. Lexicographic Representation . . . . . . . . . . . . 94 + 8.3.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94 + 8.3.3. The length Statement . . . . . . . . . . . . . . . . 95 + 8.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 96 + 8.3.5. The pattern Statement . . . . . . . . . . . . . . . . 96 + 8.3.6. Usage Example . . . . . . . . . . . . . . . . . . . . 96 + 8.4. The boolean Built-in Type . . . . . . . . . . . . . . . . 97 + 8.4.1. Lexicographic Representation . . . . . . . . . . . . 97 + 8.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97 + 8.5. The enumeration Built-in Type . . . . . . . . . . . . . . 97 + 8.5.1. Lexicographic Representation . . . . . . . . . . . . 97 + 8.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97 + 8.5.3. The enum Statement . . . . . . . . . . . . . . . . . 97 + 8.5.4. Usage Example . . . . . . . . . . . . . . . . . . . . 98 + 8.6. The bits Built-in Type . . . . . . . . . . . . . . . . . 99 + 8.6.1. Restrictions . . . . . . . . . . . . . . . . . . . . 99 + 8.6.2. Lexicographic Representation . . . . . . . . . . . . 99 + 8.6.3. The bit Statement . . . . . . . . . . . . . . . . . . 99 + 8.6.4. Usage Example . . . . . . . . . . . . . . . . . . . . 100 + 8.7. The binary Built-in Type . . . . . . . . . . . . . . . . 100 + 8.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 100 + 8.7.2. Lexicographic Representation . . . . . . . . . . . . 100 + 8.8. The keyref Built-in Type . . . . . . . . . . . . . . . . 101 + 8.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 101 + 8.8.2. The path Statement . . . . . . . . . . . . . . . . . 101 + 8.8.3. Lexicographic Representation . . . . . . . . . . . . 101 + 8.8.4. Usage Example . . . . . . . . . . . . . . . . . . . . 101 + 8.9. The empty Built-in Type . . . . . . . . . . . . . . . . . 103 + 8.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 103 + 8.9.2. Lexicographic Representation . . . . . . . . . . . . 103 + 8.9.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 + 8.10. The union Built-in Type . . . . . . . . . . . . . . . . . 104 + 8.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 104 + 8.10.2. Lexicographic Representation . . . . . . . . . . . . 104 + 8.11. The instance-identifier Built-in Type . . . . . . . . . . 104 + 8.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 105 + 8.11.2. Lexicographic Representation . . . . . . . . . . . . 105 + 8.11.3. Usage Example . . . . . . . . . . . . . . . . . . . . 105 + 9. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 106 + 10. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 + 10.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 107 + 10.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 107 + 10.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 109 + 10.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 109 + 10.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 110 + 11. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 111 + 12. Error Responses for YANG Related Errors . . . . . . . . . . . 130 + 12.1. Error Message for Data that Violates a YANG unique + Statement: . . . . . . . . . . . . . . . . . . . . . . . 130 + 12.2. Error Message for Data that Violates a YANG + max-elements Statement: . . . . . . . . . . . . . . . . . 130 + 12.3. Error Message for Data that Violates a YANG + min-elements Statement: . . . . . . . . . . . . . . . . . 130 + 12.4. Error Message for Data that Violates a YANG must + statement: . . . . . . . . . . . . . . . . . . . . . . . 131 + 12.5. Error Message for the "insert" Operation . . . . . . . . 131 + 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 132 + 14. Security Considerations . . . . . . . . . . . . . . . . . . . 133 + 15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 134 + 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 135 + 16.1. Normative References . . . . . . . . . . . . . . . . . . 135 + 16.2. Non-Normative References . . . . . . . . . . . . . . . . 136 + Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 137 + A.1. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 137 + A.2. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 138 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 139 + Intellectual Property and Copyright Statements . . . . . . . . . 140 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. 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 being used to manipulate the data. + operations are used to manipulate the data. 2. Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119]. 3. Terminology + o anyxml: A node which can contain an unknown chunk of XML data. + o augment: Adds new nodes to a previously defined node. o base type: The type from which a derived type was derived, which may be either a built-in type or another derived type. o built-in type: A YANG data type defined in the YANG language, such as uint32 or string. o choice: A node where only one of a number of identified alternative values is valid. - o container: An interior node in the data tree which exist in zero - or one instance. A container node has no value, but rather a set - of child nodes. + o configuration data: The set of writable data that is required to + transform a system from its initial default state into its current + state [RFC4741]. + + o container: An interior node in the data tree which exist in at + 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, augment, uses, and anyxml. - o data model: Formal representation of the application-specific - components of a conceptual network management programmatic - interface. - - o data model module: Container of definitions pertaining to a - specific data model. + o data model: A data model describes how data is represented and + accessed. - o data model object: A definition within a data model module that - represents a conceptual construct which can be accessed via a - network management protocol. Also called an object. + 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, and list. + 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 extension: An extension attaches non-YANG semantics to nodes. The extension statement defines new statements to express these semantics. @@ -335,64 +335,79 @@ o grouping: A reusable set of nodes, which may be used locally in the module, in modules which include it, and by other modules which import from it. o identifier: Used to identify different kinds of YANG items by name. o instance identifier: A mechanism for identifying a particular node in a data tree. - o interior nodes: Nodes within a hierarchy that are not leaf nodes. + o interior node: Nodes within a hierarchy that are not leaf nodes. o leaf: A node in the data tree with a value but no child nodes. 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 node: A logical location in a hierarchy of data elements. - 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. o schema node: A node in the schema tree. One of container, leaf, leaf-list, list, choice, case, rpc, input, output, and notification. o schema node identifier: A mechanism for identifying a particular node in the schema tree. o schema tree: The definition hierarchy specified within a module. + o state data: The additional data on a system that is not + configuration data such as read-only status information and + collected statistics [RFC4741]. + o submodule: A partial module definition which contributes derived types, groupings, data nodes, RPCs, and notifications to a module. A YANG module can be constructed from a number of submodules. o 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 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 + 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 nodes 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. @@ -429,27 +444,23 @@ that imports or includes it. YANG organizational constructs include defining lists of nodes with the same names and identifying the keys which distinguish list members 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 nodes. YANG modules can be translated into an XML format called YIN - (Appendix B), allowing applications using XML parsers and XSLT + (Section 10), allowing applications using XML parsers and XSLT scripts to operate on the models. - XML Schema [XSD] files can be generated from YANG modules, giving a - precise description of the XML representation of the data modeled in - YANG modules. - YANG strikes a balance between high-level object-oriented modeling and low-level bits-on-the-wire encoding. The reader of a YANG module can easily see the high-level view of the data model while seeing how the object 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 sufficiently for the reader to notice them. @@ -588,23 +599,24 @@ Good morning, Dave The "container" statement is covered in Section 7.5. 4.2.2.4. List Nodes A list is a sequence of list entries. An entry is like a structure - or a record. A list entry is uniquely identified by its key(s). A - list entry may contain any number of child nodes of any type - (including leafs, lists, containers etc.). + or a record. A list entry is uniquely identified by the values of + its key leafs. A list entry can have multiple keys. A list entry + may contain any number of child nodes of any type (including leafs, + lists, containers etc.). YANG Example: list user { key "name"; leaf name { type string; } leaf full-name { type string; @@ -718,22 +729,22 @@ leaf observed-speed { type uint32; config false; } } 4.2.4. Built-in Types YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special - requirements from the management information model. The following - table summarizes the built-in types discussed in Section 8: + requirements from the management domain. The following table + summarizes the built-in types discussed in Section 8: +---------------------+-------------+-------------------------------+ | Name | Type | Description | +---------------------+-------------+-------------------------------+ | int8 | Number | 8-bit signed integer | | int16 | Number | 16-bit signed integer | | int32 | Number | 32-bit signed integer | | int64 | Number | 64-bit signed integer | | uint8 | Number | 8-bit unsigned integer | | uint16 | Number | 16-bit unsigned integer | @@ -859,44 +870,48 @@ 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 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: + 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. @@ -1033,28 +1049,22 @@ The names of all standard modules must be unique, but different revisions of the same module should have the same name. Developers of enterprise modules are encouraged 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. 5.1.1. Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may - have more than one root node. While it is recommended to use a model - with a single root node, models that have multiple roots nodes are - sometimes convenient, and are supported by YANG. - - Due to the possibility of multiple roots the modeled data does not - necessarily map to a well-formed XML document. Often a conceptual - root node (e.g. or element in NETCONF RPCs) is added - to overcome this problem. + have more than one root node. Models that have multiple roots nodes + are sometimes convenient, and are supported by YANG. 5.2. File Layout YANG modules and submodules are typically stored in files, one module or submodule per file, with the name of the file given by the concatenation of the module or submodule name and the file suffix ".yang". 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 @@ -1087,21 +1097,26 @@ 5.4. XML Namespaces All YANG definitions are specified within a particular XML Namespace. Each module defines an XML namespace as a globally unique URI [RFC3986]. A NETCONF client or server uses the namespace during XML encoding of data. The namespace URI is advertised as a capability in the NETCONF message to indicate support for the YANG module by a NETCONF - server. + server. The capability URI advertised SHOULD be on the form: + + namespace-uri "?" revision + + Where "revision" is the revision of the module (see Section 7.1.9) + that the server implements. Namespaces for standard module names will be assigned by IANA. They MUST be unique (but different revisions of the same module should have the same namespace). Namespaces for private module names will be 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. @@ -1215,23 +1230,23 @@ submodule, the developer has more control over what pieces of their module are presented to the outside world, supporting the need to hide internal information and maintaining a boundary between what is shared with the outside world and what is kept private. Scoped definitions MUST NOT shadow definitions at a higher scope. A type or group cannot be defined if a higher level in the schema hierarchy has a definition with a matching identifier. When a YANG implementation resolves a reference to an unprefixed type - or grouping, it searches up the levels of hierarchy in the schema - tree, starting at the current level, for the definition of the type - or grouping. + 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. 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. @@ -1256,22 +1271,22 @@ 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 (";"), - curly braces ("{ }"), or comment sequences ("//", "/*", or "*/"), - then it MUST be enclosed within double or single quotes. + curly 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 whitespace before a line break, this trailing whitespace is stripped from the string. A single quoted string (enclosed within ' ') preserves each character @@ -1324,21 +1339,21 @@ "first line\n" + " second line" 6.2. Identifiers Identifiers are used to identify different kinds of YANG items by name. Each identifier starts with an upper-case or lower-case ASCII letter or an underscore character, followed by zero or more ASCII letters, digits, underscore characters, hyphens, and dots. Implementations MUST support identifiers up to 63 characters in length. Identifiers are case sensitive. The identifier syntax is - formally defined by the rule "identifier" in Appendix D. Identifiers + formally defined by the rule "identifier" in Section 11. 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: o All module and submodule names share the same global module identifier namespace. @@ -1375,32 +1390,35 @@ statement = keyword [argument] (";" / "{" *statement "}") The argument is a string, as defined in Section 6.1.2. 6.3.1. Language Extensions A module can introduce YANG extensions by using the "extension" keyword (see Section 7.16). The extensions can be imported by other modules with the "import" statement (see Section 7.1.5). When an - imported extension is used, the keyword must be qualified using the - prefix with which the extension's module was imported. + imported extension is used, the extension's keyword must be qualified + using the prefix with which the extension's module was imported. If + an extension is used in the module where it is defined, the + extension's keyword must be qualified with the module's prefix. 6.4. XPath Evaluations - YANG relies on 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. + 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. 7. YANG Statements The following sections describe all of the YANG core statements. @@ -1514,29 +1532,20 @@ and add the "yang-version 2" statement, or remain within the version 1 feature set and continue to use the default setting of "yang- version 1". 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 URI is advertised as a capability in the NETCONF - message to indicate support for the YANG module by a NETCONF - server. The capability URI advertised SHOULD be on the form: - - namespace-uri "?" revision - - Where "revision" is the revision of the module (see Section 7.1.9) - that the server implements. - See also Section 5.4. 7.1.4. The prefix Statement The "prefix" statement is used to define the prefix associated with the namespace of a module. 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 identifier (see Section 6.2). @@ -1554,24 +1563,24 @@ 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. 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 content 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. + 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. All identifiers contained in an imported module are imported into the current module or submodule, so that they can be referenced by definitions in the current module or submodule. 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. +--------------+---------+-------------+ | substatement | section | cardinality | @@ -1580,20 +1589,25 @@ +--------------+---------+-------------+ 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 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). + 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. + 7.1.7. The organization Statement The "organization" statement defines the party responsible for this module. The argument is a string which is used to specify a textual description of the organization(s) under whose auspices this module was developed. 7.1.8. The contact Statement The "contact" statement provides contact information for the module. @@ -1865,21 +1879,21 @@ 7.4.1. The type's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | bit | 8.6.3 | 0..n | | enum | 8.5.3 | 0..n | | length | 8.3.3 | 0..1 | | path | 8.8.2 | 0..1 | - | pattern | 8.3.4 | 0..1 | + | pattern | 8.3.5 | 0..n | | range | 8.1.3 | 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. @@ -1918,50 +1932,54 @@ 7.5.2. The must Statement The "must" statement, which is optional, takes as an argument a string which contains an XPath expression. It is used to formally declare a constraint on the configuration data. When a configuration datastore is validated, all "must" constraints are conceptually evaluated once for each corresponding instance in the datastore's 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. Within a - "must" expression, + default value, its "must" statements are not evaluated. All such constraints MUST evaluate to true for the configuration to be valid. The "must" statement is ignored if the data does not represent configuration. The XPath expression is conceptually evaluated in the following context: 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 The null namespace is defined to be the namespace of the current - module. + o Elements without a namespace refer to nodes in the current module. - o One variable "this", which is the context node, is defined. + 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 result of the XPath expression is converted to a boolean value using the standard XPath rules. + If the node with the must statement represents configuration data, + any node referenced in the XPath expression MUST also represent + configuration. + Note that the XPath expression is conceptually evaluated. This means that an implementation does not have to use an XPath evaluator on the device. How the evaluation is done in practice is an implementation decision. 7.5.3. The must's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ @@ -2475,51 +2493,52 @@ | unique | 7.8.3 | 0..n | | uses | 7.12 | 0..n | +--------------+---------+-------------+ 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. + key. Each such leaf identifier MUST refer to a child leaf of 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". All key leafs in a list MUST have the same value for their "config" as the list itself. The key string syntax is formally defined by the rule "key-arg" in - Appendix D. + Section 11. 7.8.3. The lists's unique Statement The "unique" statement is used to put constraints on valid configurations. It takes as an argument a string which contains a space separated list of schema node identifiers, which MUST be given - in the descendant form. Each such schema node identifier MUST refer - to a leaf. + in the descendant form (see the rule "descendant-schema-nodeid" in + Section 11). Each such schema node identifier MUST refer to a leaf. In a valid configuration, the combined values of all the leaf instances specified in the string MUST be unique within all list entry instances. The unique string syntax is formally defined by the rule "unique-arg" - in Appendix D. + in Section 11. 7.8.3.1. Usage Example With the following list: list server { key "name"; unique "ip port"; leaf name { type string; @@ -2738,32 +2757,30 @@ followed by a block of substatements that holds detailed choice information. The identifier is used to identify the choice node in the schema tree. A choice node does not exist in the data tree. A choice consists of a number of branches, defined with the case substatement. Each branch contains a number of child nodes. The "choice" statement puts a constraint on a valid configuration. In a valid configuration, the nodes from at most one of the choice's branches exist at the same time. - If a choice is marked with "mandatory true", at least one node from - one of the cases must be present in a valid configuration. - See Section 4.2.7 for additional information. 7.9.1. The choice's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | | case | 7.9.2 | 0..n | + | config | 7.17.1 | 0..1 | | container | 7.5 | 0..n | | default | 7.9.3 | 0..1 | | description | 7.17.3 | 0..1 | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | mandatory | 7.9.4 | 0..1 | | reference | 7.17.4 | 0..1 | | status | 7.17.2 | 0..1 | +--------------+---------+-------------+ @@ -2829,26 +2846,30 @@ | uses | 7.12 | 0..n | +--------------+---------+-------------+ 7.9.3. The choice's default Statement The "default" statement indicates if a case should be considered as the default if no child nodes from any of the choice's cases exists. The argument is the identifier of the "case" statement. If the "default" statement is missing, there is no default case. + The "default" statement MUST NOT be present on choices where + "mandatory" is true. + The default case is only important when considering the default values of nodes under the cases. The default values for nodes under the default case are used if none of the nodes under any of the cases are present. - There MUST NOT be any mandatory child nodes under the default case. + There MUST NOT be any mandatory nodes (Section 3.1) under the default + case. Default values for child nodes under a case are only used if one of the nodes under that case is present, or if that case is the default case. If none of the nodes under a case are present and the case is not the default case, the default values of the cases' child nodes are ignored. In this example, the choice defaults to "interval", and the default value will be used if none of "daily", "time-of-day", or "manual" are present. If "daily" is present, the default value for "time-of-day" @@ -2878,23 +2899,25 @@ leaf manual { type empty; } } } } 7.9.4. The choice's mandatory Statement The "mandatory" statement, which is optional, takes as an argument - the string "true" or "false". If "mandatory" is "true", nodes from - exactly one of the choice's case branches MUST exist in a valid - configuration. + the string "true" or "false". If "mandatory" is "true", at least one + node from exactly one of the choice's case branches MUST exist in a + valid configuration. If "mandatory" is "false", a valid + configuration MAY have no nodes from the choice's case branches + present. If not specified, the default is "false". 7.9.5. XML Encoding Rules The choice and case nodes are not visible in XML. 7.9.6. NETCONF operations Since only one of the choices cases can be valid at any time, the @@ -2947,22 +2970,23 @@ 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. - This can be useful in e.g. RPC replies. An example is the - parameter in the operation. + No restrictions are placed on the XML. This can be useful in e.g. + RPC replies. An example is the parameter in the operation. An anyxml node cannot be augmented. It is NOT RECOMMENDED that the anyxml statement is used to represent configuration data. 7.10.1. The anyxml's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | @@ -3038,21 +3062,22 @@ which is an identifier, followed by a block of substatements that holds detailed grouping information. The grouping statement is not a data definition statement and, as such, does not define any nodes in the schema tree. A grouping is like a "structure" or a "record" in conventional programming languages. Once a grouping is defined, it can be referenced in a "uses" - statement (see Section 7.12). + 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. For details about scoping for nested groupings, see Section 5.8. 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, @@ -3123,22 +3148,21 @@ | reference | 7.17.4 | 0..1 | | status | 7.17.2 | 0..1 | | uses | 7.12 | 0..n | +--------------+---------+-------------+ 7.12.2. The uses's Refinement Statements Some of the properties of each node in the grouping can be refined in substatements to "uses". If a node is not present in a substatement, it is not refined, and thus used exactly as it was defined in the - "grouping". The refinement substatements MUST be specified in the - same order as in the grouping, and a node can be refined only once. + "grouping". A node can be refined only once in "uses". The following refinements can be done: o A leaf or choice node may get a default value, or a new default value if it already had one. o Any node may get a specialized "description" string. o Any node may get a specialized "reference" string. @@ -3220,42 +3244,44 @@ 7.13. The rpc Statement The "rpc" statement is used to define a NETCONF RPC method. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed rpc information. This argument is the name of the RPC, and is used as the element name directly under the element, as designated by the substitution group "rpcOperation" in [RFC4741]. - The rpc "statement" defines an rpc node in the schema tree. + The "rpc" statement defines an rpc node in the schema tree. Under + the rpc node, an input node with the name "input", and an output node + with the name "output" are also defined. The nodes "input" and + "output" are defined in the module's namespace. 7.13.1. The rpc's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.17.3 | 0..1 | | grouping | 7.11 | 0..n | | input | 7.13.2 | 0..1 | | output | 7.13.3 | 0..1 | | reference | 7.17.4 | 0..1 | | status | 7.17.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 - "input" statement defines an input node in the schema tree, with the - name "input". + substatements to "input" defines nodes under the RPC's input node. If a container in the input tree has a "presence" statement, the container need not be present in a NETCONF RPC invocation. 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. @@ -3277,22 +3303,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 - "output" statement defines an output node in the schema tree, with - the name "output". + substatements to "output" defines nodes under the RPC's output node. If a container in the output tree has a "presence" statement, the container need not be present in a NETCONF RPC reply 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. @@ -3310,20 +3335,67 @@ | 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 + + 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 + returned, the contains a single element defined in + [RFC4741]. If output parameters are returned, they are encoded as + child elements to the element defined in [RFC4741], in + the same order as they are defined within the output statement. + +7.13.5. Usage Example + + The following example defines an RPC method: + + module rock { + namespace "http://example.net/rock"; + prefix rock; + + rpc rock-the-house { + input { + leaf zip-code { + type string; + } + } + } + } + + A corresponding XML encoding 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 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. @@ -3351,50 +3423,97 @@ | grouping | 7.11 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | reference | 7.17.4 | 0..1 | | status | 7.17.2 | 0..1 | | typedef | 7.3 | 0..n | | uses | 7.12 | 0..n | +--------------+---------+-------------+ +7.14.2. XML Encoding Rules + + A notification node is encoded as a child XML element to the + element defined in [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: + + + 2008-07-08T00:01:00Z + + fault + + Ethernet0 + + major + + + 7.15. The augment Statement The "augment" statement allows a module or submodule to add to the schema tree defined in another module or submodule. 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, rpc, input, output, or notification - node. It is augmented with the nodes defined in the substatements - that follow the "augment" statement. + 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 augment string is a schema node identifier. The syntax is - formally defined by the rule "augment-arg" in Appendix D. If the + formally defined by the rule "augment-arg" in Section 11. If the "augment" statement is on the top-level in a module or submodule, the - absolute form of a schema node identifier MAY be used. Otherwise, - the descendant form MUST be used. + absolute form (defined by the rule "absolute-schema-nodeid" in + Section 11) of a schema node identifier MAY be used. Otherwise, the + descendant form (defined by the rule "descendant-schema-nodeid" in + Section 11) 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. 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 rpc node, the "input" and "output" statements - 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). 7.15.1. The augment's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anyxml | 7.10 | 0..n | | augment | 7.15 | 0..n | | case | 7.9.2 | 0..n | | choice | 7.9 | 0..n | @@ -3420,28 +3539,32 @@ otherwise it is not. The XPath expression is conceptually evaluated in the following context: o 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 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 The null namespace is defined to be the namespace of the current - module. + o Elements without a namespace refer to nodes in the current module. - o One variable "this", which is the context node, is defined. + 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 result of the XPath expression is converted to a boolean value using the standard XPath rules. Note that the XPath expression is conceptually evaluated. This means that an implementation does not have to use an XPath evaluator on the device. The augment can very well be implemented with specially written code. 7.15.3. XML Encoding Rules @@ -3541,31 +3664,31 @@ The "extension" statement allows the definition of new statements within the YANG language. This new statement definition can be imported and used by other modules. The statement's argument is an identifier that is the new keyword for the extension and must be followed by a block of substatements that holds detailed extension information. The purpose of the extension statement is to define a keyword, so that it can be imported and used by other modules. - The extension can be used by like a normal YANG statement, with the + The extension can be used like a normal YANG statement, with the statement name followed by an argument if one is defined by the extension, and an optional block of substatements. The statement's name is created by combining the the prefix of the module in which the extension was defined, a colon (":"), and the extension's keyword, with no interleaving whitespace. The substatements of an extension are defined by the extension, using some mechanism outside the scope of this specification. Syntactically, the substatements MUST be core YANG statements, or also defined using "extension" statements. Core YANG statements in extensions MUST follow the - syntactical rules in Appendix D. + syntactical rules in Section 11. 7.16.1. The extension's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | argument | 7.16.2 | 0..1 | | description | 7.17.3 | 0..1 | | reference | 7.17.4 | 0..1 | | status | 7.17.2 | 0..1 | @@ -3588,21 +3711,21 @@ | substatement | section | cardinality | +--------------+----------+-------------+ | yin-element | 7.16.2.2 | 0..1 | +--------------+----------+-------------+ 7.16.2.2. The yin-element Statement The "yin-element" statement, which is optional, takes as an argument the string "true" or "false". This statement indicates if the argument should be mapped to an XML element in YIN or to an XML - attribute. (see Appendix B). + attribute. (see Section 10). If no "yin-element" statement is present, it defaults to "false". 7.16.3. Usage Example To define an extension: module my-extensions { ... @@ -3687,28 +3810,25 @@ definition. 8. Built-in Types YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special requirements from the management information model. 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. An initial set of - commonly used derived types is defined in the YANG standard modules - "yang-types" (Appendix A.1), "inet-types" (Appendix A.2), and "ieee- - types" (Appendix A.3). + 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 8.3.3, Section 8.3.4) and range restrictions of + of strings (Section 8.3.3, Section 8.3.5) and range restrictions of numeric types (Section 8.1.3). 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. 8.1. 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 @@ -3776,43 +3896,56 @@ types derived from those. A range consists of an explicit value, or a lower inclusive bound, two consecutive dots "..", and an upper inclusive bound. Multiple values or ranges can be given, separated by "|". If multiple values or ranges are given they all MUST be disjoint and MUST be in ascending order. If a value restriction is applied to an already restricted type, the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges - with intermediate gaps. Each range boundary value given in the range - expression MUST match the type being restricted, or be one of the - special values "min" or "max". "min" and "max" means the minimum and - maximum value accepted for the type being restricted, respectively. + with intermediate gaps. Each explicit value and range boundary value + given in the range expression MUST match the type being restricted, + or be one of the special values "min" or "max". "min" and "max" means + the minimum and maximum value accepted for the type being restricted, + respectively. The range expression syntax is formally defined by the rule "range- - expr" in Appendix D. + arg" in Section 11. 8.1.3.1. The range's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | description | 7.17.3 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 | | error-message | 7.5.3.1 | 0..1 | | reference | 7.17.4 | 0..1 | +---------------+---------+-------------+ 8.1.4. Usage Example + typedef my-base-int32-type { type int32 { - range "1..4 | 10 | 20..max"; + range "1..4 | 10..20"; + } + } + + type my-base-int32-type { + // legal range restriction + range "11..max"; // 11..20 + } + + type int32 { + // illegal range restriction + range "11..100"; } 8.2. The Floating Point Built-in Types The floating point built-in types are float32 and float64. They represent floating point values of single and double precision as defined in [IEEE.754]. Special values are positive and negative infinity, and not-a-number. 8.2.1. Lexicographic Representation @@ -3854,21 +3987,21 @@ %x10000-10FFFF 8.3.1. Lexicographic Representation A string value is lexicographically represented as character data in the XML encoding. 8.3.2. Restrictions A string can be restricted with the "length" (Section 8.3.3) and - "pattern" (Section 8.3.4) statements. + "pattern" (Section 8.3.5) statements. 8.3.3. The length Statement The "length" statement, which is an optional substatement to the "type" statement, takes as an argument a length expression string. It is used to restrict the built-in type "string", or types derived from "string". A "length" statement restricts the number of characters in the string. @@ -3882,61 +4015,81 @@ MUST be equal or more limiting, that is, raising the lower bounds, reducing the upper bounds, removing explicit length values or ranges, or splitting ranges into multiple ranges with intermediate gaps. A length value is a non-negative integer, or one of the special values "min" or "max". "min" and "max" means the minimum and maximum length accepted for the type being restricted, respectively. An implementation is not required to support a length value larger than 18446744073709551615. The length expression syntax is formally defined by the rule "length- - expr" in Appendix D. + arg" in Section 11. 8.3.3.1. The length's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | description | 7.17.3 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 | | error-message | 7.5.3.1 | 0..1 | | reference | 7.17.4 | 0..1 | +---------------+---------+-------------+ -8.3.4. The pattern Statement +8.3.4. Usage Example + + typedef my-base-str-type { + type string { + length "1..255"; + } + } + + type my-base-str-type { + // legal length refinement + length "11 | 42..max"; // 11 | 42..255 + } + + type my-base-str-type { + // illegal length refinement + length "1..999"; + } + +8.3.5. 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. -8.3.4.1. The pattern's Substatements + If the type has multiple "pattern" statements, the expressions are + AND:ed together, i.e. all such expressions have to match. + +8.3.5.1. The pattern's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | description | 7.17.3 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 | | error-message | 7.5.3.1 | 0..1 | | reference | 7.17.4 | 0..1 | +---------------+---------+-------------+ -8.3.5. Usage Example +8.3.6. Usage Example With the following type: type string { length "0..4"; pattern "[0-9a-fA-F]*"; } - the following strings match: AB // legal 9A00 // legal and the following strings do not match: 00ABAB // illegal xx00 // illegal @@ -4145,21 +4299,21 @@ 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 at most one equality test per key. The predicates are only used when more than one key reference is needed to uniquely identify a list entry. This occurs if the list has multiple keys, or a reference to a list within a list is needed. In these cases, multiple keyref leafs are typically specified, and predicates are used to tie them together. - The syntax is formally defined by the rule "path-arg" in Appendix D. + The syntax is formally defined by the rule "path-arg" in Section 11. 8.8.3. Lexicographic Representation A keyref value is encoded the same way as the key it references. 8.8.4. Usage Example With the following list: list interface { @@ -4197,25 +4351,25 @@ The following keyrefs refer to an existing address of an interface: container default-address { leaf ifname { type keyref { path "../../interface/name"; } } leaf address { type keyref { - path "../../interface[name = $this/../ifname]/address/ip"; + path "../../interface[name = current()/../ifname]" + + "/address/ip"; } } } - A corresponding XML snippet is e.g.: eth0
192.0.2.1
192.0.2.2
@@ -4300,21 +4453,21 @@ 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, or a value of a leaf- list. Each predicate consists of one equality test per key. Each key MUST have a corresponding predicate. The syntax is formally defined by the rule "absolute-instid" in - Appendix D. + Section 11. 8.11.1. Restrictions An instance-identifier cannot be restricted. 8.11.2. 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- @@ -4328,804 +4481,50 @@ The following are examples of instance identifiers: /ex:system/ex:services/ex:ssh/ex:port /ex:system/ex:user[ex:name='fred'] /ex:system/ex:user[ex:name='fred']/ex:type /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] + /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] 9. Updating a Module [Editor's Note: add versioning rules, i.e. what can be done w/o changing the module name and the namespace] -10. IANA Considerations - - A registry for standard YANG modules shall be set up. Each entry - shall contain the unique module name, the unique XML namespace from - the YANG URI Scheme and some reference to the module's documentation. - - This document registers five URIs for the YANG XML namespace in the - IETF XML registry [RFC3688]. - - URI: urn:ietf:params:xml:ns:yang:ieee-types - - URI: urn:ietf:params:xml:ns:yang:inet-types - - URI: urn:ietf:params:xml:ns:yang:yang-types - - URI: urn:ietf:params:xml:ns:yang:yin:1 - - URI: urn:ietf:params:xml:ns:yang:1 - -11. Security Considerations - - This document defines a language with which to write and read - descriptions of management information. The language itself has no - security impact on the Internet. - - 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. - - 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 access control mechanisms to restrict the - usage of sensitive data. - -12. Contributors - - The following people all contributed significantly to the initial - YANG draft: - - - Andy Bierman (andybierman.com) - - Balazs Lengyel (Ericsson) - - David Partain (Ericsson) - - Juergen Schoenwaelder (Jacobs University Bremen) - - Phil Shafer (Juniper Networks) - -13. References - -13.1. Normative References - - [IEEE.754] - Institute of Electrical and Electronics Engineers, - "Standard for Binary Floating-Point Arithmetic", - IEEE Standard 754, August 1985. - - [ISO.10646] - International Organization for Standardization, - "Information Technology - Universal Multiple-octet coded - Character Set (UCS) - Part 1: Architecture and Basic - Multilingual Plane", ISO Standard 10646-1, May 1993. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, - January 2004. - - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, - RFC 3986, January 2005. - - [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. - - [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, - December 2006. - - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. - - [XSD] Maloney, M., Beech, D., Thompson, H., and N. Mendelsohn, - "XML Schema Part 1: Structures Second Edition", W3C - REC REC-xmlschema-1-20041021, October 2004. - - [XSD-TYPES] - Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes - Second Edition", W3C REC REC-xmlschema-2-20041028, - October 2004. - -13.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. - -Appendix A. Derived YANG Types - - Most YANG modules are built on top of the definitions of some - commonly used derived types. The definitions of these derived types - are contained in the "yang-types", "inet-types", and "ieee-types" - modules which are defined below. Their derived types are generally - applicable for modeling all areas of management information. - -A.1. Core YANG Derived Types - -module yang-types { - - // XXX namespace to be allocated by IANA - - namespace "urn:ietf:params:xml:ns:yang:yang-types"; - prefix "yang"; - - organization - "YANG Language Design Team"; - - contact - "Martin Bjorklund (Editor) "; - - description - "This module contains standard derived YANG types."; - - revision 2007-10-02 { - description "Initial revision."; - } - - /* - * collection of counter and gauge types - */ - - typedef counter32 { - type uint32; - description - "The counter32 type represents a non-negative integer - which monotonically increases until it reaches a - maximum value of 2^32-1 (4294967295 decimal), when it - wraps around and starts increasing again from zero. - - Counters have no defined `initial' value, and thus, a - single value of a counter has (in general) no information - content. Discontinuities in the monotonically increasing - value normally occur at re-initialization of the - management system, and at other times as specified in the - description of an object instance using this type. If - such other times can occur, for example, the creation of - an object instance of type counter32 at times other than - re-initialization, then a corresponding object should be - defined, with an appropriate type, to indicate the last - discontinuity. - - The counter32 type should not be used for configuration - objects. A default statement should not be used for - attributes with a type value of counter32."; - reference - "RFC 2578 (STD 58)"; - } - - typedef zero-based-counter32 { - type yang:counter32; - default "0"; - description - "The zero-based-counter32 type represents a counter32 - which has the defined `initial' value zero."; - reference - "RFC 2021"; - } - - typedef counter64 { - type uint64; - description - "The counter64 type represents a non-negative integer - which monotonically increases until it reaches a - maximum value of 2^64-1 (18446744073709551615), when - it wraps around and starts increasing again from zero. - - Counters have no defined `initial' value, and thus, a - single value of a counter has (in general) no information - content. Discontinuities in the monotonically increasing - value normally occur at re-initialization of the - management system, and at other times as specified in the - description of an object instance using this type. If - such other times can occur, for example, the creation of - an object instance of type counter64 at times other than - re-initialization, then a corresponding object should be - defined, with an appropriate type, to indicate the last - discontinuity. - - The counter64 type should not be used for configuration - objects. A default statement should not be used for - attributes with a type value of counter64."; - reference - "RFC 2578 (STD 58)"; - } - - typedef zero-based-counter64 { - type yang:counter64; - default "0"; - description - "The zero-based-counter64 type represents a counter64 - which has the defined `initial' value zero."; - reference - "RFC 2856"; - } - - typedef gauge32 { - type uint32; - description - "The gauge32 type represents a non-negative integer, - which may increase or decrease, but shall never - exceed a maximum value, nor fall below a minimum - value. The maximum value can not be greater than - 2^32-1 (4294967295 decimal), and the minimum value - can not be smaller than 0. The value of a gauge32 - has its maximum value whenever the information - being modeled is greater than or equal to its - maximum value, and has its minimum value whenever - the information being modeled is smaller than or - equal to its minimum value. If the information - being modeled subsequently decreases below - (increases above) the maximum (minimum) value, the - gauge32 also decreases (increases)."; - reference - "RFC 2578 (STD 58)"; - } - - typedef gauge64 { - type uint64; - description - "The gauge64 type represents a non-negative integer, - which may increase or decrease, but shall never - exceed a maximum value, nor fall below a minimum - value. The maximum value can not be greater than - 2^64-1 (18446744073709551615), and the minimum value - can not be smaller than 0. The value of a gauge64 - has its maximum value whenever the information - being modeled is greater than or equal to its - maximum value, and has its minimum value whenever - the information being modeled is smaller than or - equal to its minimum value. If the information - being modeled subsequently decreases below - (increases above) the maximum (minimum) value, the - gauge64 also decreases (increases)."; - reference - "RFC 2856"; - } - - /* - * collection of identifier related types - */ - - typedef uri { - type string; - description - "A uri type represents Uniform Resource Identifier (URI) - as defined by STD 66. - - Objects using this type MUST be in US-ASCII encoding, and - MUST be normalized as described by RFC 3986 Sections - 6.2.1, 6.2.2.1, and 6.2.2.2. All unnecessary - percent-encoding is removed, and all case-insensitive - characters are set to lowercase except for hexadecimal - digits, which are normalized to uppercase as described in - Section 6.2.2.1. - - The purpose of this normalization is to help provide unique - URIs. Note that this normalization is not sufficient to - provide uniqueness. Two URIs that are textually distinct - after this normalization may still be equivalent. - - Objects using this type MAY restrict the schemes that they - permit. For example, 'data:' and 'urn:' schemes might not - be appropriate. - - A zero-length URI is not a valid URI. This can be used to - express 'URI absent' where required, for example when used - as an index field."; - reference - "RFC 3986 (STD 66), RFC 3305, and RFC 5017"; - } - - typedef object-identifier { - type string { - pattern '[0-2](\.\d+)+'; - } - description - "The object-identifier type represents administratively - assigned names in a registration-hierarchical-name tree. - - Values of this type are denoted as a sequence of numerical - non-negative sub-identifier values. Each sub-identifier - value MUST NOT exceed 2^32-1 (4294967295). Sub-identifiers - are separated by single dots and without any intermediate - white space. - - Although the number of sub-identifiers is not limited, - module designers should realize that there may be - implementations that stick with the SMIv1/v2 limit of 128 - sub-identifiers."; - reference - "ITU-T Recommendation X.660 / ISO/IEC 9834-1"; - } - - /* - * collection of date and time related types - */ - - typedef date-and-time { - type string { - pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.d*)?' - + '(Z|(\+|-)\d{2}:\d{2})'; - } - description - 'The date-and-time type is a profile of the ISO 8601 - standard for representation of dates and times using the - Gregorian calendar. The format is most easily described - using the following ABFN (see RFC 3339): - - date-fullyear = 4DIGIT - date-month = 2DIGIT ; 01-12 - date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 - time-hour = 2DIGIT ; 00-23 - time-minute = 2DIGIT ; 00-59 - time-second = 2DIGIT ; 00-58, 00-59, 00-60 - time-secfrac = "." 1*DIGIT - time-numoffset = ("+" / "-") time-hour ":" time-minute - time-offset = "Z" / time-numoffset - - partial-time = time-hour ":" time-minute ":" time-second - [time-secfrac] - full-date = date-fullyear "-" date-month "-" date-mday - full-time = partial-time time-offset - - date-time = full-date "T" full-time'; - reference "RFC 3339"; - } - typedef timeticks { - type uint32; - description - "The timeticks type represents a non-negative integer - which represents the time, modulo 2^32 (4294967296 - decimal), in hundredths of a second between two epochs. - When objects are defined which use this type, the - description of the object identifies both of the reference - epochs."; - reference - "RFC 2578 (STD 58)"; - } - - typedef timestamp { - type yang:timeticks; - description - "The timestamp type represents the value of an associated - timeticks object at which a specific occurrence - happened. The specific occurrence must be defined in the - description of any object defined using this type. When - the specific occurrence occurred prior to the last time - the associated timeticks attribute was zero, then the - timestamp value is zero. Note that this requires all - timestamp values to be reset to zero when the value of - the associated timeticks attribute reaches 497+ days and - wraps around to zero. - - The associated timeticks object must be specified - in the description of any object using this type."; - reference - "RFC 2579 (STD 58)"; - } - - /* - * collection of generic address types - */ - - typedef phys-address { - type string; - description - "Represents media- or physical-level addresses."; - reference - "RFC 2579 (STD 58)"; - } -} - -A.2. Internet Specific Derived Types - module inet-types { - - // XXX namespace to be allocated by IANA - - namespace "urn:ietf:params:xml:ns:yang:inet-types"; - prefix "inet"; - - organization - "YANG Language Design Team"; - - contact - "Martin Bjorklund (Editor) "; - - description - "This module contains standard derived YANG types - for Internet addresses and related things."; - - revision 2007-10-02 { - description "Initial revision."; - } - - /* - * collection of protocol field related types - */ - - typedef ip-version { - type enumeration { - enum unknown { - value 0; - description - "An unknown or unspecified version of the - Internet protocol."; - } - enum ipv4 { - value 1; - description - "The IPv4 protocol as defined in RFC 791."; - } - enum ipv6 { - value 2; - description - "The IPv6 protocol as defined in RFC 2460."; - } - } - description - "This value represents the version of the IP protocol."; - reference - "RFC 791 (STD 5), RFC 2460"; - } - - typedef dscp { - type uint8 { - range "0..63"; - } - description - "The dscp type represents a Differentiated Services - Code-Point that may be used for marking a traffic - stream."; - reference - "RFC 3289, RFC 2474, RFC 2780"; - } - - typedef flow-label { - type uint32 { - range "0..1048575"; - } - description - "The flow-label type represents flow identifier or - Flow Label in an IPv6 packet header that may be - used to discriminate traffic flows."; - reference - "RFC 2460"; - } - - typedef port-number { - type uint16 { - range "1..65535"; - } - description - "The port-number type represents a 16-bit port - number of an Internet transport layer protocol - such as UDP, TCP, DCCP or SCTP. Port numbers are - assigned by IANA. A current list of all - assignments is available from - . - - Note that the value zero is not a valid port - number. A union type might be used in situations - where the value zero is meaningful."; - reference - "RFC 4001"; - } - - /* - * collection of autonomous system related types - */ - typedef asn { - type uint32; - description - "The asn type represents autonomous system numbers which - identify an Autonomous System (AS). An AS is a set of - routers under a single technical administration, using an - interior gateway protocol and common metrics to route - packets within the AS, and using an exterior gateway - protocol to route packets to other ASs'. IANA maintains - the AS number space and has delegated large parts to the - regional registries. - - Autonomous system numbers are currently limited to 16 bits - (0..65535). There is however work in progress to enlarge - the autonomous system number space to 32 bits. This - textual convention therefore uses an uint32 base type - without a range restriction in order to support a larger - autonomous system number space."; - reference - "RFC 1771, RFC 1930, RFC 4001"; - } - - /* - * collection of IP address and hostname related types - */ - - typedef ip-address { - type union { - type inet:ipv4-address; - type inet:ipv6-address; - } - description - "The ip-address type represents an IP address and - is IP version neutral. The format of the textual - representations implies the IP version."; - } - - typedef ipv4-address { - type string { - pattern - '(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}' - + '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])' - + '(%[\p{N}\p{L}]+)?'; - } - description - "The ipv4-address type represents an IPv4 address in - dotted-quad notation. The IPv4 address may include - a zone index, separated by a % sign."; - } - - typedef ipv6-address { - type string { - pattern - /* full */ - '((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})' - + '(%[\p{N}\p{L}]+)?)' - /* mixed */ - + '|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\.' - + '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))' - + '(%[\p{N}\p{L}]+)?)' - /* shortened */ - + '|((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)' - + '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*' - + '(%[\p{N}\p{L}]+)?)' - /* shortened mixed */ - + '((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)' - + '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*' - + '(([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))' - + '(%[\p{N}\p{L}]+)?)'; - } - description - "The ipv6-address type represents an IPv6 address in - full, mixed, shortened and shortened mixed notation. - The IPv6 address may include a zone index, separated - by a % sign."; - } - - typedef ip-prefix { - type union { - type inet:ipv4-prefix; - type inet:ipv6-prefix; - } - description - "The ip-prefix type represents an IP prefix and - is IP version neutral. The format of the textual - representations implies the IP version."; - } - - typedef ipv4-prefix { - type string { - pattern - '(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}' - + '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])' - + '/\p{N}+'; - } - description - "The ipv4-prefix type represents an IPv4 address prefix. - The prefix length is given by the number following the - slash character and must be less than or equal 32. - Values larger than 32 should be treated as 32. - - A prefix length value of n corresponds to an IP address - mask which has n contiguous 1-bits from the most - significant bit (MSB) and all other bits set to 0. - - The IPv4 address represented in dotted quad notation - should have all bits that do not belong to the prefix - set to zero."; - } - - typedef ipv6-prefix { - type string { - pattern - /* full */ - '((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})' - + '/\p{N}+)' - /* mixed */ - + '|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\.' - + '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))' - + '/\p{N}+)' - /* shortened */ - + '|((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)' - + '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*' - + '/\p{N}+)' - /* shortened mixed */ - + '((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)' - + '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*' - + '(([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))' - + '/\p{N}+)'; - } - description - "The ipv6-prefix type represents an IPv6 address prefix. - The prefix length is given by the number following the - slash character and must be less than or equal 128. - Values larger than 128 should be treated as 128. - - A prefix length value of n corresponds to an IP address - mask which has n contiguous 1-bits from the most - significant bit (MSB) and all other bits set to 0. - - The IPv6 address represented in dotted quad notation - should have all bits that do not belong to the prefix - set to zero."; - } - typedef domain-name { - type string { - pattern '([\p{L}\p{N}]+\.)*[\p{L}\p{N}]'; - } - description - "The domain-name type represents a DNS domain - name. The name SHOULD be fully qualified - whenever possible. - - The description clause of objects using the - domain-name type MUST describe how (and when) - these names are resolved to IP addresses. - - Note that the resolution of a domain-name value - may require to query multiple DNS records (e.g., - A for IPv4 and AAAA for IPv6). The order of the - resolution process and which DNS record takes - precedence depends on the configuration of the - resolver."; - reference - "RFC 1034"; - } - - typedef host { - type union { - type inet:ip-address; - type inet:domain-name; - } - description - "The host type represents either an IP address - or a DNS domain name."; - } - - } - -A.3. IEEE 802 Specific Derived Types - - module ieee-types { - - // XXX namespace to be allocated by IANA - - namespace "urn:ietf:params:xml:ns:yang:ieee-types"; - prefix "ieee"; - - import yang-types { - prefix yang; - } - organization - "YANG Language Design Team"; - - contact - "Martin Bjorklund (Editor) "; - - description - "This module contains standard derived YANG types - for IEEE 802 addresses and related things."; - - revision 2007-10-02 { - description "Initial revision."; - } - - /* - * collection of IEEE address type definitions - */ - - typedef mac-address { - type yang:phys-address { - pattern '([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}'; - } - description - "The mac-address type represents an 802 MAC address - represented in the `canonical' order defined by - IEEE 802.1a, i.e., as if it were transmitted least - significant bit first, even though 802.5 (in contrast - to other 802.x protocols) requires MAC addresses to - be transmitted most significant bit first."; - reference - "RFC 2579 STD 58"; - } - - /* - * collection of IEEE 802 related identifier types - */ - - typedef bridgeid { - type string { - pattern '[0-9a-fA-F]{4}:' - + '([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}'; - } - description - "The bridgeid type represents identifers that uniquely - identify a bridge. Its first four hexadecimal digits - contain a priority value followed by a colon. The - remaining characters contain the MAC address used to - refer to a bridge in a unique fashion (typically, the - numerically smallest MAC address of all ports on the - bridge)."; - reference - "RFC 4188"; - } - - typedef vlanid { - type uint16 { - range "1..4094"; - } - description - "The vlanid type uniquely identifies a VLAN. This is - the 12-bit VLAN-ID used in the VLAN Tag header. The - range is defined by the referenced specification."; - reference - "IEEE Std 802.1Q 2003 Edition, Virtual Bridged Local - Area Networks."; - } - } - -Appendix B. YIN +10. YIN A YANG module can be specified in an alternative XML-based syntax called YIN. This appendix describes symmetric mapping rules between the two formats. The YANG and YIN formats contain equivalent information using different notations. The purpose of the YIN notation is to allow the user to translate YANG into YIN, use the rich set of XML based tools on the YIN format to transform, or filter the model information. Tools like XSLT or XML validators can be utilized. After this the model can be transformed back to the YANG format if needed, which provides a more concise and readable format. The YANG-2-YIN and the YIN-2-YANG transformations will not modify the information content of the model. -B.1. Formal YIN Definition +10.1. Formal YIN Definition YIN is described by an algorithm that transforms YANG to YIN. -B.2. Transformation Algorithm YANG-2-YIN +10.2. Transformation Algorithm YANG-2-YIN Every keyword results in a new XML element. The name of the element is the keyword. All core YANG elements are defined in the namespace "urn:ietf:params:xml:ns:yang:yin:1". [XXX IANA] The top-level element is always or . Elements which represent keywords that are imported extensions from other modules MUST be properly namespace qualified, where the namespace is the namespace of the imported module. Translators @@ -5202,107 +4601,86 @@ | yin-element | value | false | +---------------+---------------+-------------+ Table 30 If a statement is followed by substatements, those substatements are subelements in the YIN mapping. Comments in YANG MAY be transformed into XML comments. -B.2.1. Usage Example +10.2.1. Usage Example The following YANG snippet: leaf mtu { type uint32; description "The MTU of the interface."; } is translated into the following YIN snippet: The MTU of the interface." -B.3. Transformation Algorithm YIN-2-YANG +10.3. Transformation Algorithm YIN-2-YANG The transformation is based on a recursive algorithm that is started on the or element. The element is transformed into a YANG keyword. If the keyword in Table 30 is marked as yin-element true, the subelement with the keyword's argument name in Table 30 contains the YANG keyword's argument as text content. If the keyword in Table 30 is marked as yin-element false, the element's attribute with keyword's argument name in Table 30 contains the YANG keyword's argument. If there are no other subelements to the element, the YANG statement is closed with a ";". Otherwise, each such subelement is transformed, according to the same algorithm, as substatements to the current YANG statement, enclosed within "{" and "}". XML comments in YIN MAY be transformed into YANG comments. -B.3.1. Tabulation, Formatting +10.3.1. Tabulation, Formatting To get a readable YANG module the YANG output will have to be indented with appropriate whitespace characters. -Appendix C. XML Schema Considerations - - It is possible to generate an XSD document representing the data - model defined in YANG. The XSD will specify the structure of the - model, the used types, cardinality, etc. but a good part of the - information in YANG can not be represented in standard XSD constructs - e.g. config, status, default, keyref. - - The above information will be added to XSD inside annotation - statements (which can not be handled by standard XML tools). The - exact form of annotations is for further study. - - Data models defined in YANG might have multiple top-level elements. - To make it possible to validate the XML encoded data, both for the - generated XSD describing the data model and for the config and state - data received in NETCONF RPCs a single top level element shall - be added. - - From a YANG model, many different XSD schema can be generated - defining the same data model. The exact rules to generate XSD from - YANG are outside the scope of this document, however some general - considerations are needed. - -Appendix D. YANG ABNF Grammar +11. YANG ABNF Grammar In YANG, almost all statements are unordered. The ABNF grammar [RFC5234] defines the canonical order. To improve module readability, it is RECOMMENDED that clauses be entered in this order. Within the ABNF grammar, unordered statements are marked with comments. This grammar assumes that the scanner replaces YANG comments with a single space character. -module-stmt = module-keyword sep identifier-str optsep +module-stmt = optsep module-keyword sep identifier-arg-str + optsep "{" stmtsep module-header-stmts linkage-stmts meta-stmts revision-stmts body-stmts "}" optsep -submodule-stmt = submodule-keyword sep identifier-str optsep +submodule-stmt = optsep submodule-keyword sep identifier-arg-str + optsep "{" stmtsep submodule-header-stmts linkage-stmts meta-stmts revision-stmts body-stmts "}" optsep module-header-stmts = ;; these stmts can appear in any order [yang-version-stmt stmtsep] @@ -5342,122 +4720,129 @@ augment-stmt case-data-def-stmt = container-stmt / leaf-stmt / leaf-list-stmt / list-stmt / anyxml-stmt / uses-stmt / augment-stmt -yang-version-stmt = yang-version-keyword sep "1" optsep stmtend +yang-version-stmt = yang-version-keyword sep yang-version-arg-str + optsep stmtend -import-stmt = import-keyword sep identifier-str optsep +yang-version-arg-str = < a string which matches the rule + yang-version-arg > + +yang-version-arg = "1" + +import-stmt = import-keyword sep identifier-arg-str optsep "{" stmtsep prefix-stmt stmtsep "}" -include-stmt = include-keyword sep identifier-str optsep +include-stmt = include-keyword sep identifier-arg-str optsep stmtend namespace-stmt = namespace-keyword sep uri-str optsep stmtend uri-str = < a string which matches the rule URI in RFC 3986 > -prefix-stmt = prefix-keyword sep prefix-str optsep stmtend +prefix-stmt = prefix-keyword sep prefix-arg-str + optsep stmtend -belongs-to-stmt = belongs-to-keyword sep identifier-str +belongs-to-stmt = belongs-to-keyword sep identifier-arg-str optsep stmtend organization-stmt = organization-keyword sep string optsep stmtend contact-stmt = contact-keyword sep string optsep stmtend description-stmt = description-keyword sep string optsep stmtend reference-stmt = reference-keyword sep string optsep stmtend units-stmt = units-keyword sep string optsep stmtend -revision-stmt = revision-keyword sep date-expr-str optsep +revision-stmt = revision-keyword sep date-arg-str optsep (";" / "{" stmtsep [description-stmt stmtsep] "}") -extension-stmt = extension-keyword sep identifier-str optsep +extension-stmt = extension-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [argument-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") -argument-stmt = argument-keyword sep identifier-str optsep +argument-stmt = argument-keyword sep identifier-arg-str optsep (";" / "{" stmtsep [yin-element-stmt stmtsep] "}") yin-element-stmt = yin-element-keyword sep yin-element-arg-str stmtend yin-element-arg-str = < a string which matches the rule yin-element-arg > yin-element-arg = true-keyword / false-keyword -typedef-stmt = typedef-keyword sep identifier-str optsep +typedef-stmt = typedef-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order type-stmt stmtsep [units-stmt stmtsep] [default-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}" -type-stmt = type-keyword sep identifier-ref-str optsep +type-stmt = type-keyword sep identifier-ref-arg-str optsep (";" / "{" stmtsep ( numerical-restrictions / string-restrictions / enum-specification / keyref-specification / bits-specification / union-specification ) stmtsep "}") numerical-restrictions = range-stmt stmtsep -range-stmt = range-keyword sep range-expr-str optsep +range-stmt = range-keyword sep range-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [error-message-stmt stmtsep] [error-app-tag-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") string-restrictions = ;; these stmts can appear in any order [length-stmt stmtsep] - [pattern-stmt stmtsep] + *(pattern-stmt stmtsep) -length-stmt = length-keyword sep length-expr-str optsep +length-stmt = length-keyword sep length-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [error-message-stmt stmtsep] [error-app-tag-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") pattern-stmt = pattern-keyword sep string optsep @@ -5467,55 +4852,56 @@ [error-message-stmt stmtsep] [error-app-tag-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") default-stmt = default-keyword sep string stmtend enum-specification = 1*(enum-stmt stmtsep) -enum-stmt = enum-keyword sep identifier-str optsep +enum-stmt = enum-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [value-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") keyref-specification = path-stmt stmtsep path-stmt = path-keyword sep path-arg-str stmtend union-specification = 1*(type-stmt stmtsep) bits-specification = 1*(bit-stmt stmtsep) -bit-stmt = bit-keyword sep identifier-str optsep +bit-stmt = bit-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [position-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}" "}") -position-stmt = position-keyword sep position-value-str stmtend +position-stmt = position-keyword sep + position-value-arg-str stmtend -position-value-str = < a string which matches the rule - position-value > +position-value-arg-str = < a string which matches the rule + position-value-arg > -position-value = non-negative-decimal-value +position-value-arg = non-negative-decimal-value status-stmt = status-keyword sep status-arg-str stmtend status-arg-str = < a string which matches the rule status-arg > status-arg = current-keyword / obsolete-keyword / deprecated-keyword @@ -5536,112 +4922,112 @@ mandatory-arg = true-keyword / false-keyword presence-stmt = presence-keyword sep string stmtend ordered-by-stmt = ordered-by-keyword sep ordered-by-arg-str stmtend ordered-by-arg-str = < a string which matches the rule ordered-by-arg > -ordered-by-arg = user-keyword / - system-keyword +ordered-by-arg = user-keyword / system-keyword must-stmt = must-keyword sep string optsep (";" / "{" stmtsep ;; these stmts can appear in any order [error-message-stmt stmtsep] [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-str stmtend; + min-value-arg-str stmtend; -min-value-str = < a string which matches the rule - min-value > +min-value-arg-str = < a string which matches the rule + min-value-arg > -min-value = non-negative-decimal-value +min-value-arg = non-negative-decimal-value max-elements-stmt = max-elements-keyword sep - max-value-str stmtend; + max-value-arg-str stmtend; -max-value-str = < a string which matches the rule - max-value > +max-value-arg-str = < a string which matches the rule + max-value-arg > -max-value = unbounded-keyword / positive-decimal-value +max-value-arg = unbounded-keyword / + positive-decimal-value value-stmt = value-keyword sep decimal-value stmtend -grouping-stmt = grouping-keyword sep identifier-str optsep +grouping-stmt = grouping-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *((typedef-stmt / grouping-stmt) stmtsep) *(data-def-stmt stmtsep) "}") -container-stmt = container-keyword sep identifier-str optsep +container-stmt = container-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [presence-stmt stmtsep] [config-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *((typedef-stmt / grouping-stmt) stmtsep) *(data-def-stmt stmtsep) "}") -leaf-stmt = leaf-keyword sep identifier-str optsep +leaf-stmt = leaf-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order type-stmt stmtsep [units-stmt stmtsep] *(must-stmt stmtsep) [default-stmt stmtsep] [config-stmt stmtsep] [mandatory-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}" -leaf-list-stmt = leaf-list-keyword sep identifier-str optsep +leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order type-stmt stmtsep [units-stmt stmtsep] *(must-stmt stmtsep) [config-stmt stmtsep] [min-elements-stmt stmtsep] [max-elements-stmt stmtsep] [ordered-by-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}" -list-stmt = list-keyword sep identifier-str optsep +list-stmt = list-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [key-stmt stmtsep] *(unique-stmt stmtsep) [config-stmt stmtsep] [min-elements-stmt stmtsep] [max-elements-stmt stmtsep] [ordered-by-stmt stmtsep] [status-stmt stmtsep] @@ -5650,189 +5036,189 @@ *((typedef-stmt / grouping-stmt) stmtsep) 1*(data-def-stmt stmtsep) "}" key-stmt = key-keyword sep key-arg-str stmtend key-arg-str = < a string which matches the rule key-arg > -key-arg = 1*(identifier sep) +key-arg = identifier *(sep identifier) unique-stmt = unique-keyword sep unique-arg-str stmtend unique-arg-str = < a string which matches the rule unique-arg > -unique-arg = 1*(descendant-schema-nodeid 1*sp) +unique-arg = descendant-schema-nodeid + *(sep descendant-schema-nodeid) -choice-stmt = choice-keyword sep identifier-str optsep +choice-stmt = choice-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [default-stmt stmtsep] + [config-stmt stmtsep] [mandatory-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *((short-case-stmt / case-stmt) stmtsep) "}") short-case-stmt = container-stmt / leaf-stmt / leaf-list-stmt / list-stmt / anyxml-stmt -case-stmt = case-keyword sep identifier-str optsep +case-stmt = case-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *(case-data-def-stmt stmtsep) "}") -anyxml-stmt = anyxml-keyword sep identifier-str optsep +anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [config-stmt stmtsep] [mandatory-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") -uses-stmt = uses-keyword sep identifier-ref-str optsep +uses-stmt = uses-keyword sep identifier-ref-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *(refinement-stmt stmtsep) "}") refinement-stmt = refine-container-stmt / refine-leaf-stmt / refine-leaf-list-stmt / refine-list-stmt / refine-choice-stmt / refine-anyxml-stmt -refine-leaf-stmt = leaf-keyword sep identifier-str optsep +refine-leaf-stmt = leaf-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [default-stmt stmtsep] [config-stmt stmtsep] [mandatory-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") -refine-leaf-list-stmt = leaf-list-keyword sep identifier-str optsep +refine-leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [config-stmt stmtsep] [min-elements-stmt stmtsep] [max-elements-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") -refine-list-stmt = list-keyword sep identifier-str optsep +refine-list-stmt = list-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [config-stmt stmtsep] [min-elements-stmt stmtsep] [max-elements-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *(refinement-stmt stmtsep) "}") -refine-choice-stmt = choice-keyword sep identifier-str optsep +refine-choice-stmt = choice-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [default-stmt stmtsep] [mandatory-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *(refine-case-stmt stmtsep) "}") -refine-case-stmt = case-keyword sep identifier-str optsep +refine-case-stmt = case-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [description-stmt stmtsep] [reference-stmt stmtsep] *(refinement-stmt stmtsep) "}") -refine-container-stmt = container-keyword sep identifier-str optsep +refine-container-stmt = container-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order *(must-stmt stmtsep) [presence-stmt stmtsep] [config-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *(refinement-stmt stmtsep) "}") -refine-anyxml-stmt = anyxml-keyword sep identifier-str optsep +refine-anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [config-stmt stmtsep] [mandatory-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] "}") unknown-statement = prefix ":" identifier [sep string] optsep (";" / "{" *unknown-statement "}") augment-stmt = augment-keyword sep augment-arg-str optsep "{" stmtsep ;; these stmts can appear in any order [when-stmt stmtsep] [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] - (([input-stmt stmtsep] - [output-stmt stmtsep]) / 1*((data-def-stmt stmtsep) / - (case-stmt stmtsep))) + (case-stmt stmtsep)) "}" augment-arg-str = < a string which matches the rule augment-arg > augment-arg = absolute-schema-nodeid / descendant-schema-nodeid when-stmt = when-keyword sep string stmtend -rpc-stmt = rpc-keyword sep identifier-str optsep +rpc-stmt = rpc-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *((typedef-stmt / grouping-stmt) stmtsep) [input-stmt stmtsep] [output-stmt stmtsep] @@ -5847,68 +5233,66 @@ "}" output-stmt = output-keyword optsep "{" stmtsep ;; these stmts can appear in any order *((typedef-stmt / grouping-stmt) stmtsep) 1*(data-def-stmt stmtsep) "}" -notification-stmt = notification-keyword sep identifier-str optsep +notification-stmt = notification-keyword sep + identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt stmtsep] [description-stmt stmtsep] [reference-stmt stmtsep] *((typedef-stmt / grouping-stmt) stmtsep) *(data-def-stmt stmtsep) "}") ;; Ranges -range-expr-str = < a string which matches the rule - range-expr > +range-arg-str = < a string which matches the rule + range-arg > -range-expr = optsep range-part - *(optsep "|" optsep range-part) - optsep +range-arg = range-part *(optsep "|" optsep range-part) range-part = range-boundary [optsep ".." optsep range-boundary] range-boundary = neginf-keyword / posinf-keyword / min-keyword / max-keyword / decimal-value / float-value ;; Lengths -length-expr-str = < a string which matches the rule - length-expr > +length-arg-str = < a string which matches the rule + length-arg > -length-expr = optsep length-part *(optsep "|" - optsep length-part) optsep +length-arg = length-part *(optsep "|" optsep length-part) length-part = length-boundary [optsep ".." optsep length-boundary] length-boundary = min-keyword / max-keyword / non-negative-decimal-value ;; Date -date-expr-str = < a string which matches the rule - date-expr > +date-arg-str = < a string which matches the rule + date-arg > -date-expr = 4DIGIT "-" 2DIGIT "-" 2DIGIT +date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT ;; Schema Node Identifiers schema-nodeid = absolute-schema-nodeid / relative-schema-nodeid absolute-schema-nodeid = 1*("/" node-identifier) relative-schema-nodeid @@ -5921,22 +5305,21 @@ absolute-schema-nodeid node-identifier = [prefix ":"] identifier ;; Instance Identifiers instance-identifier-str = < a string which matches the rule instance-identifier > -instance-identifier = absolute-instid / - relative-instid +instance-identifier = absolute-instid / relative-instid absolute-instid = 1*("/" (node-identifier *predicate)) relative-instid = descendant-instid / (("." / "..") "/" *relative-instid) descendant-instid = node-identifier *predicate absolute-instid @@ -5944,31 +5327,30 @@ predicate-expr = (node-identifier / ".") *WSP "=" *WSP ((DQUOTE string DQUOTE) / (SQUOTE string SQUOTE)) ;; keyref path path-arg-str = < a string which matches the rule path-arg > -path-arg = absolute-path-arg / - relative-path-arg +path-arg = absolute-path / relative-path -absolute-path-arg = 1*("/" (node-identifier *path-predicate)) +absolute-path = 1*("/" (node-identifier *path-predicate)) -relative-path-arg = descendant-path-arg / +relative-path = descendant-path / (".." "/" - *relative-path-arg) + *relative-path) -descendant-path-arg = node-identifier *path-predicate - absolute-path-arg +descendant-path = node-identifier *path-predicate + absolute-path path-predicate = "[" *WSP path-equality-expr *WSP "]" path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr path-key-expr = this-variable-keyword "/" rel-path-keyexpr rel-path-keyexpr = 1*(".." "/") *(node-identifier "/") node-identifier @@ -6047,35 +5429,39 @@ system-keyword = 'system' this-variable-keyword = '$this' true-keyword = 'true' unbounded-keyword = 'unbounded' user-keyword = 'user' ;; Basic Rules keyword = [prefix ":"] identifier -prefix-str = < a string which matches the rule - prefix > +prefix-arg-str = < a string which matches the rule + prefix-arg > + +prefix-arg = prefix prefix = identifier -identifier-str = < a string which matches the rule - identifier > +identifier-arg-str = < a string which matches the rule + identifier-arg > + +identifier-arg = identifier identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_" / "-" / ".") -identifier-ref-str = < a string which matches the rule - identifier-ref +identifier-ref-arg-str = < a string which matches the rule + identifier-ref-arg > -identifier-ref = [prefix ":"] identifier +identifier-ref-arg = [prefix ":"] identifier string = < an unquoted string as returned by the scanner > decimal-value = ("-" non-negative-decimal-value) / non-negative-decimal-value non-negative-decimal-value = "0" / positive-decimal-value positive-decimal-value = (non-zero-digit *DIGIT) @@ -6135,192 +5521,244 @@ SP = %x20 ; space VCHAR = %x21-7E ; visible (printing) characters WSP = SP / HTAB ; white space -Appendix E. Error Responses for YANG Related Errors +12. 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. -E.1. Error Message for Data that Violates a YANG unique Statement: +12.1. Error Message for Data that Violates a YANG 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" [XXX IANA]). -E.2. Error Message for Data that Violates a YANG max-elements +12.2. Error Message for Data that Violates a YANG 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 -E.3. Error Message for Data that Violates a YANG min-elements + This error is returned once, with the error-path identifying the list + node, even if there are more than one extra child present. + +12.3. Error Message for Data that Violates a YANG 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 -E.4. Error Message for Data that Violates a YANG must or when - statement, a length, range or pattern restriction: + This error is returned once, with the error-path identifying the list + node, even if there are more than one child missing. + +12.4. Error Message for Data that Violates a YANG must statement: If a NETCONF operation would result in configuration data where the - restrictions imposed by a "must", "when", "length", "range" or - "pattern" statement is violated the following error is returned: + 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: data-restriction-violation + Error-app-tag: must-violation -E.5. Error Message for the "insert" Operation +12.5. 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 -Appendix F. Why We Need a New Modeling Language +13. IANA Considerations - There have been many discussions about whether the IETF should design - its own language or use an existing one. The YANG designers believe - strongly that existing languages are not the right answer. + This document registers two URIs for the YANG XML namespace in the + IETF XML registry [RFC3688]. - YANG is based on languages used actively for development of NETCONF- - based management systems. As such, the design of YANG is based - heavily on requirements placed upon those languages by their users - and the experience of writing NETCONF data models in vendor specific - languages. + URI: urn:ietf:params:xml:ns:yang:yin:1 - During previous implementations that were input to YANG, developers - realized that they didn't want to read or write data models written - with XSD (or RelaxNG or RelaxNG compact), so the languages were based - on something "home grown" designed for the developers who would be - writing models and implementing them on devices. + URI: urn:ietf:params:xml:ns:yang:1 -F.1. Why not XSD? +14. Security Considerations - There are several reasons for not using XSD, such as: + 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. - o XSD is too expressive, and gives too much freedom in allowable XML - content. Without restrictions on its use and very clear - guidelines, we think it will be very difficult to make - interoperable XSD models. For example, there are constructs such - as xs:redefine that would have to be disallowed. + Data modeled in YANG might contain sensitive information. RPCs or + notifications defined in YANG might transfer sensitive information. - o XSD is not expressive enough for NETCONF data modeling. - Additional semantics, such as state vs. config, integrity - constraints, error-messages, list order semantics, remote - procedure call and remote procedure call parameter definitions, - and notification definitions would have to be put in appinfo - elements, essentially creating a new language contained in appinfo - elements. + 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. - o Operators and developers want models that are simple to read and - text-based. XSD is very difficult to read and debug. In the - NETCONF work, obvious bugs in the relatively simple protocol XSD - went undetected for years. The phrase many seem to use is that - XSD is "write-only". + YANG is dependent upon: - o Defenders of XSD often counter claims of complexity with - availability of advanced tools, but the IETF cannot require such - tools to read/write models. Rather, the IETF needs a simpler - language that is text-based, patch-friendly, and grep-able. + o the security of the transmission infrastructure used to send + sensitive information - o From a process perspective, the IETF lacks any IETF change control - and real input into the update process for XSD. + o the security of applications which store or release such sensitive + information. - Does all of this mean that XSD has no place in the NETCONF management - picture? Clearly, the answer is no. XSD is an excellent formal - description mechanism that applications can consume. XSD can be - generated from the models defined in YANG. + o adequate authentication and access control mechanisms to restrict + the usage of sensitive data. -F.2. Why not RelaxNG +15. Contributors - RelaxNG is considered by many people a much simpler to understand and - to use schema notation for XML documents compared to XSD. However, - the reasons for not using RelaxNG are similar as for XSD: + The following people all contributed significantly to the initial + YANG draft: - o RelaxNG is like XSD too expressive and gives too much freedom in - allowable XML content (see above). + - Andy Bierman (andybierman.com) + - Balazs Lengyel (Ericsson) + - David Partain (Ericsson) + - Juergen Schoenwaelder (Jacobs University Bremen) + - Phil Shafer (Juniper Networks) - o RelaxNG is like XSD not expressive enough for NETCONF data - modeling (see above). +16. References - o While RelaxNG may be simpler to read (especially the compact - notation), when fully annotated with all needed features, it will - likely become as difficult to read as XSD. +16.1. Normative References - o The IETF has no change control over RelaxNG. + [IEEE.754] + Institute of Electrical and Electronics Engineers, + "Standard for Binary Floating-Point Arithmetic", + IEEE Standard 754, August 1985. - Like in the XSD case, it will be possible to generate RelaxNG from - the models defined in YANG for the purpose to feed RelaxNG tools. - But this will only cover the information needed to validate instance - documents and some NETCONF specific information will be lost or - buried in extensions generic tools will not understand. + [ISO.10646] + International Organization for Standardization, + "Information Technology - Universal Multiple-octet coded + Character Set (UCS) - Part 1: Architecture and Basic + Multilingual Plane", ISO Standard 10646-1, May 1993. -F.3. Why not SMIng + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. - SMIng has been designed to be protocol independent so that SMIng data - models can be used with several management protocols. This is - achieved by avoiding protocol details in the data model and by - providing protocol binding information in so called protocol - mappings. Unfortunately, protocol independence does not came for - free and introduces complexity: + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. - o Protocol independence requires to work with an abstract naming - system for managed objects which complicates the construction of - data models and their mappings. + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. - o Error and exception handling can only be specified in abstract - term in protocol independent data models. + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. - o Management protocols have different features to express - persistency of (changes to) management objects. + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. - o All the items listed above make it non-trivial to write and review - truly protocol independent data models. + [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, + December 2006. - A NETCONF specific data modeling language like YANG makes it much - easier to describe data models in a way that maps to NETCONF in a - very straight-forward manner and has therefore been chosen as the - best approach. Note that the design of YANG actually borrows heavily - from the SMIng work. + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. -Appendix G. ChangeLog + [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event + Notifications", RFC 5277, July 2008. -G.1. Version -00 + [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. + +16.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. + +Appendix A. ChangeLog + +A.1. 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. + + o Moved "Appendix E. Error Responses for YANG Related Errors" into + its own section. + + o The "input" and "output" nodes are now implicitly created by the + "rpc" statement, in order for augmentation of these nodes to work + correctly. + + o Allow "config" in "choice". + + o Added reference to XPath 1.0. + + o Using an XPath function "current()" instead of the variable + "$this". + + o Clarified that a "must" expression in a configuration node must + not reference non-configuration nodes. + + o Added XML encoding rules and usage examples for rpc and + notification. + + o Removed requirement that refinements are specified in the same + order as in the original grouping's definition. + + 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.2. 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