--- 1/draft-ietf-netmod-rfc6020bis-07.txt 2015-10-19 05:15:11.789883824 -0700 +++ 2/draft-ietf-netmod-rfc6020bis-08.txt 2015-10-19 05:15:12.121891828 -0700 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track September 23, 2015 -Expires: March 26, 2016 +Intended status: Standards Track October 19, 2015 +Expires: April 21, 2016 The YANG 1.1 Data Modeling Language - draft-ietf-netmod-rfc6020bis-07 + draft-ietf-netmod-rfc6020bis-08 Abstract YANG is a data modeling language used to model configuration data, state data, remote procedure calls, and notifications for network management protocols like the Network Configuration Protocol (NETCONF). Status of This Memo @@ -22,21 +22,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on March 26, 2016. + This Internet-Draft will expire on April 21, 2016. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -57,26 +57,25 @@ not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 - 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 + 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25 4.2.10. Notification Definitions . . . . . . . . . . . . . . 27 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 @@ -85,303 +84,303 @@ 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 31 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 32 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 32 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 32 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 32 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 33 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 34 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 34 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 35 - 5.6.5. Announcing Conformance Information in NETCONF . . . . 38 + 5.6.5. Announcing Conformance Information in NETCONF . . . . 37 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 38 - 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 39 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 39 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 41 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 41 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 42 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 42 - 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 43 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 42 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 43 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 45 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 45 7.1. The module Statement . . . . . . . . . . . . . . . . . . 46 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 47 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 48 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 49 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 49 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 49 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 50 - 7.1.7. The organization Statement . . . . . . . . . . . . . 51 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 51 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 51 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 52 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 53 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 54 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 55 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 56 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 56 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 57 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 57 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 57 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 57 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 58 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 58 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 58 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 58 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 59 - 7.5.2. The container's Substatements . . . . . . . . . . . . 59 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 60 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 61 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 62 - 7.5.6. The container's Child Node Statements . . . . . . . . 62 - 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 62 - 7.5.8. NETCONF Operations . . . . . . . . . . 63 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 63 - 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 65 - 7.6.1. The leaf's default value . . . . . . . . . . . . . . 65 - 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 66 - 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 66 - 7.6.4. The leaf's default Statement . . . . . . . . . . . . 66 - 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 66 - 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 67 - 7.6.7. NETCONF Operations . . . . . . . . . . 67 - 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 67 - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 68 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 69 - 7.7.2. The leaf-list's default values . . . . . . . . . . . 69 - 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 70 - 7.7.4. The leaf-list's default Statement . . . . . . . . . . 70 - 7.7.5. The min-elements Statement . . . . . . . . . . . . . 71 - 7.7.6. The max-elements Statement . . . . . . . . . . . . . 71 - 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 71 - 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 72 - 7.7.9. NETCONF Operations . . . . . . . . . . 72 - 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 73 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 75 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 75 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 76 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 77 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 78 - 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 78 - 7.8.6. NETCONF Operations . . . . . . . . . . 79 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 80 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 83 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 83 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 84 - 7.9.3. The choice's default Statement . . . . . . . . . . . 85 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 87 - 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 87 - 7.9.6. NETCONF Operations . . . . . . . . . . 87 - 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 87 - 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 88 - 7.10.1. The anydata's Substatements . . . . . . . . . . . . 89 - 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 89 - 7.10.3. NETCONF Operations . . . . . . . . . . 89 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 90 - 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 90 - 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 91 - 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 91 - 7.11.3. NETCONF Operations . . . . . . . . . . 92 - 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 92 - 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 92 - 7.12.1. The grouping's Substatements . . . . . . . . . . . . 93 - 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 94 - 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 94 - 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 94 - 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 95 - 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 96 - 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 96 - 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 97 - 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 97 - 7.14.2. The input Statement . . . . . . . . . . . . . . . . 98 - 7.14.3. The output Statement . . . . . . . . . . . . . . . . 99 - 7.14.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 100 - 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 100 - 7.15. The action Statement . . . . . . . . . . . . . . . . . . 101 - 7.15.1. The action's Substatements . . . . . . . . . . . . . 101 - 7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 102 - 7.16. The notification Statement . . . . . . . . . . . . . . . 104 - 7.16.1. The notification's Substatements . . . . . . . . . . 105 - 7.16.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 105 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 106 - 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 107 - 7.17.1. The augment's Substatements . . . . . . . . . . . . 108 - 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 109 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 - 7.18. The identity Statement . . . . . . . . . . . . . . . . . 111 - 7.18.1. The identity's Substatements . . . . . . . . . . . . 111 - 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 111 - 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 - 7.19. The extension Statement . . . . . . . . . . . . . . . . . 112 - 7.19.1. The extension's Substatements . . . . . . . . . . . 113 - 7.19.2. The argument Statement . . . . . . . . . . . . . . . 113 - 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 114 - 7.20. Conformance-Related Statements . . . . . . . . . . . . . 114 - 7.20.1. The feature Statement . . . . . . . . . . . . . . . 115 - 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 116 - 7.20.3. The deviation Statement . . . . . . . . . . . . . . 117 - 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 120 - 7.21.1. The config Statement . . . . . . . . . . . . . . . . 120 - 7.21.2. The status Statement . . . . . . . . . . . . . . . . 120 - 7.21.3. The description Statement . . . . . . . . . . . . . 121 - 7.21.4. The reference Statement . . . . . . . . . . . . . . 121 - 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 122 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 123 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 123 - 8.2. NETCONF Constraint Enforcement Model . . . . . . . . . . 124 - 8.2.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 124 - 8.2.2. NETCONF Processing . . . . . . . . . . 125 - 8.2.3. Validation . . . . . . . . . . . . . . . . . . . . . 125 - 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 126 - 9.1. Canonical Representation . . . . . . . . . . . . . . . . 126 - 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 126 - 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 127 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 128 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 128 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 128 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 - 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 129 - 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 129 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 130 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 130 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130 - 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 131 - 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 131 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 131 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 131 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 131 - 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 132 - 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 132 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 132 - 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 134 - 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 134 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 - 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 134 - 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 134 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 135 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 - 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 137 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 - 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 137 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 137 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 - 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 139 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 139 - 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 139 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 139 - 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 139 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 140 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 140 - 9.9.3. The require-instance Statement . . . . . . . . . . . 141 - 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 141 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 141 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 141 - 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 145 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 - 9.10.2. The identityref's base Statement . . . . . . . . . . 145 - 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 146 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 146 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 146 - 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 148 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 - 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 148 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 - 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 148 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149 - 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 149 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 149 - 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 149 - 9.13. The instance-identifier Built-In Type . . . . . . . . . . 150 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 - 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 151 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 151 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 151 - 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 152 - 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 152 - 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 152 - 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 152 - 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 152 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 46 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 47 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 48 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 48 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 48 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 49 + 7.1.7. The organization Statement . . . . . . . . . . . . . 50 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 50 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 50 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 51 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 52 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 53 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 53 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 54 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 54 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 55 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 55 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 55 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 55 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 56 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 56 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 56 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 56 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 57 + 7.5.2. The container's Substatements . . . . . . . . . . . . 57 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 58 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 59 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 60 + 7.5.6. The container's Child Node Statements . . . . . . . . 60 + 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 60 + 7.5.8. NETCONF Operations . . . . . . . . . . 61 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 61 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 62 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 62 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 63 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 63 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 64 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 64 + 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 64 + 7.6.7. NETCONF Operations . . . . . . . . . . 64 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 65 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 66 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 66 + 7.7.2. The leaf-list's default values . . . . . . . . . . . 67 + 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 67 + 7.7.4. The leaf-list's default Statement . . . . . . . . . . 68 + 7.7.5. The min-elements Statement . . . . . . . . . . . . . 68 + 7.7.6. The max-elements Statement . . . . . . . . . . . . . 69 + 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 69 + 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 69 + 7.7.9. NETCONF Operations . . . . . . . . . . 70 + 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 71 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 72 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 72 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 73 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 74 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 75 + 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 75 + 7.8.6. NETCONF Operations . . . . . . . . . . 76 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 77 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 80 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 80 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 81 + 7.9.3. The choice's default Statement . . . . . . . . . . . 82 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 84 + 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 84 + 7.9.6. NETCONF Operations . . . . . . . . . . 84 + 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 84 + 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 85 + 7.10.1. The anydata's Substatements . . . . . . . . . . . . 86 + 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 86 + 7.10.3. NETCONF Operations . . . . . . . . . . 86 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 87 + 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 87 + 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 88 + 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 88 + 7.11.3. NETCONF Operations . . . . . . . . . . 89 + 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 89 + 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 89 + 7.12.1. The grouping's Substatements . . . . . . . . . . . . 90 + 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 91 + 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 91 + 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 91 + 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 92 + 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 93 + 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 93 + 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 94 + 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 94 + 7.14.2. The input Statement . . . . . . . . . . . . . . . . 95 + 7.14.3. The output Statement . . . . . . . . . . . . . . . . 96 + 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 97 + 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 97 + 7.15. The action Statement . . . . . . . . . . . . . . . . . . 98 + 7.15.1. The action's Substatements . . . . . . . . . . . . . 98 + 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 99 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 99 + 7.16. The notification Statement . . . . . . . . . . . . . . . 101 + 7.16.1. The notification's Substatements . . . . . . . . . . 102 + 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 102 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 103 + 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 104 + 7.17.1. The augment's Substatements . . . . . . . . . . . . 105 + 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 106 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 106 + 7.18. The identity Statement . . . . . . . . . . . . . . . . . 108 + 7.18.1. The identity's Substatements . . . . . . . . . . . . 108 + 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 108 + 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 + 7.19. The extension Statement . . . . . . . . . . . . . . . . . 109 + 7.19.1. The extension's Substatements . . . . . . . . . . . 110 + 7.19.2. The argument Statement . . . . . . . . . . . . . . . 110 + 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 111 + 7.20. Conformance-Related Statements . . . . . . . . . . . . . 111 + 7.20.1. The feature Statement . . . . . . . . . . . . . . . 112 + 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 113 + 7.20.3. The deviation Statement . . . . . . . . . . . . . . 114 + 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 117 + 7.21.1. The config Statement . . . . . . . . . . . . . . . . 117 + 7.21.2. The status Statement . . . . . . . . . . . . . . . . 117 + 7.21.3. The description Statement . . . . . . . . . . . . . 118 + 7.21.4. The reference Statement . . . . . . . . . . . . . . 118 + 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 119 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 120 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 120 + 8.2. NETCONF Constraint Enforcement Model . . . . . . . . . . 121 + 8.2.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 121 + 8.2.2. NETCONF Processing . . . . . . . . . . 122 + 8.2.3. Validation . . . . . . . . . . . . . . . . . . . . . 123 + 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 123 + 9.1. Canonical Representation . . . . . . . . . . . . . . . . 123 + 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 124 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 124 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 125 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 + 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 126 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 126 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 127 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 127 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 127 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 + 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 128 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 128 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 128 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 128 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 128 + 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 129 + 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 130 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 130 + 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 131 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 131 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 131 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 + 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 132 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 132 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 132 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 + 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 134 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 135 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 135 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 + 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 136 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 136 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 + 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 137 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 137 + 9.9.3. The require-instance Statement . . . . . . . . . . . 138 + 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 138 + 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 138 + 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 138 + 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 142 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 142 + 9.10.2. The identityref's base Statement . . . . . . . . . . 142 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 143 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 143 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 143 + 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 145 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 145 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 145 + 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 145 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 146 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 146 + 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 146 + 9.13. The instance-identifier Built-In Type . . . . . . . . . . 147 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 + 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 148 + 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 + 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 + 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 149 + 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 149 + 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 149 + 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 149 + 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 149 10.3. Functions for the YANG Types "leafref" and "instance- - identifier" . . . . . . . . . . . . . . . . . . . . . . 153 - 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 153 - 10.4. Functions for the YANG Type "identityref" . . . . . . . 154 - 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 154 - 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 154 - 10.5. Functions for the YANG Type "enumeration" . . . . . . . 155 - 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 156 - 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 157 - 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 157 - 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 157 - 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 159 - 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 - 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 160 - 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 163 - 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 164 - 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 188 - 15.1. Error Message for Data That Violates a unique Statement 188 + identifier" . . . . . . . . . . . . . . . . . . . . . . 150 + 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 150 + 10.4. Functions for the YANG Type "identityref" . . . . . . . 151 + 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 151 + 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 151 + 10.5. Functions for the YANG Type "enumeration" . . . . . . . 152 + 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 153 + 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 154 + 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 154 + 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 154 + 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 157 + 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 + 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 157 + 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 160 + 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 161 + 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 185 + 15.1. Error Message for Data That Violates a unique Statement 185 15.2. Error Message for Data That Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 189 + Statement . . . . . . . . . . . . . . . . . . . . . . . 186 15.3. Error Message for Data That Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 189 - 15.4. Error Message for Data That Violates a must Statement . 189 + Statement . . . . . . . . . . . . . . . . . . . . . . . 186 + 15.4. Error Message for Data That Violates a must Statement . 186 15.5. Error Message for Data That Violates a require-instance - Statement . . . . . . . . . . . . . . . . . . . . . . . 190 + Statement . . . . . . . . . . . . . . . . . . . . . . . 187 15.6. Error Message for Data That Does Not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 190 + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 187 15.7. Error Message for Data That Violates a mandatory choice - Statement . . . . . . . . . . . . . . . . . . . . . . . 190 - 15.8. Error Message for the "insert" Operation . . . . . . . . 190 - 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 191 - 17. Security Considerations . . . . . . . . . . . . . . . . . . . 191 - 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191 - 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192 - 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192 - 20.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . 192 - 20.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192 - 20.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192 - 20.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192 - 20.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . 193 - 20.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193 - 20.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193 - 20.8. Version -00 . . . . . . . . . . . . . . . . . . . . . . 194 - 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 - 21.1. Normative References . . . . . . . . . . . . . . . . . . 194 - 21.2. Informative References . . . . . . . . . . . . . . . . . 195 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 196 + Statement . . . . . . . . . . . . . . . . . . . . . . . 187 + 15.8. Error Message for the "insert" Operation . . . . . . . . 187 + 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 188 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 188 + 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 188 + 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 189 + 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 189 + 20.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . 189 + 20.2. Version -07 . . . . . . . . . . . . . . . . . . . . . . 189 + 20.3. Version -06 . . . . . . . . . . . . . . . . . . . . . . 189 + 20.4. Version -05 . . . . . . . . . . . . . . . . . . . . . . 189 + 20.5. Version -04 . . . . . . . . . . . . . . . . . . . . . . 189 + 20.6. Version -03 . . . . . . . . . . . . . . . . . . . . . . 190 + 20.7. Version -02 . . . . . . . . . . . . . . . . . . . . . . 190 + 20.8. Version -01 . . . . . . . . . . . . . . . . . . . . . . 190 + 20.9. Version -00 . . . . . . . . . . . . . . . . . . . . . . 191 + 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 191 + 21.1. Normative References . . . . . . . . . . . . . . . . . . 191 + 21.2. Informative References . . . . . . . . . . . . . . . . . 192 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 193 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 has + [I-D.vanderstok-core-comi]). Further, other encodings than XML have been propsed (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 the data model defined in a - YANG module is represented in the Extensible Markup Language (XML), - and how NETCONF operations are used to manipulate the data. Other + 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. 1.1. Summary of Changes from RFC 6020 This document defines version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification [RFC6020]. o Changed the YANG version from "1" to "1.1". @@ -416,21 +415,21 @@ o Allow "must" in "input", "output", and "notification". o Added a set of new XPath functions in Section 10. o Clarified the XPath context's tree in Section 6.4.1. o Defined the string value of an identityref in XPath expressions (see Section 9.10). - o Clarified what unprefixed names means in leafrefs in typedefs (see + o Clarified what unprefixed names mean in leafrefs in typedefs (see Section 9.9.2). o Allow identities to be derived from multiple base identities (see Section 7.18 and Section 9.10). o Allow enumerations to be subtyped (see Section 9.6). o Allow leaf-lists to have default values (see Section 7.7.2). o Use [RFC7405] syntax for case-sensitive strings in the grammar. @@ -472,21 +471,24 @@ o base type: The type from which a derived type was derived, which may be either a built-in type or another derived type. o built-in type: A YANG data type defined in the YANG language, such as uint32 or string. o choice: A schema node where only one of a number of identified alternatives is valid. - o conformance: A measure of how accurately a device follows a data + o client: An entity that can access YANG-defined data on a server, + over some network management protocol. + + o conformance: A measure of how accurately a server follows a data model. o container: An interior data node that exists in at most one instance in the data tree. A container has no value, but rather a set of child nodes. o data definition statement: A statement that defines new data nodes. One of container, leaf, leaf-list, list, choice, case, augment, uses, anydata, and anyxml. @@ -498,30 +500,27 @@ anyxml. o data tree: An instantiated tree of any data modeled with YANG, e.g., configuration data, state data, combined configuration and state data, RPC or action input, RPC or action output, or notification. o derived type: A type that is derived from a built-in type (such as uint32), or another derived type. - o device deviation: A failure of the device to implement the module - faithfully. - o extension: An extension attaches non-YANG semantics to statements. The extension statement defines new statements to express these semantics. o feature: A mechanism for marking a portion of the model as optional. Definitions can be tagged with a feature name and are - only valid on devices that support that feature. + 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 instance identifier: A mechanism for identifying a particular node @@ -533,90 +532,94 @@ tree. A leaf has a value but no child nodes. o leaf-list: Like the leaf node but defines a set of uniquely identifiable nodes rather than a single node. Each node has a value but no child nodes. o list: An interior data node that may exist in multiple instances in the data tree. A list has no value, but rather a set of child 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. + o module: A YANG module defines a hierarchy of schema nodes. With its definitions and the definitions it imports or includes from elsewhere, a module is self-contained and "compilable". o RPC: A Remote Procedure Call. 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. o schema tree: The definition hierarchy specified within a module. + o server: An entity that provides access to YANG-defined data to a + client, over some network management protocol. + + o server deviation: A failure of the server to implement a module + faithfully. + o submodule: A partial module definition that contributes derived types, groupings, data nodes, RPCs, actions, and notifications to a module. A YANG module can be constructed from a number of submodules. o top-level data node: A data node where there is no other data node between it and a module or submodule statement. o uses: The "uses" statement is used to instantiate the set of schema nodes defined in a grouping statement. The instantiated nodes may be refined and augmented to tailor them to any specific needs. The following terms are defined in [RFC6241]: - o client - o configuration data + o configuration datastore: a configuration datastore is an instantiated data tree with configuration data o datastore: an instantiated data tree o running configuration datastore - o server - o state data -3.1. Mandatory Nodes - - A mandatory node is one of: - - o A leaf, choice, anydata, or anyxml node with a "mandatory" - statement with the value "true". - - o A list or leaf-list node with a "min-elements" statement with a - value greater than zero. - - o A container node without a "presence" statement, which has at - least one mandatory node as a child. - 4. YANG Overview + 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 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. Altough out of scope for this specification, YANG can also - be used for other protocols than NETCONF. + 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 @@ -651,116 +654,108 @@ 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 in NETCONF operations. + will be encoded on-the-wire. 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 NETCONF data models, not - arbitrary XML documents or arbitrary data models. The data models - described by YANG are designed to be easily operated upon by NETCONF - operations. + the problem space to allow expression of data models for network + management protocols such as NETCONF, not arbitrary XML documents or + arbitrary data models. To the extent possible, YANG maintains compatibility with Simple Network Management Protocol's (SNMP's) SMIv2 (Structure of Management Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules can be automatically translated into YANG modules for read-only - access. However, YANG is not concerned with reverse translation from - YANG to SMIv2. - - Like NETCONF, YANG targets smooth integration with the device's - native management infrastructure. This allows implementations to - leverage their existing access control mechanisms to protect or - expose elements of the data model. + access [RFC6643]. However, YANG is not concerned with reverse + 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. This progressive approach handles the inter-related nature - of YANG concepts and statements. A detailed description of YANG - statements and syntax begins in Section 7. + sections. 4.2.1. Modules and Submodules A module contains three types of statements: module-header statements, revision statements, and definition statements. The module header statements describe the module and give information about the module itself, the revision statements give information about the history of the module, and the definition statements are the body of the module where the data model is defined. - A device may implement a number of modules, allowing multiple views + A server may implement a number of modules, allowing multiple views of the same data, or multiple views of disjoint subsections of the - device's data. Alternatively, the server may implement only one + 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. The "import" statement allows a module or submodule to reference material defined in other modules. The "include" statement is used by a module to incorporate the contents of its submodules into the module. 4.2.2. Data Modeling Basics - YANG defines four types of nodes for data modeling. In each of the - following subsections, the examples show the YANG syntax as well as a - corresponding NETCONF XML representation. + YANG defines four 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. 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; description "Hostname for this system"; } - NETCONF XML Example: + XML Encoding Example: my.example.com The "leaf" statement is covered in Section 7.6. 4.2.2.2. Leaf-List Nodes A leaf-list defines a sequence of values of a particular type. YANG Example: leaf-list domain-search { type string; description "List of domain names to search"; } - NETCONF XML Example: + XML Encoding Example: high.example.com low.example.com everywhere.example.com The "leaf-list" statement is covered in Section 7.7. 4.2.2.3. Container Nodes A container is used to group related nodes in a subtree. A container @@ -773,21 +768,21 @@ container system { container login { leaf message { type string; description "Message given at start of login session"; } } } - NETCONF XML Example: + XML Encoding Example: Good morning The "container" statement is covered in Section 7.5. 4.2.2.4. List Nodes @@ -806,21 +801,21 @@ type string; } leaf full-name { type string; } leaf class { type string; } } - NETCONF XML Example: + XML Encoding Example: glocks Goldie Locks intruder snowey Snow White free-loader @@ -968,21 +964,21 @@ typedef percent { type uint8 { range "0 .. 100"; } } leaf completed { type percent; } - NETCONF XML Example: + 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: @@ -997,21 +993,21 @@ description "Target port number"; } } container peer { container destination { uses target; } } - NETCONF XML Example: + XML Encoding Example:
192.0.2.1
830 The grouping can be refined as it is used, allowing certain statements to be overridden. In this example, the description is @@ -1045,21 +1041,21 @@ 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 device handles the + 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. YANG Example: container food { @@ -1077,21 +1073,21 @@ type enumeration { enum dark; enum milk; enum first-available; } } } } } - NETCONF XML Example: + XML Encoding Example: The "choice" statement is covered in Section 7.9. 4.2.8. Extending Data Models (augment) @@ -1111,44 +1107,43 @@ 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 representation of the - data will reflect the prefix of the augmenting module. For example, - if the above augmentation were in a module with prefix "other", the - XML would look like: + 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: - NETCONF XML Example: + XML Encoding Example: alicew Alice N. Wonderland drop-out 1024 The "augment" statement is covered in Section 7.17. 4.2.9. Operation Definitions - YANG allows the definition of operations. The operations' names, + 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 - node in the data hierarchy. Such operations are defined with the - "action" statement. + data node. Such operations are defined with the "action" statement. YANG Example: rpc activate-software-image { input { leaf image-name { type string; } } output { @@ -1483,23 +1478,23 @@ type or grouping cannot be defined if a higher level in the schema 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 device follows the - model. Generally speaking, devices are responsible for implementing - the model faithfully, allowing applications to treat devices which + 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 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 @@ -1510,98 +1505,95 @@ 5.6.1. Basic Behavior The model defines a contract between a YANG-based client and server, which allows both parties to have faith the other knows the syntax and semantics behind the modeled data. The strength of YANG lies in the strength of this contract. 5.6.2. Optional Features In many models, the modeler will allow sections of the model to be - conditional. The device controls whether these conditional portions - of the model are supported or valid for that particular device. + conditional. The server controls whether these conditional portions + of the model are supported or valid for that particular server. For example, a syslog data model may choose to include the ability to save logs locally, but the modeler will realize that this is only - possible if the device has local storage. If there is no local - storage, an application should not tell the device to save logs. + possible if the server has local storage. If there is no local + storage, an application should not tell the server to save logs. YANG supports this conditional mechanism using a construct called "feature". Features give the modeler a mechanism for making portions of the module conditional in a manner that is controlled by the - device. The model can express constructs that are not universally - present in all devices. These features are included in the model + server. The model can express constructs that are not universally + present in all servers. These features are included in the model definition, allowing a consistent view and allowing applications to learn which features are supported and tailor their behavior to the - device. + server. A module may declare any number of features, identified by simple strings, and may make portions of the module optional based on those - features. If the device supports a feature, then the corresponding - portions of the module are valid for that device. If the device + features. If the server supports a feature, then the corresponding + portions of the module are valid for that server. If the server doesn't support the feature, those parts of the module are not valid, and applications should behave accordingly. Features are defined using the "feature" statement. Definitions in the module that are conditional to the feature are noted by the "if-feature" statement. Further details are available in Section 7.20.1. 5.6.3. Deviations - In an ideal world, all devices would be required to implement the + In an ideal world, all servers would be required to implement the model exactly as defined, and deviations from the model would not be - allowed. But in the real world, devices are often not able or + allowed. But in the real world, servers are often not able or designed to implement the model as written. For YANG-based - automation to deal with these device deviations, a mechanism must - exist for devices to inform applications of the specifics of such + automation to deal with these server deviations, a mechanism must + exist for servers to inform applications of the specifics of such deviations. For example, a BGP module may allow any number of BGP peers, but a - particular device may only support 16 BGP peers. Any application + particular server may only support 16 BGP peers. Any application configuring the 17th peer will receive an error. While an error may suffice to let the application know it cannot add another peer, it would be far better if the application had prior knowledge of this limitation and could prevent the user from starting down the path that could not succeed. - Device deviations are declared using the "deviation" statement, which + Server deviations are declared using the "deviation" statement, which takes as its argument a string that identifies a node in the schema tree. The contents of the statement details the manner in which the - device implementation deviates from the contract as defined in the + server implementation deviates from the contract as defined in the module. Further details are available in Section 7.20.3. 5.6.4. Implementing a Module A server implements a module if it implements the module's data nodes, rpcs, actions, notifications, and deviations. A server MUST NOT implement more than one revision of a module. If a server implements a module A that imports a module B, and A uses any node from B in an "augment" or "path" statement that the server supports, then the server MUST implement a revision of module B that has these nodes defined. This is regardless of if module B is imported by revision or not. - NOTE: The next paragraph needs to be aligned with - ietf-yang-library. - If a server implements a module A that imports a module C without specifying the revision date of module C, and the server does not implement C (e.g., if C only defines some typedefs), the server MUST - list module C in the "/modules/module" list from "ietf-yang-library", - and it MUST set the leaf "default-revision" to "true" for this - module. + list module C in the "/modules/module" list from "ietf-yang-library" + [I-D.ietf-netconf-yang-library], and it MUST set the leaf + "conformance" to "import" for this module. 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. For example, with these modules: module a { yang-version 1.1; namespace "http://example.com/a"; @@ -1667,22 +1660,22 @@ 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/module" list from "ietf-yang-library". - The following shows valid data for the "/modules/module" list for a - server that implements module "a": + The following XML enconding example shows valid data for the + "/modules/module" list for a server that implements module "a": ee1ecb017370cafd a 2015-01-01 foo implement @@ -1913,29 +1906,26 @@ 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. - If a YANG compiler does not support a particular extension, which - appears in a YANG module as an unknown-statement (see Section 14), - the entire unknown-statement MAY be ignored by the compiler. - - If a YANG parser does not support a particular extension, which - appears in a YANG module as an unknown-statement (see Section 14), - the entire unknown-statement MAY be ignored by the parser. Note that - even in this case the semantics associated with the extension still - apply (as if they were part of a description statement). + 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 support the extensions. 6.4. XPath Evaluations YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation for specifying many inter-node references and dependencies. An implementation is not required to implement an XPath interpreter, but @@ -2008,43 +1999,43 @@ The accessible tree depends on where the statement with the XPath expression is defined: o If the XPath expression is defined in substatement to a data node that represents configuration, the accessible tree is the data in the datastore where the context node exists. The root node has all top-level configuration data nodes in all modules as children. o If the XPath expression is defined in a substatement to a data node that represents state data, the accessible tree is all state - data on the device, and the running configuration datastore. The + data in the server, and the running configuration datastore. The root node has all top-level data nodes in all modules as children. o If the XPath expression is defined in a substatement to a "notification" statement, the accessible tree is the notification - instance, all state data on the device, and the running + instance, all state data in the server, and the running configuration datastore. The root node has the node representing the notification being defined and all top-level data nodes in all modules as children. o If the XPath expression is defined in a substatement to an "input" statement in an "rpc" or "action" statement, the accessible tree - is the RPC or action operation instance, all state data on the - device, and the running configuration datastore. The root node + is the RPC or action operation instance, all state data in the + server, and the running configuration datastore. The root node has the node representing the operation being defined and all top- level data nodes in all modules as children. The node representing the operation being defined has the operation's input parameters as children. o If the XPath expression is defined in a substatement to an "output" statement in an "rpc" or "action" statement, the accessible tree is the RPC or action operation's output, all state - data on the device, and the running configuration datastore. The + data in the server, and the running configuration datastore. The root node has the node representing the operation being defined and all top-level data nodes in all modules as children. The node representing the operation being defined has the operation's output parameters as children. In the accessible tree, all leafs and leaf-lists with default values in use exist (See Section 7.6.1 and Section 7.7.2). If a node that exists in the accessible tree has a non-presence container as a child, then the non-presence container also exists in @@ -2091,24 +2081,22 @@ 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. 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. It is RECOMMENDED to choose - module names that will have a low probability of colliding with - standard or other enterprise modules and submodules, e.g., by using - the enterprise or organization name as a prefix for the module name. + module without a central registry. See Section 5.1 for + recommendations on how to name modules. A module typically has the following layout: module { // header information @@ -2176,22 +2164,23 @@ 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. For compatibility between YANG version 1 and 1.1, see Section 12. 7.1.3. The namespace Statement The "namespace" statement defines the XML namespace that all - identifiers defined by the module are qualified by, with the - exception of data node identifiers defined inside a grouping (see + identifiers defined by the module are qualified by in the XML + encoding, with the exception of identifiers for data nodes, action + nodes, and notification nodes defined inside a grouping (see 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 @@ -2382,31 +2371,29 @@ 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. 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. It is RECOMMENDED to choose - submodule names that will have a low probability of colliding with - standard or other enterprise modules and submodules, e.g., by using - the enterprise or organization name as a prefix for the submodule - name. + submodule without a central registry. See Section 5.1 for + recommendations on how to name submodules. A submodule typically has the following layout: submodule { + // module identification // linkage statements // meta information @@ -2633,21 +2621,21 @@ In 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 device using ssh, but can also contain any ssh-related + the server using ssh, but can also contain any ssh-related configuration knobs, such as connection rates or retry limits. The "presence" statement (see Section 7.5.5) is used to give semantics to the existence of the container in the data tree. 7.5.2. The container's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | action | 7.15 | 0..n | @@ -2693,45 +2681,45 @@ The result of the XPath expression is converted to a boolean value using the standard XPath rules. Note that since all leaf values in the data tree are conceptually stored in their canonical form (see Section 7.6 and Section 7.7), any XPath comparisons are done on the canonical value. Also note that the XPath expression is conceptually evaluated. This means that an implementation does not have to use an XPath evaluator - on the device. How the evaluation is done in practice is an + in the server. How the evaluation is done in practice is an implementation decision. 7.5.4. The must's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | 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 - passed as in the . + 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 - passed as in the . + 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 { @@ -2771,26 +2759,22 @@ 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. - A NETCONF server that replies to a or request MAY - choose not to send a container element if the container node does not - have the "presence" statement and no child nodes exist. Thus, a - client that receives an for a or - request, must be prepared to handle the case that a container node - without a "presence" statement is not present in the XML. + 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 child node is deleted, the NETCONF server MAY delete the container. @@ -2868,21 +2852,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: + 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 @@ -2937,21 +2921,21 @@ "mandatory" is true. 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. @@ -2959,27 +2943,20 @@ 7.6.6. XML Encoding Rules A leaf node is encoded as an XML element. The element's local name is the leaf's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of the leaf node is encoded to XML according to the type, and sent as character data in the element. - A NETCONF server that replies to a or request MAY - choose not to send the leaf element if its value is the default - value. Thus, a client that receives an for a or - request, MUST be prepared to handle the case that a leaf - node with a default value is not present in the XML. In this case, - the value used by the server is known to be the default value. - See Section 7.6.8 for an example. 7.6.7. NETCONF Operations When a NETCONF server processes an request, the elements of procedure for the leaf node are: If the operation is "merge" or "replace", the node is created if it does not exist, and its value is set to the value found in the XML RPC data. @@ -3038,33 +3015,33 @@ The values in a leaf-list MUST be unique. Conceptually, the values in the data tree are always in the canonical form (see Section 9.1). 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 device is + 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 device + "description" string for the list may suggest an order to the server implementor. YANG calls this style of list "system ordered" and they are indicated with the statement "ordered-by system". For example, a list of valid users would typically be sorted alphabetically, since the order in which the users appeared in the configuration would not impact the creation of those users' accounts. In the other style of lists, the order of list entries matters for the implementation of the list's configuration and the user is - responsible for ordering the entries, while the device maintains that + responsible for ordering the entries, while the server maintains that order. YANG calls this style of list "user ordered" and they are indicated with the statement "ordered-by user". For example, the order in which packet filters entries are applied to incoming traffic may affect how that traffic is filtered. The user would need to decide if the filter entry that discards all TCP traffic should be applied before or after the filter entry that allows all traffic from trusted interfaces. The choice of order would be crucial. @@ -3074,21 +3051,22 @@ 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: + 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. o Otherwise, the default values MUST be used if the ancestor node @@ -3143,21 +3120,21 @@ 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 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 @@ -3180,26 +3157,27 @@ 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 unspecified order. - Thus, an implementation is free to sort the entries in the most - appropriate order. An implementation SHOULD use the same order for - the same data, regardless of how the data were created. Using a - deterministic order will make comparisons possible using simple tools - like "diff". + The entries in the list are sorted 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". 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. 7.7.8. XML Encoding Rules @@ -3798,26 +3776,27 @@ The "default" statement indicates if a case should be considered as the default if no child nodes from any of the choice's cases exist. The argument is the identifier of the "case" statement. If the "default" statement is missing, there is no default case. The "default" statement MUST NOT be present on choices where "mandatory" is true. The default case is only important when considering the default - values of nodes under the cases. The default values for nodes under - the default case are used if none of the nodes under any of the cases - are present. + 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.1) directly under - the default case. + There MUST NOT be any mandatory nodes (Section 3) directly under the + default case. Default values for child nodes under a case are only used if one of the nodes under that case is present, or if that case is the default case. If none of the nodes under a case are present and the case is not the default case, the default values of the cases' child nodes are ignored. In this example, the choice defaults to "interval", and the default value will be used if none of "daily", "time-of-day", or "manual" are present. If "daily" is present, the default value for "time-of-day" @@ -3854,21 +3833,21 @@ 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 which 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 Otherwise, it is enforced if the ancestor node exists. The constraint is further enforced according to the rules in Section 8. @@ -3935,21 +3914,21 @@ 7.10. The anydata Statement The "anydata" statement defines an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed anydata information. The "anydata" statement is used to represent an unknown set of nodes that can be modelled with YANG. An example of where this can be useful is a list of received notifications, where the exact - notifications are not known as design time. + 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 @@ -3983,25 +3962,25 @@ An anydata node is treated as an opaque chunk of data. This data can be modified in its entirety only. Any "operation" attributes present on subelements of an anydata node are ignored by the NETCONF server. When a NETCONF server processes an request, the elements of procedure for the anydata node are: If the operation is "merge" or "replace", the node is created if - it does not exist, and its value is set to the subelements to the + it does not exist, and its value is set to the subelements of the anydata node found in the XML RPC data. If the operation is "create", the node is created if it does not - exist, and its value is set to the subelements to the anydata node + exist, and its value is set to the subelements of the anydata node found in the XML RPC data. If the node already exists, a "data-exists" error is returned. If the operation is "delete", the node is deleted if it exists. If the node does not exist, a "data-missing" error is returned. 7.10.4. Usage Example Given the following "anydata" statement: @@ -4033,21 +4012,21 @@ 7.11. The anyxml Statement The "anyxml" statement defines an interior node in the schema tree. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed anyxml information. The "anyxml" statement is used to represent an unknown chunk of XML. No restrictions are placed on the XML. This can be useful, for example, in RPC replies. An example is the parameter in the - operation. + 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. It should be noted that in YANG version 1, anyxml was the only @@ -4103,35 +4082,35 @@ found in the XML RPC data. If the node already exists, a "data-exists" error is returned. If the operation is "delete", the node is deleted if it exists. If the node does not exist, a "data-missing" error is returned. 7.11.4. Usage Example Given the following "anyxml" statement: - anyxml data; + anyxml html-info; The following are two valid encodings of the same anyxml value: - - - 1 - - + +

+ This is very cool. +

+ - - - 1 - - + + + This is very cool. + + 7.12. The grouping Statement The "grouping" statement is used to define a reusable block of nodes, which may be used locally in the module or submodule, and by other modules that import from it, according to the rules in Section 5.5. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed grouping information. @@ -4330,23 +4309,21 @@ leaf ip { // illegal - same identifier "ip" used twice type string; } } 7.14. The rpc Statement The "rpc" statement is used to define an RPC operation. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed rpc information. This argument is - the name of the RPC, and is used as the element name directly under - the element, as designated by the substitution group - "rpcOperation" in [RFC6241]. + the name of the RPC. The "rpc" statement defines an rpc node in the schema tree. Under the rpc node, a schema node with the name "input", and a schema node with the name "output" are also defined. The nodes "input" and "output" are defined in the module's namespace. 7.14.1. The rpc's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | @@ -4444,26 +4421,26 @@ | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.14.4. XML Encoding Rules +7.14.4. NETCONF XML Encoding Rules - An rpc node is encoded as a child XML element to the element - defined in [RFC6241]. The element's local name is the rpc's - identifier, and its namespace is the module's XML namespace (see - Section 7.1.3). + An rpc node is encoded as a child XML element to the element, + as designated by the substitution group "rpcOperation" in [RFC6241]. + The element's local name is the rpc's identifier, and its namespace + is the module's XML namespace (see Section 7.1.3). Input parameters are encoded as child XML elements to the rpc node's XML element, in the same order as they are defined within the "input" statement. If the RPC operation invocation succeeded, and no output parameters are returned, the contains a single element defined in [RFC6241]. If output parameters are returned, they are encoded as child elements to the element defined in [RFC6241], in the same order as they are defined within the "output" statement. @@ -4537,21 +4514,21 @@ | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | input | 7.14.2 | 0..1 | | output | 7.14.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+ -7.15.2. XML Encoding Rules +7.15.2. NETCONF XML Encoding Rules When an action is invoked, an element with the local name "action" in the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is encoded as a child XML element to the element defined in [RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241]. The "action" element contains an hierarchy of nodes that identifies the node in the datastore. It MUST contain all containers and list nodes from the top level down to the list or container containing the @@ -4688,21 +4665,21 @@ | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.16.2. XML Encoding Rules +7.16.2. NETCONF XML Encoding Rules A notification node that is defined on the top-level of a module is encoded as a child XML element to the element defined in NETCONF Event Notifications [RFC5277]. The element's local name is the notification's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). When a notification node is defined as a child to a data node, the element defined in NETCONF Event Notifications [RFC5277] contains an hierarchy of nodes that identifies the node in @@ -4811,21 +4788,21 @@ If the target node is a container, list, case, input, output, or notification node, the "container", "leaf", "list", "leaf-list", "uses", and "choice" statements can be used within the "augment" statement. If the target node is a choice node, the "case" statement, or a case shorthand statement (see Section 7.9.2) can be used within the "augment" statement. If the target node is in another module, then nodes added by the - augmentation MUST NOT be mandatory nodes (see Section 3.1). + augmentation MUST NOT be mandatory nodes (see Section 3). The "augment" statement MUST NOT add multiple nodes with the same name from the same module to the target node. 7.17.1. The augment's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | action | 7.15 | 0..n | @@ -5122,70 +5099,70 @@ This section defines statements related to conformance, as described in Section 5.6. 7.20.1. The feature Statement The "feature" statement is used to define a mechanism by which portions of the schema are marked as conditional. A feature name is defined that can later be referenced using the "if-feature" statement (see Section 7.20.2). Schema nodes tagged with an "if-feature" - statement are ignored by the device unless the device supports the + statement are ignored by the server unless the server supports the given feature expression. This allows portions of the YANG module to - be conditional based on conditions on the device. The model can - represent the abilities of the device within the model, giving a - richer model that allows for differing device abilities and roles. + be conditional based on conditions in the server. The model can + represent the abilities of the server within the model, giving a + richer model that allows for differing server abilities and roles. The argument to the "feature" statement is the name of the new feature, and follows the rules for identifiers in Section 6.2. This name is used by the "if-feature" statement to tie the schema nodes to the feature. In this example, a feature called "local-storage" represents the - ability for a device to store syslog messages on local storage of + ability for a server to store syslog messages on local storage of some sort. This feature is used to make the "local-storage-limit" leaf conditional on the presence of some sort of local storage. If - the device does not report that it supports this feature, the + the server does not report that it supports this feature, the "local-storage-limit" node is not supported. module syslog { ... feature local-storage { description - "This feature means the device supports local + "This feature means the server supports local storage (memory, flash or disk) that can be used to store syslog messages."; } container syslog { leaf local-storage-limit { if-feature local-storage; type uint64; units "kilobyte"; config false; description "The amount of local storage that can be used to hold syslog messages."; } } } The "if-feature" statement can be used in many places within the YANG syntax. Definitions tagged with "if-feature" are ignored when the - device does not support that feature. + server does not support that feature. A feature MUST NOT reference itself, neither directly nor indirectly through a chain of other features. - In order for a device to implement a feature that is dependent on any + In order for a server to implement a feature that is dependent on any other features (i.e., the feature has one or more "if-feature" - substatements), the device MUST also implement all the dependant + substatements), the server MUST also implement all the dependant features. 7.20.1.1. The feature's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | status | 7.21.2 | 0..1 | @@ -5221,69 +5198,69 @@ server. container target { if-feature "outbound-tls or outbound-ssh"; ... } 7.20.3. The deviation Statement The "deviation" statement defines a hierarchy of a module that the - device does not implement faithfully. The argument is a string that + server does not implement faithfully. The argument is a string that identifies the node in the schema tree where a deviation from the module occurs. This node is called the deviation's target node. The contents of the "deviation" statement give details about the deviation. The argument string is an absolute schema node identifier (see Section 6.5). - Deviations define the way a device or class of devices deviate from a + Deviations define the way a server or class of servers deviate from a standard. This means that deviations MUST never be part of a published standard, since they are the mechanism for learning how implementations vary from the standards. - Device deviations are strongly discouraged and MUST only be used as a - last resort. Telling the application how a device fails to follow a + Server deviations are strongly discouraged and MUST only be used as a + last resort. Telling the application how a server fails to follow a standard is no substitute for implementing the standard correctly. A - device that deviates from a module is not fully compliant with the + server that deviates from a module is not fully compliant with the module. However, in some cases, a particular device may not have the hardware or software ability to support parts of a standard module. When this - occurs, the device makes a choice either to treat attempts to + 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 devices to document portions of a base module + 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. 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 | +--------------+----------+-------------+ 7.20.3.2. The deviate Statement - The "deviate" statement defines how the device's implementation of + The "deviate" statement defines how the server's implementation of the target node deviates from its original definition. The argument is one of the strings "not-supported", "add", "replace", or "delete". The argument "not-supported" indicates that the target node is not - implemented by this device. + implemented by this server. The argument "add" adds properties to the target node. The properties to add are identified by substatements to the "deviate" statement. If a property can only appear once, the property MUST NOT exist in the target node. The argument "replace" replaces properties of the target node. The properties to replace are identified by substatements to the "deviate" statement. The properties to replace MUST exist in the target node. @@ -5309,76 +5286,74 @@ +--------------+-------------+-------------+ The deviate's Substatements If the target node has a property defined by an extension, this property can be deviated if the extension allows deviations. See Section 7.19 for details. 7.20.3.3. Usage Example - In this example, the device is informing client applications that it + In this example, the server is informing client applications that it does not support the "daytime" service in the style of RFC 867. deviation /base:system/base:daytime { deviate not-supported; } - The following example sets a device-specific default value to a leaf + The following example sets a server-specific default value to a leaf that does not have a default value defined: deviation /base:system/base:user/base:type { deviate add { default "admin"; // new users are 'admin' by default } } - In this example, the device limits the number of name servers to 3: + In this example, the server limits the number of name servers to 3: deviation /base:system/base:name-server { deviate replace { max-elements 3; } } If the original definition is: container system { must "daytime or time"; ... } - a device might remove this must constraint by doing: + a server might remove this must constraint by doing: deviation "/base:system" { deviate delete { must "daytime or time"; } } 7.21. Common Statements This section defines substatements common to several other statements. 7.21.1. The config Statement The "config" statement takes as an argument the string "true" or "false". If "config" is "true", the definition represents - configuration. Data nodes representing configuration will be part of - the reply to a request, and can be sent in a - or request. + configuration. Data nodes representing configuration are part of + configuration datastores. If "config" is "false", the definition represents state data. Data - nodes representing state data will be part of the reply to a , - but not to a request, and cannot be sent in a - or request. + nodes representing state data are not part of configuration + datastores. If "config" is not specified, the default is the same as the parent schema node's "config" value. If the parent node is a "case" node, the value is the same as the "case" node's parent "choice" node. If the top node does not specify a "config" statement, the default is "true". If a node has "config" set to "false", no node underneath it can have "config" set to "true". @@ -5458,83 +5433,89 @@ See Section 8.2.2 for additional information. The XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o If the "when" statement is a child of an "augment" statement, then the context node is the augment's target node in the data tree, if the target node is a data node. Otherwise, the context node is the closest ancestor node to the target node that is also a data - node. + node. If no such node exists, the context node is the root node. + The accessible tree is tentatively altered during the processing + of the XPath expression by removing all instances (if any) of the + nodes added by the "augment" statement. o If the "when" statement is a child of a "uses", "choice", or "case" statement, then the context node is the closest ancestor node to the "uses", "choice", or "case" node that is also a data node. If no such node exists, the context node is the root node. + The accessible tree is tentatively altered during the processing + of the XPath expression by removing all instances (if any) of the + nodes added by the "uses", "choice", or "case" statement. o If the "when" statement is a child of any other data definition statement, the accessible tree is tentatively altered during the - processing of the XPath expression by replacing all instances (if - any) of the data node for which the "when" statement is defined - with a single dummy node with the same name, but with no value and - no children. The context node is this dummy node. + 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. Note that the XPath expression is conceptually evaluated. This means - that an implementation does not have to use an XPath evaluator on the - device. The "when" statement can very well be implemented with + 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 Several YANG statements define constraints on valid data. These constraints are enforced in different ways, depending on what type of data the statement defines. o If the constraint is defined on configuration data, it MUST be true in a valid configuration data tree. o If the constraint is defined on state data, it MUST be true in a valid state data tree. o If the constraint is defined on notification content, it MUST be - true in any notification instance data tree. + true in any notification data tree. o If the constraint is defined on RPC or action input parameters, it MUST be true in an invocation of the RPC or action operation. o If the constraint is defined on RPC or action output parameters, it MUST be true in the RPC or action reply. The following properties are true in all data trees: o All leaf data values MUST match the type constraints for the leaf, including those defined in the type's "range", "length", and "pattern" properties. o All key leafs MUST be present for all list entries. o Nodes MUST be present for at most one case branch in all choices. o There MUST be no nodes tagged with "if-feature" present if the - "if-feature" expression evaluates to "false" on the device. + "if-feature" expression evaluates to "false" in the server. o There MUST be no nodes tagged with "when" present if the "when" condition evaluates to "false" in the data tree. The following properties are true in a valid data tree: o All "must" constraints MUST evaluate to "true". o All referential integrity constraints defined via the "path" statement MUST be satisfied. @@ -5556,37 +5537,37 @@ o during processing of NETCONF operations o during validation Each of these scenarios is considered in the following sections. 8.2.1. Payload Parsing When content arrives in RPC payloads, it MUST be well-formed XML, following the hierarchy and content rules defined by the set of - models the device implements. + models the server implements. o If a leaf data value does not match the type constraints for the leaf, including those defined in the type's "range", "length", and "pattern" properties, the server MUST reply with an "invalid-value" error-tag in the rpc-error, and with the error- app-tag and error-message associated with the constraint, if any exist. o If all keys of a list entry are not present, the server MUST reply with a "missing-element" error-tag in the rpc-error. o If data for more than one case branch of a choice is present, the server MUST reply with a "bad-element" in the rpc-error. o If data for a node tagged with "if-feature" is present, and the - if-feature expression evaluates to "false" on the device, the + if-feature expression evaluates to "false" in the server, the server MUST reply with an "unknown-element" error-tag in the rpc- error. o If data for a node tagged with "when" is present, and the "when" condition evaluates to "false", the server MUST reply with an "unknown-element" error-tag in the rpc-error. o For insert handling, if the value for the attributes "before" and "after" are not valid for the type of the appropriate key leafs, the server MUST reply with a "bad-attribute" error-tag in the rpc- @@ -5603,20 +5584,24 @@ datastore. During this processing, the following errors MUST be detected: o Delete requests for non-existent data. o Create requests for existent data. o Insert requests with "before" or "after" parameters that do not exist. + o Modification requests for nodes tagged with "when", and the "when" + condition evaluates to "false". In this case the server MUST + reply with an "unknown-element" error-tag in the rpc-error. + During processing: o If the NETCONF operation creates data nodes under a "choice", any existing nodes from other "case" branches are deleted by the server. o If the NETCONF operation modifies a data node such that any node's "when" expression becomes false, then the node with the "when" expression is deleted by the server. @@ -5639,36 +5624,41 @@ Additional types may be defined, derived from those built-in types or from other derived types. Derived types may use subtyping to formally restrict the set of possible values. The different built-in types and their derived types allow different kinds of subtyping, namely length and regular expression restrictions of strings (Section 9.4.4, Section 9.4.5) and range restrictions of numeric types (Section 9.2.4). The lexical representation of a value of a certain type is used in - the NETCONF messages and when specifying default values and numerical + the XML encoding and when specifying default values and numerical ranges in YANG modules. 9.1. Canonical Representation For most types, there is a single canonical representation of the type's values. Some types allow multiple lexical representations of the same value, for example, the positive integer "17" can be represented as "+17" or "17". Implementations MUST support all lexical representations specified in this document. - When a NETCONF server sends data, it MUST be in the canonical form. + When a server sends data encoded in XML, it MUST use the canonical + form defined in this section. Other encodings may introduce + alternate representations. Note, however, that values in the data + tree are conceptually stored in the canonical representation as + defined in this section. In particular, any XPath expression + evaluations are done using the canonical form. - Some types have a lexical representation that depends on the XML - context in which they occur. These types do not have a canonical - form. + Some types have a lexical representation that depends on the + encoding, e.g., the XML context in which they occur. These types do + not have a canonical form. 9.2. The Integer Built-In Types The integer built-in types are int8, int16, int32, int64, uint8, uint16, uint32, and uint64. They represent signed and unsigned integers of different sizes: int8 represents integer values between -128 and 127, inclusively. int16 represents integer values between -32768 and 32767, @@ -5699,23 +5689,23 @@ For convenience, when specifying a default value for an integer in a YANG module, an alternative lexical representation can be used, which represents the value in a hexadecimal or octal notation. The hexadecimal notation consists of an optional sign ("+" or "-"), the characters "0x" followed a number of hexadecimal digits, where letters may be uppercase or lowercase. The octal notation consists of an optional sign ("+" or "-"), the character "0" followed a number of octal digits. Note that if a default value in a YANG module has a leading zero - ("0"), it is interpreted as an octal number. In the XML instance - documents, an integer is always interpreted as a decimal number, and - leading zeros are allowed. + ("0"), it is interpreted as an octal number. In the XML encoding, an + integer is always interpreted as a decimal number, and leading zeros + are allowed. Examples: // legal values +4711 // legal positive value 4711 // legal positive value -123 // legal negative value 0xf00f // legal positive hexadecimal value -0xf // legal negative hexadecimal value 052 // legal positive octal value @@ -5869,21 +5859,21 @@ The string built-in type represents human-readable strings in YANG. Legal characters 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 string syntax is formally defined by the rule "yang-string" in Section 14. 9.4.1. Lexical Representation A string value is lexically represented as character data in the XML - instance documents. + encoding. 9.4.2. Canonical Form The canonical form is the same as the lexical representation. No Unicode normalization is performed of string values. 9.4.3. Restrictions A string can be restricted with the "length" (Section 9.4.4) and "pattern" (Section 9.4.5) statements. @@ -5949,20 +5938,26 @@ +---------------+---------+-------------+ | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | | modifier | 9.4.6 | 0..1 | | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ 9.4.6. The modifier Statement + The "modifier" statement, which is an optional substatement to the + "pattern" statement, takes as an argument the string "invert-match". + + If a pattern has the "invert-match" modifier present, the type is + restricted to values that do not match the pattern. + 9.4.7. Usage Example With the following typedef: typedef my-base-str-type { type string { length "1..255"; } } @@ -6249,21 +6243,21 @@ disable-nagle ten-mb-only 9.8. The binary Built-In Type The binary built-in type represents any binary data, i.e., a sequence of octets. 9.8.1. Restrictions - A binary can be restricted with the "length" (Section 9.4.4) + A binary type can be restricted with the "length" (Section 9.4.4) statement. The length of a binary value is the number of octets it contains. 9.8.2. Lexical Representation Binary values are encoded with the base64 encoding scheme (see [RFC4648], Section 4). 9.8.3. Canonical Form @@ -6339,21 +6333,22 @@ If "require-instance" is "true", it means that the instance being referred MUST exist for the data to be valid. This constraint is enforced according to the rules in Section 8. If "require-instance" is "false", it means that the instance being referred MAY exist in valid data. 9.9.4. Lexical Representation - A leafref value is encoded the same way as the leaf it references. + A leafref value is lexically represented the same way as the leaf it + references. 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: @@ -6520,24 +6515,24 @@ imported with that prefix. Otherwise, an identity with the matching name MUST be defined in the current module or an included submodule. Valid values for an identityref are any identities derived from all the identityref's base identities. On a particular server, the valid values are further restricted to the set of identities defined in the modules implemented by the server. 9.10.3. Lexical Representation - An identityref is encoded as the referred identity's qualified name - as defined in [XML-NAMES]. If the prefix is not present, the - namespace of the identityref is the default namespace in effect on - the element that contains the identityref value. + An identityref is lexically represented as the referred identity's + qualified name as defined in [XML-NAMES]. If the prefix is not + present, the namespace of the identityref is the default namespace in + effect on the element that contains the identityref value. When an identityref is given a default value using the "default" statement, the identity name in the default value MAY have a prefix. If a prefix is present on the identity name, it refers to an identity defined in the module that was imported with that prefix, or the prefix for the current module if the identity is defined in the current module or one of its submodules. Otherwise, an identity with the matching name MUST be defined in the current module or one of its submodules. @@ -6642,24 +6637,25 @@ 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 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. - 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. + 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. 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 @@ -7047,24 +7043,30 @@ statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, since all XML elements are qualified by the namespace. Obsolete definitions MUST NOT be removed from modules since their identifiers may still be referenced by other modules. A definition may be revised in any of the following ways: o An "enumeration" type may have new enums added, provided the old - enums's values do not change. + enums's values do not change. Note that inserting a new enum + before an existing enum or reordering existing enums will result + in new values for the existing enums, unless they have explicit + values assigned to them. o A "bits" type may have new bits added, provided the old bit - positions do not change. + positions do not change. Note that inserting a new bit before an + existing bit or reordering existing bit will result in new + positions for the existing bits, unless they have explicit + positions assigned to them. o A "range", "length", or "pattern" statement may expand the allowed value space. o A "default" statement may be added to a leaf that does not have a default value (either directly or indirectly through its type). o A "units" statement may be added. o A "reference" statement may be added or updated. @@ -7085,32 +7087,32 @@ 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 - mandatory nodes (Section 3.1) to existing nodes or at the top - level in a module or submodule, or if they are conditionally - dependent on a new feature (i.e., have an "if-feature" statement - that refers to a new feature). + mandatory nodes (Section 3) to existing nodes or at the top level + in a module or submodule, or if they are conditionally dependent + on a new feature (i.e., have an "if-feature" statement that refers + to a new feature). o A new "case" statement may be added. o A node that represented state data may be changed to represent - configuration, provided it is not mandatory (Section 3.1). + configuration, provided it is not mandatory (Section 3). o An "if-feature" statement may be removed, provided its node is not - mandatory (Section 3.1). + mandatory (Section 3). o A "status" statement may be added, or changed from "current" to "deprecated" or "obsolete", or from "deprecated" to "obsolete". o A "type" statement may be replaced with another "type" statement that does not change the syntax or semantics of the type. For example, an inline type definition may be replaced with a typedef, but an int8 type cannot be replaced by an int16, since the syntax would change. @@ -7215,21 +7217,21 @@ Substatements of a YANG statement are represented as (additional) children of the keyword element and their relative order MUST be the same as the order of substatements in YANG. Comments in YANG MAY be mapped to XML comments. +------------------+---------------+-------------+ | keyword | argument name | yin-element | +------------------+---------------+-------------+ | action | name | false | - | anydata | 7.10 | 0..n | + | anydata | name | false | | anyxml | name | false | | argument | name | false | | augment | target-node | false | | base | name | false | | belongs-to | module | false | | bit | name | false | | case | name | false | | choice | name | false | | config | value | false | | contact | text | true | @@ -7251,20 +7253,21 @@ | include | module | false | | input | | n/a | | key | value | false | | leaf | name | false | | leaf-list | name | false | | length | value | false | | list | name | false | | mandatory | value | false | | max-elements | value | false | | min-elements | value | false | + | modifier | value | false | | module | name | false | | must | condition | false | | namespace | uri | false | | notification | name | false | | ordered-by | value | false | | organization | text | true | | output | | n/a | | path | value | false | | pattern | value | false | | position | value | false | @@ -8407,23 +8410,23 @@ identifier-ref-arg = identifier-ref identifier-ref = [prefix ":"] identifier string = < an unquoted string as returned by > < the scanner, that matches the rule > < yang-string > yang-string = *yang-char - ;; any Unicode character including tab, carriage return, and line - ;; feed, but excluding the other C0 control characters, the surrogate - ;; blocks, and the noncharacters. + ;; any Unicode or ISO/IEC 10646 character including tab, carriage + ;; return, and line feed, but excluding the other C0 control + ;; characters, the surrogate blocks, and the noncharacters. yang-char = %x9 / %xA / %xD / %x20-D7FF / ; exclude surrogate blocks %xD800-DFFF %xE000-FDCF / ; exclude noncharacters %xFDD0-FDEF %xFDF0-FFFD / ; exclude noncharacters %xFFFE-FFFF %x10000-1FFFD / ; exclude noncharacters %x1FFFE-1FFFF %x20000-2FFFD / ; exclude noncharacters %x2FFFE-2FFFF %x30000-3FFFD / ; exclude noncharacters %x3FFFE-3FFFF %x40000-4FFFD / ; exclude noncharacters %x4FFFE-4FFFF %x50000-5FFFD / ; exclude noncharacters %x5FFFE-5FFFF %x60000-6FFFD / ; exclude noncharacters %x6FFFE-6FFFF @@ -8660,80 +8663,84 @@ 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, and Bert Wijnen. 20. ChangeLog RFC Editor: remove this section upon publication as an RFC. -20.1. Version -07 +20.1. Version -08 + + o Fixes after WGLC reviews. + +20.2. Version -07 o Fixes after WG review. o Included solution Y60-01. -20.2. Version -06 +20.3. Version -06 o Included solution Y45-05. -20.3. Version -05 +20.4. Version -05 o Included solution Y18-01. o Included solution Y25-02 (parts of it was included in -04). o Included solution Y34-05. o Included solution Y36-03. -20.4. Version -04 +20.5. Version -04 o Incorporated changes to ABNF grammar after review and errata for RFC 6020. o Included solution Y16-03. o Included solution Y49-04. o Included solution Y58-01. o Included solution Y59-01. -20.5. Version -03 +20.6. Version -03 o Incorporated changes from WG reviews. o Included solution Y05-01. o Included solution Y10-01. o Included solution Y13-01. o Included solution Y28-02. o Included solution Y55-01 (parts of it was included in -01). -20.6. Version -02 +20.7. Version -02 o Included solution Y02-01. o Included solution Y04-02. o Included solution Y11-01. o Included solution Y41-01. o Included solution Y56-01. -20.7. Version -01 +20.8. Version -01 o Included solution Y01-01. o Included solution Y03-01. o Included solution Y06-02. o Included solution Y07-01. o Included solution Y14-01. @@ -8743,21 +8750,21 @@ o Included solution Y23-01. o Included solution Y29-01. o Included solution Y30-01. o Included solution Y31-01. o Included solution Y35-01. -20.8. Version -00 +20.9. Version -00 o Applied all reported errata for RFC 6020. o Updated YANG version to 1.1, and made the "yang-version" statement mandatory. 21. References 21.1. Normative References @@ -8843,20 +8850,25 @@ [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation Structure of Management Information", RFC 3780, May 2004. [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC Series and RFC Editor", RFC 4844, July 2007. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. + [RFC6643] Schoenwaelder, J., "Translation of Structure of Management + Information Version 2 (SMIv2) MIB Modules to YANG + Modules", RFC 6643, DOI 10.17487/RFC6643, July 2012, + . + [XPATH2.0] Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., Robie, J., and J. Simeon, "XML Path Language (XPath) 2.0", World Wide Web Consortium Recommendation REC-xpath20-20070123, January 2007, . [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999,