--- 1/draft-ietf-netmod-rfc6020bis-12.txt 2016-06-10 03:15:56.986404410 -0700 +++ 2/draft-ietf-netmod-rfc6020bis-13.txt 2016-06-10 03:15:57.334412896 -0700 @@ -1,42 +1,47 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track April 28, 2016 -Expires: October 30, 2016 +Intended status: Standards Track June 10, 2016 +Expires: December 12, 2016 The YANG 1.1 Data Modeling Language - draft-ietf-netmod-rfc6020bis-12 + draft-ietf-netmod-rfc6020bis-13 Abstract YANG is a data modeling language used to model configuration data, state data, remote procedure calls, and notifications for network - management protocols. This document also specifies the YANG mappings - to the Network Configuration Protocol (NETCONF). + management protocols. This document describes the syntax and + semantics of 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. There are a small number of + backward incompatibilities from YANG version 1. This document also + specifies the YANG mappings to the Network Configuration Protocol + (NETCONF). Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. 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 October 30, 2016. + This Internet-Draft will expire on December 12, 2016. Copyright Notice Copyright (c) 2016 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 @@ -58,372 +63,386 @@ 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 . . . . . . . . . . . . 9 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1. A Note on Examples . . . . . . . . . . . . . . . . . . . 14 - 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 - 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 14 + 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 15 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 16 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 16 - 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 - 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 + 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 17 + 4.2.3. Configuration and State Data . . . . . . . . . . . . 21 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 21 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 22 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 23 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 24 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 25 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 26 4.2.10. Notification Definitions . . . . . . . . . . . . . . 29 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 29 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 29 5.1.1. Import and Include by Revision . . . . . . . . . . . 31 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 32 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 33 - 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 33 + 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 34 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 34 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 34 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 34 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 35 - 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 35 - 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 35 + 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 36 + 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 36 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 36 - 5.6.4. Announcing Conformance Information in NETCONF . . . . 36 - 5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 37 - 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 40 + 5.6.4. Announcing Conformance Information in NETCONF . . . . 37 + 5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 38 + 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 41 + 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 41 + 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 42 + 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 42 + 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 42 + 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 42 + 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 44 + 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 44 + 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 46 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 46 + 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 47 + 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 51 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 52 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 52 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 53 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 54 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 55 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 55 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 56 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 57 + 7.1.7. The organization Statement . . . . . . . . . . . . . 57 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 58 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 58 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 58 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 59 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 60 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 61 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 62 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 62 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 63 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 63 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 63 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 63 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 64 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 64 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 64 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 64 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 65 + 7.5.2. The container's Substatements . . . . . . . . . . . . 65 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 66 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 67 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 68 + 7.5.6. The container's Child Node Statements . . . . . . . . 68 + 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 68 + 7.5.8. NETCONF Operations . . . . . . . . . . 69 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 69 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 71 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 71 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 72 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 72 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 72 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 73 + 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 73 + 7.6.7. NETCONF Operations . . . . . . . . . . 73 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 74 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 74 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 75 + 7.7.2. The leaf-list's default values . . . . . . . . . . . 75 + 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 76 + 7.7.4. The leaf-list's default Statement . . . . . . . . . . 77 + 7.7.5. The min-elements Statement . . . . . . . . . . . . . 77 + 7.7.6. The max-elements Statement . . . . . . . . . . . . . 78 + 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 78 + 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 79 + 7.7.9. NETCONF Operations . . . . . . . . . . 79 + 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 80 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 81 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 82 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 82 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 83 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 84 + 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 84 + 7.8.6. NETCONF Operations . . . . . . . . . . 85 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 89 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 89 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 90 + 7.9.3. The choice's default Statement . . . . . . . . . . . 91 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 93 + 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 93 + 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 93 + 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 94 + 7.10.1. The anydata's Substatements . . . . . . . . . . . . 95 + 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 95 + 7.10.3. NETCONF Operations . . . . . . . . . . 95 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 96 + 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 97 + 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 97 + 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 97 + 7.11.3. NETCONF Operations . . . . . . . . . . 98 + 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 98 - 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 40 - 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 41 - 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 41 - 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 41 - 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 41 - 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 43 - 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 43 - 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 44 - 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 44 - 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 45 - 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 45 - 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 50 - 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 51 - 7.1. The module Statement . . . . . . . . . . . . . . . . . . 51 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 52 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 53 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 54 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 54 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 54 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 56 - 7.1.7. The organization Statement . . . . . . . . . . . . . 56 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 56 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 57 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 57 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 58 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 59 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 60 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 61 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 61 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 62 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 62 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 62 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 62 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 63 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 63 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 63 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 63 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 64 - 7.5.2. The container's Substatements . . . . . . . . . . . . 64 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 65 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 66 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 67 - 7.5.6. The container's Child Node Statements . . . . . . . . 67 - 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 67 - 7.5.8. NETCONF Operations . . . . . . . . . . 68 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 68 - 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 69 - 7.6.1. The leaf's default value . . . . . . . . . . . . . . 69 - 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 70 - 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 71 - 7.6.4. The leaf's default Statement . . . . . . . . . . . . 71 - 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 71 - 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 72 - 7.6.7. NETCONF Operations . . . . . . . . . . 72 - 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 72 - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 73 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 73 - 7.7.2. The leaf-list's default values . . . . . . . . . . . 74 - 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 75 - 7.7.4. The leaf-list's default Statement . . . . . . . . . . 75 - 7.7.5. The min-elements Statement . . . . . . . . . . . . . 76 - 7.7.6. The max-elements Statement . . . . . . . . . . . . . 76 - 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 76 - 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 77 - 7.7.9. NETCONF Operations . . . . . . . . . . 77 - 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 78 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 80 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 80 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 81 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 82 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 83 - 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 83 - 7.8.6. NETCONF Operations . . . . . . . . . . 84 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 85 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 88 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 88 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 89 - 7.9.3. The choice's default Statement . . . . . . . . . . . 90 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 92 - 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 - 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 92 - 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 93 - 7.10.1. The anydata's Substatements . . . . . . . . . . . . 94 - 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 94 - 7.10.3. NETCONF Operations . . . . . . . . . . 94 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 95 - 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 95 - 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 96 - 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 96 - 7.11.3. NETCONF Operations . . . . . . . . . . 96 - 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 97 - 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 97 - 7.12.1. The grouping's Substatements . . . . . . . . . . . . 98 - 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 99 - 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 99 - 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 99 - 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 100 - 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 101 - 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 101 - 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 102 - 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 102 - 7.14.2. The input Statement . . . . . . . . . . . . . . . . 103 - 7.14.3. The output Statement . . . . . . . . . . . . . . . . 104 - 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 105 - 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 105 - 7.15. The action Statement . . . . . . . . . . . . . . . . . . 106 - 7.15.1. The action's Substatements . . . . . . . . . . . . . 107 - 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 107 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 - 7.16. The notification Statement . . . . . . . . . . . . . . . 109 - 7.16.1. The notification's Substatements . . . . . . . . . . 110 - 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 110 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 111 - 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 112 - 7.17.1. The augment's Substatements . . . . . . . . . . . . 114 - 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 115 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 115 - 7.18. The identity Statement . . . . . . . . . . . . . . . . . 117 - 7.18.1. The identity's Substatements . . . . . . . . . . . . 117 - 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 117 - 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 118 - 7.19. The extension Statement . . . . . . . . . . . . . . . . . 120 - 7.19.1. The extension's Substatements . . . . . . . . . . . 120 - 7.19.2. The argument Statement . . . . . . . . . . . . . . . 120 - 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 121 - 7.20. Conformance-Related Statements . . . . . . . . . . . . . 122 - 7.20.1. The feature Statement . . . . . . . . . . . . . . . 122 - 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 124 - 7.20.3. The deviation Statement . . . . . . . . . . . . . . 124 - 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 128 - 7.21.1. The config Statement . . . . . . . . . . . . . . . . 128 - 7.21.2. The status Statement . . . . . . . . . . . . . . . . 128 - 7.21.3. The description Statement . . . . . . . . . . . . . 129 - 7.21.4. The reference Statement . . . . . . . . . . . . . . 129 - 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 130 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 131 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 131 - 8.2. Configuration Data Modifications . . . . . . . . . . . . 132 - 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 132 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 132 - 8.3.2. NETCONF Processing . . . . . . . . . . 133 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 134 - 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 134 - 9.1. Canonical Representation . . . . . . . . . . . . . . . . 134 - 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 135 - 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 135 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 136 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 136 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 136 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 - 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 137 - 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 138 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 138 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 138 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 139 - 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 139 - 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 139 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 140 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 140 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 140 - 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 141 - 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 141 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 141 - 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 143 - 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 143 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 143 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 143 - 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 143 - 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 143 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 143 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 143 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 143 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 145 - 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 146 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 - 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 146 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 147 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 147 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 148 - 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 149 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149 - 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 149 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 149 - 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 149 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 150 - 9.9.3. The require-instance Statement . . . . . . . . . . . 150 - 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 151 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 151 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 151 - 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 155 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 155 - 9.10.2. The identityref's base Statement . . . . . . . . . . 155 - 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 155 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 156 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 156 - 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 157 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 157 - 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 157 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 157 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 157 - 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 158 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 - 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 158 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 - 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 - 9.13. The instance-identifier Built-In Type . . . . . . . . . . 159 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 160 - 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 160 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 160 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 161 - 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 161 - 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 161 - 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 161 - 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 162 - 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 162 + 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 99 + 7.12.1. The grouping's Substatements . . . . . . . . . . . . 99 + 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 100 + 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 100 + 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 101 + 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 101 + 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 + 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 102 + 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 103 + 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 103 + 7.14.2. The input Statement . . . . . . . . . . . . . . . . 104 + 7.14.3. The output Statement . . . . . . . . . . . . . . . . 105 + 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 106 + 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 106 + 7.15. The action Statement . . . . . . . . . . . . . . . . . . 107 + 7.15.1. The action's Substatements . . . . . . . . . . . . . 108 + 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 + 7.16. The notification Statement . . . . . . . . . . . . . . . 110 + 7.16.1. The notification's Substatements . . . . . . . . . . 111 + 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 111 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 + 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 113 + 7.17.1. The augment's Substatements . . . . . . . . . . . . 115 + 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 116 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 + 7.18. The identity Statement . . . . . . . . . . . . . . . . . 118 + 7.18.1. The identity's Substatements . . . . . . . . . . . . 118 + 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 118 + 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 + 7.19. The extension Statement . . . . . . . . . . . . . . . . . 121 + 7.19.1. The extension's Substatements . . . . . . . . . . . 121 + 7.19.2. The argument Statement . . . . . . . . . . . . . . . 121 + 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 122 + 7.20. Conformance-Related Statements . . . . . . . . . . . . . 123 + 7.20.1. The feature Statement . . . . . . . . . . . . . . . 123 + 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 125 + 7.20.3. The deviation Statement . . . . . . . . . . . . . . 125 + 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 129 + 7.21.1. The config Statement . . . . . . . . . . . . . . . . 129 + 7.21.2. The status Statement . . . . . . . . . . . . . . . . 129 + 7.21.3. The description Statement . . . . . . . . . . . . . 130 + 7.21.4. The reference Statement . . . . . . . . . . . . . . 130 + 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 131 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 132 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 132 + 8.2. Configuration Data Modifications . . . . . . . . . . . . 133 + 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 133 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 133 + 8.3.2. NETCONF Processing . . . . . . . . . . 134 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 135 + 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 135 + 9.1. Canonical Representation . . . . . . . . . . . . . . . . 135 + 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 136 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 136 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 137 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 137 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 137 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 + 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 138 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 139 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 139 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 139 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 139 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 140 + 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 140 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 140 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 141 + 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 142 + 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 142 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 142 + 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 144 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 144 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 + 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 144 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 144 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 144 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 + 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 147 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 147 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 148 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 149 + 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 150 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 150 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 150 + 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 150 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 151 + 9.9.3. The require-instance Statement . . . . . . . . . . . 152 + 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 152 + 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 152 + 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 152 + 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 156 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 + 9.10.2. The identityref's base Statement . . . . . . . . . . 156 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 156 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 157 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 157 + 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 158 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 158 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 + 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 159 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 159 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 159 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 159 + 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 + 9.13. The instance-identifier Built-In Type . . . . . . . . . . 160 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 161 + 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 161 + 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 161 + 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 162 + 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 162 + 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 162 + 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 162 + 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 163 + 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 163 10.3. Functions for the YANG Types "leafref" and "instance- - identifier" . . . . . . . . . . . . . . . . . . . . . . 163 - 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 163 - 10.4. Functions for the YANG Type "identityref" . . . . . . . 164 - 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 164 - 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 165 - 10.5. Functions for the YANG Type "enumeration" . . . . . . . 166 - 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 166 - 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 167 - 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 167 - 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 168 - 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 170 - 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 - 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 171 - 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 174 - 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 175 - 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 199 - 15.1. Error Message for Data That Violates a unique Statement 199 + identifier" . . . . . . . . . . . . . . . . . . . . . . 164 + 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 164 + 10.4. Functions for the YANG Type "identityref" . . . . . . . 165 + 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 165 + 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 166 + 10.5. Functions for the YANG Type "enumeration" . . . . . . . 167 + 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 167 + 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 168 + 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 168 + 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 169 + 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 171 + 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 + 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 172 + 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 175 + 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 176 + 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 200 + 15.1. Error Message for Data That Violates a unique Statement 201 15.2. Error Message for Data That Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 200 + Statement . . . . . . . . . . . . . . . . . . . . . . . 201 15.3. Error Message for Data That Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 200 - 15.4. Error Message for Data That Violates a must Statement . 200 - 15.5. Error Message for Data That Violates a require-instance Statement . . . . . . . . . . . . . . . . . . . . . . . 201 + 15.4. Error Message for Data That Violates a must Statement . 201 + 15.5. Error Message for Data That Violates a require-instance + Statement . . . . . . . . . . . . . . . . . . . . . . . 202 15.6. Error Message for Data That Violates a mandatory choice - Statement . . . . . . . . . . . . . . . . . . . . . . . 201 - 15.7. Error Message for the "insert" Operation . . . . . . . . 201 - 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 201 - 17. Security Considerations . . . . . . . . . . . . . . . . . . . 201 - 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 202 - 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 202 - 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 203 - 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 203 - 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 203 - 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 203 - 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 203 - 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 203 - 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 204 - 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 204 - 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 204 - 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 204 - 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 205 - 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 205 - 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 205 - 21.1. Normative References . . . . . . . . . . . . . . . . . . 205 - 21.2. Informative References . . . . . . . . . . . . . . . . . 207 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 208 + Statement . . . . . . . . . . . . . . . . . . . . . . . 202 + 15.7. Error Message for the "insert" Operation . . . . . . . . 202 + 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 202 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 203 + 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 203 + 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 204 + 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 204 + 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 204 + 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 204 + 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 204 + 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 205 + 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 205 + 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 205 + 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 205 + 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 205 + 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 206 + 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 206 + 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 206 + 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 206 + 21.1. Normative References . . . . . . . . . . . . . . . . . . 207 + 21.2. Informative References . . . . . . . . . . . . . . . . . 208 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 209 1. Introduction YANG is a data modeling language originally designed to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications [RFC6241]. Since the publication of YANG version 1 [RFC6020], YANG has been used or proposed to be used for other protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI [I-D.vanderstok-core-comi]). Further, other encodings than XML have been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). This document describes the syntax and semantics of version 1.1 of the YANG language. It also describes how a data model defined in a YANG module is encoded in the Extensible Markup Language (XML), and how NETCONF operations are used to manipulate the data. Other protocols and encodings are possible, but out of scope for this specification. + In terms of developing YANG data models, [I-D.ietf-netmod-rfc6087bis] + provides some guidelines and recommendations. + + Note that this document does not obsolete RFC 6020 [RFC6020]. + 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]. The following changes are not backwards compatible with YANG version 1: o Changed the rules for the interpretation of escaped characters in double quoted strings. This is an backwards incompatible change - 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 + from YANG version 1. When updating a YANG version 1 module to + 1.1, and the module uses a character sequence that is now illegal, + the string must be changed to match the new rules. See Section 6.1.3 for details. o An unquoted string cannot contain any single or double quote characters. This is an backwards incompatible change from YANG - version 1. + version 1. When updating a YANG version 1 module to 1.1, and the + module uses such quote characters, the string must be changed to + match the new rules. See Section 6.1.3 for details. - The following additional changes have been done to YANG: + o Made "when" and "if-feature" illegal on list keys. This is an + backwards incompatible change from YANG version 1. When updating + a YANG version 1 module to 1.1, and the module uses these + constructs, they must be removed to match the new rules. - o Changed the YANG version from "1" to "1.1". + o Defined the legal characters in YANG modules. When updating a + YANG version 1 module to 1.1, any characters that are now illegal + must be removed. See Section 6 for details. - o Made the "yang-version" statement mandatory. + o Made noncharacters illegal in the built-in type "string". This + change affects the run-time behavior of YANG-based protocols. - o Made noncharacters illegal in the built-in type "string". + The following additional changes have been done to YANG: - o Defined the legal characters in YANG modules. + o Changed the YANG version from "1" to "1.1". + + o Made the "yang-version" statement mandatory in YANG version "1.1". 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. - o Allow "choice" as a shorthand case statement (see Section 7.9). o Added a new substatement "modifier" to pattern (see Section 9.4.6). o Allow "must" in "input", "output", and "notification". o Allow "require-instance" in leafref. o Allow "description" and "reference" in "import" and "include". @@ -546,22 +565,22 @@ o feature: A mechanism for marking a portion of the model as optional. Definitions can be tagged with a feature name and are only valid on servers that support that feature. o grouping: A reusable set of schema nodes, which may be used locally in the module and by other modules that import from it. The grouping statement is not a data definition statement and, as such, does not define any nodes in the schema tree. - o identifier: Used to identify different kinds of YANG items by - name. + o identifier: A string used to identify different kinds of YANG + items by name. o identity: A globally unique, abstract, and untyped name. o instance identifier: A mechanism for identifying a particular node in a data tree. o interior node: Nodes within a hierarchy that are not leaf nodes. o leaf: A data node that exists in at most one instance in the data tree. A leaf has a value but no child nodes. @@ -575,27 +594,33 @@ nodes. o mandatory node: A mandatory node is one of: * A leaf, choice, anydata, or anyxml node with a "mandatory" statement with the value "true". * A list or leaf-list node with a "min-elements" statement with a value greater than zero. - * A container node without a "presence" statement, which has at - least one mandatory node as a child. + * A container node without a "presence" statement and which has + at least one mandatory node as a child. - o module: A YANG module defines a hierarchy of schema nodes. With + o module: A YANG module defines hierarchies of schema nodes. With its definitions and the definitions it imports or includes from elsewhere, a module is self-contained and "compilable". + o non-presence container: A container that has no meaning of its + own, existing only to contain child nodes. + + o presence container: A container where the presence of the + container itself carries some meaning. + o RPC: A Remote Procedure Call. o RPC operation: A specific Remote Procedure Call. 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. @@ -614,20 +639,24 @@ 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. + o value space: For a data type; the set of values permitted by the + data type. For a leaf or leaf-list instance; the value space of + its data type. + The following terms are defined in [RFC6241]: o configuration data o configuration datastore o datastore o state data @@ -644,75 +673,69 @@ not supposed to be complete, valid YANG modules. 4. YANG Overview This non-normative section is intended to give a high-level overview of YANG to first-time readers. 4.1. Functional Overview YANG is a language originally designed to model data for the NETCONF - protocol. A YANG module defines a hierarchy of data that can be used + protocol. A YANG module defines hierarchies of data that can be used for NETCONF-based operations, including configuration, state data, Remote Procedure Calls (RPCs), and notifications. This allows a complete description of all data sent between a NETCONF client and server. Although out of scope for this specification, YANG can also be used with other protocols than NETCONF. YANG models the hierarchical organization of data as a tree in which each node has a name, and either a value or a set of child nodes. YANG provides clear and concise descriptions of the nodes, as well as the interaction between those nodes. YANG structures data models into modules and submodules. A module - can import data from other external modules, and include data from - submodules. The hierarchy can be augmented, allowing one module to - add data nodes to the hierarchy defined in another module. This - augmentation can be conditional, with new nodes appearing only if - certain conditions are met. + can import definitions from other external modules, and include + definitions from submodules. The hierarchy can be augmented, + allowing one module to add data nodes to the hierarchy defined in + another module. This augmentation can be conditional, with new nodes + appearing only if certain conditions are met. YANG data models can describe constraints to be enforced on the data, restricting the presence or value of nodes based on the presence or value of other nodes in the hierarchy. These constraints are - enforceable by either the client or the server, and valid content - MUST abide by them. + enforceable by either the client or the server. YANG defines a set of built-in types, and has a type mechanism through which additional types may be defined. Derived types can restrict their base type's set of valid values using mechanisms like range or pattern restrictions that can be enforced by clients or servers. They can also define usage conventions for use of the derived type, such as a string-based type that contains a host name. YANG permits the definition of reusable groupings of nodes. The - instantiation of these groupings can refine or augment the nodes, - allowing it to tailor the nodes to its particular needs. Derived - types and groupings can be defined in one module and used in either - the same module or in another module that imports it. + usage of these groupings can refine or augment the nodes, allowing it + to tailor the nodes to its particular needs. Derived types and + groupings can be defined in one module and used in either the same + module or in another module that imports it. YANG data hierarchy constructs include defining lists where list entries are identified by keys that distinguish them from each other. Such lists may be defined as either sorted by user or automatically sorted by the system. For user-sorted lists, operations are defined for manipulating the order of the list entries. YANG modules can be translated into an equivalent XML syntax called YANG Independent Notation (YIN) (Section 13), allowing applications using XML parsers and Extensible Stylesheet Language Transformations (XSLT) scripts to operate on the models. The conversion from YANG to - YIN is lossless, so content in YIN can be round-tripped back into - YANG. - - YANG strikes a balance between high-level data modeling and low-level - bits-on-the-wire encoding. The reader of a YANG module can see the - high-level view of the data model while understanding how the data - will be encoded on-the-wire. + YIN is semantically lossless, so content in YIN can be round-tripped + back into YANG. YANG is an extensible language, allowing extension statements to be defined by standards bodies, vendors, and individuals. The statement syntax allows these extensions to coexist with standard YANG statements in a natural way, while extensions in a YANG module stand out sufficiently for the reader to notice them. YANG resists the tendency to solve all possible problems, limiting the problem space to allow expression of data models for network management protocols such as NETCONF, not arbitrary XML documents or @@ -726,47 +749,52 @@ translation from YANG to SMIv2. 4.2. Language Overview This section introduces some important constructs used in YANG that will aid in the understanding of the language specifics in later sections. 4.2.1. Modules and Submodules + YANG data models are defined in modules. A module contains a + collection of related definitions. + A module contains three types of statements: module-header statements, revision statements, and definition statements. The module header statements describe the module and give information about the module itself, the revision statements give information about the history of the module, and the definition statements are the body of the module where the data model is defined. A server may implement a number of modules, allowing multiple views of the same data, or multiple views of disjoint subsections of the server's data. Alternatively, the server may implement only one module that defines all available data. - A module may be divided into submodules, based on the needs of the - module owner. The external view remains that of a single module, - regardless of the presence or size of its submodules. + A module may have portions of its definitions separated into + submodules, based on the needs of the module designer. The external + view remains that of a single module, regardless of the presence or + size of its submodules. The "import" statement allows a module or submodule to reference - material defined in other modules. + definitions defined in other modules. - The "include" statement is used by a module to incorporate the - contents of its submodules into the module. + The "include" statement is used in a module to identify each + submodule that belongs to it. 4.2.2. Data Modeling Basics YANG defines four main types of data nodes for data modeling. In each of the following subsections, the examples show the YANG syntax - as well as a corresponding XML encoding. + as well as a corresponding XML encoding. The syntax of YANG + statements is defined in Section 6.3. 4.2.2.1. Leaf Nodes A leaf instance contains simple data like an integer or a string. It has exactly one value of a particular type and no child nodes. YANG Example: leaf host-name { type string; @@ -825,24 +853,24 @@ Good morning The "container" statement is covered in Section 7.5. 4.2.2.4. List Nodes A list defines a sequence of list entries. Each entry is like a - structure or a record instance, and is uniquely identified by the - values of its key leafs. A list can define multiple key leafs and - may contain any number of child nodes of any type (including leafs, - lists, containers etc.). + container, and is uniquely identified by the values of its key leafs, + if it has any key leafs defined. A list can define multiple key + leafs and may contain any number of child nodes of any type + (including leafs, lists, containers etc.). YANG Example: list user { key "name"; leaf name { type string; } leaf full-name { type string; @@ -921,78 +947,78 @@ type string; } leaf class { type string; } } } } } -4.2.3. State Data +4.2.3. Configuration and State Data YANG can model state data, as well as configuration data, based on the "config" statement. When a node is tagged with "config false", - its subhierarchy is flagged as state data. In NETCONF, state data is - reported using the operation, not the operation. + its subhierarchy is flagged as state data. If it is tagged with + "config true", its subhierarchy is flagged as configuration data. Parent containers, lists, and key leafs are reported also, giving the context for the state data. In this example, two leafs are defined for each interface, a - configured speed and an observed speed. The observed speed is not - configuration, so it can be returned with NETCONF operations, - but not with operations. The observed speed is not - configuration data, and it cannot be manipulated using . + configured speed and an observed speed. list interface { key "name"; + config true; leaf name { type string; } leaf speed { type enumeration { enum 10m; enum 100m; enum auto; } } leaf observed-speed { type uint32; config false; } } + The "config" statement is covered in Section 7.21.1. + 4.2.4. Built-In Types YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special - requirements from the management domain. The following table - summarizes the built-in types discussed in Section 9: + requirements of network management. The following table summarizes + the built-in types discussed in Section 9: +---------------------+-------------------------------------+ | Name | Description | +---------------------+-------------------------------------+ | binary | Any binary data | | bits | A set of bits or flags | | boolean | "true" or "false" | | decimal64 | 64-bit signed decimal number | | empty | A leaf that does not have any value | - | enumeration | Enumerated strings | + | enumeration | One of an enumerated set of strings | | identityref | A reference to an abstract identity | - | instance-identifier | A reference a data tree node | + | instance-identifier | A reference to a data tree node | | int8 | 8-bit signed integer | | int16 | 16-bit signed integer | | int32 | 32-bit signed integer | | int64 | 64-bit signed integer | | leafref | A reference to a leaf instance | - | string | Human-readable string | + | string | A character string | | uint8 | 8-bit unsigned integer | | uint16 | 16-bit unsigned integer | | uint32 | 32-bit unsigned integer | | uint64 | 64-bit unsigned integer | | union | Choice of member types | +---------------------+-------------------------------------+ The "type" statement is covered in Section 7.4. 4.2.5. Derived Types (typedef) @@ -1018,21 +1044,23 @@ XML Encoding Example: 20 The "typedef" statement is covered in Section 7.3. 4.2.6. Reusable Node Groups (grouping) Groups of nodes can be assembled into reusable collections using the "grouping" statement. A grouping defines a set of nodes that are - instantiated with the "uses" statement: + instantiated with the "uses" statement. + + YANG Example: grouping target { leaf address { type inet:ip-address; description "Target IP address"; } leaf port { type inet:port-number; description "Target port number"; } @@ -1084,28 +1112,30 @@ 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". - When a node from one case is created in the data tree, all nodes from - all other cases are implicitly deleted. The server handles the - enforcement of the constraint, preventing incompatibilities from - existing in the configuration. - The choice and case nodes appear only in the schema tree but not in the data tree. The additional levels of hierarchy are not needed - beyond the conceptual schema. + beyond the conceptual schema. The presence of a case is indicated by + the presence of one or more of the nodes within it. + + Since only one of the choice's cases can be valid at any time, when a + node from one case is created in the data tree, all nodes from all + other cases are implicitly deleted. The server handles the + enforcement of the constraint, preventing incompatibilities from + existing in the configuration. YANG Example: container food { choice snack { case sports-arena { leaf pretzel { type empty; } leaf beer { @@ -1137,38 +1167,42 @@ YANG allows a module to insert additional nodes into data models, including both the current module (and its submodules) or an external module. This is useful for example for vendors to add vendor- specific parameters to standard data models in an interoperable way. The "augment" statement defines the location in the data model hierarchy where new nodes are inserted, and the "when" statement defines the conditions when the new nodes are valid. + When a server implements a module containing an "augment" statement, + that implies that the server's implementation of the augmented module + contains the additional nodes. + YANG Example: augment /system/login/user { when "class != 'wheel'"; leaf uid { type uint16 { range "1000 .. 30000"; } } } This example defines a "uid" node that only is valid when the user's "class" is not "wheel". - If a module augments another module, the XML encoding of the data - will reflect the prefix of the augmenting module. For example, if - the above augmentation were in a module with prefix "other", the XML - would look like: + If a module augments another module, the XML elements that are added + to the encoding are in the namespace of the augmenting module. For + example, if the above augmentation were in a module with prefix + "other", the XML would look like: XML Encoding Example: alicew Alice N. Wonderland drop-out 1024 @@ -1176,21 +1210,21 @@ 4.2.9. Operation Definitions YANG allows the definition of operations. The operations' name, 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 container or list data node. Such operations are defined with the "action" statement. - YANG Example: + YANG Example for an operation at the top-level: rpc activate-software-image { input { leaf image-name { type string; } } output { leaf status { type string; @@ -1207,21 +1241,21 @@ The image example-fw-2.3 is being installed. - YANG Example: + YANG Example for an operation tied to a list data node: list interface { key "name"; leaf name { type string; } action ping { input { @@ -1295,90 +1329,96 @@ 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. + a single data model. A module can also augment an existing data + model with additional nodes. Submodules are partial modules that contribute definitions to a module. A module may include any number of submodules, but each submodule may belong to only one module. Developers of YANG modules and submodules 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. Within a server, all module names MUST be unique. - 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. + A module uses the "include" statement to list all its submodules. A + module, or submodule belonging to that module, can reference + definitions in the module and all submodules included by the module. - For backward compatibility with YANG version 1, a submodule is - allowed to 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 submodule MUST NOT - include different revisions of other submodules than the revisions - that its module includes. + A module or submodule uses the "import" statement to reference + external modules. Statements in the module or submodule can + reference definitions in the external module using the prefix + specified in the "import" statement. + + For backward compatibility with YANG version 1, a submodule MAY 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 submodule MUST NOT include + different revisions of other submodules than the revisions that its + module includes. 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: o For a module or submodule to reference definitions in an external module, the external module MUST be imported. o A module MUST include all its submodules. - o A module, or submodule belonging to that module, can reference + o A module, or submodule belonging to that module, MAY reference definitions in the module and all submodules included by the module. There MUST NOT be any circular chains of imports. For example, if module "a" imports module "b", "b" cannot import "a". When a definition in an external module is referenced, a locally - defined prefix MUST be used, followed by ":", and then the external - identifier. References to definitions in the local module MAY use - the prefix notation. Since built-in data types do not belong to any - module and have no prefix, references to built-in data types (e.g., - int32) cannot use the prefix notation. The syntax for a reference to - a definition is formally defined by the rule "identifier-ref" in - Section 14. + defined prefix MUST be used, followed by a colon (":"), and then the + external identifier. References to definitions in the local module + MAY use the prefix notation. Since built-in data types do not belong + to any module and have no prefix, references to built-in data types + (e.g., int32) cannot use the prefix notation. The syntax for a + reference to a definition is formally defined by the rule + "identifier-ref" in Section 14. 5.1.1. Import and Include by Revision Published modules evolve independently over time. In order to allow for this evolution, modules can be imported using specific revisions. - When a module is written, it can import the current revisions of - other modules, based on what is available at the time. As future - revisions of the imported modules are published, the importing module - is unaffected and its contents are unchanged. When the author of the - module is prepared to move to the most recently published revision of - an imported module, the module is republished with an updated - "import" statement. By republishing with the new revision, the - authors explicitly indicate their acceptance of any changes in the - imported module. + Initially, a module imports the revisions of other modules that are + current when the module is written. As future revisions of the + imported modules are published, the importing module is unaffected + and its contents are unchanged. When the author of the module is + prepared to move to the most recently published revision of an + imported module, the module is republished with an updated "import" + statement. By republishing with the new revision, the authors + explicitly indicate their acceptance of any changes in the imported + module. For submodules, the issue is related but simpler. A module or - submodule that includes submodules needs to specify the revision of - the included submodules. If a submodule changes, any module or - submodule that includes it needs to be updated. + submodule that includes submodules may specify the revision of the + included submodules. If a submodule changes, any module or submodule + that includes it by revision needs to be updated to reference the new + revision. For example, module "b" imports module "a". module a { yang-version 1.1; namespace "urn:example:a"; prefix "a"; revision 2008-01-01 { ... } grouping a { @@ -1400,37 +1440,38 @@ uses p:a; } } When the author of "a" publishes a new revision, the changes may not be acceptable to the author of "b". If the new revision is acceptable, the author of "b" can republish with an updated revision in the "import" statement. If a module is not imported with a specific revision, it is undefined - which exact revision is used. + which revision is used. 5.1.2. Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may - have more than one top-level node. Models that have multiple top- + have more than one top-level node. Each top-level data node in a + module defines a separate hierarchy. Models that have multiple top- level nodes are sometimes convenient, and are supported by YANG. 5.1.2.1. NETCONF XML Encoding NETCONF is capable of carrying any XML content as the payload in the and elements. The top-level nodes of YANG modules are encoded as child elements, in any order, within these elements. This encapsulation guarantees that the corresponding NETCONF messages are always well-formed XML documents. - For example: + For example, an instance of: module example-config { yang-version 1.1; namespace "urn:example:config"; prefix "co"; container system { ... } container routing { ... } } @@ -1450,33 +1491,42 @@ 5.2. File Layout YANG modules and submodules are typically stored in files, one module - or submodule per file. The name of the file SHOULD be of the form: + or submodule statement per file. The name of the file SHOULD be of + the form: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) + "module-or-submodule-name" is the name of the module or submodule, + and the optional "revision-date" is the latest revision of the module + or submodule, as defined by the "revision" statement (Section 7.1.9). + + The file extension ".yang" denotes that the contents of the file is + written with YANG syntax (Section 6), and ".yin" denotes that it is + written with YIN syntax (Section 13). + YANG parsers can find imported modules and included submodules via this convention. 5.3. XML Namespaces - All YANG definitions are specified within a module that is bound to a - particular XML namespace [XML-NAMES], which is a globally unique URI - [RFC3986]. A NETCONF client or server uses the namespace during XML - encoding of data. + All YANG definitions are specified within a module. Each module is + bound to a distinct XML namespace [XML-NAMES], which is a globally + unique URI [RFC3986]. A NETCONF client or server uses the namespace + during XML encoding of data. XML namespaces for modules published in RFC streams [RFC4844] MUST be assigned by IANA, see section 14 in [RFC6020]. XML namespaces for private modules are assigned by the organization owning the module without a central registry. Namespace URIs MUST be chosen so they cannot collide with standard or other enterprise namespaces, for example by using the enterprise or organization name in the namespace. @@ -1493,62 +1543,62 @@ Grouping, type, and identity names are resolved in the context in which they are defined, rather than the context in which they are used. Users of groupings, typedefs, and identities are not required to import modules or include submodules to satisfy all references made by the original definition. This behaves like static scoping in a conventional programming language. For example, if a module defines a grouping in which a type is referenced, when the grouping is used in a second module, the type is resolved in the context of the original module, not the second - module. There is no worry over conflicts if both modules define the - type, since there is no ambiguity. + module. There is no ambiguity if both modules define the type, since + there is no ambiguity. 5.5. Nested Typedefs and Groupings Typedefs and groupings may appear nested under many YANG statements, - allowing these to be lexically scoped by the hierarchy under which - they appear. This allows types and groupings to be defined near - where they are used, rather than placing them at the top level of the - hierarchy. The close proximity increases readability. + allowing these to be lexically scoped by the statement hierarchy + under which they appear. This allows types and groupings to be + defined near where they are used, rather than placing them at the top + level of the hierarchy. The close proximity increases readability. Scoping also allows types to be defined without concern for naming conflicts between types in different submodules. Type names can be specified without adding leading strings designed to prevent name collisions within large modules. Finally, scoping allows the module author to keep types and groupings private to their module or submodule, preventing their reuse. Since only top-level types and groupings (i.e., those appearing as substatements to a module or submodule statement) can be used outside the module or submodule, the developer has more control over what pieces of their module are presented to the outside world, supporting the need to hide internal information and maintaining a boundary between what is shared with the outside world and what is kept private. Scoped definitions MUST NOT shadow definitions at a higher scope. A - type or grouping cannot be defined if a higher level in the schema + type or grouping cannot be defined if a higher level in the statement hierarchy has a definition with a matching identifier. A reference to an unprefixed type or grouping, or one which uses the prefix of the current module, is resolved by locating the matching "typedef" or "grouping" statement among the immediate substatements of each ancestor statement. 5.6. Conformance - Conformance is a measure of how accurately a server follows the - model. Generally speaking, servers are responsible for implementing - the model faithfully, allowing applications to treat servers which - implement the model identically. Deviations from the model can - reduce the utility of the model and increase fragility of + Conformance to a model is a measure of how accurately a server + follows the model. Generally speaking, servers are responsible for + implementing the model faithfully, allowing applications to treat + servers which implement the model identically. Deviations from the + model can reduce the utility of the model and increase fragility of applications that use it. YANG modelers have three mechanisms for conformance: o the basic behavior of the model o optional features that are part of the model o deviations from the model @@ -1619,28 +1669,28 @@ module. Further details are available in Section 7.20.3. 5.6.4. Announcing Conformance Information in NETCONF This document defines the following mechanism for announcing conformance information. Other mechanisms may be defined by future specifications. - A NETCONF server announces the modules it implements (see + A NETCONF server MUST announce the modules it implements (see Section 5.6.5) by implementing the YANG module "ietf-yang-library" defined in [I-D.ietf-netconf-yang-library], and listing all implemented modules in the "/modules-state/module" list. - The server also advertises the following capability in the - message (line-breaks and whitespaces are used for formatting reasons - only): + The server also MUST advertise 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? revision=&module-set-id= The parameter "revision" has the same value as the revision date of the "ietf-yang-library" module implemented by the server. This parameter MUST be present. The parameter "module-set-id" has the same value as the leaf "/modules-state/module-set-id" from "ietf-yang-library". This @@ -1670,22 +1720,22 @@ "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set the leaf "conformance-type" to "import" for this module. If a server lists a module C in the "/modules-state/module" list from "ietf-yang-library", and there are other modules Ms listed that import C without specifying the revision date of module C, the server MUST use the definitions from the most recent revision of C listed for modules Ms. The reason for these rules is that clients need to be able to know - the exact data model structure and types of all leafs and leaf-lists - implemented in a server. + the specific data model structure and types of all leafs and leaf- + lists implemented in a server. For example, with these modules: module a { yang-version 1.1; namespace "urn:example:a"; prefix "a"; import b { revision-date 2015-01-01; @@ -1708,34 +1758,62 @@ type c:bar; } } } module b { yang-version 1.1; namespace "urn:example:b"; prefix "b"; + revision 2015-01-01; + + typedef myenum { + type enumeration { + enum zero; + } + } + + container x { + } + } + + module b { + yang-version 1.1; + namespace "urn:example:b"; + prefix "b"; + revision 2015-04-04; revision 2015-01-01; typedef myenum { type enumeration { enum zero; // added in 2015-01-01 enum one; // added in 2015-04-04 } } container x { // added in 2015-01-01 container y; // added in 2015-04-04 } } + module c { + yang-version 1.1; + namespace "urn:example:c"; + prefix "c"; + + revision 2015-02-02; + + typedef bar { + ... + } + } module c { yang-version 1.1; namespace "urn:example:c"; prefix "c"; revision 2015-03-03; revision 2015-02-02; typedef bar { @@ -1745,22 +1823,22 @@ A server that implements revision "2015-01-01" of module "a" and supports feature "foo" can implement revision "2015-01-01" or "2015-04-04" of module "b". Since "b" was imported by revision, the type of leaf "/b:x/a:y" is the same regardless of which revision of "b" the server implements. A server that implements module "a", but does not support feature "foo" does not have to implement module "b". - A server that implements revision "2015-01-01" of module "a" must - pick a revision of module "c", and list it in the "/modules-state/ + A server that implements revision "2015-01-01" of module "a" picks + any revision of module "c", and list it in the "/modules-state/ module" list from "ietf-yang-library". The following XML encoding example shows valid data for the "/modules-state/module" list for a server that implements module "a": ee1ecb017370cafd a @@ -1793,98 +1871,113 @@ changes are allowed is out of scope for this specification. 6. YANG Syntax The YANG syntax is similar to that of SMIng [RFC3780] and programming languages like C and C++. This C-like syntax was chosen specifically for its readability, since YANG values the time and effort of the readers of models above those of modules writers and YANG tool-chain developers. This section introduces the YANG syntax. - YANG modules use the UTF-8 [RFC3629] character encoding. - Legal characters in YANG modules are the Unicode and ISO/IEC 10646 [ISO.10646] characters, including tab, carriage return, and line feed but excluding the other C0 control characters, the surrogate blocks, and the noncharacters. The character syntax is formally defined by the rule "yang-char" in Section 14. + YANG modules and submodules are stored in files using the UTF-8 + [RFC3629] character encoding. + + Lines in a YANG module end with a carriage return-line feed + combination or with a line feed alone. A carriage return that is not + followed by a line feed may only appear inside a quoted string + (Section 6.1.3). Note that carriage returns and line feeds that + appear inside quoted strings become part of the value of the string + without modification; the value of a multi-line quoted string + contains the same form of line ends as those lines of the YANG + module. + 6.1. Lexical Tokenization YANG modules are parsed as a series of tokens. This section details the rules for recognizing tokens from an input stream. YANG tokenization rules are both simple and powerful. The simplicity is driven by a need to keep the parsers easy to implement, while the power is driven by the fact that modelers need to express their models in readable formats. 6.1.1. Comments Comments are C++ style. A single line comment starts with "//" and - ends at the end of the line. A block comment is enclosed within "/*" - and "*/". + ends at the end of the line. A block comment starts with "/*" and + ends with the nearest following "*/". Note that inside a quoted string (Section 6.1.3), these character pairs are never interpreted as the start or end of a comment. 6.1.2. Tokens A token in YANG is either a keyword, a string, a semicolon (";"), or braces ("{" or "}"). A string can be quoted or unquoted. A keyword is either one of the YANG keywords defined in this document, or a - prefix identifier, followed by ":", followed by a language extension - keyword. Keywords are case sensitive. See Section 6.2 for a formal - definition of identifiers. + prefix identifier, followed by a colon (":"), followed by a language + extension keyword. Keywords are case sensitive. See Section 6.2 for + a formal definition of identifiers. 6.1.3. Quoting - If a string contains any space, tab, or newline characters, a single - or double quote character, a semicolon (";"), braces ("{" or "}"), or - comment sequences ("//", "/*", or "*/"), then it MUST be enclosed - within double or single quotes. + An unquoted string is any sequence of characters that does not + contain any space, tab, carriage return, or line feed characters, a + single or double quote character, a semicolon (";"), braces ("{" or + "}"), or comment sequences ("//", "/*", or "*/"). + + Note that any keyword can legally appear as an unquoted string. Within an unquoted string, every character is preserved. Note that this means that the backslash character does not have any special meaning in an unquoted string. If a double-quoted string contains a line break followed by space or tab characters that are used to indent the text according to the layout in the YANG file, this leading whitespace is stripped from the - string, up to and including the column of the double quote character, - or to the first non-whitespace character, whichever occurs first. In - this process, a tab character is treated as 8 space characters. + string, up to and including the column of the starting double quote + character, or to the first non-whitespace character, whichever occurs + first. Any tab character in a succeeding line that must be examined + for stripping is first converted into 8 space characters. If a double-quoted string contains space or tab characters before a line break, this trailing whitespace is stripped from the string. A single-quoted string (enclosed within ' ') preserves each character within the quotes. A single quote character cannot occur in a single-quoted string, even when preceded by a backslash. Within a double-quoted string (enclosed within " "), a backslash - character introduces a special character, which depends on the - character that immediately follows the backslash: + character introduces a representation of a special character, which + depends on the character that immediately follows the backslash: \n new line \t a tab character \" a double quote \\ a single backslash - It is an error if any other character follows the backslash - character. + The backslash MUST NOT be followed by any other character. If a quoted string is followed by a plus character ("+"), followed by another quoted string, the two strings are concatenated into one string, allowing multiple concatenations to build one string. - Whitespace trimming is done before substitution of backslash-escaped - characters in double-quoted strings. Concatenation is performed as - the last step. + Whitespace, line breaks, and comments are allowed between the quoted + strings and the plus character. + + In double-quoted strings, whitespace trimming is done before + substitution of backslash-escaped characters. Concatenation is + performed as the last step. 6.1.3.1. Quoting Examples The following strings are equivalent: hello "hello" 'hello' "hel" + "lo" 'hel' + "lo" @@ -1978,21 +2071,21 @@ 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.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. + extension's keyword MUST be qualified with the prefix of this module. The processing of extensions depends on whether support for those extensions is claimed for a given YANG parser or the tool set in which it is embedded. An unsupported extension, appearing in a YANG module as an unknown-statement (see Section 14) MAY be ignored in its entirety. Any supported extension MUST be processed in accordance with the specification governing that extension. Care must be taken when defining extensions so that modules that use the extensions are meaningful also for applications that do not @@ -2238,22 +2331,22 @@ // possibly other top-level nodes here 6.5. Schema Node Identifier A schema node identifier is a string that identifies a node in the schema tree. It has two forms, "absolute" and "descendant", defined by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" in Section 14, respectively. A schema node identifier consists of a path of identifiers, separated by slashes ("/"). In an absolute schema node identifier, the first identifier after the leading slash - is any top-level schema node in the local module or in all imported - modules. + is any top-level schema node in the local module or in an imported + module. References to identifiers defined in external modules MUST be qualified with appropriate prefixes, and references to identifiers defined in the current module and its submodules MAY use a prefix. For example, to identify the child node "b" of top-level node "a", the string "/a/b" can be used. 7. YANG Statements @@ -2267,21 +2360,21 @@ description "some text" { ex:documentation-flag 5; } 7.1. The module Statement The "module" statement defines the module's name, and groups all statements that belong to the module together. The "module" statement's argument is the name of the module, followed by a block of substatements that hold detailed module information. The module - name follows the rules for identifiers in Section 6.2. + name is an identifier (see Section 6.2). Names of modules published in RFC streams [RFC4844] MUST be assigned by IANA, see section 14 in [RFC6020]. Private module names are assigned by the organization owning the module without a central registry. See Section 5.1 for recommendations on how to name modules. A module typically has the following layout: @@ -2339,22 +2432,22 @@ | rpc | 7.14 | 0..n | | typedef | 7.3 | 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. + is a string. It MUST contain the value "1.1" for YANG modules + defined based on this specification. A module or submodule that doesn't contain the "yang-version" statement, or one that contains the value "1", is developed for YANG version 1, defined in [RFC6020]. 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. @@ -2369,41 +2462,42 @@ 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 - module, e.g., "if:ifName". A prefix follows the same rules as an + prefix string MAY be used with the module to refer to definitions + contained in the module, e.g., "if:ifName". A prefix is an identifier (see Section 6.2). When used inside the "module" statement, the "prefix" statement defines the prefix suggested to be used when this module is imported. + To improve readability of the NETCONF XML, a NETCONF client or server that generates XML or XPath that use prefixes SHOULD use the prefix - defined by the module, unless there is a conflict. + defined by the module as the XML namespace prefix, unless there is a + conflict. When used inside the "import" statement, the "prefix" statement defines the prefix to be used when accessing definitions inside the imported module. When a reference to an identifier from the imported - module is used, the prefix string for the imported module is used in - combination with a colon (":") and the identifier, e.g., - "if:ifIndex". To improve readability of YANG modules, the prefix - defined by a module SHOULD be used when the module is imported, - unless there is a conflict. If there is a conflict, i.e., two - different modules that both have defined the same prefix are - imported, at least one of them MUST be imported with a different - prefix. + module is used, the prefix string for the imported module followed by + a colon (":") and the identifier is used, e.g., "if:ifIndex". To + improve readability of YANG modules, the prefix defined by a module + SHOULD be used when the module is imported, unless there is a + conflict. If there is a conflict, i.e., two different modules that + both have defined the same prefix are imported, at least one of them + MUST be imported with a different prefix. All prefixes, including the prefix for the module itself MUST be unique within the module or submodule. 7.1.5. The import Statement The "import" statement makes definitions from one module available inside another module or submodule. The argument is the name of the module to import, and the statement is followed by a block of substatements that holds detailed import information. When a module @@ -2441,37 +2535,37 @@ | prefix | 7.1.4 | 1 | | revision-date | 7.1.5.1 | 0..1 | | description | 7.21.3 | 0..1 | | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ The import's Substatements 7.1.5.1. The import's revision-date Statement - The import's "revision-date" statement is used to specify the exact - version of the module to import. + The import's "revision-date" statement is used to specify the version + of the module to import. 7.1.6. The include Statement The "include" statement is used to make content from a submodule available to that submodule's parent module. The argument is an 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). When a module includes a submodule, it incorporates the contents of the submodule into the node hierarchy of the module. 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. + but this is not necessary in YANG version 1.1 (see Section 5.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. +---------------+---------+-------------+ @@ -2560,22 +2654,21 @@ While the primary unit in YANG is a module, a YANG module can itself be constructed out of several submodules. Submodules allow a module designer to split a complex model into several pieces where all the submodules contribute to a single namespace, which is defined by the module that includes the submodules. The "submodule" statement defines the submodule's name, and groups all statements that belong to the submodule together. The "submodule" statement's argument is the name of the submodule, followed by a block of substatements that hold detailed submodule - information. The submodule name follows the rules for identifiers in - Section 6.2. + information. The submodule name is an identifier (see Section 6.2). Names of submodules published in RFC streams [RFC4844] MUST be assigned by IANA, see section 14 in [RFC6020]. Private submodule names are assigned by the organization owning the submodule without a central registry. See Section 5.1 for recommendations on how to name submodules. A submodule typically has the following layout: @@ -2795,33 +2888,36 @@ nodes in the data tree. The child nodes are defined in the container's substatements. 7.5.1. Containers with Presence YANG supports two styles of containers, those that exist only for organizing the hierarchy of data nodes, and those whose presence in the data tree has an explicit meaning. In the first style, the container has no meaning of its own, existing - only to contain child nodes. This is the default style. + only to contain child nodes. In particular, the presence of the + container node with no child nodes is semantically equivalent to the + absence of the container node. YANG calls this style a "non-presence + container". This is the default style. For example, the set of scrambling options for Synchronous Optical Network (SONET) interfaces may be placed inside a "scrambling" container to enhance the organization of the configuration hierarchy, and to keep these nodes together. The "scrambling" node itself has no meaning, so removing the node when it becomes empty relieves the user from performing this task. In the second style, the presence of the container itself carries some meaning, representing a single bit of data. - In configuration data, the container acts as both a configuration + For configuration data, the container acts as both a configuration knob and a means of organizing related configuration. These containers are explicitly created and deleted. YANG calls this style a "presence container" and it is indicated using the "presence" statement, which takes as its argument a text string indicating what the presence of the node means. For example, an "ssh" container may turn on the ability to log into the server using ssh, but can also contain any ssh-related configuration knobs, such as connection rates or retry limits. @@ -2859,21 +2955,22 @@ 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 node in the accessible tree (see Section 6.4.1). - All such constraints MUST evaluate to true for the data to be valid. + 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 using the standard XPath rules. @@ -2893,46 +2990,45 @@ +---------------+---------+-------------+ | 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.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 + an argument. If the constraint evaluates to "false", the string is passed as in the in NETCONF. 7.5.4.2. The error-app-tag Statement The "error-app-tag" statement, which is optional, takes a string as - an argument. If the constraint evaluates to false, the string is + an argument. If the constraint evaluates to "false", the string is passed as in the in NETCONF. 7.5.4.3. Usage Example of must and error-message container interface { leaf ifType { type enumeration { enum ethernet; enum atm; } } leaf ifMTU { type uint32; } - must "ifType != 'ethernet' or " + - "(ifType = 'ethernet' and ifMTU = 1500)" { + must 'ifType != "ethernet" or ifMTU = 1500' { error-message "An ethernet MTU must be 1500"; } - must "ifType != 'atm' or " + - "(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { + must 'ifType != "atm" or' + + ' (ifMTU <= 17966 and ifMTU >= 64)' { error-message "An atm MTU must be 64 .. 17966"; } } 7.5.5. The presence Statement The "presence" statement assigns a meaning to the presence of a container in the data tree. It takes as an argument a string that contains a textual description of what the node's presence means. @@ -2954,20 +3050,24 @@ 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 or action input or output parameters, these subelements are encoded in the same order as they are defined within the "container" statement. Otherwise, the subelements are encoded in any order. + Any whitespace between the subelements to the container is + insignificant, i.e., an implementation MAY insert whitespace + characters between subelements. + If a non-presence container does not have any child nodes, the container may or may not be present in the XML encoding. 7.5.8. NETCONF Operations Containers can be created, deleted, replaced, and modified through , by using the "operation" attribute (see [RFC6241], Section 7.2) in the container's XML element. If a container does not have a "presence" statement and the last @@ -3047,21 +3147,21 @@ A leaf node exists in zero or one instances in the data tree. The "leaf" statement is used to define a scalar variable of a particular built-in or derived type. 7.6.1. The leaf's default value The default value of a leaf is the value that the server uses if the leaf does not exist in the data tree. The usage of the default value depends on the leaf's closest ancestor node in the schema tree that - is not a non-presence-container (see Section 7.5.1): + is not a non-presence container (see Section 7.5.1): o If no such ancestor exists in the schema tree, the default value MUST be used. o Otherwise, if this ancestor is a case node, the default value MUST be used if any node from the case exists in the data tree, or if the case node is the choice's default case, and no nodes from any other case exist in the data tree. o Otherwise, the default value MUST be used if the ancestor node @@ -3110,42 +3210,42 @@ 7.6.4. The leaf's default Statement The "default" statement, which is optional, takes as an argument a string that contains a default value for the leaf. The value of the "default" statement MUST be valid according to the type specified in the leaf's "type" statement. The "default" statement MUST NOT be present on nodes where - "mandatory" is true. + "mandatory" is "true". - The default value MUST NOT be marked with an "if-feature" statement. - For example, the following is illegal: + The definition of the default value MUST NOT be marked with an + "if-feature" statement. For example, the following is illegal: leaf color { type enumeration { enum blue { if-feature blue; } ... } default blue; // illegal - enum value is conditional } 7.6.5. The leaf's mandatory Statement The "mandatory" statement, which is optional, takes as an argument the string "true" or "false", and puts a constraint on valid data. If not specified, the default is "false". If "mandatory" is "true", the behavior of the constraint depends on the type of the leaf's closest ancestor node in the schema tree that - is not a non-presence-container (see Section 7.5.1): + is not a non-presence container (see Section 7.5.1): o If no such ancestor exists in the schema tree, the leaf MUST exist. o Otherwise, if this ancestor is a case node, the leaf MUST exist if any node from the case exists in the data tree. o Otherwise, the leaf MUST exist if the ancestor node exists in the data tree. @@ -3218,23 +3318,24 @@ 7.7. The leaf-list Statement Where the "leaf" statement is used to define a simple scalar variable of a particular type, the "leaf-list" statement is used to define an array of a particular type. The "leaf-list" statement takes one argument, which is an identifier, followed by a block of substatements that holds detailed leaf-list information. In configuration data, the values in a leaf-list MUST be unique. - The default values MUST NOT be marked with an "if-feature" statement. + The definitions of the default values MUST NOT be marked with an + "if-feature" statement. - Conceptually, the values in the data tree are always in the canonical + Conceptually, the values in the data tree MUST be in the canonical form (see Section 9.1). 7.7.1. Ordering YANG supports two styles for ordering the entries within lists and leaf-lists. In many lists, the order of list entries does not impact the implementation of the list's configuration, and the server is free to sort the list entries in any reasonable order. The "description" string for the list may suggest an order to the server implementor. YANG calls this style of list "system ordered" and they @@ -3263,21 +3364,21 @@ positioned as the first or last entry in the list, or positioned before or after another specific entry. The "ordered-by" statement is covered in Section 7.7.7. 7.7.2. The leaf-list's default values The default values of a leaf-list are the values that the server uses if the leaf-list does not exist in the data tree. The usage of the default values depends on the leaf-list's closest ancestor node in - the schema tree that is not a non-presence-container (see + the schema tree that is not a non-presence container (see Section 7.5.1): o If no such ancestor exists in the schema tree, the default values MUST be used. o Otherwise, if this ancestor is a case node, the default values MUST be used if any node from the case exists in the data tree, or if the case node is the choice's default case, and no nodes from any other case exist in the data tree. @@ -3288,30 +3389,29 @@ Note that if the leaf-list or any of its ancestors has a "when" condition or "if-feature" expression that evaluates to "false", then the default values are not in use. When the default values are in use, the server MUST operationally behave as if the leaf-list was present in the data tree with the default values as its values. If a leaf-list has one or more "default" statement, the leaf-list's - default value are the values of the "default" statements, and if the + default values are the values of the "default" statements, and if the leaf-list is user-ordered, the default values are used in the order of the "default" statements. Otherwise, if the leaf-list's type has 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. + list's default value is one instance of 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.21.1 | 0..1 | | default | 7.7.4 | 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 | @@ -3337,24 +3437,27 @@ 7.7.5. The min-elements Statement The "min-elements" statement, which is optional, takes as an argument a non-negative integer that puts a constraint on valid list entries. A valid leaf-list or list MUST have at least min-elements entries. If no "min-elements" statement is present, it defaults to zero. The behavior of the constraint depends on the type of the leaf-list's or list's closest ancestor node in the schema tree that is not a non- - presence-container (see Section 7.5.1): + presence container (see Section 7.5.1): - o If this ancestor is a case node, the constraint is enforced if any - other node from the case exists. + o If no such ancestor exists in the schema tree, the constraint is + enforced. + + o Otherwise, if this ancestor is a case node, the constraint is + enforced if any other node from the case exists. o Otherwise, it is enforced if the ancestor node exists. The constraint is further enforced according to the rules in Section 8. 7.7.6. The max-elements Statement The "max-elements" statement, which is optional, takes as an argument a positive integer or the string "unbounded", which puts a constraint @@ -3374,51 +3477,52 @@ is one of the strings "system" or "user". If not present, order defaults to "system". This statement is ignored if the list represents state data, RPC output parameters, or notification content. See Section 7.7.1 for additional information. 7.7.7.1. ordered-by system - The entries in the list are sorted according to an order determined + The entries in the list are ordered according to an order determined by the system. The "description" string for the list may suggest an order to the server implementor. If not, an implementation is free - to sort the entries in the most appropriate order. An implementation - SHOULD use the same order for the same data, regardless of how the - data were created. Using a deterministic order will make comparisons - possible using simple tools like "diff". + to order the entries in any order. An implementation SHOULD use the + same order for the same data, regardless of how the data were + created. Using a deterministic order will make comparisons possible + using simple tools like "diff". This is the default order. 7.7.7.2. ordered-by user - The entries in the list are sorted according to an order defined by - the user. This order is controlled by using special XML attributes - in the request. See Section 7.7.9 for details. + The entries in the list are ordered according to an order defined by + the user. In NETCONF, this order is controlled by using special XML + attributes in the request. See Section 7.7.9 for + details. 7.7.8. XML Encoding Rules A leaf-list node is encoded as a series of XML elements. Each element's local name is the leaf-list's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of each leaf-list entry is encoded to XML according to the type, and sent as character data in the element. The XML elements representing leaf-list entries MUST appear in the order specified by the user if the leaf-list is "ordered-by user"; otherwise, the order is implementation-dependent. The XML elements - representing leaf-list entries MAY be interleaved with other sibling - elements, unless the leaf-list defines RPC or action input or output - parameters. + representing leaf-list entries MAY be interleaved with elements for + siblings of the leaf-list, unless the leaf-list defines RPC or action + input or output parameters. See Section 7.7.10 for an example. 7.7.9. NETCONF Operations Leaf-list entries can be created and deleted, but not modified, through , by using the "operation" attribute in the leaf-list entry's XML element. In an "ordered-by user" leaf-list, the attributes "insert" and @@ -3565,25 +3670,25 @@ | typedef | 7.3 | 0..n | | unique | 7.8.3 | 0..n | | 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 - list, or in groupings used in the list. + string that specifies a space-separated list of one or more 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 list, or in groupings used in the list. The combined values of all the leafs specified in the key are used to uniquely identify a list entry. All key leafs MUST be given values when a list entry is created. Thus, any default values in the key leafs or their types are ignored. It also implies that any mandatory statement in the key leafs are ignored. A leaf that is part of the key can be of any built-in or derived type. @@ -3600,22 +3705,22 @@ separated list of schema node identifiers, which MUST be given in the descendant form (see the rule "descendant-schema-nodeid" in Section 14). Each such schema node identifier MUST refer to a leaf. If one of the referenced leafs represents configuration data, then all of the referenced leafs MUST represent configuration data. The "unique" constraint specifies that the combined values of all the leaf instances specified in the argument string, including leafs with default values, MUST be unique within all list entry instances in - which all referenced leafs exist. The constraint is enforced - according to the rules in Section 8. + which all referenced leafs exist or have default values. The + constraint is enforced according to the rules in Section 8. The unique string syntax is formally defined by the rule "unique-arg" in Section 14. 7.8.3.1. Usage Example With the following list: list server { key "name"; @@ -3669,36 +3774,42 @@ Within a list, the "container", "leaf", "list", "leaf-list", "uses", "choice", "anydata", and "anyxml" statements can be used to define child nodes to the list. 7.8.5. XML Encoding 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). + There is no XML element surrounding the list as a whole. The list's key nodes are encoded as subelements to the list's identifier element, in the same order as they are defined within the "key" statement. The rest of the list's child nodes are encoded as subelements to the list element, after the keys. If the list defines RPC or action input or output parameters, the subelements are encoded in the same order as they are defined within the "list" statement. Otherwise, the subelements are encoded in any order. + Any whitespace between the subelements to the list entry is + insignificant, i.e., an implementation MAY insert whitespace + characters between subelements. + The XML elements representing list entries MUST appear in the order specified by the user if the list is "ordered-by user", otherwise the order is implementation-dependent. The XML elements representing - list entries MAY be interleaved with other sibling elements, unless - the list defines RPC or action input or output parameters. + list entries MAY be interleaved with elements for siblings of the + list, unless the list defines RPC or action input or output + parameters. 7.8.6. NETCONF Operations List entries can be created, deleted, replaced, and modified through , by using the "operation" attribute in the list's XML element. In each case, the values of all keys are used to uniquely identify a list entry. If all keys are not specified for a list entry, a "missing-element" error is returned. In an "ordered-by user" list, the attributes "insert" and "key" in @@ -3882,26 +3993,27 @@ rubble 7.9. The choice Statement The "choice" statement defines a set of alternatives, only one of - which may exist at any one time. The argument is an identifier, - followed by a block of substatements that holds detailed choice - information. The identifier is used to identify the choice node in - the schema tree. A choice node does not exist in the data tree. + which may be present in any one data tree. The argument is an + identifier, followed by a block of substatements that holds detailed + choice information. The identifier is used to identify the choice + node in the schema tree. A choice node does not exist in the data + tree. - A choice consists of a number of branches, defined with the "case" + A choice consists of a number of branches, each defined with a "case" 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. Since only one of the choice's cases can be valid at any time in the data tree, the creation of a node from one case implicitly deletes all nodes from all other cases. If a request creates a node from a case, the server will delete any existing nodes that are defined in other cases inside the choice. @@ -3948,23 +4060,23 @@ } case b { container ethernet { ...} } } As a shorthand, the "case" statement can be omitted if the branch contains a single "anydata", "anyxml", "choice", "container", "leaf", "list", or "leaf-list" statement. In this case, the case node still exists in the schema tree, and its identifier is the same as the - identifier in the branch statement. Schema node identifiers - (Section 6.5) MUST always explicitly include case node identifiers. - The following example: + identifier of the child node. Schema node identifiers (Section 6.5) + MUST always explicitly include case node identifiers. The following + example: choice interface-type { container ethernet { ... } } is equivalent to: choice interface-type { case ethernet { container ethernet { ... } @@ -3990,25 +4102,25 @@ | 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 argument is the identifier of the default "case" statement. If + the "default" statement is missing, there is no default case. The "default" statement MUST NOT be present on choices where - "mandatory" is true. + "mandatory" is "true". The default case is only important when considering the default statements of nodes under the cases (i.e., default values of leafs and leaf-lists, and default cases of nested choices). The default values and nested default cases under the default case are used if none of the nodes under any of the cases are present. There MUST NOT be any mandatory nodes (Section 3) directly under the default case. @@ -4054,25 +4166,28 @@ 7.9.4. The choice's mandatory Statement The "mandatory" statement, which is optional, takes as an argument the string "true" or "false", and puts a constraint on valid data. If "mandatory" is "true", at least one node from exactly one of the choice's case branches MUST exist. If not specified, the default is "false". The behavior of the constraint depends on the type of the choice's - closest ancestor node in the schema tree that is not a non-presence- + closest ancestor node in the schema tree that is not a non-presence container (see Section 7.5.1): - o If this ancestor is a case node, the constraint is enforced if any - other node from the case exists. + o If no such ancestor exists in the schema tree, the constraint is + enforced. + + o Otherwise, if this ancestor is a case node, the constraint is + enforced if any other node from the case exists. o Otherwise, it is enforced if the ancestor node exists. The constraint is further enforced according to the rules in Section 8. 7.9.5. XML Encoding Rules The choice and case nodes are not visible in XML. @@ -4132,33 +4247,32 @@ substatements that holds detailed anydata information. The "anydata" statement is used to represent an unknown set of nodes that can be modelled with YANG, except anyxml, but for which the data model is not known at module design time. It is possible, though not required, for the data model for "anydata" content to become known through protocol signalling or other means that are outside the scope of this document. An example of where anydata can be useful is a list of received - notifications, where the exact notifications are not known at design - time. + notifications, where the specific notifications are not known at + 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. An implementation may or may not know the data model used to model a specific instance of an anydata node. - Since the use of anydata limits the manipulation of the content, it - is RECOMMENDED that the "anydata" statement not be used to define - configuration data. + Since the use of anydata limits the manipulation of the content, the + "anydata" statement SHOULD NOT be used to define 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 | @@ -4237,30 +4351,29 @@ 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 in NETCONF. 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 define - configuration data. + Since the use of anyxml limits the manipulation of the content, the + "anyxml" statement SHOULD NOT be used to define configuration data. 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 data model is not known at design time. In these - situations, it is RECOMMENDED to use anydata (Section 7.10) instead - of anyxml. + but the specific YANG data model is not known at design time. In + these situations, it is RECOMMENDED to use anydata (Section 7.10) + instead of anyxml. 7.11.1. The anyxml'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 | @@ -4578,25 +4689,24 @@ If a leaf-list in the input tree has one or more default values, the server MUST use these values in the same cases as described in Section 7.7.2. In these cases, the server MUST operationally behave as if the leaf-list was present in the RPC invocation with the default values as its values. Since the input tree is not part of any datastore, all "config" statements for nodes in the input tree are ignored. - If any node has a "when" statement that would evaluate to false, then - this node MUST NOT be present in the input tree. + If any node has a "when" statement that would evaluate to "false", + then this node MUST NOT be present in the input tree. 7.14.2.1. The input's Substatements - +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | @@ -4623,25 +4733,24 @@ If a leaf-list in the output tree has one or more default values, the 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 RPC reply with the default values as its values. Since the output tree is not part of any datastore, all "config" statements for nodes in the output tree are ignored. - If any node has a "when" statement that would evaluate to false, then - this node MUST NOT be present in the output tree. + If any node has a "when" statement that would evaluate to "false", + then this node MUST NOT be present in the output tree. 7.14.3.1. The output's Substatements - +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | @@ -4753,22 +4862,22 @@ 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 datastore. It MUST contain all containers and list nodes in the direct path from the top level down to the list or container containing the action. 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 action. Within this element the + be included. The innermost container or list contains an XML element + that carries the name of the defined action. Within this element the input parameters are encoded as child XML elements, in the same order as they are defined within the "input" statement. Only one action can be invoked in one . If more than one action is 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, @@ -4908,22 +5017,22 @@ 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] contains an hierarchy of nodes that identifies the node in the datastore. 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. + innermost container or list contains an XML element that carries the + name of the defined notification. The notification's child nodes are encoded as subelements to the notification node's XML element, in any order. 7.16.3. Usage Example The following example defines a notification at the top-level of a module: module example-event { @@ -4990,25 +5099,25 @@ 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 + The "augment" statement allows a module or submodule to add to a + schema tree defined in an external module, or in 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. The argument string is a schema node identifier (see Section 6.5). If the "augment" statement is on the top level in a module or submodule, the absolute form (defined by the rule "absolute-schema-nodeid" in Section 14) of a schema node identifier MUST be used. If the "augment" statement is a substatement to the "uses" statement, the descendant form (defined by the rule @@ -5022,25 +5131,25 @@ If the target node is a container or list node, the "action" and "notification" statements can be used within the "augment" statement. If the target node is a choice node, the "case" statement, or a case shorthand statement (see Section 7.9.2) can be used within the "augment" statement. The "augment" statement MUST NOT add multiple nodes with the same name from the same module to the target node. - If the augmentation adds mandatory configuration nodes (see - Section 3) to a target node in another module, the augmentation MUST - be conditional with a "when" statement. Care must be taken when - defining the "when" expression, so that clients that do not know - about the augmenting module do not break. + If the augmentation adds mandatory nodes (see Section 3) that + represent configuration to a target node in another module, the + augmentation MUST be conditional with a "when" statement. Care must + be taken when defining the "when" expression, so that clients that do + not know about the augmenting module do not break. In the following example, it is OK to augment the "interface" entry with "mandatory-leaf" because the augmentation depends on support for "some-new-iftype". The old client does not know about this type so it would never select this type, and therefore not be adding a mandatory data node. module example-augment { yang-version 1.1; namespace "urn:example:augment"; @@ -5173,24 +5282,24 @@ 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 + abstract, and untyped identity. The identity's 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.18.1. The identity's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | @@ -5273,25 +5382,25 @@ description "Triple DES crypto algorithm"; } } 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. + The "extension" statement's argument is an identifier that is the new + keyword for the extension and must be followed by a block of + substatements that holds detailed extension information. The purpose + of the "extension" statement is to define a keyword, so that it can + be imported and used by other modules. The extension can be used like a normal YANG statement, with the statement name followed by an argument if one is defined by the "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 @@ -5469,22 +5578,22 @@ If a prefix is present on a feature name in the boolean expression, 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. 7.20.2.1. Usage Example - In this example, the container "target" is implemented if any of the - features "outbound-tls" or "outbound-ssh" are supported by the + In this example, the container "target" is implemented if either of + the features "outbound-tls" or "outbound-ssh" are supported by the server. container target { if-feature "outbound-tls or outbound-ssh"; ... } The following examples are equivalent: if-feature "not foo or bar and baz"; @@ -5518,20 +5627,23 @@ or software ability to support parts of a standard module. When this occurs, the server 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 servers to document portions of a base module that are not supported or supported but with different syntax, by using the "deviation" statement. + After applying all deviations announced by a server, in any order, + the resulting data model MUST still be valid. + 7.20.3.1. The deviation's Substatements +--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ | description | 7.21.3 | 0..1 | | deviate | 7.20.3.2 | 1..n | | reference | 7.21.4 | 0..1 | +--------------+----------+-------------+ @@ -5699,22 +5811,22 @@ 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.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 + The "reference" statement takes as an argument a string that is a + human-readable 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"; @@ -5764,23 +5876,22 @@ processing of the XPath expression by replacing all instances 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. If no such instance exists, the dummy node is tentatively created. 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. + "when" statements, those "when" expressions MUST be evaluated first. + There MUST NOT be any circular dependencies among "when" expressions. Note that the XPath expression is conceptually evaluated. This means that an implementation does not have to use an XPath evaluator in the server. The "when" statement can very well be implemented with specially written code. 8. Constraints 8.1. Constraints on Data @@ -6355,22 +6466,23 @@ The lexical representation of an enumeration value is the assigned name string. 9.6.2. Canonical Form The canonical form is the assigned name string. 9.6.3. Restrictions - An enumeration can be restricted with the "enum" (Section 9.6.4) - statement. + An enumeration can be restricted with one or more "enum" + (Section 9.6.4) statements, which enumerate a subset of the values + for the base type. 9.6.4. The enum Statement The "enum" statement, which is a substatement to the "type" statement, MUST be present if the type is "enumeration". It is repeatedly used to specify each assigned name of an enumeration type. It takes as an argument a string which is the assigned name. The string MUST NOT be zero-length and MUST NOT have any leading or trailing whitespace characters (any Unicode character with the "White_Space" property). The use of Unicode control codes SHOULD be @@ -6502,21 +6614,21 @@ changed. 9.7.1. Restrictions A bits type can be restricted with the "bit" (Section 9.7.4) statement. 9.7.2. Lexical Representation The lexical representation of the bits type is a space-separated list - of the individual bit values that are set. A zero-length string thus + of the names of the bits that are set. A zero-length string thus represents a value where no bits are set. 9.7.3. Canonical Form In the canonical form, the bit values are separated by a single space character and they appear ordered by their position (see Section 9.7.4.2). 9.7.4. The bit Statement @@ -6628,37 +6740,41 @@ statement. The length of a binary value is the number of octets it contains. 9.8.2. Lexical Representation Binary values are encoded with the base64 encoding scheme (see [RFC4648], Section 4). 9.8.3. Canonical Form - The canonical form of a binary value follows the rules in [RFC4648]. + The canonical form of a binary value follows the rules of "Base 64 + Encoding" in [RFC4648]. 9.9. The leafref Built-In Type - The leafref type is used to declare a constraint on the value space - of a leaf, based on a reference to a set of leaf instances in the - data tree. The "path" substatement (Section 9.9.2) selects a set of - leaf instances, and the leafref value space is the set of values of - these leaf instances. + The leafref type is restricted to the value space of some leaf or + leaf-list node in the schema tree and optionally further restricted + by corresponding instance nodes in the data tree. The "path" + substatement (Section 9.9.2) is used to identify the referred leaf or + leaf-list node in the schema tree. The value space of the referring + node is the value space of the referred node. - If the leaf with the leafref type represents configuration data, and - the "require-instance" property (Section 9.9.3) is "true", the leaf - it refers to MUST also represent configuration. Such a leaf puts a - constraint on valid data. All 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. + If the "require-instance" property (Section 9.9.3) is "true", there + MUST exist an node in the data tree, or a node with a default value + in use (see Section 7.6.1 and Section 7.7.2), of the referred schema + tree leaf or leaf-list node with the same value as the leafref value + in a valid data tree. + + If the referring node represents configuration data, and the + "require-instance" property (Section 9.9.3) is "true", the referred + node MUST also represent configuration. 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.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 @@ -6699,30 +6815,30 @@ the "path" statement is defined. 9.9.3. The require-instance Statement The "require-instance" statement, which is a substatement to the "type" statement, MAY be present if the type is "instance-identifier" or "leafref". It takes as an argument the string "true" or "false". If this statement is not present, it defaults to "true". If "require-instance" is "true", it means that the instance being - referred MUST exist for the data to be valid. This constraint is + referred to MUST exist for the data to be valid. This constraint is enforced according to the rules in Section 8. If "require-instance" is "false", it means that the instance being - referred MAY exist in valid data. + referred to MAY exist in valid data. 9.9.4. Lexical Representation A leafref value is lexically represented the same way as the leaf it - references. + references represents its value. 9.9.5. Canonical Form The canonical form of a leafref is the same as the canonical form of the leaf it references. 9.9.6. Usage Example With the following list: @@ -7005,31 +7121,33 @@ if the leaf exists. 9.12. The union Built-In Type The union built-in type represents a value that corresponds to one of its member types. When the type is "union", the "type" statement (Section 7.4) MUST be - present. It is used to repeatedly specify each member type of the + present. It is repeatedly used to specify each member type of the union. It takes as an argument a string that is the name of a member type. A member type can be of any built-in or derived type. - In the XML encoding, a value representing a union data type is - validated consecutively against each member type, in the order they - are specified in the "type" statement, until a match is found. The - type that matched will be the type of the value for the node that was - validated. + When generating an XML encoding, a value is encoded according to the + rules of the member type to which the value belongs. When + interpreting an XML encoding, a value is validated consecutively + against each member type, in the order they are specified in the + "type" statement, until a match is found. The type that matched will + be the type of the value for the node that was validated, and the + encoding is interpreted according to the rules for that type. Any default value or "units" property defined in the member types is not inherited by the union type. 9.12.1. Restrictions A union cannot be restricted. However, each member type can be restricted, based on the rules defined in Section 9. 9.12.2. Lexical Representation @@ -7037,21 +7155,21 @@ The lexical representation of a union is a value that corresponds to the representation of any one of the member types. 9.12.3. Canonical Form The canonical form of a union value is the same as the canonical form of the member type of the value. 9.12.4. Usage Example - The following is a union of an int32 an enumeration: + The following is a union of an int32 and an enumeration: type union { type int32; type enumeration { enum "unbounded"; } } Care must be taken when a member type is a leafref where the "require-instance" property (Section 9.9.3) is "true". If a leaf of @@ -7213,35 +7331,36 @@ } must '/interface[name=current()]/enabled = "true"'; } 10.2. Functions for Strings 10.2.1. re-match() boolean re-match(string subject, string pattern) - The re-match() function returns true if the "subject" string matches - the regular expression "pattern"; otherwise it returns false. + The re-match() function returns "true" if the "subject" string + matches the regular expression "pattern"; otherwise it returns + "false". The function "re-match" checks if a string matches a given regular expression. The regular expressions used are the XML Schema regular expressions [XSD-TYPES]. Note that this includes implicit anchoring of the regular expression at the head and tail. 10.2.1.1. Usage Example The expression: re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}") - returns true. + returns "true". To count all logical interfaces called eth0., do: count(/interface[re-match(name, "eth0\.\d+")]) 10.3. Functions for the YANG Types "leafref" and "instance-identifier" 10.3.1. deref() node-set deref(node-set nodes) @@ -7250,20 +7369,23 @@ in document order in the argument "nodes", and returns the nodes it refers to. If the first argument node is of type instance-identifier, the function returns a node set that contains the single node that the instance identifier refers to, if it exists. If no such node exists, an empty node-set is returned. If the first argument node is of type leafref, the function returns a node set that contains the nodes that the leafref refers to. + Specifically, this set contains the nodes selected by the leafref's + "path" statement (Section 9.9.2) that have the same value as the + first argument node. If the first argument node is of any other type, an empty node set is returned. 10.3.1.1. Usage Example list interface { key "name type"; leaf name { ... } leaf type { ... } leaf enabled { @@ -7288,24 +7410,24 @@ } } } 10.4. Functions for the YANG Type "identityref" 10.4.1. derived-from() boolean derived-from(node-set nodes, string identity) - The derived-from() function returns true if any node in the argument - "nodes" is a node of type identityref, and its value is an identity - that is derived from (see Section 7.18.2) the identity "identity"; - otherwise it returns false. + The derived-from() function returns "true" if any node in the + argument "nodes" is a node of type identityref, and its value is an + identity that is derived from (see Section 7.18.2) the identity + "identity"; otherwise it returns "false". The parameter "identity" is a string matching the rule "identifier-ref" in Section 14. If a prefix is present on the identity, 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. If no prefix is present, the identity refers to an identity defined in the current module or an included submodule. 10.4.1.1. Usage Example @@ -7343,24 +7465,24 @@ when 'derived-from(type, "exif:ethernet")'; // generic ethernet definitions here } ... } 10.4.2. derived-from-or-self() boolean derived-from-or-self(node-set nodes, string identity) - The derived-from-or-self() function returns true if any node in the + The derived-from-or-self() function returns "true" if any node in the argument "nodes" is a node of type identityref, and its value is an identity that is equal to or derived from (see Section 7.18.2) the - identity "identity"; otherwise it returns false. + identity "identity"; otherwise it returns "false". The parameter "identity" is a string matching the rule "identifier-ref" in Section 14. If a prefix is present on the identity, 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. If no prefix is present, the identity refers to an identity defined in the current module or an included submodule. 10.4.2.1. Usage Example @@ -7417,23 +7539,23 @@ severity "major" or higher: /alarm[enum-value(severity) >= 5] 10.6. Functions for the YANG Type "bits" 10.6.1. bit-is-set() boolean bit-is-set(node-set nodes, string bit-name) - The bit-is-set() function returns true if the first node in document - order in the argument "nodes" is a node of type bits, and its value - has the bit "'bit-name" set; otherwise it returns false. + The bit-is-set() function returns "true" if the first node in + document order in the argument "nodes" is a node of type bits, and + its value has the bit "'bit-name" set; otherwise it returns "false". 10.6.1.1. Usage Example If an interface has this leaf: leaf flags { type bits { bit UP; bit PROMISCUOUS bit DISABLED; @@ -7501,22 +7623,22 @@ o A "mandatory" statement may be removed or changed from "true" to "false". o A "min-elements" statement may be removed, or changed to require fewer elements. o A "max-elements" statement may be removed, or changed to allow more elements. - o A "description" statement may be added or clarified without - changing the semantics of the definition. + o A "description" statement may be added or changed without changing + the semantics of the definition. o A "base" statement may be added to an "identity" statement. o A "base" statement may be removed from an "identityref" type, provided there is at least one "base" statement left. o New typedefs, groupings, rpcs, notifications, extensions, features, and identities may be added. o New data definition statements may be added if they do not add @@ -7587,21 +7709,22 @@ This rule exists in order to allow implementations of existing YANG version 1 modules together with YANG version 1.1 modules. Without this rule, updating a single module to YANG version 1.1 would have a cascading effect on modules that import it, requiring all of them to also be updated to YANG version 1.1, and so on. 13. YIN A YANG module can be translated into an alternative XML-based syntax called YIN. The translated module is called a YIN module. This - section describes symmetric mapping rules between the two formats. + section describes bidirectional mapping rules between the two + formats. The YANG and YIN formats contain equivalent information using different notations. The YIN notation enables developers to represent YANG data models in XML and therefore use the rich set of XML-based tools for data filtering and validation, automated generation of code and documentation, and other tasks. Tools like XSLT or XML validators can be utilized. The mapping between YANG and YIN does not modify the information content of the model. Comments and whitespace are not preserved. @@ -7962,24 +8085,28 @@ [description-stmt] [reference-stmt] "}") stmtsep if-feature-stmt = if-feature-keyword sep if-feature-expr-str stmtend if-feature-expr-str = < a string that matches the rule > < if-feature-expr > - if-feature-expr = "(" if-feature-expr ")" / - if-feature-expr sep boolean-operator sep - if-feature-expr / - not-keyword sep if-feature-expr / + if-feature-expr = if-feature-term + [sep or-keyword sep if-feature-expr] + + if-feature-term = if-feature-factor + [sep and-keyword sep if-feature-term] + + if-feature-factor = not-keyword sep if-feature-factor / + "(" sep if-feature-expr sep ")" / identifier-ref-arg boolean-operator = and-keyword / or-keyword typedef-stmt = typedef-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order type-stmt [units-stmt] [default-stmt] @@ -7999,21 +8125,21 @@ decimal64-specification / string-restrictions / enum-specification / leafref-specification / identityref-specification / instance-identifier-specification / bits-specification / union-specification / binary-specification - numerical-restrictions = range-stmt + numerical-restrictions = [range-stmt] range-stmt = range-keyword sep range-arg-str optsep (";" / "{" stmtsep ;; these stmts can appear in any order [error-message-stmt] [error-app-tag-stmt] [description-stmt] [reference-stmt] "}") stmtsep @@ -8947,96 +9069,99 @@ 15. NETCONF Error Responses for YANG Related Errors A number of NETCONF error responses are defined for error cases related to the data-model handling. If the relevant YANG statement has an "error-app-tag" substatement, that overrides the default value specified below. 15.1. Error Message for Data That Violates a unique Statement If a NETCONF operation would result in configuration data where a - unique constraint is invalidated, the following error is returned: + unique constraint is invalidated, the following error MUST be + returned: error-tag: operation-failed error-app-tag: data-not-unique error-info: : Contains an instance identifier that points to a leaf that invalidates the unique constraint. This element is present once for each non-unique leaf. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). 15.2. Error Message for Data That Violates a max-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too many entries the following error - is returned: + MUST be returned: error-tag: operation-failed error-app-tag: too-many-elements This error is returned once, with the error-path identifying the list node, even if there are more than one extra child present. 15.3. Error Message for Data That Violates a min-elements Statement If a NETCONF operation would result in configuration data where a - list or a leaf-list would have too few entries the following error is - returned: + list or a leaf-list would have too few entries the following error + MUST be returned: error-tag: operation-failed error-app-tag: too-few-elements This error is returned once, with the error-path identifying the list node, even if there are more than one child missing. 15.4. Error Message for Data That Violates a must Statement If a NETCONF operation would result in configuration data where the restrictions imposed by a "must" statement is violated the following - error is returned, unless a specific "error-app-tag" substatement is - present for the "must" statement. + error MUST be returned, unless a specific "error-app-tag" + substatement is present for the "must" statement. error-tag: operation-failed error-app-tag: must-violation 15.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" or "leafref" marked with require- instance "true" refers to a non-existing instance, the following - error is returned: + error MUST be returned: error-tag: data-missing error-app-tag: instance-required error-path: Path to the instance-identifier or leafref leaf. 15.6. Error Message for Data That Violates a mandatory choice Statement If a NETCONF operation would result in configuration data where no - nodes exists in a mandatory choice, the following error is returned: + nodes exists in a mandatory choice, the following error MUST be + returned: error-tag: data-missing error-app-tag: missing-choice error-path: Path to the element with the missing choice. error-info: : Contains the name of the missing mandatory choice. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). 15.7. Error Message for the "insert" Operation If the "insert" and "key" or "value" attributes are used in an for a list or leaf-list node, and the "key" or "value" - refers to a non-existing instance, the following error is returned: + refers to a non-existing instance, the following error MUST be + returned: error-tag: bad-attribute error-app-tag: missing-instance 16. IANA Considerations This document registers one capability identifier URN from the "Network Configuration Protocol (NETCONF) Capability URNs" registry: Index Capability Identifier @@ -9086,23 +9211,23 @@ - Balazs Lengyel (Ericsson) - David Partain (Ericsson) - Juergen Schoenwaelder (Jacobs University Bremen) - Phil Shafer (Juniper Networks) 19. Acknowledgements The editor wishes to thank the following individuals, who all provided helpful comments on various versions of this document: Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, - Ladislav Lhotka, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy - Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert Wijnen, and - Robert Wilton. + Ladislav Lhotka, Lionel Morand, Gerhard Muenz, Peyman Owladi, Tom + Petch, Randy Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert + Wijnen, Robert Wilton, and Dale Worley. 20. ChangeLog RFC Editor: remove this section upon publication as an RFC. 20.1. Version -10 o Made single and double quote characters illegal in unquoted strings. @@ -9231,53 +9355,53 @@ Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Library", draft-ietf-netconf-yang-library-06 (work in progress), April 2016. [ISO.10646] International Organization for Standardization, "Information Technology - Universal Multiple-Octet Coded Character Set (UCS)", ISO Standard 10646:2003, 2003. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, - DOI 10.17487/RFC2119, March 1997, + Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ + RFC2119, March 1997, . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, - RFC 3986, DOI 10.17487/RFC3986, January 2005, + Resource Identifier (URI): Generic Syntax", STD 66, RFC + 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, - DOI 10.17487/RFC5234, January 2008, + Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ + RFC5234, January 2008, . [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . - [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", - RFC 7405, DOI 10.17487/RFC7405, December 2014, + [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC + 7405, DOI 10.17487/RFC7405, December 2014, . [XML-NAMES] Bray, T., Hollander, D., Layman, A., Tobin, R., and H. Thompson, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208, December 2009, . [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) @@ -9291,44 +9415,49 @@ REC-xmlschema-2-20041028, October 2004, . 21.2. Informative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", draft-ietf-netconf-restconf-13 (work in progress), April 2016. + [I-D.ietf-netmod-rfc6087bis] + Bierman, A., "Guidelines for Authors and Reviewers of YANG + Data Model Documents", draft-ietf-netmod-rfc6087bis-06 + (work in progress), March 2016. + [I-D.ietf-netmod-yang-json] Lhotka, L., "JSON Encoding of Data Modeled with YANG", draft-ietf-netmod-yang-json-10 (work in progress), March 2016. [I-D.vanderstok-core-comi] Stok, P. and A. Bierman, "CoAP Management Interface", draft-vanderstok-core-comi-09 (work in progress), March 2016. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information - Version 2 (SMIv2)", STD 58, RFC 2578, - DOI 10.17487/RFC2578, April 1999, + Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/ + RFC2578, April 1999, . [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. - Schoenwaelder, Ed., "Textual Conventions for SMIv2", - STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, + Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD + 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, . [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation - Structure of Management Information", RFC 3780, - DOI 10.17487/RFC3780, May 2004, + Structure of Management Information", RFC 3780, DOI + 10.17487/RFC3780, May 2004, . [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, July 2007, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, .