--- 1/draft-ietf-netmod-rfc6020bis-09.txt 2016-02-04 01:18:05.472101164 -0800 +++ 2/draft-ietf-netmod-rfc6020bis-10.txt 2016-02-04 01:18:06.328122442 -0800 @@ -1,18 +1,18 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Intended status: Standards Track December 11, 2015 -Expires: June 13, 2016 +Intended status: Standards Track February 4, 2016 +Expires: August 7, 2016 The YANG 1.1 Data Modeling Language - draft-ietf-netmod-rfc6020bis-09 + draft-ietf-netmod-rfc6020bis-10 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,25 +22,25 @@ 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 June 13, 2016. + This Internet-Draft will expire on August 7, 2016. Copyright Notice - Copyright (c) 2015 IETF Trust and the persons identified as the + Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -54,318 +54,317 @@ Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may 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 . . . . . . . . . . . . 9 + 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 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.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 + 4.2.10. Notification Definitions . . . . . . . . . . . . . . 28 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 5.1.1. Import and Include by Revision . . . . . . . . . . . 29 - 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 30 - 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 31 + 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 31 + 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 32 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.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 33 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 33 - 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 + 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 34 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 . . . . 37 - 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 38 - 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38 + 5.6.5. Announcing Conformance Information in NETCONF . . . . 38 + 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 39 + 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 39 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 39 - 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 39 - 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39 + 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 40 + 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 40 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 . . . . . . . . . . . . . . . . . . . . 42 - 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 43 - 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 48 - 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 48 - 7.1. The module Statement . . . . . . . . . . . . . . . . . . 49 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 49 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 50 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 51 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 51 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 51 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 52 - 7.1.7. The organization Statement . . . . . . . . . . . . . 53 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 53 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 53 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 54 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 55 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 56 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 56 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 57 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 57 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 58 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 58 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 58 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 58 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 59 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 59 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 59 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 59 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 60 - 7.5.2. The container's Substatements . . . . . . . . . . . . 60 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 61 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 62 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 63 - 7.5.6. The container's Child Node Statements . . . . . . . . 63 - 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 63 - 7.5.8. NETCONF Operations . . . . . . . . . . 64 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 64 - 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 . . . . . . . . . . . . . . 67 - 7.6.4. The leaf's default Statement . . . . . . . . . . . . 67 - 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 67 - 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 68 - 7.6.7. NETCONF Operations . . . . . . . . . . 68 - 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 68 - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 69 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 69 - 7.7.2. The leaf-list's default values . . . . . . . . . . . 70 - 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 71 - 7.7.4. The leaf-list's default Statement . . . . . . . . . . 71 - 7.7.5. The min-elements Statement . . . . . . . . . . . . . 72 - 7.7.6. The max-elements Statement . . . . . . . . . . . . . 72 - 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 72 - 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 73 - 7.7.9. NETCONF Operations . . . . . . . . . . 73 - 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 74 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 76 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 76 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 77 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 78 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 79 - 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 79 - 7.8.6. NETCONF Operations . . . . . . . . . . 80 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 81 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 84 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 84 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 85 - 7.9.3. The choice's default Statement . . . . . . . . . . . 86 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 88 - 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 88 - 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 88 - 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 89 - 7.10.1. The anydata's Substatements . . . . . . . . . . . . 90 - 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 90 - 7.10.3. NETCONF Operations . . . . . . . . . . 90 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 91 - 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 91 - 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 92 - 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 - 7.11.3. NETCONF Operations . . . . . . . . . . 92 - 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 93 - 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 93 - 7.12.1. The grouping's Substatements . . . . . . . . . . . . 94 - 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 95 - 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 95 - 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 95 - 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 96 - 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 97 - 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 97 - 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 98 - 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 98 - 7.14.2. The input Statement . . . . . . . . . . . . . . . . 99 - 7.14.3. The output Statement . . . . . . . . . . . . . . . . 100 - 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 101 - 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 101 - 7.15. The action Statement . . . . . . . . . . . . . . . . . . 102 - 7.15.1. The action's Substatements . . . . . . . . . . . . . 102 - 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 103 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 103 - 7.16. The notification Statement . . . . . . . . . . . . . . . 105 - 7.16.1. The notification's Substatements . . . . . . . . . . 106 - 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 106 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 - 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 108 - 7.17.1. The augment's Substatements . . . . . . . . . . . . 110 - 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 111 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 111 - 7.18. The identity Statement . . . . . . . . . . . . . . . . . 113 - 7.18.1. The identity's Substatements . . . . . . . . . . . . 113 - 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 113 - 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 114 - 7.19. The extension Statement . . . . . . . . . . . . . . . . . 115 - 7.19.1. The extension's Substatements . . . . . . . . . . . 115 - 7.19.2. The argument Statement . . . . . . . . . . . . . . . 115 - 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 - 7.20. Conformance-Related Statements . . . . . . . . . . . . . 117 - 7.20.1. The feature Statement . . . . . . . . . . . . . . . 117 - 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 119 - 7.20.3. The deviation Statement . . . . . . . . . . . . . . 119 - 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 123 - 7.21.1. The config Statement . . . . . . . . . . . . . . . . 123 - 7.21.2. The status Statement . . . . . . . . . . . . . . . . 123 - 7.21.3. The description Statement . . . . . . . . . . . . . 124 - 7.21.4. The reference Statement . . . . . . . . . . . . . . 124 - 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 124 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 126 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 126 - 8.2. Configuration Data Modifications . . . . . . . . . . . . 127 - 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 127 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 127 - 8.3.2. NETCONF Processing . . . . . . . . . . 128 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 128 - 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 129 - 9.1. Canonical Representation . . . . . . . . . . . . . . . . 129 - 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 129 - 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 130 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 131 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 131 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 131 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 132 - 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 132 - 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 132 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 133 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 133 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 133 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 134 - 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 134 - 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 134 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 134 - 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 135 - 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 136 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 136 - 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 137 - 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 137 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 137 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 - 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 138 - 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 138 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 138 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 138 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 139 - 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 141 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 141 - 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 141 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 141 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 141 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 142 - 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 144 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 144 - 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 144 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 144 - 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 144 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 144 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 145 - 9.9.3. The require-instance Statement . . . . . . . . . . . 145 - 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 146 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 146 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 146 - 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 149 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149 - 9.10.2. The identityref's base Statement . . . . . . . . . . 149 - 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 150 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 150 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 150 - 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 152 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 152 - 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 152 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 152 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 152 - 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 152 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 153 - 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 153 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 153 - 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 153 - 9.13. The instance-identifier Built-In Type . . . . . . . . . . 154 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 155 - 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 155 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 155 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 155 - 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 156 - 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 156 - 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 156 - 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 157 - 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 157 + 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 42 + 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 43 + 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 43 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 43 + 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 44 + 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 49 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 49 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 50 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 50 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 51 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 52 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 52 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 52 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 54 + 7.1.7. The organization Statement . . . . . . . . . . . . . 54 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 54 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 55 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 55 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 56 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 57 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 58 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 59 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 59 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 60 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 60 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 60 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 60 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 61 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 61 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 61 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 61 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 62 + 7.5.2. The container's Substatements . . . . . . . . . . . . 62 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 63 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 64 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 65 + 7.5.6. The container's Child Node Statements . . . . . . . . 65 + 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 65 + 7.5.8. NETCONF Operations . . . . . . . . . . 66 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 66 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 67 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 67 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 68 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 69 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 69 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 69 + 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 70 + 7.6.7. NETCONF Operations . . . . . . . . . . 70 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 70 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 71 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 71 + 7.7.2. The leaf-list's default values . . . . . . . . . . . 72 + 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 73 + 7.7.4. The leaf-list's default Statement . . . . . . . . . . 73 + 7.7.5. The min-elements Statement . . . . . . . . . . . . . 74 + 7.7.6. The max-elements Statement . . . . . . . . . . . . . 74 + 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 74 + 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 75 + 7.7.9. NETCONF Operations . . . . . . . . . . 75 + 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 76 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 78 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 78 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 79 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 80 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 81 + 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 81 + 7.8.6. NETCONF Operations . . . . . . . . . . 82 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 83 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 86 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 86 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 87 + 7.9.3. The choice's default Statement . . . . . . . . . . . 88 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 90 + 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 90 + 7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 90 + 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 91 + 7.10.1. The anydata's Substatements . . . . . . . . . . . . 92 + 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92 + 7.10.3. NETCONF Operations . . . . . . . . . . 92 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 93 + 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 93 + 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 94 + 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 94 + 7.11.3. NETCONF Operations . . . . . . . . . . 94 + 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 95 + 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 95 + 7.12.1. The grouping's Substatements . . . . . . . . . . . . 96 + 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 97 + 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 97 + 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 97 + 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 98 + 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 99 + 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 99 + 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 100 + 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 100 + 7.14.2. The input Statement . . . . . . . . . . . . . . . . 101 + 7.14.3. The output Statement . . . . . . . . . . . . . . . . 102 + 7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 103 + 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 103 + 7.15. The action Statement . . . . . . . . . . . . . . . . . . 104 + 7.15.1. The action's Substatements . . . . . . . . . . . . . 104 + 7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 105 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 105 + 7.16. The notification Statement . . . . . . . . . . . . . . . 107 + 7.16.1. The notification's Substatements . . . . . . . . . . 108 + 7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 + 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 110 + 7.17.1. The augment's Substatements . . . . . . . . . . . . 112 + 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 113 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 113 + 7.18. The identity Statement . . . . . . . . . . . . . . . . . 115 + 7.18.1. The identity's Substatements . . . . . . . . . . . . 115 + 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 115 + 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 + 7.19. The extension Statement . . . . . . . . . . . . . . . . . 118 + 7.19.1. The extension's Substatements . . . . . . . . . . . 118 + 7.19.2. The argument Statement . . . . . . . . . . . . . . . 118 + 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 + 7.20. Conformance-Related Statements . . . . . . . . . . . . . 120 + 7.20.1. The feature Statement . . . . . . . . . . . . . . . 120 + 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 122 + 7.20.3. The deviation Statement . . . . . . . . . . . . . . 122 + 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 126 + 7.21.1. The config Statement . . . . . . . . . . . . . . . . 126 + 7.21.2. The status Statement . . . . . . . . . . . . . . . . 126 + 7.21.3. The description Statement . . . . . . . . . . . . . 127 + 7.21.4. The reference Statement . . . . . . . . . . . . . . 127 + 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 128 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 129 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 129 + 8.2. Configuration Data Modifications . . . . . . . . . . . . 130 + 8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 130 + 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 130 + 8.3.2. NETCONF Processing . . . . . . . . . . 131 + 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 132 + 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 132 + 9.1. Canonical Representation . . . . . . . . . . . . . . . . 132 + 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 133 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 133 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 134 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 135 + 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 135 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 136 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 136 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 136 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 136 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 + 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 137 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 137 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 138 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 138 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 138 + 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 139 + 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 139 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 139 + 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 141 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 141 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 + 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 141 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 141 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 141 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 143 + 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 144 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 144 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 144 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 145 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 + 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 147 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 147 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 147 + 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 147 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 148 + 9.9.3. The require-instance Statement . . . . . . . . . . . 148 + 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 149 + 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 149 + 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 149 + 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 153 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 153 + 9.10.2. The identityref's base Statement . . . . . . . . . . 153 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 153 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 154 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 154 + 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 155 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 155 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 155 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 155 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 155 + 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 156 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 156 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 156 + 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 156 + 9.13. The instance-identifier Built-In Type . . . . . . . . . . 157 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 + 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 158 + 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 + 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 + 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 159 + 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 159 + 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 159 + 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 160 + 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 160 10.3. Functions for the YANG Types "leafref" and "instance- - identifier" . . . . . . . . . . . . . . . . . . . . . . 157 - 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 157 - 10.4. Functions for the YANG Type "identityref" . . . . . . . 158 - 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 158 - 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 160 - 10.5. Functions for the YANG Type "enumeration" . . . . . . . 160 - 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 160 - 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 161 - 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 161 - 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 162 - 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 164 - 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 - 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 165 - 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 168 - 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 169 - 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 193 - 15.1. Error Message for Data That Violates a unique Statement 193 + identifier" . . . . . . . . . . . . . . . . . . . . . . 161 + 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 161 + 10.4. Functions for the YANG Type "identityref" . . . . . . . 162 + 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 162 + 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 163 + 10.5. Functions for the YANG Type "enumeration" . . . . . . . 164 + 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 164 + 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 165 + 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 165 + 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 166 + 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 168 + 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 + 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 169 + 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 172 + 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 173 + 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 197 + 15.1. Error Message for Data That Violates a unique Statement 197 15.2. Error Message for Data That Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 194 + Statement . . . . . . . . . . . . . . . . . . . . . . . 198 15.3. Error Message for Data That Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 194 - 15.4. Error Message for Data That Violates a must Statement . 194 + Statement . . . . . . . . . . . . . . . . . . . . . . . 198 + 15.4. Error Message for Data That Violates a must Statement . 198 15.5. Error Message for Data That Violates a require-instance - Statement . . . . . . . . . . . . . . . . . . . . . . . 194 - 15.6. Error Message for Data That Does Not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 195 - 15.7. Error Message for Data That Violates a mandatory choice - Statement . . . . . . . . . . . . . . . . . . . . . . . 195 - 15.8. Error Message for the "insert" Operation . . . . . . . . 195 - 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 195 - 17. Security Considerations . . . . . . . . . . . . . . . . . . . 195 - 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 196 - 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 196 - 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 197 - 20.1. Version -09 . . . . . . . . . . . . . . . . . . . . . . 197 - 20.2. Version -08 . . . . . . . . . . . . . . . . . . . . . . 197 - 20.3. Version -07 . . . . . . . . . . . . . . . . . . . . . . 197 - 20.4. Version -06 . . . . . . . . . . . . . . . . . . . . . . 197 - 20.5. Version -05 . . . . . . . . . . . . . . . . . . . . . . 197 - 20.6. Version -04 . . . . . . . . . . . . . . . . . . . . . . 198 - 20.7. Version -03 . . . . . . . . . . . . . . . . . . . . . . 198 - 20.8. Version -02 . . . . . . . . . . . . . . . . . . . . . . 198 - 20.9. Version -01 . . . . . . . . . . . . . . . . . . . . . . 198 - 20.10. Version -00 . . . . . . . . . . . . . . . . . . . . . . 199 - 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 199 - 21.1. Normative References . . . . . . . . . . . . . . . . . . 199 - 21.2. Informative References . . . . . . . . . . . . . . . . . 200 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 201 + Statement . . . . . . . . . . . . . . . . . . . . . . . 199 + 15.6. Error Message for Data That Violates a mandatory choice + Statement . . . . . . . . . . . . . . . . . . . . . . . 199 + 15.7. Error Message for the "insert" Operation . . . . . . . . 199 + 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 199 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 199 + 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 200 + 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 200 + 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 201 + 20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 201 + 20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 201 + 20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 201 + 20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 201 + 20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 201 + 20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 202 + 20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 202 + 20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 202 + 20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 202 + 20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 203 + 20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 203 + 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 203 + 21.1. Normative References . . . . . . . . . . . . . . . . . . 203 + 21.2. Informative References . . . . . . . . . . . . . . . . . 205 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 206 1. Introduction YANG is a data modeling language originally designed to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications [RFC6241]. Since the publication of YANG version 1 [RFC6020], YANG has been used or proposed to be used for other protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI [I-D.vanderstok-core-comi]). Further, other encodings than XML have @@ -391,36 +390,42 @@ o Made noncharacters illegal in the built-in type "string". o Defined the legal characters in YANG modules. o Changed the rules for the interpretation of escaped characters in double quoted strings. This is an backwards incompatible change from YANG version 1. A module that uses a character sequence that is now illegal must change the string to match the new rules. See Section 6.1.3 for details. + o An unquoted string cannot contain any single or double quote + characters. This is an backwards incompatible change from YANG + version 1. + o Extended the "if-feature" syntax to be a boolean expression over feature names. o Allow "if-feature" in "bit", "enum", and "identity". o Allow "if-feature" in "refine". o Made "when" and "if-feature" illegal on list keys. o Allow "choice" as a shorthand case statement (see Section 7.9). o Added a new substatement "modifier" to pattern (see Section 9.4.6). o Allow "must" in "input", "output", and "notification". + o Allow "require-instance" in leafref. + o Allow "augment" to add conditionally mandatory nodes (see Section 7.17). 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). @@ -524,20 +529,22 @@ 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 identity: A globally unique, abstract, and untyped name. + o instance identifier: A mechanism for identifying a particular node in a data tree. o interior node: Nodes within a hierarchy that are not leaf nodes. o leaf: A data node that exists in at most one instance in the data tree. A leaf has a value but no child nodes. o leaf-list: Like the leaf node but defines a set of uniquely identifiable nodes rather than a single node. Each node has a @@ -714,23 +721,23 @@ 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 data nodes for data modeling. In each of - the following subsections, the examples show the YANG syntax as well - as a corresponding XML encoding. + YANG defines four main types of data nodes for data modeling. In + each of the following subsections, the examples show the YANG syntax + as well as a corresponding XML encoding. 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; @@ -833,30 +840,30 @@ Rapun Zell tower The "list" statement is covered in Section 7.8. 4.2.2.5. Example Module These statements are combined to define the module: - // Contents of "acme-system.yang" - module acme-system { + // Contents of "example-system.yang" + module example-system { yang-version 1.1; - namespace "http://acme.example.com/system"; - prefix "acme"; + namespace "urn:example:system"; + prefix "sys"; - organization "ACME Inc."; - contact "joe@acme.example.com"; + organization "Example Inc."; + contact "joe@example.com"; description - "The module for entities implementing the ACME system."; + "The module for entities implementing the Example system."; revision 2007-06-09 { description "Initial revision."; } container system { leaf host-name { type string; description "Hostname for this system"; @@ -1157,29 +1164,29 @@ leaf status { type string; } } } NETCONF XML Example: - - acmefw-2.3 + + example-fw-2.3 - - The image acmefw-2.3 is being installed. + + The image example-fw-2.3 is being installed. YANG Example: list interface { key "name"; leaf name { type string; @@ -1196,32 +1203,34 @@ type uint8; } } } } NETCONF XML Example: - + + eth1 192.0.2.1 + - 60 + xmlns:sys="http://example.com/system"> + 60 The "rpc" statement is covered in Section 7.14, and the "action" statement in Section 7.15. 4.2.10. Notification Definitions YANG allows the definition of notifications. YANG data definition statements are used to model the content of the notification. @@ -1241,21 +1250,21 @@ leaf if-oper-status { type oper-status; } } NETCONF XML Example: 2007-09-01T10:00:00Z - + so-1/2/3.0 up down The "notification" statement is covered in Section 7.16. 5. Language Concepts @@ -1328,32 +1337,32 @@ For submodules, the issue is related but simpler. A module or submodule that includes submodules needs to specify the revision of the included submodules. If a submodule changes, any module or submodule that includes it needs to be updated. For example, module "b" imports module "a". module a { yang-version 1.1; - namespace "http://example.com/a"; + namespace "urn:example:a"; prefix "a"; revision 2008-01-01 { ... } grouping a { leaf eh { .... } } } module b { yang-version 1.1; - namespace "http://example.com/b"; + namespace "urn:example:b"; prefix "b"; import a { prefix "p"; revision-date 2008-01-01; } container bee { uses p:a; } @@ -1373,43 +1382,43 @@ 5.1.2.1. NETCONF XML Encoding NETCONF is capable of carrying any XML content as the payload in the and elements. The top-level nodes of YANG modules are encoded as child elements, in any order, within these elements. This encapsulation guarantees that the corresponding NETCONF messages are always well-formed XML documents. For example: - module my-config { + module example-config { yang-version 1.1; - namespace "http://example.com/schema/config"; + namespace "urn:example:config"; prefix "co"; container system { ... } container routing { ... } } could be encoded in NETCONF as: - + - + 5.2. File Layout YANG modules and submodules are typically stored in files, one module or submodule per file. The name of the file SHOULD be of the form: @@ -1584,33 +1592,39 @@ 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. 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" - [I-D.ietf-netconf-yang-library], and it MUST set the leaf - "conformance" to "import" for this module. + list module C in the "/modules-state/module" list from + "ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set + the leaf "conformance-type" to "import" for this module. + + If a server lists a module C in the "/modules-state/module" list from + "ietf-yang-library", and there are other modules Ms listed that + import C without specifying the revision date of module C, the server + MUST use the definitions from the most recent revision of C listed + for modules Ms. The reason for these rules is that clients need to be able to know the exact data model structure and types of all leafs and leaf-lists implemented in a server. For example, with these modules: module a { yang-version 1.1; - namespace "http://example.com/a"; + namespace "urn:example:a"; prefix "a"; import b { revision-date 2015-01-01; } import c; revision 2015-01-01; feature foo; @@ -1624,21 +1638,21 @@ container a { leaf x { type c:bar; } } } module b { yang-version 1.1; - namespace "http://example.com/b"; + namespace "urn:example:b"; prefix "b"; revision 2015-04-04; revision 2015-01-01; typedef myenum { type enumeration { enum zero; // added in 2015-01-01 enum one; // added in 2015-04-04 } @@ -1636,95 +1650,99 @@ revision 2015-04-04; revision 2015-01-01; typedef myenum { type enumeration { enum zero; // added in 2015-01-01 enum one; // added in 2015-04-04 } } - container x { // added in 2015-01-01 container y; // added in 2015-04-04 } } module c { yang-version 1.1; - namespace "http://example.com/c"; + namespace "urn:example:c"; prefix "c"; revision 2015-03-03; revision 2015-02-02; - typedef foo { + + typedef bar { ... } } A server that implements revision "2015-01-01" of module "a" and supports feature "foo" can implement revision "2015-01-01" or "2015-04-04" of module "b". Since "b" was imported by revision, the type of leaf "/b:x/a:y" is the same regardless of which revision of "b" the server implements. A server that implements module "a", but does not support feature "foo" does not have to implement module "b". A server that implements revision "2015-01-01" of module "a" must - pick a revision of module "c", and list it in the "/modules/module" - list from "ietf-yang-library". + pick a revision of module "c", and list it in the "/modules-state/ + module" list from "ietf-yang-library". The following XML encoding example shows valid data for the - "/modules/module" list for a server that implements module "a": + "/modules-state/module" list for a server that implements module "a": - + ee1ecb017370cafd - a + a 2015-01-01 + urn:example:a foo - implement + implement - b + b 2015-04-04 - implement + urn:example:b + implement - c + c 2015-02-02 - import + urn:example:c + import - + 5.6.5. Announcing Conformance Information in NETCONF This document defines the following mechanism for announcing conformance information. Other mechanisms may be defined by future specifications. A NETCONF server announces the modules it implements by implementing the YANG module "ietf-yang-library" defined in [I-D.ietf-netconf-yang-library], and listing all implemented modules - in the "/modules/module" list. + in the "/modules-state/module" list. The server also advertises the following capability in the message (line-breaks and whitespaces are used for formatting reasons only): urn:ietf:params:netconf:capability:yang-library:1.0? module-set-id= The parameter "module-set-id" has the same value as the leaf - "/modules/module-set-id" from "ietf-yang-library". This parameter - MUST be present. + "/modules-state/module-set-id" from "ietf-yang-library". This + parameter MUST be present. With this mechanism, a client can cache the supported modules for a server, and only update the cache if the "module-set-id" value in the message changes. 5.7. Datastore Modification Data models may allow the server to alter the configuration datastore in ways not explicitly directed via network management protocol messages. For example, a data model may define leafs that are @@ -1756,43 +1774,51 @@ driven by a need to keep the parsers easy to implement, while the power is driven by the fact that modelers need to express their models in readable formats. 6.1.1. Comments Comments are C++ style. A single line comment starts with "//" and ends at the end of the line. A block comment is enclosed within "/*" and "*/". + Note that inside a quoted string (Section 6.1.3), these character + pairs are never interpreted as the start or end of a comment. + 6.1.2. Tokens A token in YANG is either a keyword, a string, a semicolon (";"), or braces ("{" or "}"). A string can be quoted or unquoted. A keyword is either one of the YANG keywords defined in this document, or a prefix identifier, followed by ":", followed by a language extension keyword. Keywords are case sensitive. See Section 6.2 for a formal definition of identifiers. 6.1.3. Quoting - If a string contains any space or tab characters, a semicolon (";"), - braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then - it MUST be enclosed within double or single quotes. + If a string contains any space, tab, or newline characters, a single + or double quote character, a semicolon (";"), braces ("{" or "}"), or + comment sequences ("//", "/*", or "*/"), then it MUST be enclosed + within double or single quotes. - If the double-quoted string contains a line break followed by space - or tab characters that are used to indent the text according to the + Within an unquoted string, every character is preserved. Note that + this means that the backslash character does not have any special + meaning in an unquoted string. + + If a double-quoted string contains a line break followed by space or + tab characters that are used to indent the text according to the layout in the YANG file, this leading whitespace is stripped from the string, up to and including the column of the double quote character, or to the first non-whitespace character, whichever occurs first. In this process, a tab character is treated as 8 space characters. - If the double-quoted string contains space or tab characters before a + If a double-quoted string contains space or tab characters before a line break, this trailing whitespace is stripped from the string. A single-quoted string (enclosed within ' ') preserves each character within the quotes. A single quote character cannot occur in a single-quoted string, even when preceded by a backslash. Within a double-quoted string (enclosed within " "), a backslash character introduces a special character, which depends on the character that immediately follows the backslash: @@ -2054,21 +2078,21 @@ The context node varies with the YANG XPath expression, and is specified where the YANG statement with the XPath expression is defined. 6.4.1.1. Examples Given the following module: module example-a { - namespace http://example.com/a; + namespace urn:example:a; prefix a; container a { list b { key id; leaf id { type string; } notification down { leaf reason { @@ -2093,78 +2117,78 @@ leaf b-ref { type leafref { path "/a/b/id"; } } } } And given the following data tree, specified in XML: - + 1 2 The accessible tree for a notification "down" on /a/b[id="2"] is: - + 1 2 error // possibly other top-level nodes here The accessible tree for an action invocation of "reset" on /a/ b[id="1"] with the "when" parameter set to "10" would be: - + 1 10 2 // possibly other top-level nodes here The accessible tree for the action output of this action is: - + 1 ok 2 // possibly other top-level nodes here The accessible tree for a notification "failure" could be: - + 1 2 2 @@ -2191,21 +2215,21 @@ 7. YANG Statements The following sections describe all of the YANG statements. Note that even a statement that does not have any substatements defined in YANG can have vendor-specific extensions as substatements. For example, the "description" statement does not have any substatements defined in YANG, but the following is legal: description "some text" { - acme:documentation-flag 5; + ex:documentation-flag 5; } 7.1. The module Statement The "module" statement defines the module's name, and groups all statements that belong to the module together. The "module" statement's argument is the name of the module, followed by a block of substatements that hold detailed module information. The module name follows the rules for identifiers in Section 6.2. @@ -2366,20 +2390,22 @@ module they are taken. Multiple revisions of the same module can be imported, provided that different prefixes are used. +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | prefix | 7.1.4 | 1 | | revision-date | 7.1.5.1 | 0..1 | + | description | 7.21.3 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ The import's Substatements 7.1.5.1. The import's revision-date Statement The import's "revision-date" statement is used to specify the exact version of the module to import. 7.1.6. The include Statement @@ -2402,20 +2428,22 @@ an error if the specified revision of the submodule does not exist. If no "revision-date" substatement is present, it is undefined which revision of the submodule is included. Multiple revisions of the same submodule MUST NOT be included. +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | revision-date | 7.1.5.1 | 0..1 | + | description | 7.21.3 | 0..1 | + | reference | 7.21.4 | 0..1 | +---------------+---------+-------------+ The includes's Substatements 7.1.7. The organization Statement The "organization" statement defines the party responsible for this module. The argument is a string that is used to specify a textual description of the organization(s) under whose auspices this module was developed. @@ -2443,48 +2471,47 @@ 7.1.9.1. The revision's Substatement +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | reference | 7.21.4 | 0..1 | +--------------+---------+-------------+ 7.1.10. Usage Example - - module acme-system { + module example-system { yang-version 1.1; - namespace "http://acme.example.com/system"; - prefix "acme"; + namespace "urn:example:system"; + prefix "sys"; import ietf-yang-types { prefix "yang"; } - include acme-types; + include example-types; - organization "ACME Inc."; + organization "Example Inc."; contact "Joe L. User - ACME, Inc. + Example Inc. 42 Anywhere Drive Nowhere, CA 95134 USA Phone: +1 800 555 0100 - EMail: joe@acme.example.com"; + EMail: joe@example.com"; description - "The module for entities implementing the ACME protocol."; + "The module for entities implementing the Example system."; - revision "2007-06-09" { + revision 2007-06-09 { description "Initial revision."; } // definitions follow... } 7.2. The submodule Statement While the primary unit in YANG is a module, a YANG module can itself be constructed out of several submodules. Submodules allow a module @@ -2581,44 +2607,44 @@ +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | prefix | 7.1.4 | 1 | +--------------+---------+-------------+ The belongs-to's Substatements 7.2.3. Usage Example - submodule acme-types { + submodule example-types { yang-version 1.1; - belongs-to "acme-system" { - prefix "acme"; + belongs-to "example-system" { + prefix "sys"; } import ietf-yang-types { prefix "yang"; } - organization "ACME Inc."; + organization "Example Inc."; contact "Joe L. User - ACME, Inc. + Example Inc. 42 Anywhere Drive Nowhere, CA 95134 USA Phone: +1 800 555 0100 - EMail: joe@acme.example.com"; + EMail: joe@example.com"; description - "This submodule defines common ACME types."; + "This submodule defines common Example types."; revision "2007-06-09" { description "Initial revision."; } // definitions follows... } 7.3. The typedef Statement @@ -2801,22 +2827,22 @@ The XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o The context node is the node in the accessible tree for which the "must" statement is defined. The result of the XPath expression is converted to a boolean value using the standard XPath rules. 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. + stored in their canonical form (see Section 9.1), 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 in the server. How the evaluation is done in practice is an implementation decision. 7.5.4. The must's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | @@ -2948,21 +2974,21 @@ To delete a container with an : - + 7.6. The leaf Statement @@ -3127,21 +3153,21 @@ To set the value of a leaf with an : - + 2022 @@ -3405,21 +3431,21 @@ operation "merge": - + eric @@ -3437,21 +3463,21 @@ - + blowfish-cbc @@ -3704,42 +3730,42 @@ To create a new user "barney": - + barney admin Barney Rubble To change the type of "fred" to "superuser": - + fred superuser Given the following ordered-by user list: @@ -3768,22 +3794,22 @@ - + barney rubble admin @@ -3795,22 +3821,22 @@ - + barney rubble @@ -3952,32 +3978,32 @@ 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" will be used. container transfer { choice how { default interval; case interval { leaf interval { type uint16; - default 30; units minutes; + default 30; } } case daily { leaf daily { type empty; } leaf time-of-day { type string; units 24-hour-clock; - default 1am; + default "01.00"; } } case manual { leaf manual { type empty; } } } } @@ -4039,21 +4065,21 @@ To change the protocol from tcp to udp: - + 7.10. The anydata Statement @@ -4142,21 +4168,21 @@ } The following is a valid encoding of such a list instance: 2014-07-29T13:43:01Z - + fault Ethernet0 major 7.11. The anyxml Statement @@ -4404,68 +4430,68 @@ Each node in the grouping is encoded as if it was defined inline, even if it is imported from another module with another XML namespace. 7.13.4. Usage Example To use the "endpoint" grouping defined in Section 7.12.2 in a definition of an HTTP server in some other module, we can do: - import acme-system { - prefix "acme"; + import example-system { + prefix "sys"; } container http-server { leaf name { type string; } - uses acme:endpoint; + uses sys:endpoint; } A corresponding XML instance example: extern-web 192.0.2.1 80 If port 80 should be the default for the HTTP server, default can be added: container http-server { leaf name { type string; } - uses acme:endpoint { + uses sys:endpoint { refine port { default 80; } } } If we want to define a list of servers, and each server has the ip and port as keys, we can do: list server { key "ip port"; leaf name { type string; } - uses acme:endpoint; + uses sys:endpoint; } The following is an error: container http-server { - uses acme:endpoint; + uses sys:endpoint; 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 @@ -4595,40 +4621,40 @@ If the RPC operation invocation succeeded, and no output parameters are returned, the contains a single element defined in [RFC6241]. If output parameters are returned, they are encoded as child elements to the element defined in [RFC6241], in the same order as they are defined within the "output" statement. 7.14.5. Usage Example The following example defines an RPC operation: - module rock { + module example-rock { yang-version 1.1; - namespace "http://example.net/rock"; + namespace "urn:example:rock"; prefix "rock"; rpc rock-the-house { input { leaf zip-code { type string; } } } } A corresponding XML instance example of the complete rpc and rpc- reply: - + 27606-0100 7.15. The action Statement @@ -4700,23 +4726,23 @@ element defined in [RFC6241]. If output parameters are returned, they are encoded as child elements to the element defined in [RFC6241], in the same order as they are defined within the "output" statement. 7.15.3. Usage Example The following example defines an action to reset one server at a server farm: - module server-farm { + module example-server-farm { yang-version 1.1; - namespace "http://example.net/server-farm"; + namespace "urn:example:server-farm"; prefix "sfarm"; import ietf-yang-types { prefix "yang"; } list server { key name; leaf name { type string; @@ -4737,32 +4763,32 @@ } } } A corresponding XML instance example of the complete rpc and rpc- reply: - + apache-1 2014-07-29T13:42:00Z - + 2014-07-29T13:42:12Z 7.16. The notification Statement The "notification" statement is used to define a notification. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed notification information. The "notification" statement defines a notification node in the schema @@ -4843,57 +4869,57 @@ of the defined notification. The notification's child nodes are encoded as subelements to the notification node's XML element, in any order. 7.16.3. Usage Example The following example defines a notification at the top-level of a module: - module event { + module example-event { yang-version 1.1; - namespace "http://example.com/event"; + namespace "urn:example:event"; prefix "ev"; notification event { leaf event-class { type string; } leaf reporting-entity { type instance-identifier; } leaf severity { type string; } } } A corresponding XML instance example of the complete notification: 2008-07-08T00:01:00Z - + fault /ex:interface[ex:name='Ethernet0'] major The following example defines a notification in a data node: - module interface-module { + module example-interface-module { yang-version 1.1; - namespace "http://example.com/schema/interfaces"; + namespace "urn:example:interface-module"; prefix "if"; container interfaces { list interface { key "name"; leaf name { type string; } notification interface-enabled { leaf by-user { @@ -4902,21 +4928,21 @@ } } } } A corresponding XML instance example of the complete notification: 2008-07-08T00:01:00Z - + eth1 fred 7.17. The augment Statement @@ -4946,34 +4972,34 @@ If the target node is a container or list node, the "action" and "notification" statements can be used within the "augment" statement. If the target node is a choice node, the "case" statement, or a case shorthand statement (see Section 7.9.2) can be used within the "augment" statement. The "augment" statement MUST NOT add multiple nodes with the same name from the same module to the target node. - If the augmentation adds mandatory nodes (see Section 3) to a target - node in another module, the augmentation MUST be conditional with a - "when" statement. Care must be taken when defining the "when" - expression, so that clients that do not know about the augmenting - module do not break. + If the augmentation adds mandatory configuration nodes (see + Section 3) to a target node in another module, the augmentation MUST + be conditional with a "when" statement. Care must be taken when + defining the "when" expression, so that clients that do not know + about the augmenting module do not break. In the following example, it is OK to augment the "interface" entry with "mandatory-leaf" because the augmentation depends on support for "some-new-iftype". The old client does not know about this type so it would never select this type, and therefore not be adding a mandatory data node. module example-augment { - namespace "http://example.com/augment"; + namespace "urn:example:augment"; prefix mymod; import ietf-interfaces { prefix if; } identity some-new-iftype { base if:interface-type; } @@ -5014,57 +5040,57 @@ All data nodes defined in the "augment" statement are defined as XML elements in the XML namespace of the module where the "augment" is specified. When a node is augmented, the augmenting child nodes are encoded as subelements to the augmented node, in any order. 7.17.3. Usage Example - In namespace http://example.com/schema/interfaces, we have: + In namespace urn:example:interface-module, we have: container interfaces { list ifEntry { key "ifIndex"; leaf ifIndex { type uint32; } leaf ifDescr { type string; } leaf ifType { type iana:IfType; } leaf ifMtu { type int32; } } } - Then, in namespace http://example.com/schema/ds0, we have: + Then, in namespace urn:example:ds0, we have: - import interface-module { + import example-interface-module { prefix "if"; } augment "/if:interfaces/if:ifEntry" { when "if:ifType='ds0'"; leaf ds0ChannelNumber { type ChannelNumber; } } A corresponding XML instance example: - + 1 Flintstone Inc Ethernet A562 ethernetCsmacd 1500 2 Flintstone Inc DS0 ds0 @@ -5144,49 +5170,50 @@ The derivation of identities has the following properties: o It is irreflexive, which means that an identity is not derived from itself. o It is transitive, which means that if identity B is derived from A and C is derived from B, then C is also derived from A. 7.18.3. Usage Example - - module crypto-base { + module example-crypto-base { yang-version 1.1; - namespace "http://example.com/crypto-base"; + namespace "urn:example:crypto-base"; prefix "crypto"; identity crypto-alg { description "Base identity from which all crypto algorithms are derived."; } identity symmetric-key { description - "Base identity used to identify symmetric-key crypto algorithms."; + "Base identity used to identify symmetric-key crypto + algorithms."; } identity public-key { description - "Base identity used to identify public-key crypto algorithms."; + "Base identity used to identify public-key crypto + algorithms."; } } - module des { + module example-des { yang-version 1.1; - namespace "http://example.com/des"; + namespace "urn:example:des"; prefix "des"; - import "crypto-base" { + import "example-crypto-base" { prefix "crypto"; } identity des { base "crypto:crypto-alg"; base "crypto:symmetric-key"; description "DES crypto algorithm"; } identity des3 { @@ -5260,40 +5287,40 @@ the string "true" or "false". This statement indicates if the argument is mapped to an XML element in YIN or to an XML attribute (see Section 13). If no "yin-element" statement is present, it defaults to "false". 7.19.3. Usage Example To define an extension: - module my-extensions { + module example-extensions { yang-version 1.1; ... extension c-define { description "Takes as argument a name string. Makes the code generator use the given name in the #define."; argument "name"; } } To use the extension: - module my-interfaces { + module example-interfaces { yang-version 1.1; ... - import my-extensions { + import example-extensions { prefix "myext"; } ... container interfaces { ... myext:c-define "MY_INTERFACES"; } } @@ -5319,21 +5346,21 @@ 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 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 server does not report that it supports this feature, the "local-storage-limit" node is not supported. - module syslog { + module example-syslog { yang-version 1.1; ... feature local-storage { description "This feature means the server supports local storage (memory, flash or disk) that can be used to store syslog messages."; } @@ -5500,36 +5527,37 @@ 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 server is informing client applications that it does not support the "daytime" service in the style of RFC 867. - module my-deviations { + module example-deviations { yang-version 1.1; - namespace "http://example.com/my-deviations"; + namespace "urn:example:deviations"; prefix md; - import my-base { + import example-base { prefix base; } deviation /base:system/base:daytime { deviate not-supported; } ... } - A server would advertise both modules "my-base" and "my-deviations". + A server would advertise both modules "example-base" and + "example-deviations". 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 } } @@ -5873,21 +5901,24 @@ 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 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. + evaluations are done using the canonical form, if the data type has a + canonical form. If the data type does not have a canonical form, the + format of the value MUST match the data type's lexical + representation, but the exact format is implementation dependent. 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: @@ -6281,22 +6313,23 @@ An enumeration can be restricted with the "enum" (Section 9.6.4) statement. 9.6.4. The enum Statement The "enum" statement, which is a substatement to the "type" statement, MUST be present if the type is "enumeration". It is repeatedly used to specify each assigned name of an enumeration type. It takes as an argument a string which is the assigned name. The - string MUST NOT be empty and MUST NOT have any leading or trailing - whitespace characters. The use of Unicode control codes SHOULD be + string MUST NOT be zero-length and MUST NOT have any leading or + trailing whitespace characters (any Unicode character with the + "White_Space" property). The use of Unicode control codes SHOULD be avoided. The statement is optionally followed by a block of substatements that holds detailed enum information. All assigned names in an enumeration MUST be unique. When an existing enumeration type is restricted, the set of assigned names in the new type MUST be a subset of the base type's set of assigned names. The value of such an assigned name MUST not be @@ -6417,21 +6451,21 @@ changed. 9.7.1. Restrictions A bits type can be restricted with the "bit" (Section 9.7.4) statement. 9.7.2. Lexical Representation The lexical representation of the bits type is a space-separated list - of the individual bit values that are set. An empty string thus + of the individual bit values that are set. A zero-length string thus represents a value where no bits are set. 9.7.3. Canonical Form In the canonical form, the bit values are separated by a single space character and they appear ordered by their position (see Section 9.7.4.2). 9.7.4. The bit Statement @@ -6772,21 +6806,21 @@ + "/admin-status"; } } } An example of a corresponding XML notification: 2008-04-01T00:01:00Z - + eth0 up 9.10. The identityref Built-In Type The identityref type is used to reference an existing identity (see Section 7.18). @@ -6835,26 +6869,26 @@ 9.10.4. Canonical Form Since the lexical form depends on the XML context in which the value occurs, this type does not have a canonical form. 9.10.5. Usage Example With the identity definitions in Section 7.18.3 and the following module: - module my-crypto { + module example-my-crypto { yang-version 1.1; - namespace "http://example.com/my-crypto"; + namespace "urn:example:my-crypto"; prefix mc; - import "crypto-base" { + import "example-crypto-base" { prefix "crypto"; } identity aes { base "crypto:crypto-alg"; } leaf crypto { type identityref { base "crypto:crypto-alg"; @@ -6863,33 +6897,33 @@ container aes-parameters { when "../crypto = 'mc:aes'"; ... } } the following is an example how the leaf "crypto" can be encoded, if the value is the "des3" identity defined in the "des" module: - des:des3 + des:des3 Any prefixes used in the encoding are local to each instance encoding. This means that the same identityref may be encoded differently by different implementations. For example, the following example encodes the same leaf as above: - x:des3 + x:des3 If the "crypto" leaf's value instead is "aes" defined in the - "my-crypto" module, it can be encoded as: + "example-my-crypto" module, it can be encoded as: - mc:aes + mc:aes or, using the default namespace: aes 9.11. The empty Built-In Type The empty built-in type represents a leaf that does not have any value, it conveys information by its presence or absence. @@ -7016,21 +7050,22 @@ particular instance node in the data tree. The syntax for an instance-identifier is a subset of the XPath abbreviated syntax, formally defined by the rule "instance-identifier" in Section 14. It is used to uniquely identify a node in the data tree. Predicates are used only for specifying the values for the key nodes for list entries, a value of a leaf-list entry, or a positional index for a list without keys. For identifying list entries with keys, each predicate consists of one equality test per key, and each key MUST have a corresponding - predicate. + predicate. If a key is of type "empty", it is represented as a zero- + length string (""). If the leaf with the instance-identifier type represents configuration data, and the "require-instance" property (Section 9.9.3) is "true", the node it refers to MUST also represent configuration. Such a leaf puts a constraint on valid data. All such leaf nodes MUST reference existing nodes or leaf or leaf-list nodes with their default value in use (see Section 7.6.1 and Section 7.7.2) for the data to be valid. This constraint is enforced according to the rules in Section 8. @@ -7073,20 +7108,24 @@ /* instance-identifier for a list entry */ /ex:system/ex:user[ex:name='fred'] /* instance-identifier for a leaf in a list entry */ /ex:system/ex:user[ex:name='fred']/ex:type /* instance-identifier for a list entry with two keys */ /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] + /* instance-identifier for a list entry where the second + key ("enabled") is of type empty */ + /ex:system/ex:service[ex:name='foo'][ex:enabled=''] + /* instance-identifier for a leaf-list entry */ /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] /* instance-identifier for a list entry without keys */ /ex:stats/ex:port[3] 10. XPath Functions This document defines two generic XPath functions and four YANG type- specific XPath functions. The function signatures are specified with @@ -7185,20 +7223,21 @@ container mgmt-interface { leaf name { type leafref { path "/interface/name"; } } leaf type { type leafref { path "/interface[name=current()/../name]/type"; + } must 'deref(.)/../enabled = "true"' { error-message "The management interface cannot be disabled."; } } } 10.4. Functions for the YANG Type "identityref" 10.4.1. derived-from() @@ -7268,26 +7307,24 @@ The parameter "identity" is a string matching the rule "identifier-ref" in Section 14. If a prefix is present on the identity, it refers to an identity defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. If no prefix is present, the identity refers to an identity defined in the current module or an included submodule. 10.4.2.1. Usage Example - The module defined in ^derived-from-ex^ might also have: + The module defined in Section 10.4.1.1 might also have: augment "/interface" { - when 'derived-from-or-self(type, - "example-interface", - "fast-ethernet")'; + when 'derived-from-or-self(type, "exif:fast-ethernet"); // fast-ethernet-specific definitions here } 10.5. Functions for the YANG Type "enumeration" 10.5.1. enum-value() number enum-value(node-set nodes) The enum-value() function checks if the first node in document order @@ -7353,43 +7390,44 @@ } the following XPath expression can be used to select all interfaces with the UP flag set: /interface[bit-is-set(flags, "UP")] 11. Updating a Module As experience is gained with a module, it may be desirable to revise - that module. However, changes are not allowed if they have any - potential to cause interoperability problems between a client using - an original specification and a server using an updated - specification. + that module. However, changes to published modules are not allowed + if they have any potential to cause interoperability problems between + a client using an original specification and a server using an + updated specification. For any published change, a new "revision" statement (Section 7.1.9) MUST be included in front of the existing "revision" statements. If there are no existing "revision" statements, then one MUST be added to identify the new revision. Furthermore, any necessary changes MUST be applied to any meta-data statements, including the "organization" and "contact" statements (Section 7.1.7, Section 7.1.8). Note that definitions contained in a module are available to be imported by any other module, and are referenced in "import" statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, since all XML elements are qualified by the namespace. - Obsolete definitions MUST NOT be removed from modules since their - identifiers may still be referenced by other modules. + Obsolete definitions MUST NOT be removed from published modules since + their identifiers may still be referenced by other modules. - A definition may be revised in any of the following ways: + A definition in a published module 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. 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. Note that inserting a new bit before an existing bit or reordering existing bit will result in new @@ -7465,21 +7503,22 @@ o The "prefix" statement may be changed, provided all local uses of the prefix also are changed. Otherwise, if the semantics of any previous definition are changed (i.e., if a non-editorial change is made to any definition other than those specifically allowed above), then this MUST be achieved by a new definition with a new identifier. In statements that have any data definition statements as substatements, those data definition substatements MUST NOT be - reordered. + reordered. If new data definition statements are added, they can be + added anywhere in the sequence of existing substatement. 12. Coexistence with YANG version 1 A YANG version 1.1 module MUST NOT include a YANG version 1 submodule, and a YANG version 1 module MUST NOT include a YANG version 1.1 submodule. A YANG version 1 module or submodule MUST NOT import a YANG version 1.1 module by revision. @@ -7629,55 +7668,55 @@ | yang-version | value | false | | yin-element | value | false | +------------------+---------------+-------------+ Table 1: Mapping of arguments of the YANG statements. 13.1.1. Usage Example The following YANG module: - module acme-foo { + module example-foo { yang-version 1.1; - namespace "http://acme.example.com/foo"; - prefix "acfoo"; + namespace "urn:example:foo"; + prefix "foo"; - import my-extensions { + import example-extensions { prefix "myext"; } list interface { key "name"; leaf name { type string; } leaf mtu { type uint32; description "The MTU of the interface."; myext:c-define "MY_MTU"; } } } where the extension "c-define" is defined in Section 7.19.3, is translated into the following YIN: - + xmlns:foo="urn:example:foo" + xmlns:myext="urn:example:extensions"> - - + + - + @@ -7771,26 +7810,31 @@ yang-version-arg-str = < a string that matches the rule > < yang-version-arg > yang-version-arg = "1.1" import-stmt = import-keyword sep identifier-arg-str optsep "{" stmtsep ;; these stmts can appear in any order prefix-stmt [revision-date-stmt] + [description-stmt] + [reference-stmt] "}" stmtsep include-stmt = include-keyword sep identifier-arg-str optsep (";" / "{" stmtsep + ;; these stmts can appear in any order [revision-date-stmt] + [description-stmt] + [reference-stmt] "}") stmtsep namespace-stmt = namespace-keyword sep uri-str stmtend uri-str = < a string that matches the rule > < URI in RFC 3986 > prefix-stmt = prefix-keyword sep prefix-arg-str stmtend belongs-to-stmt = belongs-to-keyword sep identifier-arg-str @@ -8897,45 +8947,35 @@ If a NETCONF operation would result in configuration data where a leaf of type "instance-identifier" or "leafref" marked with require- instance "true" refers to a non-existing instance, the following error is returned: error-tag: data-missing error-app-tag: instance-required error-path: Path to the instance-identifier or leafref leaf. -15.6. Error Message for Data That Does Not Match a leafref Type - - If a NETCONF operation would result in configuration data where a - leaf of type "leafref" refers to a non-existing instance, the - following error is returned: - - error-tag: data-missing - error-app-tag: instance-required - error-path: Path to the leafref leaf. - -15.7. Error Message for Data That Violates a mandatory choice Statement +15.6. Error Message for Data That Violates a mandatory choice Statement If a NETCONF operation would result in configuration data where no nodes exists in a mandatory choice, the following error is returned: error-tag: data-missing error-app-tag: missing-choice error-path: Path to the element with the missing choice. error-info: : Contains the name of the missing mandatory choice. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). -15.8. Error Message for the "insert" Operation +15.7. Error Message for the "insert" Operation If the "insert" and "key" or "value" attributes are used in an for a list or leaf-list node, and the "key" or "value" refers to a non-existing instance, the following error is returned: error-tag: bad-attribute error-app-tag: missing-instance 16. IANA Considerations @@ -8995,101 +9035,112 @@ provided helpful comments on various versions of this document: Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, Ladislav Lhotka, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy Presuhn, David Reid, Jernej Tuljak, Kent Watsen, Bert Wijnen, and Robert Wilton. 20. ChangeLog RFC Editor: remove this section upon publication as an RFC. -20.1. Version -09 +20.1. Version -10 + + o Made single and double quote characters illegal in unquoted + strings. + + o Allow "description" and "reference" in "import" and "include". + + o Removed redundant NETCONF Error Message subsection. + + o Editorial fixes and clarifications after second WGLC reviews. + +20.2. Version -09 o Editorial fixes and clarifications after WGLC reviews. o when statement context clarification. o Allow "augment" to add conditionally mandatory nodes (see Section 7.17). o Allow non-unique config false leaf-lists. o Made handling of choice and false "when" expressions non-NETCONF specific. o Changed the function signatures for "derived-from" and "derived-from-or-self". -20.2. Version -08 +20.3. Version -08 o Fixes after WGLC reviews. -20.3. Version -07 +20.4. Version -07 o Fixes after WG review. o Included solution Y60-01. -20.4. Version -06 +20.5. Version -06 o Included solution Y45-05. -20.5. Version -05 +20.6. 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.6. Version -04 +20.7. 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.7. Version -03 +20.8. 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.8. Version -02 +20.9. 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.9. Version -01 +20.10. 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. @@ -9099,131 +9150,148 @@ 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.10. Version -00 +20.11. 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 [I-D.ietf-netconf-yang-library] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module - Library", draft-ietf-netconf-yang-library (work in - progress), July 2015. + Library", draft-ietf-netconf-yang-library-04 (work in + progress), February 2016. [ISO.10646] International Organization for Standardization, "Information Technology - Universal Multiple-Octet Coded Character Set (UCS)", ISO Standard 10646:2003, 2003. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, RFC - 3986, January 2005. + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. + Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, + . - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event - Notifications", RFC 5277, July 2008. + Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, + . - [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. - Bierman, "Network Configuration Protocol (NETCONF)", RFC - 6241, June 2011. + [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., + and A. Bierman, Ed., "Network Configuration Protocol + (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, + . - [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC - 7405, December 2014. + [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", + RFC 7405, DOI 10.17487/RFC7405, December 2014, + . [XML-NAMES] - Hollander, D., Tobin, R., Thompson, H., Bray, T., and A. - Layman, "Namespaces in XML 1.0 (Third Edition)", World + Bray, T., Hollander, D., Layman, A., Tobin, R., and H. + Thompson, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208, December 2009, . [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . [XSD-TYPES] - Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes + Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, . 21.2. Informative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF - Protocol", draft-ietf-netconf-restconf-07 (work in - progress), July 2015. + Protocol", draft-ietf-netconf-restconf-09 (work in + progress), December 2015. [I-D.ietf-netmod-yang-json] Lhotka, L., "JSON Encoding of Data Modeled with YANG", - draft-ietf-netmod-yang-json-04 (work in progress), June - 2015. + draft-ietf-netmod-yang-json-07 (work in progress), January + 2016. [I-D.vanderstok-core-comi] Stok, P., Bierman, A., Schoenwaelder, J., and A. Sehgal, - "CoAP Management Interface", draft-vanderstok-core-comi-07 - (work in progress), July 2015. + "CoAP Management Interface", draft-vanderstok-core-comi-08 + (work in progress), October 2015. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information - Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. + Version 2 (SMIv2)", STD 58, RFC 2578, + DOI 10.17487/RFC2578, April 1999, + . [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. - Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD - 58, RFC 2579, April 1999. + Schoenwaelder, Ed., "Textual Conventions for SMIv2", + STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, + . [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation - Structure of Management Information", RFC 3780, May 2004. + Structure of Management Information", RFC 3780, + DOI 10.17487/RFC3780, May 2004, + . - [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC - Series and RFC Editor", RFC 4844, July 2007. + [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC + Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, + July 2007, . - [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the - Network Configuration Protocol (NETCONF)", RFC 6020, - October 2010. + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, 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, - . + (XPath) 2.0 (Second Edition)", World Wide Web Consortium + Recommendation REC-xpath20-20101214, December 2010, + . [XSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999, . Author's Address Martin Bjorklund (editor) Tail-f Systems