Network Working Group M. Bjorklund, Ed.
Internet-Draft Tail-f Systems
Intended status: Standards Track January 12, 2009
Expires: July 16, 2009
YANG - A data modeling language for NETCONF
draft-ietf-netmod-yang-03
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on July 16, 2009.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Bjorklund Expires July 16, 2009 [Page 1]
Internet-Draft YANG January 2009
Abstract
YANG is a data modeling language used to model configuration and
state data manipulated by the NETCONF protocol, NETCONF remote
procedure calls, and NETCONF notifications.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15
4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19
4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22
4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23
4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 24
4.2.10. Notification Definitions . . . . . . . . . . . . . . 25
5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27
5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27
5.1.1. Import and Include by Revision . . . . . . . . . . . 28
5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28
5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29
5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30
5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30
5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30
5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30
5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31
5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 31
5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32
5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32
5.6.4. Announcing Conformance Information in the <hello>
Message . . . . . . . . . . . . . . . . . . . . . . . 33
5.6.5. Mapping to the NETCONF Schema Discovery Mechanism . . 35
6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36
6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36
6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36
6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38
Bjorklund Expires July 16, 2009 [Page 2]
Internet-Draft YANG January 2009
6.2.1. Identifiers and their namespaces . . . . . . . . . . 38
6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39
6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39
6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39
7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40
7.1. The module Statement . . . . . . . . . . . . . . . . . . 40
7.1.1. The module's Substatements . . . . . . . . . . . . . 41
7.1.2. The yang-version Statement . . . . . . . . . . . . . 42
7.1.3. The namespace Statement . . . . . . . . . . . . . . . 42
7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 43
7.1.5. The import Statement . . . . . . . . . . . . . . . . 43
7.1.6. The include Statement . . . . . . . . . . . . . . . . 44
7.1.7. The organization Statement . . . . . . . . . . . . . 44
7.1.8. The contact Statement . . . . . . . . . . . . . . . . 44
7.1.9. The revision Statement . . . . . . . . . . . . . . . 45
7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 46
7.2. The submodule Statement . . . . . . . . . . . . . . . . . 46
7.2.1. The submodule's Substatements . . . . . . . . . . . . 47
7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 48
7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 49
7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 49
7.3.1. The typedef's Substatements . . . . . . . . . . . . . 50
7.3.2. The typedef's type Statement . . . . . . . . . . . . 50
7.3.3. The units Statement . . . . . . . . . . . . . . . . . 50
7.3.4. The typedef's default Statement . . . . . . . . . . . 50
7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 51
7.4. The type Statement . . . . . . . . . . . . . . . . . . . 51
7.4.1. The type's Substatements . . . . . . . . . . . . . . 51
7.5. The container Statement . . . . . . . . . . . . . . . . . 51
7.5.1. Containers with Presence . . . . . . . . . . . . . . 52
7.5.2. The container's Substatements . . . . . . . . . . . . 53
7.5.3. The must Statement . . . . . . . . . . . . . . . . . 53
7.5.4. The must's Substatements . . . . . . . . . . . . . . 55
7.5.5. The presence Statement . . . . . . . . . . . . . . . 56
7.5.6. The container's Child Node Statements . . . . . . . . 56
7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 56
7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 56
7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 57
7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 58
7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 59
7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 59
7.6.3. The leaf's default Statement . . . . . . . . . . . . 59
7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 59
7.6.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 60
7.6.6. NETCONF <edit-config> Operations . . . . . . . . . . 60
7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 60
7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 61
7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 61
Bjorklund Expires July 16, 2009 [Page 3]
Internet-Draft YANG January 2009
7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 63
7.7.3. The min-elements Statement . . . . . . . . . . . . . 63
7.7.4. The max-elements Statement . . . . . . . . . . . . . 63
7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 63
7.7.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 64
7.7.7. NETCONF <edit-config> operations . . . . . . . . . . 64
7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 65
7.8. The list Statement . . . . . . . . . . . . . . . . . . . 67
7.8.1. The list's Substatements . . . . . . . . . . . . . . 67
7.8.2. The list's key Statement . . . . . . . . . . . . . . 68
7.8.3. The lists's unique Statement . . . . . . . . . . . . 69
7.8.4. The list's Child Node Statements . . . . . . . . . . 70
7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 70
7.8.6. NETCONF <edit-config> operations . . . . . . . . . . 70
7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 71
7.9. The choice Statement . . . . . . . . . . . . . . . . . . 74
7.9.1. The choice's Substatements . . . . . . . . . . . . . 75
7.9.2. The choice's case Statement . . . . . . . . . . . . . 75
7.9.3. The choice's default Statement . . . . . . . . . . . 76
7.9.4. The choice's mandatory Statement . . . . . . . . . . 78
7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 78
7.9.6. NETCONF <edit-config> operations . . . . . . . . . . 78
7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 78
7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 79
7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 80
7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 80
7.10.3. NETCONF <edit-config> operations . . . . . . . . . . 80
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 81
7.11. The grouping Statement . . . . . . . . . . . . . . . . . 81
7.11.1. The grouping's Substatements . . . . . . . . . . . . 82
7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 82
7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 82
7.12.1. The uses's Substatements . . . . . . . . . . . . . . 83
7.12.2. The refine Statement . . . . . . . . . . . . . . . . 83
7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 84
7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 84
7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 85
7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 86
7.13.2. The input Statement . . . . . . . . . . . . . . . . . 86
7.13.3. The output Statement . . . . . . . . . . . . . . . . 87
7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 88
7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 88
7.14. The notification Statement . . . . . . . . . . . . . . . 89
7.14.1. The notification's Substatements . . . . . . . . . . 90
7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 90
7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 90
7.15. The augment Statement . . . . . . . . . . . . . . . . . . 91
7.15.1. The augment's Substatements . . . . . . . . . . . . . 92
Bjorklund Expires July 16, 2009 [Page 4]
Internet-Draft YANG January 2009
7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92
7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 93
7.16. The identity Statement . . . . . . . . . . . . . . . . . 95
7.16.1. The identity's Substatements . . . . . . . . . . . . 95
7.16.2. The base Statement . . . . . . . . . . . . . . . . . 95
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 96
7.17. The extension Statement . . . . . . . . . . . . . . . . . 96
7.17.1. The extension's Substatements . . . . . . . . . . . . 97
7.17.2. The argument Statement . . . . . . . . . . . . . . . 97
7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 98
7.18. Conformance-related Statements . . . . . . . . . . . . . 98
7.18.1. The feature Statement . . . . . . . . . . . . . . . . 98
7.18.2. The if-feature Statement . . . . . . . . . . . . . . 100
7.18.3. The deviation Statement . . . . . . . . . . . . . . . 100
7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 103
7.19.1. The config Statement . . . . . . . . . . . . . . . . 103
7.19.2. The status Statement . . . . . . . . . . . . . . . . 103
7.19.3. The description Statement . . . . . . . . . . . . . . 104
7.19.4. The reference Statement . . . . . . . . . . . . . . . 104
7.19.5. The when Statement . . . . . . . . . . . . . . . . . 104
8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 106
8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 106
8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 106
8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 107
8.3.2. NETCONF <edit-config> Processing . . . . . . . . . . 107
8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 108
9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 109
9.1. Canonical representation . . . . . . . . . . . . . . . . 109
9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 109
9.2.1. Lexicographic Representation . . . . . . . . . . . . 110
9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 111
9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 111
9.2.4. The range Statement . . . . . . . . . . . . . . . . . 111
9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 112
9.3. The Floating Point Built-in Types . . . . . . . . . . . . 112
9.3.1. Lexicographic Representation . . . . . . . . . . . . 112
9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 112
9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 112
9.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 113
9.4. The string Built-in Type . . . . . . . . . . . . . . . . 113
9.4.1. Lexicographic Representation . . . . . . . . . . . . 113
9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 113
9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 113
9.4.4. The length Statement . . . . . . . . . . . . . . . . 113
9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 114
9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 115
9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 115
Bjorklund Expires July 16, 2009 [Page 5]
Internet-Draft YANG January 2009
9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 115
9.5.1. Lexicographic Representation . . . . . . . . . . . . 116
9.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 116
9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 116
9.6.1. Lexicographic Representation . . . . . . . . . . . . 116
9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116
9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116
9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 116
9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117
9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 118
9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 118
9.7.2. Lexicographic Representation . . . . . . . . . . . . 118
9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 118
9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 118
9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119
9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 119
9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120
9.8.2. Lexicographic Representation . . . . . . . . . . . . 120
9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 120
9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 120
9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120
9.9.2. The path Statement . . . . . . . . . . . . . . . . . 120
9.9.3. The require-instance Statement . . . . . . . . . . . 121
9.9.4. Lexicographic Representation . . . . . . . . . . . . 121
9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 121
9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 121
9.10. The identityref Built-in Type . . . . . . . . . . . . . . 124
9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124
9.10.2. The identityref's base Statement . . . . . . . . . . 124
9.10.3. Lexicographic Representation . . . . . . . . . . . . 124
9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 124
9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124
9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 125
9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126
9.11.2. Lexicographic Representation . . . . . . . . . . . . 126
9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 126
9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 126
9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 126
9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127
9.12.2. Lexicographic Representation . . . . . . . . . . . . 127
9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 127
9.13. The instance-identifier Built-in Type . . . . . . . . . . 127
9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127
9.13.2. Lexicographic Representation . . . . . . . . . . . . 127
9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 128
9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . . 128
10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 129
11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Bjorklund Expires July 16, 2009 [Page 6]
Internet-Draft YANG January 2009
11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 132
11.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 132
11.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 134
11.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 135
11.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 135
12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 136
13. Error Responses for YANG Related Errors . . . . . . . . . . . 158
13.1. Error Message for Data that Violates a YANG unique
Statement: . . . . . . . . . . . . . . . . . . . . . . . 158
13.2. Error Message for Data that Violates a YANG
max-elements Statement: . . . . . . . . . . . . . . . . . 158
13.3. Error Message for Data that Violates a YANG
min-elements Statement: . . . . . . . . . . . . . . . . . 158
13.4. Error Message for Data that Violates a YANG must
statement: . . . . . . . . . . . . . . . . . . . . . . . 159
13.5. Error Message for the "insert" Operation . . . . . . . . 159
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 160
15. Security Considerations . . . . . . . . . . . . . . . . . . . 161
16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 162
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 163
17.1. Normative References . . . . . . . . . . . . . . . . . . 163
17.2. Non-Normative References . . . . . . . . . . . . . . . . 164
Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 165
A.1. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 165
A.2. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 165
A.3. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 165
A.4. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 166
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 168
Bjorklund Expires July 16, 2009 [Page 7]
Internet-Draft YANG January 2009
1. Introduction
Today, the NETCONF protocol [RFC4741] lacks a standardized way to
create data models. Instead, vendors are forced to use proprietary
solutions. In order for NETCONF to be a interoperable protocol,
models must be defined in a vendor-neutral way. YANG provides the
language and rules for defining such models for use with NETCONF.
YANG is a data modeling language used to model configuration and
state data manipulated by the NETCONF protocol, NETCONF remote
procedure calls, and NETCONF notifications. This document describes
the syntax and semantics of the YANG language, how the data model
defined in a YANG module is represented in XML, and how NETCONF
operations are used to manipulate the data.
Bjorklund Expires July 16, 2009 [Page 8]
Internet-Draft YANG January 2009
2. Key Words
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119].
Bjorklund Expires July 16, 2009 [Page 9]
Internet-Draft YANG January 2009
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 base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type.
o built-in type: A YANG data type defined in the YANG language, such
as uint32 or string.
o choice: A node where only one of a number of identified
alternative nodes is valid.
o configuration data: The set of writable data that is required to
transform a system from its initial default state into its current
state [RFC4741].
o conformance: A measure of how accurately a device follows the
model.
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
nodes. One of container, leaf, leaf-list, list, choice, case,
augment, uses, and anyxml.
o data model: A data model describes how data is represented and
accessed.
o data model object: A definition within a module that represents a
construct which can be accessed via a network management protocol.
Also called an object.
o data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, list, and anyxml.
o data tree: The instantiated tree of configuration and state data
on a device.
o derived type: A type which is derived from a built-in type (such
as uint32), or another derived type.
o device deviation: A failure of the device to implement the module
faithfully.
Bjorklund Expires July 16, 2009 [Page 10]
Internet-Draft YANG January 2009
o extension: An extension attaches non-YANG semantics to nodes. The
extension statement defines new statements to express these
semantics.
o feature: A mechanism for marking a portion of the model as
optional. Definitions can be tagged with a feature name and are
only valid on devices which support that feature.
o grouping: A reusable set of nodes, which may be used locally in
the module, in modules which include it, and by other modules
which import from it.
o identifier: Used to identify different kinds of YANG items by
name.
o instance identifier: A mechanism for identifying a particular node
in a data tree.
o interior node: Nodes within a hierarchy that are not leaf nodes.
o leaf: A 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
identifiable nodes rather than a single node. Each node has a
value but no child nodes.
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
nodes.
o MIB: A Management Information Base, traditionally referring to a
management information defined using SNMP's SMI.
o module: A YANG module defines a hierarchy of nodes which can be
used for NETCONF-based operations. With its definitions and the
definitions it imports or includes from elsewhere, a module is
self-contained and "compilable".
o RPC: A Remote Procedure Call, as used within the NETCONF protocol.
o RPC method: A specific Remote Procedure Call, as used within the
NETCONF protocol. Also called a protocol operation.
o schema node: A node in the schema tree. One of container, leaf,
leaf-list, list, choice, case, rpc, input, output, notification,
and anyxml.
Bjorklund Expires July 16, 2009 [Page 11]
Internet-Draft YANG January 2009
o schema node identifier: A mechanism for identifying a particular
node in the schema tree.
o schema tree: The definition hierarchy specified within a module.
o state data: The additional data on a system that is not
configuration data such as read-only status information and
collected statistics [RFC4741].
o submodule: A partial module definition which contributes derived
types, groupings, data nodes, RPCs, and notifications to a module.
A YANG module can be constructed from a number of submodules.
o uses: The "uses" statement is used to instantiate the set of nodes
defined in a grouping statement. The instantiated nodes may be
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.
Bjorklund Expires July 16, 2009 [Page 12]
Internet-Draft YANG January 2009
4. YANG Overview
4.1. Functional Overview
YANG is a language used to model data for the NETCONF protocol. A
YANG module defines a hierarchy of data which can be used for
NETCONF-based operations, including configuration, state data, remote
procedure calls (RPCs), and notifications. This allows a complete
description of all data sent between a NETCONF client and server.
YANG models the hierarchical organization of data as a tree in which
each node has a name, and either a value or a set of child nodes.
YANG provides clear and concise descriptions of the nodes, as well as
the interaction between those nodes.
YANG structures data models into modules and submodules. A module
can import data from other external modules, and include data from
submodules. The hierarchy can be extended, allowing one module to
add data nodes to the hierarchy defined in another module. This
augmentation can be conditional, with new nodes appearing only if
certain conditions are met.
YANG models can describe constraints to be enforced on the data,
restricting the appearance or value of nodes based on the presence or
value of other nodes in the hierarchy. These constraints are
enforceable by either the client or the server, and valid content
must abide by them.
YANG defines a set of built-in types, and has a type mechanism
through which additional types may be defined. Derived types can
restrict their base type's set of valid values using mechanisms like
range or pattern restrictions that can be enforced by clients or
servers. They can also define usage conventions for use of the
derived type, such as a string-based type that contains a host name.
YANG permits the definition of complex types using reusable grouping
of nodes. The instantiation of these groupings can refine or augment
the nodes, allowing it to tailor the nodes to its particular needs.
Derived types and groupings can be defined in one module or submodule
and used in either that location or in another module or submodule
that imports or includes it.
YANG organizational constructs include defining lists where list
entries are identified by keys which distinguish them from each
other. Such lists may be defined as either sorted by user or
automatically sorted by the system. For user-sorted lists,
operations are defined for manipulating the order of the list
entries.
Bjorklund Expires July 16, 2009 [Page 13]
Internet-Draft YANG January 2009
YANG modules can be translated into an XML format called YIN
(Section 11), allowing applications using XML parsers and XSLT
scripts to operate on the models. The conversion from YANG to YIN is
loss-less, so content in YIN can round-tripped back into YANG.
YANG strikes a balance between high-level data modeling and low-level
bits-on-the-wire encoding. The reader of a YANG module can see the
high-level view of the data model while understanding how the data
will be encoded in NETCONF operations.
YANG is an extensible language, allowing extension statements to be
defined by standards bodies, vendors, and individuals. The statement
syntax allows these extensions to coexist with standard YANG
statements in a natural way, while making extensions stand out
sufficiently for the reader to notice them.
YANG resists the tendency to solve all possible problems, limiting
the problem space to allow expression of NETCONF data models, not
arbitrary XML documents or arbitrary data models. The data models
described by YANG are designed to be easily operated upon by NETCONF
operations.
To the extent possible, YANG maintains compatibility with SNMP's
SMIv2 (Structure of Management Information version 2 [RFC2578],
[RFC2579]). SMIv2-based MIB modules can be automatically translated
into YANG modules for read-only access. However YANG is not
concerned with reverse translation from YANG to SMIv2.
Like NETCONF, YANG targets smooth integration with device's native
management infrastructure. This allows implementations to leverage
their existing access control mechanisms to protect or expose
elements of the data model.
4.2. Language Overview
This section introduces some important constructs used in YANG that
will aid in the understanding of the language specifics in later
sections. This progressive approach handles the inter-related nature
of YANG concepts and statements. Specifics about YANG statements and
syntax begins in Section 7.
4.2.1. Modules and Submodules
A module contains three types of statements: module-header
statements, revision statements, and definition statements. The
module header statements describe the module and give information
about the module itself, the revision statements give information
about the history of the module, and the definition statements are
Bjorklund Expires July 16, 2009 [Page 14]
Internet-Draft YANG January 2009
the body of the module where the data model is defined.
A NETCONF server may implement a number of modules, allowing multiple
views of the same data, or multiple views of disjoint subsections of
the device's data. Alternatively, the server may implement only one
module that defines all available data.
A module may be divided into submodules, based on the needs of the
module owner. The external view remains that of a single module,
regardless of the presence or size of its submodules.
The "include" statement allows a module or submodule to reference
material in submodules, and the "import" statement allows references
to material defined in other modules.
4.2.2. Data Modeling Basics
YANG defines four types of nodes for data modeling. In each of the
following subsections, the example shows the YANG syntax as well as a
corresponding NETCONF XML representation.
4.2.2.1. Leaf Nodes
A leaf node contains simple data like an integer or a string. It has
exactly one value of a particular type, and no child nodes.
YANG Example:
leaf host-name {
type string;
description "Hostname for this system";
}
NETCONF XML Encoding:
<host-name>my.example.com</host-name>
The "leaf" statement is covered in Section 7.6.
4.2.2.2. Leaf-list Nodes
A leaf-list is a sequence of leaf nodes with exactly one value of a
particular type per leaf.
YANG Example:
Bjorklund Expires July 16, 2009 [Page 15]
Internet-Draft YANG January 2009
leaf-list domain-search {
type string;
description "List of domain names to search";
}
NETCONF XML Encoding:
<domain-search>high.example.com</domain-search>
<domain-search>low.example.com</domain-search>
<domain-search>everywhere.example.com</domain-search>
The "leaf-list" statement is covered in Section 7.7.
4.2.2.3. Container Nodes
A container node is used to group related nodes in a subtree. A
container has only child nodes and no value. A container may contain
any number of child nodes of any type (including leafs, lists,
containers, and leaf-lists).
YANG Example:
container system {
container login {
leaf message {
type string;
description
"Message given at start of login session";
}
}
}
NETCONF XML Encoding:
<system>
<login>
<message>Good morning, Dave</message>
</login>
</system>
The "container" statement is covered in Section 7.5.
4.2.2.4. List Nodes
A list defines a sequence of list entries. Each entry is like a
structure or a record instance, and is uniquely identified by the
values of its key leafs. A list can define multiple keys and may
contain any number of child nodes of any type (including leafs,
Bjorklund Expires July 16, 2009 [Page 16]
Internet-Draft YANG January 2009
lists, containers etc.).
YANG Example:
list user {
key "name";
leaf name {
type string;
}
leaf full-name {
type string;
}
leaf class {
type string;
}
}
NETCONF XML Encoding:
<user>
<name>glocks</name>
<full-name>Goldie Locks</full-name>
<class>intruder</class>
</user>
<user>
<name>snowey</name>
<full-name>Snow White</full-name>
<class>free-loader</class>
</user>
<user>
<name>rzull</name>
<full-name>Repun Zell</full-name>
<class>tower</class>
</user>
The "list" statement is covered in Section 7.8.
4.2.2.5. Example Module
These statements are combined to define the module:
Bjorklund Expires July 16, 2009 [Page 17]
Internet-Draft YANG January 2009
// Contents of "acme-system.yang"
module acme-system {
namespace "http://acme.example.com/system";
prefix "acme";
organization "ACME Inc.";
contact "joe@acme.example.com";
description
"The module for entities implementing the ACME system.";
revision 2007-06-09 {
description "Initial revision.";
}
container system {
leaf host-name {
type string;
description "Hostname for this system";
}
leaf-list domain-search {
type string;
description "List of domain names to search";
}
container login {
leaf message {
type string;
description
"Message given at start of login session";
}
list user {
key "name";
leaf name {
type string;
}
leaf full-name {
type string;
}
leaf class {
type string;
}
}
}
}
}
Bjorklund Expires July 16, 2009 [Page 18]
Internet-Draft YANG January 2009
4.2.3. State Data
YANG can model state data, as well as configuration data, based on
the "config" statement. When a node is tagged with "config false",
its subhierarchy is flagged as state data, to be reported using
NETCONF's <get> operation, not the <get-config> operation. Parent
containers, lists, and key leafs are reported also, giving the
context for the state data.
In this example, two leafs are defined for each interface, a
configured speed and an observed speed. The observed speed is not
configuration, so it can be returned with NETCONF <get> operations,
but not with <get-config> operations. The observed speed is not
configuration data, and cannot be manipulated using <edit-config>.
list interface {
key "name";
config true;
leaf name {
type string;
}
leaf speed {
type enumeration {
enum 10m;
enum 100m;
enum auto;
}
}
leaf observed-speed {
type uint32;
config false;
}
}
4.2.4. Built-in Types
YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special
requirements from the management domain. The following table
summarizes the built-in types discussed in Section 9:
Bjorklund Expires July 16, 2009 [Page 19]
Internet-Draft YANG January 2009
+---------------------+-------------+-------------------------------+
| Name | Type | Description |
+---------------------+-------------+-------------------------------+
| binary | Text | Any binary data |
| bits | Text/Number | A set of bits or flags |
| boolean | Text | "true" or "false" |
| empty | Empty | A leaf that does not have any |
| | | value |
| enumeration | Text/Number | Enumerated strings with |
| | | associated numeric values |
| float32 | Number | 32-bit IEEE floating point |
| | | real number |
| float64 | Number | 64-bit IEEE floating point |
| | | real number |
| identityref | Text | A reference to an abstract |
| | | identity |
| instance-identifier | Text | References a data tree node |
| int8 | Number | 8-bit signed integer |
| int16 | Number | 16-bit signed integer |
| int32 | Number | 32-bit signed integer |
| int64 | Number | 64-bit signed integer |
| leafref | Text/Number | A reference to a leaf |
| | | instance |
| string | Text | Human readable string |
| uint8 | Number | 8-bit unsigned integer |
| uint16 | Number | 16-bit unsigned integer |
| uint32 | Number | 32-bit unsigned integer |
| uint64 | Number | 64-bit unsigned integer |
| union | Text/Number | Choice of member types |
+---------------------+-------------+-------------------------------+
The "type" statement is covered in Section 9.
4.2.5. Derived Types (typedef)
YANG can define derived types from base types using the "typedef"
statement. A base type can be either a built-in type or a derived
type, allowing a hierarchy of derived types.
A derived type can be used as the argument for the "type" statement.
YANG Example:
Bjorklund Expires July 16, 2009 [Page 20]
Internet-Draft YANG January 2009
typedef percent {
type uint16 {
range "0 .. 100";
}
description "Percentage";
}
leaf completed {
type percent;
}
NETCONF XML Encoding:
<completed>20</completed>
The "typedef" statement is covered in Section 7.3.
4.2.6. Reusable Node Groups (grouping)
Groups of nodes can be assembled into the equivalent of complex types
using the "grouping" statement. "grouping" defines a set of nodes
that are instantiated with the "uses" statement:
grouping target {
leaf address {
type inet:ip-address;
description "Target IP address";
}
leaf port {
type inet:port-number;
description "Target port number";
}
}
container peer {
container destination {
uses target;
}
}
NETCONF XML Encoding:
<peer>
<destination>
<address>192.0.2.1</address>
<port>830</port>
</destination>
</peer>
Bjorklund Expires July 16, 2009 [Page 21]
Internet-Draft YANG January 2009
The grouping can be refined as it is used, allowing certain
statements to be overridden. In this example, the description is
refined:
container connection {
container source {
uses target {
refine "address" {
description "Source IP address";
}
refine "port" {
description "Source port number";
}
}
}
container destination {
uses target {
refine "address" {
description "Destination IP address";
}
refine "port" {
description "Destination port number";
}
}
}
}
The "grouping" statement is covered in Section 7.11.
4.2.7. Choices
YANG allows the data model to segregate incompatible nodes into
distinct choices using the "choice" and "case" statements. The
"choice" statement contains a set of "case" statements which define
sets of schema nodes that cannot appear together. Each "case" may
contain multiple nodes, but each node may appear in only one "case"
under a "choice".
When an element from one case is created, all elements from all other
cases are implicitly deleted. The device handles the enforcement of
the constraint, preventing incompatibilities from existing in the
configuration.
The choice and case nodes appear only in the schema tree, not in the
data tree or XML encoding. The additional levels of hierarchy are
not needed beyond the conceptual schema.
YANG Example:
Bjorklund Expires July 16, 2009 [Page 22]
Internet-Draft YANG January 2009
container food {
choice snack {
mandatory true;
case sports-arena {
leaf pretzel {
type empty;
}
leaf beer {
type empty;
}
}
case late-night {
leaf chocolate {
type enumeration {
enum dark;
enum milk;
enum first-available;
}
}
}
}
}
NETCONF XML Encoding:
<food>
<chocolate>first-available</chocolate>
</food>
The "choice" statement is covered in Section 7.9.
4.2.8. Extending Data Models (augment)
YANG allows a module to insert additional nodes into data models,
including both the current module (and its submodules) or an external
module. This is useful e.g. for vendors to add vendor-specific
parameters to standard data models in an interoperable way.
The "augment" statement defines the location in the data model
hierarchy where new nodes are inserted, and the "when" statement
defines the conditions when the new nodes are valid.
YANG Example:
Bjorklund Expires July 16, 2009 [Page 23]
Internet-Draft YANG January 2009
augment system/login/user {
when "class != 'wheel'";
leaf uid {
type uint16 {
range "1000 .. 30000";
}
}
}
This example defines a "uid" node that only is valid when the user's
"class" is not "wheel".
If a module augments another model, the XML representation of the
data will reflect the prefix of the augmenting model. For example,
if the above augmentation were in a module with prefix "other", the
XML would look like:
NETCONF XML Encoding:
<user>
<name>alicew</name>
<full-name>Alice N. Wonderland</full-name>
<class>drop-out</class>
<other:uid>1024</other:uid>
</user>
The "augment" statement is covered in Section 7.15.
4.2.9. RPC Definitions
YANG allows the definition of NETCONF RPCs. The method names, input
parameters and output parameters are modeled using YANG data
definition statements.
YANG Example:
rpc activate-software-image {
input {
leaf image-name {
type string;
}
}
output {
leaf status {
type string;
}
}
}
Bjorklund Expires July 16, 2009 [Page 24]
Internet-Draft YANG January 2009
NETCONF XML Encoding:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<activate-software-image xmlns="http://acme.example.com/system">
<name>acmefw-2.3</name>
</activate-software-image>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<status xmlns="http://acme.example.com/system">
The image acmefw-2.3 is being installed.
</status>
</rpc-reply>
The "rpc" statement is covered in Section 7.13.
4.2.10. Notification Definitions
YANG allows the definition of notifications suitable for NETCONF.
YANG data definition statements are used to model the content of the
notification.
YANG Example:
notification link-failure {
description "A link failure has been detected";
leaf if-name {
type leafref {
path "/interfaces/interface/name";
}
}
leaf if-admin-status {
type ifAdminStatus;
}
}
NETCONF XML Encoding:
<notification
xmlns="urn:ietf:params:netconf:capability:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system">
<if-name>so-1/2/3.0</if-name>
<if-admin-status>up</if-admin-status>
</link-failure>
</notification>
Bjorklund Expires July 16, 2009 [Page 25]
Internet-Draft YANG January 2009
The "notification" statement is covered in Section 7.14.
Bjorklund Expires July 16, 2009 [Page 26]
Internet-Draft YANG January 2009
5. Language Concepts
5.1. Modules and Submodules
The module is the base unit of definition in YANG. A module defines
a single data model. A module can define a complete, cohesive model,
or augment an existing data model with additional nodes.
Submodule are partial modules that contribute definitions to a
module. A module may include any number of submodules, but each
submodule may belong to only one module.
The names of all standard modules and submodules MUST be unique.
Developers of enterprise modules are RECOMMENDED to choose names for
their modules that will have a low probability of colliding with
standard or other enterprise modules, e.g. by using the enterprise or
organization name as a prefix.
A module uses the "include" statement to include its submodules, and
the "import" statement to reference external modules. Similarly, a
submodule uses the "import" statement to reference other modules, and
uses the "include" statement to reference other submodules within its
module. A module or submodule MUST NOT include submodules from other
modules, and a submodule MUST NOT import its own module.
The import and include statements are used to make definitions
available to other modules and submodules:
o For a module to reference definitions in an external module, the
external module MUST be imported.
o For a module to reference definitions in one of its submodules,
the module MUST include the submodule.
o For a submodule to reference definitions in a second submodule of
the same module, the first submodule MUST include the second
submodule.
There MUST NOT be any circular chains of imports or includes. For
example, if submodule "a" includes submodule "b", "b" cannot include
"a".
When a definition in an external module is referenced, a locally
defined prefix MUST be used, followed by ":", and then the external
identifier. References to definitions in the local module MAY use
the prefix notation. Since built-in data types do not belong to any
module and have no prefix, references to built-in data types (e.g.
int32) cannot use the prefix notation.
Bjorklund Expires July 16, 2009 [Page 27]
Internet-Draft YANG January 2009
5.1.1. Import and Include by Revision
Published modules evolve independently over time. In order to allow
for this evolution, modules need to be imported using specific
revisions. When a module is written, it uses the current revisions
of other modules, based on what is available at the time. As future
revisions of the imported modules are published, the importing module
is unaffected and its contents are unchanged. When the author of the
module is prepared to move to the most recently published revision of
an imported module, the module is republished with an updated import
statement. By republishing with the new revision, the author is
explicitly indicating their acceptance of any changes in the imported
module.
For submodules, the issue is related but simpler. A module or
submodule that includes submodules need to specify the revision of
the included submodules. If a submodule changes, any module or
submodule that includes it needs to be updated.
For example, module "b" imports module "a".
module a {
revision 2008-01-01 { ... }
grouping a {
leaf eh { .... }
}
}
module b {
import a {
prefix a;
revision 2008-01-01;
}
container bee {
uses a:a;
}
}
When the author of "a" publishes a new revision, the changes may not
be acceptable to the author of "b". If the new revision is
acceptable, the author of "a" can republish with an updated revision
in the import statement.
5.1.2. Module Hierarchies
YANG allows modeling of data in multiple hierarchies, where data may
have more than one top-level node. Models that have multiple top-
Bjorklund Expires July 16, 2009 [Page 28]
Internet-Draft YANG January 2009
level nodes are sometimes convenient, and are supported by YANG.
NETCONF is capable of carrying any XML content as the payload in the
<config> element. The top-level nodes of YANG modules are encoded as
child elements within the <config> element.
For example:
module my-config {
namespace "http://example.com/schema/config";
prefix "co";
container system { ... }
container routing { ... }
}
could be encoded in NETCONF as:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<!-- system data here -->
</system>
<routing xmlns="http://example.com/schema/config">
<!-- routing data here -->
</routing>
</config>
</edit-config>
</rpc>
5.2. File Layout
YANG modules and submodules are typically stored in files, one module
or submodule per file, with the name of the file on the form:
module-or-submodule-name ['.' revision-number] ( '.yang' / '.yin' )
YANG compilers can find imported modules and included submodules via
this convention. While the YANG language defines modules, tools may
compile submodules independently for performance and manageability
reasons. Many errors and warnings that cannot be detected during
submodule compilation may be delayed until the submodules are linked
Bjorklund Expires July 16, 2009 [Page 29]
Internet-Draft YANG January 2009
into a cohesive module.
5.3. XML Namespaces
All YANG definitions are specified within a module that is bound to a
particular XML Namespace [XML-NAMES], which is a globally unique URI
[RFC3986]. A NETCONF client or server uses the namespace during XML
encoding of data.
Namespaces for standard modules MUST be assigned by IANA.
Namespaces for private modules are assigned by the organization
owning the module without a central registry. It is RECOMMENDED to
choose namespaces that will have a low probability of colliding with
standard or other enterprise modules, e.g. by using the enterprise or
organization name in the namespace.
The "namespace" statement is covered in Section 7.1.3.
5.3.1. YANG XML Namespace
YANG defines its own XML namespace for NETCONF <edit-config>
operations. This namespace is "urn:ietf:params:xml:ns:yang:1" [XXX
IANA].
5.4. Resolving Grouping, Type, and Identity Names
Grouping, type, and identity names are resolved in the context in
which they are defined, rather than the context in which they are
used. Users of groupings, typedefs, and identities are not required
to import modules or include submodules to satisfy all references
made by the original definition. This behaves like static scoping in
a conventional programming language.
For example, if a module defines a grouping in which a type is
referenced, when the grouping is used in a second module, the type is
resolved in the context of the original module, not the second
module. There is no worry over conflicts if both modules define the
type, since there is no ambiguity.
5.5. Nested Typedefs and Groupings
Typedefs and groupings may appear nested under many YANG statements,
allowing these to be lexically scoped by the hierarchy under which
they appear. This allows types and groupings to be defined near
where they are used, rather than placing them at the top level of the
hierarchy. The close proximity increases readability.
Bjorklund Expires July 16, 2009 [Page 30]
Internet-Draft YANG January 2009
Scoping also allows types to be defined without concern for naming
conflicts between types in different submodules. Type names can be
specified without adding leading strings designed to prevent name
collisions within large modules.
Finally, scoping allows the module author to keep types and groupings
private to their module or submodule, preventing their reuse. Since
only top-level types and groupings can be used outside the module or
submodule, the developer has more control over what pieces of their
module are presented to the outside world, supporting the need to
hide internal information and maintaining a boundary between what is
shared with the outside world and what is kept private.
Scoped definitions MUST NOT shadow definitions at a higher scope. A
type or group cannot be defined if a higher level in the schema
hierarchy has a definition with a matching identifier.
When a YANG implementation resolves a reference to an unprefixed type
or grouping, or one which uses the prefix of the local module, it
searches up the levels of hierarchy in the schema tree, starting at
the current level, for the definition of the type or grouping.
5.6. Conformance
Conformance is a measure of how accurately a device follows the
model. Generally speaking, devices are responsible for implementing
the model faithfully, allowing applications to treat devices which
implement the model identically. Deviations from the model can
reduce the utility of the model and increase fragility into
applications that use it.
YANG modelers have three mechanisms for conformance:
o the basic behavior of the model
o optional features that are part of the model
o deviations from the model
We will consider each of these in sequence.
5.6.1. Basic Behavior
The model defines a contract between the NETCONF client and server,
which allows both parties to have faith the other knows the syntax
and semantics behind the modeled data. The strength of YANG lies in
the strength of this contract and the mindless devotion with which
implementers follow it.
Bjorklund Expires July 16, 2009 [Page 31]
Internet-Draft YANG January 2009
5.6.2. Optional Features
In many models, the modeler will allow sections of the model to be
conditional, based on the device. The device controls whether these
conditional portions of the model are supported or valid for that
particular device.
For example, a syslog data model may choose to include the ability to
save logs locally, but the modeler will realize that this is only
possible if the device has local storage. If there is no local
storage, an application should not tell the device to save logs.
YANG supports this conditional mechanism using a construct called
"features". Features give the modeler a mechanism for making
portions of the module conditional in a manner that is controlled by
the device. The model can express constructs which are not
universally present in all devices. These features are included in
the model definition, allowing a consistent view and allowing
applications to learn which features are supported and tailor their
behavior to the device.
A module may declare any number of features, identified by simple
strings, and may make portions of the module optional based on those
feature. If the device supports a feature, then the corresponding
portions of the module are valid for that device. If the device
doesn't support the feature, those parts of the module are not valid,
and applications should behave accordingly.
Features are defined using the "feature" statement. Definitions in
the module that are conditional to the feature are noted by the "if-
feature" statement with the name of the feature as its argument.
Further details are available in Section 7.18.1.
5.6.3. Deviations
In an ideal world, all devices would be required to implement the
model exactly as defined, and deviations from the model would not be
allowed. But in the real world, devices are often not able or
willing to implement the model as written. For YANG-based automation
to deal with these device deviations, a mechanism must exist for
devices to inform applications of the specifics of such deviations.
For example, a BGP module may allow any number of BGP peers, but a
particular device may only support 16 BGP peers. Any application
configuring the 17th peer will receive an error. While an error may
suffice to let the application know it cannot add another peer, it
would be far better if the application had prior knowledge of this
Bjorklund Expires July 16, 2009 [Page 32]
Internet-Draft YANG January 2009
limitation and could prevent the user from starting down the path
that could not succeed.
Device deviations are declared using the "deviation" statement, which
takes as its argument a string which identifies a node in the schema
tree. The contents of the statement details the manner in which the
device implementation deviates from the contract as defined in the
module.
5.6.4. Announcing Conformance Information in the <hello> Message
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 MUST be on the form:
capability-string = namespace-uri [ parameter-list ]
parameter-list = "?" parameter *( "&" parameter )
parameter = revision-parameter /
module-parameter /
feature-parameter /
deviation-parameter
revision-parameter = "revision=" revision-number
module-parameter = "module=" module-name
feature-parameter = "features=" feature *( "," feature )
deviation-parameter = "deviations=" deviation *( "," deviation )
Where "revision-number" is the revision of the module (see
Section 7.1.9) that the NETCONF server implements, "module-name" is
the name of module as it appears in the "module" statement (see
Section 7.1), "namespace-uri" is the namespace for the module as it
appears in the "namespace" statement, "feature" is the name of an
optional feature implemented by the device (see Section 7.18.1), and
"deviation" is the name of a module defining device deviations (see
Section 7.18.3).
5.6.4.1. Modules
Devices indicate the names of supported modules via the <hello>
message. Module namespaces are encoded as the base URI in the
capability string, and the module name is encoded as the "module"
parameter to the base URI.
Modules that do not contribute any data definitions, rpcs,
notifications, or deviations to the device are not advertised in the
<hello> message.
For example, this <hello> message advertises one module "my-syslog".
Bjorklund Expires July 16, 2009 [Page 33]
Internet-Draft YANG January 2009
<hello>
<capability>
http://example.com/syslog?module=my-syslog&revision=2008-04-01
</capability>
</hello>
5.6.4.2. Features
Devices indicate the names of supported features via the <hello>
message. In hello messages, the features are encoded in the
"features" parameter within the URI. The value of this parameter is
a comma-separated list of feature names which the device supports for
the specific module.
For example, this <hello> message advertises one module, informing
the client that it supports the "local-storage" feature of module
"my-syslog".
<hello>
<capability>
http://example.com/syslog?module=my-syslog&features=local-storage
</capability>
</hello>
5.6.4.3. Deviations
Device deviations are announced via the "deviations" parameter. The
value of the deviations parameter is a comma-separated list of
modules containing deviations from the capability's module.
For example, this <hello> message advertises two modules, informing
the client that it deviates from module "my-syslog" according to the
deviations listed in the module "my-devs".
<hello>
<capability>
http://example.com/syslog?module=my-syslog&deviations=my-devs
</capability>
<capability>
http://example.com/my-deviations?module=my-devs
</capability>
</hello>
Bjorklund Expires July 16, 2009 [Page 34]
Internet-Draft YANG January 2009
5.6.5. Mapping to the NETCONF Schema Discovery Mechanism
+--------------------------------------------------------------+
| Open Question |
+--------------------------------------------------------------+
| Move this section to the monitoring spec? |
+--------------------------------------------------------------+
The NETCONF Schema Discovery process is defined in [TBD]. It
specifies a "schema" list where each entry is identified by
"identifier", "version", and "format".
All revisions of all YANG modules and submodules supported by a
device SHOULD be present in the "schema" list, including modules with
only typedefs and groupings.
The following table specifies how the fields in the "schema" list are
used for YANG modules and submodules:
identifier - the name of the module or submodule.
version - the supported YANG revision string.
format - the string "YANG".
namespace - the module's namespace. if the list entry describes a
submodule, this field contains the namespace of the
module to which the submodule belongs.
Note that the format is "YANG", even if the YIN syntax is used.
Bjorklund Expires July 16, 2009 [Page 35]
Internet-Draft YANG January 2009
6. YANG syntax
The YANG syntax is similar to that of SMIng [RFC3780] and programming
languages like C and C++. This C-like syntax was chosen specifically
for its readability, since YANG values the time and effort of the
readers of models above those of modules writers and YANG tool-chain
developers. This section introduces the YANG syntax.
YANG modules are written in the UTF-8 [RFC3629] character set.
6.1. Lexicographical Tokenization
YANG modules are parsed as a series of tokens. This section details
the rules for recognizing tokens from an input stream. YANG
tokenization rules are both simple and powerful. The simplicity is
driven by a need to keep the parsers easy to implement, while the
power is driven by the fact that modelers need to express their
models in readable formats.
6.1.1. Comments
Comments are C++ style. A single line comment starts with "//" and
ends at the end of the line. A block comment is enclosed within "/*"
and "*/".
6.1.2. Tokens
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
core YANG keywords defined in this document, or a prefix identifier,
followed by ":", followed by a language extension keyword. Keywords
are case sensitive. See Section 6.2 for a formal definition of
identifiers.
6.1.3. Quoting
If a string contains any whitespace characters, a semicolon (";"),
braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then
it MUST be enclosed within double or single quotes.
If the double quoted string contains a line break followed by
whitespace which is used to indent the text according to the layout
in the YANG file, this leading whitespace is stripped from the
string, up to at most the same column of the double quote character.
If the double quoted string contains whitespace before a line break,
this trailing whitespace is stripped from the string.
Bjorklund Expires July 16, 2009 [Page 36]
Internet-Draft YANG January 2009
A single quoted string (enclosed within ' ') preserves each character
within the quotes. A single quote character can not occur in a
single quoted string, even when preceded by a backslash.
If a quoted string is followed by a plus character ("+"), followed by
another quoted string, the two strings are concatenated into one
quoted string, allowing multiple concatenations to build one quoted
string. Whitespace trimming of double quoted strings is done before
concatenation.
Within a double quoted string (enclosed within " "), a backslash
character introduces a special character, which depends on the
character that immediately follows the backslash:
\n new line
\t a tab character
\" a double quote
\\ a single backslash
6.1.3.1. Quoting Examples
The following strings are equivalent:
hello
"hello"
'hello'
"hel" + "lo"
'hel' + "lo"
The following examples show some special strings:
"\"" - string containing a double quote
'"' - string containing a double quote
"\n" - string containing a newline character
'\n' - string containing a backslash followed
by the character n
The following examples show some illegal strings:
'''' - a single-quoted string cannot contain single quotes
""" - a double quote must be escaped in a double quoted string
The following strings are equivalent:
"first line
second line"
"first line\n" + " second line"
Bjorklund Expires July 16, 2009 [Page 37]
Internet-Draft YANG January 2009
6.2. Identifiers
Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an upper-case or lower-case ASCII
letter or an underscore character, followed by zero or more ASCII
letters, digits, underscore characters, hyphens, and dots.
Implementations MUST support identifiers up to 63 characters in
length. Identifiers are case sensitive. The identifier syntax is
formally defined by the rule "identifier" in Section 12. Identifiers
can be specified as quoted or unquoted strings.
6.2.1. Identifiers and their namespaces
Each identifier is valid in a namespace which depends on the type of
the YANG item being defined:
o All module and submodule names share the same global module
identifier namespace.
o All extension names defined in a module and its submodules share
the same extension identifier namespace.
o All feature names defined in a module and its submodules share the
same feature identifier namespace.
o All identity names defined in a module and its submodules share
the same identity identifier namespace.
o All derived type names defined within a parent node or at the top-
level of the module or its submodules share the same type
identifier namespace. This namespace is scoped to the parent node
or module.
o All groupings defined within a parent node or at the top-level of
the module or its submodules share the same grouping identifier
namespace. This namespace is scoped to the parent node or module.
o All leafs, leaf-lists, lists, containers, choices, rpcs, and
notifications defined within a parent node or at the top-level of
the module or its submodules share the same identifier namespace.
This namespace is scoped to the parent node or module, unless the
parent node is a case node. In that case, the namespace is scoped
to the parent node of the case node's parent choice node.
o All cases within a choice share the same case identifier
namespace. This namespace is scoped to the parent choice node.
All identifiers defined in a namespace MUST be unique.
Bjorklund Expires July 16, 2009 [Page 38]
Internet-Draft YANG January 2009
Forward references are allowed in YANG.
6.3. Statements
A YANG module contains a sequence of statements. Each statement
starts with a keyword, followed by zero or one argument, followed
either by a semicolon (";") or a block of substatements enclosed
within braces ("{ }"):
statement = keyword [argument] (";" / "{" *statement "}")
The argument is a string, as defined in Section 6.1.2.
6.3.1. Language Extensions
A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.17). The extensions can be imported by other
modules with the "import" statement (see Section 7.1.5). When an
imported extension is used, the extension's keyword MUST be qualified
using the prefix with which the extension's module was imported. If
an extension is used in the module where it is defined, the
extension's keyword MUST be qualified with the module's prefix.
Since submodules cannot include the parent module, any extensions in
the module which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the
definition of the extension.
6.4. XPath Evaluations
YANG relies on XPath 1.0 [XPATH] as a notation for specifying many
inter-node references and dependencies. NETCONF clients and servers
are not required to implement an XPath interpreter, but MUST ensure
that the requirements encoded in the data model are enforced. The
manner of enforcement is an implementation decision. The XPath
expressions MUST be valid, but any implementation may choose to
implement them by hand, rather than using the XPath expression
directly.
XPath expressions are evaluated in the context of the current node,
with the namespace of the current module defined as the null
namespace. References to identifiers in external modules MUST be
qualified with appropriate prefixes, and references to the current
module and its submodules MAY use a prefix.
Bjorklund Expires July 16, 2009 [Page 39]
Internet-Draft YANG January 2009
7. YANG Statements
The following sections describe all of the YANG core statements.
Note that even a statement which does not have any substatements
defined in core YANG can have vendor-specific extensions as
substatements. For example, the "description" statement does not
have any substatements defined in core YANG, but the following is
legal:
description "some text" {
acme:documentation-flag 5;
}
7.1. The module Statement
The "module" statement defines the module's name, and groups all
statements which belong to the module together. The "module"
statement's argument is the name of the module, followed by a block
of substatements that hold detailed module information. The module
name follows the rules for identifiers in Section 6.2.
Standard module names MUST be assigned by IANA.
Private module names are assigned by the organization owning the
module without a central registry. It is RECOMMENDED to choose
submodule names that will have a low probability of colliding with
standard or other enterprise modules and submodules, e.g. by using
the enterprise or organization name as a prefix.
A module SHOULD have the following layout:
Bjorklund Expires July 16, 2009 [Page 40]
Internet-Draft YANG January 2009
module <module-name> {
// header information
<yang-version statement>
<namespace statement>
<prefix statement>
// linkage statements
<import statements>
<include statements>
// meta information
<organization statement>
<contact statement>
<description statement>
<reference statement>
// revision history
<revision statements>
// module definitions
<other statements>
}
7.1.1. The module's Substatements
Bjorklund Expires July 16, 2009 [Page 41]
Internet-Draft YANG January 2009
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| contact | 7.1.8 | 0..1 |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| deviation | 7.18.3 | 0..n |
| extension | 7.17 | 0..n |
| feature | 7.18.1 | 0..n |
| grouping | 7.11 | 0..n |
| import | 7.1.5 | 0..n |
| include | 7.1.6 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| namespace | 7.1.3 | 1 |
| notification | 7.14 | 0..n |
| organization | 7.1.7 | 0..1 |
| prefix | 7.1.4 | 1 |
| reference | 7.19.4 | 0..1 |
| revision | 7.1.9 | 0..n |
| rpc | 7.13 | 0..n |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
| yang-version | 7.1.2 | 0..1 |
+--------------+---------+-------------+
7.1.2. The yang-version Statement
The "yang-version" statement specifies which version of the YANG
language was used in developing the module. The statement's argument
contains value "1", which is the current yang version and the default
value.
7.1.3. The namespace Statement
The "namespace" statement defines the XML namespace for all XML
elements defined by the module. Its argument is the URI of the
namespace.
See also Section 5.3.
Bjorklund Expires July 16, 2009 [Page 42]
Internet-Draft YANG January 2009
7.1.4. The prefix Statement
The "prefix" statement is used to define the prefix associated with
the module and its namespace. The "prefix" statement's argument is
the prefix string which is used as a prefix to access a module. The
prefix string MAY be used to refer to definitions contained in the
module, e.g. "if:ifName". A prefix follows the same rules as an
identifier (see Section 6.2).
When used inside the "module" statement, the "prefix" statement
defines the prefix to be used when this module is imported. To
improve readability of the NETCONF XML, a NETCONF client or server
which generates XML or XPath that use prefixes, the prefix defined by
a module SHOULD be used, unless there is a conflict.
When used inside the "import" statement, the "prefix" statement
defines the prefix to be used when accessing definitions inside the
imported module. When a reference to an identifier from the imported
module is used, the prefix string for the module from which objects
are being imported is used in combination with a colon (":") and the
identifier, e.g. "if:ifIndex". To improve readability of YANG
modules, the prefix defined by a module SHOULD be used when the
module is imported, unless there is a conflict.
All prefixes, including the prefix for the module itself MUST be
unique within the module or submodule.
7.1.5. The import Statement
The "import" statement makes definitions from one module available
inside another module or submodule. The argument is the name of the
module to import, and the statement is followed by a block of
substatements that holds detailed import information.
The mandatory "prefix" substatement assigns a prefix for the imported
module which is scoped to the importing module or submodule.
Multiple "import" statements may be specified to import from
different modules.
When the optional "revision" is present, any typedef, grouping,
extension, feature, and identity referenced by definitions in the
local module are taken from the specified revision of the imported
module.
Bjorklund Expires July 16, 2009 [Page 43]
Internet-Draft YANG January 2009
The import's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| prefix | 7.1.4 | 1 |
| revision | 7.1.9 | 0..1 |
+--------------+---------+-------------+
7.1.6. The include Statement
The "include" statement is used to make content from a submodule
available to the module. The argument is an identifier which is the
name of the submodule to include. Modules are only allowed to
include submodules that belong to that module, as defined by the
"belongs-to" statement (see Section 7.2.2).
When a module includes a submodule, it incorporates the contents of
the submodule into the node hierarchy of the module. When a
submodule includes another submodule, the target submodule's
definitions are made available to the current submodule.
When the optional "revision" is present, the specified revision of
the submodule is included in the module.
The includes's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| revision | 7.1.9 | 0..1 |
+--------------+---------+-------------+
7.1.7. The organization Statement
The "organization" statement defines the party responsible for this
module. The argument is a string which is used to specify a textual
description of the organization(s) under whose auspices this module
was developed.
7.1.8. The contact Statement
The "contact" statement provides contact information for the module.
The argument is a string which is used to specify the name, postal
address, telephone number, and electronic mail address of the person
to whom technical queries concerning this module should be sent.
Bjorklund Expires July 16, 2009 [Page 44]
Internet-Draft YANG January 2009
7.1.9. The revision Statement
The "revision" statement specifies the editorial revision history of
the module, including the initial revision. A series of revisions
statements detail the changes in the module's definition. The
argument is a date string in the format "YYYY-MM-DD", followed by a
block of substatements that holds detailed revision information. A
module SHOULD have at least one initial "revision" statement. For
every editorial change, a new one SHOULD be added in front of the
revisions sequence, so that all revisions are in reverse
chronological order.
7.1.9.1. The revision's Substatement
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description | 7.19.3 | 0..1 |
+--------------+---------+-------------+
Bjorklund Expires July 16, 2009 [Page 45]
Internet-Draft YANG January 2009
7.1.10. Usage Example
module acme-system {
namespace "http://acme.example.com/system";
prefix "acme";
import yang-types {
prefix "yang";
}
include acme-types;
organization "ACME Inc.";
contact
"Joe L. User
ACME, Inc.
42 Anywhere Drive
Nowhere, CA 95134
USA
Phone: +1 800 555 0815
EMail: joe@acme.example.com";
description
"The module for entities implementing the ACME protocol.";
revision "2007-06-09" {
description "Initial revision.";
}
// definitions follows...
}
7.2. The submodule Statement
While the primary unit in YANG is a module, a YANG module can itself
be constructed out of several submodules. Submodules allows a module
designer to split a complex model into several pieces where all the
submodules contribute to a single namespace, which is defined by the
module that includes the submodules.
The "submodule" statement is used to give the submodule a name, and
to group all statements which belong to the submodule together.
The "submodule" statement, which MUST be present at most once, takes
as an argument an identifier which is the name of the submodule,
followed by a block of substatements that hold detailed submodule
Bjorklund Expires July 16, 2009 [Page 46]
Internet-Draft YANG January 2009
information.
Standard submodule names MUST be assigned by IANA.
Private submodule names are assigned by the organization owning the
submodule without a central registry. It is RECOMMENDED to choose
submodule names that will have a low probability of colliding with
standard or other enterprise modules and submodules, e.g. by using
the enterprise or organization name as a prefix.
A submodule SHOULD have the following layout:
submodule <module-name> {
<yang-version statement>
// module identification
<belongs-to statement>
// linkage statements
<import statements>
<include statements>
// meta information
<organization statement>
<contact statement>
<description statement>
<reference statement>
// revision history
<revision statements>
// module definitions
<other statements>
}
7.2.1. The submodule's Substatements
Bjorklund Expires July 16, 2009 [Page 47]
Internet-Draft YANG January 2009
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| belongs-to | 7.2.2 | 1 |
| choice | 7.9 | 0..n |
| contact | 7.1.8 | 0..1 |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| deviation | 7.18.3 | 0..n |
| extension | 7.17 | 0..n |
| feature | 7.18.1 | 0..n |
| grouping | 7.11 | 0..n |
| import | 7.1.5 | 0..n |
| include | 7.1.6 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| notification | 7.14 | 0..n |
| organization | 7.1.7 | 0..1 |
| reference | 7.19.4 | 0..1 |
| revision | 7.1.9 | 0..n |
| rpc | 7.13 | 0..n |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
| yang-version | 7.1.2 | 0..1 |
+--------------+---------+-------------+
7.2.2. The belongs-to Statement
The "belongs-to" statement specifies the module to which the
submodule belongs. The argument is an identifier which is the name
of the module.
A submodule MUST only be included by the module to which it belongs,
or by another submodule which belongs to that module.
The mandatory "prefix" substatement assigns a prefix for the module
to which the submodule belongs. All definitions in the local
submodule and any included submodules can be accessed by using the
prefix.
Bjorklund Expires July 16, 2009 [Page 48]
Internet-Draft YANG January 2009
The belongs-to's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| prefix | 7.1.4 | 1 |
+--------------+---------+-------------+
7.2.3. Usage Example
submodule acme-types {
belongs-to "acme-system" {
prefix "acme";
}
import yang-types {
prefix "yang";
}
organization "ACME Inc.";
contact
"Joe L. User
ACME, Inc.
42 Anywhere Drive
Nowhere, CA 95134
USA
Phone: +1 800 555 0815
EMail: joe@acme.example.com";
description
"This submodule defines common ACME types.";
revision "2007-06-09" {
description "Initial revision.";
}
// definitions follows...
}
7.3. The typedef Statement
The "typedef" statement defines a new type which may be used locally
in the module, in modules or submodules which include it, and by
other modules which import from it, according to the rules in
Section 5.5. The new type is called the "derived type", and the type
Bjorklund Expires July 16, 2009 [Page 49]
Internet-Draft YANG January 2009
from which it was derived is called the "base type". All derived
types can be traced back to a YANG built-in type.
The "typedef" statement's argument is an identifier which is the name
of the type to be defined, and MUST be followed by a block of
substatements that holds detailed typedef information.
The name of the type MUST NOT be one of the YANG built-in types. If
the typedef is defined at the top level of a YANG module or
submodule, the name of the type to be defined MUST be unique within
the module.
7.3.1. The typedef's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| default | 7.3.4 | 0..1 |
| description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| type | 7.3.2 | 1 |
| units | 7.3.3 | 0..1 |
+--------------+---------+-------------+
7.3.2. The typedef's type Statement
The "type" statement, which MUST be present, defines the base type
from which this type is derived. See Section 7.4 for details.
7.3.3. The units Statement
The "units" statement, which is optional, takes as an argument a
string which contains a textual definition of the units associated
with the type.
7.3.4. The typedef's default Statement
The "default" statement takes as an argument a string which contains
a default value for the new type.
The value of the "default" statement MUST be valid according to the
type specified in the "type" statement.
If the base type has a default value, and the new derived type does
not specify a new default value, the base type's default value is
also the default value of the new derived type. If the base type's
default value is not valid according to the new restrictions, the
Bjorklund Expires July 16, 2009 [Page 50]
Internet-Draft YANG January 2009
derived type MUST define a new default value.
7.3.5. Usage Example
typedef listen-ipv4-address {
type inet:ipv4-address;
default "0.0.0.0";
}
7.4. The type Statement
The "type" statement takes as an argument a string which is the name
of a YANG built-in type (see Section 9) or a derived type (see
Section 7.3), followed by an optional block of substatements that are
used to put further restrictions on the type.
The restrictions that can be applied depend on the type being
restricted. The restriction statements are described in subsections
for each built-in type in Section 9.
7.4.1. The type's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| bit | 9.7.4 | 0..n |
| enum | 9.6.4 | 0..n |
| length | 9.4.4 | 0..1 |
| path | 9.9.2 | 0..1 |
| pattern | 9.4.6 | 0..n |
| range | 9.2.4 | 0..1 |
| type | 7.4 | 0..n |
+--------------+---------+-------------+
7.5. The container Statement
The "container" statement is used to define an interior node in the
schema tree. It takes one argument, which is an identifier, followed
by a block of substatements that holds detailed container
information.
A container node does not have a value, but it has a list of child
nodes in the data tree. The child nodes are defined in the
container's substatements.
Bjorklund Expires July 16, 2009 [Page 51]
Internet-Draft YANG January 2009
7.5.1. Containers with Presence
YANG supports two styles of containers, those which exist only for
organizing the hierarchy of data nodes, and those whose presence in
the configuration has an explicit meaning.
In the first style, the container has no meaning of its own, existing
only to contain child nodes. This is the default style.
For example, the set of scrambling options for SONET interfaces may
be placed inside a "scrambling" container to enhance the organization
of the configuration hierarchy, and to keep these nodes together.
The "scrambling" node itself has no meaning, so removing the node
when it becomes empty relieves the user from the task of performing
this task.
In the second style, the presence of the container itself is
configuration data, representing a single bit of configuration data.
The container acts as both a configuration knob and a means of
organizing related configuration. These containers are explicitly
created and deleted.
YANG calls this style a "presence container" and they are indicated
using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into
the device using ssh, but can also contain any ssh-related
configuration knobs, such as connection rates or retry limits.
The "presence" statement (see Section 7.5.5) is used to give
semantics to the existence of the container in the data tree.
Bjorklund Expires July 16, 2009 [Page 52]
Internet-Draft YANG January 2009
7.5.2. The container's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| must | 7.5.3 | 0..n |
| presence | 7.5.5 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.5.3. The must Statement
The "must" statement, which is optional, takes as an argument a
string which contains an XPath expression. It is used to formally
declare a constraint on valid data. The constraint is enforced
according to the rules in Section 8.
When a data store is validated, all "must" constraints are
conceptually evaluated once for each corresponding instance in the
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
default value, its "must" statements are not evaluated.
All such constraints MUST evaluate to true for the data to be valid.
The XPath expression is conceptually evaluated in the following
context:
o The context node is the node in the data tree for which the "must"
statement is defined.
o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values.
Bjorklund Expires July 16, 2009 [Page 53]
Internet-Draft YANG January 2009
o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI.
o Elements without a namespace refer to nodes in the current module.
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 accessible data tree depends on the context node:
o If the context node represents configuration, the tree is the data
in one of the datastores <startup/>, <running/>, or <candidate/>.
The XPath root node has all top-level configuration data nodes in
all modules as children.
o If the context node represents state data, the tree is all state
data on the device, and the <running/> datastore. The XPath root
node has all top-level data nodes in all modules as children.
o If the context node represents notification content, the tree is
the notification XML instance document. The XPath root node has
the element representing the notification being defined as the
only child.
o If the context node represents RPC input parameters, the tree is
the RPC XML instance document. The XPath root node has the
element representing the RPC method being defined as the only
child.
o If the context node represents RPC output parameters, the tree is
the RPC reply instance document. The XPath root node has the
elements representing the RPC output parameters as children.
The result of the XPath expression is converted to a boolean value
using the standard XPath rules.
Note that since all leaf values in the data tree are conceptually
stored in their canonical form (see Section 7.6 and Section 7.7), any
XPath comparisons are done on the canonical value.
Also note that the XPath expression is conceptually evaluated. This
means that an implementation does not have to use an XPath evaluator
on the device. How the evaluation is done in practice is an
implementation decision.
Bjorklund Expires July 16, 2009 [Page 54]
Internet-Draft YANG January 2009
7.5.4. The must's Substatements
+---------------+---------+-------------+
| substatement | section | cardinality |
+---------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+
7.5.4.1. The error-message Statement
The "error-message" statement, which is optional, takes a string as
an argument. If the constraint evaluates to false, the string is
passed as <error-message> in the <rpc-error>.
7.5.4.2. The error-app-tag Statement
The "error-app-tag" statement, which is optional, takes a string as
an argument. If the constraint evaluates to false, the string is
passed as <error-app-tag> in the <rpc-error>.
7.5.4.3. Usage Example of must and error-message
container interface {
leaf ifType {
type enumeration {
enum ethernet;
enum atm;
}
}
leaf ifMTU {
type uint32;
}
must "ifType != 'ethernet' or " +
"(ifType = 'ethernet' and ifMTU = 1500)" {
error-message "An ethernet MTU must be 1500";
}
must "ifType != 'atm' or " +
"(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" {
error-message "An atm MTU must be 64 .. 17966";
}
}
Bjorklund Expires July 16, 2009 [Page 55]
Internet-Draft YANG January 2009
7.5.5. The presence Statement
The "presence" statement assigns a meaning to the presence of a
container in the data tree. It takes as an argument a string which
contains a textual description of what the node's presence means.
If a container has the "presence" statement, the container's
existence in the data tree carries some meaning. Otherwise, the
container is used to give some structure to the data, and it carries
no meaning by itself.
See Section 7.5.1 for additional information.
7.5.6. The container's Child Node Statements
Within a container, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used to define child nodes to
the container.
7.5.7. XML Encoding Rules
A container node is encoded as an XML element. The element's name is
the container's identifier, and its XML namespace is the module's XML
namespace.
The container's child nodes are encoded as subelements to the
container element, in the same order as they are defined within the
container statement.
A NETCONF server that replies to a <get> or <get-config> request MAY
choose not to send a container element if the container node does not
have the "presence" statement and no child nodes exist. Thus, a
client that receives an <rpc-reply> for a <get> or <get-config>
request, must be prepared to handle the case that a container node
without a presence statement is not present in the XML.
7.5.8. NETCONF <edit-config> Operations
When a NETCONF server processes an <edit-config> request, the
elements of procedure for the container node are:
If the operation is "merge" the node is created if it does not
exist.
If the operation is "replace" and the node exists, all child nodes
not present in the XML are deleted, and child nodes present in the
XML but not present in the datastore are created.
Bjorklund Expires July 16, 2009 [Page 56]
Internet-Draft YANG January 2009
If the operation is "create" the node is created if it does not
exist.
If the operation is "delete" the node is deleted if it exists.
If the container has a "presence" statement, it MAY be implicitly
created if it does not exist, even if the operation is "none".
If a container has a "presence" statement and the last child node
is deleted, the NETCONF server MAY delete the container.
7.5.9. Usage Example
Given the following container definition:
container system {
description "Contains various system parameters";
container services {
description "Configure externally available services";
container "ssh" {
presence "Enables SSH";
description "SSH service specific configuration";
// more leafs, containers and stuff here...
}
}
}
A corresponding XML encoding would look like this:
<system>
<services>
<ssh/>
</services>
</system>
Since the <ssh> element is present, ssh is enabled.
To delete a container with an <edit-config>:
Bjorklund Expires July 16, 2009 [Page 57]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<services>
<ssh nc:operation="delete"/>
</services>
</system>
</config>
</edit-config>
</rpc>
7.6. The leaf Statement
The "leaf" statement is used to define a leaf node in the schema
tree. It takes one argument, which is an identifier, followed by a
block of substatements that holds detailed leaf information.
A leaf node has a value, but no child nodes in the data tree.
Conceptually, the value in the data tree is always in the canonical
form (see Section 9.1).
A leaf node exists in zero or one instances in the data tree,
depending on the value of the "mandatory" statement.
The "leaf" statement is used to define a scalar variable of a
particular built-in or derived type.
If a leaf has a "default" statement, the leaf's default value is set
to the value of the "default" statement. Otherwise, if the leaf's
type has a default value, and the leaf is not mandatory, then the
leaf's default value is set to the type's default value. In all
other cases, the leaf does not have a default value.
If the leaf has a default value, the server MUST use this value
internally if no value is provided by the NETCONF client when the
instance is created.
Bjorklund Expires July 16, 2009 [Page 58]
Internet-Draft YANG January 2009
7.6.1. The leaf's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| config | 7.19.1 | 0..1 |
| default | 7.6.3 | 0..1 |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| mandatory | 7.6.4 | 0..1 |
| must | 7.5.3 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| type | 7.6.2 | 1 |
| units | 7.3.3 | 0..1 |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.6.2. The leaf's type Statement
The "type" statement, which MUST be present, takes as an argument the
name of an existing built-in or derived type. The optional
substatements specify restrictions on this type. See Section 7.4 for
details.
7.6.3. The leaf's default Statement
The "default" statement, which is optional, takes as an argument a
string which contains a default value for the leaf.
The value of the "default" statement MUST be valid according to the
type specified in the leaf's "type" statement.
The "default" statement MUST NOT be present on nodes where
"mandatory" is true.
7.6.4. The leaf's mandatory Statement
The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false". If not specified, the default is
"false".
If "mandatory" is "true", the node MUST exist if its parent node
exists. This constraint is enforced according to the rules in
Section 8.
Containers without a "presence" statement are ignored when performing
mandatory tests for leafs. A mandatory leaf within such a container
Bjorklund Expires July 16, 2009 [Page 59]
Internet-Draft YANG January 2009
is mandatory even if the container's data node does not exist.
7.6.5. XML Encoding Rules
A leaf node is encoded as an XML element. The element's name is the
leaf's identifier, and its XML namespace is the module's XML
namespace.
The value of the leaf node is encoded to XML according to the type,
and sent as character data in the element.
A NETCONF server that replies to a <get> or <get-config> request MAY
choose not to send the leaf element if its value is the default
value. Thus, a client that receives an <rpc-reply> for a <get> or
<get-config> request, MUST be prepared to handle the case that a leaf
node with a default value is not present in the XML. In this case,
the value used by the server is known to be the default value.
See Section 7.6.7 for an example.
7.6.6. NETCONF <edit-config> Operations
When a NETCONF server processes an <edit-config> request, the
elements of procedure for the leaf node are:
If the operation is "merge", the node is created if it does not
exist, and its value is set to the value found in the XML RPC
data.
If the operation is "replace", the node is created if it does not
exist, and its value is set to the value found in the XML RPC
data.
If the operation is "create" the node is created if it does not
exist.
If the operation is "delete" the node is deleted if it exists.
7.6.7. Usage Example
Given the following leaf statement:
leaf port {
type inet:port-number;
default 22;
description "The port which the SSH server listens to"
}
Bjorklund Expires July 16, 2009 [Page 60]
Internet-Draft YANG January 2009
A corresponding XML encoding:
<port>2022</port>
To create a leaf with an edit-config:
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<services>
<ssh>
<port>2022</port>
</ssh>
</services>
</system>
</config>
</edit-config>
</rpc>
7.7. The leaf-list Statement
Where the "leaf" statement is used to define a simple scalar variable
of a particular type, the "leaf-list" statement is used to define an
array of a particular type. The "leaf-list" statement takes one
argument, which is an identifier, followed by a block of
substatements that holds detailed leaf-list information.
The values in a leaf-list MUST be unique.
Conceptually, the values in the data tree are always in the canonical
form (see Section 9.1).
If the type referenced by the leaf-list has a default value, it has
no effect in the leaf-list.
7.7.1. Ordering
YANG supports two styles for ordering the entries within a list. In
many lists, the order of list entries does not impact the
implementation of the list's configuration, and the device is free to
sort the list entries in any reasonable order. The "description"
string for the list may suggest an order. YANG calls this style of
Bjorklund Expires July 16, 2009 [Page 61]
Internet-Draft YANG January 2009
list "system ordered" and they are indicated with the statement
"ordered-by system".
For example, a list of valid users would typically be sorted
alphabetically, since the order in which the users appeared in the
configuration would not impact the creation of those users' accounts.
In the other style of lists, the order of list entries matters for
the implementation of the list's configuration and the user is
responsible for ordering the entries, while the device maintains that
order. YANG calls this style of list "user ordered" and they are
indicated with the statement "ordered-by user".
For example, the order in which firewall filters entries are applied
to incoming traffic may affect how that traffic is filtered. The
user would need to decide if the filter entry that discards all TCP
traffic should be applied before or after the filter entry that
allows all traffic from trusted interfaces. The choice of order
would be crucial.
YANG provides a rich set of facilities within NETCONF's <edit-config>
operation which allow the order of list entries in user-ordered lists
to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned
before or after another specific entry.
The "ordered-by" statement is covered in Section 7.7.5.
Bjorklund Expires July 16, 2009 [Page 62]
Internet-Draft YANG January 2009
7.7.2. The leaf-list's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| config | 7.19.1 | 0..1 |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.3 | 0..1 |
| must | 7.5.3 | 0..n |
| ordered-by | 7.7.5 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| type | 7.4 | 1 |
| units | 7.3.3 | 0..1 |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.7.3. The min-elements Statement
The "min-elements" statement, which is optional, takes as an argument
a non-negative integer which puts a constraint on valid list entries.
A valid leaf-list or list always has at least min-elements entries.
If no "min-elements" statement is present, it defaults to zero.
The "min-elements" constraint is enforced according to the rules in
Section 8.
7.7.4. The max-elements Statement
The "max-elements" statement, which is optional, takes as an argument
a positive integer or the string "unbounded", which puts a constraint
on valid list entries. A valid leaf-list or list always has at most
max-elements entries.
If no "max-elements" statement is present, it defaults to
"unbounded".
The "max-elements" constraint is enforced according to the rules in
Section 8.
7.7.5. The ordered-by Statement
The "ordered-by" statement defines whether the order of entries
within a list are determined by the user or the system. The argument
is one of the strings "system" or "user". If not present, order
Bjorklund Expires July 16, 2009 [Page 63]
Internet-Draft YANG January 2009
defaults to "system".
This statement is ignored if the list represents state data, RPC
output parameters, or notification content.
See Section 7.7.1 for additional information.
7.7.5.1. ordered-by system
The entries in the list are sorted according to an unspecified order.
Thus an implementation is free to sort the entries in the most
appropriate order. An implementation SHOULD use the same order for
the same data, regardless of how the data were created. Using a
deterministic order will makes comparisons possible using simple
tools like "diff".
This is the default order.
7.7.5.2. ordered-by user
The entries in the list are sorted according to an order defined by
the user. This order is controlled by using special XML attributes
in the <edit-config> request. See Section 7.7.7 for details.
7.7.6. XML Encoding Rules
A leaf-list node is encoded as a series of XML elements. Each
element's name is the leaf-list's identifier, and its XML namespace
is the module's XML namespace.
The value of the leaf-list node is encoded to XML according to the
type, and sent as character data in the element.
See Section 7.7.8 for an example.
7.7.7. NETCONF <edit-config> operations
Leaf-list entries can be created and deleted, but not modified,
through <edit-config>, by using the "operation" attribute in the
leaf-list entry's XML element.
In an "ordered-by user" leaf-list, the attributes "insert" and
"value" in the YANG XML namespace (Section 5.3.1) can be used to
control where in the leaf-list the entry is inserted. These can be
used during "create" operations to insert a new leaf-list entry, or
during "merge" or "replace" operations to insert a new leaf-list
entry or move an existing one.
Bjorklund Expires July 16, 2009 [Page 64]
Internet-Draft YANG January 2009
The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "value"
attribute MUST also be used to specify an existing entry in the leaf-
list.
If no "insert" attribute is present in the "create" operation, it
defaults to "last".
In a <copy-config>, or an <edit-config> with a "replace" operation
which covers the entire leaf-list, the leaf-list order is the same as
the order of the XML elements in the request.
When a NETCONF server processes an <edit-config> request, the
elements of procedure for a leaf-list node are:
If the operation is "merge" or "replace" the leaf-list entry is
created if it does not exist.
If the operation is "create" the leaf-list entry is created if it
does not exist.
If the operation is "delete" the entry is deleted from the leaf-
list if it exists.
7.7.8. Usage Example
leaf-list allow-user {
type string;
description "A list of user name patterns to allow";
}
A corresponding XML encoding:
<allow-user>alice</allow-user>
<allow-user>bob</allow-user>
To create a new element in the list:
Bjorklund Expires July 16, 2009 [Page 65]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<services>
<ssh>
<allow-user>eric</allow-user>
</ssh>
</services>
</system>
</config>
</edit-config>
</rpc>
Given the following ordered-by user leaf-list:
leaf-list cipher {
type string;
ordered-by user;
description "A list of ciphers";
}
The following would be used to insert a new cipher "blowfish-cbc"
after "3des-cbc":
Bjorklund Expires July 16, 2009 [Page 66]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<services>
<ssh>
<cipher nc:operation="create"
yang:insert="after"
yang:value="3des-cbc">blowfish-cbc</cipher>
</ssh>
</services>
</system>
</config>
</edit-config>
</rpc>
7.8. The list Statement
The "list" statement is used to define interior nodes in the schema
tree. A list node may exist in multiple instances in the data tree.
Each such instance is known as a list entry. The "list" statement
takes one argument which is an identifier, followed by a block of
substatements that holds detailed list information.
A list entry is uniquely identified by the values of the list's keys.
A list is similar to a table where each list entry is a row in the
table.
7.8.1. The list's Substatements
Bjorklund Expires July 16, 2009 [Page 67]
Internet-Draft YANG January 2009
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n |
| key | 7.8.2 | 0..1 |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.3 | 0..1 |
| must | 7.5.3 | 0..n |
| ordered-by | 7.7.5 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n |
| unique | 7.8.3 | 0..n |
| uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.8.2. The list's key Statement
The "key" statement, which MUST be present if the list represents
configuration, and MAY be present otherwise, takes as an argument a
string which specifies a space separated list of leaf identifiers of
this list. A leaf identifier MUST NOT appear more than once in the
key. Each such leaf identifier MUST refer to a child leaf of the
list.
The combined values of all the leafs specified in the key are used to
uniquely identify a list entry. All key leafs MUST be given values
when a list entry is created. Thus, any default values in the key
leafs or their types are ignored. It also implies that any mandatory
statement in the key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived
type, except it MUST NOT be the built-in type "empty".
All key leafs in a list MUST have the same value for their "config"
as the list itself.
Bjorklund Expires July 16, 2009 [Page 68]
Internet-Draft YANG January 2009
The key string syntax is formally defined by the rule "key-arg" in
Section 12.
7.8.3. The lists's unique Statement
The "unique" statement is used to put constraints on valid list
entries. It takes as an argument a string which contains a space
separated list of schema node identifiers, which MUST be given in the
descendant form (see the rule "descendant-schema-nodeid" in
Section 12). Each such schema node identifier MUST refer to a leaf.
If one of the referenced leafs represents configuration data, then
all of the referenced leafs MUST represent configuration data.
The "unique" constraint specifies that the combined values of all the
leaf instances specified in the argument string, including leafs with
default values, MUST be unique within all list entry instances. The
constraint is enforced according to the rules in Section 8.
The unique string syntax is formally defined by the rule "unique-arg"
in Section 12.
7.8.3.1. Usage Example
With the following list:
list server {
key "name";
unique "ip port";
leaf name {
type string;
}
leaf ip {
type inet:ip-address;
}
leaf port {
type inet:port-number;
}
}
The following configuration is not valid:
Bjorklund Expires July 16, 2009 [Page 69]
Internet-Draft YANG January 2009
<server>
<name>smtp</name>
<ip>192.0.2.1</ip>
<port>25</port>
</server>
<server>
<name>http</name>
<ip>192.0.2.1</ip>
<port>25</port>
</server>
7.8.4. The list's Child Node Statements
Within a list, the "container", "leaf", "list", "leaf-list", "uses",
and "choice" statements can be used to define child nodes to the
list.
7.8.5. XML Encoding Rules
A list is encoded as a series of XML elements, one for each entry in
the list. Each element's name is the list's identifier, and its XML
namespace is the module's XML namespace.
The list's key nodes are encoded as subelements to the list's
identifier element, in the same order as they are defined within the
key statement.
The rest of the list's child nodes are encoded as subelements to the
list element, after the keys, in the same order as they are defined
within the list statement.
7.8.6. NETCONF <edit-config> operations
List entries can be created, deleted, replaced and modified through
<edit-config>, by using the "operation" attribute in the list's XML
element. In each case, the values of all keys are used to uniquely
identify a list entry. If all keys are not specified for a list
entry, a "missing-element" error is returned.
In an "ordered-by user" list, the attributes "insert" and "key" in
the YANG XML namespace (Section 5.3.1) can be used to control where
in the list the entry is inserted. These can be used during "create"
operations to insert a new list entry, or during "merge" or "replace"
operations to insert a new list entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "key"
Bjorklund Expires July 16, 2009 [Page 70]
Internet-Draft YANG January 2009
attribute MUST also be used, to specify an existing element in the
list. The value of the "key" attribute is the key predicates of the
full instance identifier (see Section 9.13) for the list entry.
If no "insert" attribute is present in the "create" operation, it
defaults to "last".
In a <copy-config>, or an <edit-config> with a "replace" operation
which covers the entire list, the list entry order is the same as the
order of the XML elements in the request.
7.8.7. Usage Example
Given the following list:
list user {
key "name";
config true;
description "This is a list of users in the system.";
leaf name {
type string;
}
leaf type {
type string;
}
leaf full-name {
type string;
}
}
A corresponding XML encoding:
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
</name>
To create a new user "barney":
Bjorklund Expires July 16, 2009 [Page 71]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<user nc:operation="create">
<name>barney</name>
<type>admin</type>
<full-name>Barney Rubble</full-name>
</user>
</system>
</config>
</edit-config>
</rpc>
To change the type of "fred" to "superuser":
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<user>
<name>fred</name>
<type>superuser</type>
</user>
</system>
</config>
</edit-config>
</rpc>
Given the following ordered-by user list:
Bjorklund Expires July 16, 2009 [Page 72]
Internet-Draft YANG January 2009
list user {
description "This is a list of users in the system.";
ordered-by user;
config true;
key "name";
leaf name {
type string;
}
leaf type {
type string;
}
leaf full-name {
type string;
}
}
The following would be used to insert a new user "barney" after the
user "fred":
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config"
xmlns:ex="http://example.com/schema/config">
<user nc:operation="create"
yang:insert="after"
yang:key="[ex:name='fred']">
<name>barney</name>
<type>admin</type>
<full-name>Barney Rubble</full-name>
</user>
</system>
</config>
</edit-config>
</rpc>
The following would be used to move the user "barney" before the user
"fred":
Bjorklund Expires July 16, 2009 [Page 73]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config"
xmlns:ex="http://example.com/schema/config">
<user nc:operation="merge"
yang:insert="before"
yang:key="[ex:name='fred']">
<name>barney</name>
</user>
</system>
</config>
</edit-config>
</rpc>
7.9. The choice Statement
The "choice" statement defines a set of alternatives, only one of
which may exist at any one time. The argument is an identifier,
followed by a block of substatements that holds detailed choice
information. The identifier is used to identify the choice node in
the schema tree. A choice node does not exist in the data tree.
A choice consists of a number of branches, defined with the "case"
substatement. Each branch contains a number of child nodes. The
nodes from at most one of the choice's branches exist at the same
time.
See Section 8.3.2 for additional information.
Bjorklund Expires July 16, 2009 [Page 74]
Internet-Draft YANG January 2009
7.9.1. The choice's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| case | 7.9.2 | 0..n |
| config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n |
| default | 7.9.3 | 0..1 |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| mandatory | 7.9.4 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.9.2. The choice's case Statement
The "case" statement is used to define branches of the choice. It
takes as an argument an identifier, followed by a block of
substatements that holds detailed case information.
The identifier is used to identify the case node in the schema tree.
A case node does not exist in the data tree.
Within a "case" statement, the "anyxml", "container", "leaf", "list",
"leaf-list", "uses", and "augment" statements can be used to define
child nodes to the case node. The identifiers of all these child
nodes MUST be unique within all cases in a choice. For example, the
following is illegal:
choice interface-type { // This example is illegal YANG
case a {
leaf ethernet { ... }
}
case b {
container ethernet { ...}
}
}
As a shorthand, the "case" statement can be omitted if the branch
contains a single "anyxml", "container", "leaf", "list", or "leaf-
list" statement. In this case, the identifier of the case node is
Bjorklund Expires July 16, 2009 [Page 75]
Internet-Draft YANG January 2009
the same as the identifier in the branch statement. The following
example:
choice interface-type {
container ethernet { ... }
}
is equivalent to:
choice interface-type {
case ethernet {
container ethernet { ... }
}
}
The case identifier MUST be unique within a choice.
7.9.2.1. The case's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.9.3. The choice's default Statement
The "default" statement indicates if a case should be considered as
the default if no child nodes from any of the choice's cases exists.
The argument is the identifier of the "case" statement. If the
"default" statement is missing, there is no default case.
The "default" statement MUST NOT be present on choices where
"mandatory" is true.
The default case is only important when considering the default
values of nodes under the cases. The default values for nodes under
Bjorklund Expires July 16, 2009 [Page 76]
Internet-Draft YANG January 2009
the default case are used if none of the nodes under any of the cases
are present.
There MUST NOT be any mandatory nodes (Section 3.1) directly under
the default case.
Default values for child nodes under a case are only used if one of
the nodes under that case is present, or if that case is the default
case. If none of the nodes under a case are present and the case is
not the default case, the default values of the cases' child nodes
are ignored.
In this example, the choice defaults to "interval", and the default
value will be used if none of "daily", "time-of-day", or "manual" are
present. If "daily" is present, the default value for "time-of-day"
will be used.
container transfer {
choice how {
default interval;
case interval {
leaf interval {
type uint16;
default 30;
units minutes;
}
}
case daily {
leaf daily {
type empty;
}
leaf time-of-day {
type string;
units 24-hour-clock;
default 1am;
}
}
case manual {
leaf manual {
type empty;
}
}
}
}
Bjorklund Expires July 16, 2009 [Page 77]
Internet-Draft YANG January 2009
7.9.4. The choice's mandatory Statement
The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false". If "mandatory" is "true", at least one
node from exactly one of the choice's case branches MUST exist. This
constraint is enforced according to the rules in Section 8.
If not specified, the default is "false".
7.9.5. XML Encoding Rules
The choice and case nodes are not visible in XML.
7.9.6. NETCONF <edit-config> operations
Since only one of the choices cases can be valid at any time, the
creation of a node from one case implicitly deletes all nodes from
all other cases. If an <edit-config> operation creates a node, the
NETCONF server will delete any existing nodes that are defined in
other cases inside the choice.
7.9.7. Usage Example
Given the following choice:
container protocol {
choice name {
case a {
leaf udp {
type empty;
}
}
case b {
leaf tcp {
type empty;
}
}
}
}
A corresponding XML encoding:
<protocol>
<tcp/>
</protocol>
To change the protocol from tcp to udp:
Bjorklund Expires July 16, 2009 [Page 78]
Internet-Draft YANG January 2009
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<protocol>
<udp nc:operation="create"/>
</protocol>
</system>
</config>
</edit-config>
</rpc>
7.10. The anyxml Statement
The "anyxml" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anyxml information.
The anyxml statement is used to represent an unknown chunk of XML.
No restrictions are placed on the XML. This can be useful in e.g.
RPC replies. An example is the <filter> parameter in the <get-
config> operation.
An anyxml node cannot be augmented.
Since the use of anyxml limits the manipulation of the content, it is
RECOMMENDED that the anyxml statement not be used to represent
configuration data.
Bjorklund Expires July 16, 2009 [Page 79]
Internet-Draft YANG January 2009
7.10.1. The anyxml's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| config | 7.19.1 | 0..1 |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| mandatory | 7.6.4 | 0..1 |
| must | 7.5.3 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.10.2. XML Encoding Rules
An anyxml node is encoded as an XML element. The element's name is
the anyxml's identifier, and its XML namespace is the module's XML
namespace. The value of the anyxml node is encoded as XML content of
this element.
Note that any prefixes used in the encoding are local to each
instance encoding. This means that the same XML may be encoded
differently by different implementations.
7.10.3. NETCONF <edit-config> operations
An anyxml node is treated as an opaque chunk of data. This data can
be modified in its entirety only.
Any "operation" attributes within the XML value of an anyxml node are
ignored by the NETCONF server.
When a NETCONF server processes an <edit-config> request, the
elements of procedure for the anyxml node are:
If the operation is "merge", the node is created if it does not
exist, and its value is set to the XML content of the anyxml node
found in the XML RPC data.
If the operation is "replace", the node is created if it does not
exist, and its value is set to the XML content of the anyxml node
found in the XML RPC data.
If the operation is "create" the node is created if it does not
exist, and its value is set to the XML content of the anyxml node
found in the XML RPC data.
Bjorklund Expires July 16, 2009 [Page 80]
Internet-Draft YANG January 2009
If the operation is "delete" the node is deleted if it exists.
7.10.4. Usage Example
Given the following anyxml statement:
anyxml data;
The following are two valid encodings of the same anyxml value:
<data xmlns:if="http://example.com/ns/interface">
<if:interface>
<if:ifIndex>1</if:ifIndex>
</if:interface>
</data>
<data>
<interface xmlns="http://example.com/ns/interface">
<ifIndex>1</ifIndex>
</interface>
</data>
7.11. The grouping Statement
The "grouping" statement is used to define a reusable block of nodes,
which may be used locally in the module, in modules which include it,
and by other modules which import from it, according to the rules in
Section 5.5. It takes one argument which is an identifier, followed
by a block of substatements that holds detailed grouping information.
The grouping statement is not a data definition statement and, as
such, does not define any nodes in the schema tree.
A grouping is like a "structure" or a "record" in conventional
programming languages.
Once a grouping is defined, it can be referenced in a "uses"
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
submodule, the grouping's identifier MUST be unique within the
module.
A grouping is more than just a mechanism for textual substitution,
but defines a collection of nodes. References from inside the
grouping are relative to the scope in which the grouping is defined,
not where it is used. Prefix mappings, type names, grouping names,
Bjorklund Expires July 16, 2009 [Page 81]
Internet-Draft YANG January 2009
and extension usage are evaluated in the hierarchy where the grouping
statement appears. For extensions, this means that extensions are
applied to the grouping node, not the use node.
7.11.1. The grouping's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
+--------------+---------+-------------+
7.11.2. Usage Example
import inet-types {
prefix "inet";
}
grouping address {
description "A reusable address group.";
leaf ip {
type inet:ip-address;
}
leaf port {
type inet:port-number;
}
}
7.12. The uses Statement
The "uses" statement is used to reference a "grouping" definition.
It takes one argument, which is the name of the grouping.
The effect of a "uses" reference to a grouping is that the nodes
defined by the grouping are copied into the current schema tree, and
then updated according to the refinement statements. Thus, the
Bjorklund Expires July 16, 2009 [Page 82]
Internet-Draft YANG January 2009
identifiers defined in the grouping are copied into the current
module's namespace, even if the grouping is imported from some other
module.
7.12.1. The uses's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| augment | 7.15 | 0..1 |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| refine | 7.12.2 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.12.2. The refine Statement
Some of the properties of each node in the grouping can be refined
with the "refine" statement. The argument is a a string which
identifies a node in the grouping. This node is called the refine's
target node. If a node in the grouping is not present as target node
of a refine statement, it is not refined, and thus used exactly as it
was defined in the grouping.
The argument string is a schema node identifier. The syntax is
formally defined by the rule "descendant-schema-nodeid" in
Section 12.
The following refinements can be done:
o A leaf or choice node may get a default value, or a new default
value if it already had one.
o Any node may get a specialized "description" string.
o Any node may get a specialized "reference" string.
o Any node may get a different "config" statement.
o A leaf or choice node may get a different "mandatory" statement.
o A container node may get a "presence" statement.
o A leaf, leaf-list, list or container node may get additional
"must" expressions.
Bjorklund Expires July 16, 2009 [Page 83]
Internet-Draft YANG January 2009
o A leaf-list or list node may get a different "min-elements" or
"max-elements" statement.
7.12.3. XML Encoding Rules
Each node in the grouping is encoded as if it was defined inline,
even if it is imported from another module with another XML
namespace.
7.12.4. Usage Example
To use the "address" grouping defined in Section 7.11.2 in a
definition of an HTTP server in some other module, we can do:
import acme-system {
prefix "acme";
}
container http-server {
leaf name {
type string;
}
uses acme:address;
}
A corresponding XML encoding:
<http-server>
<name>extern-web</name>
<ip>192.0.2.1</ip>
<port>80</port>
</http-server>
If port 80 should be the default for the HTTP server, default can be
added:
container http-server {
leaf name {
type string;
}
uses acme:address {
refine port {
default 80;
}
}
}
If we want to define a list of servers, and each server has the ip
Bjorklund Expires July 16, 2009 [Page 84]
Internet-Draft YANG January 2009
and port as keys, we can do:
list server {
key "ip port";
leaf name {
type string;
}
uses acme:address;
}
The following is an error:
container http-server {
uses acme:address;
leaf ip { // illegal - same identifier "ip" used twice
type string;
}
}
7.13. The rpc Statement
The "rpc" statement is used to define a NETCONF RPC method. It takes
one argument, which is an identifier, followed by a block of
substatements that holds detailed rpc information. This argument is
the name of the RPC, and is used as the element name directly under
the <rpc> element, as designated by the substitution group
"rpcOperation" in [RFC4741].
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.
Bjorklund Expires July 16, 2009 [Page 85]
Internet-Draft YANG January 2009
7.13.1. The rpc's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n |
| input | 7.13.2 | 0..1 |
| output | 7.13.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n |
+--------------+---------+-------------+
7.13.2. The input Statement
The "input" statement, which is optional, is used to define input
parameters to the RPC method. It does not take an argument. The
substatements to "input" defines nodes under the RPC's input node.
If a container in the input tree has a "presence" statement, the
container need not be present in a NETCONF RPC invocation.
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.
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
NETCONF RPC invocation.
If a "config" statement is present for any node in the input tree, it
is ignored.
Bjorklund Expires July 16, 2009 [Page 86]
Internet-Draft YANG January 2009
7.13.2.1. The input's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n |
+--------------+---------+-------------+
7.13.3. The output Statement
The "output" statement, which is optional, is used to define output
parameters to the RPC method. It does not take an argument. The
substatements to "output" defines nodes under the RPC's output node.
If a container in the output tree has a "presence" statement, the
container need not be present in a NETCONF RPC reply
If a leaf in the output tree has a "mandatory" statement with the
value "true", the leaf MUST be present in a NETCONF RPC reply.
If a leaf in the output tree has a default value, the NETCONF client
MUST internally use this default if the leaf is not present in a
NETCONF RPC reply.
If a "config" statement is present for any node in the output tree,
it is ignored.
Bjorklund Expires July 16, 2009 [Page 87]
Internet-Draft YANG January 2009
7.13.3.1. The output's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| grouping | 7.11 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| typedef | 7.3 | 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;
}
}
}
Bjorklund Expires July 16, 2009 [Page 88]
Internet-Draft YANG January 2009
}
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
The "notification" statement is used to define a NETCONF
notification. It takes one argument, which is an identifier,
followed by a block of substatements that holds detailed notification
information. The notification "statement" defines a notification
node in the schema tree.
If a container in the notification tree has a "presence" statement,
the container need not be present in a NETCONF notification.
If a leaf in the notification tree has a "mandatory" statement with
the value "true", the leaf MUST be present in a NETCONF notification.
If a leaf in the notification tree has a default value, the NETCONF
server MUST internally use this default if the leaf is not present in
a NETCONF notification.
If a "config" statement is present for any node in the notification
tree, it is ignored.
Bjorklund Expires July 16, 2009 [Page 89]
Internet-Draft YANG January 2009
7.14.1. The notification's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| typedef | 7.3 | 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:
Bjorklund Expires July 16, 2009 [Page 90]
Internet-Draft YANG January 2009
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
The "augment" statement allows a module or submodule to add to the
schema tree defined in another module or submodule. The argument 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
container, list, choice, case, input, output, or notification node.
It is augmented with the nodes defined in the substatements that
follow the "augment" statement.
The argument string is a schema node identifier. The syntax is
formally defined by the rule "augment-arg" in Section 12. If the
"augment" statement is on the top-level in a module or submodule, the
absolute form (defined by the rule "absolute-schema-nodeid" in
Section 12) of a schema node identifier MUST be used. If the
"augment" statement is in a "uses" statement, the descendant form
(defined by the rule "descendant-schema-nodeid" in Section 12) MUST
be used.
Bjorklund Expires July 16, 2009 [Page 91]
Internet-Draft YANG January 2009
The syntax for a schema node identifier is a subset of the XPath
syntax. It is an absolute or relative XPath location path in
abbreviated syntax, where axes and predicates are not permitted.
If the target node is a container, list, case, input, output, or
notification node, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used within the "augment"
statement.
If the target node is a choice node, the "case" statement can be used
within the "augment" statement.
If the target node is in another module, then nodes added by the
augmentation MUST NOT be mandatory nodes (see Section 3.1).
7.15.1. The augment's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n |
| case | 7.9.2 | 0..n |
| choice | 7.9 | 0..n |
| container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 |
+--------------+---------+-------------+
7.15.2. XML Encoding Rules
All data nodes defined in the "augment" statement are defined as XML
elements in the XML namespace of the module where the "augment" is
specified.
When a node is augmented, the augmented child nodes are encoded after
all normal child nodes. If the node is augmented more than once, the
blocks of augmented child nodes are sorted (in alphanumeric order)
according to their namespace URI and name of the first child node in
each block.
Bjorklund Expires July 16, 2009 [Page 92]
Internet-Draft YANG January 2009
7.15.3. Usage Example
In namespace http://example.com/schema/interfaces, we have:
container interfaces {
list ifEntry {
key "ifIndex";
leaf ifIndex {
type uint32;
}
leaf ifDescr {
type string;
}
leaf ifType {
type iana:IfType;
}
leaf ifMtu {
type int32;
}
}
}
Then in namespace http://example.com/schema/ds0, we have:
import interface-module {
prefix "if";
}
augment "/if:interfaces/if:ifEntry" {
when "if:ifType='ds0'";
leaf ds0ChannelNumber {
type ChannelNumber;
}
}
A corresponding XML encoding:
Bjorklund Expires July 16, 2009 [Page 93]
Internet-Draft YANG January 2009
<interfaces xmlns="http://example.com/schema/interfaces"
xmlns:ds0="http://example.com/schema/ds0"
<ifEntry>
<ifIndex>1</ifIndex>
<ifDescr>Flintstone Inc Ethernet A562</ifDescr>
<ifType>ethernetCsmacd</ifType>
<ifMtu>1500</ifMtu>
</ifEntry>
<ifEntry>
<ifIndex>2</ifIndex>
<ifDescr>Flintstone Inc DS0</ifDescr>
<ifType>ds0</ifType>
<ds0:ds0ChannelNumber>1</ds0:ds0ChannelNumber>
</ifEntry>
</interfaces>
As another example, suppose we have the choice defined in
Section 7.9.7. The following construct can be used to extend the
protocol definition:
augment /ex:system/ex:protocol/ex:name {
case c {
leaf smtp {
type empty;
}
}
}
A corresponding XML encoding:
<ex:system>
<ex:protocol>
<ex:tcp/>
</ex:protocol>
</ex:system>
or
<ex:system>
<ex:protocol>
<other:smtp/>
</ex:protocol>
</ex:system>
Bjorklund Expires July 16, 2009 [Page 94]
Internet-Draft YANG January 2009
7.16. The identity Statement
The "identity" statement is used to define a new globally unique,
abstract and untyped identity. Its only purpose is to denote its
name, semantics, and existence. An identity can be defined either
from scratch or derived from a base identity. The identity's
argument is an identifier that is the name of the identity. It is
followed by a block of substatements that holds detailed identity
information.
The built-in datatype "identityref" (see Section 9.10) can be used to
reference identities within a data model.
7.16.1. The identity's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| base | 7.16.2 | 0..1 |
| description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
+--------------+---------+-------------+
7.16.2. The base Statement
The base statement, which is optional, takes as an argument a string
which is the name of an existing identity, from which the new
identity is derived. If no base statement is present, the identity
is defined from scratch.
If a prefix is present on the base name, it refers to an identity
defined in the module which was imported with that prefix, or the
local module if the prefix matches the local module's prefix.
Otherwise an identity with the matching name MUST be defined in the
current module or an included submodule.
Since submodules cannot include the parent module, any identities in
the module which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the
definition of the identity.
An identity MUST NOT reference itself, neither directly nor
indirectly through a chain of other identities.
Bjorklund Expires July 16, 2009 [Page 95]
Internet-Draft YANG January 2009
7.16.3. Usage Example
module crypto-base {
namespace "http://example.com/crypto-base";
prefix "crypto";
identity crypto-alg {
description
"Base identity from which all crypto algorithms
are derived.";
}
}
module des {
namespace "http://example.com/des";
prefix "des";
import "crypto-base" {
prefix "crypto";
}
identity des {
base "crypto:crypto-alg";
description "DES crypto algorithm";
}
identity des3 {
base "crypto:crypto-alg";
description "Triple DES crypto algorithm";
}
}
7.17. The extension Statement
The "extension" statement allows the definition of new statements
within the YANG language. This new statement definition can be
imported and used by other modules.
The statement's argument is an identifier that is the new keyword for
the extension and must be followed by a block of substatements that
holds detailed extension information. The purpose of the extension
statement is to define a keyword, so that it can be imported and used
by other modules.
The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the
extension, and an optional block of substatements. The statement's
name is created by combining the the prefix of the module in which
Bjorklund Expires July 16, 2009 [Page 96]
Internet-Draft YANG January 2009
the extension was defined, a colon (":"), and the extension's
keyword, with no interleaving whitespace. The substatements of an
extension are defined by the extension, using some mechanism outside
the scope of this specification. Syntactically, the substatements
MUST be core YANG statements, or also defined using "extension"
statements. Core YANG statements in extensions MUST follow the
syntactical rules in Section 12.
7.17.1. The extension's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| argument | 7.17.2 | 0..1 |
| description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
+--------------+---------+-------------+
7.17.2. The argument Statement
The "argument" statement, which is optional, takes as an argument a
string which is the name of the argument to the keyword. If no
argument statement is present, the keyword expects no argument when
it is used.
The argument's name is used in the YIN mapping, where it is used as
an XML attribute or element name, depending on the argument's text
statement.
7.17.2.1. The argument's Substatements
+--------------+----------+-------------+
| substatement | section | cardinality |
+--------------+----------+-------------+
| yin-element | 7.17.2.2 | 0..1 |
+--------------+----------+-------------+
7.17.2.2. The yin-element Statement
The "yin-element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the
argument is mapped to an XML element in YIN or to an XML attribute.
(see Section 11).
If no "yin-element" statement is present, it defaults to "false".
Bjorklund Expires July 16, 2009 [Page 97]
Internet-Draft YANG January 2009
7.17.3. Usage Example
To define an extension:
module my-extensions {
...
extension c-define {
description
"Takes as argument a name string.
Makes the code generator use the given name in the
#define.";
argument "name";
}
}
To use the extension:
module my-interfaces {
...
import my-extensions {
prefix "myext";
}
...
container interfaces {
...
myext:c-define "MY_INTERFACES";
}
}
7.18. Conformance-related Statements
This section defines statements related to conformance, as described
in Section 5.6.
7.18.1. The feature Statement
The "feature" statement is used to define a mechanism by which
portions of the schema are marked as conditional. A feature name is
defined that can later be referenced using the "if-feature" statement
(see Section 7.18.2). Schema nodes tagged with a feature are ignored
unless the device supports the given feature. This allows portions
of the YANG module to be conditional based on conditions on the
device. The model can represent the abilities of the device within
the model, giving a richer model that allows for differing device
abilities and roles.
Bjorklund Expires July 16, 2009 [Page 98]
Internet-Draft YANG January 2009
The argument to the "feature" statement is the name of the new
feature, and follows the rules for identifiers in Section 6.2. This
name is used by the "if-feature" statement to tie the schema nodes to
the feature.
In this example, a feature called "local-storage" represents the
ability for a device to store syslog messages on local storage of
some sort. This feature is used to make the "local-storage-limit"
leaf conditional on the presence of some sort of local-storage. If
the device does not report that it supports this feature, the local-
storage-limit node is not supported.
module my-syslog {
...
feature local-storage {
description
"This feature means the device supports local
storage (memory, flash or disk) that can be used to
store syslog messages.";
}
container syslog {
leaf local-storage-limit {
if-feature local-storage;
type uint64;
units "kilobyte";
config false;
description
"The amount of local storage that can be
used to hold syslog messages.";
}
}
}
The "if-feature" statement can be used in many places within the YANG
syntax. Definitions tagged with "if-feature" are ignored when the
device does not support that feature.
A feature MUST NOT reference itself, neither directly nor indirectly
through a chain of other features.
Bjorklund Expires July 16, 2009 [Page 99]
Internet-Draft YANG January 2009
7.18.1.1. The feature's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n |
| status | 7.19.2 | 0..1 |
| reference | 7.19.4 | 0..1 |
+--------------+---------+-------------+
7.18.2. The if-feature Statement
The "if-feature" statement is used to mark portions of the model as
conditional. The argument is the name of a feature, as defined by a
"feature" statement. If a prefix is present on the feature name, it
refers to a feature defined the module which was imported with that
prefix, or the local module if the prefix matches the local module's
prefix. Otherwise a feature with the matching name MUST be defined
in the current module or an included submodule.
Since submodules cannot include the parent module, any features in
the module which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the
definition of the feature.
7.18.3. The deviation Statement
The deviation statement defines a hierarchy of the module which the
device does not implement faithfully. The argument is a string that
identifies the node in the schema tree where a deviation from the
module occurs. This node is called the deviation's target node. The
contents of the deviation statement give details about the deviation.
The argument's syntax is formally defined by the rule "deviation-arg"
in Section 12.
Deviations define the way a device or class of devices deviate from
the standard. This means that deviations MUST never be part of a
published standard, since they are the mechanism for learning how
implementations vary from the standards.
Device deviations are strongly discouraged and SHOULD only be used as
a last resort. Telling the application how a device fails to follow
the standard is no substitute for implementing the standard
correctly.
However in some cases a particular device may not have the hardware
Bjorklund Expires July 16, 2009 [Page 100]
Internet-Draft YANG January 2009
or software ability to support parts of a standard module. When this
occurs, the device makes a choice to treat attempts to configure
unsupported parts of the module as either an error that is reported
back to the unsuspecting application, or ignore that incoming
requests. Neither choice is acceptable.
Instead, YANG allows devices to document portions of the base module
which are not supported or supported but with different syntax, by
using the "deviation" statement.
7.18.3.1. The deviation's Substatements
+--------------+----------+-------------+
| substatement | section | cardinality |
+--------------+----------+-------------+
| description | 7.19.3 | 0..1 |
| deviate | 7.18.3.2 | 0..n |
| reference | 7.19.4 | 0..1 |
+--------------+----------+-------------+
7.18.3.2. The deviate Statement
The "deviate" statement defines how the device's implementation of
the target node deviates from its original definition. The argument
is one of the strings "not-supported", "add", "replace", or "delete".
The argument "not-supported" indicates that the target node is not
implemented by this device.
The argument "add" adds properties to the target node. The
properties to add are identified as a substatement to the "deviate"
statement. If the property can only appear once, the property MUST
NOT exist in the target node.
The argument "replace" replaces properties of the target node. The
properties to replace are identified by substatements to the
"deviate" statement. The property to replace MUST exist in the
target node.
The argument "delete" deletes properties from the target node. The
properties to delete are identified by substatement to "delete". The
substatement's keyword MUST match a corresponding keyword in the
target node, and the argument's string MUST be equal to the
corresponding keyword's argument string in the target node.
Bjorklund Expires July 16, 2009 [Page 101]
Internet-Draft YANG January 2009
The deviates's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| config | 7.19.1 | 0..1 |
| default | 7.6.3 | 0..1 |
| mandatory | 7.6.4 | 0..1 |
| max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.3 | 0..1 |
| must | 7.5.3 | 0..n |
| type | 7.4 | 0..1 |
| unique | 7.8.3 | 0..n |
| units | 7.3.3 | 0..1 |
+--------------+---------+-------------+
7.18.3.3. Usage Example
In this example, the device is informing client applications that it
does not support the old RFC867-style "daytime" service.
deviation /base:system/base:daytime {
deviate not-supported;
}
The following example sets a device-specific default value to a leaf
that does not have a default value defined:
deviation /base:system/base:user/base:type {
deviate add {
default "admin"; // new users are 'admin' by default
}
}
In this example, the device limits the number of name servers to 3:
deviation /base:system/base:name-server {
deviate replace {
max-elements 3;
}
}
If the original definition is:
container system {
must "daytime or time";
...
}
Bjorklund Expires July 16, 2009 [Page 102]
Internet-Draft YANG January 2009
a device might remove this must constraint by doing:
deviation "/base:system" {
deviate delete {
must "daytime or time";
}
}
7.19. Common Statements
This section defines sub-statements common to several other
statements.
7.19.1. The config Statement
The "config" statement takes as an argument the string "true" or
"false". If "config" is "true", the definition represents
configuration, and will be part of the reply to a <get-config>
request, and may be sent in a <copy-config> or <edit-config> request.
If "config" is "false", it represents state data, and will be part of
the reply to a <get>, but not to a <get-config> request.
If "config" is not specified, the default is the same as the parent
node's (in the data model) "config" value. If the top node does not
specify a "config" statement, the default is "true".
If a node has "config" "false", no node underneath it can have
"config" set to "true".
7.19.2. The status Statement
The "status" statement takes as an argument one of the strings
"current", "deprecated", or "obsolete".
o "current" means that the definition is current and valid.
o "deprecated" indicates an obsolete definition, but it permits new/
continued implementation in order to foster interoperability with
older/existing implementations.
o "obsolete" means the definition is obsolete and SHOULD NOT be
implemented and/or can be removed if previously implemented.
If no status is specified, the default is "current".
If a definition is "current", it MUST NOT reference a "deprecated" or
"obsolete" definition within the same module.
Bjorklund Expires July 16, 2009 [Page 103]
Internet-Draft YANG January 2009
If a definition is "deprecated", it MUST NOT reference an "obsolete"
definition within the same module.
7.19.3. The description Statement
The "description" statement takes as an argument a string which
contains a high-level textual description of this definition.
7.19.4. The reference Statement
The "reference" statement takes as an argument a string which is used
to specify a textual cross-reference to an external document, either
another module which defines related management information, or a
document which provides additional information relevant to this
definition.
7.19.5. The when Statement
The "when" statement allows a data definition statement to be
conditional, with the node(s) defined by the data definition
statement only being valid when a specific criteria is satisfied.
The statement's argument is an XPath expression, which is used to
formally specify this criteria. If the XPath expression conceptually
evaluates to "true" for a particular instance, then the nodes defined
by the data definition statement are valid, otherwise they are not.
See Section 8.3.2 for additional information.
The XPath expression is conceptually evaluated in the following
context:
o If the "when" statement is a child of an "augment" statement, then
the context node is the augment's target node in the data tree, if
the target node is a data node. Otherwise, the context node is
the closest ancestor node to the target node which is also a data
node.
o If the "when" statement is a child of a "choice" or "case"
statement, then the context node is the closest ancestor node to
the "choice" or "case" node which is also a data node.
o If the "when" statement is a child of any other data definition
statement, the context node is the data definition's node in the
data tree.
o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values.
Bjorklund Expires July 16, 2009 [Page 104]
Internet-Draft YANG January 2009
o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI.
o Elements without a namespace refer to nodes in the current module.
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 accessible data tree depends on the context node:
o If the context node represents configuration, the tree is the data
in one of the datastores <startup/>, <running/>, or <candidate/>.
The XPath root node has all top-level configuration data nodes in
all modules as children.
o If the context node represents state data, the tree is all state
data on the device, and the <running/> datastore. The XPath root
node has all top-level data nodes in all modules as children.
o If the context node represents notification content, the tree is
the notification XML instance document. The XPath root node has
the element representing the notification being defined as the
only child.
o If the context node represents RPC input parameters, the tree is
the RPC XML instance document. The XPath root node has the
element representing the RPC method being defined as the only
child.
o If the context node represents RPC output parameters, the tree is
the RPC reply instance document. The XPath root node has the
elements representing the RPC output parameters as children.
The result of the XPath expression is converted to a boolean value
using the standard XPath rules.
Note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator on the
device. The augment can very well be implemented with specially
written code.
Bjorklund Expires July 16, 2009 [Page 105]
Internet-Draft YANG January 2009
8. Constraints
8.1. Constraints on Data
Several YANG statements define constraints on valid data. These
constraints are enforced in different ways, depending on what type of
data the statement defines.
o If the constraint is defined on configuration data, it MUST be
true in a valid configuration data tree.
o If the constraint is defined on state data, it MUST be true in a
reply to the <get> command.
o If the constraint is defined on notification content, it MUST be
true in any notification instance.
o If the constraint is defined on RPC input parameters, it MUST be
true in an invocation of the RPC method.
o If the constraint is defined on RPC output parameters, it MUST be
true in the RPC reply.
8.2. Hierarchy of Constraints
Conditions on parent nodes affect constraints on child nodes as a
natural consequence of the hierarchy of nodes. "must" and "mandatory"
constraints are not enforced if the parent node has a "when" or "if-
feature" property that is not satisfied on the current device.
In this example, the mandatory constraints on the "longitude" leaf is
not enforced on devices that lack the the "has-gps" feature:
container location {
if-feature has-gps;
leaf longitude {
mandatory true;
...
}
}
8.3. Constraint Enforcement Model
For configuration data, there are three windows when constraints can
be enforced:
Bjorklund Expires July 16, 2009 [Page 106]
Internet-Draft YANG January 2009
o during parsing of RPC payloads
o during processing of NETCONF operations
o during validation
Each of these scenarios are considered in the following sections.
8.3.1. Payload Parsing
When content arrives in RPC payloads, it MUST be well-formed and
valid XML, following the hierarchy and content rules defined by the
set of models the device implements.
o Leaf data values MUST match the type constraints for those leafs,
including those defined in the type's range, length, and pattern
properties.
o Key data MUST be present for all list instances.
o Only data for a single case MUST be present for any choices.
o Data for nodes tagged with "if-feature" MUST NOT be present if the
feature is not supported by the device.
o Data for nodes tagged with "when" MUST NOT be present if the
condition does not evaluate to "true".
o For insert handling, the value for the attributes "before" and
"after" MUST be valid for the type of the appropriate key leafs.
o The attributes "before" and "after" MUST NOT appear for lists
whose "ordered-by" property is "system".
8.3.2. NETCONF <edit-config> Processing
After the incoming data is parsed, the NETCONF server performs the
<edit-config> operation by applying the data to the configuration
datastore. During this processing the following errors MUST be
detected:
o Delete requests for non-existent data.
o Create requests for existent data.
o Insert requests with "before" or "after" parameters which do not
exist.
Bjorklund Expires July 16, 2009 [Page 107]
Internet-Draft YANG January 2009
During <edit-config> processing:
o If the NETCONF operation creates data nodes under a "choice", any
existing nodes from other "case" branches are deleted by the
server.
o If the NETCONF operation modifies a data node such that any node's
"when" expression becomes false, then that node is deleted by the
server.
8.3.3. Validation
When datastore processing is complete, the final contents MUST obey
all validation constraints. This validation processing is performed
at differing time according to the datastore. If the datastore is
<running/> or <startup/>, these constraints MUST be enforced at the
end of the <edit-config> or <copy-config> operation. If the
datastore is <candidate>, the constraint enforcement is delayed until
a <commit> or <validate> operation.
o Any "must" constraints MUST evaluate to "true".
o Any referential integrity constraints defined via the "path"
statement MUST be satisfied.
o Any "unique" constraints on lists MUST be satisfied.
o The "min-elements" and "max-elements" constraints are enforced for
lists and leaf-lists.
Bjorklund Expires July 16, 2009 [Page 108]
Internet-Draft YANG January 2009
9. Built-in Types
YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special
requirements from the management information model.
Additional types may be defined, derived from those built-in types or
from other derived types. Derived types may use subtyping to
formally restrict the set of possible values.
The different built-in types and their derived types allow different
kinds of subtyping, namely length and regular expression restrictions
of strings (Section 9.4.4, Section 9.4.6) and range restrictions of
numeric types (Section 9.2.4).
The lexicographic representation of a value of a certain type is used
in the XML encoding over NETCONF, and when specifying default values
in a YANG module.
9.1. Canonical representation
For most types, there is a single canonical representation of the
type's values. Some types allow multiple lexicographic
representations of the same value, for example the positive integer
"17" can be represented as "+17" or "17".
When NETCONF servers sends data, it MUST be in the canonical form.
Some types have a lexical representation that depends on the XML
context in which they occur. These types do not have a canonical
form.
9.2. The Integer Built-in Types
The integer built-in types are int8, int16, int32, int64, uint8,
uint16, uint32, and uint64. They represent signed and unsigned
integers of different sizes:
int8 represents integer values between -128 and 127, inclusively.
int16 represents integer values between -32768 and 32767,
inclusively.
int32 represents integer values between -2147483648 and 2147483647,
inclusively.
Bjorklund Expires July 16, 2009 [Page 109]
Internet-Draft YANG January 2009
int64 represents integer values between -9223372036854775808 and
9223372036854775807, inclusively.
uint8 represents integer values between 0 and 255, inclusively.
uint16 represents integer values between 0 and 65535, inclusively.
uint32 represents integer values between 0 and 4294967295,
inclusively.
uint64 represents integer values between 0 and 18446744073709551615,
inclusively.
9.2.1. Lexicographic Representation
An integer value is lexicographically represented as an optional sign
("+" or "-"), followed by a sequence of decimal digits. If no sign
is specified, "+" is assumed.
For convenience, when specifying a default value for an integer in a
YANG module, an alternative lexicographic representation can be used,
which represents the value in a hexadecimal or octal notation. The
hexadecimal notation consists of an optional sign ("+" or "-"), the
characters "0x" followed a number of hexadecimal digits, where
letters may be upper- or lowercase. The octal notation consists of
an optional sign ("+" or "-"), the character "0" followed a number of
octal digits.
Note that if a default value in a YANG module has a leading zero
("0"), it is interpreted as an octal number. In the XML encoding, an
integer is always interpreted as a decimal number, and leading zeros
are allowed.
Examples:
// legal values
+4711 // legal positive value
4711 // legal positive value
-123 // legal negative value
0xf00f // legal positive hexadecimal value
-0xf // legal negative hexadecimal value
052 // legal positive octal value
// illegal values
- 1 // illegal intermediate space
Bjorklund Expires July 16, 2009 [Page 110]
Internet-Draft YANG January 2009
9.2.2. Canonical Form
The canonical form of a positive integer does not include the sign
"+". Leading zeros are prohibited. The value zero is represented as
"0".
9.2.3. Restrictions
All integer types can be restricted with the "range" statement
(Section 9.2.4).
9.2.4. The range Statement
The "range" statement, which is an optional substatement to the
"type" statement, takes as an argument a range expression string. It
is used to restrict integer and floating point built-in types, or
types derived from those.
A range consists of an explicit value, or a lower inclusive bound,
two consecutive dots "..", and an upper inclusive bound. Multiple
values or ranges can be given, separated by "|". If multiple values
or ranges are given they all MUST be disjoint and MUST be in
ascending order. If a value restriction is applied to an already
restricted type, the new restriction MUST be equal or more limiting,
that is raising the lower bounds, reducing the upper bounds, removing
explicit values or ranges, or splitting ranges into multiple ranges
with intermediate gaps. Each explicit value and range boundary value
given in the range expression MUST match the type being restricted,
or be one of the special values "min" or "max". "min" and "max" means
the minimum and maximum value accepted for the type being restricted,
respectively.
The range expression syntax is formally defined by the rule "range-
arg" in Section 12.
9.2.4.1. The range's Substatements
+---------------+---------+-------------+
| substatement | section | cardinality |
+---------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+
Bjorklund Expires July 16, 2009 [Page 111]
Internet-Draft YANG January 2009
9.2.5. Usage Example
typedef my-base-int32-type {
type int32 {
range "1..4 | 10..20";
}
}
type my-base-int32-type {
// legal range restriction
range "11..max"; // 11..20
}
type my-base-int32-type {
// illegal range restriction
range "11..100";
}
9.3. The Floating Point Built-in Types
The floating point built-in types are float32 and float64. They
represent floating point values of single and double precision as
defined in [IEEE.754]. Special values are positive and negative
infinity, and not-a-number.
9.3.1. Lexicographic Representation
A floating point value is lexicographically represented as consisting
of a decimal mantissa followed, optionally, by the character "E" or
"e", followed by an integer exponent. The special values positive
and negative infinity and not-a-number have lexical representations
INF, -INF and NaN, respectively. The minimal value accepted for a
float is -INF, and the maximal value accepted for a float is INF.
9.3.2. Canonical Form
[Editor's Note: TBD]
9.3.3. Restrictions
All floating point types can be restricted with the "range" statement
(Section 9.2.4).
Bjorklund Expires July 16, 2009 [Page 112]
Internet-Draft YANG January 2009
9.3.4. Usage Example
type float32 {
range "1..4.5 | 10 | 20..INF";
}
is equivalent to
type float32 {
range "1..4.5 | 10 | 20..max";
}
9.4. The string Built-in Type
The string built-in type represents human readable strings in YANG.
Legal characters are tab, carriage return, line feed, and the legal
characters of Unicode and ISO/IEC 10646 [ISO.10646]:
// any Unicode character, excluding the surrogate blocks,
// FFFE, and FFFF.
string = *char
char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
%x10000-10FFFF
9.4.1. Lexicographic Representation
A string value is lexicographically represented as character data in
the XML encoding.
9.4.2. Canonical Form
The canonical form is the same as the lexicographical representation.
No Unicode normalization is performed of string values.
9.4.3. Restrictions
A string can be restricted with the "length" (Section 9.4.4) and
"pattern" (Section 9.4.6) statements.
9.4.4. The length Statement
The "length" statement, which is an optional substatement to the
"type" statement, takes as an argument a length expression string.
It is used to restrict the built-in type "string", or types derived
from "string".
A "length" statement restricts the number of characters in the
string.
Bjorklund Expires July 16, 2009 [Page 113]
Internet-Draft YANG January 2009
A length range consists of an explicit value, or a lower bound, two
consecutive dots "..", and an upper bound. Multiple values or ranges
can be given, separated by "|". Length restricting values MUST NOT
be negative. If multiple values or ranges are given, they all MUST
be disjoint and MUST be in ascending order. If a length restriction
is applied to an already length restricted type, the new restriction
MUST be equal or more limiting, that is, raising the lower bounds,
reducing the upper bounds, removing explicit length values or ranges,
or splitting ranges into multiple ranges with intermediate gaps. A
length value is a non-negative integer, or one of the special values
"min" or "max". "min" and "max" means the minimum and maximum length
accepted for the type being restricted, respectively. An
implementation is not required to support a length value larger than
18446744073709551615.
The length expression syntax is formally defined by the rule "length-
arg" in Section 12.
9.4.4.1. The length's Substatements
+---------------+---------+-------------+
| substatement | section | cardinality |
+---------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+
9.4.5. 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";
}
Bjorklund Expires July 16, 2009 [Page 114]
Internet-Draft YANG January 2009
9.4.6. The pattern Statement
The "pattern" statement, which is an optional substatement to the
"type" statement, takes as an argument a regular expression string,
as defined in [XSD-TYPES]. It is used to restrict the built-in type
"string", or types derived from "string", to values that completely
matches the pattern.
If the type has multiple "pattern" statements, the expressions are
AND:ed together, i.e. all such expressions have to match.
9.4.6.1. The pattern's Substatements
+---------------+---------+-------------+
| substatement | section | cardinality |
+---------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+
9.4.7. Usage Example
With the following type:
type string {
length "0..4";
pattern "[0-9a-fA-F]*";
}
the following strings match:
AB // legal
9A00 // legal
and the following strings do not match:
00ABAB // illegal
xx00 // illegal
9.5. The boolean Built-in Type
The boolean built-in type represents a boolean value.
Bjorklund Expires July 16, 2009 [Page 115]
Internet-Draft YANG January 2009
9.5.1. Lexicographic Representation
The lexicographical representation of a boolean value is the strings
"true" and "false".
9.5.2. Restrictions
A boolean cannot be restricted.
9.6. The enumeration Built-in Type
The enumeration built-in type represents values from a set of
assigned names.
9.6.1. Lexicographic Representation
The lexicographical representation of an enumeration value is the
assigned name string.
9.6.2. Canonical Form
The canonical form is the assigned name string.
9.6.3. Restrictions
An enumeration cannot be restricted.
9.6.4. The enum Statement
The "enum" statement, which is a substatement to the "type"
statement, MUST be present if the type is "enumeration". It is
repeatedly used to specify each assigned name of an enumeration type.
It takes as an argument a string which is the assigned name. The
string MUST NOT be empty and MUST NOT have any leading or trailing
whitespace characters. The use of control codes SHOULD be avoided.
The statement is optionally followed by a block of substatements
which holds detailed enum information.
All assigned names in an enumeration MUST be unique.
Bjorklund Expires July 16, 2009 [Page 116]
Internet-Draft YANG January 2009
9.6.4.1. The enum's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| value | 9.6.4.2 | 0..1 |
+--------------+---------+-------------+
9.6.4.2. The value Statement
The "value" statement, which is optional, is used to associate an
integer value with the assigned name for the enum. This integer
value MUST be in the range -2147483648 to 2147483647, and it MUST be
unique within the enumeration type.
If a value is not specified, then one will be automatically assigned.
If the enum sub-statement is the first one defined, the assigned
value is zero (0), otherwise the assigned value is one greater than
the current highest enum value.
If the current highest value is equal to 2147483647, then an enum
value MUST be specified for enum sub-statements following the one
with the current highest value.
9.6.5. Usage Example
type enumeration {
enum enabled {
value 1;
}
enum disabled {
value 2;
}
}
type enumeration {
enum zero;
enum one;
enum seven {
value 7;
}
}
Bjorklund Expires July 16, 2009 [Page 117]
Internet-Draft YANG January 2009
9.7. The bits Built-in Type
The bits built-in type represents a bit set. That is, a bits value
is a set of flags identified by small integer position numbers
starting at 0. Each bit number has an assigned name.
9.7.1. Restrictions
A bits type cannot be restricted.
9.7.2. Lexicographic Representation
The lexicographical representation of the bits type is a space
separated list of the individual bit values that are set. An empty
string thus represents a value where no bits are set.
9.7.3. Canonical Form
In the canonical form, the bit values are separated by a single space
character and they appear in the same order as they are specified in
the "bits" statement.
9.7.4. The bit Statement
The "bit" statement, which is a substatement to the "type" statement,
MUST be present if the type is "bits". It is repeatedly used to
specify each assigned named bit of a bits type. It takes as an
argument a string which is the assigned name of the bit. It is
followed by a block of substatements which holds detailed bit
information. A bit name follows the same syntax rules as an
identifier (see Section 6.2).
All bit names in a bits type MUST be unique.
9.7.4.1. The bit's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 |
| position | 9.7.4.2 | 0..1 |
+--------------+---------+-------------+
Bjorklund Expires July 16, 2009 [Page 118]
Internet-Draft YANG January 2009
9.7.4.2. The position Statement
The "position" statement, which is optional, takes as an argument a
non-negative integer value which specifies the bit's position within
a hypothetical bit field. The position value MUST be in the range 0
to 4294967295, and it MUST be unique within the bits type. The value
is unused by YANG and the XML encoding, but is carried as a
convenience to implementors.
If a bit position is not specified, then one will be automatically
assigned. If the bit sub-statement is the first one defined, the
assigned value is zero (0), otherwise the assigned value is one
greater than the current highest bit position.
If the current highest bit position value is equal to 4294967295,
then a position value MUST be specified for bit sub-statements
following the one with the current highest position value.
9.7.5. Usage Example
Given the following type:
leaf mybits {
type bits {
bit disable-nagle {
position 0;
}
bit auto-sense-speed {
position 1;
}
bit 10-Mb-only {
position 2;
}
}
default "auto-sense-speed";
}
The lexicographic representation of this leaf with bit values
disable-nagle and 10-Mb-only set would be:
<mybits>disable-nagle 10-Mb-only</mybits>
9.8. The binary Built-in Type
The binary built-in type represents any binary data, i.e. a sequence
of octets.
Bjorklund Expires July 16, 2009 [Page 119]
Internet-Draft YANG January 2009
9.8.1. Restrictions
A binary can be restricted with the "length" (Section 9.4.4)
statement. The length of a binary value is the number of octets it
contains.
9.8.2. Lexicographic Representation
Binary values are encoded with the base64 encoding scheme [RFC4648].
9.8.3. Canonical Form
The canonical form of a binary value follow the rules in [RFC4648].
9.9. The leafref Built-in Type
The leafref type is used to reference a particular leaf instance in
the data tree. Its value is constrained to be the same as the value
of an existing leaf.
If the leaf with the leafref type represents configuration data, and
the "require-instance" property (Section 9.9.3) is "true", the leaf
it refers to MUST also represent configuration. Such a leaf puts a
constraint on valid data. All leafref nodes MUST reference existing
leaf instances for the data to be valid. This constraint is enforced
according to the rules in Section 8.
9.9.1. Restrictions
A leafref can be restricted with the "require-instance" statement
(Section 9.9.3).
9.9.2. The path Statement
The "path" statement, which is a substatement to the "type"
statement, MUST be present if the type is "leafref". It takes as an
argument a string which MUST refer to a leaf node. The value of the
referring leaf MUST match the type of the referred leaf.
The syntax for a path argument is a subset of the XPath syntax. It
is an absolute or relative XPath location path in abbreviated syntax,
where axes are not permitted, and predicates are used only for
constraining the values for the key nodes for list entries. Each
predicate consists of exactly one equality test per key.
The predicates are only used when more than one key reference is
needed to uniquely identify a leaf instance. This occurs if a list
has multiple keys, or a reference to a leaf other than the key in a
Bjorklund Expires July 16, 2009 [Page 120]
Internet-Draft YANG January 2009
list is needed. In these cases, multiple leafrefs are typically
specified, and predicates are used to tie them together.
The syntax is formally defined by the rule "path-arg" in Section 12.
For leafs of type "leafref", the "path" expression evaluates to a
node set consisting of zero, one or more nodes. If "require-
instance" is "true", the node set MUST be non-empty.
9.9.3. The require-instance Statement
The "require-instance" statement, which is a substatement to the
"type" statement, MAY be present if the type is "leafref" or
"instance-identifier". It takes as an argument the string "true" or
"false". If this statement is not present, it defaults to "true".
If "require-instance" is "true", it means that the instance being
referred MUST exist for the data to be valid. This constraint is
enforced according to the rules in Section 8.
9.9.4. Lexicographic Representation
A leafref value is encoded the same way as the leaf it references.
9.9.5. Canonical Form
The canonical form of a leafref is the same as the canonical form of
the leaf it references.
9.9.6. Usage Example
With the following list:
list interface {
key "name";
leaf name {
type string;
}
leaf ifIndex {
type uint32;
}
list address {
key "ip";
leaf ip {
type yang:ip-address;
}
}
}
Bjorklund Expires July 16, 2009 [Page 121]
Internet-Draft YANG January 2009
The following leafref refers to an existing interface:
leaf mgmt-interface {
type leafref {
path "../interface/name";
}
}
An example of a corresponding XML snippet:
<interface>
<name>eth0</name>
</interface>
<interface>
<name>lo</name>
</interface>
<mgmt-interface>eth0</mgmt-interface>
The following leafrefs refer to an existing address of an interface:
container default-address {
leaf ifname {
type leafref {
path "../../interface/name";
}
}
leaf address {
type leafref {
path "../../interface[name = current()/../ifname]"
+ "/address/ip";
}
}
}
An example of a corresponding XML snippet:
Bjorklund Expires July 16, 2009 [Page 122]
Internet-Draft YANG January 2009
<interface>
<name>eth0</name>
<address>
<ip>192.0.2.1</ip>
</address>
<address>
<ip>192.0.2.2</ip>
</address>
</interface>
<interface>
<name>lo</name>
<address>
<ip>127.0.0.1</ip>
</address>
</interface>
<default-address>
<ifname>eth0</ifname>
<address>192.0.2.2</address>
</default-address>
The following notification defines two leafrefs to refer to an
existing ifIndex:
notification link-failure {
leaf if-name {
path "/interfaces/interface/name";
}
leaf index {
path "/interfaces/interface[name = current()/../if-name]"
+ "/ifIndex";
}
}
An example of a corresponding XML notification:
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-04-01T00:01:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system">
<if-name>eth0</if-name>
<index>2</index>
</link-failure>
</notification>
Bjorklund Expires July 16, 2009 [Page 123]
Internet-Draft YANG January 2009
9.10. The identityref Built-in Type
The identityref type is used to reference an existing identity (see
Section 7.16).
9.10.1. Restrictions
An identityref cannot be restricted.
9.10.2. The identityref's base Statement
The "base" statement, which is a substatement to the "type"
statement, MUST be present if the type is "identityref". The
argument is the name of an identity, as defined by an "identity"
statement. If a prefix is present on the identity name, it refers to
an identity defined the module which was imported with that prefix.
Otherwise an identity with the matching name MUST be defined in the
current module or an included submodule.
Valid values for an identityref are any identities derived from the
identityref's base identity.
9.10.3. Lexicographic Representation
An identityref is encoded as the referred identity's Qualified Name
as defined in [XML-NAMES]. If the Prefix is not present, the
namespace of the identityref is the default namespace in effect on
the element which contains the identityref value.
9.10.4. Canonical Form
Since the lexicographic form depends on the XML context in which the
value occurs, this type does not have a canonical form.
9.10.5. Usage Example
With the identity definitions in Section 7.16.3, and the following
module:
Bjorklund Expires July 16, 2009 [Page 124]
Internet-Draft YANG January 2009
module my-crypto {
namespace "http://example.com/my-crypto";
prefix mc;
import "crypto-base" {
prefix "crypto";
}
identity aes {
base "crypto:crypto-alg";
}
leaf crypto {
type identityref {
base "crypto:crypto-alg";
}
}
}
The leaf "crypto" will be encoded as follows, if the value is the
"des3" identity defined in the "des" module:
<crypto xmlns:des="http://example.com/des">des:des3</crypto>
Any prefixes used in the encoding are local to each instance
encoding. This means that the same identityref may be encoded
differently by different implementations. For example, the following
example encodes the same leaf as above:
<crypto xmlns:x="http://example.com/des">x:des3</crypto>
If the "crypto" leaf's value instead is "aes" defined in the "my-
crypto" module it can be encoded as:
<crypto xmlns:mc="http://example.com/my-crypto">mc:aes</crypto>
or, using the default namespace:
<crypto>aes</crypto>
9.11. The empty Built-in Type
The empty built-in type represents a leaf that does not have any
value, it conveys information by its presence or absence.
An empty type cannot have a default value.
Bjorklund Expires July 16, 2009 [Page 125]
Internet-Draft YANG January 2009
9.11.1. Restrictions
An empty type cannot be restricted.
9.11.2. Lexicographic Representation
Not applicable.
9.11.3. Canonical Form
Not applicable.
9.11.4. Usage Example
The following leaf
leaf enable-qos {
type empty;
}
will be encoded as
<enable-qos/>
if it exists.
9.12. The union Built-in Type
The union built-in type represents a value that corresponds to one of
its member types.
When the type is "union", the "type" statement (Section 7.4) MUST be
present. It is used to repeatedly specify each member type of the
union. It takes as an argument a string which is the name of a
member type.
A member type can be of any built-in or derived type, except it MUST
NOT be one of the built-in types "empty" or "leafref".
Example:
type union {
type int32;
type enumeration {
enum "unbounded";
}
}
Bjorklund Expires July 16, 2009 [Page 126]
Internet-Draft YANG January 2009
9.12.1. Restrictions
A union can not be restricted. However, each member type can be
restricted, based on the rules defined in Section 9 chapter.
9.12.2. Lexicographic Representation
The lexicographical representation of an union is a value that
corresponds to the representation of any one of the member types.
9.12.3. Canonical Form
The canonical form of a union value is the same as the canonical form
of the member type of the value.
9.13. The instance-identifier Built-in Type
The instance-identifier built-in type is used to uniquely identify a
particular instance node in the data tree.
The syntax for an instance-identifier is a subset of the XPath
syntax, which is used to uniquely identify a node in the data tree.
It is an absolute XPath location path in abbreviated syntax, where
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-
list. Each predicate consists of one equality test per key. Each
key MUST have a corresponding predicate.
If the leaf with the instance-identifier type represents
configuration data, and the "require-instance" property
(Section 9.9.3) is "true", the node it refers to MUST also represent
configuration. Such a leaf puts a constraint on valid data. All
such leaf nodes MUST reference existing nodes for the data to be
valid. This constraint is enforced according to the rules in
Section 8.
The syntax is formally defined by the rule "absolute-instid" in
Section 12.
9.13.1. Restrictions
An instance-identifier can be restricted with the "require-instance"
statement (Section 9.9.3).
9.13.2. Lexicographic Representation
An instance-identifier value is lexicographically represented as a
string in the XML encoding. The namespace prefixes used in the
Bjorklund Expires July 16, 2009 [Page 127]
Internet-Draft YANG January 2009
encoding MUST be declared in the XML namespace scope in the instance-
idenfitier's XML element.
Any prefixes used in the encoding are local to each instance
encoding. This means that the same instance-identifier may be
encoded differently by different implementations.
9.13.3. Canonical Form
Since the lexicographic form depends on the XML context in which the
value occurs, this type does not have a canonical form.
9.13.4. Usage Example
The following are examples of instance identifiers:
/ex:system/ex:services/ex:ssh/ex:port
/ex:system/ex:user[ex:name='fred']
/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:services/ex:ssh/ex:cipher[.='blowfish-cbc']
Bjorklund Expires July 16, 2009 [Page 128]
Internet-Draft YANG January 2009
10. Updating a Module
As experience is gained with a module, it may be desirable to revise
that module. However, changes are not allowed if they have any
potential to cause interoperability problems between a client using
an original specification and a server using an updated
specification.
For any published change, a new "revision" statement (Section 7.1.9)
SHOULD be included in front of the existing revision statements.
Furthermore, any necessary changes MUST be applied to any meta
statements, including the "organization" and "contact" statements
(Section 7.1.7, Section 7.1.8).
Note that definitions contained in a module are available to be
imported by any other module, and are referenced in "import"
statements via the module name. Thus, a module name MUST NOT be
changed. Furthermore, the "namespace" statement MUST NOT be changed,
since all XML elements are encoded in the namespace.
Obsolete definitions MUST NOT be removed from modules since their
identifiers may still be referenced by other modules.
A definition may be revised in any of the following ways:
o An "enumeration" type may have new enums added, provided the old
enums's values do not change.
o A "bits" type may have new bits added, provided the old bits's
positions do not change.
o A "range", "length", or "pattern" statement may expand the allowed
value space.
o A "default" statement may be added.
o A "units" statement may be added.
o A "reference" statement may be added or updated.
o A "must" statement may be removed or its constraint relaxed.
o A "mandatory" statement may be removed or changed from "true" to
"false".
o A "min-elements" statement may be removed, or changed to require
less elements.
Bjorklund Expires July 16, 2009 [Page 129]
Internet-Draft YANG January 2009
o A "max-elements" statement may be removed, or changed to allow
more elements.
o A "description" statement may be added or clarified without
changing the semantics of the definition.
o New typedefs, groupings, rpc, notifications, extensions, features,
and identities may be added.
o New data definition statements may be added if they do not add
mandatory nodes (Section 3.1) to existing nodes or at the top-
level in a module or submodule, or if they are conditionally
dependent on a new feature (i.e. have a "if-feature" statement
which refers to a new feature).
o A new "case" statement may be added.
o A node that represented state data may be changed to represent
configuration, provided it is not mandatory (Section 3.1).
o An "if-feature" statement may be removed, provided its node is not
mandatory (Section 3.1).
o A "status" statement may be added, or changed from "current" to
"deprecated" or "obsolete", or from "deprecated" to "obsolete".
o A "type" statement may be replaced with another "type" statement
which does not change the syntax or semantics of the type. For
example, an inline type definition may be replaced with a typedef,
but a int8 type cannot be replaced by a int16, since the syntax
would change.
o Any set of data definition nodes may be replaced with another set
of syntactically and semantically equivalent nodes. For example,
a set of leafs may be replaced by a uses of a grouping with the
same leafs.
o A module may be split into a set of submodules, or submodule may
be removed, provided the definitions in the module do not change
in any other way than allowed here.
o The "prefix" statment may be changed, provided all local uses of
the prefix also are changed.
Otherwise, if the semantics of any previous definition are changed
(i.e. if a non-editorial change is made to any definition other than
those specifically allowed above), then this MUST be achieved by a
new definition with a new identifier.
Bjorklund Expires July 16, 2009 [Page 130]
Internet-Draft YANG January 2009
In statements which have any data definition statements as
substatements, those data definition substatements MUST NOT be
reordered.
Bjorklund Expires July 16, 2009 [Page 131]
Internet-Draft YANG January 2009
11. YIN
A YANG module can be specified in an alternative XML-based syntax
called YIN. This section describes symmetric mapping rules between
the two formats.
The YANG and YIN formats contain equivalent information using
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
on the YIN format to transform, or filter the model information.
Tools like XSLT or XML validators can be utilized. After this the
model can be transformed back to the YANG format if needed, which
provides a more concise and readable format.
The YANG-2-YIN and the YIN-2-YANG transformations will not modify the
information content of the model.
11.1. Formal YIN Definition
YIN is described by an algorithm that transforms YANG to YIN.
11.2. Transformation Algorithm YANG-2-YIN
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
"urn:ietf:params:xml:ns:yang:yin:1". [XXX IANA]
The top-level element is always <module> or <submodule>.
Elements which represent keywords that are imported extensions from
other modules MUST be properly namespace qualified, where the
namespace is the namespace of the imported module. The XML prefix
for such extensions MUST be the same as the prefix defined in the
module's "import" statement.
Elements which represent keywords that are included extensions from
other submodules MUST be properly namespace qualified, where the
namespace is the namespace of the module that the submodule belongs
to. The XML prefix for such extensions MUST be the same as the local
prefix, i.e. for a module it is as defined in the "prefix" statement,
and for a submodule, as defined in the submodule's "belongs-to"
statement.
If the keyword has an argument, its encoding depends on the value of
the argument's "yin-element". If "yin-element" is false, the
argument is encoded as an XML attribute to the keyword's element. If
"yin-element" is true, the argument is encoded as a subelement to the
keyword's element. The name of the attribute or element is the name
Bjorklund Expires July 16, 2009 [Page 132]
Internet-Draft YANG January 2009
of the argument.
The core YANG keywords have arguments according to the table below.
Extension keywords have arguments according to Section 7.17.2.
YANG to YIN keyword map
+------------------+---------------+-------------+
| keyword | argument name | yin-element |
+------------------+---------------+-------------+
| anyxml | name | false |
| argument | name | false |
| augment | target-node | false |
| base | name | false |
| belongs-to | module | false |
| bit | name | false |
| case | name | false |
| choice | name | false |
| config | value | false |
| contact | info | true |
| container | name | false |
| default | value | false |
| description | text | true |
| deviate | value | false |
| deviation | target-node | false |
| enum | name | false |
| error-app-tag | value | false |
| error-message | value | true |
| extension | name | false |
| feature | name | false |
| grouping | name | false |
| identity | name | false |
| if-feature | name | false |
| import | module | false |
| include | module | false |
| input | <no argument> | n/a |
| key | value | false |
| leaf | name | false |
| leaf-list | name | false |
| length | value | false |
| list | name | false |
| mandatory | value | false |
| max-elements | value | false |
| min-elements | value | false |
| module | name | false |
| must | condition | false |
| namespace | uri | false |
| notification | name | false |
Bjorklund Expires July 16, 2009 [Page 133]
Internet-Draft YANG January 2009
| ordered-by | value | false |
| organization | info | true |
| output | <no argument> | n/a |
| path | value | false |
| pattern | value | false |
| position | value | false |
| prefix | value | false |
| presence | value | false |
| range | value | false |
| reference | info | false |
| refine | target-node | false |
| require-instance | value | false |
| revision | date | false |
| rpc | name | false |
| status | value | false |
| submodule | name | false |
| type | name | false |
| typedef | name | false |
| unique | tag | false |
| units | name | false |
| uses | name | false |
| value | value | false |
| when | condition | false |
| yang-version | value | false |
| yin-element | value | false |
+------------------+---------------+-------------+
Table 1
If a statement is followed by substatements, those substatements are
subelements in the YIN mapping.
Comments in YANG MAY be transformed into XML comments.
11.2.1. Usage Example
The following YANG snippet:
leaf mtu {
type uint32;
description "The MTU of the interface.";
}
is translated into the following YIN snippet:
Bjorklund Expires July 16, 2009 [Page 134]
Internet-Draft YANG January 2009
<leaf name="mtu">
<type name="uint32"/>
<description>
<text>The MTU of the interface.</text>
</description>
</leaf>
11.3. Transformation Algorithm YIN-2-YANG
The transformation is based on a recursive algorithm that is started
on the <module> or <submodule> element.
The element is transformed into a YANG keyword. If the keyword in
Table 1 is marked as yin-element true, the subelement with the
keyword's argument name in Table 1 contains the YANG keyword's
argument as text content. If the keyword in Table 1 is marked as
yin-element false, the element's attribute with keyword's argument
name in Table 1 contains the YANG keyword's argument.
If there are no other subelements to the element, the YANG statement
is closed with a ";". Otherwise, each such subelement is
transformed, according to the same algorithm, as substatements to the
current YANG statement, enclosed within "{" and "}".
XML comments in YIN MAY be transformed into YANG comments.
11.3.1. Tabulation, Formatting
To get a readable YANG module the YANG output will have to be
indented with appropriate whitespace characters.
Bjorklund Expires July 16, 2009 [Page 135]
Internet-Draft YANG January 2009
12. YANG ABNF Grammar
In YANG, almost all statements are unordered. The ABNF grammar
[RFC5234] defines the canonical order. To improve module
readability, it is RECOMMENDED that clauses be entered in this order.
Within the ABNF grammar, unordered statements are marked with
comments.
This grammar assumes that the scanner replaces YANG comments with a
single space character.
module-stmt = optsep module-keyword sep identifier-arg-str
optsep
"{" stmtsep
module-header-stmts
linkage-stmts
meta-stmts
revision-stmts
body-stmts
"}" optsep
submodule-stmt = optsep submodule-keyword sep identifier-arg-str
optsep
"{" stmtsep
submodule-header-stmts
linkage-stmts
meta-stmts
revision-stmts
body-stmts
"}" optsep
module-header-stmts = ;; these stmts can appear in any order
[yang-version-stmt stmtsep]
namespace-stmt stmtsep
prefix-stmt stmtsep
submodule-header-stmts = ;; these stmts can appear in any order
[yang-version-stmt stmtsep]
belongs-to-stmt stmtsep
meta-stmts = ;; these stmts can appear in any order
[organization-stmt stmtsep]
[contact-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
linkage-stmts = ;; these stmts can appear in any order
Bjorklund Expires July 16, 2009 [Page 136]
Internet-Draft YANG January 2009
*(import-stmt stmtsep)
*(include-stmt stmtsep)
revision-stmts = *(revision-stmt stmtsep)
body-stmts = *((extension-stmt /
feature-stmt /
identity-stmt /
typedef-stmt /
grouping-stmt /
data-def-stmt /
augment-stmt /
rpc-stmt /
notification-stmt /
deviation-stmt) stmtsep)
data-def-stmt = container-stmt /
leaf-stmt /
leaf-list-stmt /
list-stmt /
choice-stmt /
anyxml-stmt /
uses-stmt
case-data-def-stmt = container-stmt /
leaf-stmt /
leaf-list-stmt /
list-stmt /
anyxml-stmt /
uses-stmt
yang-version-stmt = yang-version-keyword sep yang-version-arg-str
optsep stmtend
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
prefix-stmt stmtsep
[revision-stmt stmtsep]
"}"
include-stmt = include-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
Bjorklund Expires July 16, 2009 [Page 137]
Internet-Draft YANG January 2009
[revision-stmt stmtsep]
"}")
namespace-stmt = namespace-keyword sep uri-str optsep stmtend
uri-str = < a string which matches the rule
URI in RFC 3986 >
prefix-stmt = prefix-keyword sep prefix-arg-str
optsep stmtend
belongs-to-stmt = belongs-to-keyword sep identifier-arg-str
optsep
"{" stmtsep
prefix-stmt stmtsep
"}"
organization-stmt = organization-keyword sep string
optsep stmtend
contact-stmt = contact-keyword sep string optsep stmtend
description-stmt = description-keyword sep string optsep
stmtend
reference-stmt = reference-keyword sep string optsep stmtend
units-stmt = units-keyword sep string optsep stmtend
revision-stmt = revision-keyword sep date-arg-str optsep
(";" /
"{" stmtsep
[description-stmt stmtsep]
"}")
extension-stmt = extension-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[argument-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
argument-stmt = argument-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
Bjorklund Expires July 16, 2009 [Page 138]
Internet-Draft YANG January 2009
[yin-element-stmt stmtsep]
"}")
yin-element-stmt = yin-element-keyword sep yin-element-arg-str
stmtend
yin-element-arg-str = < a string which matches the rule
yin-element-arg >
yin-element-arg = true-keyword / false-keyword
identity-stmt = identity-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[base-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
base-stmt = base-keyword sep identifier-ref-arg-str
optsep stmtend
feature-stmt = feature-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
if-feature-stmt = if-feature-keyword sep identifier-ref-arg-str
optsep stmtend
typedef-stmt = typedef-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
type-stmt stmtsep
[units-stmt stmtsep]
[default-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}"
Bjorklund Expires July 16, 2009 [Page 139]
Internet-Draft YANG January 2009
type-stmt = type-keyword sep identifier-ref-arg-str optsep
(";" /
"{" stmtsep
type-body-stmts
"}")
type-body-stmts = numerical-restrictions /
string-restrictions /
enum-specification /
leafref-specification /
identityref-specification /
bits-specification /
union-specification
numerical-restrictions = range-stmt stmtsep
range-stmt = range-keyword sep range-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
string-restrictions = ;; these stmts can appear in any order
[length-stmt stmtsep]
*(pattern-stmt stmtsep)
length-stmt = length-keyword sep length-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
pattern-stmt = pattern-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
Bjorklund Expires July 16, 2009 [Page 140]
Internet-Draft YANG January 2009
"}")
default-stmt = default-keyword sep string stmtend
enum-specification = 1*(enum-stmt stmtsep)
enum-stmt = enum-keyword sep string optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[value-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
leafref-specification = ;; these stmts can appear in any order
path-stmt stmtsep
[require-instance-stmt stmtsep]
path-stmt = path-keyword sep path-arg-str stmtend
require-instance-stmt = require-instance-keyword sep
require-instance-arg-str stmtend
require-instance-arg-str = < a string which matches the rule
require-instance-arg >
require-instance-arg = true-keyword / false-keyword
identityref-specification = ;; these stmts can appear in any order
base-stmt stmtsep
[require-instance-stmt stmtsep]
union-specification = 1*(type-stmt stmtsep)
bits-specification = 1*(bit-stmt stmtsep)
bit-stmt = bit-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[position-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
Bjorklund Expires July 16, 2009 [Page 141]
Internet-Draft YANG January 2009
"}"
"}")
position-stmt = position-keyword sep
position-value-arg-str stmtend
position-value-arg-str = < a string which matches the rule
position-value-arg >
position-value-arg = non-negative-decimal-value
status-stmt = status-keyword sep status-arg-str stmtend
status-arg-str = < a string which matches the rule
status-arg >
status-arg = current-keyword /
obsolete-keyword /
deprecated-keyword
config-stmt = config-keyword sep
config-arg-str stmtend
config-arg-str = < a string which matches the rule
config-arg >
config-arg = true-keyword / false-keyword
mandatory-stmt = mandatory-keyword sep
mandatory-arg-str stmtend
mandatory-arg-str = < a string which matches the rule
mandatory-arg >
mandatory-arg = true-keyword / false-keyword
presence-stmt = presence-keyword sep string stmtend
ordered-by-stmt = ordered-by-keyword sep
ordered-by-arg-str stmtend
ordered-by-arg-str = < a string which matches the rule
ordered-by-arg >
ordered-by-arg = user-keyword / system-keyword
must-stmt = must-keyword sep string optsep
(";" /
Bjorklund Expires July 16, 2009 [Page 142]
Internet-Draft YANG January 2009
"{" stmtsep
;; these stmts can appear in any order
[error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
error-message-stmt = error-message-keyword sep string stmtend
error-app-tag-stmt = error-app-tag-keyword sep string stmtend
min-elements-stmt = min-elements-keyword sep
min-value-arg-str stmtend;
min-value-arg-str = < a string which matches the rule
min-value-arg >
min-value-arg = non-negative-decimal-value
max-elements-stmt = max-elements-keyword sep
max-value-arg-str stmtend;
max-value-arg-str = < a string which matches the rule
max-value-arg >
max-value-arg = unbounded-keyword /
positive-decimal-value
value-stmt = value-keyword sep decimal-value stmtend
grouping-stmt = grouping-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((typedef-stmt /
grouping-stmt) stmtsep)
*(data-def-stmt stmtsep)
"}")
container-stmt = container-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
Bjorklund Expires July 16, 2009 [Page 143]
Internet-Draft YANG January 2009
*(if-feature-stmt stmtsep)
*(must-stmt stmtsep)
[presence-stmt stmtsep]
[config-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((typedef-stmt /
grouping-stmt) stmtsep)
*(data-def-stmt stmtsep)
"}")
leaf-stmt = leaf-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
type-stmt stmtsep
[units-stmt stmtsep]
*(must-stmt stmtsep)
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}"
leaf-list-stmt = leaf-list-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
type-stmt stmtsep
[units-stmt stmtsep]
*(must-stmt stmtsep)
[config-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
[ordered-by-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}"
list-stmt = list-keyword sep identifier-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
Bjorklund Expires July 16, 2009 [Page 144]
Internet-Draft YANG January 2009
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
*(must-stmt stmtsep)
[key-stmt stmtsep]
*(unique-stmt stmtsep)
[config-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
[ordered-by-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((typedef-stmt /
grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep)
"}"
key-stmt = key-keyword sep key-arg-str stmtend
key-arg-str = < a string which matches the rule
key-arg >
key-arg = identifier *(sep identifier)
unique-stmt = unique-keyword sep unique-arg-str stmtend
unique-arg-str = < a string which matches the rule
unique-arg >
unique-arg = descendant-schema-nodeid
*(sep descendant-schema-nodeid)
choice-stmt = choice-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((short-case-stmt / case-stmt) stmtsep)
"}")
short-case-stmt = container-stmt /
Bjorklund Expires July 16, 2009 [Page 145]
Internet-Draft YANG January 2009
leaf-stmt /
leaf-list-stmt /
list-stmt /
anyxml-stmt
case-stmt = case-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(case-data-def-stmt stmtsep)
"}")
anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
*(must-stmt stmtsep)
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
uses-stmt = uses-keyword sep identifier-ref-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(refine-stmt stmtsep)
*(uses-augment-stmt stmtsep)
"}")
refine-stmt = refine-keyword sep refine-arg-str optsep
(";" /
"{" stmtsep
(refine-container-stmts /
Bjorklund Expires July 16, 2009 [Page 146]
Internet-Draft YANG January 2009
refine-leaf-stmts /
refine-leaf-list-stmts /
refine-list-stmts /
refine-choice-stmts /
refine-case-stmts /
refine-anyxml-stmts)
"}")
refine-arg-str = < a string which matches the rule
refine-arg >
refine-arg = descendant-schema-nodeid
refine-container-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep)
[presence-stmt stmtsep]
[config-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-leaf-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep)
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-leaf-list-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep)
[config-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-list-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep)
[config-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-choice-stmts = ;; these stmts can appear in any order
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
Bjorklund Expires July 16, 2009 [Page 147]
Internet-Draft YANG January 2009
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-case-stmts = ;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
refine-anyxml-stmts = ;; these stmts can appear in any order
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
uses-augment-stmt = augment-keyword sep uses-augment-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
1*((data-def-stmt stmtsep) /
(case-stmt stmtsep))
"}"
uses-augment-arg-str = < a string which matches the rule
uses-augment-arg >
uses-augment-arg = descendant-schema-nodeid
augment-stmt = augment-keyword sep augment-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[when-stmt stmtsep]
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
1*((data-def-stmt stmtsep) /
(case-stmt stmtsep))
"}"
augment-arg-str = < a string which matches the rule
augment-arg >
augment-arg = absolute-schema-nodeid
Bjorklund Expires July 16, 2009 [Page 148]
Internet-Draft YANG January 2009
unknown-statement = prefix ":" identifier [sep string] optsep
(";" / "{" *unknown-statement "}")
when-stmt = when-keyword sep string stmtend
rpc-stmt = rpc-keyword sep identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((typedef-stmt /
grouping-stmt) stmtsep)
[input-stmt stmtsep]
[output-stmt stmtsep]
"}")
input-stmt = input-keyword optsep
"{" stmtsep
;; these stmts can appear in any order
*((typedef-stmt /
grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep)
"}"
output-stmt = output-keyword optsep
"{" stmtsep
;; these stmts can appear in any order
*((typedef-stmt /
grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep)
"}"
notification-stmt = notification-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
*(if-feature-stmt stmtsep)
[status-stmt stmtsep]
[description-stmt stmtsep]
[reference-stmt stmtsep]
*((typedef-stmt /
grouping-stmt) stmtsep)
*(data-def-stmt stmtsep)
"}")
Bjorklund Expires July 16, 2009 [Page 149]
Internet-Draft YANG January 2009
deviation-stmt = deviation-keyword sep
deviation-arg-str optsep
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
(deviate-not-supported-stmt /
1*(deviate-add-stmt /
deviate-replace-stmt /
deviate-delete-stmt))
"}"
deviation-arg-str = < a string which matches the rule
deviation-arg >
deviation-arg = absolute-schema-nodeid
deviate-not-supported-stmt =
deviate-keyword sep
not-supported-keyword optsep
(";" /
"{" stmtsep
"}")
deviate-add-stmt = deviate-keyword sep add-keyword optsep
(";" /
"{" stmtsep
[units-stmt stmtsep]
*(must-stmt stmtsep)
*(unique-stmt stmtsep)
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
"}")
deviate-delete-stmt = deviate-keyword sep delete-keyword optsep
(";" /
"{" stmtsep
[units-stmt stmtsep]
*(must-stmt stmtsep)
*(unique-stmt stmtsep)
[default-stmt stmtsep]
"}")
deviate-replace-stmt = deviate-keyword sep replace-keyword optsep
(";" /
Bjorklund Expires July 16, 2009 [Page 150]
Internet-Draft YANG January 2009
"{" stmtsep
[type-stmt stmtsep]
[units-stmt stmtsep]
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
"}")
;; Ranges
range-arg-str = < a string which matches the rule
range-arg >
range-arg = range-part *(optsep "|" optsep range-part)
range-part = range-boundary
[optsep ".." optsep range-boundary]
range-boundary = neginf-keyword / posinf-keyword /
min-keyword / max-keyword /
decimal-value / float-value
;; Lengths
length-arg-str = < a string which matches the rule
length-arg >
length-arg = length-part *(optsep "|" optsep length-part)
length-part = length-boundary
[optsep ".." optsep length-boundary]
length-boundary = min-keyword / max-keyword /
non-negative-decimal-value
;; Date
date-arg-str = < a string which matches the rule
date-arg >
date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT
;; Schema Node Identifiers
schema-nodeid = absolute-schema-nodeid /
relative-schema-nodeid
Bjorklund Expires July 16, 2009 [Page 151]
Internet-Draft YANG January 2009
absolute-schema-nodeid
= 1*("/" node-identifier)
relative-schema-nodeid
= descendant-schema-nodeid /
(("." / "..") "/"
*relative-schema-nodeid)
descendant-schema-nodeid
= node-identifier
absolute-schema-nodeid
node-identifier = [prefix ":"] identifier
;; Instance Identifiers
instance-identifier-str
= < a string which matches the rule
instance-identifier >
instance-identifier = absolute-instid / relative-instid
absolute-instid = 1*("/" (node-identifier *predicate))
relative-instid = descendant-instid /
(("." / "..") "/"
*relative-instid)
descendant-instid = node-identifier *predicate
absolute-instid
predicate = "[" *WSP predicate-expr *WSP "]"
predicate-expr = (node-identifier / ".") *WSP "=" *WSP
((DQUOTE string DQUOTE) /
(SQUOTE string SQUOTE))
;; leafref path
path-arg-str = < a string which matches the rule
path-arg >
path-arg = absolute-path / relative-path
absolute-path = 1*("/" (node-identifier *path-predicate))
relative-path = 1*(".." "/") descendant-path
Bjorklund Expires July 16, 2009 [Page 152]
Internet-Draft YANG January 2009
descendant-path = node-identifier
[*path-predicate absolute-path]
path-predicate = "[" *WSP path-equality-expr *WSP "]"
path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr
path-key-expr = current-function-invocation *WSP "/" *WSP
rel-path-keyexpr
rel-path-keyexpr = 1*(".." *WSP "/" *WSP)
*(node-identifier *WSP "/" *WSP)
node-identifier
;;; Keywords, using abnfgen's syntax for case-sensitive strings
;; statment keywords
anyxml-keyword = 'anyxml'
argument-keyword = 'argument'
augment-keyword = 'augment'
base-keyword = 'base'
belongs-to-keyword = 'belongs-to'
bit-keyword = 'bit'
case-keyword = 'case'
choice-keyword = 'choice'
config-keyword = 'config'
contact-keyword = 'contact'
container-keyword = 'container'
default-keyword = 'default'
description-keyword = 'description'
enum-keyword = 'enum'
error-app-tag-keyword = 'error-app-tag'
error-message-keyword = 'error-message'
extension-keyword = 'extension'
deviation-keyword = 'deviation'
deviate-keyword = 'deviate'
feature-keyword = 'feature'
grouping-keyword = 'grouping'
identity-keyword = 'identity'
if-feature-keyword = 'if-feature'
import-keyword = 'import'
include-keyword = 'include'
input-keyword = 'input'
key-keyword = 'key'
leaf-keyword = 'leaf'
leaf-list-keyword = 'leaf-list'
length-keyword = 'length'
list-keyword = 'list'
Bjorklund Expires July 16, 2009 [Page 153]
Internet-Draft YANG January 2009
mandatory-keyword = 'mandatory'
max-elements-keyword = 'max-elements'
min-elements-keyword = 'min-elements'
module-keyword = 'module'
must-keyword = 'must'
namespace-keyword = 'namespace'
notification-keyword = 'notification'
ordered-by-keyword = 'ordered-by'
organization-keyword = 'organization'
output-keyword = 'output'
path-keyword = 'path'
pattern-keyword = 'pattern'
position-keyword = 'position'
prefix-keyword = 'prefix'
presence-keyword = 'presence'
range-keyword = 'range'
reference-keyword = 'reference'
refine-keyword = 'refine'
require-instance-keyword = 'require-instance'
revision-keyword = 'revision'
rpc-keyword = 'rpc'
status-keyword = 'status'
submodule-keyword = 'submodule'
type-keyword = 'type'
typedef-keyword = 'typedef'
unique-keyword = 'unique'
units-keyword = 'units'
uses-keyword = 'uses'
value-keyword = 'value'
when-keyword = 'when'
yang-version-keyword = 'yang-version'
yin-element-keyword = 'yin-element'
;; other keywords
add-keyword = 'add'
current-keyword = 'current'
delete-keyword = 'delete'
deprecated-keyword = 'deprecated'
false-keyword = 'false'
max-keyword = 'max'
min-keyword = 'min'
nan-keyword = 'NaN'
neginf-keyword = '-INF'
not-supported-keyword = 'not-supported'
obsolete-keyword = 'obsolete'
posinf-keyword = 'INF'
replace-keyword = 'replace'
Bjorklund Expires July 16, 2009 [Page 154]
Internet-Draft YANG January 2009
system-keyword = 'system'
true-keyword = 'true'
unbounded-keyword = 'unbounded'
user-keyword = 'user'
current-function-invocation = current-keyword *WSP "(" *WSP ")"
;; Basic Rules
prefix-arg-str = < a string which matches the rule
prefix-arg >
prefix-arg = prefix
prefix = identifier
identifier-arg-str = < a string which matches the rule
identifier-arg >
identifier-arg = identifier
identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".")
identifier-ref-arg-str = < a string which matches the rule
identifier-ref-arg >
identifier-ref-arg = [prefix ":"] identifier
string = < an unquoted string as returned by
the scanner >
decimal-value = ("-" non-negative-decimal-value) /
non-negative-decimal-value
non-negative-decimal-value = "0" / positive-decimal-value
positive-decimal-value = (non-zero-digit *DIGIT)
zero-decimal-value = 1*DIGIT
stmtend = ";" / "{" *unknown-statement "}"
sep = 1*(WSP / line-break)
; unconditional separator
optsep = *(WSP / line-break)
Bjorklund Expires July 16, 2009 [Page 155]
Internet-Draft YANG January 2009
stmtsep = *(WSP / line-break / unknown-statement)
line-break = CRLF / LF
non-zero-digit = %x31-39
float-value = neginf-keyword /
posinf-keyword /
nan-keyword /
decimal-value "." zero-decimal-value
*1("E" ("+"/"-") zero-decimal-value)
SQUOTE = %x27
; ' (Single Quote)
;;
;; RFC 4234 core rules.
;;
ALPHA = %x41-5A / %x61-7A
; A-Z / a-z
CR = %x0D
; carriage return
CRLF = CR LF
; Internet standard newline
DIGIT = %x30-39
; 0-9
DQUOTE = %x22
; " (Double Quote)
HEXDIG = DIGIT /
%x61 / %x62 / %x63 / %x64 / %x65 / %x66
; only lower-case a..f
HTAB = %x09
; horizontal tab
LF = %x0A
; linefeed
SP = %x20
; space
VCHAR = %x21-7E
Bjorklund Expires July 16, 2009 [Page 156]
Internet-Draft YANG January 2009
; visible (printing) characters
WSP = SP / HTAB
; white space
Bjorklund Expires July 16, 2009 [Page 157]
Internet-Draft YANG January 2009
13. Error Responses for YANG Related Errors
A number of NETCONF error responses are defined for error cases
related to the data-model handling. If the relevant YANG statement
has an "error-app-tag" substatement, that overrides the default value
specified below.
13.1. Error Message for Data that Violates a YANG unique Statement:
If a NETCONF operation would result in configuration data where a
unique constraint is invalidated, the following error is returned:
Tag: operation-failed
Error-app-tag: data-not-unique
Error-info: <non-unique>: Contains an instance identifier which
points to a leaf which invalidates the unique
constraint. This element is present once for each
leaf invalidating the unique constraint.
The <non-unique> element is in the YANG
namespace ("urn:ietf:params:xml:ns:yang:1"
[XXX IANA]).
13.2. Error Message for Data that Violates a YANG max-elements
Statement:
If a NETCONF operation would result in configuration data where a
list or a leaf-list would have too many entries the following error
is returned:
Tag: operation-failed
Error-app-tag: too-many-elements
This error is returned once, with the error-path identifying the list
node, even if there are more than one extra child present.
13.3. Error Message for Data that Violates a YANG min-elements
Statement:
If a NETCONF operation would result in configuration data where a
list or a leaf-list would have too few entries the following error is
returned:
Tag: operation-failed
Error-app-tag: too-few-elements
This error is returned once, with the error-path identifying the list
node, even if there are more than one child missing.
Bjorklund Expires July 16, 2009 [Page 158]
Internet-Draft YANG January 2009
13.4. Error Message for Data that Violates a YANG must statement:
If a NETCONF operation would result in configuration data where the
restrictions imposed by a "must" statement is violated the following
error is returned, unless a specific "error-app-tag" substatement is
present for the "must" statement.
Tag: operation-failed
Error-app-tag: must-violation
13.5. Error Message for the "insert" Operation
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
to a non-existing instance, the following error is returned:
Tag: bad-attribute
Error-app-tag: missing-instance
Bjorklund Expires July 16, 2009 [Page 159]
Internet-Draft YANG January 2009
14. IANA Considerations
+-------------------------------------------------------------------+
| Open Question |
+-------------------------------------------------------------------+
| Write this section properly. We need a registry for (sub)module |
| names and module namespaces. |
+-------------------------------------------------------------------+
This document registers two URIs for the YANG XML namespace in the
IETF XML registry [RFC3688].
URI: urn:ietf:params:xml:ns:yang:yin:1
URI: urn:ietf:params:xml:ns:yang:1
Bjorklund Expires July 16, 2009 [Page 160]
Internet-Draft YANG January 2009
15. 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 and access control mechanisms to restrict
the usage of sensitive data.
Bjorklund Expires July 16, 2009 [Page 161]
Internet-Draft YANG January 2009
16. 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)
Bjorklund Expires July 16, 2009 [Page 162]
Internet-Draft YANG January 2009
17. References
17.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.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
Notifications", RFC 5277, July 2008.
[XML-NAMES]
Tobin, R., Bray, T., Hollander, D., and A. Layman,
"Namespaces in XML 1.0 (Second Edition)", World Wide Web
Consortium Recommendation REC-xml-names-20060816,
August 2006,
<http://www.w3.org/TR/2006/REC-xml-names-20060816>.
[XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
Bjorklund Expires July 16, 2009 [Page 163]
Internet-Draft YANG January 2009
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.
17.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.
Bjorklund Expires July 16, 2009 [Page 164]
Internet-Draft YANG January 2009
Appendix A. ChangeLog
A.1. Version -03
o Added import by revision (yang-00413)
o Changed type "keyref" to "leafref", and added the statement
"require-instance" (yang-01253)
o Clarified that data sent from the server must be in the canonical
form.
o Clarified when and how constraints in the models are enforced.
o Many editorial fixes
o Added more strict grammar for the "deviate" statement.
A.2. Version -02
o Added module update rules. (yang-00000)
o Added "refine" statement as a substatement to "uses". (yang-00088)
o Allow "augment" on top-level and in "uses" only. (yang-00088)
o Allow "when" on all data defintion statements. (yang-00088)
o Added section "Constraints" and clarified when constraints are
enforced. (yang-00172)
o Added "feature" and "if-feature" statements. (yang-00750)
o Added "prefix" as a substatement to "belongs-to". (yang-00755)
o Added section on Conformance. (yang-01281)
o Added "deviation" statement. (yang-01281)
o Added "identity" statement and "identityref" type. (yang-01339)
o Aligned grammar for "enum" with text.
A.3. Version -01
o Removed "Appendix A. Derived YANG Types".
Bjorklund Expires July 16, 2009 [Page 165]
Internet-Draft YANG January 2009
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.4. Version -00
Changes from draft-bjorklund-netconf-yang-02.txt
o Fixed bug in grammar for bit-stmt
Bjorklund Expires July 16, 2009 [Page 166]
Internet-Draft YANG January 2009
o Fixed bugs in example XPath expressions
o Added keyword 'presence' to the YIN mapping table
Bjorklund Expires July 16, 2009 [Page 167]
Internet-Draft YANG January 2009
Author's Address
Martin Bjorklund (editor)
Tail-f Systems
Email: mbj@tail-f.com
Bjorklund Expires July 16, 2009 [Page 168]
