--- 1/draft-ietf-netmod-rfc6020bis-04.txt 2015-05-04 01:14:54.810061509 -0700 +++ 2/draft-ietf-netmod-rfc6020bis-05.txt 2015-05-04 01:14:55.130069274 -0700 @@ -1,20 +1,20 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Obsoletes: 6020 (if approved) March 9, 2015 +Obsoletes: 6020 (if approved) May 4, 2015 Intended status: Standards Track -Expires: September 10, 2015 +Expires: November 5, 2015 YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) - draft-ietf-netmod-rfc6020bis-04 + draft-ietf-netmod-rfc6020bis-05 Abstract YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. This document obsoletes RFC 6020. Status of This Memo @@ -24,21 +24,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months 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." - This Internet-Draft will expire on September 10, 2015. + This Internet-Draft will expire on November 5, 2015. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -59,309 +59,315 @@ not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 12 - 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 - 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 - 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 - 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 + 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13 + 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 + 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 + 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 - 4.2.3. State 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 - 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23 - 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 24 - 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25 - 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 26 - 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 26 - 5.1.1. Import and Include by Revision . . . . . . . . . . . 27 - 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28 - 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29 - 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30 - 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30 - 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30 - 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30 - 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31 - 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 32 - 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32 - 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32 + 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 + 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20 + 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 + 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 + 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 + 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25 + 4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 + 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 + 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 + 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 + 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 + 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 + 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 + 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 + 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 + 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 + 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 + 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 + 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 + 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 5.6.4. Announcing Conformance Information in the - Message . . . . . . . . . . . . . . . . . . . . . . . 33 - 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 33 - 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 34 - 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 34 - 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 34 - 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 34 - 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 34 - 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 36 - 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 36 - 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 37 - 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 37 - 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 38 - 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 38 - 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 40 - 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40 - 7.1. The module Statement . . . . . . . . . . . . . . . . . . 41 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 42 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 43 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 44 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 44 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 44 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 45 - 7.1.7. The organization Statement . . . . . . . . . . . . . 46 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 46 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 46 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 47 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 48 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 49 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 50 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 51 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 51 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 52 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 52 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 52 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 52 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 53 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 53 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 53 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 53 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 54 - 7.5.2. The container's Substatements . . . . . . . . . . . . 54 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 55 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 56 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 57 - 7.5.6. The container's Child Node Statements . . . . . . . . 57 - 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 57 - 7.5.8. NETCONF Operations . . . . . . . . . . 58 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 58 - 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 59 - 7.6.1. The leaf's default value . . . . . . . . . . . . . . 60 - 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 60 - 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 61 - 7.6.4. The leaf's default Statement . . . . . . . . . . . . 61 - 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 61 - 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 - 7.6.7. NETCONF Operations . . . . . . . . . . 62 - 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 62 - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 63 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 63 - 7.7.2. The leaf-list's default values . . . . . . . . . . . 64 - 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 65 - 7.7.4. The leaf-list's default Statement . . . . . . . . . . 65 - 7.7.5. The min-elements Statement . . . . . . . . . . . . . 65 - 7.7.6. The max-elements Statement . . . . . . . . . . . . . 66 - 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 66 - 7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 67 - 7.7.9. NETCONF Operations . . . . . . . . . . 67 - 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 68 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 70 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 70 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 71 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 72 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 73 - 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 73 - 7.8.6. NETCONF Operations . . . . . . . . . . 74 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 75 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 78 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 78 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 79 - 7.9.3. The choice's default Statement . . . . . . . . . . . 80 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 82 - 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 - 7.9.6. NETCONF Operations . . . . . . . . . . 82 - 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 82 - 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 83 - 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 84 - 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 84 - 7.10.3. NETCONF Operations . . . . . . . . . . 84 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 85 - 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 85 - 7.11.1. The grouping's Substatements . . . . . . . . . . . . 86 - 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . 86 - 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 87 - 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 87 - 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 87 - 7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 88 - 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 88 - 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 90 - 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . 90 - 7.13.2. The input Statement . . . . . . . . . . . . . . . . 90 - 7.13.3. The output Statement . . . . . . . . . . . . . . . . 91 - 7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 92 - 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . 93 - 7.14. The action Statement . . . . . . . . . . . . . . . . . . 93 - 7.14.1. The action's Substatements . . . . . . . . . . . . . 94 - 7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 94 - 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . 95 - 7.15. The notification Statement . . . . . . . . . . . . . . . 96 - 7.15.1. The notification's Substatements . . . . . . . . . . 97 + Message . . . . . . . . . . . . . . . . . . . . . . . 34 + 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 34 + 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 35 + 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 35 + 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 35 + 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 35 + 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 35 + 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 37 + 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 37 + 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 38 + 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 38 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39 + 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 39 + 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 41 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 41 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 42 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 43 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 44 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 45 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 45 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 45 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 46 + 7.1.7. The organization Statement . . . . . . . . . . . . . 47 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 47 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 47 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 48 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 49 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 50 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 51 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 52 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 52 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 53 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 53 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 53 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 53 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 54 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 54 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 54 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 54 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 55 + 7.5.2. The container's Substatements . . . . . . . . . . . . 55 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 56 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 57 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 58 + 7.5.6. The container's Child Node Statements . . . . . . . . 58 + 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 58 + 7.5.8. NETCONF Operations . . . . . . . . . . 59 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 59 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 60 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 61 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 61 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 62 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 62 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 62 + 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 62 + 7.6.7. NETCONF Operations . . . . . . . . . . 63 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 63 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 64 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 64 + 7.7.2. The leaf-list's default values . . . . . . . . . . . 65 + 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 66 + 7.7.4. The leaf-list's default Statement . . . . . . . . . . 66 + 7.7.5. The min-elements Statement . . . . . . . . . . . . . 66 + 7.7.6. The max-elements Statement . . . . . . . . . . . . . 67 + 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 67 + 7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 68 + 7.7.9. NETCONF Operations . . . . . . . . . . 68 + 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 69 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 71 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 71 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 72 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 73 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 74 + 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 74 + 7.8.6. NETCONF Operations . . . . . . . . . . 75 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 76 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 79 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 79 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 80 + 7.9.3. The choice's default Statement . . . . . . . . . . . 81 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 83 + 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 83 + 7.9.6. NETCONF Operations . . . . . . . . . . 83 + 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 83 + 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 84 + 7.10.1. The anydata's Substatements . . . . . . . . . . . . 85 + 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 85 + 7.10.3. NETCONF Operations . . . . . . . . . . 85 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 86 + 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 86 + 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 87 + 7.11.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 87 + 7.11.3. NETCONF Operations . . . . . . . . . . 87 + 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 88 + 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 88 + 7.12.1. The grouping's Substatements . . . . . . . . . . . . 89 + 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 89 + 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 90 + 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 90 + 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 90 + 7.13.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 91 + 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 91 + 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 93 + 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 93 + 7.14.2. The input Statement . . . . . . . . . . . . . . . . 93 + 7.14.3. The output Statement . . . . . . . . . . . . . . . . 94 + 7.14.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 95 + 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 96 + 7.15. The action Statement . . . . . . . . . . . . . . . . . . 96 + 7.15.1. The action's Substatements . . . . . . . . . . . . . 97 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 97 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 97 - 7.16. The augment Statement . . . . . . . . . . . . . . . . . . 98 - 7.16.1. The augment's Substatements . . . . . . . . . . . . 99 - 7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 99 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 99 - 7.17. The identity Statement . . . . . . . . . . . . . . . . . 101 - 7.17.1. The identity's Substatements . . . . . . . . . . . . 101 - 7.17.2. The base Statement . . . . . . . . . . . . . . . . . 102 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 102 - 7.18. The extension Statement . . . . . . . . . . . . . . . . . 103 - 7.18.1. The extension's Substatements . . . . . . . . . . . 104 - 7.18.2. The argument Statement . . . . . . . . . . . . . . . 104 - 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 105 - 7.19. Conformance-Related Statements . . . . . . . . . . . . . 105 - 7.19.1. The feature Statement . . . . . . . . . . . . . . . 105 - 7.19.2. The if-feature Statement . . . . . . . . . . . . . . 107 - 7.19.3. The deviation Statement . . . . . . . . . . . . . . 108 - 7.20. Common Statements . . . . . . . . . . . . . . . . . . . . 110 - 7.20.1. The config Statement . . . . . . . . . . . . . . . . 110 - 7.20.2. The status Statement . . . . . . . . . . . . . . . . 111 - 7.20.3. The description Statement . . . . . . . . . . . . . 112 - 7.20.4. The reference Statement . . . . . . . . . . . . . . 112 - 7.20.5. The when Statement . . . . . . . . . . . . . . . . . 112 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 113 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 113 - 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 114 - 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 114 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 114 - 8.3.2. NETCONF Processing . . . . . . . . . . 115 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 116 - 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 116 - 9.1. Canonical Representation . . . . . . . . . . . . . . . . 116 - 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 117 - 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 117 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 118 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 118 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119 - 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 119 - 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 120 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 120 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 - 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 121 - 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 121 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 122 - 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 123 - 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 123 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 123 - 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 124 - 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 125 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 - 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 125 - 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 125 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 125 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 - 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 128 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 128 - 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 128 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 128 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 128 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 - 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 130 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 130 - 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 130 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 130 - 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 130 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 131 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 131 - 9.9.3. The require-instance Statement . . . . . . . . . . . 131 - 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 132 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 132 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 132 - 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 136 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 - 9.10.2. The identityref's base Statement . . . . . . . . . . 136 - 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 136 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 137 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 137 - 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 138 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 138 - 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 138 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 138 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 138 - 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 139 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 139 - 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 139 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 139 - 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 139 - 9.13. The instance-identifier Built-In Type . . . . . . . . . . 140 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 141 - 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 141 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 141 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 141 - 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 142 - 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 142 - 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 142 - 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 142 - 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 142 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 98 + 7.16. The notification Statement . . . . . . . . . . . . . . . 99 + 7.16.1. The notification's Substatements . . . . . . . . . . 100 + 7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 100 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 101 + 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 102 + 7.17.1. The augment's Substatements . . . . . . . . . . . . 103 + 7.17.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 104 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 104 + 7.18. The identity Statement . . . . . . . . . . . . . . . . . 106 + 7.18.1. The identity's Substatements . . . . . . . . . . . . 106 + 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 106 + 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 + 7.19. The extension Statement . . . . . . . . . . . . . . . . . 107 + 7.19.1. The extension's Substatements . . . . . . . . . . . 108 + 7.19.2. The argument Statement . . . . . . . . . . . . . . . 108 + 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 + 7.20. Conformance-Related Statements . . . . . . . . . . . . . 109 + 7.20.1. The feature Statement . . . . . . . . . . . . . . . 109 + 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 111 + 7.20.3. The deviation Statement . . . . . . . . . . . . . . 112 + 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 114 + 7.21.1. The config Statement . . . . . . . . . . . . . . . . 114 + 7.21.2. The status Statement . . . . . . . . . . . . . . . . 115 + 7.21.3. The description Statement . . . . . . . . . . . . . 116 + 7.21.4. The reference Statement . . . . . . . . . . . . . . 116 + 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 116 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 117 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 117 + 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 118 + 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 118 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 118 + 8.3.2. NETCONF Processing . . . . . . . . . . 119 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 120 + 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 120 + 9.1. Canonical Representation . . . . . . . . . . . . . . . . 120 + 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 121 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 121 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 122 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 122 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 122 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 123 + 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 123 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 124 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 124 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 124 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 124 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 125 + 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 125 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 125 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 126 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 126 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 126 + 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 127 + 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 127 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 127 + 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 128 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 129 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 129 + 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 129 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 129 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 129 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 129 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130 + 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 132 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 132 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 132 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 132 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 + 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 134 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 134 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 134 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 135 + 9.9.3. The require-instance Statement . . . . . . . . . . . 135 + 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 136 + 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 136 + 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 136 + 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 140 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 140 + 9.10.2. The identityref's base Statement . . . . . . . . . . 140 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 140 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 141 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 141 + 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 142 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 142 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 142 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 142 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 142 + 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 143 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 143 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 143 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 143 + 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 143 + 9.13. The instance-identifier Built-In Type . . . . . . . . . . 144 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 + 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 145 + 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 + 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 145 + 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 146 + 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 146 + 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 146 + 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 146 + 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 146 10.3. Functions for the YANG Types "leafref" and "instance- - identifier" . . . . . . . . . . . . . . . . . . . . . . 143 - 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 143 - 10.4. Functions for the YANG Type "identityref" . . . . . . . 144 - 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 144 - 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 144 - 10.5. Functions for the YANG Type "enumeration" . . . . . . . 145 - 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 145 - 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 146 - 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 146 - 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 147 - 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 - 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 150 - 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 152 - 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 153 - 14. Error Responses for YANG Related Errors . . . . . . . . . . . 177 - 14.1. Error Message for Data That Violates a unique Statement 177 + identifier" . . . . . . . . . . . . . . . . . . . . . . 147 + 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 147 + 10.4. Functions for the YANG Type "identityref" . . . . . . . 148 + 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 148 + 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 148 + 10.5. Functions for the YANG Type "enumeration" . . . . . . . 149 + 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 149 + 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 150 + 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 150 + 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 151 + 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 + 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 154 + 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 156 + 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 157 + 14. Error Responses for YANG Related Errors . . . . . . . . . . . 181 + 14.1. Error Message for Data That Violates a unique Statement 181 14.2. Error Message for Data That Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 177 + Statement . . . . . . . . . . . . . . . . . . . . . . . 182 + 14.3. Error Message for Data That Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 177 - 14.4. Error Message for Data That Violates a must Statement . 178 + Statement . . . . . . . . . . . . . . . . . . . . . . . 182 + 14.4. Error Message for Data That Violates a must Statement . 182 14.5. Error Message for Data That Violates a require-instance - Statement . . . . . . . . . . . . . . . . . . . . . . . 178 - + Statement . . . . . . . . . . . . . . . . . . . . . . . 183 14.6. Error Message for Data That Does Not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 178 + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 183 14.7. Error Message for Data That Violates a mandatory choice - Statement . . . . . . . . . . . . . . . . . . . . . . . 178 - 14.8. Error Message for the "insert" Operation . . . . . . . . 179 - 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 179 - 15.1. Media type application/yang . . . . . . . . . . . . . . 180 - 15.2. Media type application/yin+xml . . . . . . . . . . . . . 181 - 16. Security Considerations . . . . . . . . . . . . . . . . . . . 183 - 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 183 - 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 184 - 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 184 - 19.1. Version -04 . . . . . . . . . . . . . . . . . . . . . . 184 - 19.2. Version -03 . . . . . . . . . . . . . . . . . . . . . . 184 - 19.3. Version -02 . . . . . . . . . . . . . . . . . . . . . . 184 - 19.4. Version -01 . . . . . . . . . . . . . . . . . . . . . . 185 - 19.5. Version -00 . . . . . . . . . . . . . . . . . . . . . . 185 - 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 185 - 20.1. Normative References . . . . . . . . . . . . . . . . . . 185 - 20.2. Informative References . . . . . . . . . . . . . . . . . 187 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 187 + Statement . . . . . . . . . . . . . . . . . . . . . . . 183 + 14.8. Error Message for the "insert" Operation . . . . . . . . 183 + 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 184 + 15.1. Media type application/yang . . . . . . . . . . . . . . 185 + 15.2. Media type application/yin+xml . . . . . . . . . . . . . 186 + 16. Security Considerations . . . . . . . . . . . . . . . . . . . 188 + 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 188 + 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 189 + 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 189 + 19.1. Version -05 . . . . . . . . . . . . . . . . . . . . . . 189 + 19.2. Version -04 . . . . . . . . . . . . . . . . . . . . . . 189 + 19.3. Version -03 . . . . . . . . . . . . . . . . . . . . . . 189 + 19.4. Version -02 . . . . . . . . . . . . . . . . . . . . . . 190 + 19.5. Version -01 . . . . . . . . . . . . . . . . . . . . . . 190 + 19.6. Version -00 . . . . . . . . . . . . . . . . . . . . . . 190 + 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 190 + 20.1. Normative References . . . . . . . . . . . . . . . . . . 191 + 20.2. Informative References . . . . . . . . . . . . . . . . . 192 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 193 1. Introduction YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. YANG is used to model the operations and content layers of NETCONF (see the NETCONF Configuration Protocol [RFC6241], Section 1.2). This document describes the syntax and semantics of the YANG @@ -370,30 +376,30 @@ are used to manipulate the data. 1.1. Summary of Changes from RFC 6020 This document defines version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification [RFC6020]. o Changed the YANG version from "1" to "1.1". + o Made the "yang-version" statement mandatory. + o Made noncharacters illegal in the built-in type "string". o Defined the legal characters in YANG modules. - o Made the "yang-version" statement mandatory. - o Changed the rules for the interpretation of escaped characters in double quoted strings. This is an backwards incompatible change - from YANG 1.0. A module that uses a character sequence that is - now illegal must change the string to match the new rules. See + from YANG version 1. A module that uses a character sequence that + is now illegal must change the string to match the new rules. See Section 6.1.3 for details. o Extended the "if-feature" syntax to be a boolean expression over feature names. o Allow "if-feature" in "bit", "enum", and "identity". o Allow "if-feature" in "refine". o Made "when" and "if-feature" illegal on list keys, unless the @@ -411,48 +417,56 @@ o Clarified the XPath context's tree in Section 6.4.1. o Defined the string value of an identityref in XPath expressions (see Section 9.10). o Clarified what unprefixed names means in leafrefs in typedefs (see Section 9.9.2). o Allow identities to be derived from multiple base identities (see - Section 7.17 and Section 9.10). + Section 7.18 and Section 9.10). o Allow enumerations to be subtyped (see Section 9.6). o Allow leaf-lists to have default values (see Section 7.7.2). o Use [RFC7405] syntax for case-sensitive strings in the grammar. o Changed the module advertisement mechanism (see Section 5.6.4). o Changed the scoping rules for definitions in submodules. A submodule can now reference all defintions in all submodules that belong to the same module, without using the "include" statement. o Added a new statement "action" that is used to define operations tied to data nodes. + o Allow notifications to be tied to data nodes. + + o Added a new data definition statement "anydata" (see + Section 7.10). + 2. Keywords The keywords "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 action: An operation defined for a node in the data tree. + o anydata: A data node that can contain an unknown set of nodes that + can be modelled by YANG. + o anyxml: A data node that can contain an unknown chunk of XML data. o augment: Adds new schema nodes to a previously defined schema 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. @@ -466,27 +480,28 @@ o conformance: A measure of how accurately a device follows a data model. o container: An interior data node that exists in at most one instance in the data tree. A container has no value, but rather a set of child nodes. o data definition statement: A statement that defines new data nodes. One of container, leaf, leaf-list, list, choice, case, - augment, uses, and anyxml. + augment, uses, anydata, and anyxml. o data model: A data model describes how data is represented and accessed. o data node: A node in the schema tree that can be instantiated in a - data tree. One of container, leaf, leaf-list, list, and anyxml. + data tree. One of container, leaf, leaf-list, list, anydata, and + anyxml. o data tree: The instantiated tree of configuration and state data on a device. o derived type: A type that is derived from a built-in type (such as uint32), or another derived type. o device deviation: A failure of the device to implement the module faithfully. @@ -526,51 +541,52 @@ o module: A YANG module defines a hierarchy of nodes that can be used for NETCONF-based operations. With its definitions and the definitions it imports or includes from elsewhere, a module is self-contained and "compilable". o RPC: A Remote Procedure Call, as used within the NETCONF protocol. o RPC operation: A specific Remote Procedure Call, as used within the NETCONF protocol. It is 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, notification, - and anyxml. + o schema node: A node in the schema tree. One of action, container, + leaf, leaf-list, list, choice, case, rpc, input, output, + notification, anydata, and anyxml. 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 [RFC6241]. o submodule: A partial module definition that contributes derived - types, groupings, data nodes, RPCs, and notifications to a module. - A YANG module can be constructed from a number of submodules. + types, groupings, data nodes, RPCs, actions, and notifications to + a module. A YANG module can be constructed from a number of + submodules. o top-level data node: A data node where there is no other data node between it and a module or submodule statement. o uses: The "uses" statement is used to instantiate the set of schema nodes defined in a grouping statement. The instantiated nodes may be refined and augmented to tailor them to any specific needs. 3.1. Mandatory Nodes A mandatory node is one of: - o A leaf, choice, or anyxml node with a "mandatory" statement with - the value "true". + o A leaf, choice, anydata, or anyxml node with a "mandatory" + statement with the value "true". o A list or leaf-list node with a "min-elements" statement with a value greater than zero. o A container node without a "presence" statement, which has at least one mandatory node as a child. 4. YANG Overview 4.1. Functional Overview @@ -1001,21 +1017,21 @@ refine "address" { description "Destination IP address"; } refine "port" { description "Destination port number"; } } } } - The "grouping" statement is covered in Section 7.11. + The "grouping" statement is covered in Section 7.12. 4.2.7. Choices YANG allows the data model to segregate incompatible nodes into distinct choices using the "choice" and "case" statements. The "choice" statement contains a set of "case" statements that define sets of schema nodes that cannot appear together. Each "case" may contain multiple nodes, but each node may appear in only one "case" under a "choice". @@ -1093,21 +1109,21 @@ NETCONF XML Example: alicew Alice N. Wonderland drop-out 1024 - The "augment" statement is covered in Section 7.16. + The "augment" statement is covered in Section 7.17. 4.2.9. Operation Definitions YANG allows the definition of operations. The operations' names, input parameters, and output parameters are modeled using YANG data definition statements. Operations on the top-level in a module are defined with the "rpc" statement. Operations can also be tied to a node in the data hierarchy. Such operations are defined with the "action" statement. @@ -1135,22 +1151,22 @@ The image acmefw-2.3 is being installed. - The "rpc" statement is covered in Section 7.13, and the "action" - statement in Section 7.14. + The "rpc" statement is covered in Section 7.14, and the "action" + statement in Section 7.15. 4.2.10. Notification Definitions YANG allows the definition of notifications suitable for NETCONF. YANG data definition statements are used to model the content of the notification. YANG Example: notification link-failure { @@ -1173,21 +1189,21 @@ 2007-09-01T10:00:00Z so-1/2/3.0 up down - The "notification" statement is covered in Section 7.15. + The "notification" statement is covered in Section 7.16. 5. Language Concepts 5.1. Modules and Submodules The module is the base unit of definition in YANG. A module defines a single data model. A module can define a complete, cohesive model, or augment an existing data model with additional nodes. Submodules are partial modules that contribute definitions to a @@ -1197,21 +1213,21 @@ The names of all standard modules and submodules MUST be unique. Developers of enterprise modules are RECOMMENDED to choose names for their modules that will have a low probability of colliding with standard or other enterprise modules, e.g., by using the enterprise or organization name as a prefix for the module name. A module uses the "include" statement to include all its submodules, and the "import" statement to reference external modules. Similarly, a submodule uses the "import" statement to reference other modules. - For backwards compatibility with YANG version 1, a submodule is + For backward compatibility with YANG version 1, a submodule is allowed it use the "include" statement to reference other submodules within its module, but this is not necessary in YANG version 1.1. A submodule can reference any definition in the module it belongs to and in all submodules included by the module. A module or submodule MUST NOT include submodules from other modules, and a submodule MUST NOT import its own module. The import and include statements are used to make definitions available from other modules: @@ -1467,21 +1483,21 @@ strings, and may make portions of the module optional based on those features. If the device supports a feature, then the corresponding portions of the module are valid for that device. If the device doesn't support the feature, those parts of the module are not valid, and applications should behave accordingly. Features are defined using the "feature" statement. Definitions in the module that are conditional to the feature are noted by the "if-feature" statement. - Further details are available in Section 7.19.1. + Further details are available in Section 7.20.1. 5.6.3. Deviations In an ideal world, all devices would be required to implement the model exactly as defined, and deviations from the model would not be allowed. But in the real world, devices are often not able or designed to implement the model as written. For YANG-based automation to deal with these device deviations, a mechanism must exist for devices to inform applications of the specifics of such deviations. @@ -1493,40 +1509,40 @@ would be far better if the application had prior knowledge of this limitation and could prevent the user from starting down the path that could not succeed. Device deviations are declared using the "deviation" statement, which takes as its argument a string that identifies a node in the schema tree. The contents of the statement details the manner in which the device implementation deviates from the contract as defined in the module. - Further details are available in Section 7.19.3. + Further details are available in Section 7.20.3. 5.6.4. Announcing Conformance Information in the Message This document defines the following mechanism for announcing conformance information. Other mechanisms may be defined by future specificiations. A NETCONF server announces the modules it implements by implementing the YANG module "ietf-yang-library" defined in [I-D.ietf-netconf-yang-library]. The server also advertises the following capability in the message (line-breaks and whitespaces are used for formatting reasons only): urn:ietf:params:netconf:capability:yang-library:1.0? module-set-id= - The parameter "module-set-id" has the same value as the leaf - "/modules/module-set-id" from "ietf-yang-library". This parameter - MUST be present. + The parameter "module-set-id" has the same value as the leaf "/ + modules/module-set-id" from "ietf-yang-library". This parameter MUST + be present. With this mechanism, a client can cache the supported modules for a server, and only update the cache if the "module-set-id" value in the message changes. 5.7. Data Store Modification Data models may allow the server to alter the configuration data store in ways not explicitly directed via NETCONF protocol messages. For example, a data model may define leafs that are assigned system- @@ -1678,25 +1694,25 @@ descendent node may use that typedef, and it MUST NOT define a typedef with the same name. o All grouping names defined within a parent node or at the top level of the module or its submodules share the same grouping identifier namespace. This namespace is scoped to all descendant nodes of the parent node or module. This means that any descendent node may use that grouping, and it MUST NOT define a grouping with the same name. - o All leafs, leaf-lists, lists, containers, choices, rpcs, - notifications, and anyxmls defined (directly or through a uses - statement) within a parent node or at the top level of the module - or its submodules share the same identifier namespace. This - namespace is scoped to the parent node or module, unless the + o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, + notifications, anydatas, and anyxmls defined (directly or through + a uses statement) within a parent node or at the top level of the + module or its submodules share the same identifier namespace. + This namespace is scoped to the parent node or module, unless the parent node is a case node. In that case, the namespace is scoped to the closest ancestor node that is not a case or choice node. o All cases within a choice share the same case identifier namespace. This namespace is scoped to the parent choice node. Forward references are allowed in YANG. 6.3. Statements @@ -1705,21 +1721,21 @@ either by a semicolon (";") or a block of substatements enclosed within braces ("{ }"): 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.18). The extensions can be imported by other + keyword (see Section 7.19). The extensions can be imported by other modules with the "import" statement (see Section 7.1.5). When an 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. If a YANG compiler does not support a particular extension, which appears in a YANG module as an unknown-statement (see Section 13), the entire unknown-statement MAY be ignored by the compiler. @@ -1767,24 +1783,24 @@ definition: o The set of namespace declarations is the set of all "import" statements' prefix and namespace pairs in the module where the XPath expression is specified, and the "prefix" statement's prefix for the "namespace" statement's URI. o Names without a namespace prefix belong to the same namespace as the identifier of the current node. Inside a grouping, that namespace is affected by where the grouping is used (see - Section 7.12). Inside a typedef, that namespace is affected by + Section 7.13). Inside a typedef, that namespace is affected by where the typedef is referenced. If a typedef is defined and referenced within a grouping, the namespace is affected by where - the grouping is used (see Section 7.12). + the grouping is used (see Section 7.13). o The function library is the core function library defined in [XPATH], and the functions defined in Section 10. o The set of variable bindings is empty. The mechanism for handling unprefixed names is adopted from XPath 2.0 [XPATH2.0], and helps simplify XPath expressions in YANG. No ambiguity may ever arise because YANG node identifiers are always qualified names with a non-null namespace URI. @@ -1909,45 +1925,46 @@ // module definitions } 7.1.1. The module's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | - | augment | 7.16 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | + | augment | 7.17 | 0..n | | choice | 7.9 | 0..n | | contact | 7.1.8 | 0..1 | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | deviation | 7.19.3 | 0..n | - | extension | 7.18 | 0..n | - | feature | 7.19.1 | 0..n | - | grouping | 7.11 | 0..n | - | identity | 7.17 | 0..n | + | description | 7.21.3 | 0..1 | + | deviation | 7.20.3 | 0..n | + | extension | 7.19 | 0..n | + | feature | 7.20.1 | 0..n | + | grouping | 7.12 | 0..n | + | identity | 7.18 | 0..n | | import | 7.1.5 | 0..n | | include | 7.1.6 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | namespace | 7.1.3 | 1 | - | notification | 7.15 | 0..n | + | notification | 7.16 | 0..n | | organization | 7.1.7 | 0..1 | | prefix | 7.1.4 | 1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | | revision | 7.1.9 | 0..n | - | rpc | 7.13 | 0..n | + | rpc | 7.14 | 0..n | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | | yang-version | 7.1.2 | 1 | +--------------+---------+-------------+ 7.1.2. The yang-version Statement The "yang-version" statement specifies which version of the YANG language was used in developing the module. The statement's argument is a string. It MUST contain the value "1.1", which is the current YANG version. @@ -1958,21 +1975,21 @@ Handling of the "yang-version" statement for versions other than "1.1" (the version defined here) is out of scope for this specification. Any document that defines a higher version will need to define the backward compatibility of such a higher version. 7.1.3. The namespace Statement The "namespace" statement defines the XML namespace that all identifiers defined by the module are qualified by, with the exception of data node identifiers defined inside a grouping (see - Section 7.12 for details). The argument to the "namespace" statement + Section 7.13 for details). The argument to the "namespace" statement is the URI of the namespace. See also Section 5.3. 7.1.4. The prefix Statement The "prefix" statement is used to define the prefix associated with the module and its namespace. The "prefix" statement's argument is the prefix string that is used as a prefix to access a module. The prefix string MAY be used to refer to definitions contained in the @@ -2055,21 +2072,21 @@ identifier that 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). Submodules are only allowed to include other submodules belonging to the same module. When a module includes a submodule, it incorporates the contents of the submodule into the node hierarchy of the module. - For backwards compatibility with YANG version 1, a submodule is + For backward compatibility with YANG version 1, a submodule is allowed to include another submodule belonging to the same module, but this is not necessary in YANG version 1.1. When the optional "revision-date" substatement is present, the specified revision of the submodule is included in the module. It is an error if the specified revision of the submodule does not exist. If no "revision-date" substatement is present, it is undefined which revision of the submodule is included. Multiple revisions of the same submodule MUST NOT be included. @@ -2107,22 +2124,22 @@ module SHOULD have at least one "revision" statement. For every published editorial change, a new one SHOULD be added in front of the revisions sequence, so that all revisions are in reverse chronological order. 7.1.9.1. The revision's Substatement +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | reference | 7.20.4 | 0..1 | + | description | 7.21.3 | 0..1 | + | reference | 7.21.4 | 0..1 | +--------------+---------+-------------+ 7.1.10. Usage Example module acme-system { yang-version 1.1; namespace "http://acme.example.com/system"; prefix "acme"; import ietf-yang-types { @@ -2199,44 +2216,45 @@ // module definitions } 7.2.1. The submodule's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | - | augment | 7.16 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | + | augment | 7.17 | 0..n | | belongs-to | 7.2.2 | 1 | | choice | 7.9 | 0..n | | contact | 7.1.8 | 0..1 | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | deviation | 7.19.3 | 0..n | - | extension | 7.18 | 0..n | - | feature | 7.19.1 | 0..n | - | grouping | 7.11 | 0..n | - | identity | 7.17 | 0..n | + | description | 7.21.3 | 0..1 | + | deviation | 7.20.3 | 0..n | + | extension | 7.19 | 0..n | + | feature | 7.20.1 | 0..n | + | grouping | 7.12 | 0..n | + | identity | 7.18 | 0..n | | import | 7.1.5 | 0..n | | include | 7.1.6 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | - | notification | 7.15 | 0..n | + | notification | 7.16 | 0..n | | organization | 7.1.7 | 0..1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | | revision | 7.1.9 | 0..n | - | rpc | 7.13 | 0..n | + | rpc | 7.14 | 0..n | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | | yang-version | 7.1.2 | 1 | +--------------+---------+-------------+ 7.2.2. The belongs-to Statement The "belongs-to" statement specifies the module to which the submodule belongs. The argument is an identifier that is the name of the module. A submodule MUST only be included by the module to which it belongs, @@ -2306,23 +2324,23 @@ the typedef is defined at the top level of a YANG module or submodule, the name of the type to be defined MUST be unique within the module. 7.3.1. The typedef's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | default | 7.3.4 | 0..1 | - | description | 7.20.3 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | type | 7.3.2 | 1 | | units | 7.3.3 | 0..1 | +--------------+---------+-------------+ 7.3.2. The typedef's type Statement The "type" statement, which MUST be present, defines the base type from which this type is derived. See Section 7.4 for details. 7.3.3. The units Statement @@ -2364,21 +2382,21 @@ The restrictions that can be applied depend on the type being restricted. The restriction statements for all built-in types are described in the subsections of Section 9. 7.4.1. The type's Substatements +------------------+---------+-------------+ | substatement | section | cardinality | +------------------+---------+-------------+ - | base | 7.17.2 | 0..n | + | base | 7.18.2 | 0..n | | bit | 9.7.4 | 0..n | | enum | 9.6.4 | 0..n | | fraction-digits | 9.3.4 | 0..1 | | length | 9.4.4 | 0..1 | | path | 9.9.2 | 0..1 | | pattern | 9.4.5 | 0..n | | range | 9.2.4 | 0..1 | | require-instance | 9.9.3 | 0..1 | | type | 7.4 | 0..n | +------------------+---------+-------------+ @@ -2424,50 +2442,52 @@ the device using ssh, but can also contain any ssh-related configuration knobs, such as connection rates or retry limits. The "presence" statement (see Section 7.5.5) is used to give semantics to the existence of the container in the data tree. 7.5.2. The container's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | action | 7.14 | 0..n | - | anyxml | 7.10 | 0..n | + | action | 7.15 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | + | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | + | notification | 7.16 | 0..n | | presence | 7.5.5 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | - | when | 7.20.5 | 0..1 | + | uses | 7.13 | 0..n | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 7.5.3. The must Statement The "must" statement, which is optional, takes as an argument a string that contains an XPath expression (see Section 6.4). It is used to formally declare a constraint on valid data. The constraint is enforced according to the rules in Section 8. When a datastore is validated, all "must" constraints are - conceptually evaluated once for each data node in the accessible tree - (see Section 6.4.1). + conceptually evaluated once for each node in the accessible tree (see + Section 6.4.1). All such constraints MUST evaluate to true for the data to be valid. The XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o The context node is the node in the accessible tree for which the "must" statement is defined. The result of the XPath expression is converted to a boolean value @@ -2480,24 +2500,24 @@ Also 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.4. The must's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ - | description | 7.20.3 | 0..1 | + | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ 7.5.4.1. The error-message Statement The "error-message" statement, which is optional, takes a string as an argument. If the constraint evaluates to false, the string is passed as in the . 7.5.4.2. The error-app-tag Statement @@ -2535,22 +2555,22 @@ If a container has the "presence" statement, the container's existence in the data tree carries some meaning. Otherwise, the container is used to give some structure to the data, and it carries no meaning by itself. See Section 7.5.1 for additional information. 7.5.6. The container's Child Node Statements Within a container, the "container", "leaf", "list", "leaf-list", - "uses", "choice", and "anyxml" statements can be used to define child - nodes to the container. + "uses", "choice", "anydata", and "anyxml" statements can be used to + define child nodes to the container. 7.5.7. XML Mapping Rules A container node is encoded as an XML element. The element's local name is the container's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The container's child nodes are encoded as subelements to the container element. If the container defines RPC input or output parameters, these subelements are encoded in the same order as they @@ -2674,31 +2694,31 @@ value of the "default" statement. Otherwise, if the leaf's type has a default value, and the leaf is not mandatory, then the leaf's default value is the type's default value. In all other cases, the leaf does not have a default value. 7.6.2. The leaf's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | default | 7.6.4 | 0..1 | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | type | 7.6.3 | 1 | | units | 7.3.3 | 0..1 | - | when | 7.20.5 | 0..1 | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 7.6.3. The leaf's type Statement The "type" statement, which MUST be present, takes as an argument the name of an existing built-in or derived type. The optional substatements specify restrictions on this type. See Section 7.4 for details. 7.6.4. The leaf's default Statement @@ -2882,33 +2902,33 @@ a default value, and the leaf-list does not have a "min-elements" statement with a value greater than or equal to one, then the leaf- list's default value is the type's default value. In all other cases, the leaf-list does not have any default values. 7.7.3. The leaf-list's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | default | 7.7.4 | 0..n | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | max-elements | 7.7.6 | 0..1 | | min-elements | 7.7.5 | 0..1 | | must | 7.5.3 | 0..n | | ordered-by | 7.7.7 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | type | 7.4 | 1 | | units | 7.3.3 | 0..1 | - | when | 7.20.5 | 0..1 | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 7.7.4. The leaf-list's default Statement The "default" statement, which is optional, takes as an argument a string that contains a default value for the leaf-list. The value of the "default" statement MUST be valid according to the type specified in the leaf-list's "type" statement. @@ -3113,42 +3133,44 @@ statement takes one argument, which is an identifier, followed by a block of substatements that holds detailed list information. A list entry is uniquely identified by the values of the list's keys, if defined. 7.8.1. The list's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | action | 7.14 | 0..n | - | anyxml | 7.10 | 0..n | + | action | 7.15 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | + | if-feature | 7.20.2 | 0..n | | key | 7.8.2 | 0..1 | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | max-elements | 7.7.6 | 0..1 | | min-elements | 7.7.5 | 0..1 | | must | 7.5.3 | 0..n | + | notification | 7.16 | 0..n | | ordered-by | 7.7.7 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | | unique | 7.8.3 | 0..n | - | uses | 7.12 | 0..n | - | when | 7.20.5 | 0..1 | + | uses | 7.13 | 0..n | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 7.8.2. The list's key Statement The "key" statement, which MUST be present if the list represents configuration, and MAY be present otherwise, takes as an argument a string that specifies a space-separated list of leaf identifiers of this list. A leaf identifier MUST NOT appear more than once in the key. Each such leaf identifier MUST refer to a child leaf of the list. The leafs can be defined directly in substatements to the @@ -3237,22 +3259,22 @@ ftp 192.0.2.1 7.8.4. The list's Child Node Statements Within a list, the "container", "leaf", "list", "leaf-list", "uses", - "choice", and "anyxml" statements can be used to define child nodes - to the list. + "choice", "anydata", and "anyxml" statements can be used to define + child nodes to the list. 7.8.5. XML Mapping Rules A list is encoded as a series of XML elements, one for each entry in the list. Each element's local name is the list's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The list's key nodes are encoded as subelements to the list's identifier element, in the same order as they are defined within the "key" statement. @@ -3469,98 +3491,100 @@ substatement. Each branch contains a number of child nodes. The nodes from at most one of the choice's branches exist at the same time. See Section 8.3.2 for additional information. 7.9.1. The choice's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | case | 7.9.2 | 0..n | | choice | 7.9 | 0..n | - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | container | 7.5 | 0..n | | default | 7.9.3 | 0..1 | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | mandatory | 7.9.4 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | - | when | 7.20.5 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 7.9.2. The choice's case Statement The "case" statement is used to define branches of the choice. It takes as an argument an identifier, followed by a block of substatements that holds detailed case information. The identifier is used to identify the case node in the schema tree. A case node does not exist in the data tree. - Within a "case" statement, the "anyxml", "choice", "container", - "leaf", "list", "leaf-list", and "uses" statements can be used to - define child nodes to the case node. The identifiers of all these - child nodes MUST be unique within all cases in a choice. For - example, the following is illegal: + Within a "case" statement, the "anydata", "anyxml", "choice", + "container", "leaf", "list", "leaf-list", and "uses" statements can + be used to define child nodes to the case node. The identifiers of + all these child nodes MUST be unique within all cases in a choice. + For example, the following is illegal: choice interface-type { // This example is illegal YANG case a { leaf ethernet { ... } } case b { container ethernet { ...} } } As a shorthand, the "case" statement can be omitted if the branch - contains a single "anyxml", "choice", "container", "leaf", "list", or - "leaf-list" statement. In this case, the identifier of the case node - is the same as the identifier in the branch statement. The following - example: + contains a single "anydata", "anyxml", "choice", "container", "leaf", + "list", or "leaf-list" statement. In this case, the identifier of + the case node is the same as the identifier in the branch statement. + The following example: choice interface-type { container ethernet { ... } } is equivalent to: choice interface-type { case ethernet { container ethernet { ... } } } The case identifier MUST be unique within a choice. 7.9.2.1. The case's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | - | uses | 7.12 | 0..n | - | when | 7.20.5 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | uses | 7.13 | 0..n | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ 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 exist. 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 @@ -3688,66 +3712,168 @@ -7.10. The anyxml Statement +7.10. The anydata Statement + + The "anydata" 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 anydata information. + + The "anydata" statement is used to represent an unknown set of nodes + that can be modelled with YANG. An example of where this can be + useful is a list of received notifications, where the exact + notifications are not known as design time. + + An anydata node cannot be augmented (see Section 7.17). + + An anydata node exists in zero or one instances in the data tree. + + Since the use of anydata limits the manipulation of the content, it + is RECOMMENDED that the "anydata" statement not be used to represent + configuration data. + +7.10.1. The anydata's Substatements + + +--------------+---------+-------------+ + | substatement | section | cardinality | + +--------------+---------+-------------+ + | config | 7.21.1 | 0..1 | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | mandatory | 7.6.5 | 0..1 | + | must | 7.5.3 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | when | 7.21.5 | 0..1 | + +--------------+---------+-------------+ + +7.10.2. XML Mapping Rules + + An anydata node is encoded as an XML element. The element's local + name is the anydata's identifier, and its namespace is the module's + XML namespace (see Section 7.1.3). The value of the anydata node is + a set of nodes, which are encoded as XML subelements to the anydata + element. + +7.10.3. NETCONF Operations + + An anydata node is treated as an opaque chunk of data. This data can + be modified in its entirety only. + + Any "operation" attributes present on subelements of an anydata node + are ignored by the NETCONF server. + + When a NETCONF server processes an request, the + elements of procedure for the anydata node are: + + If the operation is "merge" or "replace", the node is created if + it does not exist, and its value is set to the subelements to the + anydata node found in the XML RPC data. + + If the operation is "create", the node is created if it does not + exist, and its value is set to the subelements to the anydata node + found in the XML RPC data. If the node already exists, a + "data-exists" error is returned. + + If the operation is "delete", the node is deleted if it exists. + If the node does not exist, a "data-missing" error is returned. + +7.10.4. Usage Example + + Given the following "anydata" statement: + + list logged-notification { + key time; + leaf time { + type yang:date-and-time; + } + anydata data; + } + + The following is a valid encoding of such a list instance: + + + + + + 2014-07-29T13:43:01Z + + fault + + Ethernet0 + + major + + + + +7.11. The anyxml Statement The "anyxml" statement defines an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed anyxml information. The "anyxml" statement is used to represent an unknown chunk of XML. No restrictions are placed on the XML. This can be useful, for example, in RPC replies. An example is the parameter in the operation. - An anyxml node cannot be augmented (see Section 7.16). + An anyxml node cannot be augmented (see Section 7.17). + + An anyxml node exists in zero or one instances in the data tree. Since the use of anyxml limits the manipulation of the content, it is RECOMMENDED that the "anyxml" statement not be used to represent configuration data. - An anyxml node exists in zero or one instances in the data tree. + It should be noted that in YANG version 1, anyxml was the only + statement that could model an unknown hierarchy of data. In many + cases this unknown hierarchy of data is actually modelled in YANG, + but the exact YANG model is not known at design time. In these + situations, it is RECOMMENDED to use anydata (Section 7.10) instead + of anyxml. -7.10.1. The anyxml's Substatements +7.11.1. The anyxml's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | config | 7.20.1 | 0..1 | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | config | 7.21.1 | 0..1 | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | - | when | 7.20.5 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.10.2. XML Mapping Rules +7.11.2. XML Mapping Rules An anyxml node is encoded as an XML element. The element's local name is the anyxml's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of the anyxml node is encoded as XML content of this element. - Note that any prefixes used in the encoding are local to each + Note that any XML prefixes used in the encoding are local to each instance encoding. This means that the same XML may be encoded differently by different implementations. -7.10.3. NETCONF Operations +7.11.3. NETCONF Operations An anyxml node is treated as an opaque chunk of data. This data can be modified in its entirety only. Any "operation" attributes present on subelements of an anyxml node are ignored by the NETCONF server. When a NETCONF server processes an request, the elements of procedure for the anyxml node are: @@ -3756,134 +3882,136 @@ anyxml node found in the XML RPC data. If the operation is "create", the node is created if it does not exist, and its value is set to the XML content of the anyxml node found in the XML RPC data. If the node already exists, a "data-exists" error is returned. If the operation is "delete", the node is deleted if it exists. If the node does not exist, a "data-missing" error is returned. -7.10.4. Usage Example +7.11.4. Usage Example Given the following "anyxml" statement: anyxml data; The following are two valid encodings of the same anyxml value: 1 1 -7.11. The grouping Statement +7.12. The grouping Statement The "grouping" statement is used to define a reusable block of nodes, which may be used locally in the module or submodule, and by other modules that import from it, according to the rules in Section 5.5. It takes one argument, 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). A grouping MUST NOT reference itself, + statement (see Section 7.13). A grouping MUST NOT reference itself, neither directly nor indirectly through a chain of other groupings. If the grouping is defined at the top level of a YANG module or submodule, the grouping's identifier MUST be unique within the module. A grouping is more than just a mechanism for textual substitution, but defines a collection of nodes. Identifiers appearing inside the grouping are resolved relative to the scope in which the grouping is defined, not where it is used. Prefix mappings, type names, grouping names, and extension usage are evaluated in the hierarchy where the "grouping" statement appears. For extensions, this means that extensions are applied to the grouping node, not the uses node. -7.11.1. The grouping's Substatements +7.12.1. The grouping's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | action | 7.14 | 0..n | - | anyxml | 7.10 | 0..n | + | action | 7.15 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | notification | 7.16 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.11.2. Usage Example +7.12.2. Usage Example import ietf-inet-types { prefix "inet"; } grouping endpoint { description "A reusable endpoint group."; leaf ip { type inet:ip-address; } leaf port { type inet:port-number; } } -7.12. The uses Statement +7.13. The uses Statement The "uses" statement is used to reference a "grouping" definition. It takes one argument, which is the name of the grouping. The effect of a "uses" reference to a grouping is that the nodes defined by the grouping are copied into the current schema tree, and then updated according to the "refine" and "augment" statements. The identifiers defined in the grouping are not bound to a namespace until the contents of the grouping are added to the schema tree via a "uses" statement that does not appear inside a "grouping" statement, at which point they are bound to the namespace of the current module. -7.12.1. The uses's Substatements +7.13.1. The uses's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | augment | 7.16 | 0..n | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | - | refine | 7.12.2 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | - | when | 7.20.5 | 0..1 | + | augment | 7.17 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | refine | 7.13.2 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.12.2. The refine Statement +7.13.2. The refine Statement Some of the properties of each node in the grouping can be refined with the "refine" statement. The argument is a string that identifies a node in the grouping. This node is called the refine's target node. If a node in the grouping is not present as a target node of a "refine" statement, it is not refined, and thus used exactly as it was defined in the grouping. The argument string is a descendant schema node identifier (see Section 6.5). @@ -3892,43 +4020,43 @@ o A leaf or choice node may get a default value, or a new default value if it already had one. o Any node may get a specialized "description" string. o Any node may get a specialized "reference" string. o Any node may get a different "config" statement. - o A leaf, anyxml, or choice node may get a different "mandatory" - statement. + o A leaf, anydata, anyxml, or choice node may get a different + "mandatory" statement. o A container node may get a "presence" statement. - o A leaf, leaf-list, list, container, or anyxml node may get - additional "must" expressions. + o A leaf, leaf-list, list, container, anydata, or anyxml node may + get additional "must" expressions. o A leaf-list or list node may get a different "min-elements" or "max-elements" statement. - o A leaf, leaf-list, list, container, or anyxml node may get - additional "if-feature" expressions. + o A leaf, leaf-list, list, container, anydata, or anyxml node may + get additional "if-feature" expressions. -7.12.3. XML Mapping Rules +7.13.3. XML Mapping Rules Each node in the grouping is encoded as if it was defined inline, even if it is imported from another module with another XML namespace. -7.12.4. Usage Example +7.13.4. Usage Example - To use the "endpoint" grouping defined in Section 7.11.2 in a + To use the "endpoint" grouping defined in Section 7.12.2 in a definition of an HTTP server in some other module, we can do: import acme-system { prefix "acme"; } container http-server { leaf name { type string; } @@ -3970,50 +4098,50 @@ The following is an error: container http-server { uses acme:endpoint; leaf ip { // illegal - same identifier "ip" used twice type string; } } -7.13. The rpc Statement +7.14. The rpc Statement The "rpc" statement is used to define an RPC operation. 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 [RFC6241]. The "rpc" statement defines an rpc node in the schema tree. Under the rpc node, a schema node with the name "input", and a schema 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 +7.14.1. The rpc's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | - | if-feature | 7.19.2 | 0..n | - | input | 7.13.2 | 0..1 | - | output | 7.13.3 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | + | if-feature | 7.20.2 | 0..n | + | input | 7.14.2 | 0..1 | + | output | 7.14.3 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+ -7.13.2. The input Statement +7.14.2. The input Statement The "input" statement, which is optional, is used to define input parameters to the operation. It does not take an argument. The substatements to "input" define nodes under the operation's input node. If a leaf in the input tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF RPC invocation. Otherwise, the server MUST return a "missing-element" error. @@ -4028,38 +4156,39 @@ in Section 7.7.2. In these cases, the server MUST operationally behave as if the leaf-list was present in the NETCONF RPC invocation with the default values as its values. If a "config" statement is present for any node in the input tree, the "config" statement is ignored. If any node has a "when" statement that would evaluate to false, then this node MUST NOT be present in the input tree. -7.13.2.1. The input's Substatements +7.14.2.1. The input's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | grouping | 7.11 | 0..n | + | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.13.3. The output Statement +7.14.3. The output Statement The "output" statement, which is optional, is used to define output parameters to the RPC operation. It does not take an argument. The substatements to "output" define nodes under the operation's output node. If a leaf in the output tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF RPC reply. If a leaf in the output tree has a default value, the NETCONF client @@ -4073,55 +4203,56 @@ in Section 7.7.2. In these cases, the client MUST operationally behave as if the leaf-list was present in the NETCONF RPC reply with the default values as its values. If a "config" statement is present for any node in the output tree, the "config" statement is ignored. If any node has a "when" statement that would evaluate to false, then this node MUST NOT be present in the output tree. -7.13.3.1. The output's Substatements +7.14.3.1. The output's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | grouping | 7.11 | 0..n | + | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.13.4. XML Mapping Rules +7.14.4. XML Mapping Rules An rpc node is encoded as a child XML element to the element defined in [RFC6241]. The element's local name is the rpc's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). 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 operation invocation succeeded, and no output parameters are returned, the contains a single element defined in [RFC6241]. If output parameters are returned, they are encoded as child elements to the element defined in [RFC6241], in the same order as they are defined within the "output" statement. -7.13.5. Usage Example +7.14.5. Usage Example The following example defines an RPC operation: module rock { yang-version 1.1; namespace "http://example.net/rock"; prefix "rock"; rpc rock-the-house { input { @@ -4140,59 +4271,65 @@ 27606-0100 -7.14. The action Statement +7.15. The action Statement The "action" statement is used to define an operation connected to a specific container or list data node. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed action information. The argument is the name of the action. The "action" statement defines an action node in the schema tree. Under the action node, a schema node with the name "input", and a schema node with the name "output" are also defined. The nodes "input" and "output" are defined in the module's namespace. An action MUST NOT be defined within an rpc, another action or a notification, i.e., an action node MUST NOT have an rpc, action, or a notification node as one of its ancestors in the schema tree. For example, this means that it is an error if a grouping that contains - an action is used in a notification definition. + an action somewhere in its node hierarchy is used in a notification + definition. + + Since an action cannot be defined an the top-level of a module or in + a case statement, it is an error if a grouping that contains an + action at the top of its node hierarchy is used at the top-level of a + module or in a case definition. The difference between an action and an rpc is that an action is tied to a node in the data tree, whereas an rpc is not. When an action is invoked, the node in the data tree is specified along with the name of the action and the input parameters. -7.14.1. The action's Substatements +7.15.1. The action's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | - | if-feature | 7.19.2 | 0..n | - | input | 7.13.2 | 0..1 | - | output | 7.13.3 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | + | if-feature | 7.20.2 | 0..n | + | input | 7.14.2 | 0..1 | + | output | 7.14.3 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+ -7.14.2. XML Mapping Rules +7.15.2. XML Mapping Rules When an action is invoked, an element with the local name "action" in the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is encoded as a child XML element to the element defined in [RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241]. The "action" element contains an hierarchy of nodes that identifies the node in the data tree. It MUST contain all containers and list nodes from the top level down to the list or container containing the @@ -4206,21 +4343,21 @@ actions are present in the , the server MUST reply with an "bad-element" error-tag in the . If the action operation invocation succeeded, and no output parameters are returned, the contains a single element defined in [RFC6241]. If output parameters are returned, they are encoded as child elements to the element defined in [RFC6241], in the same order as they are defined within the "output" statement. -7.14.3. Usage Example +7.15.3. Usage Example The following example defines an action to reset one server at a server farm: module server-farm { yang-version 1.1; namespace "http://example.net/server-farm"; prefix "sfarm"; import ietf-yang-types { @@ -4264,110 +4401,178 @@ 2014-07-29T13:42:12Z -7.15. The notification Statement +7.16. 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. + A notification can be defined at the top-level of a module, or + connected to a specific container or list data node in the schema + tree. + + A notification MUST NOT be defined within an rpc, action or another + notification, i.e., a notification node MUST NOT have an rpc, action, + or a notification node as one of its ancestors in the schema tree. + For example, this means that it is an error if a grouping that + contains an notification somewhere in its node hierarchy is used in + an rpc definition. + + Since a notification cannot be defined in a case statement, it is an + error if a grouping that contains a notification at the top of its + node hierarchy is used in a case definition. + If a leaf in the notification tree has a "mandatory" statement with the value "true", the leaf MUST be present in a NETCONF notification. If a leaf in the notification tree has a default value, the NETCONF client MUST use this value in the same cases as described in Section 7.6.1. In these cases, the client MUST operationally behave as if the leaf was present in the NETCONF notification with the default value as its value. If a leaf-list in the notification tree has one or more default values, the NETCONF client MUST use these values in the same cases as described in Section 7.7.2. In these cases, the client MUST operationally behave as if the leaf-list was present in the NETCONF notification with the default values as its values. If a "config" statement is present for any node in the notification tree, the "config" statement is ignored. -7.15.1. The notification's Substatements +7.16.1. The notification's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | anyxml | 7.10 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | grouping | 7.11 | 0..n | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | grouping | 7.12 | 0..n | + | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | - | uses | 7.12 | 0..n | + | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.15.2. XML Mapping Rules +7.16.2. XML Mapping Rules - A notification node is encoded as a child XML element to the + A notification node that is defined on the top-level of a module is + encoded as a child XML element to the element defined + in NETCONF Event Notifications [RFC5277]. The element's local name + is the notification's identifier, and its namespace is the module's + XML namespace (see Section 7.1.3). + + When a notification node is defined as a child to a data node, the element defined in NETCONF Event Notifications - [RFC5277]. The element's local name is the notification's - identifier, and its namespace is the module's XML namespace (see - Section 7.1.3). + [RFC5277] contains an hierarchy of nodes that identifies the node in + the data tree. It MUST contain all containers and list nodes from + the top level down to the list or container containing the + notification. For lists, all key leafs MUST also be included. The + last container or list contains an XML element that carries the name + of the defined notification. -7.15.3. Usage Example + The notification's child nodes are encoded as subelements to the + notification node's XML element, in any order. - The following example defines a notification: +7.16.3. Usage Example + + The following example defines a notification at the top-level of a + module: module event { yang-version 1.1; namespace "http://example.com/event"; prefix "ev"; notification event { leaf event-class { type string; } - anyxml reporting-entity; + leaf reporting-entity { + type instance-identifier; + } leaf severity { type string; } } } A corresponding XML instance example of the complete notification: 2008-07-08T00:01:00Z fault - Ethernet0 + /ex:interface[ex:name='Ethernet0'] major -7.16. The augment Statement + The following example defines a notification in a data node: + + module interface-module { + yang-version 1.1; + namespace "http://example.com/schema/interfaces"; + prefix "if"; + + container interfaces { + list interface { + key "name"; + leaf name { + type string; + } + notification interface-enabled { + leaf by-user { + type string; + } + } + } + } + } + + A corresponding XML instance example of the complete notification: + + + 2008-07-08T00:01:00Z + + + eth1 + + fred + + + + + +7.17. The augment Statement The "augment" statement allows a module or submodule to add to the schema tree defined in an external module, or the current module and its submodules, and to add to the nodes from a grouping in a "uses" statement. The argument is a string that identifies a node in the schema tree. This node is called the augment's target node. The target node MUST be either a container, list, choice, case, input, output, or notification node. It is augmented with the nodes defined in the substatements that follow the "augment" statement. @@ -4387,51 +4592,53 @@ If the target node is a choice node, the "case" statement, or a case shorthand statement (see Section 7.9.2) can be used within the "augment" statement. If the target node is in another module, then nodes added by the augmentation MUST NOT be mandatory nodes (see Section 3.1). The "augment" statement MUST NOT add multiple nodes with the same name from the same module to the target node. -7.16.1. The augment's Substatements +7.17.1. The augment's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | action | 7.14 | 0..n | - | anyxml | 7.10 | 0..n | + | action | 7.15 | 0..n | + | anydata | 7.10 | 0..n | + | anyxml | 7.11 | 0..n | | case | 7.9.2 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | - | uses | 7.12 | 0..n | - | when | 7.20.5 | 0..1 | + | notification | 7.16 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | + | uses | 7.13 | 0..n | + | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.16.2. XML Mapping Rules +7.17.2. XML Mapping Rules All data nodes defined in the "augment" statement are defined as XML elements in the XML namespace of the module where the "augment" is specified. When a node is augmented, the augmenting child nodes are encoded as subelements to the augmented node, in any order. -7.16.3. Usage Example +7.17.3. Usage Example In namespace http://example.com/schema/interfaces, we have: container interfaces { list ifEntry { key "ifIndex"; leaf ifIndex { type uint32; } @@ -4498,45 +4705,46 @@ or -7.17. The identity Statement +7.18. The identity Statement The "identity" statement is used to define a new globally unique, abstract, and untyped identity. Its only purpose is to denote its name, semantics, and existence. An identity can either be defined from scratch or derived from one or more base identities. The identity's argument is an identifier that is the name of the identity. It is followed by a block of substatements that holds detailed identity information. The built-in datatype "identityref" (see Section 9.10) can be used to reference identities within a data model. -7.17.1. The identity's Substatements +7.18.1. The identity's Substatements + +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | base | 7.17.2 | 0..n | - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | base | 7.18.2 | 0..n | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | +--------------+---------+-------------+ -7.17.2. The base Statement +7.18.2. The base Statement The "base" statement, which is optional, takes as an argument a string that is the name of an existing identity, from which the new identity is derived. If no "base" statement is present, the identity is defined from scratch. If multiple "base" statements are present, the identity is derived from all of them. If a prefix is present on the base name, it refers to an identity defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. @@ -4547,21 +4755,22 @@ indirectly through a chain of other identities. The derivation of identities has the following properties: o It is irreflexive, which means that an identity is not derived from itself. o It is transitive, which means that if identity B is derived from A and C is derived from B, then C is also derived from A. -7.17.3. Usage Example +7.18.3. Usage Example + module crypto-base { yang-version 1.1; namespace "http://example.com/crypto-base"; prefix "crypto"; identity crypto-alg { description "Base identity from which all crypto algorithms are derived."; } @@ -4580,21 +4789,21 @@ base "crypto:crypto-alg"; description "DES crypto algorithm"; } identity des3 { base "crypto:crypto-alg"; description "Triple DES crypto algorithm"; } } -7.18. The extension Statement +7.19. The extension Statement 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. @@ -4604,60 +4813,60 @@ "extension" statement, and an optional block of substatements. The statement's name is created by combining 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" statement, using some mechanism outside the scope of this specification. Syntactically, the substatements MUST be YANG statements, or also extensions defined using "extension" statements. YANG statements in extensions MUST follow the syntactical rules in Section 13. -7.18.1. The extension's Substatements +7.19.1. The extension's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | argument | 7.18.2 | 0..1 | - | description | 7.20.3 | 0..1 | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | argument | 7.19.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | +--------------+---------+-------------+ -7.18.2. The argument Statement +7.19.2. The argument Statement The "argument" statement, which is optional, takes as an argument a string that is the name of the argument to the keyword. If no argument statement is present, the keyword expects no argument when it is used. The argument's name is used in the YIN mapping, where it is used as an XML attribute or element name, depending on the argument's "yin-element" statement. -7.18.2.1. The argument's Substatements +7.19.2.1. The argument's Substatements +--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ - | yin-element | 7.18.2.2 | 0..1 | + | yin-element | 7.19.2.2 | 0..1 | +--------------+----------+-------------+ -7.18.2.2. The yin-element Statement +7.19.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 is mapped to an XML element in YIN or to an XML attribute (see Section 12). If no "yin-element" statement is present, it defaults to "false". -7.18.3. Usage Example +7.19.3. Usage Example To define an extension: module my-extensions { ... extension c-define { description "Takes as argument a name string. Makes the code generator use the given name in the @@ -4674,31 +4883,31 @@ prefix "myext"; } ... container interfaces { ... myext:c-define "MY_INTERFACES"; } } -7.19. Conformance-Related Statements +7.20. Conformance-Related Statements This section defines statements related to conformance, as described in Section 5.6. -7.19.1. The feature Statement +7.20.1. The feature Statement The "feature" statement is used to define a mechanism by which portions of the schema are marked as conditional. A feature name is defined that can later be referenced using the "if-feature" statement - (see Section 7.19.2). Schema nodes tagged with an "if-feature" + (see Section 7.20.2). Schema nodes tagged with an "if-feature" statement are ignored by the device unless the device supports the given feature expression. This allows portions of the YANG module to be conditional based on conditions on the device. The model can represent the abilities of the device within the model, giving a richer model that allows for differing device abilities and roles. The argument to the "feature" statement is the name of the new feature, and follows the rules for identifiers in Section 6.2. This name is used by the "if-feature" statement to tie the schema nodes to the feature. @@ -4737,32 +4946,32 @@ device does not support that feature. A feature MUST NOT reference itself, neither directly nor indirectly through a chain of other features. In order for a device to implement a feature that is dependent on any other features (i.e., the feature has one or more "if-feature" substatements), the device MUST also implement all the dependant features. -7.19.1.1. The feature's Substatements +7.20.1.1. The feature's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | - | status | 7.20.2 | 0..1 | - | reference | 7.20.4 | 0..1 | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | status | 7.21.2 | 0..1 | + | reference | 7.21.4 | 0..1 | +--------------+---------+-------------+ -7.19.2. The if-feature Statement +7.20.2. The if-feature Statement The "if-feature" statement makes its parent statement conditional. The argument is a boolean expression over feature names. In this expression, a feature name evaluates to "true" if and only if the feature is implemented by the server. The parent statement is implemented by servers where the boolean expression evaluates to "true". The if-feature boolean expression syntax is formally defined by the rule "if-feature-expr" in Section 13. When this boolean expression @@ -4773,32 +4982,32 @@ the prefixed name refers to a feature defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. Otherwise, a feature with the matching name MUST be defined in the current module or an included submodule. A leaf that is a list key MUST NOT have any "if-feature" statements, unless the conditions specified in the "if-feature" statements are the same as the "if-feature" conditions in effect on the leaf's parent node. -7.19.2.1. Usage Example +7.20.2.1. Usage Example In this example, the container "target" is implemented if any of the features "outbound-tls" or "outbound-ssh" is implemented by the server. container target { if-feature "outbound-tls or outbound-ssh"; ... } -7.19.3. The deviation Statement +7.20.3. The deviation Statement The "deviation" statement defines a hierarchy of a module that the device does not implement faithfully. The argument is a string that identifies the node in the schema tree where a deviation from the module occurs. This node is called the deviation's target node. The contents of the "deviation" statement give details about the deviation. The argument string is an absolute schema node identifier (see Section 6.5). @@ -4818,31 +5027,31 @@ or software ability to support parts of a standard module. When this occurs, the device makes a choice either to treat attempts to configure unsupported parts of the module as an error that is reported back to the unsuspecting application or ignore those incoming requests. Neither choice is acceptable. Instead, YANG allows devices to document portions of a base module that are not supported or supported but with different syntax, by using the "deviation" statement. -7.19.3.1. The deviation's Substatements +7.20.3.1. The deviation's Substatements +--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ - | description | 7.20.3 | 0..1 | - | deviate | 7.19.3.2 | 1..n | - | reference | 7.20.4 | 0..1 | + | description | 7.21.3 | 0..1 | + | deviate | 7.20.3.2 | 1..n | + | reference | 7.21.4 | 0..1 | +--------------+----------+-------------+ -7.19.3.2. The deviate Statement +7.20.3.2. The deviate Statement The "deviate" statement defines how the device's implementation of the target node deviates from its original definition. The argument is one of the strings "not-supported", "add", "replace", or "delete". The argument "not-supported" indicates that the target node is not implemented by this device. The argument "add" adds properties to the target node. The properties to add are identified by substatements to the "deviate" @@ -4856,34 +5065,34 @@ The argument "delete" deletes properties from the target node. The properties to delete are identified by substatements to the "delete" statement. The substatement's keyword MUST match a corresponding keyword in the target node, and the argument's string MUST be equal to the corresponding keyword's argument string in the target node. +--------------+-------------+-------------+ | substatement | section | cardinality | +--------------+-------------+-------------+ - | config | 7.20.1 | 0..1 | + | config | 7.21.1 | 0..1 | | default | 7.6.4 7.7.4 | 0..n | | mandatory | 7.6.5 | 0..1 | | max-elements | 7.7.6 | 0..1 | | min-elements | 7.7.5 | 0..1 | | must | 7.5.3 | 0..n | | type | 7.4 | 0..1 | | unique | 7.8.3 | 0..n | | units | 7.3.3 | 0..1 | +--------------+-------------+-------------+ The deviate's Substatements -7.19.3.3. Usage Example +7.20.3.3. Usage Example In this example, the device is informing client applications that it does not support the "daytime" service in the style of RFC 867. deviation /base:system/base:daytime { deviate not-supported; } The following example sets a device-specific default value to a leaf that does not have a default value defined: @@ -4910,26 +5119,26 @@ } a device might remove this must constraint by doing: deviation "/base:system" { deviate delete { must "daytime or time"; } } -7.20. Common Statements +7.21. Common Statements This section defines substatements common to several other statements. -7.20.1. The config Statement +7.21.1. The config Statement The "config" statement takes as an argument the string "true" or "false". If "config" is "true", the definition represents configuration. Data nodes representing configuration will be part of the reply to a request, and can be sent in a or request. If "config" is "false", the definition represents state data. Data nodes representing state data will be part of the reply to a , but not to a request, and cannot be sent in a @@ -4938,21 +5147,21 @@ If "config" is not specified, the default is the same as the parent schema node's "config" value. If the parent node is a "case" node, the value is the same as the "case" node's parent "choice" node. If the top node does not specify a "config" statement, the default is "true". If a node has "config" set to "false", no node underneath it can have "config" set to "true". -7.20.2. The status Statement +7.21.2. The status Statement The "status" statement takes as an argument one of the strings "current", "deprecated", or "obsolete". o "current" means that the definition is current and valid. o "deprecated" indicates an obsolete definition, but it permits new/ continued implementation in order to foster interoperability with older/existing implementations. @@ -4972,47 +5181,47 @@ typedef my-type { status deprecated; type int32; } leaf my-leaf { status current; type my-type; // illegal, since my-type is deprecated } -7.20.3. The description Statement +7.21.3. The description Statement The "description" statement takes as an argument a string that contains a human-readable textual description of this definition. The text is provided in a language (or languages) chosen by the module developer; for the sake of interoperability, it is RECOMMENDED to choose a language that is widely understood among the community of network administrators who will use the module. -7.20.4. The reference Statement +7.21.4. The reference Statement The "reference" statement takes as an argument a string that is used to specify a textual cross-reference to an external document, either another module that defines related management information, or a document that provides additional information relevant to this definition. For example, a typedef for a "uri" data type could look like: typedef uri { type string; reference "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; ... } -7.20.5. The when Statement +7.21.5. The when Statement The "when" statement makes its parent data definition statement conditional. The node defined by the parent data definition statement is only valid when the condition specified by the "when" statement is satisfied. The statement's argument is an XPath expression (see Section 6.4), which is used to formally specify this condition. If the XPath expression conceptually evaluates to "true" for a particular instance, then the node defined by the parent data definition statement is valid; otherwise, it is not. @@ -5027,25 +5236,28 @@ o If the "when" statement is a child of an "augment" statement, then the context node is the augment's target node in the data tree, if the target node is a data node. Otherwise, the context node is the closest ancestor node to the target node that is also a data node. o If the "when" statement is a child of a "uses", "choice", or "case" statement, then the context node is the closest ancestor node to the "uses", "choice", or "case" node that is also a data - node. + node. If no such node exists, the context node is the root node. o If the "when" statement is a child of any other data definition - statement, the context node is the node in the accessible tree for - which the "when" statement is defined. + statement, the accessible tree is tentatively altered during the + processing of the XPath expression by replacing all instances (if + any) of the data node for which the "when" statement is defined + with a single dummy node with the same name, but with no value and + no children. The context node is this dummy node. The result of the XPath expression is converted to a boolean value using the standard XPath rules. If the XPath expression references any node that also has associated "when" statements, these "when" expressions MUST be evaluated first. There MUST NOT be any circular dependencies in these "when" expressions. Note that the XPath expression is conceptually evaluated. This means @@ -5315,24 +5527,24 @@ for the type being restricted, respectively. The range expression syntax is formally defined by the rule "range-arg" in Section 13. 9.2.4.1. The range's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ - | description | 7.20.3 | 0..1 | + | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ 9.2.5. Usage Example typedef my-base-int32-type { type int32 { range "1..4 | 10..20"; } } @@ -5348,23 +5560,23 @@ // illegal range restriction range "11..100"; } } 9.3. The decimal64 Built-In Type The decimal64 type represents a subset of the real numbers, which can be represented by decimal numerals. The value space of decimal64 is the set of numbers that can be obtained by multiplying a 64-bit - signed integer by a negative power of ten, i.e., expressible as "i x - 10^-n" where i is an integer64 and n is an integer between 1 and 18, - inclusively. + signed integer by a negative power of ten, i.e., expressible as + "i x 10^-n" where i is an integer64 and n is an integer between 1 and + 18, inclusively. 9.3.1. Lexical Representation A decimal64 value is lexically represented as an optional sign ("+" or "-"), followed by a sequence of decimal digits, optionally followed by a period ('.') as a decimal indicator and a sequence of decimal digits. If no sign is specified, "+" is assumed. 9.3.2. Canonical Form @@ -5473,24 +5685,24 @@ 18446744073709551615. The length expression syntax is formally defined by the rule "length-arg" in Section 13. 9.4.4.1. The length's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ - | description | 7.20.3 | 0..1 | + | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ 9.4.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 match the pattern. @@ -5499,25 +5711,25 @@ If a pattern restriction is applied to an already pattern-restricted type, values must match all patterns in the base type, in addition to the new patterns. 9.4.5.1. The pattern's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ - | description | 7.20.3 | 0..1 | + | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | | modifier | 9.4.6 | 0..1 | - | reference | 7.20.4 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ 9.4.6. The modifier Statement 9.4.7. Usage Example With the following typedef: typedef my-base-str-type { type string { @@ -5631,24 +5843,24 @@ When an existing enumeration type is restricted, the set of assigned names in the new type MUST be a subset of the base type's set of assigned names. The value of such an assigned name MUST not be changed. 9.6.4.1. The enum's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | value | 9.6.4.2 | 0..1 | +--------------+---------+-------------+ 9.6.4.2. The value Statement The "value" statement, which is optional, is used to associate an integer value with the assigned name for the enum. This integer value MUST be in the range -2147483648 to 2147483647, and it MUST be unique within the enumeration type. @@ -5657,23 +5869,22 @@ value is zero (0); otherwise, the assigned value is one greater than the current highest enum value (i.e., the highest enum value, implicit or explicit, prior to the current "enum" substatement in the parent "type" statement). If the current highest value is equal to 2147483647, then an enum value MUST be specified for "enum" substatements following the one with the current highest value. When an existing enumeration type is restricted, the "value" - statement MUST either have the same value as the in the base type or - not be present, in which case the value is the same as in the base - type. + statement MUST either have the same value as in the base type or not + be present, in which case the value is the same as in the base type. 9.6.5. Usage Example leaf myenum { type enumeration { enum zero; enum one; enum seven { value 7; } } @@ -5751,35 +5962,33 @@ followed by a block of substatements that holds detailed bit information. The assigned name follows the same syntax rules as an identifier (see Section 6.2). All assigned names in a bits type MUST be unique. 9.7.4.1. The bit's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ - | description | 7.20.3 | 0..1 | - | if-feature | 7.19.2 | 0..n | - | reference | 7.20.4 | 0..1 | - | status | 7.20.2 | 0..1 | + | description | 7.21.3 | 0..1 | + | if-feature | 7.20.2 | 0..n | + | reference | 7.21.4 | 0..1 | + | status | 7.21.2 | 0..1 | | position | 9.7.4.2 | 0..1 | +--------------+---------+-------------+ 9.7.4.2. The position Statement The "position" statement, which is optional, takes as an argument a non-negative integer value that specifies the bit's position within a hypothetical bit field. The position value MUST be in the range 0 to - 4294967295, and it MUST be unique within the bits type. The value is - unused by YANG and the NETCONF messages, but is carried as a - convenience to implementors. + 4294967295, and it MUST be unique within the bits type. If a bit position is not specified, then one will be automatically assigned. If the "bit" substatement is the first one defined, the assigned value is zero (0); otherwise, the assigned value is one greater than the current highest bit position (i.e., the highest bit position, implicit or explicit, prior to the current "bit" substatement in the parent "type" statement). If the current highest bit position value is equal to 4294967295, then a position value MUST be specified for "bit" substatements @@ -5790,31 +5999,31 @@ Given the following leaf: leaf mybits { type bits { bit disable-nagle { position 0; } bit auto-sense-speed { position 1; } - bit ten-Mb-only { + bit ten-mb-only { position 2; } } default "auto-sense-speed"; } The lexical representation of this leaf with bit values disable-nagle - and ten-Mb-only set would be: + and ten-mb-only set would be: - disable-nagle ten-Mb-only + disable-nagle ten-mb-only 9.8. The binary Built-In Type The binary built-in type represents any binary data, i.e., a sequence of octets. 9.8.1. Restrictions A binary can be restricted with the "length" (Section 9.4.4) statement. The length of a binary value is the number of octets it @@ -5841,21 +6050,21 @@ the "require-instance" property (Section 9.9.3) is "true", the leaf it refers to MUST also represent configuration. Such a leaf puts a constraint on valid data. All such nodes MUST reference existing leaf instances or leafs with default values in use (see Section 7.6.1 and Section 7.7.2) for the data to be valid. This constraint is enforced according to the rules in Section 8. There MUST NOT be any circular chains of leafrefs. If the leaf that the leafref refers to is conditional based on one or - more features (see Section 7.19.2), then the leaf with the leafref + more features (see Section 7.20.2), then the leaf with the leafref type MUST also be conditional based on at least the same set of features. 9.9.1. Restrictions A leafref can be restricted with the "require-instance" statement (Section 9.9.3). 9.9.2. The path Statement @@ -6058,21 +6267,21 @@ 2008-04-01T00:01:00Z eth0 up 9.10. The identityref Built-In Type The identityref type is used to reference an existing identity (see - Section 7.17). + Section 7.18). 9.10.1. Restrictions An identityref cannot be restricted. 9.10.2. The identityref's base Statement The "base" statement, which is a substatement to the "type" statement, MUST be present at least once if the type is "identityref". The argument is the name of an identity, as defined @@ -6109,21 +6318,21 @@ corresponding "import" statement. Otherwise, the prefix in the string value is the prefix for the current module. 9.10.4. Canonical Form Since the lexical form depends on the XML context in which the value occurs, this type does not have a canonical form. 9.10.5. Usage Example - With the identity definitions in Section 7.17.3 and the following + With the identity definitions in Section 7.18.3 and the following module: module my-crypto { yang-version 1.1; namespace "http://example.com/my-crypto"; prefix mc; import "crypto-base" { prefix "crypto"; } @@ -6723,40 +6932,41 @@ via the "extension" statement. The names of all YIN elements MUST be properly qualified with their namespaces specified above using the standard mechanisms of [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes. The argument of a YANG statement is represented in YIN either as an XML attribute or a subelement of the keyword element. Table 1 defines the mapping for the set of YANG keywords. For extensions, the argument mapping is specified within the "extension" statement - (see Section 7.18). The following rules hold for arguments: + (see Section 7.19). The following rules hold for arguments: o If the argument is represented as an attribute, this attribute has no namespace. o If the argument is represented as an element, it is qualified by the same namespace as its parent keyword element. o If the argument is represented as an element, it MUST be the first child of the keyword element. Substatements of a YANG statement are represented as (additional) children of the keyword element and their relative order MUST be the same as the order of substatements in YANG. Comments in YANG MAY be mapped to XML comments. +------------------+---------------+-------------+ | keyword | argument name | yin-element | +------------------+---------------+-------------+ + | anydata | 7.10 | 0..n | | anyxml | name | false | | argument | name | false | | augment | target-node | false | | base | name | false | | belongs-to | module | false | | bit | name | false | | case | name | false | | choice | name | false | | config | value | false | | contact | text | true | @@ -6839,21 +7049,21 @@ } leaf mtu { type uint32; description "The MTU of the interface."; myext:c-define "MY_MTU"; } } } - where the extension "c-define" is defined in Section 7.18.3, is + where the extension "c-define" is defined in Section 7.19.3, is translated into the following YIN: @@ -6941,20 +7151,21 @@ augment-stmt / rpc-stmt / notification-stmt / deviation-stmt) data-def-stmt = container-stmt / leaf-stmt / leaf-list-stmt / list-stmt / choice-stmt / + anydata-stmt / anyxml-stmt / uses-stmt yang-version-stmt = yang-version-keyword sep yang-version-arg-str stmtend yang-version-arg-str = < a string that matches the rule > < yang-version-arg > yang-version-arg = "1.1" @@ -7289,37 +7497,39 @@ grouping-stmt = grouping-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [status-stmt] [description-stmt] [reference-stmt] *(typedef-stmt / grouping-stmt) *data-def-stmt *action-stmt + *notification-stmt "}") stmtsep container-stmt = container-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt *must-stmt [presence-stmt] [config-stmt] [status-stmt] [description-stmt] [reference-stmt] *(typedef-stmt / grouping-stmt) *data-def-stmt *action-stmt + *notification-stmt "}") stmtsep leaf-stmt = leaf-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt type-stmt [units-stmt] *must-stmt @@ -7361,20 +7571,21 @@ [config-stmt] [min-elements-stmt] [max-elements-stmt] [ordered-by-stmt] [status-stmt] [description-stmt] [reference-stmt] *(typedef-stmt / grouping-stmt) 1*data-def-stmt *action-stmt + *notification-stmt "}" stmtsep key-stmt = key-keyword sep key-arg-str stmtend key-arg-str = < a string that matches the rule > < key-arg > key-arg = node-identifier *(sep node-identifier) unique-stmt = unique-keyword sep unique-arg-str stmtend @@ -7397,43 +7609,57 @@ [description-stmt] [reference-stmt] *(short-case-stmt / case-stmt) "}") stmtsep short-case-stmt = choice-stmt / container-stmt / leaf-stmt / leaf-list-stmt / list-stmt / + anydata-stmt / anyxml-stmt case-stmt = case-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt [status-stmt] [description-stmt] [reference-stmt] *data-def-stmt "}") stmtsep - anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep + anydata-stmt = anydata-keyword sep identifier-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt *must-stmt [config-stmt] + [mandatory-stmt] + [status-stmt] + [description-stmt] + [reference-stmt] + "}") stmtsep + anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep + (";" / + "{" stmtsep + ;; these stmts can appear in any order + [when-stmt] + *if-feature-stmt + *must-stmt + [config-stmt] [mandatory-stmt] [status-stmt] [description-stmt] [reference-stmt] "}") stmtsep uses-stmt = uses-keyword sep identifier-ref-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order @@ -7467,38 +7694,39 @@ refine-arg = descendant-schema-nodeid uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt [status-stmt] [description-stmt] [reference-stmt] - 1*(data-def-stmt / case-stmt / action-stmt) - + 1*(data-def-stmt / case-stmt / + action-stmt / notification-stmt) "}" stmtsep uses-augment-arg-str = < a string that matches the rule > < uses-augment-arg > uses-augment-arg = descendant-schema-nodeid augment-stmt = augment-keyword sep augment-arg-str optsep "{" stmtsep ;; these stmts can appear in any order [when-stmt] *if-feature-stmt [status-stmt] [description-stmt] [reference-stmt] - 1*(data-def-stmt / case-stmt / action-stmt) + 1*(data-def-stmt / case-stmt / + action-stmt / notification-stmt) "}" stmtsep augment-arg-str = < a string that matches the rule > < augment-arg > augment-arg = absolute-schema-nodeid when-stmt = when-keyword sep string optsep (";" / "{" stmtsep @@ -7634,20 +7863,21 @@ < replace-keyword > ;; represents the usage of an extension statement unknown-statement = prefix ":" identifier [sep string] optsep (";" / "{" optsep *((yang-stmt / unknown-statement) optsep) "}") stmtsep yang-stmt = action-stmt / + anydata-stmt / anyxml-stmt / argument-stmt / augment-stmt / base-stmt / belongs-to-stmt / bit-stmt / case-stmt / choice-stmt / config-stmt / contact-stmt / @@ -7791,20 +8022,21 @@ rel-path-keyexpr rel-path-keyexpr = 1*(".." *WSP "/" *WSP) *(node-identifier *WSP "/" *WSP) node-identifier ;;; Keywords, using RFC 7405 syntax for case-sensitive strings ;; statement keywords action-keyword = %s"action" + anydata-keyword = %s"anydata" anyxml-keyword = %s"anyxml" argument-keyword = %s"argument" augment-keyword = %s"augment" base-keyword = %s"base" belongs-to-keyword = %s"belongs-to" bit-keyword = %s"bit" case-keyword = %s"case" choice-keyword = %s"choice" config-keyword = %s"config" contact-keyword = %s"contact" @@ -8060,27 +8292,27 @@ 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. error-tag: operation-failed error-app-tag: must-violation 14.5. Error Message for Data That Violates a require-instance Statement If a NETCONF operation would result in configuration data where a - leaf of type "instance-identifier" marked with require-instance - "true" refers to a non-existing instance, the following error is - returned: + leaf of type "instance-identifier" or "leafref" marked with require- + instance "true" refers to a non-existing instance, the following + error is returned: error-tag: data-missing error-app-tag: instance-required - error-path: Path to the instance-identifier leaf. + error-path: Path to the instance-identifier or leafref leaf. 14.6. Error Message for Data That Does Not Match a leafref Type If a NETCONF operation would result in configuration data where a leaf of type "leafref" refers to a non-existing instance, the following error is returned: error-tag: data-missing error-app-tag: instance-required error-path: Path to the leafref leaf. @@ -8303,60 +8536,70 @@ The editor wishes to thank the following individuals, who all provided helpful comments on various versions of this document: Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert Wijnen. 19. ChangeLog RFC Editor: remove this section upon publication as an RFC. -19.1. Version -04 +19.1. Version -05 + + o Included solution Y18-01. + + o Included solution Y25-02 (parts of it was included in -04). + + o Included solution Y34-05. + + o Included solution Y36-03. + +19.2. Version -04 o Incorporated changes to ABNF grammar after review and errata for RFC 6020. o Included solution Y16-03. o Included solution Y49-04. o Included solution Y58-01. o Included solution Y59-01. -19.2. Version -03 +19.3. Version -03 o Incorporated changes from WG reviews. o Included solution Y05-01. o Included solution Y10-01. o Included solution Y13-01. o Included solution Y28-02. o Included solution Y55-01 (parts of it was included in -01). -19.3. Version -02 +19.4. Version -02 o Included solution Y02-01. o Included solution Y04-02. o Included solution Y11-01. o Included solution Y41-01. o Included solution Y56-01. -19.4. Version -01 +19.5. Version -01 o Included solution Y01-01. o Included solution Y03-01. o Included solution Y06-02. o Included solution Y07-01. o Included solution Y14-01. @@ -8366,29 +8609,28 @@ o Included solution Y23-01. o Included solution Y29-01. o Included solution Y30-01. o Included solution Y31-01. o Included solution Y35-01. -19.5. Version -00 +19.6. Version -00 o Applied all reported errata for RFC 6020. o Updated YANG version to 1.1, and made the "yang-version" statement mandatory. 20. References - 20.1. Normative References [I-D.ietf-netconf-yang-library] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Library", draft-ietf-netconf-yang-library (work in progress), January 2015. [ISO.10646] International Organization for Standardization, "Information Technology - Universal Multiple-Octet Coded