draft-ietf-netmod-yang-00.txt   draft-ietf-netmod-yang-01.txt 
Network Working Group M. Bjorklund, Ed. Network Working Group M. Bjorklund, Ed.
Internet-Draft Tail-f Systems Internet-Draft Tail-f Systems
Intended status: Standards Track May 5, 2008 Intended status: Standards Track August 29, 2008
Expires: November 6, 2008 Expires: March 2, 2009
YANG - A data modeling language for NETCONF YANG - A data modeling language for NETCONF
draft-ietf-netmod-yang-00 draft-ietf-netmod-yang-01
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 34 skipping to change at page 1, line 34
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 6, 2008. This Internet-Draft will expire on March 2, 2009.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2008). Copyright (C) The IETF Trust (2008).
Abstract Abstract
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
state data manipulated by the NETCONF protocol, NETCONF remote state data manipulated by the NETCONF protocol, NETCONF remote
procedure calls, and NETCONF notifications. procedure calls, and NETCONF notifications.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 9 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 11
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 12
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 12
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 13
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 13 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 13
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 14 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 14
4.2.3. Operational Data . . . . . . . . . . . . . . . . . . 19 4.2.3. Operational Data . . . . . . . . . . . . . . . . . . 19
4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22
skipping to change at page 4, line 25 skipping to change at page 4, line 26
7.9.4. The choice's mandatory Statement . . . . . . . . . . 69 7.9.4. The choice's mandatory Statement . . . . . . . . . . 69
7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 69 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 69
7.9.6. NETCONF <edit-config> operations . . . . . . . . . . 69 7.9.6. NETCONF <edit-config> operations . . . . . . . . . . 69
7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 70 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 70
7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 71 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 71
7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 71 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 71
7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 71 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 71
7.10.3. NETCONF <edit-config> operations . . . . . . . . . . 71 7.10.3. NETCONF <edit-config> operations . . . . . . . . . . 71
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 72 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 72
7.11. The grouping Statement . . . . . . . . . . . . . . . . . 72 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 72
7.11.1. The grouping's Substatements . . . . . . . . . . . . 73 7.11.1. The grouping's Substatements . . . . . . . . . . . . 74
7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 74 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 74
7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 74 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 74
7.12.1. The uses's Substatements . . . . . . . . . . . . . . 75 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 75
7.12.2. The uses's Refinement Statements . . . . . . . . . . 75 7.12.2. The uses's Refinement Statements . . . . . . . . . . 75
7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 76 7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 76
7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 76 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 76
7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 77 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 77
7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 77 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 78
7.13.2. The input Statement . . . . . . . . . . . . . . . . . 77 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 78
7.13.3. The output Statement . . . . . . . . . . . . . . . . 78 7.13.3. The output Statement . . . . . . . . . . . . . . . . 79
7.14. The notification Statement . . . . . . . . . . . . . . . 79 7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 80
7.14.1. The notification's Substatements . . . . . . . . . . 80 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 80
7.15. The augment Statement . . . . . . . . . . . . . . . . . . 80 7.14. The notification Statement . . . . . . . . . . . . . . . 81
7.15.1. The augment's Substatements . . . . . . . . . . . . . 81 7.14.1. The notification's Substatements . . . . . . . . . . 82
7.15.2. The when Statement . . . . . . . . . . . . . . . . . 81 7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 82
7.15.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 82
7.15.4. Usage Example . . . . . . . . . . . . . . . . . . . . 82 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 83
7.16. The extension Statement . . . . . . . . . . . . . . . . . 84 7.15.1. The augment's Substatements . . . . . . . . . . . . . 84
7.16.1. The extension's Substatements . . . . . . . . . . . . 84 7.15.2. The when Statement . . . . . . . . . . . . . . . . . 84
7.16.2. The argument Statement . . . . . . . . . . . . . . . 84 7.15.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 85
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 85 7.15.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85
7.17. Common Statements . . . . . . . . . . . . . . . . . . . . 86 7.16. The extension Statement . . . . . . . . . . . . . . . . . 87
7.17.1. The config Statement . . . . . . . . . . . . . . . . 86 7.16.1. The extension's Substatements . . . . . . . . . . . . 88
7.17.2. The status Statement . . . . . . . . . . . . . . . . 86 7.16.2. The argument Statement . . . . . . . . . . . . . . . 88
7.17.3. The description Statement . . . . . . . . . . . . . . 87 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 88
7.17.4. The reference Statement . . . . . . . . . . . . . . . 87 7.17. Common Statements . . . . . . . . . . . . . . . . . . . . 89
8. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 88 7.17.1. The config Statement . . . . . . . . . . . . . . . . 89
8.1. The Integer Built-in Types . . . . . . . . . . . . . . . 88 7.17.2. The status Statement . . . . . . . . . . . . . . . . 90
8.1.1. Lexicographic Representation . . . . . . . . . . . . 89 7.17.3. The description Statement . . . . . . . . . . . . . . 90
8.1.2. Restrictions . . . . . . . . . . . . . . . . . . . . 89 7.17.4. The reference Statement . . . . . . . . . . . . . . . 90
8.1.3. The range Statement . . . . . . . . . . . . . . . . . 89 8. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 91
8.1.4. Usage Example . . . . . . . . . . . . . . . . . . . . 90 8.1. The Integer Built-in Types . . . . . . . . . . . . . . . 91
8.2. The Floating Point Built-in Types . . . . . . . . . . . . 90 8.1.1. Lexicographic Representation . . . . . . . . . . . . 92
8.2.1. Lexicographic Representation . . . . . . . . . . . . 90 8.1.2. Restrictions . . . . . . . . . . . . . . . . . . . . 92
8.2.2. Restrictions . . . . . . . . . . . . . . . . . . . . 90 8.1.3. The range Statement . . . . . . . . . . . . . . . . . 92
8.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 91 8.1.4. Usage Example . . . . . . . . . . . . . . . . . . . . 93
8.3. The string Built-in Type . . . . . . . . . . . . . . . . 91 8.2. The Floating Point Built-in Types . . . . . . . . . . . . 93
8.3.1. Lexicographic Representation . . . . . . . . . . . . 91 8.2.1. Lexicographic Representation . . . . . . . . . . . . 94
8.3.2. Restrictions . . . . . . . . . . . . . . . . . . . . 91 8.2.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94
8.3.3. The length Statement . . . . . . . . . . . . . . . . 91 8.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 94
8.3.4. The pattern Statement . . . . . . . . . . . . . . . . 92 8.3. The string Built-in Type . . . . . . . . . . . . . . . . 94
8.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 93 8.3.1. Lexicographic Representation . . . . . . . . . . . . 94
8.4. The boolean Built-in Type . . . . . . . . . . . . . . . . 93 8.3.2. Restrictions . . . . . . . . . . . . . . . . . . . . 94
8.4.1. Lexicographic Representation . . . . . . . . . . . . 93 8.3.3. The length Statement . . . . . . . . . . . . . . . . 95
8.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . 93 8.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 96
8.5. The enumeration Built-in Type . . . . . . . . . . . . . . 93 8.3.5. The pattern Statement . . . . . . . . . . . . . . . . 96
8.5.1. Lexicographic Representation . . . . . . . . . . . . 93 8.3.6. Usage Example . . . . . . . . . . . . . . . . . . . . 96
8.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 93 8.4. The boolean Built-in Type . . . . . . . . . . . . . . . . 97
8.5.3. The enum Statement . . . . . . . . . . . . . . . . . 94 8.4.1. Lexicographic Representation . . . . . . . . . . . . 97
8.5.4. Usage Example . . . . . . . . . . . . . . . . . . . . 95 8.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97
8.6. The bits Built-in Type . . . . . . . . . . . . . . . . . 95 8.5. The enumeration Built-in Type . . . . . . . . . . . . . . 97
8.6.1. Restrictions . . . . . . . . . . . . . . . . . . . . 95 8.5.1. Lexicographic Representation . . . . . . . . . . . . 97
8.6.2. Lexicographic Representation . . . . . . . . . . . . 95 8.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 97
8.6.3. The bit Statement . . . . . . . . . . . . . . . . . . 95 8.5.3. The enum Statement . . . . . . . . . . . . . . . . . 97
8.6.4. Usage Example . . . . . . . . . . . . . . . . . . . . 96 8.5.4. Usage Example . . . . . . . . . . . . . . . . . . . . 98
8.7. The binary Built-in Type . . . . . . . . . . . . . . . . 97 8.6. The bits Built-in Type . . . . . . . . . . . . . . . . . 99
8.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 97 8.6.1. Restrictions . . . . . . . . . . . . . . . . . . . . 99
8.7.2. Lexicographic Representation . . . . . . . . . . . . 97 8.6.2. Lexicographic Representation . . . . . . . . . . . . 99
8.8. The keyref Built-in Type . . . . . . . . . . . . . . . . 97 8.6.3. The bit Statement . . . . . . . . . . . . . . . . . . 99
8.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 97 8.6.4. Usage Example . . . . . . . . . . . . . . . . . . . . 100
8.8.2. The path Statement . . . . . . . . . . . . . . . . . 97 8.7. The binary Built-in Type . . . . . . . . . . . . . . . . 100
8.8.3. Lexicographic Representation . . . . . . . . . . . . 98 8.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 100
8.8.4. Usage Example . . . . . . . . . . . . . . . . . . . . 98 8.7.2. Lexicographic Representation . . . . . . . . . . . . 100
8.9. The empty Built-in Type . . . . . . . . . . . . . . . . . 99 8.8. The keyref Built-in Type . . . . . . . . . . . . . . . . 101
8.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 99 8.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 101
8.9.2. Lexicographic Representation . . . . . . . . . . . . 100 8.8.2. The path Statement . . . . . . . . . . . . . . . . . 101
8.9.3. Usage Example . . . . . . . . . . . . . . . . . . . . 100 8.8.3. Lexicographic Representation . . . . . . . . . . . . 101
8.10. The union Built-in Type . . . . . . . . . . . . . . . . . 100 8.8.4. Usage Example . . . . . . . . . . . . . . . . . . . . 101
8.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 100 8.9. The empty Built-in Type . . . . . . . . . . . . . . . . . 103
8.10.2. Lexicographic Representation . . . . . . . . . . . . 101 8.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 103
8.11. The instance-identifier Built-in Type . . . . . . . . . . 101 8.9.2. Lexicographic Representation . . . . . . . . . . . . 103
8.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 101 8.9.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103
8.11.2. Lexicographic Representation . . . . . . . . . . . . 101 8.10. The union Built-in Type . . . . . . . . . . . . . . . . . 104
8.11.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 8.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 104
9. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 103 8.10.2. Lexicographic Representation . . . . . . . . . . . . 104
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 104 8.11. The instance-identifier Built-in Type . . . . . . . . . . 104
11. Security Considerations . . . . . . . . . . . . . . . . . . . 105 8.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 105
12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 106 8.11.2. Lexicographic Representation . . . . . . . . . . . . 105
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 107 8.11.3. Usage Example . . . . . . . . . . . . . . . . . . . . 105
13.1. Normative References . . . . . . . . . . . . . . . . . . 107 9. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 106
13.2. Non-Normative References . . . . . . . . . . . . . . . . 108 10. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Appendix A. Derived YANG Types . . . . . . . . . . . . . . . . . 109 10.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 107
A.1. Core YANG Derived Types . . . . . . . . . . . . . . . . . 109 10.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 107
A.2. Internet Specific Derived Types . . . . . . . . . . . . . 114 10.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 109
A.3. IEEE 802 Specific Derived Types . . . . . . . . . . . . . 120 10.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 109
Appendix B. YIN . . . . . . . . . . . . . . . . . . . . . . . . 123 10.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 110
B.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 123 11. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 111
B.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 123 12. Error Responses for YANG Related Errors . . . . . . . . . . . 130
B.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 125 12.1. Error Message for Data that Violates a YANG unique
B.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 125 Statement: . . . . . . . . . . . . . . . . . . . . . . . 130
B.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 126 12.2. Error Message for Data that Violates a YANG
Appendix C. XML Schema Considerations . . . . . . . . . . . . . 127 max-elements Statement: . . . . . . . . . . . . . . . . . 130
Appendix D. YANG ABNF Grammar . . . . . . . . . . . . . . . . . 128 12.3. Error Message for Data that Violates a YANG
Appendix E. Error Responses for YANG Related Errors . . . . . . 146 min-elements Statement: . . . . . . . . . . . . . . . . . 130
E.1. Error Message for Data that Violates a YANG unique 12.4. Error Message for Data that Violates a YANG must
Statement: . . . . . . . . . . . . . . . . . . . . . . . 146 statement: . . . . . . . . . . . . . . . . . . . . . . . 131
E.2. Error Message for Data that Violates a YANG 12.5. Error Message for the "insert" Operation . . . . . . . . 131
max-elements Statement: . . . . . . . . . . . . . . . . . 146 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 132
E.3. Error Message for Data that Violates a YANG 14. Security Considerations . . . . . . . . . . . . . . . . . . . 133
min-elements Statement: . . . . . . . . . . . . . . . . . 146 15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 134
E.4. Error Message for Data that Violates a YANG must or 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 135
when statement, a length, range or pattern restriction: . 146 16.1. Normative References . . . . . . . . . . . . . . . . . . 135
E.5. Error Message for the "insert" Operation . . . . . . . . 147 16.2. Non-Normative References . . . . . . . . . . . . . . . . 136
Appendix F. Why We Need a New Modeling Language . . . . . . . . 148 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 137
F.1. Why not XSD? . . . . . . . . . . . . . . . . . . . . . . 148 A.1. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 137
F.2. Why not RelaxNG . . . . . . . . . . . . . . . . . . . . . 149 A.2. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 138
F.3. Why not SMIng . . . . . . . . . . . . . . . . . . . . . . 149 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 139
Appendix G. ChangeLog . . . . . . . . . . . . . . . . . . . . . 151 Intellectual Property and Copyright Statements . . . . . . . . . 140
G.1. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 151
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 152
Intellectual Property and Copyright Statements . . . . . . . . . 153
1. Introduction 1. Introduction
Today, the NETCONF protocol [RFC4741] lacks a standardized way to Today, the NETCONF protocol [RFC4741] lacks a standardized way to
create data models. Instead, vendors are forced to use proprietary create data models. Instead, vendors are forced to use proprietary
solutions. In order for NETCONF to be a interoperable protocol, solutions. In order for NETCONF to be a interoperable protocol,
models must be defined in a vendor-neutral way. YANG provides the models must be defined in a vendor-neutral way. YANG provides the
language and rules for defining such models for use with NETCONF. language and rules for defining such models for use with NETCONF.
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
state data manipulated by the NETCONF protocol, NETCONF remote state data manipulated by the NETCONF protocol, NETCONF remote
procedure calls, and NETCONF notifications. This document describes procedure calls, and NETCONF notifications. This document describes
the syntax and semantics of the YANG language, how the data model the syntax and semantics of the YANG language, how the data model
defined in a YANG module is represented in XML, and how NETCONF defined in a YANG module is represented in XML, and how NETCONF
operations are being used to manipulate the data. operations are used to manipulate the data.
2. Key Words 2. Key Words
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119]. 14, [RFC2119].
3. Terminology 3. Terminology
o anyxml: A node which can contain an unknown chunk of XML data.
o augment: Adds new nodes to a previously defined node. o augment: Adds new nodes to a previously defined node.
o base type: The type from which a derived type was derived, which o base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type. 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 o built-in type: A YANG data type defined in the YANG language, such
as uint32 or string. as uint32 or string.
o choice: A node where only one of a number of identified o choice: A node where only one of a number of identified
alternative values is valid. alternative values is valid.
o container: An interior node in the data tree which exist in zero o configuration data: The set of writable data that is required to
or one instance. A container node has no value, but rather a set transform a system from its initial default state into its current
of child nodes. state [RFC4741].
o container: An interior node in the data tree which exist in at
most one instance. A container node has no value, but rather a
set of child nodes.
o data definition statement: A statement that defines new data o data definition statement: A statement that defines new data
nodes. One of container, leaf, leaf-list, list, augment, uses, nodes. One of container, leaf, leaf-list, list, augment, uses,
and anyxml. and anyxml.
o data model: Formal representation of the application-specific o data model: A data model describes how data is represented and
components of a conceptual network management programmatic accessed.
interface.
o data model module: Container of definitions pertaining to a
specific data model.
o data model object: A definition within a data model module that o data model object: A definition within a module that represents a
represents a conceptual construct which can be accessed via a construct which can be accessed via a network management protocol.
network management protocol. Also called an object. Also called an object.
o data node: A node in the schema tree that can be instantiated in a o data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, and list. data tree. One of container, leaf, leaf-list, list, and anyxml.
o data tree: The instantiated tree of configuration and state data o data tree: The instantiated tree of configuration and state data
on a device. on a device.
o derived type: A type which is derived from a built-in type (such o derived type: A type which is derived from a built-in type (such
as uint32), or another derived type. as uint32), or another derived type.
o extension: An extension attaches non-YANG semantics to nodes. The o extension: An extension attaches non-YANG semantics to nodes. The
extension statement defines new statements to express these extension statement defines new statements to express these
semantics. semantics.
skipping to change at page 10, line 11 skipping to change at page 10, line 15
o grouping: A reusable set of nodes, which may be used locally in o grouping: A reusable set of nodes, which may be used locally in
the module, in modules which include it, and by other modules the module, in modules which include it, and by other modules
which import from it. which import from it.
o identifier: Used to identify different kinds of YANG items by o identifier: Used to identify different kinds of YANG items by
name. name.
o instance identifier: A mechanism for identifying a particular node o instance identifier: A mechanism for identifying a particular node
in a data tree. in a data tree.
o interior nodes: Nodes within a hierarchy that are not leaf nodes. o interior node: Nodes within a hierarchy that are not leaf nodes.
o leaf: A node in the data tree with a value but no child nodes. o leaf: A node in the data tree with a value but no child nodes.
o leaf-list: Like the leaf node but defines a set of uniquely o leaf-list: Like the leaf node but defines a set of uniquely
identifiable nodes rather than a single node. Each node has a identifiable nodes rather than a single node. Each node has a
value but no child nodes. value but no child nodes.
o list: Interior nodes in the data tree which may exist in multiple o list: Interior nodes in the data tree which may exist in multiple
instances. A list node has no value, but rather a set of child instances. A list node has no value, but rather a set of child
nodes. nodes.
o MIB: A Management Information Base, traditionally referring to a o MIB: A Management Information Base, traditionally referring to a
management information defined using SNMP's SMI. management information defined using SNMP's SMI.
o module: A YANG module defines a hierarchy of nodes which can be o module: A YANG module defines a hierarchy of nodes which can be
used for NETCONF-based operations. With its definitions and the used for NETCONF-based operations. With its definitions and the
definitions it imports or includes from elsewhere, a module is definitions it imports or includes from elsewhere, a module is
self-contained and "compilable". self-contained and "compilable".
o node: A logical location in a hierarchy of data elements.
o RPC: A Remote Procedure Call, as used within the NETCONF protocol. o RPC: A Remote Procedure Call, as used within the NETCONF protocol.
o RPC method: A specific Remote Procedure Call, as used within the o RPC method: A specific Remote Procedure Call, as used within the
NETCONF protocol. Also called a protocol operation. NETCONF protocol. Also called a protocol operation.
o schema node: A node in the schema tree. One of container, leaf, o schema node: A node in the schema tree. One of container, leaf,
leaf-list, list, choice, case, rpc, input, output, and leaf-list, list, choice, case, rpc, input, output, and
notification. notification.
o schema node identifier: A mechanism for identifying a particular o schema node identifier: A mechanism for identifying a particular
node in the schema tree. node in the schema tree.
o schema tree: The definition hierarchy specified within a module. 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 [RFC4741].
o submodule: A partial module definition which contributes derived o submodule: A partial module definition which contributes derived
types, groupings, data nodes, RPCs, and notifications to a module. types, groupings, data nodes, RPCs, and notifications to a module.
A YANG module can be constructed from a number of submodules. A YANG module can be constructed from a number of submodules.
o uses: The "uses" statement is used to instantiate the set of nodes o uses: The "uses" statement is used to instantiate the set of nodes
defined in a grouping statement. The instantiated nodes may be defined in a grouping statement. The instantiated nodes may be
refined and augmented to tailor them to any specific needs. refined and augmented to tailor them to any specific needs.
3.1. Mandatory nodes
A mandatory node is one of:
o A leaf or choice 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 has at
least one mandatory node as a child.
4. YANG Overview 4. YANG Overview
4.1. Functional Overview 4.1. Functional Overview
YANG is a language used to model data for the NETCONF protocol. A YANG is a language used to model data for the NETCONF protocol. A
YANG module defines a hierarchy of nodes which can be used for YANG module defines a hierarchy of nodes which can be used for
NETCONF-based operations, including configuration, state data, remote NETCONF-based operations, including configuration, state data, remote
procedure calls (RPCs), and notifications. This allows a complete procedure calls (RPCs), and notifications. This allows a complete
description of all data sent between a NETCONF client and server. description of all data sent between a NETCONF client and server.
skipping to change at page 13, line 6 skipping to change at page 13, line 6
that imports or includes it. that imports or includes it.
YANG organizational constructs include defining lists of nodes with YANG organizational constructs include defining lists of nodes with
the same names and identifying the keys which distinguish list the same names and identifying the keys which distinguish list
members from each other. Such lists may be defined as either sorted members from each other. Such lists may be defined as either sorted
by user or automatically sorted by the system. For user-sorted by user or automatically sorted by the system. For user-sorted
lists, operations are defined for manipulating the order of the lists, operations are defined for manipulating the order of the
nodes. nodes.
YANG modules can be translated into an XML format called YIN YANG modules can be translated into an XML format called YIN
(Appendix B), allowing applications using XML parsers and XSLT (Section 10), allowing applications using XML parsers and XSLT
scripts to operate on the models. scripts to operate on the models.
XML Schema [XSD] files can be generated from YANG modules, giving a
precise description of the XML representation of the data modeled in
YANG modules.
YANG strikes a balance between high-level object-oriented modeling YANG strikes a balance between high-level object-oriented modeling
and low-level bits-on-the-wire encoding. The reader of a YANG module and low-level bits-on-the-wire encoding. The reader of a YANG module
can easily see the high-level view of the data model while seeing how can easily see the high-level view of the data model while seeing how
the object will be encoded in NETCONF operations. the object will be encoded in NETCONF operations.
YANG is an extensible language, allowing extension statements to be YANG is an extensible language, allowing extension statements to be
defined by standards bodies, vendors, and individuals. The statement defined by standards bodies, vendors, and individuals. The statement
syntax allows these extensions to coexist with standard YANG syntax allows these extensions to coexist with standard YANG
statements in a natural way, while making extensions stand out statements in a natural way, while making extensions stand out
sufficiently for the reader to notice them. sufficiently for the reader to notice them.
skipping to change at page 16, line 19 skipping to change at page 16, line 16
<login> <login>
<message>Good morning, Dave</message> <message>Good morning, Dave</message>
</login> </login>
</system> </system>
The "container" statement is covered in Section 7.5. The "container" statement is covered in Section 7.5.
4.2.2.4. List Nodes 4.2.2.4. List Nodes
A list is a sequence of list entries. An entry is like a structure A list is a sequence of list entries. An entry is like a structure
or a record. A list entry is uniquely identified by its key(s). A or a record. A list entry is uniquely identified by the values of
list entry may contain any number of child nodes of any type its key leafs. A list entry can have multiple keys. A list entry
(including leafs, lists, containers etc.). may contain any number of child nodes of any type (including leafs,
lists, containers etc.).
YANG Example: YANG Example:
list user { list user {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf full-name { leaf full-name {
type string; type string;
skipping to change at page 19, line 44 skipping to change at page 19, line 44
leaf observed-speed { leaf observed-speed {
type uint32; type uint32;
config false; config false;
} }
} }
4.2.4. Built-in Types 4.2.4. Built-in Types
YANG has a set of built-in types, similar to those of many YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special programming languages, but with some differences due to special
requirements from the management information model. The following requirements from the management domain. The following table
table summarizes the built-in types discussed in Section 8: summarizes the built-in types discussed in Section 8:
+---------------------+-------------+-------------------------------+ +---------------------+-------------+-------------------------------+
| Name | Type | Description | | Name | Type | Description |
+---------------------+-------------+-------------------------------+ +---------------------+-------------+-------------------------------+
| int8 | Number | 8-bit signed integer | | int8 | Number | 8-bit signed integer |
| int16 | Number | 16-bit signed integer | | int16 | Number | 16-bit signed integer |
| int32 | Number | 32-bit signed integer | | int32 | Number | 32-bit signed integer |
| int64 | Number | 64-bit signed integer | | int64 | Number | 64-bit signed integer |
| uint8 | Number | 8-bit unsigned integer | | uint8 | Number | 8-bit unsigned integer |
| uint16 | Number | 16-bit unsigned integer | | uint16 | Number | 16-bit unsigned integer |
skipping to change at page 23, line 5 skipping to change at page 23, line 5
cases are implicitly deleted. The device handles the enforcement of cases are implicitly deleted. The device handles the enforcement of
the constraint, preventing incompatibilities from existing in the the constraint, preventing incompatibilities from existing in the
configuration. configuration.
The choice and case nodes appear only in the schema tree, not in the The choice and case nodes appear only in the schema tree, not in the
data tree or XML encoding. The additional levels of hierarchy are data tree or XML encoding. The additional levels of hierarchy are
not needed beyond the conceptual schema. not needed beyond the conceptual schema.
YANG Example: YANG Example:
container food {
choice snack { choice snack {
mandatory true; mandatory true;
case sports-arena { case sports-arena {
leaf pretzel { leaf pretzel {
type empty; type empty;
} }
leaf beer { leaf beer {
type empty; type empty;
} }
} }
case late-night { case late-night {
leaf chocolate { leaf chocolate {
type enumeration { type enumeration {
enum dark; enum dark;
enum milk; enum milk;
enum first-available; enum first-available;
} }
} }
} }
} }
}
NETCONF XML Encoding: NETCONF XML Encoding:
<food>
<chocolate>first-available</chocolate> <chocolate>first-available</chocolate>
</food>
The "choice" statement is covered in Section 7.9. The "choice" statement is covered in Section 7.9.
4.2.8. Extending Data Models (augment) 4.2.8. Extending Data Models (augment)
YANG allows a module to insert additional nodes into data models, YANG allows a module to insert additional nodes into data models,
including both the current module (and its submodules) or an external including both the current module (and its submodules) or an external
module. This is useful e.g. for vendors to add vendor-specific module. This is useful e.g. for vendors to add vendor-specific
parameters to standard data models in an interoperable way. parameters to standard data models in an interoperable way.
skipping to change at page 27, line 40 skipping to change at page 27, line 40
The names of all standard modules must be unique, but different The names of all standard modules must be unique, but different
revisions of the same module should have the same name. Developers revisions of the same module should have the same name. Developers
of enterprise modules are encouraged to choose names for their of enterprise modules are encouraged to choose names for their
modules that will have a low probability of colliding with standard modules that will have a low probability of colliding with standard
or other enterprise modules, e.g., by using the enterprise or or other enterprise modules, e.g., by using the enterprise or
organization name as a prefix. organization name as a prefix.
5.1.1. Module Hierarchies 5.1.1. Module Hierarchies
YANG allows modeling of data in multiple hierarchies, where data may YANG allows modeling of data in multiple hierarchies, where data may
have more than one root node. While it is recommended to use a model have more than one root node. Models that have multiple roots nodes
with a single root node, models that have multiple roots nodes are are sometimes convenient, and are supported by YANG.
sometimes convenient, and are supported by YANG.
Due to the possibility of multiple roots the modeled data does not
necessarily map to a well-formed XML document. Often a conceptual
root node (e.g. <data> or <config> element in NETCONF RPCs) is added
to overcome this problem.
5.2. File Layout 5.2. File Layout
YANG modules and submodules are typically stored in files, one module YANG modules and submodules are typically stored in files, one module
or submodule per file, with the name of the file given by the or submodule per file, with the name of the file given by the
concatenation of the module or submodule name and the file suffix concatenation of the module or submodule name and the file suffix
".yang". YANG compilers can find imported modules and included ".yang". YANG compilers can find imported modules and included
submodules via this convention. While the YANG language defines submodules via this convention. While the YANG language defines
modules, tools may compile submodules independently for performance modules, tools may compile submodules independently for performance
and manageability reasons. Many errors and warnings that cannot be and manageability reasons. Many errors and warnings that cannot be
skipping to change at page 28, line 45 skipping to change at page 28, line 39
5.4. XML Namespaces 5.4. XML Namespaces
All YANG definitions are specified within a particular XML Namespace. All YANG definitions are specified within a particular XML Namespace.
Each module defines an XML namespace as a globally unique URI Each module defines an XML namespace as a globally unique URI
[RFC3986]. A NETCONF client or server uses the namespace during XML [RFC3986]. A NETCONF client or server uses the namespace during XML
encoding of data. encoding of data.
The namespace URI is advertised as a capability in the NETCONF The namespace URI is advertised as a capability in the NETCONF
<hello> message to indicate support for the YANG module by a NETCONF <hello> message to indicate support for the YANG module by a NETCONF
server. server. The capability URI advertised SHOULD be on the form:
namespace-uri "?" revision
Where "revision" is the revision of the module (see Section 7.1.9)
that the server implements.
Namespaces for standard module names will be assigned by IANA. They Namespaces for standard module names will be assigned by IANA. They
MUST be unique (but different revisions of the same module should MUST be unique (but different revisions of the same module should
have the same namespace). have the same namespace).
Namespaces for private module names will be assigned by the Namespaces for private module names will be assigned by the
organization owning the module without a central registry. It is organization owning the module without a central registry. It is
recommended to choose namespaces that will have a low probability of recommended to choose namespaces that will have a low probability of
colliding with standard or other enterprise modules, e.g. by using colliding with standard or other enterprise modules, e.g. by using
the enterprise or organization name in the namespace. the enterprise or organization name in the namespace.
skipping to change at page 31, line 31 skipping to change at page 31, line 31
submodule, the developer has more control over what pieces of their submodule, the developer has more control over what pieces of their
module are presented to the outside world, supporting the need to module are presented to the outside world, supporting the need to
hide internal information and maintaining a boundary between what is hide internal information and maintaining a boundary between what is
shared with the outside world and what is kept private. shared with the outside world and what is kept private.
Scoped definitions MUST NOT shadow definitions at a higher scope. A Scoped definitions MUST NOT shadow definitions at a higher scope. A
type or group cannot be defined if a higher level in the schema type or group cannot be defined if a higher level in the schema
hierarchy has a definition with a matching identifier. hierarchy has a definition with a matching identifier.
When a YANG implementation resolves a reference to an unprefixed type When a YANG implementation resolves a reference to an unprefixed type
or grouping, it searches up the levels of hierarchy in the schema or grouping, or one which uses the prefix of the local module, it
tree, starting at the current level, for the definition of the type searches up the levels of hierarchy in the schema tree, starting at
or grouping. the current level, for the definition of the type or grouping.
6. YANG syntax 6. YANG syntax
The YANG syntax is similar to that of SMIng [RFC3780] and programming The YANG syntax is similar to that of SMIng [RFC3780] and programming
languages like C and C++. This C-like syntax was chosen specifically languages like C and C++. This C-like syntax was chosen specifically
for its readability, since YANG values the time and effort of the for its readability, since YANG values the time and effort of the
readers of models above those of modules writers and YANG tool-chain readers of models above those of modules writers and YANG tool-chain
developers. This section introduces the YANG syntax. developers. This section introduces the YANG syntax.
YANG modules are written in the UTF-8 [RFC3629] character set. YANG modules are written in the UTF-8 [RFC3629] character set.
skipping to change at page 32, line 42 skipping to change at page 32, line 42
A token in YANG is either a keyword, a string, ";", "{", or "}". A A token in YANG is either a keyword, a string, ";", "{", or "}". A
string can be quoted or unquoted. A keyword is either one of the string can be quoted or unquoted. A keyword is either one of the
core YANG keywords defined in this document, or a prefix identifier, core YANG keywords defined in this document, or a prefix identifier,
followed by ":", followed by a language extension keyword. Keywords followed by ":", followed by a language extension keyword. Keywords
are case sensitive. See Section 6.2 for a formal definition of are case sensitive. See Section 6.2 for a formal definition of
identifiers. identifiers.
6.1.3. Quoting 6.1.3. Quoting
If a string contains any whitespace characters, a semicolon (";"), If a string contains any whitespace characters, a semicolon (";"),
curly braces ("{ }"), or comment sequences ("//", "/*", or "*/"), curly braces ("{" or "}"), or comment sequences ("//", "/*", or
then it MUST be enclosed within double or single quotes. "*/"), then it MUST be enclosed within double or single quotes.
If the double quoted string contains a line break followed by If the double quoted string contains a line break followed by
whitespace which is used to indent the text according to the layout whitespace which is used to indent the text according to the layout
in the YANG file, this leading whitespace is stripped from the in the YANG file, this leading whitespace is stripped from the
string, up to at most the same column of the double quote character. string, up to at most the same column of the double quote character.
If the double quoted string contains whitespace before a line break, If the double quoted string contains whitespace before a line break,
this trailing whitespace is stripped from the string. this trailing whitespace is stripped from the string.
A single quoted string (enclosed within ' ') preserves each character A single quoted string (enclosed within ' ') preserves each character
skipping to change at page 34, line 13 skipping to change at page 34, line 13
"first line\n" + " second line" "first line\n" + " second line"
6.2. Identifiers 6.2. Identifiers
Identifiers are used to identify different kinds of YANG items by Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an upper-case or lower-case ASCII name. Each identifier starts with an upper-case or lower-case ASCII
letter or an underscore character, followed by zero or more ASCII letter or an underscore character, followed by zero or more ASCII
letters, digits, underscore characters, hyphens, and dots. letters, digits, underscore characters, hyphens, and dots.
Implementations MUST support identifiers up to 63 characters in Implementations MUST support identifiers up to 63 characters in
length. Identifiers are case sensitive. The identifier syntax is length. Identifiers are case sensitive. The identifier syntax is
formally defined by the rule "identifier" in Appendix D. Identifiers formally defined by the rule "identifier" in Section 11. Identifiers
can be specified as quoted or unquoted strings. can be specified as quoted or unquoted strings.
6.2.1. Identifiers and their namespaces 6.2.1. Identifiers and their namespaces
Each identifier is valid in a namespace which depends on the type of Each identifier is valid in a namespace which depends on the type of
the YANG item being defined: the YANG item being defined:
o All module and submodule names share the same global module o All module and submodule names share the same global module
identifier namespace. identifier namespace.
skipping to change at page 35, line 15 skipping to change at page 35, line 15
statement = keyword [argument] (";" / "{" *statement "}") statement = keyword [argument] (";" / "{" *statement "}")
The argument is a string, as defined in Section 6.1.2. The argument is a string, as defined in Section 6.1.2.
6.3.1. Language Extensions 6.3.1. Language Extensions
A module can introduce YANG extensions by using the "extension" A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.16). The extensions can be imported by other keyword (see Section 7.16). The extensions can be imported by other
modules with the "import" statement (see Section 7.1.5). When an modules with the "import" statement (see Section 7.1.5). When an
imported extension is used, the keyword must be qualified using the imported extension is used, the extension's keyword must be qualified
prefix with which the extension's module was imported. 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.
6.4. XPath Evaluations 6.4. XPath Evaluations
YANG relies on XPath as a notation for specifying many inter-node YANG relies on XPath 1.0 [XPATH] as a notation for specifying many
references and dependencies. NETCONF clients and servers are not inter-node references and dependencies. NETCONF clients and servers
required to implement an XPath interpreter, but MUST ensure that the are not required to implement an XPath interpreter, but MUST ensure
requirements encoded in the data model are enforced. The manner of that the requirements encoded in the data model are enforced. The
enforcement is an implementation decision. The XPath expressions manner of enforcement is an implementation decision. The XPath
MUST be valid, but any implementation may choose to implement them by expressions MUST be valid, but any implementation may choose to
hand, rather than using the XPath expression directly. implement them by hand, rather than using the XPath expression
directly.
XPath expressions are evaluated in the context of the current node, XPath expressions are evaluated in the context of the current node,
with the namespace of the current module defined as the null with the namespace of the current module defined as the null
namespace. References to identifiers in external modules MUST be namespace. References to identifiers in external modules MUST be
qualified with appropriate prefixes, and references to the current qualified with appropriate prefixes, and references to the current
module and its submodules MAY use a prefix. module and its submodules MAY use a prefix.
7. YANG Statements 7. YANG Statements
The following sections describe all of the YANG core statements. The following sections describe all of the YANG core statements.
skipping to change at page 39, line 6 skipping to change at page 39, line 6
and add the "yang-version 2" statement, or remain within the version and add the "yang-version 2" statement, or remain within the version
1 feature set and continue to use the default setting of "yang- 1 feature set and continue to use the default setting of "yang-
version 1". version 1".
7.1.3. The namespace Statement 7.1.3. The namespace Statement
The "namespace" statement defines the XML namespace for all XML The "namespace" statement defines the XML namespace for all XML
elements defined by the module. Its argument is the URI of the elements defined by the module. Its argument is the URI of the
namespace. namespace.
The namespace URI is advertised as a capability in the NETCONF
<hello> message to indicate support for the YANG module by a NETCONF
server. The capability URI advertised SHOULD be on the form:
namespace-uri "?" revision
Where "revision" is the revision of the module (see Section 7.1.9)
that the server implements.
See also Section 5.4. See also Section 5.4.
7.1.4. The prefix Statement 7.1.4. The prefix Statement
The "prefix" statement is used to define the prefix associated with The "prefix" statement is used to define the prefix associated with
the namespace of a module. The "prefix" statement's argument is the the namespace of a module. The "prefix" statement's argument is the
prefix string which is used as a prefix to access a module. The prefix string which is used as a prefix to access a module. The
prefix string may be used to refer to definitions contained in the prefix string may be used to refer to definitions contained in the
module, e.g. "if:ifName". A prefix follows the same rules as an module, e.g. "if:ifName". A prefix follows the same rules as an
identifier (see Section 6.2). identifier (see Section 6.2).
skipping to change at page 39, line 46 skipping to change at page 39, line 37
being imported is used in combination with a colon (":") and the being imported is used in combination with a colon (":") and the
identifier, e.g. "if:ifIndex". To improve readability of YANG identifier, e.g. "if:ifIndex". To improve readability of YANG
modules, the prefix defined by a module SHOULD be used when the modules, the prefix defined by a module SHOULD be used when the
module is imported, unless there is a conflict. module is imported, unless there is a conflict.
All prefixes, including the prefix for the module itself MUST be All prefixes, including the prefix for the module itself MUST be
unique within the module or submodule. unique within the module or submodule.
7.1.5. The import Statement 7.1.5. The import Statement
The "import" statement makes content from one module available inside The "import" statement makes definitions from one module available
another module or submodule. The argument is the name of the module inside another module or submodule. The argument is the name of the
to import, and the statement is followed by a block of substatements module to import, and the statement is followed by a block of
that holds detailed import information. substatements that holds detailed import information.
All identifiers contained in an imported module are imported into the All identifiers contained in an imported module are imported into the
current module or submodule, so that they can be referenced by current module or submodule, so that they can be referenced by
definitions in the current module or submodule. The mandatory definitions in the current module or submodule. The mandatory
"prefix" substatement assigns a prefix for the imported module which "prefix" substatement assigns a prefix for the imported module which
is scoped to the importing module or submodule. Multiple "import" is scoped to the importing module or submodule. Multiple "import"
statements may be specified to import from different modules. statements may be specified to import from different modules.
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 40, line 24 skipping to change at page 40, line 19
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.6. The include Statement 7.1.6. The include Statement
The "include" statement is used to make content from a submodule The "include" statement is used to make content from a submodule
available to the module. The argument is an identifier which is the available to the module. The argument is an identifier which is the
name of the submodule to include. Modules are only allowed to name of the submodule to include. Modules are only allowed to
include submodules that belong to that module, as defined by the include submodules that belong to that module, as defined by the
"belongs-to" statement (see Section 7.2.2). "belongs-to" statement (see Section 7.2.2).
When a module includes a submodule, it incorporates the contents of
the submodule into the node hierarchy of the module. When a
submodule includes another submodule, the target submodule's
definitions are made available to the current submodule.
7.1.7. The organization Statement 7.1.7. The organization Statement
The "organization" statement defines the party responsible for this The "organization" statement defines the party responsible for this
module. The argument is a string which is used to specify a textual module. The argument is a string which is used to specify a textual
description of the organization(s) under whose auspices this module description of the organization(s) under whose auspices this module
was developed. was developed.
7.1.8. The contact Statement 7.1.8. The contact Statement
The "contact" statement provides contact information for the module. The "contact" statement provides contact information for the module.
skipping to change at page 47, line 32 skipping to change at page 47, line 32
7.4.1. The type's Substatements 7.4.1. The type's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| bit | 8.6.3 | 0..n | | bit | 8.6.3 | 0..n |
| enum | 8.5.3 | 0..n | | enum | 8.5.3 | 0..n |
| length | 8.3.3 | 0..1 | | length | 8.3.3 | 0..1 |
| path | 8.8.2 | 0..1 | | path | 8.8.2 | 0..1 |
| pattern | 8.3.4 | 0..1 | | pattern | 8.3.5 | 0..n |
| range | 8.1.3 | 0..1 | | range | 8.1.3 | 0..1 |
| type | 7.4 | 0..n | | type | 7.4 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.5. The container Statement 7.5. The container Statement
The "container" statement is used to define an interior node in the The "container" statement is used to define an interior node in the
schema tree. It takes one argument, which is an identifier, followed schema tree. It takes one argument, which is an identifier, followed
by a block of substatements that holds detailed container by a block of substatements that holds detailed container
information. information.
skipping to change at page 48, line 37 skipping to change at page 48, line 37
7.5.2. The must Statement 7.5.2. The must Statement
The "must" statement, which is optional, takes as an argument a The "must" statement, which is optional, takes as an argument a
string which contains an XPath expression. It is used to formally string which contains an XPath expression. It is used to formally
declare a constraint on the configuration data. When a configuration declare a constraint on the configuration data. When a configuration
datastore is validated, all "must" constraints are conceptually datastore is validated, all "must" constraints are conceptually
evaluated once for each corresponding instance in the datastore's evaluated once for each corresponding instance in the datastore's
data tree, and for all leafs with default values in effect. If an data tree, and for all leafs with default values in effect. If an
instance does not exist in the data tree, and it does not have a instance does not exist in the data tree, and it does not have a
default value, its "must" statements are not evaluated. Within a default value, its "must" statements are not evaluated.
"must" expression,
All such constraints MUST evaluate to true for the configuration to All such constraints MUST evaluate to true for the configuration to
be valid. be valid.
The "must" statement is ignored if the data does not represent The "must" statement is ignored if the data does not represent
configuration. configuration.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context: context:
o The context node is the node in the data tree for which the "must" o The context node is the node in the data tree for which the "must"
statement is defined. statement is defined.
o The accessible tree is made up of all nodes in the data tree, and o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values. all leafs with default values.
o The set of namespace declarations is the set of all "import" o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix" statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI. statement's prefix for the "namespace" statement's URI.
o The null namespace is defined to be the namespace of the current o Elements without a namespace refer to nodes in the current module.
module.
o One variable "this", which is the context node, is defined. o The function library is the core function library defined in
[XPATH], and a function "current()" which returns a node set with
the initial context node.
The result of the XPath expression is converted to a boolean value The result of the XPath expression is converted to a boolean value
using the standard XPath rules. using the standard XPath rules.
If the node with the must statement represents configuration data,
any node referenced in the XPath expression MUST also represent
configuration.
Note that the XPath expression is conceptually evaluated. This means Note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator on the that an implementation does not have to use an XPath evaluator on the
device. How the evaluation is done in practice is an implementation device. How the evaluation is done in practice is an implementation
decision. decision.
7.5.3. The must's Substatements 7.5.3. The must's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
skipping to change at page 60, line 38 skipping to change at page 60, line 38
| unique | 7.8.3 | 0..n | | unique | 7.8.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.8.2. The list's key Statement 7.8.2. The list's key Statement
The "key" statement, which MUST be present if the list represents The "key" statement, which MUST be present if the list represents
configuration, and MAY be present otherwise, takes as an argument a configuration, and MAY be present otherwise, takes as an argument a
string which specifies a space separated list of leaf identifiers of string which specifies a space separated list of leaf identifiers of
this list. A leaf identifier MUST NOT appear more than once in the this list. A leaf identifier MUST NOT appear more than once in the
key. key. Each such leaf identifier MUST refer to a child leaf of the
list.
The combined values of all the leafs specified in the key are used to The combined values of all the leafs specified in the key are used to
uniquely identify a list entry. All key leafs MUST be given values uniquely identify a list entry. All key leafs MUST be given values
when a list entry is created. Thus, any default values in the key when a list entry is created. Thus, any default values in the key
leafs or their types are ignored. It also implies that any mandatory leafs or their types are ignored. It also implies that any mandatory
statement in the key leafs are ignored. statement in the key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived A leaf that is part of the key can be of any built-in or derived
type, except it MUST NOT be the built-in type "empty". type, except it MUST NOT be the built-in type "empty".
All key leafs in a list MUST have the same value for their "config" All key leafs in a list MUST have the same value for their "config"
as the list itself. as the list itself.
The key string syntax is formally defined by the rule "key-arg" in The key string syntax is formally defined by the rule "key-arg" in
Appendix D. Section 11.
7.8.3. The lists's unique Statement 7.8.3. The lists's unique Statement
The "unique" statement is used to put constraints on valid The "unique" statement is used to put constraints on valid
configurations. It takes as an argument a string which contains a configurations. It takes as an argument a string which contains a
space separated list of schema node identifiers, which MUST be given space separated list of schema node identifiers, which MUST be given
in the descendant form. Each such schema node identifier MUST refer in the descendant form (see the rule "descendant-schema-nodeid" in
to a leaf. Section 11). Each such schema node identifier MUST refer to a leaf.
In a valid configuration, the combined values of all the leaf In a valid configuration, the combined values of all the leaf
instances specified in the string MUST be unique within all list instances specified in the string MUST be unique within all list
entry instances. entry instances.
The unique string syntax is formally defined by the rule "unique-arg" The unique string syntax is formally defined by the rule "unique-arg"
in Appendix D. in Section 11.
7.8.3.1. Usage Example 7.8.3.1. Usage Example
With the following list: With the following list:
list server { list server {
key "name"; key "name";
unique "ip port"; unique "ip port";
leaf name { leaf name {
type string; type string;
skipping to change at page 66, line 19 skipping to change at page 66, line 19
followed by a block of substatements that holds detailed choice followed by a block of substatements that holds detailed choice
information. The identifier is used to identify the choice node in information. The identifier is used to identify the choice node in
the schema tree. A choice node does not exist in the data tree. the schema tree. A choice node does not exist in the data tree.
A choice consists of a number of branches, defined with the case A choice consists of a number of branches, defined with the case
substatement. Each branch contains a number of child nodes. The substatement. Each branch contains a number of child nodes. The
"choice" statement puts a constraint on a valid configuration. In a "choice" statement puts a constraint on a valid configuration. In a
valid configuration, the nodes from at most one of the choice's valid configuration, the nodes from at most one of the choice's
branches exist at the same time. branches exist at the same time.
If a choice is marked with "mandatory true", at least one node from
one of the cases must be present in a valid configuration.
See Section 4.2.7 for additional information. See Section 4.2.7 for additional information.
7.9.1. The choice's Substatements 7.9.1. The choice's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| case | 7.9.2 | 0..n | | case | 7.9.2 | 0..n |
| config | 7.17.1 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| default | 7.9.3 | 0..1 | | default | 7.9.3 | 0..1 |
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| mandatory | 7.9.4 | 0..1 | | mandatory | 7.9.4 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
| status | 7.17.2 | 0..1 | | status | 7.17.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 68, line 29 skipping to change at page 68, line 29
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.9.3. The choice's default Statement 7.9.3. The choice's default Statement
The "default" statement indicates if a case should be considered as The "default" statement indicates if a case should be considered as
the default if no child nodes from any of the choice's cases exists. the default if no child nodes from any of the choice's cases exists.
The argument is the identifier of the "case" statement. If the The argument is the identifier of the "case" statement. If the
"default" statement is missing, there is no default case. "default" statement is missing, there is no default case.
The "default" statement MUST NOT be present on choices where
"mandatory" is true.
The default case is only important when considering the default The default case is only important when considering the default
values of nodes under the cases. The default values for nodes under values of nodes under the cases. The default values for nodes under
the default case are used if none of the nodes under any of the cases the default case are used if none of the nodes under any of the cases
are present. are present.
There MUST NOT be any mandatory child nodes under the default case. There MUST NOT be any mandatory nodes (Section 3.1) under the default
case.
Default values for child nodes under a case are only used if one of Default values for child nodes under a case are only used if one of
the nodes under that case is present, or if that case is the default the nodes under that case is present, or if that case is the default
case. If none of the nodes under a case are present and the case is case. If none of the nodes under a case are present and the case is
not the default case, the default values of the cases' child nodes not the default case, the default values of the cases' child nodes
are ignored. are ignored.
In this example, the choice defaults to "interval", and the default In this example, the choice defaults to "interval", and the default
value will be used if none of "daily", "time-of-day", or "manual" are value will be used if none of "daily", "time-of-day", or "manual" are
present. If "daily" is present, the default value for "time-of-day" present. If "daily" is present, the default value for "time-of-day"
skipping to change at page 69, line 36 skipping to change at page 69, line 36
leaf manual { leaf manual {
type empty; type empty;
} }
} }
} }
} }
7.9.4. The choice's mandatory Statement 7.9.4. The choice's mandatory Statement
The "mandatory" statement, which is optional, takes as an argument The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false". If "mandatory" is "true", nodes from the string "true" or "false". If "mandatory" is "true", at least one
exactly one of the choice's case branches MUST exist in a valid node from exactly one of the choice's case branches MUST exist in a
configuration. valid configuration. If "mandatory" is "false", a valid
configuration MAY have no nodes from the choice's case branches
present.
If not specified, the default is "false". If not specified, the default is "false".
7.9.5. XML Encoding Rules 7.9.5. XML Encoding Rules
The choice and case nodes are not visible in XML. The choice and case nodes are not visible in XML.
7.9.6. NETCONF <edit-config> operations 7.9.6. NETCONF <edit-config> operations
Since only one of the choices cases can be valid at any time, the Since only one of the choices cases can be valid at any time, the
skipping to change at page 71, line 12 skipping to change at page 71, line 12
</edit-config> </edit-config>
</rpc> </rpc>
7.10. The anyxml Statement 7.10. The anyxml Statement
The "anyxml" statement defines an interior node in the schema tree. The "anyxml" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anyxml information. substatements that holds detailed anyxml information.
The anyxml statement is used to represent an unknown chunk of XML. The anyxml statement is used to represent an unknown chunk of XML.
This can be useful in e.g. RPC replies. An example is the <filter> No restrictions are placed on the XML. This can be useful in e.g.
parameter in the <get-config> operation. RPC replies. An example is the <filter> parameter in the <get-
config> operation.
An anyxml node cannot be augmented. An anyxml node cannot be augmented.
It is NOT RECOMMENDED that the anyxml statement is used to represent It is NOT RECOMMENDED that the anyxml statement is used to represent
configuration data. configuration data.
7.10.1. The anyxml's Substatements 7.10.1. The anyxml's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 73, line 6 skipping to change at page 73, line 7
which is an identifier, followed by a block of substatements that which is an identifier, followed by a block of substatements that
holds detailed grouping information. holds detailed grouping information.
The grouping statement is not a data definition statement and, as The grouping statement is not a data definition statement and, as
such, does not define any nodes in the schema tree. such, does not define any nodes in the schema tree.
A grouping is like a "structure" or a "record" in conventional A grouping is like a "structure" or a "record" in conventional
programming languages. programming languages.
Once a grouping is defined, it can be referenced in a "uses" Once a grouping is defined, it can be referenced in a "uses"
statement (see Section 7.12). statement (see Section 7.12). A grouping MUST NOT reference itself,
neither directly nor indirectly through a chain of other groupings.
If the grouping is defined at the top level of a YANG module or If the grouping is defined at the top level of a YANG module or
submodule, the grouping's identifier MUST be unique within the submodule, the grouping's identifier MUST be unique within the
module. For details about scoping for nested groupings, see module. For details about scoping for nested groupings, see
Section 5.8. Section 5.8.
A grouping is more than just a mechanism for textual substitution, A grouping is more than just a mechanism for textual substitution,
but defines a collection of nodes. References from inside the but defines a collection of nodes. References from inside the
grouping are relative to the scope in which the grouping is defined, grouping are relative to the scope in which the grouping is defined,
not where it is used. Prefix mappings, type names, grouping names, not where it is used. Prefix mappings, type names, grouping names,
skipping to change at page 75, line 27 skipping to change at page 75, line 27
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
| status | 7.17.2 | 0..1 | | status | 7.17.2 | 0..1 |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.12.2. The uses's Refinement Statements 7.12.2. The uses's Refinement Statements
Some of the properties of each node in the grouping can be refined in Some of the properties of each node in the grouping can be refined in
substatements to "uses". If a node is not present in a substatement, substatements to "uses". If a node is not present in a substatement,
it is not refined, and thus used exactly as it was defined in the it is not refined, and thus used exactly as it was defined in the
"grouping". The refinement substatements MUST be specified in the "grouping". A node can be refined only once in "uses".
same order as in the grouping, and a node can be refined only once.
The following refinements can be done: The following refinements can be done:
o A leaf or choice node may get a default value, or a new default o A leaf or choice node may get a default value, or a new default
value if it already had one. value if it already had one.
o Any node may get a specialized "description" string. o Any node may get a specialized "description" string.
o Any node may get a specialized "reference" string. o Any node may get a specialized "reference" string.
skipping to change at page 77, line 31 skipping to change at page 77, line 31
7.13. The rpc Statement 7.13. The rpc Statement
The "rpc" statement is used to define a NETCONF RPC method. It takes The "rpc" statement is used to define a NETCONF RPC method. It takes
one argument, which is an identifier, followed by a block of one argument, which is an identifier, followed by a block of
substatements that holds detailed rpc information. This argument is substatements that holds detailed rpc information. This argument is
the name of the RPC, and is used as the element name directly under the name of the RPC, and is used as the element name directly under
the <rpc> element, as designated by the substitution group the <rpc> element, as designated by the substitution group
"rpcOperation" in [RFC4741]. "rpcOperation" in [RFC4741].
The rpc "statement" defines an rpc node in the schema tree. The "rpc" statement defines an rpc node in the schema tree. Under
the rpc node, an input node with the name "input", and an output node
with the name "output" are also defined. The nodes "input" and
"output" are defined in the module's namespace.
7.13.1. The rpc's Substatements 7.13.1. The rpc's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
| input | 7.13.2 | 0..1 | | input | 7.13.2 | 0..1 |
| output | 7.13.3 | 0..1 | | output | 7.13.3 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
| status | 7.17.2 | 0..1 | | status | 7.17.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.13.2. The input Statement 7.13.2. The input Statement
The "input" statement, which is optional, is used to define input The "input" statement, which is optional, is used to define input
parameters to the RPC method. It does not take an argument. The parameters to the RPC method. It does not take an argument. The
"input" statement defines an input node in the schema tree, with the substatements to "input" defines nodes under the RPC's input node.
name "input".
If a container in the input tree has a "presence" statement, the If a container in the input tree has a "presence" statement, the
container need not be present in a NETCONF RPC invocation. container need not be present in a NETCONF RPC invocation.
If a leaf in the input tree has a "mandatory" statement with the 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. value "true", the leaf MUST be present in a NETCONF RPC invocation.
If a leaf in the input tree has a default value, the NETCONF server If a leaf in the input tree has a default value, the NETCONF server
MUST internally use this default if the leaf is not present in a MUST internally use this default if the leaf is not present in a
NETCONF RPC invocation. NETCONF RPC invocation.
skipping to change at page 78, line 39 skipping to change at page 79, line 26
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.13.3. The output Statement 7.13.3. The output Statement
The "output" statement, which is optional, is used to define output The "output" statement, which is optional, is used to define output
parameters to the RPC method. It does not take an argument. The parameters to the RPC method. It does not take an argument. The
"output" statement defines an output node in the schema tree, with substatements to "output" defines nodes under the RPC's output node.
the name "output".
If a container in the output tree has a "presence" statement, the If a container in the output tree has a "presence" statement, the
container need not be present in a NETCONF RPC reply container need not be present in a NETCONF RPC reply
If a leaf in the output tree has a "mandatory" statement with the 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. 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 If a leaf in the output tree has a default value, the NETCONF client
MUST internally use this default if the leaf is not present in a MUST internally use this default if the leaf is not present in a
NETCONF RPC reply. NETCONF RPC reply.
skipping to change at page 79, line 23 skipping to change at page 80, line 22
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.13.4. XML Encoding Rules
An rpc node is encoded as a child XML element to the <rpc> element
defined in [RFC4741]. The element's name is the rpc's identifier,
and its XML namespace is the module's XML namespace.
Input parameters are encoded as child XML elements to the rpc node's
XML element, in the same order as they are defined within the input
statement.
If the rpc method invocation succeeded, and no output parameters are
returned, the <rpc-reply> contains a single <ok/> element defined in
[RFC4741]. If output parameters are returned, they are encoded as
child elements to the <rpc-reply> element defined in [RFC4741], in
the same order as they are defined within the output statement.
7.13.5. Usage Example
The following example defines an RPC method:
module rock {
namespace "http://example.net/rock";
prefix rock;
rpc rock-the-house {
input {
leaf zip-code {
type string;
}
}
}
}
A corresponding XML encoding of the complete rpc and rpc-reply:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rock-the-house xmlns="http://example.net/rock">
<zip-code>27606-0100</zip-code>
</rock-the-house>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
7.14. The notification Statement 7.14. The notification Statement
The "notification" statement is used to define a NETCONF The "notification" statement is used to define a NETCONF
notification. It takes one argument, which is an identifier, notification. It takes one argument, which is an identifier,
followed by a block of substatements that holds detailed notification followed by a block of substatements that holds detailed notification
information. The notification "statement" defines a notification information. The notification "statement" defines a notification
node in the schema tree. node in the schema tree.
If a container in the notification tree has a "presence" statement, If a container in the notification tree has a "presence" statement,
the container need not be present in a NETCONF notification. the container need not be present in a NETCONF notification.
skipping to change at page 80, line 25 skipping to change at page 82, line 25
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
| status | 7.17.2 | 0..1 | | status | 7.17.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.2. XML Encoding Rules
A notification node is encoded as a child XML element to the
<notification> element defined in [RFC5277]. The element's name is
the notification's identifier, and its XML namespace is the module's
XML namespace.
The notifications's child nodes are encoded as subelements to the
notification node's XML element, in the same order as they are
defined within the notification statement.
7.14.3. Usage Example
The following example defines a notification:
module event {
namespace "http://example.com/event";
prefix ev;
notification event {
leaf event-class {
type string;
}
anyxml reporting-entity;
leaf severity {
type string;
}
}
}
A corresponding XML encoding of the complete notification:
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-07-08T00:01:00Z</eventTime>
<event xmlns="http://example.com/event">
<event-class>fault</event-class>
<reporting-entity>
<card>Ethernet0</card>
</reporting-entity>
<severity>major</severity>
</event>
</notification>
7.15. The augment Statement 7.15. The augment Statement
The "augment" statement allows a module or submodule to add to the The "augment" statement allows a module or submodule to add to the
schema tree defined in another module or submodule. The argument is schema tree defined in another module or submodule. The argument is
a string which identifies a node in the schema tree. This node is a string which identifies a node in the schema tree. This node is
called the augment's target node. The target node MUST be either a called the augment's target node. The target node MUST be either a
container, list, choice, case, rpc, input, output, or notification container, list, choice, case, input, output, or notification node.
node. It is augmented with the nodes defined in the substatements It is augmented with the nodes defined in the substatements that
that follow the "augment" statement. follow the "augment" statement.
The augment string is a schema node identifier. The syntax is The augment string is a schema node identifier. The syntax is
formally defined by the rule "augment-arg" in Appendix D. If the formally defined by the rule "augment-arg" in Section 11. If the
"augment" statement is on the top-level in a module or submodule, the "augment" statement is on the top-level in a module or submodule, the
absolute form of a schema node identifier MAY be used. Otherwise, absolute form (defined by the rule "absolute-schema-nodeid" in
the descendant form MUST be used. Section 11) of a schema node identifier MAY be used. Otherwise, the
descendant form (defined by the rule "descendant-schema-nodeid" in
Section 11) MUST be used.
The syntax for a schema node identifier is a subset of the XPath The syntax for a schema node identifier is a subset of the XPath
syntax. It is an absolute or relative XPath location path in syntax. It is an absolute or relative XPath location path in
abbreviated syntax, where axes and predicates are not permitted. abbreviated syntax, where axes and predicates are not permitted.
If the target node is a container, list, case, input, output, or If the target node is a container, list, case, input, output, or
notification node, the "container", "leaf", "list", "leaf-list", notification node, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used within the "augment" "uses", and "choice" statements can be used within the "augment"
statement. statement.
If the target node is a choice node, the "case" statement can be used If the target node is a choice node, the "case" statement can be used
within the "augment" statement. within the "augment" statement.
If the target node is rpc node, the "input" and "output" statements If the target node is in another module, then nodes added by the
can be used within the "augment" statement. augmentation MUST NOT be mandatory nodes (see Section 3.1).
7.15.1. The augment's Substatements 7.15.1. The augment's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n | | augment | 7.15 | 0..n |
| case | 7.9.2 | 0..n | | case | 7.9.2 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
skipping to change at page 81, line 46 skipping to change at page 85, line 10
otherwise it is not. otherwise it is not.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context: context:
o The context node is the augment's target node in the data tree, if o 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 target node is a data node. Otherwise, the context node is
the closest ancestor node to the target node which is also a data the closest ancestor node to the target node which is also a data
node. node.
o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values.
o The set of namespace declarations is the set of all "import" o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix" statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI. statement's prefix for the "namespace" statement's URI.
o The null namespace is defined to be the namespace of the current o Elements without a namespace refer to nodes in the current module.
module.
o One variable "this", which is the context node, is defined. o The function library is the core function library defined in
[XPATH], and a function "current()" which returns a node set with
the initial context node.
The result of the XPath expression is converted to a boolean value The result of the XPath expression is converted to a boolean value
using the standard XPath rules. using the standard XPath rules.
Note that the XPath expression is conceptually evaluated. This means Note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator on the that an implementation does not have to use an XPath evaluator on the
device. The augment can very well be implemented with specially device. The augment can very well be implemented with specially
written code. written code.
7.15.3. XML Encoding Rules 7.15.3. XML Encoding Rules
skipping to change at page 84, line 24 skipping to change at page 87, line 44
The "extension" statement allows the definition of new statements The "extension" statement allows the definition of new statements
within the YANG language. This new statement definition can be within the YANG language. This new statement definition can be
imported and used by other modules. imported and used by other modules.
The statement's argument is an identifier that is the new keyword for The statement's argument is an identifier that is the new keyword for
the extension and must be followed by a block of substatements that the extension and must be followed by a block of substatements that
holds detailed extension information. The purpose of the extension holds detailed extension information. The purpose of the extension
statement is to define a keyword, so that it can be imported and used statement is to define a keyword, so that it can be imported and used
by other modules. by other modules.
The extension can be used by like a normal YANG statement, with the The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the statement name followed by an argument if one is defined by the
extension, and an optional block of substatements. The statement's extension, and an optional block of substatements. The statement's
name is created by combining the the prefix of the module in which name is created by combining the the prefix of the module in which
the extension was defined, a colon (":"), and the extension's the extension was defined, a colon (":"), and the extension's
keyword, with no interleaving whitespace. The substatements of an keyword, with no interleaving whitespace. The substatements of an
extension are defined by the extension, using some mechanism outside extension are defined by the extension, using some mechanism outside
the scope of this specification. Syntactically, the substatements the scope of this specification. Syntactically, the substatements
MUST be core YANG statements, or also defined using "extension" MUST be core YANG statements, or also defined using "extension"
statements. Core YANG statements in extensions MUST follow the statements. Core YANG statements in extensions MUST follow the
syntactical rules in Appendix D. syntactical rules in Section 11.
7.16.1. The extension's Substatements 7.16.1. The extension's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| argument | 7.16.2 | 0..1 | | argument | 7.16.2 | 0..1 |
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
| status | 7.17.2 | 0..1 | | status | 7.17.2 | 0..1 |
skipping to change at page 85, line 23 skipping to change at page 88, line 43
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| yin-element | 7.16.2.2 | 0..1 | | yin-element | 7.16.2.2 | 0..1 |
+--------------+----------+-------------+ +--------------+----------+-------------+
7.16.2.2. The yin-element Statement 7.16.2.2. The yin-element Statement
The "yin-element" statement, which is optional, takes as an argument The "yin-element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the the string "true" or "false". This statement indicates if the
argument should be mapped to an XML element in YIN or to an XML argument should be mapped to an XML element in YIN or to an XML
attribute. (see Appendix B). attribute. (see Section 10).
If no "yin-element" statement is present, it defaults to "false". If no "yin-element" statement is present, it defaults to "false".
7.16.3. Usage Example 7.16.3. Usage Example
To define an extension: To define an extension:
module my-extensions { module my-extensions {
... ...
skipping to change at page 88, line 13 skipping to change at page 91, line 13
definition. definition.
8. Built-in Types 8. Built-in Types
YANG has a set of built-in types, similar to those of many YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special programming languages, but with some differences due to special
requirements from the management information model. requirements from the management information model.
Additional types may be defined, derived from those built-in types or Additional types may be defined, derived from those built-in types or
from other derived types. Derived types may use subtyping to from other derived types. Derived types may use subtyping to
formally restrict the set of possible values. An initial set of formally restrict the set of possible values.
commonly used derived types is defined in the YANG standard modules
"yang-types" (Appendix A.1), "inet-types" (Appendix A.2), and "ieee-
types" (Appendix A.3).
The different built-in types and their derived types allow different The different built-in types and their derived types allow different
kinds of subtyping, namely length and regular expression restrictions kinds of subtyping, namely length and regular expression restrictions
of strings (Section 8.3.3, Section 8.3.4) and range restrictions of of strings (Section 8.3.3, Section 8.3.5) and range restrictions of
numeric types (Section 8.1.3). numeric types (Section 8.1.3).
The lexicographic representation of a value of a certain type is used The lexicographic representation of a value of a certain type is used
in the XML encoding over NETCONF, and when specifying default values in the XML encoding over NETCONF, and when specifying default values
in a YANG module. in a YANG module.
8.1. The Integer Built-in Types 8.1. The Integer Built-in Types
The integer built-in types are int8, int16, int32, int64, uint8, The integer built-in types are int8, int16, int32, int64, uint8,
uint16, uint32, and uint64. They represent signed and unsigned uint16, uint32, and uint64. They represent signed and unsigned
skipping to change at page 90, line 7 skipping to change at page 93, line 4
types derived from those. types derived from those.
A range consists of an explicit value, or a lower inclusive bound, A range consists of an explicit value, or a lower inclusive bound,
two consecutive dots "..", and an upper inclusive bound. Multiple two consecutive dots "..", and an upper inclusive bound. Multiple
values or ranges can be given, separated by "|". If multiple values values or ranges can be given, separated by "|". If multiple values
or ranges are given they all MUST be disjoint and MUST be in or ranges are given they all MUST be disjoint and MUST be in
ascending order. If a value restriction is applied to an already ascending order. If a value restriction is applied to an already
restricted type, the new restriction MUST be equal or more limiting, restricted type, the new restriction MUST be equal or more limiting,
that is raising the lower bounds, reducing the upper bounds, removing that is raising the lower bounds, reducing the upper bounds, removing
explicit values or ranges, or splitting ranges into multiple ranges explicit values or ranges, or splitting ranges into multiple ranges
with intermediate gaps. Each range boundary value given in the range with intermediate gaps. Each explicit value and range boundary value
expression MUST match the type being restricted, or be one of the given in the range expression MUST match the type being restricted,
special values "min" or "max". "min" and "max" means the minimum and or be one of the special values "min" or "max". "min" and "max" means
maximum value accepted for the type being restricted, respectively. the minimum and maximum value accepted for the type being restricted,
respectively.
The range expression syntax is formally defined by the rule "range- The range expression syntax is formally defined by the rule "range-
expr" in Appendix D. arg" in Section 11.
8.1.3.1. The range's Substatements 8.1.3.1. The range's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| error-app-tag | 7.5.3.2 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.3.1 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
8.1.4. Usage Example 8.1.4. Usage Example
typedef my-base-int32-type {
type int32 { type int32 {
range "1..4 | 10 | 20..max"; range "1..4 | 10..20";
}
}
type my-base-int32-type {
// legal range restriction
range "11..max"; // 11..20
}
type int32 {
// illegal range restriction
range "11..100";
} }
8.2. The Floating Point Built-in Types 8.2. The Floating Point Built-in Types
The floating point built-in types are float32 and float64. They The floating point built-in types are float32 and float64. They
represent floating point values of single and double precision as represent floating point values of single and double precision as
defined in [IEEE.754]. Special values are positive and negative defined in [IEEE.754]. Special values are positive and negative
infinity, and not-a-number. infinity, and not-a-number.
8.2.1. Lexicographic Representation 8.2.1. Lexicographic Representation
skipping to change at page 91, line 37 skipping to change at page 94, line 51
%x10000-10FFFF %x10000-10FFFF
8.3.1. Lexicographic Representation 8.3.1. Lexicographic Representation
A string value is lexicographically represented as character data in A string value is lexicographically represented as character data in
the XML encoding. the XML encoding.
8.3.2. Restrictions 8.3.2. Restrictions
A string can be restricted with the "length" (Section 8.3.3) and A string can be restricted with the "length" (Section 8.3.3) and
"pattern" (Section 8.3.4) statements. "pattern" (Section 8.3.5) statements.
8.3.3. The length Statement 8.3.3. The length Statement
The "length" statement, which is an optional substatement to the The "length" statement, which is an optional substatement to the
"type" statement, takes as an argument a length expression string. "type" statement, takes as an argument a length expression string.
It is used to restrict the built-in type "string", or types derived It is used to restrict the built-in type "string", or types derived
from "string". from "string".
A "length" statement restricts the number of characters in the A "length" statement restricts the number of characters in the
string. string.
skipping to change at page 92, line 16 skipping to change at page 95, line 31
MUST be equal or more limiting, that is, raising the lower bounds, MUST be equal or more limiting, that is, raising the lower bounds,
reducing the upper bounds, removing explicit length values or ranges, reducing the upper bounds, removing explicit length values or ranges,
or splitting ranges into multiple ranges with intermediate gaps. A or splitting ranges into multiple ranges with intermediate gaps. A
length value is a non-negative integer, or one of the special values length value is a non-negative integer, or one of the special values
"min" or "max". "min" and "max" means the minimum and maximum length "min" or "max". "min" and "max" means the minimum and maximum length
accepted for the type being restricted, respectively. An accepted for the type being restricted, respectively. An
implementation is not required to support a length value larger than implementation is not required to support a length value larger than
18446744073709551615. 18446744073709551615.
The length expression syntax is formally defined by the rule "length- The length expression syntax is formally defined by the rule "length-
expr" in Appendix D. arg" in Section 11.
8.3.3.1. The length's Substatements 8.3.3.1. The length's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| error-app-tag | 7.5.3.2 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.3.1 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
8.3.4. The pattern Statement 8.3.4. Usage Example
typedef my-base-str-type {
type string {
length "1..255";
}
}
type my-base-str-type {
// legal length refinement
length "11 | 42..max"; // 11 | 42..255
}
type my-base-str-type {
// illegal length refinement
length "1..999";
}
8.3.5. The pattern Statement
The "pattern" statement, which is an optional substatement to the The "pattern" statement, which is an optional substatement to the
"type" statement, takes as an argument a regular expression string, "type" statement, takes as an argument a regular expression string,
as defined in [XSD-TYPES]. It is used to restrict the built-in type as defined in [XSD-TYPES]. It is used to restrict the built-in type
"string", or types derived from "string", to values that completely "string", or types derived from "string", to values that completely
matches the pattern. matches the pattern.
8.3.4.1. The pattern's Substatements If the type has multiple "pattern" statements, the expressions are
AND:ed together, i.e. all such expressions have to match.
8.3.5.1. The pattern's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.17.3 | 0..1 | | description | 7.17.3 | 0..1 |
| error-app-tag | 7.5.3.2 | 0..1 | | error-app-tag | 7.5.3.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.3.1 | 0..1 |
| reference | 7.17.4 | 0..1 | | reference | 7.17.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
8.3.5. Usage Example 8.3.6. Usage Example
With the following type: With the following type:
type string { type string {
length "0..4"; length "0..4";
pattern "[0-9a-fA-F]*"; pattern "[0-9a-fA-F]*";
} }
the following strings match: the following strings match:
AB // legal AB // legal
9A00 // legal 9A00 // legal
and the following strings do not match: and the following strings do not match:
00ABAB // illegal 00ABAB // illegal
xx00 // illegal xx00 // illegal
skipping to change at page 98, line 9 skipping to change at page 101, line 38
where axes are not permitted, and predicates are used only for where axes are not permitted, and predicates are used only for
constraining the values for the key nodes for list entries. Each constraining the values for the key nodes for list entries. Each
predicate consists of at most one equality test per key. predicate consists of at most one equality test per key.
The predicates are only used when more than one key reference is The predicates are only used when more than one key reference is
needed to uniquely identify a list entry. This occurs if the list needed to uniquely identify a list entry. This occurs if the list
has multiple keys, or a reference to a list within a list is needed. has multiple keys, or a reference to a list within a list is needed.
In these cases, multiple keyref leafs are typically specified, and In these cases, multiple keyref leafs are typically specified, and
predicates are used to tie them together. predicates are used to tie them together.
The syntax is formally defined by the rule "path-arg" in Appendix D. The syntax is formally defined by the rule "path-arg" in Section 11.
8.8.3. Lexicographic Representation 8.8.3. Lexicographic Representation
A keyref value is encoded the same way as the key it references. A keyref value is encoded the same way as the key it references.
8.8.4. Usage Example 8.8.4. Usage Example
With the following list: With the following list:
list interface { list interface {
skipping to change at page 99, line 13 skipping to change at page 102, line 47
The following keyrefs refer to an existing address of an interface: The following keyrefs refer to an existing address of an interface:
container default-address { container default-address {
leaf ifname { leaf ifname {
type keyref { type keyref {
path "../../interface/name"; path "../../interface/name";
} }
} }
leaf address { leaf address {
type keyref { type keyref {
path "../../interface[name = $this/../ifname]/address/ip"; path "../../interface[name = current()/../ifname]"
+ "/address/ip";
} }
} }
} }
A corresponding XML snippet is e.g.: A corresponding XML snippet is e.g.:
<interface> <interface>
<name>eth0</name> <name>eth0</name>
<address> <address>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
</address> </address>
<address> <address>
<ip>192.0.2.2</ip> <ip>192.0.2.2</ip>
</address> </address>
skipping to change at page 101, line 24 skipping to change at page 105, line 6
The syntax for an instance-identifier is a subset of the XPath The syntax for an instance-identifier is a subset of the XPath
syntax, which is used to uniquely identify a node in the data tree. syntax, which is used to uniquely identify a node in the data tree.
It is an absolute XPath location path in abbreviated syntax, where It is an absolute XPath location path in abbreviated syntax, where
axes are not permitted, and predicates are used only for specifying axes are not permitted, and predicates are used only for specifying
the values for the key nodes for list entries, or a value of a leaf- the values for the key nodes for list entries, or a value of a leaf-
list. Each predicate consists of one equality test per key. Each list. Each predicate consists of one equality test per key. Each
key MUST have a corresponding predicate. key MUST have a corresponding predicate.
The syntax is formally defined by the rule "absolute-instid" in The syntax is formally defined by the rule "absolute-instid" in
Appendix D. Section 11.
8.11.1. Restrictions 8.11.1. Restrictions
An instance-identifier cannot be restricted. An instance-identifier cannot be restricted.
8.11.2. Lexicographic Representation 8.11.2. Lexicographic Representation
An instance-identifier value is lexicographically represented as a An instance-identifier value is lexicographically represented as a
string in the XML encoding. The namespace prefixes used in the string in the XML encoding. The namespace prefixes used in the
encoding MUST be declared in the XML namespace scope in the instance- encoding MUST be declared in the XML namespace scope in the instance-
skipping to change at page 102, line 4 skipping to change at page 105, line 34
The following are examples of instance identifiers: The following are examples of instance identifiers:
/ex:system/ex:services/ex:ssh/ex:port /ex:system/ex:services/ex:ssh/ex:port
/ex:system/ex:user[ex:name='fred'] /ex:system/ex:user[ex:name='fred']
/ex:system/ex:user[ex:name='fred']/ex:type /ex:system/ex:user[ex:name='fred']/ex:type
/ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80']
/ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc']
9. Updating a Module 9. Updating a Module
[Editor's Note: add versioning rules, i.e. what can be done w/o [Editor's Note: add versioning rules, i.e. what can be done w/o
changing the module name and the namespace] changing the module name and the namespace]
10. IANA Considerations 10. YIN
A registry for standard YANG modules shall be set up. Each entry
shall contain the unique module name, the unique XML namespace from
the YANG URI Scheme and some reference to the module's documentation.
This document registers five URIs for the YANG XML namespace in the
IETF XML registry [RFC3688].
URI: urn:ietf:params:xml:ns:yang:ieee-types
URI: urn:ietf:params:xml:ns:yang:inet-types
URI: urn:ietf:params:xml:ns:yang:yang-types
URI: urn:ietf:params:xml:ns:yang:yin:1
URI: urn:ietf:params:xml:ns:yang:1
11. 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.
Data modeled in YANG might contain sensitive information. RPCs or
notifications defined in YANG might transfer sensitive information.
Security issues are related to the usage of data modeled in YANG.
Such issues shall be dealt with in documents describing the data
models and documents about the interfaces used to manipulate the data
e.g. the NETCONF documents.
YANG is dependent upon:
o the security of the transmission infrastructure used to send
sensitive information
o the security of applications which store or release such sensitive
information.
o adequate authentication access control mechanisms to restrict the
usage of sensitive data.
12. Contributors
The following people all contributed significantly to the initial
YANG draft:
- Andy Bierman (andybierman.com)
- Balazs Lengyel (Ericsson)
- David Partain (Ericsson)
- Juergen Schoenwaelder (Jacobs University Bremen)
- Phil Shafer (Juniper Networks)
13. References
13.1. Normative References
[IEEE.754]
Institute of Electrical and Electronics Engineers,
"Standard for Binary Floating-Point Arithmetic",
IEEE Standard 754, August 1985.
[ISO.10646]
International Organization for Standardization,
"Information Technology - Universal Multiple-octet coded
Character Set (UCS) - Part 1: Architecture and Basic
Multilingual Plane", ISO Standard 10646-1, May 1993.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[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.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[XSD] Maloney, M., Beech, D., Thompson, H., and N. Mendelsohn,
"XML Schema Part 1: Structures Second Edition", W3C
REC REC-xmlschema-1-20041021, October 2004.
[XSD-TYPES]
Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", W3C REC REC-xmlschema-2-20041028,
October 2004.
13.2. Non-Normative References
[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
Structure of Management Information", RFC 3780, May 2004.
Appendix A. Derived YANG Types
Most YANG modules are built on top of the definitions of some
commonly used derived types. The definitions of these derived types
are contained in the "yang-types", "inet-types", and "ieee-types"
modules which are defined below. Their derived types are generally
applicable for modeling all areas of management information.
A.1. Core YANG Derived Types
module yang-types {
// XXX namespace to be allocated by IANA
namespace "urn:ietf:params:xml:ns:yang:yang-types";
prefix "yang";
organization
"YANG Language Design Team";
contact
"Martin Bjorklund (Editor) <mbj@tail-f.com>";
description
"This module contains standard derived YANG types.";
revision 2007-10-02 {
description "Initial revision.";
}
/*
* collection of counter and gauge types
*/
typedef counter32 {
type uint32;
description
"The counter32 type represents a non-negative integer
which monotonically increases until it reaches a
maximum value of 2^32-1 (4294967295 decimal), when it
wraps around and starts increasing again from zero.
Counters have no defined `initial' value, and thus, a
single value of a counter has (in general) no information
content. Discontinuities in the monotonically increasing
value normally occur at re-initialization of the
management system, and at other times as specified in the
description of an object instance using this type. If
such other times can occur, for example, the creation of
an object instance of type counter32 at times other than
re-initialization, then a corresponding object should be
defined, with an appropriate type, to indicate the last
discontinuity.
The counter32 type should not be used for configuration
objects. A default statement should not be used for
attributes with a type value of counter32.";
reference
"RFC 2578 (STD 58)";
}
typedef zero-based-counter32 {
type yang:counter32;
default "0";
description
"The zero-based-counter32 type represents a counter32
which has the defined `initial' value zero.";
reference
"RFC 2021";
}
typedef counter64 {
type uint64;
description
"The counter64 type represents a non-negative integer
which monotonically increases until it reaches a
maximum value of 2^64-1 (18446744073709551615), when
it wraps around and starts increasing again from zero.
Counters have no defined `initial' value, and thus, a
single value of a counter has (in general) no information
content. Discontinuities in the monotonically increasing
value normally occur at re-initialization of the
management system, and at other times as specified in the
description of an object instance using this type. If
such other times can occur, for example, the creation of
an object instance of type counter64 at times other than
re-initialization, then a corresponding object should be
defined, with an appropriate type, to indicate the last
discontinuity.
The counter64 type should not be used for configuration
objects. A default statement should not be used for
attributes with a type value of counter64.";
reference
"RFC 2578 (STD 58)";
}
typedef zero-based-counter64 {
type yang:counter64;
default "0";
description
"The zero-based-counter64 type represents a counter64
which has the defined `initial' value zero.";
reference
"RFC 2856";
}
typedef gauge32 {
type uint32;
description
"The gauge32 type represents a non-negative integer,
which may increase or decrease, but shall never
exceed a maximum value, nor fall below a minimum
value. The maximum value can not be greater than
2^32-1 (4294967295 decimal), and the minimum value
can not be smaller than 0. The value of a gauge32
has its maximum value whenever the information
being modeled is greater than or equal to its
maximum value, and has its minimum value whenever
the information being modeled is smaller than or
equal to its minimum value. If the information
being modeled subsequently decreases below
(increases above) the maximum (minimum) value, the
gauge32 also decreases (increases).";
reference
"RFC 2578 (STD 58)";
}
typedef gauge64 {
type uint64;
description
"The gauge64 type represents a non-negative integer,
which may increase or decrease, but shall never
exceed a maximum value, nor fall below a minimum
value. The maximum value can not be greater than
2^64-1 (18446744073709551615), and the minimum value
can not be smaller than 0. The value of a gauge64
has its maximum value whenever the information
being modeled is greater than or equal to its
maximum value, and has its minimum value whenever
the information being modeled is smaller than or
equal to its minimum value. If the information
being modeled subsequently decreases below
(increases above) the maximum (minimum) value, the
gauge64 also decreases (increases).";
reference
"RFC 2856";
}
/*
* collection of identifier related types
*/
typedef uri {
type string;
description
"A uri type represents Uniform Resource Identifier (URI)
as defined by STD 66.
Objects using this type MUST be in US-ASCII encoding, and
MUST be normalized as described by RFC 3986 Sections
6.2.1, 6.2.2.1, and 6.2.2.2. All unnecessary
percent-encoding is removed, and all case-insensitive
characters are set to lowercase except for hexadecimal
digits, which are normalized to uppercase as described in
Section 6.2.2.1.
The purpose of this normalization is to help provide unique
URIs. Note that this normalization is not sufficient to
provide uniqueness. Two URIs that are textually distinct
after this normalization may still be equivalent.
Objects using this type MAY restrict the schemes that they
permit. For example, 'data:' and 'urn:' schemes might not
be appropriate.
A zero-length URI is not a valid URI. This can be used to
express 'URI absent' where required, for example when used
as an index field.";
reference
"RFC 3986 (STD 66), RFC 3305, and RFC 5017";
}
typedef object-identifier {
type string {
pattern '[0-2](\.\d+)+';
}
description
"The object-identifier type represents administratively
assigned names in a registration-hierarchical-name tree.
Values of this type are denoted as a sequence of numerical
non-negative sub-identifier values. Each sub-identifier
value MUST NOT exceed 2^32-1 (4294967295). Sub-identifiers
are separated by single dots and without any intermediate
white space.
Although the number of sub-identifiers is not limited,
module designers should realize that there may be
implementations that stick with the SMIv1/v2 limit of 128
sub-identifiers.";
reference
"ITU-T Recommendation X.660 / ISO/IEC 9834-1";
}
/*
* collection of date and time related types
*/
typedef date-and-time {
type string {
pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.d*)?'
+ '(Z|(\+|-)\d{2}:\d{2})';
}
description
'The date-and-time type is a profile of the ISO 8601
standard for representation of dates and times using the
Gregorian calendar. The format is most easily described
using the following ABFN (see RFC 3339):
date-fullyear = 4DIGIT
date-month = 2DIGIT ; 01-12
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31
time-hour = 2DIGIT ; 00-23
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-58, 00-59, 00-60
time-secfrac = "." 1*DIGIT
time-numoffset = ("+" / "-") time-hour ":" time-minute
time-offset = "Z" / time-numoffset
partial-time = time-hour ":" time-minute ":" time-second
[time-secfrac]
full-date = date-fullyear "-" date-month "-" date-mday
full-time = partial-time time-offset
date-time = full-date "T" full-time';
reference "RFC 3339";
}
typedef timeticks {
type uint32;
description
"The timeticks type represents a non-negative integer
which represents the time, modulo 2^32 (4294967296
decimal), in hundredths of a second between two epochs.
When objects are defined which use this type, the
description of the object identifies both of the reference
epochs.";
reference
"RFC 2578 (STD 58)";
}
typedef timestamp {
type yang:timeticks;
description
"The timestamp type represents the value of an associated
timeticks object at which a specific occurrence
happened. The specific occurrence must be defined in the
description of any object defined using this type. When
the specific occurrence occurred prior to the last time
the associated timeticks attribute was zero, then the
timestamp value is zero. Note that this requires all
timestamp values to be reset to zero when the value of
the associated timeticks attribute reaches 497+ days and
wraps around to zero.
The associated timeticks object must be specified
in the description of any object using this type.";
reference
"RFC 2579 (STD 58)";
}
/*
* collection of generic address types
*/
typedef phys-address {
type string;
description
"Represents media- or physical-level addresses.";
reference
"RFC 2579 (STD 58)";
}
}
A.2. Internet Specific Derived Types
module inet-types {
// XXX namespace to be allocated by IANA
namespace "urn:ietf:params:xml:ns:yang:inet-types";
prefix "inet";
organization
"YANG Language Design Team";
contact
"Martin Bjorklund (Editor) <mbj@tail-f.com>";
description
"This module contains standard derived YANG types
for Internet addresses and related things.";
revision 2007-10-02 {
description "Initial revision.";
}
/*
* collection of protocol field related types
*/
typedef ip-version {
type enumeration {
enum unknown {
value 0;
description
"An unknown or unspecified version of the
Internet protocol.";
}
enum ipv4 {
value 1;
description
"The IPv4 protocol as defined in RFC 791.";
}
enum ipv6 {
value 2;
description
"The IPv6 protocol as defined in RFC 2460.";
}
}
description
"This value represents the version of the IP protocol.";
reference
"RFC 791 (STD 5), RFC 2460";
}
typedef dscp {
type uint8 {
range "0..63";
}
description
"The dscp type represents a Differentiated Services
Code-Point that may be used for marking a traffic
stream.";
reference
"RFC 3289, RFC 2474, RFC 2780";
}
typedef flow-label {
type uint32 {
range "0..1048575";
}
description
"The flow-label type represents flow identifier or
Flow Label in an IPv6 packet header that may be
used to discriminate traffic flows.";
reference
"RFC 2460";
}
typedef port-number {
type uint16 {
range "1..65535";
}
description
"The port-number type represents a 16-bit port
number of an Internet transport layer protocol
such as UDP, TCP, DCCP or SCTP. Port numbers are
assigned by IANA. A current list of all
assignments is available from
<http://www.iana.org/>.
Note that the value zero is not a valid port
number. A union type might be used in situations
where the value zero is meaningful.";
reference
"RFC 4001";
}
/*
* collection of autonomous system related types
*/
typedef asn {
type uint32;
description
"The asn type represents autonomous system numbers which
identify an Autonomous System (AS). An AS is a set of
routers under a single technical administration, using an
interior gateway protocol and common metrics to route
packets within the AS, and using an exterior gateway
protocol to route packets to other ASs'. IANA maintains
the AS number space and has delegated large parts to the
regional registries.
Autonomous system numbers are currently limited to 16 bits
(0..65535). There is however work in progress to enlarge
the autonomous system number space to 32 bits. This
textual convention therefore uses an uint32 base type
without a range restriction in order to support a larger
autonomous system number space.";
reference
"RFC 1771, RFC 1930, RFC 4001";
}
/*
* collection of IP address and hostname related types
*/
typedef ip-address {
type union {
type inet:ipv4-address;
type inet:ipv6-address;
}
description
"The ip-address type represents an IP address and
is IP version neutral. The format of the textual
representations implies the IP version.";
}
typedef ipv4-address {
type string {
pattern
'(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}'
+ '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])'
+ '(%[\p{N}\p{L}]+)?';
}
description
"The ipv4-address type represents an IPv4 address in
dotted-quad notation. The IPv4 address may include
a zone index, separated by a % sign.";
}
typedef ipv6-address {
type string {
pattern
/* full */
'((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})'
+ '(%[\p{N}\p{L}]+)?)'
/* mixed */
+ '|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\.'
+ '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))'
+ '(%[\p{N}\p{L}]+)?)'
/* shortened */
+ '|((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)'
+ '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*'
+ '(%[\p{N}\p{L}]+)?)'
/* shortened mixed */
+ '((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)'
+ '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*'
+ '(([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))'
+ '(%[\p{N}\p{L}]+)?)';
}
description
"The ipv6-address type represents an IPv6 address in
full, mixed, shortened and shortened mixed notation.
The IPv6 address may include a zone index, separated
by a % sign.";
}
typedef ip-prefix {
type union {
type inet:ipv4-prefix;
type inet:ipv6-prefix;
}
description
"The ip-prefix type represents an IP prefix and
is IP version neutral. The format of the textual
representations implies the IP version.";
}
typedef ipv4-prefix {
type string {
pattern
'(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}'
+ '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])'
+ '/\p{N}+';
}
description
"The ipv4-prefix type represents an IPv4 address prefix.
The prefix length is given by the number following the
slash character and must be less than or equal 32.
Values larger than 32 should be treated as 32.
A prefix length value of n corresponds to an IP address
mask which has n contiguous 1-bits from the most
significant bit (MSB) and all other bits set to 0.
The IPv4 address represented in dotted quad notation
should have all bits that do not belong to the prefix
set to zero.";
}
typedef ipv6-prefix {
type string {
pattern
/* full */
'((([0-9a-fA-F]{1,4}:){7})([0-9a-fA-F]{1,4})'
+ '/\p{N}+)'
/* mixed */
+ '|((([0-9a-fA-F]{1,4}:){6})(([0-9]{1,3}\.'
+ '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))'
+ '/\p{N}+)'
/* shortened */
+ '|((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)'
+ '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*'
+ '/\p{N}+)'
/* shortened mixed */
+ '((([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*(::)'
+ '(([0-9a-fA-F]{1,4}:)*([0-9a-fA-F]{1,4}))*'
+ '(([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}))'
+ '/\p{N}+)';
}
description
"The ipv6-prefix type represents an IPv6 address prefix.
The prefix length is given by the number following the
slash character and must be less than or equal 128.
Values larger than 128 should be treated as 128.
A prefix length value of n corresponds to an IP address
mask which has n contiguous 1-bits from the most
significant bit (MSB) and all other bits set to 0.
The IPv6 address represented in dotted quad notation
should have all bits that do not belong to the prefix
set to zero.";
}
typedef domain-name {
type string {
pattern '([\p{L}\p{N}]+\.)*[\p{L}\p{N}]';
}
description
"The domain-name type represents a DNS domain
name. The name SHOULD be fully qualified
whenever possible.
The description clause of objects using the
domain-name type MUST describe how (and when)
these names are resolved to IP addresses.
Note that the resolution of a domain-name value
may require to query multiple DNS records (e.g.,
A for IPv4 and AAAA for IPv6). The order of the
resolution process and which DNS record takes
precedence depends on the configuration of the
resolver.";
reference
"RFC 1034";
}
typedef host {
type union {
type inet:ip-address;
type inet:domain-name;
}
description
"The host type represents either an IP address
or a DNS domain name.";
}
}
A.3. IEEE 802 Specific Derived Types
module ieee-types {
// XXX namespace to be allocated by IANA
namespace "urn:ietf:params:xml:ns:yang:ieee-types";
prefix "ieee";
import yang-types {
prefix yang;
}
organization
"YANG Language Design Team";
contact
"Martin Bjorklund (Editor) <mbj@tail-f.com>";
description
"This module contains standard derived YANG types
for IEEE 802 addresses and related things.";
revision 2007-10-02 {
description "Initial revision.";
}
/*
* collection of IEEE address type definitions
*/
typedef mac-address {
type yang:phys-address {
pattern '([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}';
}
description
"The mac-address type represents an 802 MAC address
represented in the `canonical' order defined by
IEEE 802.1a, i.e., as if it were transmitted least
significant bit first, even though 802.5 (in contrast
to other 802.x protocols) requires MAC addresses to
be transmitted most significant bit first.";
reference
"RFC 2579 STD 58";
}
/*
* collection of IEEE 802 related identifier types
*/
typedef bridgeid {
type string {
pattern '[0-9a-fA-F]{4}:'
+ '([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}';
}
description
"The bridgeid type represents identifers that uniquely
identify a bridge. Its first four hexadecimal digits
contain a priority value followed by a colon. The
remaining characters contain the MAC address used to
refer to a bridge in a unique fashion (typically, the
numerically smallest MAC address of all ports on the
bridge).";
reference
"RFC 4188";
}
typedef vlanid {
type uint16 {
range "1..4094";
}
description
"The vlanid type uniquely identifies a VLAN. This is
the 12-bit VLAN-ID used in the VLAN Tag header. The
range is defined by the referenced specification.";
reference
"IEEE Std 802.1Q 2003 Edition, Virtual Bridged Local
Area Networks.";
}
}
Appendix B. YIN
A YANG module can be specified in an alternative XML-based syntax A YANG module can be specified in an alternative XML-based syntax
called YIN. This appendix describes symmetric mapping rules between called YIN. This appendix describes symmetric mapping rules between
the two formats. the two formats.
The YANG and YIN formats contain equivalent information using The YANG and YIN formats contain equivalent information using
different notations. The purpose of the YIN notation is to allow the different notations. The purpose of the YIN notation is to allow the
user to translate YANG into YIN, use the rich set of XML based tools user to translate YANG into YIN, use the rich set of XML based tools
on the YIN format to transform, or filter the model information. on the YIN format to transform, or filter the model information.
Tools like XSLT or XML validators can be utilized. After this the Tools like XSLT or XML validators can be utilized. After this the
model can be transformed back to the YANG format if needed, which model can be transformed back to the YANG format if needed, which
provides a more concise and readable format. provides a more concise and readable format.
The YANG-2-YIN and the YIN-2-YANG transformations will not modify the The YANG-2-YIN and the YIN-2-YANG transformations will not modify the
information content of the model. information content of the model.
B.1. Formal YIN Definition 10.1. Formal YIN Definition
YIN is described by an algorithm that transforms YANG to YIN. YIN is described by an algorithm that transforms YANG to YIN.
B.2. Transformation Algorithm YANG-2-YIN 10.2. Transformation Algorithm YANG-2-YIN
Every keyword results in a new XML element. The name of the element Every keyword results in a new XML element. The name of the element
is the keyword. All core YANG elements are defined in the namespace is the keyword. All core YANG elements are defined in the namespace
"urn:ietf:params:xml:ns:yang:yin:1". [XXX IANA] "urn:ietf:params:xml:ns:yang:yin:1". [XXX IANA]
The top-level element is always <module> or <submodule>. The top-level element is always <module> or <submodule>.
Elements which represent keywords that are imported extensions from Elements which represent keywords that are imported extensions from
other modules MUST be properly namespace qualified, where the other modules MUST be properly namespace qualified, where the
namespace is the namespace of the imported module. Translators namespace is the namespace of the imported module. Translators
skipping to change at page 125, line 23 skipping to change at page 109, line 23
| yin-element | value | false | | yin-element | value | false |
+---------------+---------------+-------------+ +---------------+---------------+-------------+
Table 30 Table 30
If a statement is followed by substatements, those substatements are If a statement is followed by substatements, those substatements are
subelements in the YIN mapping. subelements in the YIN mapping.
Comments in YANG MAY be transformed into XML comments. Comments in YANG MAY be transformed into XML comments.
B.2.1. Usage Example 10.2.1. Usage Example
The following YANG snippet: The following YANG snippet:
leaf mtu { leaf mtu {
type uint32; type uint32;
description "The MTU of the interface."; description "The MTU of the interface.";
} }
is translated into the following YIN snippet: is translated into the following YIN snippet:
<leaf name="mtu"> <leaf name="mtu">
<type name="uint32"/> <type name="uint32"/>
<description> <description>
<text>The MTU of the interface."</text> <text>The MTU of the interface."</text>
</description> </description>
</leaf> </leaf>
B.3. Transformation Algorithm YIN-2-YANG 10.3. Transformation Algorithm YIN-2-YANG
The transformation is based on a recursive algorithm that is started The transformation is based on a recursive algorithm that is started
on the <module> or <submodule> element. on the <module> or <submodule> element.
The element is transformed into a YANG keyword. If the keyword in The element is transformed into a YANG keyword. If the keyword in
Table 30 is marked as yin-element true, the subelement with the Table 30 is marked as yin-element true, the subelement with the
keyword's argument name in Table 30 contains the YANG keyword's keyword's argument name in Table 30 contains the YANG keyword's
argument as text content. If the keyword in Table 30 is marked as argument as text content. If the keyword in Table 30 is marked as
yin-element false, the element's attribute with keyword's argument yin-element false, the element's attribute with keyword's argument
name in Table 30 contains the YANG keyword's argument. name in Table 30 contains the YANG keyword's argument.
If there are no other subelements to the element, the YANG statement If there are no other subelements to the element, the YANG statement
is closed with a ";". Otherwise, each such subelement is is closed with a ";". Otherwise, each such subelement is
transformed, according to the same algorithm, as substatements to the transformed, according to the same algorithm, as substatements to the
current YANG statement, enclosed within "{" and "}". current YANG statement, enclosed within "{" and "}".
XML comments in YIN MAY be transformed into YANG comments. XML comments in YIN MAY be transformed into YANG comments.
B.3.1. Tabulation, Formatting 10.3.1. Tabulation, Formatting
To get a readable YANG module the YANG output will have to be To get a readable YANG module the YANG output will have to be
indented with appropriate whitespace characters. indented with appropriate whitespace characters.
Appendix C. XML Schema Considerations 11. YANG ABNF Grammar
It is possible to generate an XSD document representing the data
model defined in YANG. The XSD will specify the structure of the
model, the used types, cardinality, etc. but a good part of the
information in YANG can not be represented in standard XSD constructs
e.g. config, status, default, keyref.
The above information will be added to XSD inside annotation
statements (which can not be handled by standard XML tools). The
exact form of annotations is for further study.
Data models defined in YANG might have multiple top-level elements.
To make it possible to validate the XML encoded data, both for the
generated XSD describing the data model and for the config and state
data received in NETCONF RPCs a single top level element <data> shall
be added.
From a YANG model, many different XSD schema can be generated
defining the same data model. The exact rules to generate XSD from
YANG are outside the scope of this document, however some general
considerations are needed.
Appendix D. YANG ABNF Grammar
In YANG, almost all statements are unordered. The ABNF grammar In YANG, almost all statements are unordered. The ABNF grammar
[RFC5234] defines the canonical order. To improve module [RFC5234] defines the canonical order. To improve module
readability, it is RECOMMENDED that clauses be entered in this order. readability, it is RECOMMENDED that clauses be entered in this order.
Within the ABNF grammar, unordered statements are marked with Within the ABNF grammar, unordered statements are marked with
comments. comments.
This grammar assumes that the scanner replaces YANG comments with a This grammar assumes that the scanner replaces YANG comments with a
single space character. single space character.
module-stmt = module-keyword sep identifier-str optsep module-stmt = optsep module-keyword sep identifier-arg-str
optsep
"{" stmtsep "{" stmtsep
module-header-stmts module-header-stmts
linkage-stmts linkage-stmts
meta-stmts meta-stmts
revision-stmts revision-stmts
body-stmts body-stmts
"}" optsep "}" optsep
submodule-stmt = submodule-keyword sep identifier-str optsep submodule-stmt = optsep submodule-keyword sep identifier-arg-str
optsep
"{" stmtsep "{" stmtsep
submodule-header-stmts submodule-header-stmts
linkage-stmts linkage-stmts
meta-stmts meta-stmts
revision-stmts revision-stmts
body-stmts body-stmts
"}" optsep "}" optsep
module-header-stmts = ;; these stmts can appear in any order module-header-stmts = ;; these stmts can appear in any order
[yang-version-stmt stmtsep] [yang-version-stmt stmtsep]
skipping to change at page 129, line 32 skipping to change at page 112, line 33
augment-stmt augment-stmt
case-data-def-stmt = container-stmt / case-data-def-stmt = container-stmt /
leaf-stmt / leaf-stmt /
leaf-list-stmt / leaf-list-stmt /
list-stmt / list-stmt /
anyxml-stmt / anyxml-stmt /
uses-stmt / uses-stmt /
augment-stmt augment-stmt
yang-version-stmt = yang-version-keyword sep "1" optsep stmtend yang-version-stmt = yang-version-keyword sep yang-version-arg-str
optsep stmtend
import-stmt = import-keyword sep identifier-str optsep yang-version-arg-str = < a string which matches the rule
yang-version-arg >
yang-version-arg = "1"
import-stmt = import-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
prefix-stmt stmtsep prefix-stmt stmtsep
"}" "}"
include-stmt = include-keyword sep identifier-str optsep include-stmt = include-keyword sep identifier-arg-str optsep
stmtend stmtend
namespace-stmt = namespace-keyword sep uri-str optsep stmtend namespace-stmt = namespace-keyword sep uri-str optsep stmtend
uri-str = < a string which matches the rule uri-str = < a string which matches the rule
URI in RFC 3986 > URI in RFC 3986 >
prefix-stmt = prefix-keyword sep prefix-str optsep stmtend prefix-stmt = prefix-keyword sep prefix-arg-str
optsep stmtend
belongs-to-stmt = belongs-to-keyword sep identifier-str belongs-to-stmt = belongs-to-keyword sep identifier-arg-str
optsep stmtend optsep stmtend
organization-stmt = organization-keyword sep string organization-stmt = organization-keyword sep string
optsep stmtend optsep stmtend
contact-stmt = contact-keyword sep string optsep stmtend contact-stmt = contact-keyword sep string optsep stmtend
description-stmt = description-keyword sep string optsep description-stmt = description-keyword sep string optsep
stmtend stmtend
reference-stmt = reference-keyword sep string optsep stmtend reference-stmt = reference-keyword sep string optsep stmtend
units-stmt = units-keyword sep string optsep stmtend units-stmt = units-keyword sep string optsep stmtend
revision-stmt = revision-keyword sep date-expr-str optsep revision-stmt = revision-keyword sep date-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
[description-stmt stmtsep] [description-stmt stmtsep]
"}") "}")
extension-stmt = extension-keyword sep identifier-str optsep extension-stmt = extension-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[argument-stmt stmtsep] [argument-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
argument-stmt = argument-keyword sep identifier-str optsep argument-stmt = argument-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
[yin-element-stmt stmtsep] [yin-element-stmt stmtsep]
"}") "}")
yin-element-stmt = yin-element-keyword sep yin-element-arg-str yin-element-stmt = yin-element-keyword sep yin-element-arg-str
stmtend stmtend
yin-element-arg-str = < a string which matches the rule yin-element-arg-str = < a string which matches the rule
yin-element-arg > yin-element-arg >
yin-element-arg = true-keyword / false-keyword yin-element-arg = true-keyword / false-keyword
typedef-stmt = typedef-keyword sep identifier-str optsep typedef-stmt = typedef-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
type-stmt stmtsep type-stmt stmtsep
[units-stmt stmtsep] [units-stmt stmtsep]
[default-stmt stmtsep] [default-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}" "}"
type-stmt = type-keyword sep identifier-ref-str optsep type-stmt = type-keyword sep identifier-ref-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
( numerical-restrictions / ( numerical-restrictions /
string-restrictions / string-restrictions /
enum-specification / enum-specification /
keyref-specification / keyref-specification /
bits-specification / bits-specification /
union-specification ) union-specification )
stmtsep stmtsep
"}") "}")
numerical-restrictions = range-stmt stmtsep numerical-restrictions = range-stmt stmtsep
range-stmt = range-keyword sep range-expr-str optsep range-stmt = range-keyword sep range-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
string-restrictions = ;; these stmts can appear in any order string-restrictions = ;; these stmts can appear in any order
[length-stmt stmtsep] [length-stmt stmtsep]
[pattern-stmt stmtsep] *(pattern-stmt stmtsep)
length-stmt = length-keyword sep length-expr-str optsep length-stmt = length-keyword sep length-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
pattern-stmt = pattern-keyword sep string optsep pattern-stmt = pattern-keyword sep string optsep
skipping to change at page 132, line 13 skipping to change at page 115, line 21
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
default-stmt = default-keyword sep string stmtend default-stmt = default-keyword sep string stmtend
enum-specification = 1*(enum-stmt stmtsep) enum-specification = 1*(enum-stmt stmtsep)
enum-stmt = enum-keyword sep identifier-str optsep enum-stmt = enum-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[value-stmt stmtsep] [value-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
keyref-specification = path-stmt stmtsep keyref-specification = path-stmt stmtsep
path-stmt = path-keyword sep path-arg-str stmtend path-stmt = path-keyword sep path-arg-str stmtend
union-specification = 1*(type-stmt stmtsep) union-specification = 1*(type-stmt stmtsep)
bits-specification = 1*(bit-stmt stmtsep) bits-specification = 1*(bit-stmt stmtsep)
bit-stmt = bit-keyword sep identifier-str optsep bit-stmt = bit-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[position-stmt stmtsep] [position-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}" "}"
"}") "}")
position-stmt = position-keyword sep position-value-str stmtend position-stmt = position-keyword sep
position-value-arg-str stmtend
position-value-str = < a string which matches the rule position-value-arg-str = < a string which matches the rule
position-value > position-value-arg >
position-value = non-negative-decimal-value position-value-arg = non-negative-decimal-value
status-stmt = status-keyword sep status-arg-str stmtend status-stmt = status-keyword sep status-arg-str stmtend
status-arg-str = < a string which matches the rule status-arg-str = < a string which matches the rule
status-arg > status-arg >
status-arg = current-keyword / status-arg = current-keyword /
obsolete-keyword / obsolete-keyword /
deprecated-keyword deprecated-keyword
skipping to change at page 133, line 34 skipping to change at page 116, line 43
mandatory-arg = true-keyword / false-keyword mandatory-arg = true-keyword / false-keyword
presence-stmt = presence-keyword sep string stmtend presence-stmt = presence-keyword sep string stmtend
ordered-by-stmt = ordered-by-keyword sep ordered-by-stmt = ordered-by-keyword sep
ordered-by-arg-str stmtend ordered-by-arg-str stmtend
ordered-by-arg-str = < a string which matches the rule ordered-by-arg-str = < a string which matches the rule
ordered-by-arg > ordered-by-arg >
ordered-by-arg = user-keyword / ordered-by-arg = user-keyword / system-keyword
system-keyword
must-stmt = must-keyword sep string optsep must-stmt = must-keyword sep string optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
error-message-stmt = error-message-keyword sep string stmtend error-message-stmt = error-message-keyword sep string stmtend
error-app-tag-stmt = error-app-tag-keyword sep string stmtend error-app-tag-stmt = error-app-tag-keyword sep string stmtend
min-elements-stmt = min-elements-keyword sep min-elements-stmt = min-elements-keyword sep
min-value-str stmtend; min-value-arg-str stmtend;
min-value-str = < a string which matches the rule min-value-arg-str = < a string which matches the rule
min-value > min-value-arg >
min-value = non-negative-decimal-value min-value-arg = non-negative-decimal-value
max-elements-stmt = max-elements-keyword sep max-elements-stmt = max-elements-keyword sep
max-value-str stmtend; max-value-arg-str stmtend;
max-value-str = < a string which matches the rule max-value-arg-str = < a string which matches the rule
max-value > max-value-arg >
max-value = unbounded-keyword / positive-decimal-value max-value-arg = unbounded-keyword /
positive-decimal-value
value-stmt = value-keyword sep decimal-value stmtend value-stmt = value-keyword sep decimal-value stmtend
grouping-stmt = grouping-keyword sep identifier-str optsep grouping-stmt = grouping-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
*(data-def-stmt stmtsep) *(data-def-stmt stmtsep)
"}") "}")
container-stmt = container-keyword sep identifier-str optsep container-stmt = container-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[presence-stmt stmtsep] [presence-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
*(data-def-stmt stmtsep) *(data-def-stmt stmtsep)
"}") "}")
leaf-stmt = leaf-keyword sep identifier-str optsep leaf-stmt = leaf-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
type-stmt stmtsep type-stmt stmtsep
[units-stmt stmtsep] [units-stmt stmtsep]
*(must-stmt stmtsep) *(must-stmt stmtsep)
[default-stmt stmtsep] [default-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}" "}"
leaf-list-stmt = leaf-list-keyword sep identifier-str optsep leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
type-stmt stmtsep type-stmt stmtsep
[units-stmt stmtsep] [units-stmt stmtsep]
*(must-stmt stmtsep) *(must-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
[ordered-by-stmt stmtsep] [ordered-by-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}" "}"
list-stmt = list-keyword sep identifier-str optsep list-stmt = list-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[key-stmt stmtsep] [key-stmt stmtsep]
*(unique-stmt stmtsep) *(unique-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
[ordered-by-stmt stmtsep] [ordered-by-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
skipping to change at page 136, line 5 skipping to change at page 119, line 12
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep) 1*(data-def-stmt stmtsep)
"}" "}"
key-stmt = key-keyword sep key-arg-str stmtend key-stmt = key-keyword sep key-arg-str stmtend
key-arg-str = < a string which matches the rule key-arg-str = < a string which matches the rule
key-arg > key-arg >
key-arg = 1*(identifier sep) key-arg = identifier *(sep identifier)
unique-stmt = unique-keyword sep unique-arg-str stmtend unique-stmt = unique-keyword sep unique-arg-str stmtend
unique-arg-str = < a string which matches the rule unique-arg-str = < a string which matches the rule
unique-arg > unique-arg >
unique-arg = 1*(descendant-schema-nodeid 1*sp) unique-arg = descendant-schema-nodeid
*(sep descendant-schema-nodeid)
choice-stmt = choice-keyword sep identifier-str optsep choice-stmt = choice-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[default-stmt stmtsep] [default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((short-case-stmt / case-stmt) stmtsep) *((short-case-stmt / case-stmt) stmtsep)
"}") "}")
short-case-stmt = container-stmt / short-case-stmt = container-stmt /
leaf-stmt / leaf-stmt /
leaf-list-stmt / leaf-list-stmt /
list-stmt / list-stmt /
anyxml-stmt anyxml-stmt
case-stmt = case-keyword sep identifier-str optsep case-stmt = case-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(case-data-def-stmt stmtsep) *(case-data-def-stmt stmtsep)
"}") "}")
anyxml-stmt = anyxml-keyword sep identifier-str optsep anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
uses-stmt = uses-keyword sep identifier-ref-str optsep uses-stmt = uses-keyword sep identifier-ref-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(refinement-stmt stmtsep) *(refinement-stmt stmtsep)
"}") "}")
refinement-stmt = refine-container-stmt / refinement-stmt = refine-container-stmt /
refine-leaf-stmt / refine-leaf-stmt /
refine-leaf-list-stmt / refine-leaf-list-stmt /
refine-list-stmt / refine-list-stmt /
refine-choice-stmt / refine-choice-stmt /
refine-anyxml-stmt refine-anyxml-stmt
refine-leaf-stmt = leaf-keyword sep identifier-str optsep refine-leaf-stmt = leaf-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[default-stmt stmtsep] [default-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
refine-leaf-list-stmt = leaf-list-keyword sep identifier-str optsep refine-leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
refine-list-stmt = list-keyword sep identifier-str optsep refine-list-stmt = list-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(refinement-stmt stmtsep) *(refinement-stmt stmtsep)
"}") "}")
refine-choice-stmt = choice-keyword sep identifier-str optsep refine-choice-stmt = choice-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[default-stmt stmtsep] [default-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(refine-case-stmt stmtsep) *(refine-case-stmt stmtsep)
"}") "}")
refine-case-stmt = case-keyword sep identifier-str optsep refine-case-stmt = case-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(refinement-stmt stmtsep) *(refinement-stmt stmtsep)
"}") "}")
refine-container-stmt = container-keyword sep identifier-str optsep refine-container-stmt = container-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[presence-stmt stmtsep] [presence-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(refinement-stmt stmtsep) *(refinement-stmt stmtsep)
"}") "}")
refine-anyxml-stmt = anyxml-keyword sep identifier-str optsep refine-anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
unknown-statement = prefix ":" identifier [sep string] optsep unknown-statement = prefix ":" identifier [sep string] optsep
(";" / "{" *unknown-statement "}") (";" / "{" *unknown-statement "}")
augment-stmt = augment-keyword sep augment-arg-str optsep augment-stmt = augment-keyword sep augment-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
(([input-stmt stmtsep]
[output-stmt stmtsep]) /
1*((data-def-stmt stmtsep) / 1*((data-def-stmt stmtsep) /
(case-stmt stmtsep))) (case-stmt stmtsep))
"}" "}"
augment-arg-str = < a string which matches the rule augment-arg-str = < a string which matches the rule
augment-arg > augment-arg >
augment-arg = absolute-schema-nodeid / augment-arg = absolute-schema-nodeid /
descendant-schema-nodeid descendant-schema-nodeid
when-stmt = when-keyword sep string stmtend when-stmt = when-keyword sep string stmtend
rpc-stmt = rpc-keyword sep identifier-str optsep rpc-stmt = rpc-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
[input-stmt stmtsep] [input-stmt stmtsep]
[output-stmt stmtsep] [output-stmt stmtsep]
skipping to change at page 140, line 9 skipping to change at page 123, line 17
"}" "}"
output-stmt = output-keyword optsep output-stmt = output-keyword optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep) 1*(data-def-stmt stmtsep)
"}" "}"
notification-stmt = notification-keyword sep identifier-str optsep notification-stmt = notification-keyword sep
identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
*(data-def-stmt stmtsep) *(data-def-stmt stmtsep)
"}") "}")
;; Ranges ;; Ranges
range-expr-str = < a string which matches the rule range-arg-str = < a string which matches the rule
range-expr > range-arg >
range-expr = optsep range-part range-arg = range-part *(optsep "|" optsep range-part)
*(optsep "|" optsep range-part)
optsep
range-part = range-boundary range-part = range-boundary
[optsep ".." optsep range-boundary] [optsep ".." optsep range-boundary]
range-boundary = neginf-keyword / posinf-keyword / range-boundary = neginf-keyword / posinf-keyword /
min-keyword / max-keyword / min-keyword / max-keyword /
decimal-value / float-value decimal-value / float-value
;; Lengths ;; Lengths
length-expr-str = < a string which matches the rule length-arg-str = < a string which matches the rule
length-expr > length-arg >
length-expr = optsep length-part *(optsep "|" length-arg = length-part *(optsep "|" optsep length-part)
optsep length-part) optsep
length-part = length-boundary length-part = length-boundary
[optsep ".." optsep length-boundary] [optsep ".." optsep length-boundary]
length-boundary = min-keyword / max-keyword / length-boundary = min-keyword / max-keyword /
non-negative-decimal-value non-negative-decimal-value
;; Date ;; Date
date-expr-str = < a string which matches the rule date-arg-str = < a string which matches the rule
date-expr > date-arg >
date-expr = 4DIGIT "-" 2DIGIT "-" 2DIGIT date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT
;; Schema Node Identifiers ;; Schema Node Identifiers
schema-nodeid = absolute-schema-nodeid / schema-nodeid = absolute-schema-nodeid /
relative-schema-nodeid relative-schema-nodeid
absolute-schema-nodeid absolute-schema-nodeid
= 1*("/" node-identifier) = 1*("/" node-identifier)
relative-schema-nodeid relative-schema-nodeid
skipping to change at page 141, line 35 skipping to change at page 124, line 41
absolute-schema-nodeid absolute-schema-nodeid
node-identifier = [prefix ":"] identifier node-identifier = [prefix ":"] identifier
;; Instance Identifiers ;; Instance Identifiers
instance-identifier-str instance-identifier-str
= < a string which matches the rule = < a string which matches the rule
instance-identifier > instance-identifier >
instance-identifier = absolute-instid / instance-identifier = absolute-instid / relative-instid
relative-instid
absolute-instid = 1*("/" (node-identifier *predicate)) absolute-instid = 1*("/" (node-identifier *predicate))
relative-instid = descendant-instid / relative-instid = descendant-instid /
(("." / "..") "/" (("." / "..") "/"
*relative-instid) *relative-instid)
descendant-instid = node-identifier *predicate descendant-instid = node-identifier *predicate
absolute-instid absolute-instid
skipping to change at page 142, line 10 skipping to change at page 125, line 16
predicate-expr = (node-identifier / ".") *WSP "=" *WSP predicate-expr = (node-identifier / ".") *WSP "=" *WSP
((DQUOTE string DQUOTE) / ((DQUOTE string DQUOTE) /
(SQUOTE string SQUOTE)) (SQUOTE string SQUOTE))
;; keyref path ;; keyref path
path-arg-str = < a string which matches the rule path-arg-str = < a string which matches the rule
path-arg > path-arg >
path-arg = absolute-path-arg / path-arg = absolute-path / relative-path
relative-path-arg
absolute-path-arg = 1*("/" (node-identifier *path-predicate)) absolute-path = 1*("/" (node-identifier *path-predicate))
relative-path-arg = descendant-path-arg / relative-path = descendant-path /
(".." "/" (".." "/"
*relative-path-arg) *relative-path)
descendant-path-arg = node-identifier *path-predicate descendant-path = node-identifier *path-predicate
absolute-path-arg absolute-path
path-predicate = "[" *WSP path-equality-expr *WSP "]" path-predicate = "[" *WSP path-equality-expr *WSP "]"
path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr
path-key-expr = this-variable-keyword "/" rel-path-keyexpr path-key-expr = this-variable-keyword "/" rel-path-keyexpr
rel-path-keyexpr = 1*(".." "/") *(node-identifier "/") rel-path-keyexpr = 1*(".." "/") *(node-identifier "/")
node-identifier node-identifier
skipping to change at page 144, line 15 skipping to change at page 127, line 20
system-keyword = 'system' system-keyword = 'system'
this-variable-keyword = '$this' this-variable-keyword = '$this'
true-keyword = 'true' true-keyword = 'true'
unbounded-keyword = 'unbounded' unbounded-keyword = 'unbounded'
user-keyword = 'user' user-keyword = 'user'
;; Basic Rules ;; Basic Rules
keyword = [prefix ":"] identifier keyword = [prefix ":"] identifier
prefix-str = < a string which matches the rule prefix-arg-str = < a string which matches the rule
prefix > prefix-arg >
prefix-arg = prefix
prefix = identifier prefix = identifier
identifier-str = < a string which matches the rule identifier-arg-str = < a string which matches the rule
identifier > identifier-arg >
identifier-arg = identifier
identifier = (ALPHA / "_") identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".") *(ALPHA / DIGIT / "_" / "-" / ".")
identifier-ref-str = < a string which matches the rule identifier-ref-arg-str = < a string which matches the rule
identifier-ref identifier-ref-arg >
identifier-ref = [prefix ":"] identifier identifier-ref-arg = [prefix ":"] identifier
string = < an unquoted string as returned by string = < an unquoted string as returned by
the scanner > the scanner >
decimal-value = ("-" non-negative-decimal-value) / decimal-value = ("-" non-negative-decimal-value) /
non-negative-decimal-value non-negative-decimal-value
non-negative-decimal-value = "0" / positive-decimal-value non-negative-decimal-value = "0" / positive-decimal-value
positive-decimal-value = (non-zero-digit *DIGIT) positive-decimal-value = (non-zero-digit *DIGIT)
skipping to change at page 146, line 5 skipping to change at page 130, line 5
SP = %x20 SP = %x20
; space ; space
VCHAR = %x21-7E VCHAR = %x21-7E
; visible (printing) characters ; visible (printing) characters
WSP = SP / HTAB WSP = SP / HTAB
; white space ; white space
Appendix E. Error Responses for YANG Related Errors 12. Error Responses for YANG Related Errors
A number of NETCONF error responses are defined for error cases A number of NETCONF error responses are defined for error cases
related to the data-model handling. If the relevant YANG statement related to the data-model handling. If the relevant YANG statement
has an "error-app-tag" substatement, that overrides the default value has an "error-app-tag" substatement, that overrides the default value
specified below. specified below.
E.1. Error Message for Data that Violates a YANG unique Statement: 12.1. Error Message for Data that Violates a YANG unique Statement:
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
unique constraint is invalidated, the following error is returned: unique constraint is invalidated, the following error is returned:
Tag: operation-failed Tag: operation-failed
Error-app-tag: data-not-unique Error-app-tag: data-not-unique
Error-info: <non-unique>: Contains an instance identifier which Error-info: <non-unique>: Contains an instance identifier which
points to a leaf which invalidates the unique points to a leaf which invalidates the unique
constraint. This element is present once for each constraint. This element is present once for each
leaf invalidating the unique constraint. leaf invalidating the unique constraint.
The <non-unique> element is in the YANG The <non-unique> element is in the YANG
namespace ("urn:ietf:params:xml:ns:yang:1" namespace ("urn:ietf:params:xml:ns:yang:1"
[XXX IANA]). [XXX IANA]).
E.2. Error Message for Data that Violates a YANG max-elements 12.2. Error Message for Data that Violates a YANG max-elements
Statement: Statement:
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
list or a leaf-list would have too many entries the following error list or a leaf-list would have too many entries the following error
is returned: is returned:
Tag: operation-failed Tag: operation-failed
Error-app-tag: too-many-elements Error-app-tag: too-many-elements
E.3. Error Message for Data that Violates a YANG min-elements This error is returned once, with the error-path identifying the list
node, even if there are more than one extra child present.
12.3. Error Message for Data that Violates a YANG min-elements
Statement: Statement:
If a NETCONF operation would result in configuration data where a 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 list or a leaf-list would have too few entries the following error is
returned: returned:
Tag: operation-failed Tag: operation-failed
Error-app-tag: too-few-elements Error-app-tag: too-few-elements
E.4. Error Message for Data that Violates a YANG must or when This error is returned once, with the error-path identifying the list
statement, a length, range or pattern restriction: node, even if there are more than one child missing.
12.4. Error Message for Data that Violates a YANG must statement:
If a NETCONF operation would result in configuration data where the If a NETCONF operation would result in configuration data where the
restrictions imposed by a "must", "when", "length", "range" or restrictions imposed by a "must" statement is violated the following
"pattern" statement is violated the following error is returned: error is returned, unless a specific "error-app-tag" substatement is
present for the "must" statement.
Tag: operation-failed Tag: operation-failed
Error-app-tag: data-restriction-violation Error-app-tag: must-violation
E.5. Error Message for the "insert" Operation 12.5. Error Message for the "insert" Operation
If the "insert" and "key" or "value" attributes are used in an <edit- If the "insert" and "key" or "value" attributes are used in an <edit-
config> for a list or leaf-list node, and the "key" or "value" refers config> for a list or leaf-list node, and the "key" or "value" refers
to a non-existing instance, the following error is returned: to a non-existing instance, the following error is returned:
Tag: bad-attribute Tag: bad-attribute
Error-app-tag: missing-instance Error-app-tag: missing-instance
Appendix F. Why We Need a New Modeling Language 13. IANA Considerations
There have been many discussions about whether the IETF should design This document registers two URIs for the YANG XML namespace in the
its own language or use an existing one. The YANG designers believe IETF XML registry [RFC3688].
strongly that existing languages are not the right answer.
YANG is based on languages used actively for development of NETCONF- URI: urn:ietf:params:xml:ns:yang:yin:1
based management systems. As such, the design of YANG is based
heavily on requirements placed upon those languages by their users
and the experience of writing NETCONF data models in vendor specific
languages.
During previous implementations that were input to YANG, developers URI: urn:ietf:params:xml:ns:yang:1
realized that they didn't want to read or write data models written
with XSD (or RelaxNG or RelaxNG compact), so the languages were based
on something "home grown" designed for the developers who would be
writing models and implementing them on devices.
F.1. Why not XSD? 14. Security Considerations
There are several reasons for not using XSD, such as: 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.
o XSD is too expressive, and gives too much freedom in allowable XML Data modeled in YANG might contain sensitive information. RPCs or
content. Without restrictions on its use and very clear notifications defined in YANG might transfer sensitive information.
guidelines, we think it will be very difficult to make
interoperable XSD models. For example, there are constructs such
as xs:redefine that would have to be disallowed.
o XSD is not expressive enough for NETCONF data modeling. Security issues are related to the usage of data modeled in YANG.
Additional semantics, such as state vs. config, integrity Such issues shall be dealt with in documents describing the data
constraints, error-messages, list order semantics, remote models and documents about the interfaces used to manipulate the data
procedure call and remote procedure call parameter definitions, e.g. the NETCONF documents.
and notification definitions would have to be put in appinfo
elements, essentially creating a new language contained in appinfo
elements.
o Operators and developers want models that are simple to read and YANG is dependent upon:
text-based. XSD is very difficult to read and debug. In the
NETCONF work, obvious bugs in the relatively simple protocol XSD
went undetected for years. The phrase many seem to use is that
XSD is "write-only".
o Defenders of XSD often counter claims of complexity with o the security of the transmission infrastructure used to send
availability of advanced tools, but the IETF cannot require such sensitive information
tools to read/write models. Rather, the IETF needs a simpler
language that is text-based, patch-friendly, and grep-able.
o From a process perspective, the IETF lacks any IETF change control o the security of applications which store or release such sensitive
and real input into the update process for XSD. information.
Does all of this mean that XSD has no place in the NETCONF management o adequate authentication and access control mechanisms to restrict
picture? Clearly, the answer is no. XSD is an excellent formal the usage of sensitive data.
description mechanism that applications can consume. XSD can be
generated from the models defined in YANG.
F.2. Why not RelaxNG 15. Contributors
RelaxNG is considered by many people a much simpler to understand and The following people all contributed significantly to the initial
to use schema notation for XML documents compared to XSD. However, YANG draft:
the reasons for not using RelaxNG are similar as for XSD:
o RelaxNG is like XSD too expressive and gives too much freedom in - Andy Bierman (andybierman.com)
allowable XML content (see above). - Balazs Lengyel (Ericsson)
- David Partain (Ericsson)
- Juergen Schoenwaelder (Jacobs University Bremen)
- Phil Shafer (Juniper Networks)
o RelaxNG is like XSD not expressive enough for NETCONF data 16. References
modeling (see above).
o While RelaxNG may be simpler to read (especially the compact 16.1. Normative References
notation), when fully annotated with all needed features, it will
likely become as difficult to read as XSD.
o The IETF has no change control over RelaxNG. [IEEE.754]
Institute of Electrical and Electronics Engineers,
"Standard for Binary Floating-Point Arithmetic",
IEEE Standard 754, August 1985.
Like in the XSD case, it will be possible to generate RelaxNG from [ISO.10646]
the models defined in YANG for the purpose to feed RelaxNG tools. International Organization for Standardization,
But this will only cover the information needed to validate instance "Information Technology - Universal Multiple-octet coded
documents and some NETCONF specific information will be lost or Character Set (UCS) - Part 1: Architecture and Basic
buried in extensions generic tools will not understand. Multilingual Plane", ISO Standard 10646-1, May 1993.
F.3. Why not SMIng [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
SMIng has been designed to be protocol independent so that SMIng data [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
models can be used with several management protocols. This is 10646", STD 63, RFC 3629, November 2003.
achieved by avoiding protocol details in the data model and by
providing protocol binding information in so called protocol
mappings. Unfortunately, protocol independence does not came for
free and introduces complexity:
o Protocol independence requires to work with an abstract naming [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
system for managed objects which complicates the construction of January 2004.
data models and their mappings.
o Error and exception handling can only be specified in abstract [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
term in protocol independent data models. Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
o Management protocols have different features to express [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
persistency of (changes to) management objects. Encodings", RFC 4648, October 2006.
o All the items listed above make it non-trivial to write and review [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
truly protocol independent data models. December 2006.
A NETCONF specific data modeling language like YANG makes it much [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
easier to describe data models in a way that maps to NETCONF in a Specifications: ABNF", STD 68, RFC 5234, January 2008.
very straight-forward manner and has therefore been chosen as the
best approach. Note that the design of YANG actually borrows heavily
from the SMIng work.
Appendix G. ChangeLog [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
Notifications", RFC 5277, July 2008.
G.1. Version -00 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[XSD-TYPES]
Biron, P V. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", W3C REC REC-xmlschema-2-20041028,
October 2004.
16.2. Non-Normative References
[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
Structure of Management Information", RFC 3780, May 2004.
Appendix A. ChangeLog
A.1. Version -01
o Removed "Appendix A. Derived YANG Types".
o Removed "Appendix C. XML Schema Considerations".
o Removed "Appendix F. Why We Need a New Modeling Language".
o Moved "Appendix B. YIN" to its own section.
o Moved "Appendix D. YANG ABNF Grammar" to its own section.
o Moved "Appendix E. Error Responses for YANG Related Errors" into
its own section.
o The "input" and "output" nodes are now implicitly created by the
"rpc" statement, in order for augmentation of these nodes to work
correctly.
o Allow "config" in "choice".
o Added reference to XPath 1.0.
o Using an XPath function "current()" instead of the variable
"$this".
o Clarified that a "must" expression in a configuration node must
not reference non-configuration nodes.
o Added XML encoding rules and usage examples for rpc and
notification.
o Removed requirement that refinements are specified in the same
order as in the original grouping's definition.
o Fixed whitespace issues in the ABNF grammar.
o Added the term "mandatory node", and refer to it in the
description of augment (see Section 7.15), and choice (see
Section 7.9.3).
o Added support for multiple "pattern" statements in "type".
o Several clarifications and fixed typos.
A.2. Version -00
Changes from draft-bjorklund-netconf-yang-02.txt Changes from draft-bjorklund-netconf-yang-02.txt
o Fixed bug in grammar for bit-stmt o Fixed bug in grammar for bit-stmt
o Fixed bugs in example XPath expressions o Fixed bugs in example XPath expressions
o Added keyword 'presence' to the YIN mapping table o Added keyword 'presence' to the YIN mapping table
Author's Address Author's Address
 End of changes. 192 change blocks. 
1196 lines changed or deleted 634 lines changed or added

This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/