--- 1/draft-ietf-netmod-rfc6020bis-06.txt 2015-09-23 01:15:03.343939491 -0700 +++ 2/draft-ietf-netmod-rfc6020bis-07.txt 2015-09-23 01:15:03.675947529 -0700 @@ -1,44 +1,42 @@ Network Working Group M. Bjorklund, Ed. Internet-Draft Tail-f Systems -Obsoletes: 6020 (if approved) July 6, 2015 -Intended status: Standards Track -Expires: January 7, 2016 +Intended status: Standards Track September 23, 2015 +Expires: March 26, 2016 - YANG - A Data Modeling Language for the Network Configuration Protocol - (NETCONF) - draft-ietf-netmod-rfc6020bis-06 + The YANG 1.1 Data Modeling Language + draft-ietf-netmod-rfc6020bis-07 Abstract - YANG is a data modeling language used to model configuration and - state data manipulated by the Network Configuration Protocol - (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. - This document obsoletes RFC 6020. + 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 This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 7, 2016. + This Internet-Draft will expire on March 26, 2016. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -64,324 +62,328 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 - 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 - 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 + 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 . . . . . . . . . . . . . . 26 - 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 - 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 - 5.1.1. Import and Include by Revision . . . . . . . . . . . 28 - 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 - 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 - 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 - 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 - 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 - 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 - 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 + 4.2.10. Notification Definitions . . . . . . . . . . . . . . 27 + 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.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 32 + 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 32 + 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 32 + 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 32 + 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 33 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 - 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 - 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 - 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 34 - 5.6.5. Announcing Conformance Information in NETCONF . . . . 37 - 5.7. Data Store Modification . . . . . . . . . . . . . . . . . 38 + 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 34 + 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 34 + 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 35 + 5.6.5. Announcing Conformance Information in NETCONF . . . . 38 + 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 38 + 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38 - 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 38 - 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 38 - 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 38 + 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 39 + 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 39 + 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39 - 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 40 - 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 40 - 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 41 - 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 41 - 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 42 - 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 42 - 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 44 - 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 44 - 7.1. The module Statement . . . . . . . . . . . . . . . . . . 45 - 7.1.1. The module's Substatements . . . . . . . . . . . . . 46 - 7.1.2. The yang-version Statement . . . . . . . . . . . . . 47 - 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 48 - 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 48 - 7.1.5. The import Statement . . . . . . . . . . . . . . . . 48 - 7.1.6. The include Statement . . . . . . . . . . . . . . . . 49 - 7.1.7. The organization Statement . . . . . . . . . . . . . 50 - 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 50 - 7.1.9. The revision Statement . . . . . . . . . . . . . . . 50 - 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 51 - 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 52 - 7.2.1. The submodule's Substatements . . . . . . . . . . . . 53 - 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 54 - 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 55 - 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 55 - 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 56 - 7.3.2. The typedef's type Statement . . . . . . . . . . . . 56 - 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 56 - 7.3.4. The typedef's default Statement . . . . . . . . . . . 56 - 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 57 - 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 57 - 7.4.1. The type's Substatements . . . . . . . . . . . . . . 57 - 7.5. The container Statement . . . . . . . . . . . . . . . . . 57 - 7.5.1. Containers with Presence . . . . . . . . . . . . . . 58 - 7.5.2. The container's Substatements . . . . . . . . . . . . 58 - 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 59 - 7.5.4. The must's Substatements . . . . . . . . . . . . . . 60 - 7.5.5. The presence Statement . . . . . . . . . . . . . . . 61 - 7.5.6. The container's Child Node Statements . . . . . . . . 61 - 7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 - 7.5.8. NETCONF Operations . . . . . . . . . . 62 - 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 62 - 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 63 - 7.6.1. The leaf's default value . . . . . . . . . . . . . . 64 - 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 64 - 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 65 - 7.6.4. The leaf's default Statement . . . . . . . . . . . . 65 - 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 65 - 7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 65 - 7.6.7. NETCONF Operations . . . . . . . . . . 66 - 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 - 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 67 - 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 67 - 7.7.2. The leaf-list's default values . . . . . . . . . . . 68 - 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 69 - 7.7.4. The leaf-list's default Statement . . . . . . . . . . 69 - 7.7.5. The min-elements Statement . . . . . . . . . . . . . 69 - 7.7.6. The max-elements Statement . . . . . . . . . . . . . 70 - 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 70 - 7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 71 - 7.7.9. NETCONF Operations . . . . . . . . . . 71 - 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 72 - 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 74 - 7.8.1. The list's Substatements . . . . . . . . . . . . . . 74 - 7.8.2. The list's key Statement . . . . . . . . . . . . . . 75 - 7.8.3. The list's unique Statement . . . . . . . . . . . . . 76 - 7.8.4. The list's Child Node Statements . . . . . . . . . . 77 - 7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 77 - 7.8.6. NETCONF Operations . . . . . . . . . . 78 - 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 79 - 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 82 - 7.9.1. The choice's Substatements . . . . . . . . . . . . . 82 - 7.9.2. The choice's case Statement . . . . . . . . . . . . . 83 - 7.9.3. The choice's default Statement . . . . . . . . . . . 84 - 7.9.4. The choice's mandatory Statement . . . . . . . . . . 86 - 7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 86 - 7.9.6. NETCONF Operations . . . . . . . . . . 86 - 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 - 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 87 - 7.10.1. The anydata's Substatements . . . . . . . . . . . . 88 - 7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 88 - 7.10.3. NETCONF Operations . . . . . . . . . . 88 - 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 89 - 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 89 - 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 90 - 7.11.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 90 - 7.11.3. NETCONF Operations . . . . . . . . . . 90 - 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 91 - 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 91 - 7.12.1. The grouping's Substatements . . . . . . . . . . . . 92 - 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 92 - 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 93 - 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 93 - 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 93 - 7.13.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 94 - 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 94 - 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 96 - 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 96 - 7.14.2. The input Statement . . . . . . . . . . . . . . . . 96 - 7.14.3. The output Statement . . . . . . . . . . . . . . . . 97 - 7.14.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 98 - 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 99 - 7.15. The action Statement . . . . . . . . . . . . . . . . . . 99 - 7.15.1. The action's Substatements . . . . . . . . . . . . . 100 - 7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 100 - 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 101 - 7.16. The notification Statement . . . . . . . . . . . . . . . 102 - 7.16.1. The notification's Substatements . . . . . . . . . . 103 - 7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 103 - 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 104 - 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 105 - 7.17.1. The augment's Substatements . . . . . . . . . . . . 106 - 7.17.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 107 - 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 - 7.18. The identity Statement . . . . . . . . . . . . . . . . . 109 - 7.18.1. The identity's Substatements . . . . . . . . . . . . 109 - 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 109 - 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 110 - 7.19. The extension Statement . . . . . . . . . . . . . . . . . 110 - 7.19.1. The extension's Substatements . . . . . . . . . . . 111 - 7.19.2. The argument Statement . . . . . . . . . . . . . . . 111 - 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 - 7.20. Conformance-Related Statements . . . . . . . . . . . . . 112 - 7.20.1. The feature Statement . . . . . . . . . . . . . . . 112 - 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 114 - 7.20.3. The deviation Statement . . . . . . . . . . . . . . 115 - 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 117 - 7.21.1. The config Statement . . . . . . . . . . . . . . . . 117 - 7.21.2. The status Statement . . . . . . . . . . . . . . . . 118 - 7.21.3. The description Statement . . . . . . . . . . . . . 119 - 7.21.4. The reference Statement . . . . . . . . . . . . . . 119 - 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 119 - 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 120 - 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 120 - 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 121 - 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 121 - 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 121 - 8.3.2. NETCONF Processing . . . . . . . . . . 122 - 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 123 - 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 123 - 9.1. Canonical Representation . . . . . . . . . . . . . . . . 123 - 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 124 - 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 124 - 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 - 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 - 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 125 - 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 - 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 126 - 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 127 - 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 127 - 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 127 - 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 127 - 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 - 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 128 - 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 128 - 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 - 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 129 - 9.4.4. The length Statement . . . . . . . . . . . . . . . . 129 - 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 130 - 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 130 - 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 130 - 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 131 - 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 132 - 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 - 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 - 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 132 - 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 132 - 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 - 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 - 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 132 - 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 - 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 135 - 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 - 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 135 - 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 - 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 135 - 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 - 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 137 - 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 - 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 137 - 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 - 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 137 - 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 138 - 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 138 - 9.9.3. The require-instance Statement . . . . . . . . . . . 138 - 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 139 - 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 139 - 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 139 - 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 143 - 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 143 - 9.10.2. The identityref's base Statement . . . . . . . . . . 143 - 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 143 - 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 144 - 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 144 - 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 145 - 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 - 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 145 - 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 - 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 145 - 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 146 - 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 - 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 146 - 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 146 - 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 146 - 9.13. The instance-identifier Built-In Type . . . . . . . . . . 147 - 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 - 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 148 - 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 - 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 - 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 149 - 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 149 - 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 149 - 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 149 - 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 149 + 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 41 + 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 41 + 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 42 + 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 42 + 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 43 + 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 43 + 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 45 + 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 45 + 7.1. The module Statement . . . . . . . . . . . . . . . . . . 46 + 7.1.1. The module's Substatements . . . . . . . . . . . . . 47 + 7.1.2. The yang-version Statement . . . . . . . . . . . . . 48 + 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 49 + 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 49 + 7.1.5. The import Statement . . . . . . . . . . . . . . . . 49 + 7.1.6. The include Statement . . . . . . . . . . . . . . . . 50 + 7.1.7. The organization Statement . . . . . . . . . . . . . 51 + 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 51 + 7.1.9. The revision Statement . . . . . . . . . . . . . . . 51 + 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 52 + 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 53 + 7.2.1. The submodule's Substatements . . . . . . . . . . . . 54 + 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 55 + 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 56 + 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 56 + 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 57 + 7.3.2. The typedef's type Statement . . . . . . . . . . . . 57 + 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 57 + 7.3.4. The typedef's default Statement . . . . . . . . . . . 57 + 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 58 + 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 58 + 7.4.1. The type's Substatements . . . . . . . . . . . . . . 58 + 7.5. The container Statement . . . . . . . . . . . . . . . . . 58 + 7.5.1. Containers with Presence . . . . . . . . . . . . . . 59 + 7.5.2. The container's Substatements . . . . . . . . . . . . 59 + 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 60 + 7.5.4. The must's Substatements . . . . . . . . . . . . . . 61 + 7.5.5. The presence Statement . . . . . . . . . . . . . . . 62 + 7.5.6. The container's Child Node Statements . . . . . . . . 62 + 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 62 + 7.5.8. NETCONF Operations . . . . . . . . . . 63 + 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 63 + 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 65 + 7.6.1. The leaf's default value . . . . . . . . . . . . . . 65 + 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 66 + 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 66 + 7.6.4. The leaf's default Statement . . . . . . . . . . . . 66 + 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 66 + 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 67 + 7.6.7. NETCONF Operations . . . . . . . . . . 67 + 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 67 + 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 68 + 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 69 + 7.7.2. The leaf-list's default values . . . . . . . . . . . 69 + 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 70 + 7.7.4. The leaf-list's default Statement . . . . . . . . . . 70 + 7.7.5. The min-elements Statement . . . . . . . . . . . . . 71 + 7.7.6. The max-elements Statement . . . . . . . . . . . . . 71 + 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 71 + 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 72 + 7.7.9. NETCONF Operations . . . . . . . . . . 72 + 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 73 + 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 75 + 7.8.1. The list's Substatements . . . . . . . . . . . . . . 75 + 7.8.2. The list's key Statement . . . . . . . . . . . . . . 76 + 7.8.3. The list's unique Statement . . . . . . . . . . . . . 77 + 7.8.4. The list's Child Node Statements . . . . . . . . . . 78 + 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 78 + 7.8.6. NETCONF Operations . . . . . . . . . . 79 + 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 80 + 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 83 + 7.9.1. The choice's Substatements . . . . . . . . . . . . . 83 + 7.9.2. The choice's case Statement . . . . . . . . . . . . . 84 + 7.9.3. The choice's default Statement . . . . . . . . . . . 85 + 7.9.4. The choice's mandatory Statement . . . . . . . . . . 87 + 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 87 + 7.9.6. NETCONF Operations . . . . . . . . . . 87 + 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 87 + 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 88 + 7.10.1. The anydata's Substatements . . . . . . . . . . . . 89 + 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 89 + 7.10.3. NETCONF Operations . . . . . . . . . . 89 + 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 90 + 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 90 + 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 91 + 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 91 + 7.11.3. NETCONF Operations . . . . . . . . . . 92 + 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 92 + 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 92 + 7.12.1. The grouping's Substatements . . . . . . . . . . . . 93 + 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 94 + 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 94 + 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 94 + 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 95 + 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 96 + 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 96 + 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 97 + 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 97 + 7.14.2. The input Statement . . . . . . . . . . . . . . . . 98 + 7.14.3. The output Statement . . . . . . . . . . . . . . . . 99 + 7.14.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 100 + 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 100 + 7.15. The action Statement . . . . . . . . . . . . . . . . . . 101 + 7.15.1. The action's Substatements . . . . . . . . . . . . . 101 + 7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 + 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 102 + 7.16. The notification Statement . . . . . . . . . . . . . . . 104 + 7.16.1. The notification's Substatements . . . . . . . . . . 105 + 7.16.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 105 + 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 106 + 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 107 + 7.17.1. The augment's Substatements . . . . . . . . . . . . 108 + 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 109 + 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 + 7.18. The identity Statement . . . . . . . . . . . . . . . . . 111 + 7.18.1. The identity's Substatements . . . . . . . . . . . . 111 + 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 111 + 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 + 7.19. The extension Statement . . . . . . . . . . . . . . . . . 112 + 7.19.1. The extension's Substatements . . . . . . . . . . . 113 + 7.19.2. The argument Statement . . . . . . . . . . . . . . . 113 + 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 114 + 7.20. Conformance-Related Statements . . . . . . . . . . . . . 114 + 7.20.1. The feature Statement . . . . . . . . . . . . . . . 115 + 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 116 + 7.20.3. The deviation Statement . . . . . . . . . . . . . . 117 + 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 120 + 7.21.1. The config Statement . . . . . . . . . . . . . . . . 120 + 7.21.2. The status Statement . . . . . . . . . . . . . . . . 120 + 7.21.3. The description Statement . . . . . . . . . . . . . 121 + 7.21.4. The reference Statement . . . . . . . . . . . . . . 121 + 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 122 + 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 123 + 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 123 + 8.2. NETCONF Constraint Enforcement Model . . . . . . . . . . 124 + 8.2.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 124 + 8.2.2. NETCONF Processing . . . . . . . . . . 125 + 8.2.3. Validation . . . . . . . . . . . . . . . . . . . . . 125 + 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 126 + 9.1. Canonical Representation . . . . . . . . . . . . . . . . 126 + 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 126 + 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 127 + 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 128 + 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 128 + 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 128 + 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129 + 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 129 + 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 129 + 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 + 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 130 + 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 130 + 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130 + 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 131 + 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 131 + 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 131 + 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 131 + 9.4.4. The length Statement . . . . . . . . . . . . . . . . 131 + 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 132 + 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 132 + 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 132 + 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 134 + 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 134 + 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 134 + 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 134 + 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134 + 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134 + 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 135 + 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 + 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 137 + 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 + 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 137 + 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 + 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 137 + 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 + 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 139 + 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 139 + 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 139 + 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 139 + 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 139 + 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 140 + 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 140 + 9.9.3. The require-instance Statement . . . . . . . . . . . 141 + 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 141 + 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 141 + 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 141 + 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 145 + 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 + 9.10.2. The identityref's base Statement . . . . . . . . . . 145 + 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 146 + 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 146 + 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 146 + 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 148 + 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 + 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 148 + 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 + 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 + 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 148 + 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149 + 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 149 + 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 149 + 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 149 + 9.13. The instance-identifier Built-In Type . . . . . . . . . . 150 + 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 + 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 151 + 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 151 + 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 151 + 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 152 + 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 152 + 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 152 + 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 152 + 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 152 10.3. Functions for the YANG Types "leafref" and "instance- - identifier" . . . . . . . . . . . . . . . . . . . . . . 150 - 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 150 - 10.4. Functions for the YANG Type "identityref" . . . . . . . 151 - 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 151 - 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 151 - 10.5. Functions for the YANG Type "enumeration" . . . . . . . 152 - 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 152 - 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 153 - 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 153 - 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 154 - 12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 - 12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 157 - 12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 159 - 13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 160 - 14. Error Responses for YANG Related Errors . . . . . . . . . . . 184 - 14.1. Error Message for Data That Violates a unique Statement 184 - 14.2. Error Message for Data That Violates a max-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 185 - - 14.3. Error Message for Data That Violates a min-elements - Statement . . . . . . . . . . . . . . . . . . . . . . . 185 - 14.4. Error Message for Data That Violates a must Statement . 185 - 14.5. Error Message for Data That Violates a require-instance - Statement . . . . . . . . . . . . . . . . . . . . . . . 186 - 14.6. Error Message for Data That Does Not Match a leafref - Type . . . . . . . . . . . . . . . . . . . . . . . . . . 186 - 14.7. Error Message for Data That Violates a mandatory choice - Statement . . . . . . . . . . . . . . . . . . . . . . . 186 - 14.8. Error Message for the "insert" Operation . . . . . . . . 186 - 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 187 - 15.1. Media type application/yang . . . . . . . . . . . . . . 188 - 15.2. Media type application/yin+xml . . . . . . . . . . . . . 189 - 16. Security Considerations . . . . . . . . . . . . . . . . . . . 191 - 17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191 - 18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192 - 19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192 - 19.1. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192 - 19.2. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192 - 19.3. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192 - 19.4. Version -03 . . . . . . . . . . . . . . . . . . . . . . 192 - 19.5. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193 - 19.6. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193 - 19.7. Version -00 . . . . . . . . . . . . . . . . . . . . . . 193 - 20. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 - 20.1. Normative References . . . . . . . . . . . . . . . . . . 194 - 20.2. Informative References . . . . . . . . . . . . . . . . . 195 + identifier" . . . . . . . . . . . . . . . . . . . . . . 153 + 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 153 + 10.4. Functions for the YANG Type "identityref" . . . . . . . 154 + 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 154 + 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 154 + 10.5. Functions for the YANG Type "enumeration" . . . . . . . 155 + 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 156 + 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 157 + 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 157 + 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 157 + 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 159 + 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 + 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 160 + 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 163 + 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 164 + 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 188 + 15.1. Error Message for Data That Violates a unique Statement 188 + 15.2. Error Message for Data That Violates a max-elements + Statement . . . . . . . . . . . . . . . . . . . . . . . 189 + 15.3. Error Message for Data That Violates a min-elements + Statement . . . . . . . . . . . . . . . . . . . . . . . 189 + 15.4. Error Message for Data That Violates a must Statement . 189 + 15.5. Error Message for Data That Violates a require-instance + Statement . . . . . . . . . . . . . . . . . . . . . . . 190 + 15.6. Error Message for Data That Does Not Match a leafref + Type . . . . . . . . . . . . . . . . . . . . . . . . . . 190 + 15.7. Error Message for Data That Violates a mandatory choice + Statement . . . . . . . . . . . . . . . . . . . . . . . 190 + 15.8. Error Message for the "insert" Operation . . . . . . . . 190 + 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 191 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 191 + 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191 + 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192 + 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192 + 20.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . 192 + 20.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192 + 20.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192 + 20.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192 + 20.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . 193 + 20.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193 + 20.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193 + 20.8. Version -00 . . . . . . . . . . . . . . . . . . . . . . 194 + 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 + 21.1. Normative References . . . . . . . . . . . . . . . . . . 194 + 21.2. Informative References . . . . . . . . . . . . . . . . . 195 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 196 1. Introduction - YANG is a data modeling language used to model configuration and - state data manipulated by the Network Configuration Protocol - (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. - YANG is used to model the operations and content layers of NETCONF - (see the NETCONF Configuration Protocol [RFC6241], Section 1.2). + YANG is a data modeling language originally designed to model + configuration and state data manipulated by the Network Configuration + Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF + notifications [RFC6241]. Since the publication of YANG version 1 + [RFC6020], YANG has been used or proposed to be used for other + protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI + [I-D.vanderstok-core-comi]). Further, other encodings than XML has + been propsed (e.g., JSON [I-D.ietf-netmod-yang-json]). - This document describes the syntax and semantics of the YANG - language, how the data model defined in a YANG module is represented - in the Extensible Markup Language (XML), and how NETCONF operations - are used to manipulate the data. + This document describes the syntax and semantics of version 1.1 of + the YANG language. It also describes how the data model defined in a + YANG module is represented in the Extensible Markup Language (XML), + and how NETCONF operations are used to manipulate the data. Other + protocols and encodings are possible, but out of scope for this + specification. 1.1. Summary of Changes from RFC 6020 This document defines version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification [RFC6020]. o Changed the YANG version from "1" to "1.1". o Made the "yang-version" statement mandatory. @@ -449,161 +451,172 @@ 2. Keywords The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119]. 3. Terminology + The following terms are used within this document: + o action: An operation defined for a node in the data tree. o anydata: A data node that can contain an unknown set of nodes that can be modelled by YANG. o anyxml: A data node that can contain an unknown chunk of XML data. o augment: Adds new schema nodes to a previously defined schema node. o base type: The type from which a derived type was derived, which may be either a built-in type or another derived type. o built-in type: A YANG data type defined in the YANG language, such as uint32 or string. o choice: A schema node where only one of a number of identified alternatives is valid. - o configuration data: The set of writable data that is required to - transform a system from its initial default state into its current - state [RFC6241]. - o conformance: A measure of how accurately a device follows a data model. o container: An interior data node that exists in at most one instance in the data tree. A container has no value, but rather a set of child nodes. o data definition statement: A statement that defines new data nodes. One of container, leaf, leaf-list, list, choice, case, augment, uses, anydata, and anyxml. o data model: A data model describes how data is represented and accessed. o data node: A node in the schema tree that can be instantiated in a data tree. One of container, leaf, leaf-list, list, anydata, and anyxml. - o data tree: The instantiated tree of configuration and state data - on a device. + o data tree: An instantiated tree of any data modeled with YANG, + e.g., configuration data, state data, combined configuration and + state data, RPC or action input, RPC or action output, or + notification. o derived type: A type that is derived from a built-in type (such as uint32), or another derived type. o device deviation: A failure of the device to implement the module faithfully. o extension: An extension attaches non-YANG semantics to statements. The extension statement defines new statements to express these semantics. o feature: A mechanism for marking a portion of the model as optional. Definitions can be tagged with a feature name and are only valid on devices that support that feature. o grouping: A reusable set of schema nodes, which may be used - locally in the module, in modules that include it, 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. + locally in the module and by other modules that import from it. + The grouping statement is not a data definition statement and, as + such, does not define any nodes in the schema tree. o identifier: Used to identify different kinds of YANG items by name. o instance identifier: A mechanism for identifying a particular node 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 value but no child nodes. o list: An interior data node that may exist in multiple instances in the data tree. A list has no value, but rather a set of child nodes. - o module: A YANG module defines a hierarchy of nodes that can be - used for NETCONF-based operations. With its definitions and the - definitions it imports or includes from elsewhere, a module is - self-contained and "compilable". + o module: A YANG module defines a hierarchy of schema nodes. With + its definitions and the definitions it imports or includes from + elsewhere, a module is self-contained and "compilable". - o RPC: A Remote Procedure Call, as used within the NETCONF protocol. + o RPC: A Remote Procedure Call. - o RPC operation: A specific Remote Procedure Call, as used within - the NETCONF protocol. It is also called a protocol operation. + o RPC operation: A specific Remote Procedure Call. o schema node: A node in the schema tree. One of action, container, leaf, leaf-list, list, choice, case, rpc, input, output, notification, anydata, and anyxml. o schema node identifier: A mechanism for identifying a particular node in the schema tree. o schema tree: The definition hierarchy specified within a module. - o state data: The additional data on a system that is not - configuration data such as read-only status information and - collected statistics [RFC6241]. - o submodule: A partial module definition that contributes derived types, groupings, data nodes, RPCs, actions, and notifications to a module. A YANG module can be constructed from a number of submodules. o top-level data node: A data node where there is no other data node between it and a module or submodule statement. o uses: The "uses" statement is used to instantiate the set of schema nodes defined in a grouping statement. The instantiated nodes may be refined and augmented to tailor them to any specific needs. + The following terms are defined in [RFC6241]: + + o client + + o configuration data + o configuration datastore: a configuration datastore is an + instantiated data tree with configuration data + + o datastore: an instantiated data tree + + o running configuration datastore + + o server + + o state data + 3.1. Mandatory Nodes A mandatory node is one of: o A leaf, choice, anydata, or anyxml node with a "mandatory" statement with the value "true". o A list or leaf-list node with a "min-elements" statement with a value greater than zero. o A container node without a "presence" statement, which has at least one mandatory node as a child. 4. YANG Overview 4.1. Functional Overview - YANG is a language used to model data for the NETCONF protocol. A - YANG module defines a hierarchy of data that can be used for NETCONF- - based operations, including configuration, state data, Remote - Procedure Calls (RPCs), and notifications. This allows a complete - description of all data sent between a NETCONF client and server. + YANG is a language originally designed to model data for the NETCONF + protocol. A YANG module defines a hierarchy of data that can be used + for NETCONF-based operations, including configuration, state data, + Remote Procedure Calls (RPCs), and notifications. This allows a + complete description of all data sent between a NETCONF client and + server. Altough out of scope for this specification, YANG can also + be used for other protocols than NETCONF. YANG models the hierarchical organization of data as a tree in which each node has a name, and either a value or a set of child nodes. YANG provides clear and concise descriptions of the nodes, as well as the interaction between those nodes. YANG structures data models into modules and submodules. A module can import data from other external modules, and include data from submodules. The hierarchy can be augmented, allowing one module to add data nodes to the hierarchy defined in another module. This @@ -619,32 +632,31 @@ YANG defines a set of built-in types, and has a type mechanism through which additional types may be defined. Derived types can restrict their base type's set of valid values using mechanisms like range or pattern restrictions that can be enforced by clients or servers. They can also define usage conventions for use of the derived type, such as a string-based type that contains a host name. YANG permits the definition of reusable groupings of nodes. The instantiation of these groupings can refine or augment the nodes, allowing it to tailor the nodes to its particular needs. Derived - types and groupings can be defined in one module or submodule and - used in either that location or in another module or submodule that - imports or includes it. + types and groupings can be defined in one module and used in either + the same module or in another module that imports it. YANG data hierarchy constructs include defining lists where list entries are identified by keys that distinguish them from each other. Such lists may be defined as either sorted by user or automatically sorted by the system. For user-sorted lists, operations are defined for manipulating the order of the list entries. YANG modules can be translated into an equivalent XML syntax called - YANG Independent Notation (YIN) (Section 12), allowing applications + YANG Independent Notation (YIN) (Section 13), allowing applications using XML parsers and Extensible Stylesheet Language Transformations (XSLT) scripts to operate on the models. The conversion from YANG to YIN is lossless, so content in YIN can be round-tripped back into YANG. YANG strikes a balance between high-level data modeling and low-level bits-on-the-wire encoding. The reader of a YANG module can see the high-level view of the data model while understanding how the data will be encoded in NETCONF operations. @@ -682,84 +694,86 @@ 4.2.1. Modules and Submodules A module contains three types of statements: module-header statements, revision statements, and definition statements. The module header statements describe the module and give information about the module itself, the revision statements give information about the history of the module, and the definition statements are the body of the module where the data model is defined. - A NETCONF server may implement a number of modules, allowing multiple - views of the same data, or multiple views of disjoint subsections of - the device's data. Alternatively, the server may implement only one + A device may implement a number of modules, allowing multiple views + of the same data, or multiple views of disjoint subsections of the + device's data. Alternatively, the server may implement only one module that defines all available data. A module may be divided into submodules, based on the needs of the module owner. The external view remains that of a single module, regardless of the presence or size of its submodules. The "import" statement allows a module or submodule to reference material defined in other modules. The "include" statement is used by a module to incorporate the contents of its submodules into the module. 4.2.2. Data Modeling Basics YANG defines four types of nodes for data modeling. In each of the - following subsections, the example shows the YANG syntax as well as a + following subsections, the examples show the YANG syntax as well as a corresponding NETCONF XML representation. 4.2.2.1. Leaf Nodes - A leaf node contains simple data like an integer or a string. It has - exactly one value of a particular type and no child nodes. + A leaf instance contains simple data like an integer or a string. It + has exactly one value of a particular type and no child nodes. YANG Example: leaf host-name { type string; - description "Hostname for this system"; + description + "Hostname for this system"; } NETCONF XML Example: my.example.com The "leaf" statement is covered in Section 7.6. 4.2.2.2. Leaf-List Nodes A leaf-list defines a sequence of values of a particular type. YANG Example: leaf-list domain-search { type string; - description "List of domain names to search"; + description + "List of domain names to search"; } NETCONF XML Example: high.example.com low.example.com everywhere.example.com The "leaf-list" statement is covered in Section 7.7. 4.2.2.3. Container Nodes - A container node is used to group related nodes in a subtree. A - container has only child nodes and no value. A container may contain - any number of child nodes of any type (including leafs, lists, - containers, and leaf-lists). + A container is used to group related nodes in a subtree. A container + has only child nodes and no value. A container may contain any + number of child nodes of any type (leafs, lists, containers, leaf- + lists, and actions). YANG Example: container system { container login { leaf message { type string; description "Message given at start of login session"; } @@ -834,26 +848,28 @@ description "The module for entities implementing the ACME system."; revision 2007-06-09 { description "Initial revision."; } container system { leaf host-name { type string; - description "Hostname for this system"; + description + "Hostname for this system"; } leaf-list domain-search { type string; - description "List of domain names to search"; + description + "List of domain names to search"; } container login { leaf message { type string; description "Message given at start of login session"; } list user { @@ -869,23 +885,23 @@ } } } } } 4.2.3. State Data YANG can model state data, as well as configuration data, based on the "config" statement. When a node is tagged with "config false", - its subhierarchy is flagged as state data, to be reported using - NETCONF's operation, not the operation. Parent - containers, lists, and key leafs are reported also, giving the + its subhierarchy is flagged as state data. In NETCONF, state data is + reported using the operation, not the operation. + Parent containers, lists, and key leafs are reported also, giving the context for the state data. In this example, two leafs are defined for each interface, a configured speed and an observed speed. The observed speed is not configuration, so it can be returned with NETCONF operations, but not with operations. The observed speed is not configuration data, and it cannot be manipulated using . list interface { key "name"; @@ -946,21 +962,20 @@ type, allowing a hierarchy of derived types. A derived type can be used as the argument for the "type" statement. YANG Example: typedef percent { type uint8 { range "0 .. 100"; } - description "Percentage"; } leaf completed { type percent; } NETCONF XML Example: 20 @@ -1034,23 +1049,23 @@ "choice" statement contains a set of "case" statements that define sets of schema nodes that cannot appear together. Each "case" may contain multiple nodes, but each node may appear in only one "case" under a "choice". When a node from one case is created in the data tree, all nodes from all other cases are implicitly deleted. The device handles the enforcement of the constraint, preventing incompatibilities from existing in the configuration. - The choice and case nodes appear only in the schema tree, not in the - data tree or NETCONF messages. The additional levels of hierarchy - are not needed beyond the conceptual schema. + The choice and case nodes appear only in the schema tree but not in + the data tree. The additional levels of hierarchy are not needed + beyond the conceptual schema. YANG Example: container food { choice snack { case sports-arena { leaf pretzel { type empty; } leaf beer { @@ -1152,33 +1167,74 @@ The image acmefw-2.3 is being installed. + YANG Example: + + list interface { + key "name"; + + leaf name { + type string; + } + + action ping { + input { + leaf destination { + type inet:ip-address; + } + } + output { + leaf packet-loss { + type uint8; + } + } + } + } + + NETCONF XML Example: + + + + eth1 + + 192.0.2.1 + + + + + + 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 suitable for NETCONF. - YANG data definition statements are used to model the content of the - notification. + YANG allows the definition of notifications. YANG data definition + statements are used to model the content of the notification. YANG Example: notification link-failure { - description "A link failure has been detected"; + description + "A link failure has been detected"; leaf if-name { type leafref { path "/interface/name"; } } leaf if-admin-status { type admin-status; } leaf if-oper-status { type oper-status; @@ -1235,31 +1291,31 @@ o For a module or submodule to reference definitions in an external module, the external module MUST be imported. o A module MUST include all its submodules. o A module or submodule belonging to that module can reference definitions in the module and all submodules included by the module. - There MUST NOT be any circular chains of imports or includes. For - example, if module "a" imports module "b", "b" cannot import "a". + There MUST NOT be any circular chains of imports. For example, if + module "a" imports module "b", "b" cannot import "a". When a definition in an external module is referenced, a locally defined prefix MUST be used, followed by ":", and then the external identifier. References to definitions in the local module MAY use the prefix notation. Since built-in data types do not belong to any module and have no prefix, references to built-in data types (e.g., int32) cannot use the prefix notation. The syntax for a reference to a definition is formally defined by the rule "identifier-ref" in - Section 13. + Section 14. 5.1.1. Import and Include by Revision Published modules evolve independently over time. In order to allow for this evolution, modules need to be imported using specific revisions. When a module is written, it uses the current revisions of other modules, based on what is available at the time. As future revisions of the imported modules are published, the importing module is unaffected and its contents are unchanged. When the author of the module is prepared to move to the most recently published revision of @@ -1285,40 +1341,42 @@ leaf eh { .... } } } module b { yang-version 1.1; namespace "http://example.com/b"; prefix "b"; import a { - prefix p; + prefix "p"; revision-date 2008-01-01; } container bee { uses p:a; } } When the author of "a" publishes a new revision, the changes may not be acceptable to the author of "b". If the new revision is acceptable, the author of "b" can republish with an updated revision in the "import" statement. 5.1.2. Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may have more than one top-level node. Models that have multiple top- level nodes are sometimes convenient, and are supported by YANG. +5.1.2.1. NETCONF XML Encoding + NETCONF is capable of carrying any XML content as the payload in the and elements. The top-level nodes of YANG modules are encoded as child elements, in any order, within these elements. This encapsulation guarantees that the corresponding NETCONF messages are always well-formed XML documents. For example: module my-config { yang-version 1.1; @@ -1349,38 +1407,34 @@ 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: module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) - YANG compilers can find imported modules and included submodules via - this convention. While the YANG language defines modules, tools may - compile submodules independently for performance and manageability - reasons. Errors and warnings that cannot be detected during - submodule compilation may be delayed until the submodules are linked - into a cohesive module. + YANG parsers can find imported modules and included submodules via + this convention. 5.3. XML Namespaces All YANG definitions are specified within a module that is bound to a particular XML namespace [XML-NAMES], which is a globally unique URI [RFC3986]. A NETCONF client or server uses the namespace during XML encoding of data. - Namespaces for modules published in RFC streams [RFC4844] MUST be - assigned by IANA, see Section 15. + XML namespaces for modules published in RFC streams [RFC4844] MUST be + assigned by IANA, see section 14 in [RFC6020]. - Namespaces for private modules are assigned by the organization + XML namespaces for private modules are assigned by the organization owning the module without a central registry. Namespace URIs MUST be chosen so they cannot collide with standard or other enterprise namespaces, for example by using the enterprise or organization name in the namespace. The "namespace" statement is covered in Section 7.1.3. 5.3.1. YANG XML Namespace YANG defines an XML namespace for NETCONF operations, @@ -1423,23 +1477,23 @@ pieces of their module are presented to the outside world, supporting the need to hide internal information and maintaining a boundary between what is shared with the outside world and what is kept private. Scoped definitions MUST NOT shadow definitions at a higher scope. A type or grouping cannot be defined if a higher level in the schema hierarchy has a definition with a matching identifier. A reference to an unprefixed type or grouping, or one which uses the - prefix of the current module, is resolved by locating the closest - matching "typedef" or "grouping" statement among the immediate - substatements of each ancestor statement. + prefix of the current module, is resolved by locating the matching + "typedef" or "grouping" statement among the immediate substatements + of each ancestor statement. 5.6. Conformance Conformance is a measure of how accurately a device follows the model. Generally speaking, devices are responsible for implementing the model faithfully, allowing applications to treat devices which implement the model identically. Deviations from the model can reduce the utility of the model and increase fragility of applications that use it. @@ -1448,21 +1502,21 @@ o the basic behavior of the model o optional features that are part of the model o deviations from the model We will consider each of these in sequence. 5.6.1. Basic Behavior - The model defines a contract between the NETCONF client and server, + The model defines a contract between a YANG-based client and server, which allows both parties to have faith the other knows the syntax and semantics behind the modeled data. The strength of YANG lies in the strength of this contract. 5.6.2. Optional Features In many models, the modeler will allow sections of the model to be conditional. The device controls whether these conditional portions of the model are supported or valid for that particular device. @@ -1515,21 +1569,21 @@ takes as its argument a string that identifies a node in the schema tree. The contents of the statement details the manner in which the device implementation deviates from the contract as defined in the module. Further details are available in Section 7.20.3. 5.6.4. Implementing a Module A server implements a module if it implements the module's data - nodes, rpcs, notifications, and deviations. + nodes, rpcs, actions, notifications, and deviations. A server MUST NOT implement more than one revision of a module. If a server implements a module A that imports a module B, and A uses any node from B in an "augment" or "path" statement that the server supports, then the server MUST implement a revision of module B that has these nodes defined. This is regardless of if module B is imported by revision or not. NOTE: The next paragraph needs to be aligned with @@ -1545,31 +1599,30 @@ 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"; prefix "a"; - import b { revision-date 2015-01-01; } import c; revision 2015-01-01; feature foo; - augement "/b:x" { + augment "/b:x" { if-feature foo; leaf y { type b:myenum; } } container a { leaf x { type c:bar; } @@ -1636,21 +1689,20 @@ b 2015-04-04 implement c 2015-02-02 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 @@ -1664,44 +1716,44 @@ 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. With this mechanism, a client can cache the supported modules for a server, and only update the cache if the "module-set-id" value in the message changes. -5.7. Data Store Modification +5.7. Datastore Modification - Data models may allow the server to alter the configuration data - store in ways not explicitly directed via NETCONF protocol messages. - For example, a data model may define leafs that are assigned system- + Data models may allow the server to alter the configuration datastore + in ways not explicitly directed via NETCONF protocol messages. For + example, a data model may define leafs that are assigned system- generated values when the client does not provide one. A formal mechanism for specifying the circumstances where these changes are allowed is out of scope for this specification. 6. YANG Syntax The YANG syntax is similar to that of SMIng [RFC3780] and programming languages like C and C++. This C-like syntax was chosen specifically for its readability, since YANG values the time and effort of the readers of models above those of modules writers and YANG tool-chain developers. This section introduces the YANG syntax. YANG modules use the UTF-8 [RFC3629] character encoding. Legal characters in YANG modules are the Unicode and ISO/IEC 10646 [ISO.10646] characters, including tab, carriage return, and line feed but excluding the other C0 control characters, the surrogate blocks, and the noncharacters. The character syntax is formally defined by - the rule "yang-char" in Section 13. + the rule "yang-char" in Section 14. 6.1. Lexical Tokenization YANG modules are parsed as a series of tokens. This section details the rules for recognizing tokens from an input stream. YANG tokenization rules are both simple and powerful. The simplicity is driven by a need to keep the parsers easy to implement, while the power is driven by the fact that modelers need to express their models in readable formats. @@ -1748,22 +1800,23 @@ \t a tab character \" a double quote \\ a single backslash It is an error if any other character follows the backslash character. If a quoted string is followed by a plus character ("+"), followed by another quoted string, the two strings are concatenated into one string, allowing multiple concatenations to build one string. - Whitespace trimming and substitution of backslash-escaped characters - in double-quoted strings is done before concatenation. + Whitespace trimming is done before substitution of backslash-escaped + characters in double-quoted strings. Concatenation is performed as + the last step. 6.1.3.1. Quoting Examples The following strings are equivalent: hello "hello" 'hello' "hel" + "lo" 'hel' + "lo" @@ -1788,23 +1841,24 @@ "first line\n" + " second line" 6.2. Identifiers Identifiers are used to identify different kinds of YANG items by name. Each identifier starts with an uppercase or lowercase ASCII letter or an underscore character, followed by zero or more ASCII letters, digits, underscore characters, hyphens, and dots. Implementations MUST support identifiers up to 64 characters in - length. Identifiers are case sensitive. The identifier syntax is - formally defined by the rule "identifier" in Section 13. Identifiers - can be specified as quoted or unquoted strings. + length, and MAY support longer identifiers. Identifiers are case + sensitive. The identifier syntax is formally defined by the rule + "identifier" in Section 14. Identifiers can be specified as quoted + or unquoted strings. 6.2.1. Identifiers and Their Namespaces Each identifier is valid in a namespace that depends on the type of the YANG item being defined. All identifiers defined in a namespace MUST be unique. o All module and submodule names share the same global module identifier namespace. @@ -1859,41 +1914,56 @@ A module can introduce YANG extensions by using the "extension" keyword (see Section 7.19). The extensions can be imported by other modules with the "import" statement (see Section 7.1.5). When an imported extension is used, the extension's keyword MUST be qualified using the prefix with which the extension's module was imported. If an extension is used in the module where it is defined, the extension's keyword MUST be qualified with the module's prefix. If a YANG compiler does not support a particular extension, which - appears in a YANG module as an unknown-statement (see Section 13), + appears in a YANG module as an unknown-statement (see Section 14), the entire unknown-statement MAY be ignored by the compiler. + If a YANG parser does not support a particular extension, which + appears in a YANG module as an unknown-statement (see Section 14), + the entire unknown-statement MAY be ignored by the parser. Note that + even in this case the semantics associated with the extension still + apply (as if they were part of a description statement). + + Care must be taken when defining extensions so that modules that use + the extensions are meaningful also for applications that do not + support the extensions. + 6.4. XPath Evaluations YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation - for specifying many inter-node references and dependencies. NETCONF - clients and servers are not required to implement an XPath - interpreter, but MUST ensure that the requirements encoded in the - data model are enforced. The manner of enforcement is an - implementation decision. The XPath expressions MUST be syntactically - correct, and all prefixes used MUST be present in the XPath context - (see Section 6.4.1). An implementation may choose to implement them - by hand, rather than using the XPath expression directly. + for specifying many inter-node references and dependencies. An + implementation is not required to implement an XPath interpreter, but + MUST ensure that the requirements encoded in the data model are + enforced. The manner of enforcement is an implementation decision. + The XPath expressions MUST be syntactically correct, and all prefixes + used MUST be present in the XPath context (see Section 6.4.1). An + implementation may choose to implement them by hand, rather than + using the XPath expression directly. The data model used in the XPath expressions is the same as that used in XPath 1.0 [XPATH], with the same extension for root node children as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means that the root node may have any number of element nodes as its children. + The data tree has no concept of document order. An implementation + needs to choose some document order but how it is done is an + implementation decision. This means that XPath expressions in YANG + modules SHOULD not rely on any specific document order. + Numbers in XPath 1.0 are IEEE 754 double-precision floating-point values, see Section 3.5 in [XPATH]. This means that some values of int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) cannot be exactly represented in XPath expressions. Therefore, due caution should be exercised when using nodes with 64-bit numeric values in XPath expressions. In particular, numerical comparisons involving equality may yield unexpected results. For example, consider the following definition: @@ -1933,69 +2003,70 @@ The mechanism for handling unprefixed names is adopted from XPath 2.0 [XPATH2.0], and helps simplify XPath expressions in YANG. No ambiguity may ever arise because YANG node identifiers are always qualified names with a non-null namespace URI. The accessible tree depends on where the statement with the XPath expression is defined: o If the XPath expression is defined in substatement to a data node that represents configuration, the accessible tree is the data in - the NETCONF datastore where the context node exists. The root - node has all top-level configuration data nodes in all modules as - children. + the datastore where the context node exists. The root node has + all top-level configuration data nodes in all modules as children. o If the XPath expression is defined in a substatement to a data - node that represents state data, the accessible tree is all all - state data on the device, and the "running" datastore. The root - node has all top-level data nodes in all modules as children. + node that represents state data, the accessible tree is all state + data on the device, and the running configuration datastore. The + root node has all top-level data nodes in all modules as children. o If the XPath expression is defined in a substatement to a "notification" statement, the accessible tree is the notification - instance, all state data on the device, and the "running" - datastore. The root node has the node representing the - notification being defined and all top-level data nodes in all + instance, all state data on the device, and the running + configuration datastore. The root node has the node representing + the notification being defined and all top-level data nodes in all modules as children. o If the XPath expression is defined in a substatement to an "input" - statement in an "rpc" statement, the accessible tree is the RPC - operation instance, all state data on the device, and the - "running" datastore. The root node has the node representing the - operation being defined and all top-level data nodes in all - modules as children. The node representing the operation being - defined has the operation's input parameters as children. + statement in an "rpc" or "action" statement, the accessible tree + is the RPC or action operation instance, all state data on the + device, and the running configuration datastore. The root node + has the node representing the operation being defined and all top- + level data nodes in all modules as children. The node + representing the operation being defined has the operation's input + parameters as children. o If the XPath expression is defined in a substatement to an - "output" statement in an "rpc" statement, the accessible tree is - the RPC operation's output, all state data on the device, and the - "running" datastore. The root node has the node representing the - operation being defined and all top-level data nodes in all - modules as children. The node representing the operation being - defined has the operation's output parameters as children. + "output" statement in an "rpc" or "action" statement, the + accessible tree is the RPC or action operation's output, all state + data on the device, and the running configuration datastore. The + root node has the node representing the operation being defined + and all top-level data nodes in all modules as children. The node + representing the operation being defined has the operation's + output parameters as children. In the accessible tree, all leafs and leaf-lists with default values in use exist (See Section 7.6.1 and Section 7.7.2). If a node that exists in the accessible tree has a non-presence container as a child, then the non-presence container also exists in the tree. The context node varies with the YANG XPath expression, and is specified where the YANG statement with the XPath expression is defined. 6.5. Schema Node Identifier A schema node identifier is a string that identifies a node in the schema tree. It has two forms, "absolute" and "descendant", defined by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" - in Section 13, respectively. A schema node identifier consists of a + in Section 14, respectively. A schema node identifier consists of a path of identifiers, separated by slashes ("/"). In an absolute schema node identifier, the first identifier after the leading slash is any top-level schema node in the local module or in all imported modules. References to identifiers defined in external modules MUST be qualified with appropriate prefixes, and references to identifiers defined in the current module and its submodules MAY use a prefix. For example, to identify the child node "b" of top-level node "a", @@ -2017,21 +2088,21 @@ 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. Names of modules published in RFC streams [RFC4844] MUST be assigned - by IANA, see Section 15. + by IANA, see section 14 in [RFC6020]. Private module names are assigned by the organization owning the module without a central registry. It is RECOMMENDED to choose module names that will have a low probability of colliding with standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix for the module name. A module typically has the following layout: module { @@ -2100,20 +2171,22 @@ A module or submodule that doesn't contain the "yang-version" statement, or one that contains the value "1", is developed for YANG version 1, defined in [RFC6020]. Handling of the "yang-version" statement for versions other than "1.1" (the version defined here) is out of scope for this specification. Any document that defines a higher version will need to define the backward compatibility of such a higher version. + For compatibility between YANG version 1 and 1.1, see Section 12. + 7.1.3. The namespace Statement The "namespace" statement defines the XML namespace that all identifiers defined by the module are qualified by, with the exception of data node identifiers defined inside a grouping (see Section 7.13 for details). The argument to the "namespace" statement is the URI of the namespace. See also Section 5.3. @@ -2186,34 +2259,30 @@ +---------------+---------+-------------+ | prefix | 7.1.4 | 1 | | revision-date | 7.1.5.1 | 0..1 | +---------------+---------+-------------+ The import's Substatements 7.1.5.1. The import's revision-date Statement The import's "revision-date" statement is used to specify the exact - version of the module to import. The "revision-date" statement MUST - match the most recent "revision" statement in the imported module. + version of the module to import. 7.1.6. The include Statement The "include" statement is used to make content from a submodule available to that submodule's parent module. The argument is an identifier that is the name of the submodule to include. Modules are only allowed to include submodules that belong to that module, as defined by the "belongs-to" statement (see Section 7.2.2). - Submodules are only allowed to include other submodules belonging to - the same module. - When a module includes a submodule, it incorporates the contents of the submodule into the node hierarchy of the module. For backward compatibility with YANG version 1, a submodule is allowed to include another submodule belonging to the same module, but this is not necessary in YANG version 1.1. When the optional "revision-date" substatement is present, the specified revision of the submodule is included in the module. It is an error if the specified revision of the submodule does not exist. @@ -2310,21 +2379,21 @@ module that includes the submodules. The "submodule" statement defines the submodule's name, and groups all statements that belong to the submodule together. The "submodule" statement's argument is the name of the submodule, followed by a block of substatements that hold detailed submodule information. The submodule name follows the rules for identifiers in Section 6.2. Names of submodules published in RFC streams [RFC4844] MUST be - assigned by IANA, see Section 15. + assigned by IANA, see section 14 in [RFC6020]. Private submodule names are assigned by the organization owning the submodule without a central registry. It is RECOMMENDED to choose submodule names that will have a low probability of colliding with standard or other enterprise modules and submodules, e.g., by using the enterprise or organization name as a prefix for the submodule name. A submodule typically has the following layout: @@ -2540,37 +2609,38 @@ information. A container node does not have a value, but it has a list of child nodes in the data tree. The child nodes are defined in the container's substatements. 7.5.1. Containers with Presence YANG supports two styles of containers, those that exist only for organizing the hierarchy of data nodes, and those whose presence in - the configuration has an explicit meaning. + the data tree has an explicit meaning. In the first style, the container has no meaning of its own, existing only to contain child nodes. This is the default style. For example, the set of scrambling options for Synchronous Optical Network (SONET) interfaces may be placed inside a "scrambling" container to enhance the organization of the configuration hierarchy, and to keep these nodes together. The "scrambling" node itself has no meaning, so removing the node when it becomes empty relieves the user from performing this task. - In the second style, the presence of the container itself is - configuration data, representing a single bit of configuration data. - The container acts as both a configuration knob and a means of - organizing related configuration. These containers are explicitly - created and deleted. + In the second style, the presence of the container itself carries + some meaning, representing a single bit of data. + + In configuration data, the container acts as both a configuration + knob and a means of organizing related configuration. These + containers are explicitly created and deleted. YANG calls this style a "presence container" and it is indicated using the "presence" statement, which takes as its argument a text string indicating what the presence of the node means. For example, an "ssh" container may turn on the ability to log into the device using ssh, but can also contain any ssh-related configuration knobs, such as connection rates or retry limits. The "presence" statement (see Section 7.5.5) is used to give @@ -2689,30 +2759,30 @@ no meaning by itself. See Section 7.5.1 for additional information. 7.5.6. The container's Child Node Statements Within a container, the "container", "leaf", "list", "leaf-list", "uses", "choice", "anydata", and "anyxml" statements can be used to define child nodes to the container. -7.5.7. XML Mapping Rules +7.5.7. XML Encoding Rules A container node is encoded as an XML element. The element's local name is the container's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The container's child nodes are encoded as subelements to the - container element. If the container defines RPC input or output - parameters, these subelements are encoded in the same order as they - are defined within the "container" statement. Otherwise, the + container element. If the container defines RPC or action input or + output parameters, these subelements are encoded in the same order as + they are defined within the "container" statement. Otherwise, the subelements are encoded in any order. A NETCONF server that replies to a or request MAY choose not to send a container element if the container node does not have the "presence" statement and no child nodes exist. Thus, a client that receives an for a or request, must be prepared to handle the case that a container node without a "presence" statement is not present in the XML. 7.5.8. NETCONF Operations @@ -2735,26 +2805,29 @@ returned. If the operation is "delete", the node is deleted if it exists. If the node does not exist, a "data-missing" error is returned. 7.5.9. Usage Example Given the following container definition: container system { - description "Contains various system parameters"; + description + "Contains various system parameters"; container services { - description "Configure externally available services"; + description + "Configure externally available services"; container "ssh" { presence "Enables SSH"; - description "SSH service specific configuration"; + description + "SSH service specific configuration"; // more leafs, containers and stuff here... } } } A corresponding XML instance example: @@ -2877,21 +2950,21 @@ exist. o Otherwise, if this ancestor is a case node, the leaf MUST exist if any node from the case exists in the data tree. o Otherwise, the leaf MUST exist if the ancestor node exists in the data tree. This constraint is enforced according to the rules in Section 8. -7.6.6. XML Mapping Rules +7.6.6. XML Encoding Rules A leaf node is encoded as an XML element. The element's local name is the leaf's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of the leaf node is encoded to XML according to the type, and sent as character data in the element. A NETCONF server that replies to a or request MAY choose not to send the leaf element if its value is the default @@ -2919,21 +2992,22 @@ If the node does not exist, a "data-missing" error is returned. 7.6.8. Usage Example Given the following "leaf" statement, placed in the previously defined "ssh" container (see Section 7.5.9): leaf port { type inet:port-number; default 22; - description "The port to which the SSH server listens" + description + "The port to which the SSH server listens" } A corresponding XML instance example: 2022 To set the value of a leaf with an : operation that allows the order of list entries in user-ordered lists to be controlled. List entries may be inserted or rearranged, positioned as the first or last entry in the list, or positioned before or after another specific entry. @@ -3121,34 +3195,34 @@ like "diff". This is the default order. 7.7.7.2. ordered-by user The entries in the list are sorted according to an order defined by the user. This order is controlled by using special XML attributes in the request. See Section 7.7.9 for details. -7.7.8. XML Mapping Rules +7.7.8. XML Encoding Rules A leaf-list node is encoded as a series of XML elements. Each element's local name is the leaf-list's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of each leaf-list entry is encoded to XML according to the type, and sent as character data in the element. The XML elements representing leaf-list entries MUST appear in the order specified by the user if the leaf-list is "ordered-by user"; otherwise, the order is implementation-dependent. The XML elements representing leaf-list entries MAY be interleaved with other sibling - elements, unless the leaf-list defines RPC input or output + elements, unless the leaf-list defines RPC or action input or output parameters. See Section 7.7.10 for an example. 7.7.9. NETCONF Operations Leaf-list entries can be created and deleted, but not modified, through , by using the "operation" attribute in the leaf-list entry's XML element. @@ -3186,21 +3260,22 @@ "data-exists" error is returned. If the operation is "delete", the entry is deleted from the leaf- list if it exists. If the leaf-list entry does not exist, a "data-missing" error is returned. 7.7.10. Usage Example leaf-list allow-user { type string; - description "A list of user name patterns to allow"; + description + "A list of user name patterns to allow"; } A corresponding XML instance example: alice bob To create a new element in this list, using the default operation "merge": @@ -3221,21 +3296,22 @@ Given the following ordered-by user leaf-list: leaf-list cipher { type string; ordered-by user; - description "A list of ciphers"; + description + "A list of ciphers"; } The following would be used to insert a new cipher "blowfish-cbc" after "3des-cbc": @@ -3313,41 +3389,41 @@ leafs or their types are ignored. It also implies that any mandatory statement in the key leafs are ignored. A leaf that is part of the key can be of any built-in or derived type. All key leafs in a list MUST have the same value for their "config" as the list itself. The key string syntax is formally defined by the rule "key-arg" in - Section 13. + Section 14. 7.8.3. The list's unique Statement The "unique" statement is used to put constraints on valid list entries. It takes as an argument a string that contains a space- separated list of schema node identifiers, which MUST be given in the descendant form (see the rule "descendant-schema-nodeid" in - Section 13). Each such schema node identifier MUST refer to a leaf. + Section 14). Each such schema node identifier MUST refer to a leaf. If one of the referenced leafs represents configuration data, then all of the referenced leafs MUST represent configuration data. The "unique" constraint specifies that the combined values of all the leaf instances specified in the argument string, including leafs with default values, MUST be unique within all list entry instances in which all referenced leafs exist. The constraint is enforced according to the rules in Section 8. The unique string syntax is formally defined by the rule "unique-arg" - in Section 13. + in Section 14. 7.8.3.1. Usage Example With the following list: list server { key "name"; unique "ip port"; leaf name { type string; @@ -3393,41 +3469,41 @@ ftp 192.0.2.1 7.8.4. The list's Child Node Statements Within a list, the "container", "leaf", "list", "leaf-list", "uses", "choice", "anydata", and "anyxml" statements can be used to define child nodes to the list. -7.8.5. XML Mapping Rules +7.8.5. XML Encoding Rules A list is encoded as a series of XML elements, one for each entry in the list. Each element's local name is the list's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The list's key nodes are encoded as subelements to the list's identifier element, in the same order as they are defined within the "key" statement. The rest of the list's child nodes are encoded as subelements to the - list element, after the keys. If the list defines RPC input or - output parameters, the subelements are encoded in the same order as - they are defined within the "list" statement. Otherwise, the - subelements are encoded in any order. + list element, after the keys. If the list defines RPC or action + input or output parameters, the subelements are encoded in the same + order as they are defined within the "list" statement. Otherwise, + the subelements are encoded in any order. The XML elements representing list entries MUST appear in the order specified by the user if the list is "ordered-by user", otherwise the order is implementation-dependent. The XML elements representing list entries MAY be interleaved with other sibling elements, unless - the list defines RPC input or output parameters. + the list defines RPC or action input or output parameters. 7.8.6. NETCONF Operations List entries can be created, deleted, replaced, and modified through , by using the "operation" attribute in the list's XML element. In each case, the values of all keys are used to uniquely identify a list entry. If all keys are not specified for a list entry, a "missing-element" error is returned. In an "ordered-by user" list, the attributes "insert" and "key" in @@ -3471,21 +3547,22 @@ if it exists. If the list entry does not exist, a "data-missing" error is returned. 7.8.7. Usage Example Given the following list: list user { key "name"; config true; - description "This is a list of users in the system."; + description + "This is a list of users in the system."; leaf name { type string; } leaf type { type string; } leaf full-name { type string; } @@ -3536,101 +3613,105 @@ superuser Given the following ordered-by user list: list user { - description "This is a list of users in the system."; + description + "This is a list of users in the system."; ordered-by user; config true; - key "name"; + key "first-name surname"; - leaf name { + leaf first-name { type string; } - leaf type { + leaf surname { type string; } - leaf full-name { + leaf type { type string; } } - The following would be used to insert a new user "barney" after the - user "fred": + The following would be used to insert a new user "barney rubble" + after the user "fred flintstone": - barney + yang:key="[ex:first-name='fred'] + [ex:surname='flintstone']"> + barney + rubble admin - Barney Rubble - The following would be used to move the user "barney" before the user - "fred": + The following would be used to move the user "barney rubble" before + the user "fred flintstone": - barney + yang:key="[ex:name='fred'] + [ex:surname='flintstone']"> + barney + rubble 7.9. The choice Statement The "choice" statement defines a set of alternatives, only one of which may exist at any one time. The argument is an identifier, followed by a block of substatements that holds detailed choice information. The identifier is used to identify the choice node in the schema tree. A choice node does not exist in the data tree. A choice consists of a number of branches, defined with the "case" substatement. Each branch contains a number of child nodes. The nodes from at most one of the choice's branches exist at the same time. - See Section 8.3.2 for additional information. + See Section 8.2.2 for additional information. 7.9.1. The choice's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | case | 7.9.2 | 0..n | | choice | 7.9 | 0..n | | config | 7.21.1 | 0..1 | @@ -3666,22 +3747,24 @@ case a { leaf ethernet { ... } } case b { container ethernet { ...} } } As a shorthand, the "case" statement can be omitted if the branch contains a single "anydata", "anyxml", "choice", "container", "leaf", - "list", or "leaf-list" statement. In this case, the identifier of - the case node is the same as the identifier in the branch statement. + "list", or "leaf-list" statement. In this case, the case node still + exists in the schema tree, and its identifier is the same as the + identifier in the branch statement. Schema node identifiers + (Section 6.5) MUST always explicitly include case node identifiers. The following example: choice interface-type { container ethernet { ... } } is equivalent to: choice interface-type { case ethernet { @@ -3782,28 +3865,28 @@ container (see Section 7.5.1): o If this ancestor is a case node, the constraint is enforced if any other node from the case exists. o Otherwise, it is enforced if the ancestor node exists. The constraint is further enforced according to the rules in Section 8. -7.9.5. XML Mapping Rules +7.9.5. XML Encoding Rules The choice and case nodes are not visible in XML. The child nodes of the selected "case" statement MUST be encoded in the same order as they are defined in the "case" statement if they - are part of an RPC input or output parameter definition. Otherwise, - the subelements are encoded in any order. + are part of an RPC or action input or output parameter definition. + Otherwise, the subelements are encoded in any order. 7.9.6. NETCONF Operations Since only one of the choice's cases can be valid at any time, the creation of a node from one case implicitly deletes all nodes from all other cases. If an operation creates a node from a case, the NETCONF server will delete any existing nodes that are defined in other cases inside the choice. 7.9.7. Usage Example @@ -3858,40 +3941,43 @@ The "anydata" statement is used to represent an unknown set of nodes that can be modelled with YANG. An example of where this can be useful is a list of received notifications, where the exact notifications are not known as design time. An anydata node cannot be augmented (see Section 7.17). An anydata node exists in zero or one instances in the data tree. + An implementation may or may not know the data model used to model a + specific instance of an anydata node. + Since the use of anydata limits the manipulation of the content, it is RECOMMENDED that the "anydata" statement not be used to define configuration data. 7.10.1. The anydata's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | config | 7.21.1 | 0..1 | | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.10.2. XML Mapping Rules +7.10.2. XML Encoding Rules An anydata node is encoded as an XML element. The element's local name is the anydata's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of the anydata node is a set of nodes, which are encoded as XML subelements to the anydata element. 7.10.3. NETCONF Operations An anydata node is treated as an opaque chunk of data. This data can @@ -3979,21 +4065,21 @@ | config | 7.21.1 | 0..1 | | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | mandatory | 7.6.5 | 0..1 | | must | 7.5.3 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.11.2. XML Mapping Rules +7.11.2. XML Encoding Rules An anyxml node is encoded as an XML element. The element's local name is the anyxml's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). The value of the anyxml node is encoded as XML content of this element. Note that any XML prefixes used in the encoding are local to each instance encoding. This means that the same XML may be encoded differently by different implementations. @@ -4061,21 +4148,22 @@ If the grouping is defined at the top level of a YANG module or submodule, the grouping's identifier MUST be unique within the module. A grouping is more than just a mechanism for textual substitution, but defines a collection of nodes. Identifiers appearing inside the grouping are resolved relative to the scope in which the grouping is defined, not where it is used. Prefix mappings, type names, grouping names, and extension usage are evaluated in the hierarchy where the "grouping" statement appears. For extensions, this means that - extensions are applied to the grouping node, not the uses node. + extensions defined as direct children to a "grouping" statement are + applied to the grouping itself. 7.12.1. The grouping's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | action | 7.15 | 0..n | | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | @@ -4145,41 +4234,48 @@ exactly as it was defined in the grouping. The argument string is a descendant schema node identifier (see Section 6.5). The following refinements can be done: o A leaf or choice node may get a default value, or a new default value if it already had one. + o A leaf-list node may get a set of default values, or a new set of + default values if it already had defaults; i.e., the set of + refined default values replaces the defaults already given. + o Any node may get a specialized "description" string. o Any node may get a specialized "reference" string. o Any node may get a different "config" statement. o A leaf, anydata, anyxml, or choice node may get a different "mandatory" statement. o A container node may get a "presence" statement. o A leaf, leaf-list, list, container, anydata, or anyxml node may get additional "must" expressions. o A leaf-list or list node may get a different "min-elements" or "max-elements" statement. o A leaf, leaf-list, list, container, anydata, or anyxml node may get additional "if-feature" expressions. -7.13.3. XML Mapping Rules + o Any node can get refined extensions, if the extension allows + refinement. See Section 7.19 for details. + +7.13.3. XML Encoding Rules Each node in the grouping is encoded as if it was defined inline, even if it is imported from another module with another XML namespace. 7.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: @@ -4266,34 +4362,32 @@ +--------------+---------+-------------+ 7.14.2. The input Statement The "input" statement, which is optional, is used to define input parameters to the operation. It does not take an argument. The substatements to "input" define nodes under the operation's input node. If a leaf in the input tree has a "mandatory" statement with the - value "true", the leaf MUST be present in a NETCONF RPC invocation. - Otherwise, the server MUST return a "missing-element" error. + value "true", the leaf MUST be present in an RPC invocation. - If a leaf in the input tree has a default value, the NETCONF server - MUST use this value in the same cases as described in Section 7.6.1. - In these cases, the server MUST operationally behave as if the leaf - was present in the NETCONF RPC invocation with the default value as - its value. + If a leaf in the input tree has a default value, the server MUST use + this value in the same cases as described in Section 7.6.1. In these + cases, the server MUST operationally behave as if the leaf was + present in the RPC invocation with the default value as its value. If a leaf-list in the input tree has one or more default values, the - NETCONF server MUST use these values in the same cases as described - in Section 7.7.2. In these cases, the server MUST operationally - behave as if the leaf-list was present in the NETCONF RPC invocation - with the default values as its values. + server MUST use these values in the same cases as described in + Section 7.7.2. In these cases, the server MUST operationally behave + as if the leaf-list was present in the RPC invocation with the + default values as its values. If a "config" statement is present for any node in the input tree, the "config" statement is ignored. If any node has a "when" statement that would evaluate to false, then this node MUST NOT be present in the input tree. 7.14.2.1. The input's Substatements +--------------+---------+-------------+ @@ -4313,34 +4407,32 @@ +--------------+---------+-------------+ 7.14.3. The output Statement The "output" statement, which is optional, is used to define output parameters to the RPC operation. It does not take an argument. The substatements to "output" define nodes under the operation's output node. If a leaf in the output tree has a "mandatory" statement with the - value "true", the leaf MUST be present in a NETCONF RPC reply. - - If a leaf in the output tree has a default value, the NETCONF client - MUST use this value in the same cases as described in Section 7.6.1. + value "true", the leaf MUST be present in an RPC reply. - In these cases, the client MUST operationally behave as if the leaf - was present in the NETCONF RPC reply with the default value as its - value. + If a leaf in the output tree has a default value, the client MUST use + this value in the same cases as described in Section 7.6.1. In these + cases, the client MUST operationally behave as if the leaf was + present in the RPC reply with the default value as its value. If a leaf-list in the output tree has one or more default values, the - NETCONF client MUST use these values in the same cases as described - in Section 7.7.2. In these cases, the client MUST operationally - behave as if the leaf-list was present in the NETCONF RPC reply with - the default values as its values. + client MUST use these values in the same cases as described in + Section 7.7.2. In these cases, the client MUST operationally behave + as if the leaf-list was present in the RPC reply with the default + values as its values. If a "config" statement is present for any node in the output tree, the "config" statement is ignored. If any node has a "when" statement that would evaluate to false, then this node MUST NOT be present in the output tree. 7.14.3.1. The output's Substatements +--------------+---------+-------------+ @@ -4352,21 +4444,21 @@ | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.14.4. XML Mapping Rules +7.14.4. XML Encoding Rules An rpc node is encoded as a child XML element to the element defined in [RFC6241]. The element's local name is the rpc's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). Input parameters are encoded as child XML elements to the rpc node's XML element, in the same order as they are defined within the "input" statement. @@ -4427,26 +4519,25 @@ example, this means that it is an error if a grouping that contains an action somewhere in its node hierarchy is used in a notification definition. Since an action cannot be defined an the top-level of a module or in a case statement, it is an error if a grouping that contains an action at the top of its node hierarchy is used at the top-level of a module or in a case definition. The difference between an action and an rpc is that an action is tied - to a node in the data tree, whereas an rpc is not. When an action is - invoked, the node in the data tree is specified along with the name + to a node in the datastore, whereas an rpc is not. When an action is + invoked, the node in the datastore is specified along with the name of the action and the input parameters. 7.15.1. The action's Substatements - +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | input | 7.14.2 | 0..1 | | output | 7.14.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | @@ -4446,30 +4537,30 @@ | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | input | 7.14.2 | 0..1 | | output | 7.14.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+ -7.15.2. XML Mapping Rules +7.15.2. XML Encoding Rules When an action is invoked, an element with the local name "action" in the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is encoded as a child XML element to the element defined in [RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241]. The "action" element contains an hierarchy of nodes that identifies - the node in the data tree. It MUST contain all containers and list + the node in the datastore. It MUST contain all containers and list nodes from the top level down to the list or container containing the action. For lists, all key leafs MUST also be included. The last container or list contains an XML element that carries the name of the defined action. Within this element the input parameters are encoded as child XML elements, in the same order as they are defined within the "input" statement. Only one action can be invoked in one . If more than one action is present in the , the server MUST reply with an "bad-element" error-tag in the . @@ -4529,60 +4620,62 @@ 2014-07-29T13:42:00Z 2014-07-29T13:42:12Z - + 7.16. The notification Statement - The "notification" statement is used to define a NETCONF - notification. It takes one argument, which is an identifier, - followed by a block of substatements that holds detailed notification - information. The "notification" statement defines a notification - node in the schema tree. + 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 + tree. A notification can be defined at the top-level of a module, or connected to a specific container or list data node in the schema tree. A notification MUST NOT be defined within an rpc, action or another notification, i.e., a notification node MUST NOT have an rpc, action, or a notification node as one of its ancestors in the schema tree. For example, this means that it is an error if a grouping that contains an notification somewhere in its node hierarchy is used in an rpc definition. Since a notification cannot be defined in a case statement, it is an error if a grouping that contains a notification at the top of its node hierarchy is used in a case definition. If a leaf in the notification tree has a "mandatory" statement with - the value "true", the leaf MUST be present in a NETCONF notification. + the value "true", the leaf MUST be present in a notification + instance. - If a leaf in the notification tree has a default value, the NETCONF - client MUST use this value in the same cases as described in - Section 7.6.1. In these cases, the client MUST operationally behave - as if the leaf was present in the NETCONF notification with the - default value as its value. + If a leaf in the notification tree has a default value, the client + MUST use this value in the same cases as described in Section 7.6.1. + + In these cases, the client MUST operationally behave as if the leaf + was present in the notification instance with the default value as + its value. If a leaf-list in the notification tree has one or more default - values, the NETCONF client MUST use these values in the same cases as + values, the client MUST use these values in the same cases as described in Section 7.7.2. In these cases, the client MUST - operationally behave as if the leaf-list was present in the NETCONF - notification with the default values as its values. + operationally behave as if the leaf-list was present in the + notification instance with the default values as its values. If a "config" statement is present for any node in the notification tree, the "config" statement is ignored. 7.16.1. The notification's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | @@ -4595,32 +4688,32 @@ | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+ -7.16.2. XML Mapping Rules +7.16.2. XML Encoding Rules A notification node that is defined on the top-level of a module is encoded as a child XML element to the element defined in NETCONF Event Notifications [RFC5277]. The element's local name is the notification's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). When a notification node is defined as a child to a data node, the element defined in NETCONF Event Notifications [RFC5277] contains an hierarchy of nodes that identifies the node in - the data tree. It MUST contain all containers and list nodes from + the datastore. It MUST contain all containers and list nodes from the top level down to the list or container containing the notification. For lists, all key leafs MUST also be included. The last container or list contains an XML element that carries the name of the defined notification. The notification's child nodes are encoded as subelements to the notification node's XML element, in any order. 7.16.3. Usage Example @@ -4703,24 +4796,24 @@ its submodules, and to add to the nodes from a grouping in a "uses" statement. The argument is a string that identifies a node in the schema tree. This node is called the augment's target node. The target node MUST be either a container, list, choice, case, input, output, or notification node. It is augmented with the nodes defined in the substatements that follow the "augment" statement. The argument string is a schema node identifier (see Section 6.5). If the "augment" statement is on the top level in a module or submodule, the absolute form (defined by the rule - "absolute-schema-nodeid" in Section 13) of a schema node identifier + "absolute-schema-nodeid" in Section 14) of a schema node identifier MUST be used. If the "augment" statement is a substatement to the "uses" statement, the descendant form (defined by the rule - "descendant-schema-nodeid" in Section 13) MUST be used. + "descendant-schema-nodeid" in Section 14) MUST be used. If the target node is a container, list, case, input, output, or notification node, the "container", "leaf", "list", "leaf-list", "uses", and "choice" statements can be used within the "augment" statement. If the target node is a choice node, the "case" statement, or a case shorthand statement (see Section 7.9.2) can be used within the "augment" statement. @@ -4746,21 +4839,21 @@ | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | notification | 7.16 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | uses | 7.13 | 0..n | | when | 7.21.5 | 0..1 | +--------------+---------+-------------+ -7.17.2. XML Mapping Rules +7.17.2. XML Encoding Rules All data nodes defined in the "augment" statement are defined as XML elements in the XML namespace of the module where the "augment" is specified. When a node is augmented, the augmenting child nodes are encoded as subelements to the augmented node, in any order. 7.17.3. Usage Example @@ -4942,21 +5035,25 @@ The extension can be used like a normal YANG statement, with the statement name followed by an argument if one is defined by the "extension" statement, and an optional block of substatements. The statement's name is created by combining the prefix of the module in which the extension was defined, a colon (":"), and the extension's keyword, with no interleaving whitespace. The substatements of an extension are defined by the "extension" statement, using some mechanism outside the scope of this specification. Syntactically, the substatements MUST be YANG statements, or also extensions defined using "extension" statements. YANG statements in extensions MUST - follow the syntactical rules in Section 13. + follow the syntactical rules in Section 14. + + An extension can allow refinement (see Section 7.13.2) and deviations + (Section 7.20.3.2), but the mechanism for how this is defined is + outside the scope of this specification. 7.19.1. The extension's Substatements +--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | argument | 7.19.2 | 0..1 | | description | 7.21.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | @@ -4979,21 +5076,21 @@ | substatement | section | cardinality | +--------------+----------+-------------+ | yin-element | 7.19.2.2 | 0..1 | +--------------+----------+-------------+ 7.19.2.2. The yin-element Statement The "yin-element" statement, which is optional, takes as an argument the string "true" or "false". This statement indicates if the argument is mapped to an XML element in YIN or to an XML attribute - (see Section 12). + (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 { ... @@ -5098,21 +5195,21 @@ 7.20.2. The if-feature Statement The "if-feature" statement makes its parent statement conditional. The argument is a boolean expression over feature names. In this expression, a feature name evaluates to "true" if and only if the feature is implemented by the server. The parent statement is implemented by servers where the boolean expression evaluates to "true". The if-feature boolean expression syntax is formally defined by the - rule "if-feature-expr" in Section 13. When this boolean expression + rule "if-feature-expr" in Section 14. When this boolean expression is evaluated, the operator order of precedence is (highest precedence first): "not", "and", "or". If a prefix is present on a feature name in the boolean expression, the prefixed name refers to a feature defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. Otherwise, a feature with the matching name MUST be defined in the current module or an included submodule. A leaf that is a list key MUST NOT have any "if-feature" statements. @@ -5206,20 +5303,24 @@ | max-elements | 7.7.6 | 0..1 | | min-elements | 7.7.5 | 0..1 | | must | 7.5.3 | 0..n | | type | 7.4 | 0..1 | | unique | 7.8.3 | 0..n | | units | 7.3.3 | 0..1 | +--------------+-------------+-------------+ The deviate's Substatements + If the target node has a property defined by an extension, this + property can be deviated if the extension allows deviations. See + Section 7.19 for details. + 7.20.3.3. Usage Example In this example, the device is informing client applications that it does not support the "daytime" service in the style of RFC 867. deviation /base:system/base:daytime { deviate not-supported; } The following example sets a device-specific default value to a leaf @@ -5348,21 +5449,21 @@ conditional. The node defined by the parent data definition statement is only valid when the condition specified by the "when" statement is satisfied. The statement's argument is an XPath expression (see Section 6.4), which is used to formally specify this condition. If the XPath expression conceptually evaluates to "true" for a particular instance, then the node defined by the parent data definition statement is valid; otherwise, it is not. A leaf that is a list key MUST NOT have a "when" statement. - See Section 8.3.2 for additional information. + See Section 8.2.2 for additional information. The XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o If the "when" statement is a child of an "augment" statement, then the context node is the augment's target node in the data tree, if the target node is a data node. Otherwise, the context node is the closest ancestor node to the target node that is also a data node. @@ -5396,64 +5498,75 @@ 8.1. Constraints on Data Several YANG statements define constraints on valid data. These constraints are enforced in different ways, depending on what type of data the statement defines. o If the constraint is defined on configuration data, it MUST be true in a valid configuration data tree. o If the constraint is defined on state data, it MUST be true in a - reply to a operation without a filter. + valid state data tree. o If the constraint is defined on notification content, it MUST be - true in any notification instance. + true in any notification instance data tree. - o If the constraint is defined on RPC input parameters, it MUST be - true in an invocation of the RPC operation. + o If the constraint is defined on RPC or action input parameters, it + MUST be true in an invocation of the RPC or action operation. - o If the constraint is defined on RPC output parameters, it MUST be - true in the RPC reply. + o If the constraint is defined on RPC or action output parameters, + it MUST be true in the RPC or action reply. -8.2. Hierarchy of Constraints + The following properties are true in all data trees: - Conditions on parent nodes affect constraints on child nodes as a - natural consequence of the hierarchy of nodes. "must", "mandatory", - "min-elements", and "max-elements" constraints are not enforced if - the parent node has a "when" or "if-feature" property that is not - satisfied on the current device. + o All leaf data values MUST match the type constraints for the leaf, + including those defined in the type's "range", "length", and + "pattern" properties. - In this example, the "mandatory" constraint on the "longitude" leaf - is not enforced on devices that lack the "has-gps" feature: + o All key leafs MUST be present for all list entries. - container location { - if-feature has-gps; - leaf longitude { - mandatory true; - ... - } - } + o Nodes MUST be present for at most one case branch in all choices. -8.3. Constraint Enforcement Model + o There MUST be no nodes tagged with "if-feature" present if the + "if-feature" expression evaluates to "false" on the device. + + o There MUST be no nodes tagged with "when" present if the "when" + condition evaluates to "false" in the data tree. + + The following properties are true in a valid data tree: + + o All "must" constraints MUST evaluate to "true". + + o All referential integrity constraints defined via the "path" + statement MUST be satisfied. + + o All "unique" constraints on lists MUST be satisfied. + + o The "min-elements" and "max-elements" constraints are enforced for + lists and leaf-lists. + + The running configuration datastore MUST always be valid. + +8.2. NETCONF Constraint Enforcement Model For configuration data, there are three windows when constraints MUST be enforced: o during parsing of RPC payloads o during processing of NETCONF operations o during validation Each of these scenarios is considered in the following sections. -8.3.1. Payload Parsing +8.2.1. Payload Parsing When content arrives in RPC payloads, it MUST be well-formed XML, following the hierarchy and content rules defined by the set of models the device implements. o If a leaf data value does not match the type constraints for the leaf, including those defined in the type's "range", "length", and "pattern" properties, the server MUST reply with an "invalid-value" error-tag in the rpc-error, and with the error- app-tag and error-message associated with the constraint, if any @@ -5476,21 +5589,21 @@ o For insert handling, if the value for the attributes "before" and "after" are not valid for the type of the appropriate key leafs, the server MUST reply with a "bad-attribute" error-tag in the rpc- error. o If the attributes "before" and "after" appears in any element that is not a list whose "ordered-by" property is "user", the server MUST reply with an "unknown-attribute" error-tag in the rpc-error. -8.3.2. NETCONF Processing +8.2.2. NETCONF Processing After the incoming data is parsed, the NETCONF server performs the operation by applying the data to the configuration datastore. During this processing, the following errors MUST be detected: o Delete requests for non-existent data. o Create requests for existent data. @@ -5500,40 +5613,30 @@ During processing: o If the NETCONF operation creates data nodes under a "choice", any existing nodes from other "case" branches are deleted by the server. o If the NETCONF operation modifies a data node such that any node's "when" expression becomes false, then the node with the "when" expression is deleted by the server. -8.3.3. Validation +8.2.3. Validation When datastore processing is complete, the final contents MUST obey all validation constraints. This validation processing is performed at differing times according to the datastore. If the datastore is "running" or "startup", these constraints MUST be enforced at the end of the or operation. If the datastore is "candidate", the constraint enforcement is delayed until a or operation. - o Any "must" constraints MUST evaluate to "true". - - o Any referential integrity constraints defined via the "path" - statement MUST be satisfied. - - o Any "unique" constraints on lists MUST be satisfied. - - o The "min-elements" and "max-elements" constraints are enforced for - lists and leaf-lists. - 9. Built-In Types YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special requirements from the management information model. Additional types may be defined, derived from those built-in types or from other derived types. Derived types may use subtyping to formally restrict the set of possible values. @@ -5646,21 +5749,21 @@ range-restricted type, the new restriction MUST be equal or more limiting, that is raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Each explicit value and range boundary value given in the range expression MUST match the type being restricted, or be one of the special values "min" or "max". "min" and "max" mean the minimum and maximum value accepted for the type being restricted, respectively. The range expression syntax is formally defined by the rule - "range-arg" in Section 13. + "range-arg" in Section 14. 9.2.4.1. The range's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | | reference | 7.21.4 | 0..1 | @@ -5761,21 +5864,21 @@ } } 9.4. The string Built-In Type The string built-in type represents human-readable strings in YANG. Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] characters, including tab, carriage return, and line feed but excluding the other C0 control characters, the surrogate blocks, and the noncharacters. The string syntax is formally defined by the rule - "yang-string" in Section 13. + "yang-string" in Section 14. 9.4.1. Lexical Representation A string value is lexically represented as character data in the XML instance documents. 9.4.2. Canonical Form The canonical form is the same as the lexical representation. No Unicode normalization is performed of string values. @@ -5804,21 +5907,21 @@ MUST be equal or more limiting, that is, raising the lower bounds, reducing the upper bounds, removing explicit length values or ranges, or splitting ranges into multiple ranges with intermediate gaps. A length value is a non-negative integer, or one of the special values "min" or "max". "min" and "max" mean the minimum and maximum length accepted for the type being restricted, respectively. An implementation is not required to support a length value larger than 18446744073709551615. The length expression syntax is formally defined by the rule - "length-arg" in Section 13. + "length-arg" in Section 14. 9.4.4.1. The length's Substatements +---------------+---------+-------------+ | substatement | section | cardinality | +---------------+---------+-------------+ | description | 7.21.3 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 | | error-message | 7.5.4.1 | 0..1 | | reference | 7.21.4 | 0..1 | @@ -6196,21 +6301,21 @@ The "path" statement, which is a substatement to the "type" statement, MUST be present if the type is "leafref". It takes as an argument a string that MUST refer to a leaf or leaf-list node. The syntax for a path argument is a subset of the XPath abbreviated syntax. Predicates are used only for constraining the values for the key nodes for list entries. Each predicate consists of exactly one equality test per key, and multiple adjacent predicates MAY be present if a list has multiple keys. The syntax is formally defined - by the rule "path-arg" in Section 13. + by the rule "path-arg" in Section 14. The predicates are only used when more than one key reference is needed to uniquely identify a leaf instance. This occurs if a list has multiple keys, or a reference to a leaf other than the key in a list is needed. In these cases, multiple leafrefs are typically specified, and predicates are used to tie them together. The "path" expression evaluates to a node set consisting of zero, one, or more nodes. If the leaf with the leafref type represents configuration data, this node set MUST be non-empty. @@ -6372,22 +6477,21 @@ existing admin-status: notification link-failure { leaf if-name { type leafref { path "/interface/name"; } } leaf admin-status { type leafref { - path - "/interface[name = current()/../if-name]" + path "/interface[name = current()/../if-name]" + "/admin-status"; } } } An example of a corresponding XML notification: 2008-04-01T00:01:00Z @@ -6412,21 +6516,21 @@ statement, MUST be present at least once if the type is "identityref". The argument is the name of an identity, as defined by an "identity" statement. If a prefix is present on the identity name, it refers to an identity defined in the module that was imported with that prefix. Otherwise, an identity with the matching name MUST be defined in the current module or an included submodule. Valid values for an identityref are any identities derived from all the identityref's base identities. On a particular server, the valid values are further restricted to the set of identities defined in the - modules supported by the server. + modules implemented by the server. 9.10.3. Lexical Representation An identityref is encoded as the referred identity's qualified name as defined in [XML-NAMES]. If the prefix is not present, the namespace of the identityref is the default namespace in effect on the element that contains the identityref value. When an identityref is given a default value using the "default" statement, the identity name in the default value MAY have a prefix. @@ -6621,21 +6725,21 @@ instead of an enumeration, the current value would have matched, and the resulting configuration would have been valid. 9.13. The instance-identifier Built-In Type The instance-identifier built-in type is used to uniquely identify a 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 13. It is used to uniquely identify + "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. 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 @@ -6754,37 +6858,44 @@ an empty node-set is returned. If the first argument node is of type leafref, the function returns a node set that contains the nodes that the leafref refers to. If the first argument node is of any other type, an empty node set is returned. 10.3.1.1. Usage Example list interface { - key name; + key "name type"; leaf name { ... } + leaf type { ... } leaf enabled { type boolean; } ... } - leaf mgmt-interface { + 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() boolean derived-from(node-set nodes, string module-name, string identity-name) The derived-from() function returns true if the first node in @@ -7018,37 +7128,63 @@ 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. -12. YIN +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. + + A YANG version 1.1 module or submodule MAY import a YANG version 1 + module by revision. + + If a YANG version 1 module A imports module B without revision, and + module B is updated to YANG version 1.1, a server MAY implement both + these modules at the same time. In such cases, a NETCONF server MUST + advertise both modules using the rules defined in Section 5.6.5, and + SHOULD advertise module A and the latest revision of module B that is + specified with YANG version 1 according to the rules defined in + [RFC6020]. + + This rule exists in order to allow implementations of existing YANG + version 1 modules together with YANG version 1.1 modules. Without + this rule, updating a single module to YANG version 1.1 would have a + cascading effect on modules that import it, requiring all of them to + also be updated to YANG version 1.1, and so on. + +13. YIN A YANG module can be translated into an alternative XML-based syntax called YIN. The translated module is called a YIN module. This section describes symmetric mapping rules between the two formats. The YANG and YIN formats contain equivalent information using different notations. The YIN notation enables developers to represent YANG data models in XML and therefore use the rich set of XML-based tools for data filtering and validation, automated generation of code and documentation, and other tasks. Tools like XSLT or XML validators can be utilized. The mapping between YANG and YIN does not modify the information content of the model. Comments and whitespace are not preserved. -12.1. Formal YIN Definition +13.1. Formal YIN Definition There is a one-to-one correspondence between YANG keywords and YIN elements. The local name of a YIN element is identical to the corresponding YANG keyword. This means, in particular, that the document element (root) of a YIN document is always or . YIN elements corresponding to the YANG keywords belong to the namespace whose associated URI is "urn:ietf:params:xml:ns:yang:yin:1". @@ -7149,21 +7285,21 @@ | units | name | false | | uses | name | false | | value | value | false | | when | condition | false | | yang-version | value | false | | yin-element | value | false | +------------------+---------------+-------------+ Table 1: Mapping of arguments of the YANG statements. -12.1.1. Usage Example +13.1.1. Usage Example The following YANG module: module acme-foo { yang-version 1.1; namespace "http://acme.example.com/foo"; prefix "acfoo"; import my-extensions { prefix "myext"; @@ -7206,21 +7342,21 @@ The MTU of the interface. -13. YANG ABNF Grammar +14. YANG ABNF Grammar In YANG, almost all statements are unordered. The ABNF grammar [RFC5234] [RFC7405] defines the canonical order. To improve module readability, it is RECOMMENDED that clauses be entered in this order. Within the ABNF grammar, unordered statements are marked with comments. This grammar assumes that the scanner replaces YANG comments with a single space character. @@ -8360,267 +8496,128 @@ ; space VCHAR = %x21-7E ; visible (printing) characters WSP = SP / HTAB ; whitespace -14. Error Responses for YANG Related Errors +15. NETCONF Error Responses for YANG Related Errors A number of NETCONF error responses are defined for error cases related to the data-model handling. If the relevant YANG statement has an "error-app-tag" substatement, that overrides the default value specified below. -14.1. Error Message for Data That Violates a unique Statement +15.1. Error Message for Data That Violates a unique Statement If a NETCONF operation would result in configuration data where a unique constraint is invalidated, the following error is returned: error-tag: operation-failed error-app-tag: data-not-unique error-info: : Contains an instance identifier that points to a leaf that invalidates the unique constraint. This element is present once for each non-unique leaf. The element is in the YANG namespace ("urn:ietf:params:xml:ns:yang:1"). -14.2. Error Message for Data That Violates a max-elements Statement +15.2. Error Message for Data That Violates a max-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too many entries the following error is returned: error-tag: operation-failed error-app-tag: too-many-elements This error is returned once, with the error-path identifying the list node, even if there are more than one extra child present. -14.3. Error Message for Data That Violates a min-elements Statement +15.3. Error Message for Data That Violates a min-elements Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too few entries the following error is returned: error-tag: operation-failed error-app-tag: too-few-elements This error is returned once, with the error-path identifying the list node, even if there are more than one child missing. -14.4. Error Message for Data That Violates a must Statement +15.4. Error Message for Data That Violates a must Statement If a NETCONF operation would result in configuration data where the restrictions imposed by a "must" statement is violated the following error is returned, unless a specific "error-app-tag" substatement is present for the "must" statement. error-tag: operation-failed error-app-tag: must-violation -14.5. Error Message for Data That Violates a require-instance Statement +15.5. Error Message for Data That Violates a require-instance Statement If a NETCONF operation would result in configuration data where a leaf of type "instance-identifier" or "leafref" marked with require- instance "true" refers to a non-existing instance, the following error is returned: error-tag: data-missing error-app-tag: instance-required error-path: Path to the instance-identifier or leafref leaf. -14.6. Error Message for Data That Does Not Match a leafref Type +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. -14.7. Error Message for Data That Violates a mandatory choice Statement +15.7. 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"). -14.8. Error Message for the "insert" Operation +15.8. 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 -15. IANA Considerations - - This document defines a registry for YANG module and submodule names. - The name of the registry is "YANG Module Names". - - The registry shall record for each entry: - - o the name of the module or submodule - - o for modules, the assigned XML namespace - - o for modules, the prefix of the module - - o for submodules, the name of the module it belongs to - - o a reference to the (sub)module's documentation (e.g., the RFC - number) - - There are no initial assignments. - - For allocation, RFC publication is required as per RFC 5226 - [RFC5226]. All registered YANG module names MUST comply with the - rules for identifiers stated in Section 6.2, and MUST have a module - name prefix. - - The module name prefix 'ietf-' is reserved for IETF stream documents - [RFC4844], while the module name prefix 'irtf-' is reserved for IRTF - stream documents. Modules published in other RFC streams MUST have a - similar suitable prefix. - - All module and submodule names in the registry MUST be unique. - - All XML namespaces in the registry MUST be unique. - - This document registers two URIs for the YANG and YIN XML namespaces - in the IETF XML registry [RFC3688]. Following the format in RFC - 3688, the following have been registered. - - URI: urn:ietf:params:xml:ns:yang:yin:1 - URI: urn:ietf:params:xml:ns:yang:1 - - Registrant Contact: The IESG. - - XML: N/A, the requested URIs are XML namespaces. +16. IANA Considerations This document registers one capability identifier URN from the "Network Configuration Protocol (NETCONF) Capability URNs" registry: urn:ietf:params:netconf:capability:yang-library:1.0 - This document registers two new media types as defined in the - following sections. - -15.1. Media type application/yang - - MIME media type name: application - - MIME subtype name: yang - - Mandatory parameters: none - - Optional parameters: none - - Encoding considerations: 8-bit - - Security considerations: See Section 15 in RFC XXXX - - Interoperability considerations: None - - Published specification: RFC XXXX - - Applications that use this media type: - - YANG module validators, web servers used for downloading YANG - modules, email clients, etc. - - Additional information: - - Magic Number: None - - File Extension: .yang - - Macintosh file type code: 'TEXT' - - Personal and email address for further information: - Martin Bjorklund - - Intended usage: COMMON - - Author: - This specification is a work item of the IETF NETMOD working - group, with mailing list address . - - Change controller: - The IESG - -15.2. Media type application/yin+xml - MIME media type name: application - - MIME subtype name: yin+xml - - Mandatory parameters: none - - Optional parameters: - - "charset": This parameter has identical semantics to the - charset parameter of the "application/xml" media type as - specified in [RFC3023]. - - Encoding considerations: - - Identical to those of "application/xml" as - described in [RFC3023], Section 3.2. - - Security considerations: See Section 15 in RFC XXXX - - Interoperability considerations: None - - Published specification: RFC XXXX - - Applications that use this media type: - - YANG module validators, web servers used for downloading YANG - modules, email clients, etc. - - Additional information: - - Magic Number: As specified for "application/xml" in [RFC3023], - Section 3.2. - - File Extension: .yin - - Macintosh file type code: 'TEXT' - - Personal and email address for further information: - Martin Bjorklund - - Intended usage: COMMON - - Author: - This specification is a work item of the IETF NETMOD working - group, with mailing list address . - - Change controller: - The IESG - -16. Security Considerations +17. Security Considerations This document defines a language with which to write and read descriptions of management information. The language itself has no security impact on the Internet. The same considerations are relevant as for the base NETCONF protocol (see [RFC6241], Section 9). Data modeled in YANG might contain sensitive information. RPCs or notifications defined in YANG might transfer sensitive information. @@ -8640,97 +8637,103 @@ o adequate authentication and access control mechanisms to restrict the usage of sensitive data. YANG parsers need to be robust with respect to malformed documents. Reading malformed documents from unknown or untrusted sources could result in an attacker gaining privileges of the user running the YANG parser. In an extreme situation, the entire machine could be compromised. -17. Contributors +18. Contributors The following people all contributed significantly to the initial YANG document: - Andy Bierman (Brocade) - Balazs Lengyel (Ericsson) - David Partain (Ericsson) - Juergen Schoenwaelder (Jacobs University Bremen) - Phil Shafer (Juniper Networks) -18. Acknowledgements +19. Acknowledgements The editor wishes to thank the following individuals, who all provided helpful comments on various versions of this document: - Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav - Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert - Wijnen. + Mehmet Ersue, Washam Fan, Joel Halpern, Per Hedeland, Leif Johansson, + Ladislav Lhotka, Gerhard Muenz, Peyman Owladi, Tom Petch, Randy + Presuhn, David Reid, Jernej Tuljak, and Bert Wijnen. -19. ChangeLog +20. ChangeLog RFC Editor: remove this section upon publication as an RFC. -19.1. Version -06 +20.1. Version -07 + + o Fixes after WG review. + + o Included solution Y60-01. + +20.2. Version -06 o Included solution Y45-05. -19.2. Version -05 +20.3. Version -05 o Included solution Y18-01. o Included solution Y25-02 (parts of it was included in -04). o Included solution Y34-05. o Included solution Y36-03. -19.3. Version -04 +20.4. Version -04 o Incorporated changes to ABNF grammar after review and errata for RFC 6020. o Included solution Y16-03. o Included solution Y49-04. o Included solution Y58-01. o Included solution Y59-01. -19.4. Version -03 +20.5. Version -03 o Incorporated changes from WG reviews. o Included solution Y05-01. o Included solution Y10-01. o Included solution Y13-01. o Included solution Y28-02. o Included solution Y55-01 (parts of it was included in -01). -19.5. Version -02 +20.6. Version -02 o Included solution Y02-01. o Included solution Y04-02. o Included solution Y11-01. o Included solution Y41-01. o Included solution Y56-01. -19.6. Version -01 +20.7. 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. @@ -8740,64 +8743,54 @@ o Included solution Y23-01. o Included solution Y29-01. o Included solution Y30-01. o Included solution Y31-01. o Included solution Y35-01. -19.7. Version -00 +20.8. Version -00 o Applied all reported errata for RFC 6020. o Updated YANG version to 1.1, and made the "yang-version" statement mandatory. -20. References +21. References -20.1. Normative 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), January 2015. + progress), July 2015. [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. - [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media - Types", RFC 3023, January 2001. - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. - [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, - January 2004. - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - May 2008. - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, July 2008. [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. @@ -8815,21 +8808,36 @@ 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 Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, . -20.2. Informative References +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. + + [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. + + [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. [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Textual Conventions for SMIv2", STD 58, RFC 2579, April 1999. [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation