draft-ietf-netmod-rfc6020bis-14.txt   rfc7950.txt 
Network Working Group M. Bjorklund, Ed. Internet Engineering Task Force (IETF) M. Bjorklund, Ed.
Internet-Draft Tail-f Systems Request for Comments: 7950 Tail-f Systems
Intended status: Standards Track June 17, 2016 Category: Standards Track August 2016
Expires: December 19, 2016 ISSN: 2070-1721
The YANG 1.1 Data Modeling Language The YANG 1.1 Data Modeling Language
draft-ietf-netmod-rfc6020bis-14
Abstract Abstract
YANG is a data modeling language used to model configuration data, YANG is a data modeling language used to model configuration data,
state data, remote procedure calls, and notifications for network state data, Remote Procedure Calls, and notifications for network
management protocols. This document describes the syntax and management protocols. This document describes the syntax and
semantics of version 1.1 of the YANG language. YANG version 1.1 is a semantics of version 1.1 of the YANG language. YANG version 1.1 is a
maintenance release of the YANG language, addressing ambiguities and maintenance release of the YANG language, addressing ambiguities and
defects in the original specification. There are a small number of defects in the original specification. There are a small number of
backward incompatibilities from YANG version 1. This document also backward incompatibilities from YANG version 1. This document also
specifies the YANG mappings to the Network Configuration Protocol specifies the YANG mappings to the Network Configuration Protocol
(NETCONF). (NETCONF).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on December 19, 2016. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7950.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 23 skipping to change at page 3, line 7
modifications of such material outside the IETF Standards Process. modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction ....................................................9
1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 9 1.1. Summary of Changes from RFC 6020 ..........................10
2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2. Key Words ......................................................12
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 3. Terminology ....................................................12
3.1. A Note on Examples . . . . . . . . . . . . . . . . . . . 14 3.1. A Note on Examples ........................................16
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 15 4. YANG Overview ..................................................16
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 15 4.1. Functional Overview .......................................16
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 16 4.2. Language Overview .........................................18
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 16 4.2.1. Modules and Submodules .............................18
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 17 4.2.2. Data Modeling Basics ...............................19
4.2.3. Configuration and State Data . . . . . . . . . . . . 21 4.2.3. Configuration and State Data .......................23
4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 21 4.2.4. Built-In Types .....................................24
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 22 4.2.5. Derived Types (typedef) ............................25
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 23 4.2.6. Reusable Node Groups (grouping) ....................25
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 24 4.2.7. Choices ............................................27
4.2.8. Extending Data Models (augment) . . . . . . . . . . . 25 4.2.8. Extending Data Models (augment) ....................28
4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 26 4.2.9. Operation Definitions ..............................29
4.2.10. Notification Definitions . . . . . . . . . . . . . . 29 4.2.10. Notification Definitions ..........................31
5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 29 5. Language Concepts ..............................................32
5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 29 5.1. Modules and Submodules ....................................32
5.1.1. Import and Include by Revision . . . . . . . . . . . 31 5.1.1. Import and Include by Revision .....................33
5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 32 5.1.2. Module Hierarchies .................................34
5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 33 5.2. File Layout ...............................................36
5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 34 5.3. XML Namespaces ............................................36
5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 34 5.3.1. YANG XML Namespace .................................36
5.4. Resolving Grouping, Type, and Identity Names . . . . . . 34 5.4. Resolving Grouping, Type, and Identity Names ..............37
5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 34 5.5. Nested Typedefs and Groupings .............................37
5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 35 5.6. Conformance ...............................................38
5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 35 5.6.1. Basic Behavior .....................................38
5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 36 5.6.2. Optional Features ..................................38
5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 36 5.6.3. Deviations .........................................39
5.6.4. Announcing Conformance Information in NETCONF . . . . 37 5.6.4. Announcing Conformance Information in NETCONF ......40
5.6.5. Implementing a Module . . . . . . . . . . . . . . . . 38 5.6.5. Implementing a Module ..............................40
5.7. Datastore Modification . . . . . . . . . . . . . . . . . 41 5.7. Datastore Modification ....................................44
6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 41 6. YANG Syntax ....................................................44
6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 42 6.1. Lexical Tokenization ......................................45
6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 42 6.1.1. Comments ...........................................45
6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 42 6.1.2. Tokens .............................................45
6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 42 6.1.3. Quoting ............................................45
6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 44 6.2. Identifiers ...............................................47
6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 44 6.2.1. Identifiers and Their Namespaces ...................47
6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 45 6.3. Statements ................................................48
6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 46 6.3.1. Language Extensions ................................48
6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 46 6.4. XPath Evaluations .........................................49
6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 47 6.4.1. XPath Context ......................................50
6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 51 6.5. Schema Node Identifier ....................................54
7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 52
7.1. The module Statement . . . . . . . . . . . . . . . . . . 52
7.1.1. The module's Substatements . . . . . . . . . . . . . 53
7.1.2. The yang-version Statement . . . . . . . . . . . . . 54
7.1.3. The namespace Statement . . . . . . . . . . . . . . . 55
7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 55
7.1.5. The import Statement . . . . . . . . . . . . . . . . 56
7.1.6. The include Statement . . . . . . . . . . . . . . . . 57
7.1.7. The organization Statement . . . . . . . . . . . . . 57
7.1.8. The contact Statement . . . . . . . . . . . . . . . . 58
7.1.9. The revision Statement . . . . . . . . . . . . . . . 58
7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 58
7.2. The submodule Statement . . . . . . . . . . . . . . . . . 59
7.2.1. The submodule's Substatements . . . . . . . . . . . . 60
7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 61
7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 62
7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 62
7.3.1. The typedef's Substatements . . . . . . . . . . . . . 63
7.3.2. The typedef's type Statement . . . . . . . . . . . . 63
7.3.3. The units Statement . . . . . . . . . . . . . . . . . 63
7.3.4. The typedef's default Statement . . . . . . . . . . . 63
7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 64
7.4. The type Statement . . . . . . . . . . . . . . . . . . . 64
7.4.1. The type's Substatements . . . . . . . . . . . . . . 64
7.5. The container Statement . . . . . . . . . . . . . . . . . 64
7.5.1. Containers with Presence . . . . . . . . . . . . . . 65
7.5.2. The container's Substatements . . . . . . . . . . . . 65
7.5.3. The must Statement . . . . . . . . . . . . . . . . . 66
7.5.4. The must's Substatements . . . . . . . . . . . . . . 67
7.5.5. The presence Statement . . . . . . . . . . . . . . . 68
7.5.6. The container's Child Node Statements . . . . . . . . 68
7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 68
7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 69
7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 69
7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 71
7.6.1. The leaf's default value . . . . . . . . . . . . . . 71
7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 72
7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 72
7.6.4. The leaf's default Statement . . . . . . . . . . . . 72
7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 73
7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 73
7.6.7. NETCONF <edit-config> Operations . . . . . . . . . . 73
7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 74
7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 74
7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 75
7.7.2. The leaf-list's default values . . . . . . . . . . . 75
7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 76
7.7.4. The leaf-list's default Statement . . . . . . . . . . 77
7.7.5. The min-elements Statement . . . . . . . . . . . . . 77
7.7.6. The max-elements Statement . . . . . . . . . . . . . 78
7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 78
7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 79
7.7.9. NETCONF <edit-config> Operations . . . . . . . . . . 79
7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 80
7.8. The list Statement . . . . . . . . . . . . . . . . . . . 81
7.8.1. The list's Substatements . . . . . . . . . . . . . . 82
7.8.2. The list's key Statement . . . . . . . . . . . . . . 82
7.8.3. The list's unique Statement . . . . . . . . . . . . . 83
7.8.4. The list's Child Node Statements . . . . . . . . . . 84
7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 84
7.8.6. NETCONF <edit-config> Operations . . . . . . . . . . 85
7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86
7.9. The choice Statement . . . . . . . . . . . . . . . . . . 89
7.9.1. The choice's Substatements . . . . . . . . . . . . . 89
7.9.2. The choice's case Statement . . . . . . . . . . . . . 90
7.9.3. The choice's default Statement . . . . . . . . . . . 91
7.9.4. The choice's mandatory Statement . . . . . . . . . . 93
7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 93
7.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 93
7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 94
7.10.1. The anydata's Substatements . . . . . . . . . . . . 95
7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 95
7.10.3. NETCONF <edit-config> Operations . . . . . . . . . . 95
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 96
7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 97
7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 97
7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 97
7.11.3. NETCONF <edit-config> Operations . . . . . . . . . . 98
7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 98
7.12. The grouping Statement . . . . . . . . . . . . . . . . . 99 7. YANG Statements ................................................55
7.12.1. The grouping's Substatements . . . . . . . . . . . . 99 7.1. The "module" Statement ....................................55
7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 100 7.1.1. The module's Substatements .........................56
7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 100 7.1.2. The "yang-version" Statement .......................57
7.13.1. The uses's Substatements . . . . . . . . . . . . . . 101 7.1.3. The "namespace" Statement ..........................57
7.13.2. The refine Statement . . . . . . . . . . . . . . . . 101 7.1.4. The "prefix" Statement .............................57
7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 102 7.1.5. The "import" Statement .............................58
7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 102 7.1.6. The "include" Statement ............................59
7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 103 7.1.7. The "organization" Statement .......................60
7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 103 7.1.8. The "contact" Statement ............................60
7.14.2. The input Statement . . . . . . . . . . . . . . . . 104 7.1.9. The "revision" Statement ...........................60
7.14.3. The output Statement . . . . . . . . . . . . . . . . 105 7.1.10. Usage Example .....................................61
7.14.4. NETCONF XML Encoding Rules . . . . . . . . . . . . . 106 7.2. The "submodule" Statement .................................62
7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 106 7.2.1. The submodule's Substatements ......................63
7.15. The action Statement . . . . . . . . . . . . . . . . . . 107 7.2.2. The "belongs-to" Statement .........................63
7.15.1. The action's Substatements . . . . . . . . . . . . . 108 7.2.3. Usage Example ......................................64
7.15.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 108 7.3. The "typedef" Statement ...................................65
7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 109 7.3.1. The typedef's Substatements ........................65
7.16. The notification Statement . . . . . . . . . . . . . . . 110 7.3.2. The typedef's "type" Statement .....................65
7.16.1. The notification's Substatements . . . . . . . . . . 111 7.3.3. The "units" Statement ..............................65
7.16.2. NETCONF XML Encoding Rules . . . . . . . . . . . . . 111 7.3.4. The typedef's "default" Statement ..................66
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 7.3.5. Usage Example ......................................66
7.17. The augment Statement . . . . . . . . . . . . . . . . . . 113 7.4. The "type" Statement ......................................66
7.17.1. The augment's Substatements . . . . . . . . . . . . 115 7.4.1. The type's Substatements ...........................67
7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 116 7.5. The "container" Statement .................................67
7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 116 7.5.1. Containers with Presence ...........................67
7.18. The identity Statement . . . . . . . . . . . . . . . . . 118 7.5.2. The container's Substatements ......................68
7.18.1. The identity's Substatements . . . . . . . . . . . . 118 7.5.3. The "must" Statement ...............................69
7.18.2. The base Statement . . . . . . . . . . . . . . . . . 118 7.5.4. The must's Substatements ...........................70
7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 119 7.5.5. The "presence" Statement ...........................71
7.19. The extension Statement . . . . . . . . . . . . . . . . . 121 7.5.6. The container's Child Node Statements ..............71
7.19.1. The extension's Substatements . . . . . . . . . . . 121 7.5.7. XML Encoding Rules .................................71
7.19.2. The argument Statement . . . . . . . . . . . . . . . 121 7.5.8. NETCONF <edit-config> Operations ...................72
7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 122 7.5.9. Usage Example ......................................72
7.20. Conformance-Related Statements . . . . . . . . . . . . . 123 7.6. The "leaf" Statement ......................................73
7.20.1. The feature Statement . . . . . . . . . . . . . . . 123 7.6.1. The leaf's Default Value ...........................74
7.20.2. The if-feature Statement . . . . . . . . . . . . . . 125 7.6.2. The leaf's Substatements ...........................75
7.20.3. The deviation Statement . . . . . . . . . . . . . . 125 7.6.3. The leaf's "type" Statement ........................75
7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 129 7.6.4. The leaf's "default" Statement .....................75
7.21.1. The config Statement . . . . . . . . . . . . . . . . 129 7.6.5. The leaf's "mandatory" Statement ...................76
7.21.2. The status Statement . . . . . . . . . . . . . . . . 129 7.6.6. XML Encoding Rules .................................76
7.21.3. The description Statement . . . . . . . . . . . . . 130 7.6.7. NETCONF <edit-config> Operations ...................76
7.21.4. The reference Statement . . . . . . . . . . . . . . 130 7.6.8. Usage Example ......................................77
7.21.5. The when Statement . . . . . . . . . . . . . . . . . 131 7.7. The "leaf-list" Statement .................................77
8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 132 7.7.1. Ordering ...........................................78
8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 132 7.7.2. The leaf-list's Default Values .....................79
8.2. Configuration Data Modifications . . . . . . . . . . . . 133 7.7.3. The leaf-list's Substatements ......................80
8.3. NETCONF Constraint Enforcement Model . . . . . . . . . . 133 7.7.4. The leaf-list's "default" Statement ................80
8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 133 7.7.5. The "min-elements" Statement .......................80
8.3.2. NETCONF <edit-config> Processing . . . . . . . . . . 134 7.7.6. The "max-elements" Statement .......................81
8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 135 7.7.7. The "ordered-by" Statement .........................81
9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 135 7.7.8. XML Encoding Rules .................................82
9.1. Canonical Representation . . . . . . . . . . . . . . . . 135 7.7.9. NETCONF <edit-config> Operations ...................82
9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 136 7.7.10. Usage Example .....................................83
9.2.1. Lexical Representation . . . . . . . . . . . . . . . 136 7.8. The "list" Statement ......................................84
9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 137 7.8.1. The list's Substatements ...........................85
9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 137 7.8.2. The list's "key" Statement .........................85
9.2.4. The range Statement . . . . . . . . . . . . . . . . . 137 7.8.3. The list's "unique" Statement ......................86
9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138 7.8.4. The list's Child Node Statements ...................87
9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 138 7.8.5. XML Encoding Rules .................................88
9.3.1. Lexical Representation . . . . . . . . . . . . . . . 139 7.8.6. NETCONF <edit-config> Operations ...................88
9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 139 7.8.7. Usage Example ......................................90
9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 139 7.9. The "choice" Statement ....................................93
9.3.4. The fraction-digits Statement . . . . . . . . . . . . 139 7.9.1. The choice's Substatements .........................94
9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 140 7.9.2. The choice's "case" Statement ......................94
9.4. The string Built-In Type . . . . . . . . . . . . . . . . 140 7.9.3. The choice's "default" Statement ...................96
9.4.1. Lexical Representation . . . . . . . . . . . . . . . 140 7.9.4. The choice's "mandatory" Statement .................98
9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 141 7.9.5. XML Encoding Rules .................................98
9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 141 7.9.6. Usage Example ......................................99
9.4.4. The length Statement . . . . . . . . . . . . . . . . 141 7.10. The "anydata" Statement .................................100
9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 142 7.10.1. The anydata's Substatements ......................100
9.4.6. The modifier Statement . . . . . . . . . . . . . . . 142 7.10.2. XML Encoding Rules ...............................101
9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 142 7.10.3. NETCONF <edit-config> Operations .................101
9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 144 7.10.4. Usage Example ....................................101
9.5.1. Lexical Representation . . . . . . . . . . . . . . . 144 7.11. The "anyxml" Statement ..................................102
9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 7.11.1. The anyxml's Substatements .......................103
9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 7.11.2. XML Encoding Rules ...............................103
9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 144 7.11.3. NETCONF <edit-config> Operations .................103
9.6.1. Lexical Representation . . . . . . . . . . . . . . . 144 7.11.4. Usage Example ....................................104
9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 144 7.12. The "grouping" Statement ................................104
9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 144 7.12.1. The grouping's Substatements .....................105
9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 144 7.12.2. Usage Example ....................................105
9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 146 7.13. The "uses" Statement ....................................106
9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 147 7.13.1. The uses's Substatements .........................106
9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 147 7.13.2. The "refine" Statement ...........................106
9.7.2. Lexical Representation . . . . . . . . . . . . . . . 147 7.13.3. XML Encoding Rules ...............................107
9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 7.13.4. Usage Example ....................................107
9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 148 7.14. The "rpc" Statement .....................................108
9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 149 7.14.1. The rpc's Substatements ..........................109
9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 150 7.14.2. The "input" Statement ............................109
9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 150 7.14.3. The "output" Statement ...........................110
9.8.2. Lexical Representation . . . . . . . . . . . . . . . 150 7.14.4. NETCONF XML Encoding Rules .......................111
9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 150 7.14.5. Usage Example ....................................112
9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 150
9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151 7.15. The "action" Statement ..................................113
9.9.2. The path Statement . . . . . . . . . . . . . . . . . 151 7.15.1. The action's Substatements .......................114
9.9.3. The require-instance Statement . . . . . . . . . . . 152 7.15.2. NETCONF XML Encoding Rules .......................114
9.9.4. Lexical Representation . . . . . . . . . . . . . . . 152 7.15.3. Usage Example ....................................115
9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 152 7.16. The "notification" Statement ............................116
9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 152 7.16.1. The notification's Substatements .................117
9.10. The identityref Built-In Type . . . . . . . . . . . . . . 156 7.16.2. NETCONF XML Encoding Rules .......................117
9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 156 7.16.3. Usage Example ....................................118
9.10.2. The identityref's base Statement . . . . . . . . . . 156 7.17. The "augment" Statement .................................119
9.10.3. Lexical Representation . . . . . . . . . . . . . . . 156 7.17.1. The augment's Substatements ......................121
9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 157 7.17.2. XML Encoding Rules ...............................121
9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 157 7.17.3. Usage Example ....................................122
9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 158 7.18. The "identity" Statement ................................124
9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 158 7.18.1. The identity's Substatements .....................124
9.11.2. Lexical Representation . . . . . . . . . . . . . . . 158 7.18.2. The "base" Statement .............................124
9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 158 7.18.3. Usage Example ....................................125
9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 158 7.19. The "extension" Statement ...............................126
9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 159 7.19.1. The extension's Substatements ....................126
9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 159 7.19.2. The "argument" Statement .........................127
9.12.2. Lexical Representation . . . . . . . . . . . . . . . 159 7.19.3. Usage Example ....................................127
9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 159 7.20. Conformance-Related Statements ..........................128
9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 159 7.20.1. The "feature" Statement ..........................128
9.13. The instance-identifier Built-In Type . . . . . . . . . . 160 7.20.2. The "if-feature" Statement .......................130
9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 161 7.20.3. The "deviation" Statement ........................131
9.13.2. Lexical Representation . . . . . . . . . . . . . . . 161 7.21. Common Statements .......................................134
9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 161 7.21.1. The "config" Statement ...........................134
9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 162 7.21.2. The "status" Statement ...........................135
10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 162 7.21.3. The "description" Statement ......................136
10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 162 7.21.4. The "reference" Statement ........................136
10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 162 7.21.5. The "when" Statement .............................136
10.2. Functions for Strings . . . . . . . . . . . . . . . . . 163 8. Constraints ...................................................138
10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 163 8.1. Constraints on Data ......................................138
10.3. Functions for the YANG Types "leafref" and "instance- 8.2. Configuration Data Modifications .........................139
identifier" . . . . . . . . . . . . . . . . . . . . . . 164 8.3. NETCONF Constraint Enforcement Model .....................139
10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 164 8.3.1. Payload Parsing ...................................139
10.4. Functions for the YANG Type "identityref" . . . . . . . 165 8.3.2. NETCONF <edit-config> Processing ..................140
10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 165 8.3.3. Validation ........................................141
10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 166 9. Built-In Types ................................................141
10.5. Functions for the YANG Type "enumeration" . . . . . . . 167 9.1. Canonical Representation .................................141
10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 167 9.2. The Integer Built-In Types ...............................142
10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 168 9.2.1. Lexical Representation ............................142
10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 168 9.2.2. Canonical Form ....................................143
11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 169 9.2.3. Restrictions ......................................143
12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 171 9.2.4. The "range" Statement .............................143
13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 9.2.5. Usage Example .....................................144
13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 172
13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 175 9.3. The decimal64 Built-In Type ..............................144
14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 176 9.3.1. Lexical Representation ............................145
15. NETCONF Error Responses for YANG Related Errors . . . . . . . 200 9.3.2. Canonical Form ....................................145
15.1. Error Message for Data That Violates a unique Statement 201 9.3.3. Restrictions ......................................145
15.2. Error Message for Data That Violates a max-elements 9.3.4. The "fraction-digits" Statement ...................145
Statement . . . . . . . . . . . . . . . . . . . . . . . 201 9.3.5. Usage Example .....................................146
15.3. Error Message for Data That Violates a min-elements 9.4. The string Built-In Type .................................146
Statement . . . . . . . . . . . . . . . . . . . . . . . 201 9.4.1. Lexical Representation ............................146
15.4. Error Message for Data That Violates a must Statement . 201 9.4.2. Canonical Form ....................................147
15.5. Error Message for Data That Violates a require-instance 9.4.3. Restrictions ......................................147
Statement . . . . . . . . . . . . . . . . . . . . . . . 202 9.4.4. The "length" Statement ............................147
15.6. Error Message for Data That Violates a mandatory choice 9.4.5. The "pattern" Statement ...........................148
Statement . . . . . . . . . . . . . . . . . . . . . . . 202 9.4.6. The "modifier" Statement ..........................148
15.7. Error Message for the "insert" Operation . . . . . . . . 202 9.4.7. Usage Example .....................................149
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 202 9.5. The boolean Built-In Type ................................150
17. Security Considerations . . . . . . . . . . . . . . . . . . . 203 9.5.1. Lexical Representation ............................150
18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 203 9.5.2. Canonical Form ....................................150
19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 204 9.5.3. Restrictions ......................................150
20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 204 9.6. The enumeration Built-In Type ............................150
20.1. Version -10 . . . . . . . . . . . . . . . . . . . . . . 204 9.6.1. Lexical Representation ............................150
20.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . 204 9.6.2. Canonical Form ....................................151
20.3. Version -08 . . . . . . . . . . . . . . . . . . . . . . 204 9.6.3. Restrictions ......................................151
20.4. Version -07 . . . . . . . . . . . . . . . . . . . . . . 205 9.6.4. The "enum" Statement ..............................151
20.5. Version -06 . . . . . . . . . . . . . . . . . . . . . . 205 9.6.5. Usage Example .....................................152
20.6. Version -05 . . . . . . . . . . . . . . . . . . . . . . 205 9.7. The bits Built-In Type ...................................154
20.7. Version -04 . . . . . . . . . . . . . . . . . . . . . . 205 9.7.1. Restrictions ......................................154
20.8. Version -03 . . . . . . . . . . . . . . . . . . . . . . 205 9.7.2. Lexical Representation ............................154
20.9. Version -02 . . . . . . . . . . . . . . . . . . . . . . 206 9.7.3. Canonical Form ....................................154
20.10. Version -01 . . . . . . . . . . . . . . . . . . . . . . 206 9.7.4. The "bit" Statement ...............................155
20.11. Version -00 . . . . . . . . . . . . . . . . . . . . . . 206 9.7.5. Usage Example .....................................156
21. References . . . . . . . . . . . . . . . . . . . . . . . . . 206 9.8. The binary Built-In Type .................................157
21.1. Normative References . . . . . . . . . . . . . . . . . . 207 9.8.1. Restrictions ......................................157
21.2. Informative References . . . . . . . . . . . . . . . . . 208 9.8.2. Lexical Representation ............................157
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 209 9.8.3. Canonical Form ....................................157
9.9. The leafref Built-In Type ................................157
9.9.1. Restrictions ......................................158
9.9.2. The "path" Statement ..............................158
9.9.3. The "require-instance" Statement ..................159
9.9.4. Lexical Representation ............................159
9.9.5. Canonical Form ....................................159
9.9.6. Usage Example .....................................159
9.10. The identityref Built-In Type ...........................163
9.10.1. Restrictions .....................................163
9.10.2. The identityref's "base" Statement ...............163
9.10.3. Lexical Representation ...........................163
9.10.4. Canonical Form ...................................164
9.10.5. Usage Example ....................................164
9.11. The empty Built-In Type .................................165
9.11.1. Restrictions .....................................165
9.11.2. Lexical Representation ...........................165
9.11.3. Canonical Form ...................................165
9.11.4. Usage Example ....................................166
9.12. The union Built-In Type .................................166
9.12.1. Restrictions .....................................166
9.12.2. Lexical Representation ...........................166
9.12.3. Canonical Form ...................................167
9.12.4. Usage Example ....................................167
9.13. The instance-identifier Built-In Type ...................168
9.13.1. Restrictions .....................................168
9.13.2. Lexical Representation ...........................169
9.13.3. Canonical Form ...................................169
9.13.4. Usage Example ....................................169
10. XPath Functions ..............................................170
10.1. Function for Node Sets ..................................170
10.1.1. current() ........................................170
10.2. Function for Strings ....................................170
10.2.1. re-match() .......................................170
10.3. Function for the YANG Types "leafref" and
"instance-identifier" ...................................171
10.3.1. deref() ..........................................171
10.4. Functions for the YANG Type "identityref" ...............172
10.4.1. derived-from() ...................................172
10.4.2. derived-from-or-self() ...........................174
10.5. Function for the YANG Type "enumeration" ................174
10.5.1. enum-value() .....................................174
10.6. Function for the YANG Type "bits" .......................175
10.6.1. bit-is-set() .....................................175
11. Updating a Module ............................................176
12. Coexistence with YANG Version 1 ..............................179
13. YIN ..........................................................179
13.1. Formal YIN Definition ...................................180
13.1.1. Usage Example ....................................182
14. YANG ABNF Grammar ............................................184
15. NETCONF Error Responses for YANG-Related Errors ..............211
15.1. Error Message for Data That Violates a "unique"
Statement ...............................................211
15.2. Error Message for Data That Violates a
"max-elements" Statement ................................211
15.3. Error Message for Data That Violates a
"min-elements" Statement ................................211
15.4. Error Message for Data That Violates a "must"
Statement ...............................................212
15.5. Error Message for Data That Violates a
"require-instance" Statement ............................212
15.6. Error Message for Data That Violates a Mandatory
"choice" Statement ......................................212
15.7. Error Message for the "insert" Operation ................212
16. IANA Considerations ..........................................213
17. Security Considerations ......................................213
18. References ...................................................214
18.1. Normative References ....................................214
18.2. Informative References ..................................215
Acknowledgements .................................................217
Contributors .....................................................217
Author's Address .................................................217
1. Introduction 1. Introduction
YANG is a data modeling language originally designed to model YANG is a data modeling language originally designed to model
configuration and state data manipulated by the Network Configuration configuration and state data manipulated by the Network Configuration
Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF Protocol (NETCONF), NETCONF Remote Procedure Calls, and NETCONF
notifications [RFC6241]. Since the publication of YANG version 1 notifications [RFC6241]. Since the publication of YANG version 1
[RFC6020], YANG has been used or proposed to be used for other [RFC6020], YANG has been used or proposed to be used for other
protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI protocols (e.g., RESTCONF [RESTCONF] and the Constrained Application
[I-D.vanderstok-core-comi]). Further, other encodings than XML have Protocol (CoAP) Management Interface (CoMI) [CoMI]). Further,
been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]). encodings other than XML have been proposed (e.g., JSON [RFC7951]).
This document describes the syntax and semantics of version 1.1 of This document describes the syntax and semantics of version 1.1 of
the YANG language. It also describes how a data model defined in a the YANG language. It also describes how a data model defined in a
YANG module is encoded in the Extensible Markup Language (XML), and YANG module is encoded in the Extensible Markup Language (XML) [XML]
how NETCONF operations are used to manipulate the data. Other and how NETCONF operations are used to manipulate the data. Other
protocols and encodings are possible, but out of scope for this protocols and encodings are possible but are out of scope for this
specification. specification.
In terms of developing YANG data models, [I-D.ietf-netmod-rfc6087bis] In terms of developing YANG data models, [YANG-Guidelines] provides
provides some guidelines and recommendations. some guidelines and recommendations.
Note that this document does not obsolete RFC 6020 [RFC6020]. Note that this document does not obsolete RFC 6020 [RFC6020].
1.1. Summary of Changes from RFC 6020 1.1. Summary of Changes from RFC 6020
This document defines version 1.1 of the YANG language. YANG version This document defines version 1.1 of the YANG language. YANG
1.1 is a maintenance release of the YANG language, addressing version 1.1 is a maintenance release of the YANG language, addressing
ambiguities and defects in the original specification [RFC6020]. ambiguities and defects in the original specification [RFC6020].
The following changes are not backwards compatible with YANG version The following changes are not backward compatible with YANG
1: version 1:
o Changed the rules for the interpretation of escaped characters in o Changed the rules for the interpretation of escaped characters in
double quoted strings. This is an backwards incompatible change double-quoted strings. This is a backward-incompatible change
from YANG version 1. When updating a YANG version 1 module to from YANG version 1. When updating a YANG version 1 module to 1.1
1.1, and the module uses a character sequence that is now illegal, and the module uses a character sequence that is now illegal, the
the string must be changed to match the new rules. See string must be changed to match the new rules. See Section 6.1.3
Section 6.1.3 for details. for details.
o An unquoted string cannot contain any single or double quote o An unquoted string cannot contain any single or double quote
characters. This is an backwards incompatible change from YANG characters. This is a backward-incompatible change from YANG
version 1. When updating a YANG version 1 module to 1.1, and the version 1. When updating a YANG version 1 module to 1.1 and the
module uses such quote characters, the string must be changed to module uses such quote characters, the string must be changed to
match the new rules. See Section 6.1.3 for details. match the new rules. See Section 6.1.3 for details.
o Made "when" and "if-feature" illegal on list keys. This is an o Made "when" and "if-feature" illegal on list keys. This is a
backwards incompatible change from YANG version 1. When updating backward-incompatible change from YANG version 1. When updating a
a YANG version 1 module to 1.1, and the module uses these YANG version 1 module to 1.1 and the module uses these constructs,
constructs, they must be removed to match the new rules. they must be removed to match the new rules.
o Defined the legal characters in YANG modules. When updating a o Defined the legal characters in YANG modules. When updating a
YANG version 1 module to 1.1, any characters that are now illegal YANG version 1 module to 1.1, any characters that are now illegal
must be removed. See Section 6 for details. must be removed. See Section 6 for details.
o Made noncharacters illegal in the built-in type "string". This o Made noncharacters illegal in the built-in type "string". This
change affects the run-time behavior of YANG-based protocols. change affects the runtime behavior of YANG-based protocols.
The following additional changes have been done to YANG: The following additional changes have been done to YANG:
o Changed the YANG version from "1" to "1.1". o Changed the YANG version from "1" to "1.1".
o Made the "yang-version" statement mandatory in YANG version "1.1". o Made the "yang-version" statement mandatory in YANG version "1.1".
o Extended the "if-feature" syntax to be a boolean expression over o Extended the "if-feature" syntax to be a boolean expression over
feature names. feature names.
o Allow "if-feature" in "bit", "enum", and "identity". o Allow "if-feature" in "bit", "enum", and "identity".
o Allow "if-feature" in "refine". o Allow "if-feature" in "refine".
o Allow "choice" as a shorthand case statement (see Section 7.9). o Allow "choice" as a shorthand "case" statement (see
Section 7.9.2).
o Added a new substatement "modifier" to pattern (see o Added a new substatement "modifier" to the "pattern" statement
Section 9.4.6). (see Section 9.4.6).
o Allow "must" in "input", "output", and "notification". o Allow "must" in "input", "output", and "notification".
o Allow "require-instance" in leafref. o Allow "require-instance" in leafref.
o Allow "description" and "reference" in "import" and "include". o Allow "description" and "reference" in "import" and "include".
o Allow imports of multiple revisions of a module. o Allow imports of multiple revisions of a module.
o Allow "augment" to add conditionally mandatory nodes (see o Allow "augment" to add conditionally mandatory nodes (see
Section 7.17). Section 7.17).
o Added a set of new XPath functions in Section 10. o Added a set of new XML Path Language (XPath) functions in
Section 10.
o Clarified the XPath context's tree in Section 6.4.1. o Clarified the XPath context's tree in Section 6.4.1.
o Defined the string value of an identityref in XPath expressions o Defined the string value of an identityref in XPath expressions
(see Section 9.10). (see Section 9.10).
o Clarified what unprefixed names mean in leafrefs in typedefs (see o Clarified what unprefixed names mean in leafrefs in typedefs (see
Section 6.4.1 and Section 9.9.2). Sections 6.4.1 and 9.9.2).
o Allow identities to be derived from multiple base identities (see o Allow identities to be derived from multiple base identities (see
Section 7.18 and Section 9.10). Sections 7.18 and 9.10).
o Allow enumerations and bits to be subtyped (see Section 9.6 and o Allow enumerations and bits to be subtyped (see Sections 9.6
Section 9.7). and 9.7).
o Allow leaf-lists to have default values (see Section 7.7.2). o Allow leaf-lists to have default values (see Section 7.7.2).
o Allow non-unique values in non-configuration leaf-lists (see o Allow non-unique values in non-configuration leaf-lists (see
Section 7.7). Section 7.7).
o Use [RFC7405] syntax for case-sensitive strings in the grammar. o Use syntax for case-sensitive strings (as per [RFC7405]) in the
grammar.
o Changed the module advertisement mechanism (see Section 5.6.4). o Changed the module advertisement mechanism (see Section 5.6.4).
o Changed the scoping rules for definitions in submodules. A o Changed the scoping rules for definitions in submodules. A
submodule can now reference all definitions in all submodules that submodule can now reference all definitions in all submodules that
belong to the same module, without using the "include" statement. belong to the same module, without using the "include" statement.
o Added a new statement "action" that is used to define operations o Added a new statement "action", which is used to define operations
tied to data nodes. tied to data nodes.
o Allow notifications to be tied to data nodes. o Allow notifications to be tied to data nodes.
o Added a new data definition statement "anydata" (see Section 7.10) o Added a new data definition statement "anydata" (see
which is RECOMMENDED to be used instead of "anyxml" when the data Section 7.10), which is RECOMMENDED to be used instead of "anyxml"
can be modeled in YANG when the data can be modeled in YANG.
o Allow types empty and leafref in unions. o Allow types "empty" and "leafref" in unions.
o Allow type empty in a key. o Allow type "empty" in a key.
o Removed the restriction that identifiers could not start with the
characters "xml".
The following changes have been done to the NETCONF mapping: The following changes have been done to the NETCONF mapping:
o A server advertises support for YANG 1.1 modules by using ietf- o A server advertises support for YANG 1.1 modules by using
yang-library [I-D.ietf-netconf-yang-library] instead of listing ietf-yang-library [RFC7895] instead of listing them as
them as capabilities in the <hello> message. capabilities in the <hello> message.
2. Keywords 2. Key Words
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14, [RFC2119]. BCP 14 [RFC2119].
3. Terminology 3. Terminology
The following terms are used within this document: The following terms are used within this document:
o action: An operation defined for a node in the data tree. o action: An operation defined for a node in the data tree.
o anydata: A data node that can contain an unknown set of nodes that o anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG, except anyxml. can be modeled by YANG, except anyxml.
o anyxml: A data node that can contain an unknown chunk of XML data. o anyxml: A data node that can contain an unknown chunk of XML data.
o augment: Adds new schema nodes to a previously defined schema o augment: Adds new schema nodes to a previously defined schema
node. node.
o base type: The type from which a derived type was derived, which o base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type. may be either a built-in type or another derived type.
o built-in type: A YANG data type defined in the YANG language, such o built-in type: A YANG data type defined in the YANG language, such
skipping to change at page 12, line 16 skipping to change at page 13, line 19
over some network management protocol. over some network management protocol.
o conformance: A measure of how accurately a server follows a data o conformance: A measure of how accurately a server follows a data
model. model.
o container: An interior data node that exists in at most one o container: An interior data node that exists in at most one
instance in the data tree. A container has no value, but rather a instance in the data tree. A container has no value, but rather a
set of child nodes. set of child nodes.
o data definition statement: A statement that defines new data o data definition statement: A statement that defines new data
nodes. One of container, leaf, leaf-list, list, choice, case, nodes. One of "container", "leaf", "leaf-list", "list", "choice",
augment, uses, anydata, and anyxml. "case", "augment", "uses", "anydata", and "anyxml".
o data model: A data model describes how data is represented and o data model: A data model describes how data is represented and
accessed. accessed.
o data node: A node in the schema tree that can be instantiated in a o data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, list, anydata, and data tree. One of container, leaf, leaf-list, list, anydata, and
anyxml. anyxml.
o data tree: An instantiated tree of any data modeled with YANG, o data tree: An instantiated tree of any data modeled with YANG,
e.g., configuration data, state data, combined configuration and e.g., configuration data, state data, combined configuration and
state data, RPC or action input, RPC or action output, or state data, RPC or action input, RPC or action output, or
notification. notification.
o derived type: A type that is derived from a built-in type (such as o derived type: A type that is derived from a built-in type (such as
uint32), or another derived type. uint32) or another derived type.
o extension: An extension attaches non-YANG semantics to statements. o extension: An extension attaches non-YANG semantics to statements.
The extension statement defines new statements to express these The "extension" statement defines new statements to express these
semantics. semantics.
o feature: A mechanism for marking a portion of the model as o feature: A mechanism for marking a portion of the model as
optional. Definitions can be tagged with a feature name and are optional. Definitions can be tagged with a feature name and are
only valid on servers that support that feature. only valid on servers that support that feature.
o grouping: A reusable set of schema nodes, which may be used o grouping: A reusable set of schema nodes, which may be used
locally in the module and by other modules that import from it. locally in the module and by other modules that import from it.
The grouping statement is not a data definition statement and, as The "grouping" statement is not a data definition statement and,
such, does not define any nodes in the schema tree. as such, does not define any nodes in the schema tree.
o identifier: A string used to identify different kinds of YANG o identifier: A string used to identify different kinds of YANG
items by name. items by name.
o identity: A globally unique, abstract, and untyped name. o identity: A globally unique, abstract, and untyped name.
o instance identifier: A mechanism for identifying a particular node o instance identifier: A mechanism for identifying a particular node
in a data tree. in a data tree.
o interior node: Nodes within a hierarchy that are not leaf nodes. o interior node: Nodes within a hierarchy that are not leaf nodes.
skipping to change at page 13, line 29 skipping to change at page 14, line 31
nodes. nodes.
o mandatory node: A mandatory node is one of: o mandatory node: A mandatory node is one of:
* A leaf, choice, anydata, or anyxml node with a "mandatory" * A leaf, choice, anydata, or anyxml node with a "mandatory"
statement with the value "true". statement with the value "true".
* A list or leaf-list node with a "min-elements" statement with a * A list or leaf-list node with a "min-elements" statement with a
value greater than zero. value greater than zero.
* A container node without a "presence" statement and which has * A container node without a "presence" statement and that has at
at least one mandatory node as a child. least one mandatory node as a child.
o module: A YANG module defines hierarchies of schema nodes. With o module: A YANG module defines hierarchies of schema nodes. With
its definitions and the definitions it imports or includes from its definitions and the definitions it imports or includes from
elsewhere, a module is self-contained and "compilable". elsewhere, a module is self-contained and "compilable".
o non-presence container: A container that has no meaning of its o non-presence container: A container that has no meaning of its
own, existing only to contain child nodes. own, existing only to contain child nodes.
o presence container: A container where the presence of the o presence container: A container where the presence of the
container itself carries some meaning. container itself carries some meaning.
skipping to change at page 14, line 19 skipping to change at page 15, line 22
o server deviation: A failure of the server to implement a module o server deviation: A failure of the server to implement a module
faithfully. faithfully.
o submodule: A partial module definition that contributes derived o submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, actions, and notifications to types, groupings, data nodes, RPCs, actions, and notifications to
a module. A YANG module can be constructed from a number of a module. A YANG module can be constructed from a number of
submodules. submodules.
o top-level data node: A data node where there is no other data node o top-level data node: A data node where there is no other data node
between it and a module or submodule statement. between it and a "module" or "submodule" statement.
o uses: The "uses" statement is used to instantiate the set of o uses: The "uses" statement is used to instantiate the set of
schema nodes defined in a grouping statement. The instantiated schema nodes defined in a "grouping" statement. The instantiated
nodes may be refined and augmented to tailor them to any specific nodes may be refined and augmented to tailor them to any specific
needs. needs.
o value space: For a data type; the set of values permitted by the o value space: For a data type; the set of values permitted by the
data type. For a leaf or leaf-list instance; the value space of data type. For a leaf or leaf-list instance; the value space of
its data type. its data type.
The following terms are defined in [RFC6241]: The following terms are defined in [RFC6241]:
o configuration data o configuration data
o configuration datastore o configuration datastore
o datastore o datastore
o state data o state data
When modelled with YANG, a datastore is realized as an instantiated When modeled with YANG, a datastore is realized as an instantiated
data tree. data tree.
When modelled with YANG, a configuration datastore is realized as an When modeled with YANG, a configuration datastore is realized as an
instantiated data tree with configuration data. instantiated data tree with configuration data.
3.1. A Note on Examples 3.1. A Note on Examples
Throughout this document there are many examples of YANG statements. Throughout this document, there are many examples of YANG statements.
These examples are supposed to illustrate certain features, and are These examples are supposed to illustrate certain features and are
not supposed to be complete, valid YANG modules. not supposed to be complete, valid YANG modules.
4. YANG Overview 4. YANG Overview
This non-normative section is intended to give a high-level overview This non-normative section is intended to give a high-level overview
of YANG to first-time readers. of YANG to first-time readers.
4.1. Functional Overview 4.1. Functional Overview
YANG is a language originally designed to model data for the NETCONF YANG is a language originally designed to model data for the NETCONF
protocol. A YANG module defines hierarchies of data that can be used protocol. A YANG module defines hierarchies of data that can be used
for NETCONF-based operations, including configuration, state data, for NETCONF-based operations, including configuration, state data,
Remote Procedure Calls (RPCs), and notifications. This allows a RPCs, and notifications. This allows a complete description of all
complete description of all data sent between a NETCONF client and data sent between a NETCONF client and server. Although out of scope
server. Although out of scope for this specification, YANG can also for this specification, YANG can also be used with protocols other
be used with other protocols than NETCONF. than NETCONF.
YANG models the hierarchical organization of data as a tree in which 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. 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 YANG provides clear and concise descriptions of the nodes, as well as
the interaction between those nodes. the interaction between those nodes.
YANG structures data models into modules and submodules. A module YANG structures data models into modules and submodules. A module
can import definitions from other external modules, and include can import definitions from other external modules and can include
definitions from submodules. The hierarchy can be augmented, definitions from submodules. The hierarchy can be augmented,
allowing one module to add data nodes to the hierarchy defined in allowing one module to add data nodes to the hierarchy defined in
another module. This augmentation can be conditional, with new nodes another module. This augmentation can be conditional, with new nodes
appearing only if certain conditions are met. appearing only if certain conditions are met.
YANG data models can describe constraints to be enforced on the data, YANG data models can describe constraints to be enforced on the data,
restricting the presence or value of nodes based on the presence or restricting the presence or value of nodes based on the presence or
value of other nodes in the hierarchy. These constraints are value of other nodes in the hierarchy. These constraints are
enforceable by either the client or the server. enforceable by either the client or the server.
YANG defines a set of built-in types, and has a type mechanism YANG defines a set of built-in types and has a type mechanism through
through which additional types may be defined. Derived types can which additional types may be defined. Derived types can restrict
restrict their base type's set of valid values using mechanisms like their base type's set of valid values using mechanisms like range or
range or pattern restrictions that can be enforced by clients or pattern restrictions that can be enforced by clients or servers.
servers. They can also define usage conventions for use of the They can also define usage conventions for use of the derived type,
derived type, such as a string-based type that contains a host name. such as a string-based type that contains a hostname.
YANG permits the definition of reusable groupings of nodes. The YANG permits the definition of reusable groupings of nodes. The
usage of these groupings can refine or augment the nodes, allowing it usage of these groupings can refine or augment the nodes, allowing it
to tailor the nodes to its particular needs. Derived types and to tailor the nodes to its particular needs. Derived types and
groupings can be defined in one module and used in either the same groupings can be defined in one module and used in either the same
module or in another module that imports it. module or another module that imports it.
YANG data hierarchy constructs include defining lists where list YANG data hierarchy constructs include defining lists where list
entries are identified by keys that distinguish them from each other. entries are identified by keys that distinguish them from each other.
Such lists may be defined as either sorted by user or automatically Such lists may be defined as either sorted by user or automatically
sorted by the system. For user-sorted lists, operations are defined sorted by the system. For user-sorted lists, operations are defined
for manipulating the order of the list entries. for manipulating the order of the list entries.
YANG modules can be translated into an equivalent XML syntax called YANG modules can be translated into an equivalent XML syntax called
YANG Independent Notation (YIN) (Section 13), allowing applications YANG Independent Notation (YIN) (Section 13), allowing applications
using XML parsers and Extensible Stylesheet Language Transformations using XML parsers and Extensible Stylesheet Language Transformations
(XSLT) scripts to operate on the models. The conversion from YANG to (XSLT) scripts to operate on the models. The conversion from YANG to
YIN is semantically lossless, so content in YIN can be round-tripped YIN is semantically lossless, so content in YIN can be round-tripped
back into YANG. back into YANG.
YANG is an extensible language, allowing extension statements to be YANG is an extensible language, allowing extensions to be defined by
defined by standards bodies, vendors, and individuals. The statement standards bodies, vendors, and individuals. The statement syntax
syntax allows these extensions to coexist with standard YANG allows these extensions to coexist with standard YANG statements in a
statements in a natural way, while extensions in a YANG module stand natural way, while extensions in a YANG module stand out sufficiently
out sufficiently for the reader to notice them. for the reader to notice them.
YANG resists the tendency to solve all possible problems, limiting YANG resists the tendency to solve all possible problems, limiting
the problem space to allow expression of data models for network the problem space to allow expression of data models for network
management protocols such as NETCONF, not arbitrary XML documents or management protocols such as NETCONF, not arbitrary XML documents or
arbitrary data models. arbitrary data models.
To the extent possible, YANG maintains compatibility with Simple To the extent possible, YANG maintains compatibility with the Simple
Network Management Protocol's (SNMP's) SMIv2 (Structure of Management Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules Information version 2 [RFC2578] [RFC2579]). SMIv2-based MIB modules
can be automatically translated into YANG modules for read-only can be automatically translated into YANG modules for read-only
access [RFC6643]. However, YANG is not concerned with reverse access [RFC6643]. However, YANG is not concerned with reverse
translation from YANG to SMIv2. translation from YANG to SMIv2.
4.2. Language Overview 4.2. Language Overview
This section introduces some important constructs used in YANG that This section introduces some important constructs used in YANG that
will aid in the understanding of the language specifics in later will aid in the understanding of the language specifics in later
sections. sections.
4.2.1. Modules and Submodules 4.2.1. Modules and Submodules
YANG data models are defined in modules. A module contains a YANG data models are defined in modules. A module contains a
collection of related definitions. collection of related definitions.
A module contains three types of statements: module-header A module contains three types of statements: module header
statements, revision statements, and definition statements. The statements, "revision" statements, and definition statements. The
module header statements describe the module and give information module header statements describe the module and give information
about the module itself, the revision statements give information about the module itself, the "revision" statements give information
about the history of the module, and the definition statements are about the history of the module, and the definition statements are
the body of the module where the data model is defined. the body of the module where the data model is defined.
A server may implement a number of modules, allowing multiple views A server may implement a number of modules, allowing multiple views
of the same data, or multiple views of disjoint subsections of the of the same data or multiple views of disjoint subsections of the
server's data. Alternatively, the server may implement only one server's data. Alternatively, the server may implement only one
module that defines all available data. module that defines all available data.
A module may have portions of its definitions separated into A module may have portions of its definitions separated into
submodules, based on the needs of the module designer. The external submodules, based on the needs of the module designer. The external
view remains that of a single module, regardless of the presence or view remains that of a single module, regardless of the presence or
size of its submodules. size of its submodules.
The "import" statement allows a module or submodule to reference The "import" statement allows a module or submodule to reference
definitions defined in other modules. definitions defined in other modules.
skipping to change at page 17, line 35 skipping to change at page 19, line 22
4.2.2.1. Leaf Nodes 4.2.2.1. Leaf Nodes
A leaf instance contains simple data like an integer or a string. It A leaf instance contains simple data like an integer or a string. It
has exactly one value of a particular type and no child nodes. has exactly one value of a particular type and no child nodes.
YANG Example: YANG Example:
leaf host-name { leaf host-name {
type string; type string;
description description
"Hostname for this system"; "Hostname for this system.";
} }
XML Encoding Example: XML Encoding Example:
<host-name>my.example.com</host-name> <host-name>my.example.com</host-name>
The "leaf" statement is covered in Section 7.6. The "leaf" statement is covered in Section 7.6.
4.2.2.2. Leaf-List Nodes 4.2.2.2. Leaf-List Nodes
A leaf-list defines a sequence of values of a particular type. A leaf-list defines a sequence of values of a particular type.
YANG Example: YANG Example:
leaf-list domain-search { leaf-list domain-search {
type string; type string;
description description
"List of domain names to search"; "List of domain names to search.";
} }
XML Encoding Example: XML Encoding Example:
<domain-search>high.example.com</domain-search> <domain-search>high.example.com</domain-search>
<domain-search>low.example.com</domain-search> <domain-search>low.example.com</domain-search>
<domain-search>everywhere.example.com</domain-search> <domain-search>everywhere.example.com</domain-search>
The "leaf-list" statement is covered in Section 7.7. The "leaf-list" statement is covered in Section 7.7.
4.2.2.3. Container Nodes 4.2.2.3. Container Nodes
A container is used to group related nodes in a subtree. A container A container is used to group related nodes in a subtree. A container
has only child nodes and no value. A container may contain any has only child nodes and no value. A container may contain any
number of child nodes of any type (leafs, lists, containers, leaf- number of child nodes of any type (leafs, lists, containers,
lists, actions, and notifications). leaf-lists, actions, and notifications).
YANG Example: YANG Example:
container system { container system {
container login { container login {
leaf message { leaf message {
type string; type string;
description description
"Message given at start of login session"; "Message given at start of login session.";
} }
} }
} }
XML Encoding Example: XML Encoding Example:
<system> <system>
<login> <login>
<message>Good morning</message> <message>Good morning</message>
</login> </login>
</system> </system>
The "container" statement is covered in Section 7.5. The "container" statement is covered in Section 7.5.
4.2.2.4. List Nodes 4.2.2.4. List Nodes
A list defines a sequence of list entries. Each entry is like a A list defines a sequence of list entries. Each entry is like a
container, and is uniquely identified by the values of its key leafs, container and is uniquely identified by the values of its key leafs
if it has any key leafs defined. A list can define multiple key if it has any key leafs defined. A list can define multiple key
leafs and may contain any number of child nodes of any type leafs and may contain any number of child nodes of any type
(including leafs, lists, containers etc.). (including leafs, lists, containers, etc.).
YANG Example: YANG Example:
list user { list user {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf full-name { leaf full-name {
type string; type string;
skipping to change at page 20, line 17 skipping to change at page 22, line 28
"The module for entities implementing the Example system."; "The module for entities implementing the Example system.";
revision 2007-06-09 { revision 2007-06-09 {
description "Initial revision."; description "Initial revision.";
} }
container system { container system {
leaf host-name { leaf host-name {
type string; type string;
description description
"Hostname for this system"; "Hostname for this system.";
} }
leaf-list domain-search { leaf-list domain-search {
type string; type string;
description description
"List of domain names to search"; "List of domain names to search.";
} }
container login { container login {
leaf message { leaf message {
type string; type string;
description description
"Message given at start of login session"; "Message given at start of login session.";
} }
list user { list user {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf full-name { leaf full-name {
type string; type string;
} }
leaf class { leaf class {
type string; type string;
skipping to change at page 23, line 20 skipping to change at page 25, line 42
Groups of nodes can be assembled into reusable collections using the Groups of nodes can be assembled into reusable collections using the
"grouping" statement. A grouping defines a set of nodes that are "grouping" statement. A grouping defines a set of nodes that are
instantiated with the "uses" statement. instantiated with the "uses" statement.
YANG Example: YANG Example:
grouping target { grouping target {
leaf address { leaf address {
type inet:ip-address; type inet:ip-address;
description "Target IP address"; description "Target IP address.";
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
description "Target port number"; description "Target port number.";
} }
} }
container peer { container peer {
container destination { container destination {
uses target; uses target;
} }
} }
XML Encoding Example: XML Encoding Example:
<peer> <peer>
<destination> <destination>
skipping to change at page 24, line 9 skipping to change at page 26, line 27
</peer> </peer>
The grouping can be refined as it is used, allowing certain The grouping can be refined as it is used, allowing certain
statements to be overridden. In this example, the description is statements to be overridden. In this example, the description is
refined: refined:
container connection { container connection {
container source { container source {
uses target { uses target {
refine "address" { refine "address" {
description "Source IP address"; description "Source IP address.";
} }
refine "port" { refine "port" {
description "Source port number"; description "Source port number.";
} }
} }
} }
container destination { container destination {
uses target { uses target {
refine "address" { refine "address" {
description "Destination IP address"; description "Destination IP address.";
} }
refine "port" { refine "port" {
description "Destination port number"; description "Destination port number.";
} }
} }
} }
} }
The "grouping" statement is covered in Section 7.12. The "grouping" statement is covered in Section 7.12.
4.2.7. Choices 4.2.7. Choices
YANG allows the data model to segregate incompatible nodes into YANG allows the data model to segregate incompatible nodes into
distinct choices using the "choice" and "case" statements. The distinct choices using the "choice" and "case" statements. The
"choice" statement contains a set of "case" statements that define "choice" statement contains a set of "case" statements that define
sets of schema nodes that cannot appear together. Each "case" may sets of schema nodes that cannot appear together. Each "case" may
contain multiple nodes, but each node may appear in only one "case" contain multiple nodes, but each node may appear in only one "case"
under a "choice". under a "choice".
The choice and case nodes appear only in the schema tree but not in The choice and case nodes appear only in the schema tree and not in
the data tree. The additional levels of hierarchy are not needed the data tree. The additional levels of hierarchy are not needed
beyond the conceptual schema. The presence of a case is indicated by beyond the conceptual schema. The presence of a case is indicated by
the presence of one or more of the nodes within it. the presence of one or more of the nodes within it.
Since only one of the choice's cases can be valid at any time, when a Since only one of the choice's cases can be valid at any time, when a
node from one case is created in the data tree, all nodes from all node from one case is created in the data tree, all nodes from all
other cases are implicitly deleted. The server handles the other cases are implicitly deleted. The server handles the
enforcement of the constraint, preventing incompatibilities from enforcement of the constraint, preventing incompatibilities from
existing in the configuration. existing in the configuration.
skipping to change at page 25, line 39 skipping to change at page 28, line 17
<food> <food>
<pretzel/> <pretzel/>
<beer/> <beer/>
</food> </food>
The "choice" statement is covered in Section 7.9. The "choice" statement is covered in Section 7.9.
4.2.8. Extending Data Models (augment) 4.2.8. Extending Data Models (augment)
YANG allows a module to insert additional nodes into data models, YANG allows a module to insert additional nodes into data models,
including both the current module (and its submodules) or an external including both the current module (and its submodules) and an
module. This is useful for example for vendors to add vendor- external module. This is useful, for example, for vendors to add
specific parameters to standard data models in an interoperable way. vendor-specific parameters to standard data models in an
interoperable way.
The "augment" statement defines the location in the data model The "augment" statement defines the location in the data model
hierarchy where new nodes are inserted, and the "when" statement hierarchy where new nodes are inserted, and the "when" statement
defines the conditions when the new nodes are valid. defines the conditions when the new nodes are valid.
When a server implements a module containing an "augment" statement, When a server implements a module containing an "augment" statement,
that implies that the server's implementation of the augmented module that implies that the server's implementation of the augmented module
contains the additional nodes. contains the additional nodes.
YANG Example: YANG Example:
augment /system/login/user { augment /system/login/user {
when "class != 'wheel'"; when "class != 'wheel'";
leaf uid { leaf uid {
type uint16 { type uint16 {
range "1000 .. 30000"; range "1000 .. 30000";
} }
} }
} }
This example defines a "uid" node that only is valid when the user's This example defines a "uid" node that is valid only when the user's
"class" is not "wheel". "class" is not "wheel".
If a module augments another module, the XML elements that are added If a module augments another module, the XML elements that are added
to the encoding are in the namespace of the augmenting module. For to the encoding are in the namespace of the augmenting module. For
example, if the above augmentation were in a module with prefix example, if the above augmentation were in a module with prefix
"other", the XML would look like: "other", the XML would look like:
XML Encoding Example: XML Encoding Example:
<user> <user>
<name>alicew</name> <name>alicew</name>
<full-name>Alice N. Wonderland</full-name> <full-name>Alice N. Wonderland</full-name>
<class>drop-out</class> <class>drop-out</class>
<other:uid>1024</other:uid> <other:uid>1024</other:uid>
</user> </user>
The "augment" statement is covered in Section 7.17. The "augment" statement is covered in Section 7.17.
4.2.9. Operation Definitions 4.2.9. Operation Definitions
YANG allows the definition of operations. The operations' name, YANG allows the definition of operations. The operations' names,
input parameters, and output parameters are modeled using YANG data input parameters, and output parameters are modeled using YANG data
definition statements. Operations on the top-level in a module are definition statements. Operations on the top level in a module are
defined with the "rpc" statement. Operations can also be tied to a defined with the "rpc" statement. Operations can also be tied to a
container or list data node. Such operations are defined with the container or list data node. Such operations are defined with the
"action" statement. "action" statement.
YANG Example for an operation at the top-level: YANG Example for an operation at the top level:
rpc activate-software-image { rpc activate-software-image {
input { input {
leaf image-name { leaf image-name {
type string; type string;
} }
} }
output { output {
leaf status { leaf status {
type string; type string;
skipping to change at page 28, line 47 skipping to change at page 31, line 26
</action> </action>
</rpc> </rpc>
<rpc-reply message-id="102" <rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:sys="http://example.com/system"> xmlns:sys="http://example.com/system">
<sys:packet-loss>60</sys:packet-loss> <sys:packet-loss>60</sys:packet-loss>
</rpc-reply> </rpc-reply>
The "rpc" statement is covered in Section 7.14, and the "action" The "rpc" statement is covered in Section 7.14, and the "action"
statement in Section 7.15. statement is covered in Section 7.15.
4.2.10. Notification Definitions 4.2.10. Notification Definitions
YANG allows the definition of notifications. YANG data definition YANG allows the definition of notifications. YANG data definition
statements are used to model the content of the notification. statements are used to model the content of the notification.
YANG Example: YANG Example:
notification link-failure { notification link-failure {
description description
"A link failure has been detected"; "A link failure has been detected.";
leaf if-name { leaf if-name {
type leafref { type leafref {
path "/interface/name"; path "/interface/name";
} }
} }
leaf if-admin-status { leaf if-admin-status {
type admin-status; type admin-status;
} }
leaf if-oper-status { leaf if-oper-status {
type oper-status; type oper-status;
skipping to change at page 30, line 31 skipping to change at page 33, line 8
the "include" statement to reference other submodules within its the "include" statement to reference other submodules within its
module, but this is not necessary in YANG version 1.1. A submodule module, but this is not necessary in YANG version 1.1. A submodule
can reference any definition in the module it belongs to and in all can reference any definition in the module it belongs to and in all
submodules included by the module. A submodule MUST NOT include submodules included by the module. A submodule MUST NOT include
different revisions of other submodules than the revisions that its different revisions of other submodules than the revisions that its
module includes. module includes.
A module or submodule MUST NOT include submodules from other modules, A module or submodule MUST NOT include submodules from other modules,
and a submodule MUST NOT import its own module. and a submodule MUST NOT import its own module.
The import and include statements are used to make definitions The "import" and "include" statements are used to make definitions
available from other modules: available from other modules:
o For a module or submodule to reference definitions in an external o For a module or submodule to reference definitions in an external
module, the external module MUST be imported. module, the external module MUST be imported.
o A module MUST include all its submodules. o A module MUST include all its submodules.
o A module, or submodule belonging to that module, MAY reference o A module, or submodule belonging to that module, MAY reference
definitions in the module and all submodules included by the definitions in the module and all submodules included by the
module. module.
There MUST NOT be any circular chains of imports. For example, if There MUST NOT be any circular chains of imports. For example, if
module "a" imports module "b", "b" cannot import "a". module "a" imports module "b", "b" cannot import "a".
When a definition in an external module is referenced, a locally When a definition in an external module is referenced, a locally
defined prefix MUST be used, followed by a colon (":"), and then the defined prefix MUST be used, followed by a colon (":") and then the
external identifier. References to definitions in the local module external identifier. References to definitions in the local module
MAY use the prefix notation. Since built-in data types do not belong 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 to any module and have no prefix, references to built-in data types
(e.g., int32) cannot use the prefix notation. The syntax for a (e.g., int32) cannot use the prefix notation. The syntax for a
reference to a definition is formally defined by the rule reference to a definition is formally defined by the rule
"identifier-ref" in Section 14. "identifier-ref" in Section 14.
5.1.1. Import and Include by Revision 5.1.1. Import and Include by Revision
Published modules evolve independently over time. In order to allow Published modules evolve independently over time. In order to allow
skipping to change at page 32, line 43 skipping to change at page 34, line 45
acceptable, the author of "b" can republish with an updated revision acceptable, the author of "b" can republish with an updated revision
in the "import" statement. in the "import" statement.
If a module is not imported with a specific revision, it is undefined If a module is not imported with a specific revision, it is undefined
which revision is used. which revision is used.
5.1.2. Module Hierarchies 5.1.2. Module Hierarchies
YANG allows modeling of data in multiple hierarchies, where data may YANG allows modeling of data in multiple hierarchies, where data may
have more than one top-level node. Each top-level data node in a have more than one top-level node. Each top-level data node in a
module defines a separate hierarchy. Models that have multiple top- module defines a separate hierarchy. Models that have multiple
level nodes are sometimes convenient, and are supported by YANG. top-level nodes are sometimes convenient and are supported by YANG.
5.1.2.1. NETCONF XML Encoding 5.1.2.1. NETCONF XML Encoding
NETCONF is capable of carrying any XML content as the payload in the NETCONF is capable of carrying any XML content as the payload in the
<config> and <data> elements. The top-level nodes of YANG modules <config> and <data> elements. The top-level nodes of YANG modules
are encoded as child elements, in any order, within these elements. are encoded as child elements, in any order, within these elements.
This encapsulation guarantees that the corresponding NETCONF messages This encapsulation guarantees that the corresponding NETCONF messages
are always well-formed XML documents. are always well-formed XML documents.
For example, an instance of: For example, an instance of:
skipping to change at page 33, line 38 skipping to change at page 36, line 7
</system> </system>
<routing xmlns="urn:example:config"> <routing xmlns="urn:example:config">
<!-- routing data here --> <!-- routing data here -->
</routing> </routing>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
5.2. File Layout 5.2. File Layout
YANG modules and submodules are typically stored in files, one module YANG modules and submodules are typically stored in files, one
or submodule statement per file. The name of the file SHOULD be of "module" or "submodule" statement per file. The name of the file
the form: SHOULD be of the form:
module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )
"module-or-submodule-name" is the name of the module or submodule, "module-or-submodule-name" is the name of the module or submodule,
and the optional "revision-date" is the latest revision of the module and the optional "revision-date" is the latest revision of the module
or submodule, as defined by the "revision" statement (Section 7.1.9). or submodule, as defined by the "revision" statement (Section 7.1.9).
The file extension ".yang" denotes that the contents of the file is The file extension ".yang" denotes that the contents of the file are
written with YANG syntax (Section 6), and ".yin" denotes that it is written with YANG syntax (Section 6), and ".yin" denotes that the
written with YIN syntax (Section 13). contents of the file are written with YIN syntax (Section 13).
YANG parsers can find imported modules and included submodules via YANG parsers can find imported modules and included submodules via
this convention. this convention.
5.3. XML Namespaces 5.3. XML Namespaces
All YANG definitions are specified within a module. Each module is All YANG definitions are specified within a module. Each module is
bound to a distinct XML namespace [XML-NAMES], which is a globally bound to a distinct XML namespace [XML-NAMES], which is a globally
unique URI [RFC3986]. A NETCONF client or server uses the namespace unique URI [RFC3986]. A NETCONF client or server uses the namespace
during XML encoding of data. during XML encoding of data.
XML namespaces for modules published in RFC streams [RFC4844] MUST be XML namespaces for modules published in RFC streams [RFC4844] MUST be
assigned by IANA, see section 14 in [RFC6020]. assigned by IANA; see Section 14 in [RFC6020].
XML namespaces for private modules are assigned by the organization XML namespaces for private modules are assigned by the organization
owning the module without a central registry. Namespace URIs MUST be owning the module without a central registry. Namespace URIs MUST be
chosen so they cannot collide with standard or other enterprise chosen so they cannot collide with standard or other enterprise
namespaces, for example by using the enterprise or organization name namespaces -- for example, by using the enterprise or organization
in the namespace. name in the namespace.
The "namespace" statement is covered in Section 7.1.3. The "namespace" statement is covered in Section 7.1.3.
5.3.1. YANG XML Namespace 5.3.1. YANG XML Namespace
YANG defines an XML namespace for NETCONF <edit-config> operations, YANG defines an XML namespace for NETCONF <edit-config> operations,
<error-info> content, and the <action> element. The name of this <error-info> content, and the <action> element. The name of this
namespace is "urn:ietf:params:xml:ns:yang:1". namespace is "urn:ietf:params:xml:ns:yang:1".
5.4. Resolving Grouping, Type, and Identity Names 5.4. Resolving Grouping, Type, and Identity Names
skipping to change at page 34, line 51 skipping to change at page 37, line 24
For example, if a module defines a grouping in which a type is 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 referenced, when the grouping is used in a second module, the type is
resolved in the context of the original module, not the second resolved in the context of the original module, not the second
module. There is no ambiguity if both modules define the type. module. There is no ambiguity if both modules define the type.
5.5. Nested Typedefs and Groupings 5.5. Nested Typedefs and Groupings
Typedefs and groupings may appear nested under many YANG statements, Typedefs and groupings may appear nested under many YANG statements,
allowing these to be lexically scoped by the statement hierarchy allowing these to be lexically scoped by the statement hierarchy
under which they appear. This allows types and groupings to be under which they appear. This allows types and groupings to be
defined near where they are used, rather than placing them at the top defined near where they are used, rather than placing them at the
level of the hierarchy. The close proximity increases readability. top level of the hierarchy. The close proximity increases
readability.
Scoping also allows types to be defined without concern for naming Scoping also allows types to be defined without concern for naming
conflicts between types in different submodules. Type names can be conflicts between types in different submodules. Type names can be
specified without adding leading strings designed to prevent name specified without adding leading strings designed to prevent name
collisions within large modules. collisions within large modules.
Finally, scoping allows the module author to keep types and groupings Finally, scoping allows the module author to keep types and groupings
private to their module or submodule, preventing their reuse. Since private to their module or submodule, preventing their reuse. Since
only top-level types and groupings (i.e., those appearing as only top-level types and groupings (i.e., those appearing as
substatements to a module or submodule statement) can be used outside substatements to a "module" or "submodule" statement) can be used
the module or submodule, the developer has more control over what outside the module or submodule, the developer has more control over
pieces of their module are presented to the outside world, supporting what pieces of their module are presented to the outside world,
the need to hide internal information and maintaining a boundary supporting the need to hide internal information and maintaining a
between what is shared with the outside world and what is kept boundary between what is shared with the outside world and what is
private. kept private.
Scoped definitions MUST NOT shadow definitions at a higher scope. A Scoped definitions MUST NOT shadow definitions at a higher scope. A
type or grouping cannot be defined if a higher level in the statement type or grouping cannot be defined if a higher level in the statement
hierarchy has a definition with a matching identifier. hierarchy has a definition with a matching identifier.
A reference to an unprefixed type or grouping, or one which uses the A reference to an unprefixed type or grouping, or one that uses the
prefix of the current module, is resolved by locating the matching prefix of the current module, is resolved by locating the matching
"typedef" or "grouping" statement among the immediate substatements "typedef" or "grouping" statement among the immediate substatements
of each ancestor statement. of each ancestor statement.
5.6. Conformance 5.6. Conformance
Conformance to a model is a measure of how accurately a server Conformance to a model is a measure of how accurately a server
follows the model. Generally speaking, servers are responsible for follows the model. Generally speaking, servers are responsible for
implementing the model faithfully, allowing applications to treat implementing the model faithfully, allowing applications to treat
servers which implement the model identically. Deviations from the servers that implement the model identically. Deviations from the
model can reduce the utility of the model and increase fragility of model can reduce the utility of the model and increase the fragility
applications that use it. of applications that use it.
YANG modelers have three mechanisms for conformance: YANG modelers have three mechanisms for conformance:
o the basic behavior of the model o the basic behavior of the model
o optional features that are part of the model o optional features that are part of the model
o deviations from the model o deviations from the model
We will consider each of these in sequence. We will consider each of these in sequence.
5.6.1. Basic Behavior 5.6.1. Basic Behavior
The model defines a contract between a YANG-based client and server, The model defines a contract between a YANG-based client and server;
which allows both parties to have faith the other knows the syntax this contract allows both parties to have faith that the other knows
and semantics behind the modeled data. The strength of YANG lies in the syntax and semantics behind the modeled data. The strength of
the strength of this contract. YANG lies in the strength of this contract.
5.6.2. Optional Features 5.6.2. Optional Features
In many models, the modeler will allow sections of the model to be In many models, the modeler will allow sections of the model to be
conditional. The server controls whether these conditional portions conditional. The server controls whether these conditional portions
of the model are supported or valid for that particular server. of the model are supported or valid for that particular server.
For example, a syslog data model may choose to include the ability to 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 save logs locally, but the modeler will realize that this is only
possible if the server has local storage. If there is no local possible if the server has local storage. If there is no local
skipping to change at page 37, line 12 skipping to change at page 39, line 38
For example, a BGP module may allow any number of BGP peers, but a For example, a BGP module may allow any number of BGP peers, but a
particular server may only support 16 BGP peers. Any application particular server may only support 16 BGP peers. Any application
configuring the 17th peer will receive an error. While an error may configuring the 17th peer will receive an error. While an error may
suffice to let the application know it cannot add another peer, it suffice to let the application know it cannot add another peer, it
would be far better if the application had prior knowledge of this would be far better if the application had prior knowledge of this
limitation and could prevent the user from starting down the path limitation and could prevent the user from starting down the path
that could not succeed. that could not succeed.
Server deviations are declared using the "deviation" statement, which Server deviations are declared using the "deviation" statement, which
takes as its argument a string that identifies a node in the schema takes as its argument a string that identifies a node in the schema
tree. The contents of the statement details the manner in which the tree. The contents of the statement detail the manner in which the
server implementation deviates from the contract as defined in the server implementation deviates from the contract as defined in the
module. module.
Further details are available in Section 7.20.3. Further details are available in Section 7.20.3.
5.6.4. Announcing Conformance Information in NETCONF 5.6.4. Announcing Conformance Information in NETCONF
This document defines the following mechanism for announcing This document defines the following mechanism for announcing
conformance information. Other mechanisms may be defined by future conformance information. Other mechanisms may be defined by future
specifications. specifications.
A NETCONF server MUST announce the modules it implements (see A NETCONF server MUST announce the modules it implements (see
Section 5.6.5) by implementing the YANG module "ietf-yang-library" Section 5.6.5) by implementing the YANG module "ietf-yang-library"
defined in [I-D.ietf-netconf-yang-library], and listing all defined in [RFC7895] and listing all implemented modules in the
implemented modules in the "/modules-state/module" list. "/modules-state/module" list.
The server also MUST advertise the following capability in the The server also MUST advertise the following capability in the
<hello> message (line-breaks and whitespaces are used for formatting <hello> message (line breaks and whitespaces are used for formatting
reasons only): reasons only):
urn:ietf:params:netconf:capability:yang-library:1.0? urn:ietf:params:netconf:capability:yang-library:1.0?
revision=<date>&module-set-id=<id> revision=<date>&module-set-id=<id>
The parameter "revision" has the same value as the revision date of The parameter "revision" has the same value as the revision date of
the "ietf-yang-library" module implemented by the server. This the "ietf-yang-library" module implemented by the server. This
parameter MUST be present. parameter MUST be present.
The parameter "module-set-id" has the same value as the leaf The parameter "module-set-id" has the same value as the leaf
"/modules-state/module-set-id" from "ietf-yang-library". This "/modules-state/module-set-id" from "ietf-yang-library". This
parameter MUST be present. parameter MUST be present.
With this mechanism, a client can cache the supported modules for a With this mechanism, a client can cache the supported modules for a
server, and only update the cache if the "module-set-id" value in the server and only update the cache if the "module-set-id" value in the
<hello> message changes. <hello> message changes.
5.6.5. Implementing a Module 5.6.5. Implementing a Module
A server implements a module if it implements the module's data A server implements a module if it implements the module's data
nodes, rpcs, actions, notifications, and deviations. nodes, RPCs, actions, notifications, and deviations.
A server MUST NOT implement more than one revision of a module. A server MUST NOT implement more than one revision of a module.
If a server implements a module A that imports a module B, and A uses If a server implements a module A that imports a module B, and A uses
any node from B in an "augment" or "path" statement that the server any node from B in an "augment" or "path" statement that the server
supports, then the server MUST implement a revision of module B that supports, then the server MUST implement a revision of module B that
has these nodes defined. This is regardless of if module B is has these nodes defined. This is regardless of whether module B is
imported by revision or not. imported by revision or not.
If a server implements a module A that imports a module C without If a server implements a module A that imports a module C without
specifying the revision date of module C, and the server does not specifying the revision date of module C and the server does not
implement C (e.g., if C only defines some typedefs), the server MUST implement C (e.g., if C only defines some typedefs), the server MUST
list module C in the "/modules-state/module" list from list module C in the "/modules-state/module" list from
"ietf-yang-library" [I-D.ietf-netconf-yang-library], and it MUST set "ietf-yang-library" [RFC7895], and it MUST set the leaf
the leaf "conformance-type" to "import" for this module. "conformance-type" to "import" for this module.
If a server lists a module C in the "/modules-state/module" list from If a server lists a module C in the "/modules-state/module" list from
"ietf-yang-library", and there are other modules Ms listed that "ietf-yang-library" and there are other modules Ms listed that import
import C without specifying the revision date of module C, the server C without specifying the revision date of module C, the server MUST
MUST use the definitions from the most recent revision of C listed use the definitions from the most recent revision of C listed for
for modules Ms. modules Ms.
The reason for these rules is that clients need to be able to know The reason for these rules is that clients need to be able to know
the specific data model structure and types of all leafs and leaf- the specific data model structure and types of all leafs and
lists implemented in a server. leaf-lists implemented in a server.
For example, with these modules: For example, with these modules:
module a { module a {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:a"; namespace "urn:example:a";
prefix "a"; prefix "a";
import b { import b {
revision-date 2015-01-01; revision-date 2015-01-01;
skipping to change at page 40, line 32 skipping to change at page 43, line 20
revision 2015-02-02; revision 2015-02-02;
typedef bar { typedef bar {
... ...
} }
} }
A server that implements revision "2015-01-01" of module "a" and A server that implements revision "2015-01-01" of module "a" and
supports feature "foo" can implement revision "2015-01-01" or supports feature "foo" can implement revision "2015-01-01" or
"2015-04-04" of module "b". Since "b" was imported by revision, the "2015-04-04" of module "b". Since "b" was imported by revision, the
type of leaf "/b:x/a:y" is the same regardless of which revision of type of leaf "/b:x/a:y" is the same, regardless of which revision of
"b" the server implements. "b" the server implements.
A server that implements module "a", but does not support feature A server that implements module "a" but does not support feature
"foo" does not have to implement module "b". "foo" does not have to implement module "b".
A server that implements revision "2015-01-01" of module "a" picks A server that implements revision "2015-01-01" of module "a"
any revision of module "c", and list it in the "/modules-state/ picks any revision of module "c" and lists it in the
module" list from "ietf-yang-library". "/modules-state/module" list from "ietf-yang-library".
The following XML encoding example shows valid data for the The following XML encoding example shows valid data for the
"/modules-state/module" list for a server that implements module "a": "/modules-state/module" list for a server that implements module "a":
<modules-state <modules-state
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set-id>ee1ecb017370cafd</module-set-id> <module-set-id>ee1ecb017370cafd</module-set-id>
<module> <module>
<name>a</name> <name>a</name>
<revision>2015-01-01</revision> <revision>2015-01-01</revision>
skipping to change at page 43, line 28 skipping to change at page 46, line 16
line break, this trailing whitespace is stripped from the string. line break, this trailing whitespace is stripped from the string.
A single-quoted string (enclosed within ' ') preserves each character A single-quoted string (enclosed within ' ') preserves each character
within the quotes. A single quote character cannot occur in a within the quotes. A single quote character cannot occur in a
single-quoted string, even when preceded by a backslash. single-quoted string, even when preceded by a backslash.
Within a double-quoted string (enclosed within " "), a backslash Within a double-quoted string (enclosed within " "), a backslash
character introduces a representation of a special character, which character introduces a representation of a special character, which
depends on the character that immediately follows the backslash: depends on the character that immediately follows the backslash:
\n new line \n newline
\t a tab character \t a tab character
\" a double quote \" a double quote
\\ a single backslash \\ a single backslash
The backslash MUST NOT be followed by any other character. The backslash MUST NOT be followed by any other character.
If a quoted string is followed by a plus character ("+"), followed by If a quoted string is followed by a plus character ("+"), followed by
another quoted string, the two strings are concatenated into one another quoted string, the two strings are concatenated into one
string, allowing multiple concatenations to build one string. string, allowing multiple concatenations to build one string.
Whitespace, line breaks, and comments are allowed between the quoted Whitespace, line breaks, and comments are allowed between the quoted
skipping to change at page 44, line 15 skipping to change at page 46, line 47
hello hello
"hello" "hello"
'hello' 'hello'
"hel" + "lo" "hel" + "lo"
'hel' + "lo" 'hel' + "lo"
The following examples show some special strings: The following examples show some special strings:
"\"" - string containing a double quote "\"" - string containing a double quote
'"' - string containing a double quote '"' - string containing a double quote
"\n" - string containing a new line character "\n" - string containing a newline character
'\n' - string containing a backslash followed '\n' - string containing a backslash followed
by the character n by the character n
The following examples show some illegal strings: The following examples show some illegal strings:
'''' - a single-quoted string cannot contain single quotes '''' - a single-quoted string cannot contain single quotes
""" - a double quote must be escaped in a double-quoted string """ - a double quote must be escaped in a double-quoted string
The following strings are equivalent: The following strings are equivalent:
skipping to change at page 44, line 38 skipping to change at page 47, line 24
"first line\n" + " second line" "first line\n" + " second line"
6.2. Identifiers 6.2. Identifiers
Identifiers are used to identify different kinds of YANG items by Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an uppercase or lowercase ASCII name. Each identifier starts with an uppercase or lowercase ASCII
letter or an underscore character, followed by zero or more ASCII letter or an underscore character, followed by zero or more ASCII
letters, digits, underscore characters, hyphens, and dots. letters, digits, underscore characters, hyphens, and dots.
Implementations MUST support identifiers up to 64 characters in Implementations MUST support identifiers up to 64 characters in
length, and MAY support longer identifiers. Identifiers are case length and MAY support longer identifiers. Identifiers are case
sensitive. The identifier syntax is formally defined by the rule sensitive. The identifier syntax is formally defined by the rule
"identifier" in Section 14. Identifiers can be specified as quoted "identifier" in Section 14. Identifiers can be specified as quoted
or unquoted strings. or unquoted strings.
6.2.1. Identifiers and Their Namespaces 6.2.1. Identifiers and Their Namespaces
Each identifier is valid in a namespace that depends on the type of Each identifier is valid in a namespace that depends on the type of
the YANG item being defined. All identifiers defined in a namespace the YANG item being defined. All identifiers defined in a namespace
MUST be unique. MUST be unique.
skipping to change at page 45, line 18 skipping to change at page 47, line 51
o All feature names defined in a module and its submodules share the o All feature names defined in a module and its submodules share the
same feature identifier namespace. same feature identifier namespace.
o All identity names defined in a module and its submodules share o All identity names defined in a module and its submodules share
the same identity identifier namespace. the same identity identifier namespace.
o All derived type names defined within a parent node or at the top 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 level of the module or its submodules share the same type
identifier namespace. This namespace is scoped to all descendant identifier namespace. This namespace is scoped to all descendant
nodes of the parent node or module. This means that any nodes of the parent node or module. This means that any
descendent node may use that typedef, and it MUST NOT define a descendant node may use that typedef, and it MUST NOT define a
typedef with the same name. typedef with the same name.
o All grouping names defined within a parent node or at the top o All grouping names defined within a parent node or at the top
level of the module or its submodules share the same grouping level of the module or its submodules share the same grouping
identifier namespace. This namespace is scoped to all descendant identifier namespace. This namespace is scoped to all descendant
nodes of the parent node or module. This means that any nodes of the parent node or module. This means that any
descendent node may use that grouping, and it MUST NOT define a descendant node may use that grouping, and it MUST NOT define a
grouping with the same name. grouping with the same name.
o All leafs, leaf-lists, lists, containers, choices, rpcs, actions, o All leafs, leaf-lists, lists, containers, choices, rpcs, actions,
notifications, anydatas, and anyxmls defined (directly or through notifications, anydatas, and anyxmls defined (directly or through
a uses statement) within a parent node or at the top level of the a "uses" statement) within a parent node or at the top level of
module or its submodules share the same identifier namespace. the module or its submodules share the same identifier namespace.
This namespace is scoped to the parent node or module, unless the 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 parent node is a case node. In that case, the namespace is scoped
to the closest ancestor node that is not a case or choice node. to the closest ancestor node that is not a case or choice node.
o All cases within a choice share the same case identifier o All cases within a choice share the same case identifier
namespace. This namespace is scoped to the parent choice node. namespace. This namespace is scoped to the parent choice node.
Forward references are allowed in YANG. Forward references are allowed in YANG.
6.3. Statements 6.3. Statements
A YANG module contains a sequence of statements. Each statement A YANG module contains a sequence of statements. Each statement
starts with a keyword, followed by zero or one argument, followed starts with a keyword, followed by zero or one argument, followed by
either by a semicolon (";") or a block of substatements enclosed either a semicolon (";") or a block of substatements enclosed within
within braces ("{ }"): braces ("{ }"):
statement = keyword [argument] (";" / "{" *statement "}") statement = keyword [argument] (";" / "{" *statement "}")
The argument is a string, as defined in Section 6.1.2. The argument is a string, as defined in Section 6.1.2.
6.3.1. Language Extensions 6.3.1. Language Extensions
A module can introduce YANG extensions by using the "extension" A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.19). The extensions can be imported by other keyword (see Section 7.19). The extensions can be imported by other
modules with the "import" statement (see Section 7.1.5). When an modules with the "import" statement (see Section 7.1.5). When an
imported extension is used, the extension's keyword MUST be qualified imported extension is used, the extension's keyword MUST be qualified
using the prefix with which the extension's module was imported. If using the prefix with which the extension's module was imported. If
an extension is used in the module where it is defined, the an extension is used in the module where it is defined, the
extension's keyword MUST be qualified with the prefix of this module. extension's keyword MUST be qualified with the prefix of this module.
The processing of extensions depends on whether support for those The processing of extensions depends on whether support for those
extensions is claimed for a given YANG parser or the tool set in extensions is claimed for a given YANG parser or the tool set in
which it is embedded. An unsupported extension, appearing in a YANG which it is embedded. An unsupported extension appearing in a YANG
module as an unknown-statement (see Section 14) MAY be ignored in its module as an unknown-statement (see Section 14) MAY be ignored in its
entirety. Any supported extension MUST be processed in accordance entirety. Any supported extension MUST be processed in accordance
with the specification governing that extension. with the specification governing that extension.
Care must be taken when defining extensions so that modules that use Care must be taken when defining extensions so that modules that use
the extensions are meaningful also for applications that do not the extensions are meaningful also for applications that do not
support the extensions. support the extensions.
6.4. XPath Evaluations 6.4. XPath Evaluations
YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation
for specifying many inter-node references and dependencies. An for specifying many inter-node references and dependencies. An
implementation is not required to implement an XPath interpreter, but implementation is not required to implement an XPath interpreter but
MUST ensure that the requirements encoded in the data model are MUST ensure that the requirements encoded in the data model are
enforced. The manner of enforcement is an implementation decision. enforced. The manner of enforcement is an implementation decision.
The XPath expressions MUST be syntactically correct, and all prefixes The XPath expressions MUST be syntactically correct, and all prefixes
used MUST be present in the XPath context (see Section 6.4.1). An used MUST be present in the XPath context (see Section 6.4.1). An
implementation may choose to implement them by hand, rather than implementation may choose to implement them by hand, rather than
using the XPath expression directly. using the XPath expression directly.
The data model used in the XPath expressions is the same as that used The data model used in the XPath expressions is the same as that used
in XPath 1.0 [XPATH], with the same extension for root node children in XPath 1.0 [XPATH], with the same extension for root node children
as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means as used by XSLT 1.0 (see Section 3.1 in [XSLT]). Specifically, it
that the root node may have any number of element nodes as its means that the root node may have any number of element nodes as its
children. children.
The data tree has no concept of document order. An implementation The data tree has no concept of document order. An implementation
needs to choose some document order but how it is done is an needs to choose some document order, but how it is done is an
implementation decision. This means that XPath expressions in YANG implementation decision. This means that XPath expressions in YANG
modules SHOULD NOT rely on any specific document order. modules SHOULD NOT rely on any specific document order.
Numbers in XPath 1.0 are IEEE 754 double-precision floating-point Numbers in XPath 1.0 are IEEE 754 [IEEE754-2008] double-precision
values, see Section 3.5 in [XPATH]. This means that some values of floating-point values; see Section 3.5 in [XPATH]. This means that
int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) some values of int64, uint64, and decimal64 types (see Sections 9.2
cannot be exactly represented in XPath expressions. Therefore, due and 9.3) cannot be exactly represented in XPath expressions.
caution should be exercised when using nodes with 64-bit numeric Therefore, due caution should be exercised when using nodes with
values in XPath expressions. In particular, numerical comparisons 64-bit numeric values in XPath expressions. In particular, numerical
involving equality may yield unexpected results. comparisons involving equality may yield unexpected results.
For example, consider the following definition: For example, consider the following definition:
leaf lxiv { leaf lxiv {
type decimal64 { type decimal64 {
fraction-digits 18; fraction-digits 18;
} }
must ". <= 10"; must ". <= 10";
} }
skipping to change at page 47, line 39 skipping to change at page 50, line 24
o Names without a namespace prefix belong to the same namespace as o Names without a namespace prefix belong to the same namespace as
the identifier of the current node. Inside a grouping, that the identifier of the current node. Inside a grouping, that
namespace is affected by where the grouping is used (see namespace is affected by where the grouping is used (see
Section 7.13). Inside a typedef, that namespace is affected by Section 7.13). Inside a typedef, that namespace is affected by
where the typedef is referenced. If a typedef is defined and where the typedef is referenced. If a typedef is defined and
referenced within a grouping, the namespace is affected by where referenced within a grouping, the namespace is affected by where
the grouping is used (see Section 7.13). the grouping is used (see Section 7.13).
o The function library is the core function library defined in o The function library is the core function library defined in
[XPATH], and the functions defined in Section 10. [XPATH] and the functions defined in Section 10.
o The set of variable bindings is empty. o The set of variable bindings is empty.
The mechanism for handling unprefixed names is adopted from XPath 2.0 The mechanism for handling unprefixed names is adopted from XPath 2.0
[XPATH2.0], and helps simplify XPath expressions in YANG. No [XPATH2.0] and helps simplify XPath expressions in YANG. No
ambiguity may ever arise because YANG node identifiers are always ambiguity may ever arise, because YANG node identifiers are always
qualified names with a non-null namespace URI. qualified names with a non-null namespace URI.
The accessible tree depends on where the statement with the XPath The accessible tree depends on where the statement with the XPath
expression is defined: expression is defined:
o If the XPath expression is defined in substatement to a data node o If the XPath expression is defined in a substatement to a data
that represents configuration, the accessible tree is the data in node that represents configuration, the accessible tree is the
the datastore where the context node exists. The root node has data in the datastore where the context node exists. The root
all top-level configuration data nodes in all modules as children. node has all top-level configuration data nodes in all modules as
children.
o If the XPath expression is defined in a substatement to a data o If the XPath expression is defined in a substatement to a data
node that represents state data, the accessible tree is all state node that represents state data, the accessible tree is all state
data in the server, and the running configuration datastore. The data in the server, and the running configuration datastore. The
root node has all top-level data nodes in all modules as children. root node has all top-level data nodes in all modules as children.
o If the XPath expression is defined in a substatement to a o If the XPath expression is defined in a substatement to a
"notification" statement, the accessible tree is the notification "notification" statement, the accessible tree is the notification
instance, all state data in the server, and the running instance, all state data in the server, and the running
configuration datastore. If the notification is defined on the configuration datastore. If the notification is defined on the
top-level in a module, then the root node has the node top level in a module, then the root node has the node
representing the notification being defined and all top-level data representing the notification being defined and all top-level data
nodes in all modules as children. Otherwise, the root node has nodes in all modules as children. Otherwise, the root node has
all top-level data nodes in all modules as children. all top-level data nodes in all modules as children.
o If the XPath expression is defined in a substatement to an "input" o If the XPath expression is defined in a substatement to an "input"
statement in an "rpc" or "action" statement, the accessible tree statement in an "rpc" or "action" statement, the accessible tree
is the RPC or action operation instance, all state data in the is the RPC or action operation instance, all state data in the
server, and the running configuration datastore. The root node server, and the running configuration datastore. The root node
has top-level data nodes in all modules as children. has top-level data nodes in all modules as children.
Additionally, for an RPC, the root node also has the node Additionally, for an RPC, the root node also has the node
skipping to change at page 48, line 45 skipping to change at page 51, line 29
"output" statement in an "rpc" or "action" statement, the "output" statement in an "rpc" or "action" statement, the
accessible tree is the RPC or action operation instance, all state accessible tree is the RPC or action operation instance, all state
data in the server, and the running configuration datastore. The data in the server, and the running configuration datastore. The
root node has top-level data nodes in all modules as children. root node has top-level data nodes in all modules as children.
Additionally, for an RPC, the root node also has the node Additionally, for an RPC, the root node also has the node
representing the RPC operation being defined as a child. The node representing the RPC operation being defined as a child. The node
representing the operation being defined has the operation's representing the operation being defined has the operation's
output parameters as children. output parameters as children.
In the accessible tree, all leafs and leaf-lists with default values In the accessible tree, all leafs and leaf-lists with default values
in use exist (See Section 7.6.1 and Section 7.7.2). in use exist (see Sections 7.6.1 and 7.7.2).
If a node that exists in the accessible tree has a non-presence If a node that exists in the accessible tree has a non-presence
container as a child, then the non-presence container also exists in container as a child, then the non-presence container also exists in
the tree. the accessible tree.
The context node varies with the YANG XPath expression, and is The context node varies with the YANG XPath expression and is
specified where the YANG statement with the XPath expression is specified where the YANG statement with the XPath expression is
defined. defined.
6.4.1.1. Examples 6.4.1.1. Examples
Given the following module: Given the following module:
module example-a { module example-a {
yang-version 1.1; yang-version 1.1;
namespace urn:example:a; namespace urn:example:a;
skipping to change at page 49, line 52 skipping to change at page 53, line 5
} }
notification failure { notification failure {
leaf b-ref { leaf b-ref {
type leafref { type leafref {
path "/a/b/id"; path "/a/b/id";
} }
} }
} }
} }
And given the following data tree, specified in XML: and given the following data tree, specified in XML:
<a xmlns="urn:example:a"> <a xmlns="urn:example:a">
<b> <b>
<id>1</id> <id>1</id>
</b> </b>
<b> <b>
<id>2</id> <id>2</id>
</b> </b>
</a> </a>
skipping to change at page 50, line 29 skipping to change at page 53, line 31
</b> </b>
<b> <b>
<id>2</id> <id>2</id>
<down> <down>
<reason>error</reason> <reason>error</reason>
</down> </down>
</b> </b>
</a> </a>
// possibly other top-level nodes here // possibly other top-level nodes here
The accessible tree for an action invocation of "reset" on /a/ The accessible tree for an action invocation of "reset" on
b[id="1"] with the "when" parameter set to "10" would be: /a/b[id="1"] with the "when" parameter set to "10" would be:
<a xmlns="urn:example:a"> <a xmlns="urn:example:a">
<b> <b>
<id>1</id> <id>1</id>
<reset> <reset>
<delay>10</delay> <delay>10</delay>
</reset> </reset>
</b> </b>
<b> <b>
<id>2</id> <id>2</id>
skipping to change at page 52, line 14 skipping to change at page 55, line 14
7. YANG Statements 7. YANG Statements
The following sections describe all of the YANG statements. The following sections describe all of the YANG statements.
Note that even a statement that does not have any substatements Note that even a statement that does not have any substatements
defined in YANG can have vendor-specific extensions as substatements. defined in YANG can have vendor-specific extensions as substatements.
For example, the "description" statement does not have any For example, the "description" statement does not have any
substatements defined in YANG, but the following is legal: substatements defined in YANG, but the following is legal:
description "some text" { description "Some text." {
ex:documentation-flag 5; ex:documentation-flag 5;
} }
7.1. The module Statement 7.1. The "module" Statement
The "module" statement defines the module's name, and groups all The "module" statement defines the module's name and groups all
statements that belong to the module together. The "module" statements that belong to the module together. The "module"
statement's argument is the name of the module, followed by a block statement's argument is the name of the module, followed by a block
of substatements that hold detailed module information. The module of substatements that holds detailed module information. The module
name is an identifier (see Section 6.2). name is an identifier (see Section 6.2).
Names of modules published in RFC streams [RFC4844] MUST be assigned Names of modules published in RFC streams [RFC4844] MUST be assigned
by IANA, see section 14 in [RFC6020]. by IANA; see Section 14 in [RFC6020].
Private module names are assigned by the organization owning the Private module names are assigned by the organization owning the
module without a central registry. See Section 5.1 for module without a central registry. See Section 5.1 for
recommendations on how to name modules. recommendations on how to name modules.
A module typically has the following layout: A module typically has the following layout:
module <module-name> { module <module-name> {
// header information // header information
<yang-version statement> <yang-version statement>
<namespace statement> <namespace statement>
<prefix statement> <prefix statement>
// linkage statements // linkage statements
<import statements> <import statements>
<include statements> <include statements>
// meta information // meta-information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<other statements> <other statements>
} }
7.1.1. The module's Substatements 7.1.1. The module's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| augment | 7.17 | 0..n | | augment | 7.17 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| contact | 7.1.8 | 0..1 | | contact | 7.1.8 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
skipping to change at page 54, line 36 skipping to change at page 57, line 5
| organization | 7.1.7 | 0..1 | | organization | 7.1.7 | 0..1 |
| prefix | 7.1.4 | 1 | | prefix | 7.1.4 | 1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| revision | 7.1.9 | 0..n | | revision | 7.1.9 | 0..n |
| rpc | 7.14 | 0..n | | rpc | 7.14 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| yang-version | 7.1.2 | 1 | | yang-version | 7.1.2 | 1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.2. The yang-version Statement 7.1.2. The "yang-version" Statement
The "yang-version" statement specifies which version of the YANG The "yang-version" statement specifies which version of the YANG
language was used in developing the module. The statement's argument language was used in developing the module. The statement's argument
is a string. It MUST contain the value "1.1" for YANG modules is a string. It MUST contain the value "1.1" for YANG modules
defined based on this specification. defined based on this specification.
A module or submodule that doesn't contain the "yang-version" A module or submodule that doesn't contain the "yang-version"
statement, or one that contains the value "1", is developed for YANG statement, or one that contains the value "1", is developed for YANG
version 1, defined in [RFC6020]. version 1, defined in [RFC6020].
Handling of the "yang-version" statement for versions other than Handling of the "yang-version" statement for versions other than
"1.1" (the version defined here) is out of scope for this "1.1" (the version defined here) is out of scope for this
specification. Any document that defines a higher version will need specification. Any document that defines a higher version will need
to define the backward compatibility of such a higher version. to define the backward compatibility of such a higher version.
For compatibility between YANG version 1 and 1.1, see Section 12. For compatibility between YANG versions 1 and 1.1, see Section 12.
7.1.3. The namespace Statement 7.1.3. The "namespace" Statement
The "namespace" statement defines the XML namespace that all The "namespace" statement defines the XML namespace that all
identifiers defined by the module are qualified by in the XML identifiers defined by the module are qualified by in the XML
encoding, with the exception of identifiers for data nodes, action encoding, with the exception of identifiers for data nodes, action
nodes, and notification nodes defined inside a grouping (see nodes, and notification nodes defined inside a grouping (see
Section 7.13 for details). The argument to the "namespace" statement Section 7.13 for details). The argument to the "namespace" statement
is the URI of the namespace. is the URI of the namespace.
See also Section 5.3. See also Section 5.3.
7.1.4. The prefix Statement 7.1.4. The "prefix" Statement
The "prefix" statement is used to define the prefix associated with The "prefix" statement is used to define the prefix associated with
the module and its namespace. The "prefix" statement's argument is the module and its namespace. The "prefix" statement's argument is
the prefix string that is used as a prefix to access a module. The the prefix string that is used as a prefix to access a module. The
prefix string MAY be used with the module to refer to definitions prefix string MAY be used with the module to refer to definitions
contained in the module, e.g., "if:ifName". A prefix is an contained in the module, e.g., "if:ifName". A prefix is an
identifier (see Section 6.2). identifier (see Section 6.2).
When used inside the "module" statement, the "prefix" statement When used inside the "module" statement, the "prefix" statement
defines the prefix suggested to be used when this module is imported. defines the prefix suggested to be used when this module is imported.
To improve readability of the NETCONF XML, a NETCONF client or server To improve readability of the NETCONF XML, a NETCONF client or server
that generates XML or XPath that use prefixes SHOULD use the prefix that generates XML or XPath that uses prefixes SHOULD use the prefix
defined by the module as the XML namespace prefix, unless there is a defined by the module as the XML namespace prefix, unless there is a
conflict. conflict.
When used inside the "import" statement, the "prefix" statement When used inside the "import" statement, the "prefix" statement
defines the prefix to be used when accessing definitions inside the defines the prefix to be used when accessing definitions inside the
imported module. When a reference to an identifier from the imported imported module. When a reference to an identifier from the imported
module is used, the prefix string for the imported module followed by module is used, the prefix string for the imported module followed by
a colon (":") and the identifier is used, e.g., "if:ifIndex". To a colon (":") and the identifier is used, e.g., "if:ifIndex". To
improve readability of YANG modules, the prefix defined by a module improve readability of YANG modules, the prefix defined by a module
SHOULD be used when the module is imported, unless there is a SHOULD be used when the module is imported, unless there is a
conflict. If there is a conflict, i.e., two different modules that conflict. If there is a conflict, i.e., two different modules that
both have defined the same prefix are imported, at least one of them both have defined the same prefix are imported, at least one of them
MUST be imported with a different prefix. MUST be imported with a different prefix.
All prefixes, including the prefix for the module itself MUST be All prefixes, including the prefix for the module itself, MUST be
unique within the module or submodule. unique within the module or submodule.
7.1.5. The import Statement 7.1.5. The "import" Statement
The "import" statement makes definitions from one module available The "import" statement makes definitions from one module available
inside another module or submodule. The argument is the name of the inside another module or submodule. The argument is the name of the
module to import, and the statement is followed by a block of module to import, and the statement is followed by a block of
substatements that holds detailed import information. When a module substatements that holds detailed import information. When a module
is imported, the importing module may: is imported, the importing module may:
o use any grouping and typedef defined at the top level in the o use any grouping and typedef defined at the top level in the
imported module or its submodules. imported module or its submodules.
skipping to change at page 56, line 42 skipping to change at page 59, line 8
the imported module does not exist. If no "revision-date" the imported module does not exist. If no "revision-date"
substatement is present, it is undefined from which revision of the substatement is present, it is undefined from which revision of the
module they are taken. module they are taken.
Multiple revisions of the same module can be imported, provided that Multiple revisions of the same module can be imported, provided that
different prefixes are used. different prefixes are used.
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| prefix | 7.1.4 | 1 |
| revision-date | 7.1.5.1 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| prefix | 7.1.4 | 1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| revision-date | 7.1.5.1 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
The import's Substatements The import's Substatements
7.1.5.1. The import's revision-date Statement 7.1.5.1. The import's "revision-date" Statement
The import's "revision-date" statement is used to specify the version The import's "revision-date" statement is used to specify the version
of the module to import. of the module to import.
7.1.6. The include Statement 7.1.6. The "include" Statement
The "include" statement is used to make content from a submodule The "include" statement is used to make content from a submodule
available to that submodule's parent module. The argument is an available to that submodule's parent module. The argument is an
identifier that is the name of the submodule to include. Modules are identifier that is the name of the submodule to include. Modules are
only allowed to include submodules that belong to that module, as only allowed to include submodules that belong to that module, as
defined by the "belongs-to" statement (see Section 7.2.2). defined by the "belongs-to" statement (see Section 7.2.2).
When a module includes a submodule, it incorporates the contents of When a module includes a submodule, it incorporates the contents of
the submodule into the node hierarchy of the module. the submodule into the node hierarchy of the module.
skipping to change at page 57, line 36 skipping to change at page 59, line 47
specified revision of the submodule is included in the module. It is specified revision of the submodule is included in the module. It is
an error if the specified revision of the submodule does not exist. an error if the specified revision of the submodule does not exist.
If no "revision-date" substatement is present, it is undefined which If no "revision-date" substatement is present, it is undefined which
revision of the submodule is included. revision of the submodule is included.
Multiple revisions of the same submodule MUST NOT be included. Multiple revisions of the same submodule MUST NOT be included.
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| revision-date | 7.1.5.1 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| revision-date | 7.1.5.1 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
The includes's Substatements The includes's Substatements
7.1.7. The organization Statement 7.1.7. The "organization" Statement
The "organization" statement defines the party responsible for this The "organization" statement defines the party responsible for this
module. The argument is a string that is used to specify a textual module. The argument is a string that is used to specify a textual
description of the organization(s) under whose auspices this module description of the organization(s) under whose auspices this module
was developed. was developed.
7.1.8. The contact Statement 7.1.8. The "contact" Statement
The "contact" statement provides contact information for the module. The "contact" statement provides contact information for the module.
The argument is a string that is used to specify contact information The argument is a string that is used to specify contact information
for the person or persons to whom technical queries concerning this for the person or persons to whom technical queries concerning this
module should be sent, such as their name, postal address, telephone module should be sent, such as their name, postal address, telephone
number, and electronic mail address. number, and electronic mail address.
7.1.9. The revision Statement 7.1.9. The "revision" Statement
The "revision" statement specifies the editorial revision history of The "revision" statement specifies the editorial revision history of
the module, including the initial revision. A series of revision the module, including the initial revision. A series of "revision"
statements detail the changes in the module's definition. The statements detail the changes in the module's definition. The
argument is a date string in the format "YYYY-MM-DD", followed by a argument is a date string in the format "YYYY-MM-DD", followed by a
block of substatements that holds detailed revision information. A block of substatements that holds detailed revision information. A
module SHOULD have at least one "revision" statement. For every module SHOULD have at least one "revision" statement. For every
published editorial change, a new one SHOULD be added in front of the published editorial change, a new one SHOULD be added in front of the
revisions sequence, so that all revisions are in reverse revisions sequence so that all revisions are in reverse chronological
chronological order. order.
7.1.9.1. The revision's Substatement 7.1.9.1. The revision's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.10. Usage Example 7.1.10. Usage Example
The following example relies on [RFC6991].
module example-system { module example-system {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:system"; namespace "urn:example:system";
prefix "sys"; prefix "sys";
import ietf-yang-types { import ietf-yang-types {
prefix "yang"; prefix "yang";
reference "RFC 6991: Common YANG Data Types"; reference "RFC 6991: Common YANG Data Types";
} }
skipping to change at page 59, line 26 skipping to change at page 61, line 31
organization "Example Inc."; organization "Example Inc.";
contact contact
"Joe L. User "Joe L. User
Example Inc. Example Inc.
42 Anywhere Drive 42 Anywhere Drive
Nowhere, CA 95134 Nowhere, CA 95134
USA USA
Phone: +1 800 555 0100 Phone: +1 800 555 0100
EMail: joe@example.com"; Email: joe@example.com";
description description
"The module for entities implementing the Example system."; "The module for entities implementing the Example system.";
revision 2007-06-09 { revision 2007-06-09 {
description "Initial revision."; description "Initial revision.";
} }
// definitions follow... // definitions follow...
} }
7.2. The submodule Statement 7.2. The "submodule" Statement
While the primary unit in YANG is a module, a YANG module can itself While the primary unit in YANG is a module, a YANG module can itself
be constructed out of several submodules. Submodules allow a module be constructed out of several submodules. Submodules allow a module
designer to split a complex model into several pieces where all the designer to split a complex model into several pieces where all the
submodules contribute to a single namespace, which is defined by the submodules contribute to a single namespace, which is defined by the
module that includes the submodules. module that includes the submodules.
The "submodule" statement defines the submodule's name, and groups The "submodule" statement defines the submodule's name, and it groups
all statements that belong to the submodule together. The all statements that belong to the submodule together. The
"submodule" statement's argument is the name of the submodule, "submodule" statement's argument is the name of the submodule,
followed by a block of substatements that hold detailed submodule followed by a block of substatements that holds detailed submodule
information. The submodule name is an identifier (see Section 6.2). information. The submodule name is an identifier (see Section 6.2).
Names of submodules published in RFC streams [RFC4844] MUST be Names of submodules published in RFC streams [RFC4844] MUST be
assigned by IANA, see section 14 in [RFC6020]. assigned by IANA; see Section 14 in [RFC6020].
Private submodule names are assigned by the organization owning the Private submodule names are assigned by the organization owning the
submodule without a central registry. See Section 5.1 for submodule without a central registry. See Section 5.1 for
recommendations on how to name submodules. recommendations on how to name submodules.
A submodule typically has the following layout: A submodule typically has the following layout:
submodule <module-name> { submodule <module-name> {
<yang-version statement> <yang-version statement>
// module identification // module identification
<belongs-to statement> <belongs-to statement>
// linkage statements // linkage statements
<import statements> <import statements>
// meta information // meta-information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<other statements> <other statements>
skipping to change at page 61, line 35 skipping to change at page 63, line 38
| notification | 7.16 | 0..n | | notification | 7.16 | 0..n |
| organization | 7.1.7 | 0..1 | | organization | 7.1.7 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| revision | 7.1.9 | 0..n | | revision | 7.1.9 | 0..n |
| rpc | 7.14 | 0..n | | rpc | 7.14 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| yang-version | 7.1.2 | 1 | | yang-version | 7.1.2 | 1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.2.2. The belongs-to Statement 7.2.2. The "belongs-to" Statement
The "belongs-to" statement specifies the module to which the The "belongs-to" statement specifies the module to which the
submodule belongs. The argument is an identifier that is the name of submodule belongs. The argument is an identifier that is the name of
the module. the module.
A submodule MUST only be included by the module to which it belongs, A submodule MUST only be included by either the module to which it
or by another submodule that belongs to that module. belongs or another submodule that belongs to that module.
The mandatory "prefix" substatement assigns a prefix for the module The mandatory "prefix" substatement assigns a prefix for the module
to which the submodule belongs. All definitions in the module that to which the submodule belongs. All definitions in the module that
the submodule belongs to and all its submodules can be accessed by the submodule belongs to and all its submodules can be accessed by
using the prefix. using the prefix.
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| prefix | 7.1.4 | 1 | | prefix | 7.1.4 | 1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
The belongs-to's Substatements The belongs-to's Substatement
7.2.3. Usage Example 7.2.3. Usage Example
submodule example-types { submodule example-types {
yang-version 1.1; yang-version 1.1;
belongs-to "example-system" { belongs-to "example-system" {
prefix "sys"; prefix "sys";
} }
import ietf-yang-types { import ietf-yang-types {
skipping to change at page 62, line 35 skipping to change at page 64, line 35
organization "Example Inc."; organization "Example Inc.";
contact contact
"Joe L. User "Joe L. User
Example Inc. Example Inc.
42 Anywhere Drive 42 Anywhere Drive
Nowhere, CA 95134 Nowhere, CA 95134
USA USA
Phone: +1 800 555 0100 Phone: +1 800 555 0100
EMail: joe@example.com"; Email: joe@example.com";
description description
"This submodule defines common Example types."; "This submodule defines common Example types.";
revision "2007-06-09" { revision "2007-06-09" {
description "Initial revision."; description "Initial revision.";
} }
// definitions follows... // definitions follow...
} }
7.3. The typedef Statement 7.3. The "typedef" Statement
The "typedef" statement defines a new type that may be used locally The "typedef" statement defines a new type that may be used locally
in the module or submodule, and by other modules that import from it, in the module or submodule, and by other modules that import from it,
according to the rules in Section 5.5. The new type is called the according to the rules in Section 5.5. The new type is called the
"derived type", and the type from which it was derived is called the "derived type", and the type from which it was derived is called the
"base type". All derived types can be traced back to a YANG built-in "base type". All derived types can be traced back to a YANG
type. built-in type.
The "typedef" statement's argument is an identifier that is the name The "typedef" statement's argument is an identifier that is the name
of the type to be defined, and MUST be followed by a block of of the type to be defined and MUST be followed by a block of
substatements that holds detailed typedef information. substatements that holds detailed typedef information.
The name of the type MUST NOT be one of the YANG built-in types. If 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 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 submodule, the name of the type to be defined MUST be unique within
the module. the module.
7.3.1. The typedef's Substatements 7.3.1. The typedef's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| default | 7.3.4 | 0..1 | | default | 7.3.4 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| type | 7.3.2 | 1 | | type | 7.3.2 | 1 |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.3.2. The typedef's type Statement 7.3.2. The typedef's "type" Statement
The "type" statement, which MUST be present, defines the base type The "type" statement, which MUST be present, defines the base type
from which this type is derived. See Section 7.4 for details. from which this type is derived. See Section 7.4 for details.
7.3.3. The units Statement 7.3.3. The "units" Statement
The "units" statement, which is optional, takes as an argument a The "units" statement, which is optional, takes as an argument a
string that contains a textual definition of the units associated string that contains a textual definition of the units associated
with the type. with the type.
7.3.4. The typedef's default Statement 7.3.4. The typedef's "default" Statement
The "default" statement takes as an argument a string that contains a The "default" statement takes as an argument a string that contains a
default value for the new type. default value for the new type.
The value of the "default" statement MUST be valid according to the The value of the "default" statement MUST be valid according to the
type specified in the "type" statement. type specified in the "type" statement.
If the base type has a default value, and the new derived type does 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 not specify a new default value, the base type's default value is
also the default value of the new derived type. also the default value of the new derived type.
If the type's default value is not valid according to the new If the type's default value is not valid according to the new
restrictions specified in a derived type or leaf definition, the restrictions specified in a derived type or leaf definition, the
derived type or leaf definition MUST specify a new default value derived type or leaf definition MUST specify a new default value
compatible with the restrictions. compatible with the restrictions.
7.3.5. Usage Example 7.3.5. Usage Example
typedef listen-ipv4-address { typedef listen-ipv4-address {
type inet:ipv4-address; type inet:ipv4-address;
default "0.0.0.0"; default "0.0.0.0";
} }
7.4. The type Statement 7.4. The "type" Statement
The "type" statement takes as an argument a string that is the name The "type" statement takes as an argument a string that is the name
of a YANG built-in type (see Section 9) or a derived type (see 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 Section 7.3), followed by an optional block of substatements that is
used to put further restrictions on the type. used to put further restrictions on the type.
The restrictions that can be applied depend on the type being The restrictions that can be applied depend on the type being
restricted. The restriction statements for all built-in types are restricted. The restriction statements for all built-in types are
described in the subsections of Section 9. described in the subsections of Section 9.
7.4.1. The type's Substatements 7.4.1. The type's Substatements
+------------------+---------+-------------+ +------------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 64, line 45 skipping to change at page 67, line 22
| enum | 9.6.4 | 0..n | | enum | 9.6.4 | 0..n |
| fraction-digits | 9.3.4 | 0..1 | | fraction-digits | 9.3.4 | 0..1 |
| length | 9.4.4 | 0..1 | | length | 9.4.4 | 0..1 |
| path | 9.9.2 | 0..1 | | path | 9.9.2 | 0..1 |
| pattern | 9.4.5 | 0..n | | pattern | 9.4.5 | 0..n |
| range | 9.2.4 | 0..1 | | range | 9.2.4 | 0..1 |
| require-instance | 9.9.3 | 0..1 | | require-instance | 9.9.3 | 0..1 |
| type | 7.4 | 0..n | | type | 7.4 | 0..n |
+------------------+---------+-------------+ +------------------+---------+-------------+
7.5. The container Statement 7.5. The "container" Statement
The "container" statement is used to define an interior data node in The "container" statement is used to define an interior data node in
the schema tree. It takes one argument, which is an identifier, the schema tree. It takes one argument, which is an identifier,
followed by a block of substatements that holds detailed container followed by a block of substatements that holds detailed container
information. information.
A container node does not have a value, but it has a list of child 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 nodes in the data tree. The child nodes are defined in the
container's substatements. container's substatements.
7.5.1. Containers with Presence 7.5.1. Containers with Presence
YANG supports two styles of containers, those that exist only for YANG supports two styles of containers, those that exist only for
organizing the hierarchy of data nodes, and those whose presence in organizing the hierarchy of data nodes and those whose presence in
the data tree has an explicit meaning. the data tree has an explicit meaning.
In the first style, the container has no meaning of its own, existing In the first style, the container has no meaning of its own, existing
only to contain child nodes. In particular, the presence of the only to contain child nodes. In particular, the presence of the
container node with no child nodes is semantically equivalent to the container node with no child nodes is semantically equivalent to the
absence of the container node. YANG calls this style a "non-presence absence of the container node. YANG calls this style a "non-presence
container". This is the default style. container". This is the default style.
For example, the set of scrambling options for Synchronous Optical For example, the set of scrambling options for Synchronous Optical
Network (SONET) interfaces may be placed inside a "scrambling" Network (SONET) interfaces may be placed inside a "scrambling"
container to enhance the organization of the configuration hierarchy, container to enhance the organization of the configuration hierarchy
and to keep these nodes together. The "scrambling" node itself has and to keep these nodes together. The "scrambling" node itself has
no meaning, so removing the node when it becomes empty relieves the no meaning, so removing the node when it becomes empty relieves the
user from performing this task. user from performing this task.
In the second style, the presence of the container itself carries In the second style, the presence of the container itself carries
some meaning, representing a single bit of data. some meaning, representing a single bit of data.
For configuration data, the container acts as both a configuration For configuration data, the container acts as both a configuration
knob and a means of organizing related configuration. These knob and a means of organizing related configuration nodes. These
containers are explicitly created and deleted. containers are explicitly created and deleted.
YANG calls this style a "presence container" and it is indicated YANG calls this style a "presence container", and it is indicated
using the "presence" statement, which takes as its argument a text using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means. string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into For example, an "ssh" container may turn on the ability to log into
the server using ssh, but can also contain any ssh-related the server using Secure SHell (SSH) but can also contain any
configuration knobs, such as connection rates or retry limits. SSH-related configuration knobs, such as connection rates or retry
limits.
The "presence" statement (see Section 7.5.5) is used to give The "presence" statement (see Section 7.5.5) is used to give
semantics to the existence of the container in the data tree. semantics to the existence of the container in the data tree.
7.5.2. The container's Substatements 7.5.2. The container's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| action | 7.15 | 0..n | | action | 7.15 | 0..n |
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
skipping to change at page 66, line 29 skipping to change at page 69, line 5
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| notification | 7.16 | 0..n | | notification | 7.16 | 0..n |
| presence | 7.5.5 | 0..1 | | presence | 7.5.5 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.5.3. The must Statement 7.5.3. The "must" Statement
The "must" statement, which is optional, takes as an argument a The "must" statement, which is optional, takes as an argument a
string that contains an XPath expression (see Section 6.4). It is string that contains an XPath expression (see Section 6.4). It is
used to formally declare a constraint on valid data. The constraint used to formally declare a constraint on valid data. The constraint
is enforced according to the rules in Section 8. is enforced according to the rules in Section 8.
When a datastore is validated, all "must" constraints are When a datastore is validated, all "must" constraints are
conceptually evaluated once for each node in the accessible tree (see conceptually evaluated once for each node in the accessible tree (see
Section 6.4.1). Section 6.4.1).
skipping to change at page 67, line 39 skipping to change at page 70, line 16
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
7.5.4.1. The error-message Statement 7.5.4.1. The "error-message" Statement
The "error-message" statement, which is optional, takes a string as The "error-message" statement, which is optional, takes a string as
an argument. If the constraint evaluates to "false", the string is an argument. If the constraint evaluates to "false", the string is
passed as <error-message> in the <rpc-error> in NETCONF. passed as <error-message> in the <rpc-error> in NETCONF.
7.5.4.2. The error-app-tag Statement 7.5.4.2. The "error-app-tag" Statement
The "error-app-tag" statement, which is optional, takes a string as The "error-app-tag" statement, which is optional, takes a string as
an argument. If the constraint evaluates to "false", the string is an argument. If the constraint evaluates to "false", the string is
passed as <error-app-tag> in the <rpc-error> in NETCONF. passed as <error-app-tag> in the <rpc-error> in NETCONF.
7.5.4.3. Usage Example of must and error-message 7.5.4.3. Usage Example of must and error-message
container interface { container interface {
leaf ifType { leaf ifType {
type enumeration { type enumeration {
enum ethernet; enum ethernet;
enum atm; enum atm;
} }
} }
leaf ifMTU { leaf ifMTU {
type uint32; type uint32;
} }
must 'ifType != "ethernet" or ifMTU = 1500' { must 'ifType != "ethernet" or ifMTU = 1500' {
error-message "An ethernet MTU must be 1500"; error-message "An Ethernet MTU must be 1500";
} }
must 'ifType != "atm" or' must 'ifType != "atm" or'
+ ' (ifMTU <= 17966 and ifMTU >= 64)' { + ' (ifMTU <= 17966 and ifMTU >= 64)' {
error-message "An atm MTU must be 64 .. 17966"; error-message "An ATM MTU must be 64 .. 17966";
} }
} }
7.5.5. The presence Statement 7.5.5. The "presence" Statement
The "presence" statement assigns a meaning to the presence of a The "presence" statement assigns a meaning to the presence of a
container in the data tree. It takes as an argument a string that container in the data tree. It takes as an argument a string that
contains a textual description of what the node's presence means. contains a textual description of what the node's presence means.
If a container has the "presence" statement, the container's If a container has the "presence" statement, the container's
existence in the data tree carries some meaning. Otherwise, the existence in the data tree carries some meaning. Otherwise, the
container is used to give some structure to the data, and it carries container is used to give some structure to the data, and it carries
no meaning by itself. no meaning by itself.
skipping to change at page 69, line 18 skipping to change at page 72, line 8
Any whitespace between the subelements to the container is Any whitespace between the subelements to the container is
insignificant, i.e., an implementation MAY insert whitespace insignificant, i.e., an implementation MAY insert whitespace
characters between subelements. characters between subelements.
If a non-presence container does not have any child nodes, the If a non-presence container does not have any child nodes, the
container may or may not be present in the XML encoding. container may or may not be present in the XML encoding.
7.5.8. NETCONF <edit-config> Operations 7.5.8. NETCONF <edit-config> Operations
Containers can be created, deleted, replaced, and modified through Containers can be created, deleted, replaced, and modified through
<edit-config>, by using the "operation" attribute (see [RFC6241], <edit-config> by using the "operation" attribute (see Section 7.2 in
Section 7.2) in the container's XML element. [RFC6241]) in the container's XML element.
If a container does not have a "presence" statement and the last If a container does not have a "presence" statement and the last
child node is deleted, the NETCONF server MAY delete the container. child node is deleted, the NETCONF server MAY delete the container.
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for the container node are: elements of procedure for the container node are as follows:
If the operation is "merge" or "replace", the node is created if o If the operation is "merge" or "replace", the node is created if
it does not exist. it does not exist.
If the operation is "create", the node is created if it does not o If the operation is "create", the node is created if it does not
exist. If the node already exists, a "data-exists" error is exist. If the node already exists, a "data-exists" error is
returned. returned.
If the operation is "delete", the node is deleted if it exists. o If the operation is "delete", the node is deleted if it exists.
If the node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.5.9. Usage Example 7.5.9. Usage Example
Given the following container definition: Given the following container definition:
container system { container system {
description description
"Contains various system parameters"; "Contains various system parameters.";
container services { container services {
description description
"Configure externally available services"; "Configure externally available services.";
container "ssh" { container "ssh" {
presence "Enables SSH"; presence "Enables SSH";
description description
"SSH service specific configuration"; "SSH service-specific configuration.";
// more leafs, containers and stuff here... // more leafs, containers, and stuff here...
} }
} }
} }
A corresponding XML instance example: A corresponding XML instance example:
<system> <system>
<services> <services>
<ssh/> <ssh/>
</services> </services>
</system> </system>
Since the <ssh> element is present, ssh is enabled. Since the <ssh> element is present, SSH is enabled.
To delete a container with an <edit-config>: To delete a container with an <edit-config>:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<system xmlns="urn:example:config"> <system xmlns="urn:example:config">
<services> <services>
<ssh nc:operation="delete"/> <ssh nc:operation="delete"/>
</services> </services>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.6. The leaf Statement 7.6. The "leaf" Statement
The "leaf" statement is used to define a leaf node in the schema 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 tree. It takes one argument, which is an identifier, followed by a
block of substatements that holds detailed leaf information. block of substatements that holds detailed leaf information.
A leaf node has a value, but no child nodes in the data tree. 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 Conceptually, the value in the data tree is always in the canonical
form (see Section 9.1). form (see Section 9.1).
A leaf node exists in zero or one instances in the data tree. A leaf node exists in zero or one instance in the data tree.
The "leaf" statement is used to define a scalar variable of a The "leaf" statement is used to define a scalar variable of a
particular built-in or derived type. particular built-in or derived type.
7.6.1. The leaf's default value 7.6.1. The leaf's Default Value
The default value of a leaf is the value that the server uses if the The default value of a leaf is the value that the server uses if the
leaf does not exist in the data tree. The usage of the default value leaf does not exist in the data tree. The usage of the default value
depends on the leaf's closest ancestor node in the schema tree that depends on the leaf's closest ancestor node in the schema tree that
is not a non-presence container (see Section 7.5.1): is not a non-presence container (see Section 7.5.1):
o If no such ancestor exists in the schema tree, the default value o If no such ancestor exists in the schema tree, the default value
MUST be used. MUST be used.
o Otherwise, if this ancestor is a case node, the default value MUST o Otherwise, if this ancestor is a case node, the default value MUST
be used if any node from the case exists in the data tree, or if be used if any node from the case exists in the data tree or the
the case node is the choice's default case, and no nodes from any case node is the choice's default case, and if no nodes from any
other case exist in the data tree. other case exist in the data tree.
o Otherwise, the default value MUST be used if the ancestor node o Otherwise, the default value MUST be used if the ancestor node
exists in the data tree. exists in the data tree.
In these cases, the default value is said to be in use. In these cases, the default value is said to be in use.
Note that if the leaf or any of its ancestors has a "when" condition Note that if the leaf or any of its ancestors has a "when" condition
or "if-feature" expression that evaluates to "false", then the or "if-feature" expression that evaluates to "false", then the
default value is not in use. default value is not in use.
When the default value is in use, the server MUST operationally When the default value is in use, the server MUST operationally
behave as if the leaf was present in the data tree with the default behave as if the leaf was present in the data tree with the default
value as its value. value as its value.
If a leaf has a "default" statement, the leaf's default value is the If a leaf has a "default" statement, the leaf's default value is the
value of the "default" statement. Otherwise, if the leaf's type has 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 a default value and the leaf is not mandatory, then the leaf's
default value is the type's default value. In all other cases, the default value is the type's default value. In all other cases, the
leaf does not have a default value. leaf does not have a default value.
7.6.2. The leaf's Substatements 7.6.2. The leaf's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| default | 7.6.4 | 0..1 | | default | 7.6.4 | 0..1 |
skipping to change at page 72, line 23 skipping to change at page 75, line 23
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| mandatory | 7.6.5 | 0..1 | | mandatory | 7.6.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| type | 7.6.3 | 1 | | type | 7.6.3 | 1 |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.6.3. The leaf's type Statement 7.6.3. The leaf's "type" Statement
The "type" statement, which MUST be present, takes as an argument the The "type" statement, which MUST be present, takes as an argument the
name of an existing built-in or derived type. The optional name of an existing built-in or derived type. The optional
substatements specify restrictions on this type. See Section 7.4 for substatements specify restrictions on this type. See Section 7.4 for
details. details.
7.6.4. The leaf's default Statement 7.6.4. The leaf's "default" Statement
The "default" statement, which is optional, takes as an argument a The "default" statement, which is optional, takes as an argument a
string that contains a default value for the leaf. string that contains a default value for the leaf.
The value of the "default" statement MUST be valid according to the The value of the "default" statement MUST be valid according to the
type specified in the leaf's "type" statement. type specified in the leaf's "type" statement.
The "default" statement MUST NOT be present on nodes where The "default" statement MUST NOT be present on nodes where
"mandatory" is "true". "mandatory" is "true".
skipping to change at page 73, line 5 skipping to change at page 76, line 5
"if-feature" statement. For example, the following is illegal: "if-feature" statement. For example, the following is illegal:
leaf color { leaf color {
type enumeration { type enumeration {
enum blue { if-feature blue; } enum blue { if-feature blue; }
... ...
} }
default blue; // illegal - enum value is conditional default blue; // illegal - enum value is conditional
} }
7.6.5. The leaf's mandatory Statement 7.6.5. The leaf's "mandatory" Statement
The "mandatory" statement, which is optional, takes as an argument The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false", and puts a constraint on valid data. the string "true" or "false" and puts a constraint on valid data. If
If not specified, the default is "false". not specified, the default is "false".
If "mandatory" is "true", the behavior of the constraint depends on If "mandatory" is "true", the behavior of the constraint depends on
the type of the leaf's closest ancestor node in the schema tree that the type of the leaf's closest ancestor node in the schema tree that
is not a non-presence container (see Section 7.5.1): is not a non-presence container (see Section 7.5.1):
o If no such ancestor exists in the schema tree, the leaf MUST o If no such ancestor exists in the schema tree, the leaf MUST
exist. exist.
o Otherwise, if this ancestor is a case node, the leaf MUST exist if o Otherwise, if this ancestor is a case node, the leaf MUST exist if
any node from the case exists in the data tree. any node from the case exists in the data tree.
skipping to change at page 73, line 32 skipping to change at page 76, line 32
data tree. data tree.
This constraint is enforced according to the rules in Section 8. This constraint is enforced according to the rules in Section 8.
7.6.6. XML Encoding Rules 7.6.6. XML Encoding Rules
A leaf node is encoded as an XML element. The element's local name A leaf node is encoded as an XML element. The element's local name
is the leaf's identifier, and its namespace is the module's XML is the leaf's identifier, and its namespace is the module's XML
namespace (see Section 7.1.3). namespace (see Section 7.1.3).
The value of the leaf node is encoded to XML according to the type, The value of the leaf node is encoded to XML according to the type
and sent as character data in the element. and is sent as character data in the element.
See Section 7.6.8 for an example. See Section 7.6.8 for an example.
7.6.7. NETCONF <edit-config> Operations 7.6.7. NETCONF <edit-config> Operations
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for the leaf node are: elements of procedure for the leaf node are as follows:
If the operation is "merge" or "replace", the node is created if o If the operation is "merge" or "replace", the node is created if
it does not exist, and its value is set to the value found in the it does not exist, and its value is set to the value found in the
XML RPC data. XML RPC data.
If the operation is "create", the node is created if it does not o If the operation is "create", the node is created if it does not
exist. If the node already exists, a "data-exists" error is exist. If the node already exists, a "data-exists" error is
returned. returned.
If the operation is "delete", the node is deleted if it exists. o If the operation is "delete", the node is deleted if it exists.
If the node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.6.8. Usage Example 7.6.8. Usage Example
Given the following "leaf" statement, placed in the previously Given the following "leaf" statement, placed in the previously
defined "ssh" container (see Section 7.5.9): defined "ssh" container (see Section 7.5.9):
leaf port { leaf port {
type inet:port-number; type inet:port-number;
default 22; default 22;
description description
"The port to which the SSH server listens" "The port to which the SSH server listens.";
} }
A corresponding XML instance example: A corresponding XML instance example:
<port>2022</port> <port>2022</port>
To set the value of a leaf with an <edit-config>: To set the value of a leaf with an <edit-config>:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
skipping to change at page 74, line 42 skipping to change at page 77, line 42
<services> <services>
<ssh> <ssh>
<port>2022</port> <port>2022</port>
</ssh> </ssh>
</services> </services>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.7. The leaf-list Statement 7.7. The "leaf-list" Statement
Where the "leaf" statement is used to define a simple scalar variable 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 of a particular type, the "leaf-list" statement is used to define an
array of a particular type. The "leaf-list" statement takes one array of a particular type. The "leaf-list" statement takes one
argument, which is an identifier, followed by a block of argument, which is an identifier, followed by a block of
substatements that holds detailed leaf-list information. substatements that holds detailed leaf-list information.
In configuration data, the values in a leaf-list MUST be unique. In configuration data, the values in a leaf-list MUST be unique.
The definitions of the default values MUST NOT be marked with an The definitions of the default values MUST NOT be marked with an
skipping to change at page 75, line 18 skipping to change at page 78, line 18
Conceptually, the values in the data tree MUST be in the canonical Conceptually, the values in the data tree MUST be in the canonical
form (see Section 9.1). form (see Section 9.1).
7.7.1. Ordering 7.7.1. Ordering
YANG supports two styles for ordering the entries within lists and YANG supports two styles for ordering the entries within lists and
leaf-lists. In many lists, the order of list entries does not impact leaf-lists. In many lists, the order of list entries does not impact
the implementation of the list's configuration, and the server is the implementation of the list's configuration, and the server is
free to sort the list entries in any reasonable order. The free to sort the list entries in any reasonable order. The
"description" string for the list may suggest an order to the server "description" string for the list may suggest an order to the server
implementor. YANG calls this style of list "system ordered" and they implementor. YANG calls this style of list "system ordered"; such
are indicated with the statement "ordered-by system". lists are indicated with the statement "ordered-by system".
For example, a list of valid users would typically be sorted For example, a list of valid users would typically be sorted
alphabetically, since the order in which the users appeared in the alphabetically, since the order in which the users appeared in the
configuration would not impact the creation of those users' accounts. configuration would not impact the creation of those users' accounts.
In the other style of lists, the order of list entries matters for In the other style of lists, the order of list entries matters for
the implementation of the list's configuration and the user is the implementation of the list's configuration and the user is
responsible for ordering the entries, while the server maintains that responsible for ordering the entries, while the server maintains that
order. YANG calls this style of list "user ordered" and they are order. YANG calls this style of list "user ordered"; such lists are
indicated with the statement "ordered-by user". indicated with the statement "ordered-by user".
For example, the order in which packet filters entries are applied to For example, the order in which packet filter entries are applied to
incoming traffic may affect how that traffic is filtered. The user incoming traffic may affect how that traffic is filtered. The user
would need to decide if the filter entry that discards all TCP would need to decide if the filter entry that discards all TCP
traffic should be applied before or after the filter entry that traffic should be applied before or after the filter entry that
allows all traffic from trusted interfaces. The choice of order allows all traffic from trusted interfaces. The choice of order
would be crucial. would be crucial.
YANG provides a rich set of facilities within NETCONF's <edit-config> YANG provides a rich set of facilities within NETCONF's <edit-config>
operation that allows the order of list entries in user-ordered lists operation that allows the order of list entries in user-ordered lists
to be controlled. List entries may be inserted or rearranged, to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned positioned as the first or last entry in the list, or positioned
before or after another specific entry. before or after another specific entry.
The "ordered-by" statement is covered in Section 7.7.7. The "ordered-by" statement is covered in Section 7.7.7.
7.7.2. The leaf-list's default values 7.7.2. The leaf-list's Default Values
The default values of a leaf-list are the values that the server uses The default values of a leaf-list are the values that the server uses
if the leaf-list does not exist in the data tree. The usage of the if the leaf-list does not exist in the data tree. The usage of the
default values depends on the leaf-list's closest ancestor node in default values depends on the leaf-list's closest ancestor node in
the schema tree that is not a non-presence container (see the schema tree that is not a non-presence container (see
Section 7.5.1): Section 7.5.1):
o If no such ancestor exists in the schema tree, the default values o If no such ancestor exists in the schema tree, the default values
MUST be used. MUST be used.
o Otherwise, if this ancestor is a case node, the default values o Otherwise, if this ancestor is a case node, the default values
MUST be used if any node from the case exists in the data tree, or MUST be used if any node from the case exists in the data tree or
if the case node is the choice's default case, and no nodes from the case node is the choice's default case, and if no nodes from
any other case exist in the data tree. any other case exist in the data tree.
o Otherwise, the default values MUST be used if the ancestor node o Otherwise, the default values MUST be used if the ancestor node
exists in the data tree. exists in the data tree.
In these cases, the default values are said to be in use. In these cases, the default values are said to be in use.
Note that if the leaf-list or any of its ancestors has a "when" Note that if the leaf-list or any of its ancestors has a "when"
condition or "if-feature" expression that evaluates to "false", then condition or "if-feature" expression that evaluates to "false", then
the default values are not in use. the default values are not in use.
When the default values are in use, the server MUST operationally When the default values are in use, the server MUST operationally
behave as if the leaf-list was present in the data tree with the behave as if the leaf-list was present in the data tree with the
default values as its values. default values as its values.
If a leaf-list has one or more "default" statement, the leaf-list's If a leaf-list has one or more "default" statements, the leaf-list's
default values are the values of the "default" statements, and if the default values are the values of the "default" statements, and if the
leaf-list is user-ordered, the default values are used in the order leaf-list is user ordered, the default values are used in the order
of the "default" statements. Otherwise, if the leaf-list's type has of the "default" statements. Otherwise, if the leaf-list's type has
a default value, and the leaf-list does not have a "min-elements" a default value and the leaf-list does not have a "min-elements"
statement with a value greater than or equal to one, then the leaf- statement with a value greater than or equal to one, then the
list's default value is one instance of the type's default value. In leaf-list's default value is one instance of the type's default
all other cases, the leaf-list does not have any default values. value. In all other cases, the leaf-list does not have any default
values.
7.7.3. The leaf-list's Substatements 7.7.3. The leaf-list's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| default | 7.7.4 | 0..n | | default | 7.7.4 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| max-elements | 7.7.6 | 0..1 | | max-elements | 7.7.6 | 0..1 |
| min-elements | 7.7.5 | 0..1 | | min-elements | 7.7.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
skipping to change at page 77, line 22 skipping to change at page 80, line 25
| min-elements | 7.7.5 | 0..1 | | min-elements | 7.7.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| ordered-by | 7.7.7 | 0..1 | | ordered-by | 7.7.7 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| type | 7.4 | 1 | | type | 7.4 | 1 |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.7.4. The leaf-list's default Statement 7.7.4. The leaf-list's "default" Statement
The "default" statement, which is optional, takes as an argument a The "default" statement, which is optional, takes as an argument a
string that contains a default value for the leaf-list. string that contains a default value for the leaf-list.
The value of the "default" statement MUST be valid according to the The value of the "default" statement MUST be valid according to the
type specified in the leaf-list's "type" statement. type specified in the leaf-list's "type" statement.
The "default" statement MUST NOT be present on nodes where The "default" statement MUST NOT be present on nodes where
"min-elements" has a value greater than or equal to one. "min-elements" has a value greater than or equal to one.
7.7.5. The min-elements Statement 7.7.5. The "min-elements" Statement
The "min-elements" statement, which is optional, takes as an argument The "min-elements" statement, which is optional, takes as an argument
a non-negative integer that puts a constraint on valid list entries. a non-negative integer that puts a constraint on valid list entries.
A valid leaf-list or list MUST have at least min-elements entries. A valid leaf-list or list MUST have at least min-elements entries.
If no "min-elements" statement is present, it defaults to zero. If no "min-elements" statement is present, it defaults to zero.
The behavior of the constraint depends on the type of the leaf-list's The behavior of the constraint depends on the type of the leaf-list's
or list's closest ancestor node in the schema tree that is not a non- or list's closest ancestor node in the schema tree that is not a
presence container (see Section 7.5.1): non-presence container (see Section 7.5.1):
o If no such ancestor exists in the schema tree, the constraint is o If no such ancestor exists in the schema tree, the constraint is
enforced. enforced.
o Otherwise, if this ancestor is a case node, the constraint is o Otherwise, if this ancestor is a case node, the constraint is
enforced if any other node from the case exists. enforced if any other node from the case exists.
o Otherwise, it is enforced if the ancestor node exists. o Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in The constraint is further enforced according to the rules in
Section 8. Section 8.
7.7.6. The max-elements Statement 7.7.6. The "max-elements" Statement
The "max-elements" statement, which is optional, takes as an argument The "max-elements" statement, which is optional, takes as an argument
a positive integer or the string "unbounded", which puts a constraint 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 on valid list entries. A valid leaf-list or list always has at most
max-elements entries. max-elements entries.
If no "max-elements" statement is present, it defaults to If no "max-elements" statement is present, it defaults to
"unbounded". "unbounded".
The "max-elements" constraint is enforced according to the rules in The "max-elements" constraint is enforced according to the rules in
Section 8. Section 8.
7.7.7. The ordered-by Statement 7.7.7. The "ordered-by" Statement
The "ordered-by" statement defines whether the order of entries The "ordered-by" statement defines whether the order of entries
within a list are determined by the user or the system. The argument 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 is one of the strings "system" or "user". If not present, ordering
defaults to "system". defaults to "system".
This statement is ignored if the list represents state data, RPC This statement is ignored if the list represents state data, RPC
output parameters, or notification content. output parameters, or notification content.
See Section 7.7.1 for additional information. See Section 7.7.1 for additional information.
7.7.7.1. ordered-by system 7.7.7.1. ordered-by system
The entries in the list are ordered according to an order determined The entries in the list are ordered according to an order determined
skipping to change at page 79, line 12 skipping to change at page 82, line 12
attributes in the <edit-config> request. See Section 7.7.9 for attributes in the <edit-config> request. See Section 7.7.9 for
details. details.
7.7.8. XML Encoding Rules 7.7.8. XML Encoding Rules
A leaf-list node is encoded as a series of XML elements. Each A leaf-list node is encoded as a series of XML elements. Each
element's local name is the leaf-list's identifier, and its namespace element's local name is the leaf-list's identifier, and its namespace
is the module's XML namespace (see Section 7.1.3). is the module's XML namespace (see Section 7.1.3).
The value of each leaf-list entry is encoded to XML according to the The value of each leaf-list entry is encoded to XML according to the
type, and sent as character data in the element. type and is sent as character data in the element.
The XML elements representing leaf-list entries MUST appear in the The XML elements representing leaf-list entries MUST appear in the
order specified by the user if the leaf-list is "ordered-by user"; order specified by the user if the leaf-list is "ordered-by user";
otherwise, the order is implementation-dependent. The XML elements otherwise, the order is implementation dependent. The XML elements
representing leaf-list entries MAY be interleaved with elements for representing leaf-list entries MAY be interleaved with elements for
siblings of the leaf-list, unless the leaf-list defines RPC or action siblings of the leaf-list, unless the leaf-list defines RPC or action
input or output parameters. input or output parameters.
See Section 7.7.10 for an example. See Section 7.7.10 for an example.
7.7.9. NETCONF <edit-config> Operations 7.7.9. NETCONF <edit-config> Operations
Leaf-list entries can be created and deleted, but not modified, Leaf-list entries can be created and deleted, but not modified,
through <edit-config>, by using the "operation" attribute in the through <edit-config>, by using the "operation" attribute in the
skipping to change at page 79, line 38 skipping to change at page 82, line 38
In an "ordered-by user" leaf-list, the attributes "insert" and 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 "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 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 used during "create" operations to insert a new leaf-list entry, or
during "merge" or "replace" operations to insert a new leaf-list during "merge" or "replace" operations to insert a new leaf-list
entry or move an existing one. entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before", The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "value" and "after". If the value is "before" or "after", the "value"
attribute MUST also be used to specify an existing entry in the leaf- attribute MUST also be used to specify an existing entry in the
list. leaf-list.
If no "insert" attribute is present in the "create" operation, it If no "insert" attribute is present in the "create" operation, it
defaults to "last". defaults to "last".
If several entries in an "ordered-by user" leaf-list are modified in If several entries in an "ordered-by user" leaf-list are modified in
the same <edit-config> request, the entries are modified one at the the same <edit-config> request, the entries are modified one at a
time, in the order of the XML elements in the request. time, in the order of the XML elements in the request.
In a <copy-config>, or an <edit-config> with a "replace" operation In a <copy-config> or in an <edit-config> with a "replace" operation
that covers the entire leaf-list, the leaf-list order is the same as that covers the entire leaf-list, the leaf-list order is the same as
the order of the XML elements in the request. the order of the XML elements in the request.
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for a leaf-list node are: elements of procedure for a leaf-list node are as follows:
If the operation is "merge" or "replace", the leaf-list entry is o If the operation is "merge" or "replace", the leaf-list entry is
created if it does not exist. created if it does not exist.
If the operation is "create", the leaf-list entry is created if it o If the operation is "create", the leaf-list entry is created if it
does not exist. If the leaf-list entry already exists, a does not exist. If the leaf-list entry already exists, a
"data-exists" error is returned. "data-exists" error is returned.
If the operation is "delete", the entry is deleted from the leaf- o If the operation is "delete", the entry is deleted from the
list if it exists. If the leaf-list entry does not exist, a leaf-list if it exists. If the leaf-list entry does not exist, a
"data-missing" error is returned. "data-missing" error is returned.
7.7.10. Usage Example 7.7.10. Usage Example
leaf-list allow-user { leaf-list allow-user {
type string; type string;
description description
"A list of user name patterns to allow"; "A list of user name patterns to allow.";
} }
A corresponding XML instance example: A corresponding XML instance example:
<allow-user>alice</allow-user> <allow-user>alice</allow-user>
<allow-user>bob</allow-user> <allow-user>bob</allow-user>
To create a new element in this list, using the default <edit-config> To create a new element in this list, using the default <edit-config>
operation "merge": operation "merge":
skipping to change at page 81, line 7 skipping to change at page 84, line 7
<allow-user>eric</allow-user> <allow-user>eric</allow-user>
</ssh> </ssh>
</services> </services>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
Given the following ordered-by user leaf-list: Given the following ordered-by user leaf-list:
leaf-list cipher { leaf-list cipher {
type string; type string;
ordered-by user; ordered-by user;
description description
"A list of ciphers"; "A list of ciphers.";
} }
The following would be used to insert a new cipher "blowfish-cbc" The following would be used to insert a new cipher "blowfish-cbc"
after "3des-cbc": after "3des-cbc":
<rpc message-id="102" <rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="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"> xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config> <edit-config>
skipping to change at page 81, line 39 skipping to change at page 84, line 39
<cipher nc:operation="create" <cipher nc:operation="create"
yang:insert="after" yang:insert="after"
yang:value="3des-cbc">blowfish-cbc</cipher> yang:value="3des-cbc">blowfish-cbc</cipher>
</ssh> </ssh>
</services> </services>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.8. The list Statement 7.8. The "list" Statement
The "list" statement is used to define an interior data node in the The "list" statement is used to define an interior data node in the
schema tree. A list node may exist in multiple instances in the data 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" tree. Each such instance is known as a list entry. The "list"
statement takes one argument, which is an identifier, followed by a statement takes one argument, which is an identifier, followed by a
block of substatements that holds detailed list information. block of substatements that holds detailed list information.
A list entry is uniquely identified by the values of the list's keys, A list entry is uniquely identified by the values of the list's keys,
if defined. if defined.
skipping to change at page 82, line 36 skipping to change at page 85, line 36
| notification | 7.16 | 0..n | | notification | 7.16 | 0..n |
| ordered-by | 7.7.7 | 0..1 | | ordered-by | 7.7.7 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| unique | 7.8.3 | 0..n | | unique | 7.8.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.8.2. The list's key Statement 7.8.2. The list's "key" Statement
The "key" statement, which MUST be present if the list represents The "key" statement, which MUST be present if the list represents
configuration, and MAY be present otherwise, takes as an argument a configuration and MAY be present otherwise, takes as an argument a
string that specifies a space-separated list of one or more leaf string that specifies a space-separated list of one or more leaf
identifiers of this list. A leaf identifier MUST NOT appear more identifiers of this list. A leaf identifier MUST NOT appear more
than once in the key. Each such leaf identifier MUST refer to a than once in the key. Each such leaf identifier MUST refer to a
child leaf of the list. The leafs can be defined directly in child leaf of the list. The leafs can be defined directly in
substatements to the list, or in groupings used in the list. substatements to the list or in groupings used in the list.
The combined values of all the leafs specified in the key are used to The combined values of all the leafs specified in the key are used to
uniquely identify a list entry. All key leafs MUST be given values uniquely identify a list entry. All key leafs MUST be given values
when a list entry is created. Thus, any default values in the key when a list entry is created. Thus, any default values in the key
leafs or their types are ignored. It also implies that any mandatory leafs or their types are ignored. Any "mandatory" statements in the
statement in the key leafs are ignored. key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived A leaf that is part of the key can be of any built-in or
type. derived type.
All key leafs in a list MUST have the same value for their "config" All key leafs in a list MUST have the same value for their "config"
as the list itself. as the list itself.
The key string syntax is formally defined by the rule "key-arg" in The key string syntax is formally defined by the rule "key-arg" in
Section 14. Section 14.
7.8.3. The list's unique Statement 7.8.3. The list's "unique" Statement
The "unique" statement is used to put constraints on valid list The "unique" statement is used to put constraints on valid list
entries. It takes as an argument a string that contains a space- entries. It takes as an argument a string that contains a space-
separated list of schema node identifiers, which MUST be given in the separated list of schema node identifiers, which MUST be given in the
descendant form (see the rule "descendant-schema-nodeid" in descendant form (see the rule "descendant-schema-nodeid" in
Section 14). Each such schema node identifier MUST refer to a leaf. Section 14). Each such schema node identifier MUST refer to a leaf.
If one of the referenced leafs represents configuration data, then If one of the referenced leafs represents configuration data, then
all of the referenced leafs MUST represent configuration data. all of the referenced leafs MUST represent configuration data.
skipping to change at page 83, line 52 skipping to change at page 87, line 5
type string; type string;
} }
leaf ip { leaf ip {
type inet:ip-address; type inet:ip-address;
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
} }
} }
The following configuration is not valid: the following configuration is not valid:
<server> <server>
<name>smtp</name> <name>smtp</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>25</port> <port>25</port>
</server> </server>
<server> <server>
<name>http</name> <name>http</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>25</port> <port>25</port>
</server> </server>
The following configuration is valid, since the "http" and "ftp" list The following configuration is valid, since the "http" and "ftp" list
entries do not have a value for all referenced leafs, and are thus entries do not have a value for all referenced leafs and are thus not
not taken into account when the "unique" constraint is enforced: taken into account when the "unique" constraint is enforced:
<server> <server>
<name>smtp</name> <name>smtp</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>25</port> <port>25</port>
</server> </server>
<server> <server>
<name>http</name> <name>http</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
skipping to change at page 85, line 16 skipping to change at page 88, line 27
list element, after the keys. If the list defines RPC or action list element, after the keys. If the list defines RPC or action
input or output parameters, the subelements are encoded in the same input or output parameters, the subelements are encoded in the same
order as they are defined within the "list" statement. Otherwise, order as they are defined within the "list" statement. Otherwise,
the subelements are encoded in any order. the subelements are encoded in any order.
Any whitespace between the subelements to the list entry is Any whitespace between the subelements to the list entry is
insignificant, i.e., an implementation MAY insert whitespace insignificant, i.e., an implementation MAY insert whitespace
characters between subelements. characters between subelements.
The XML elements representing list entries MUST appear in the order The XML elements representing list entries MUST appear in the order
specified by the user if the list is "ordered-by user", otherwise the specified by the user if the list is "ordered-by user"; otherwise,
order is implementation-dependent. The XML elements representing the order is implementation dependent. The XML elements representing
list entries MAY be interleaved with elements for siblings of the list entries MAY be interleaved with elements for siblings of the
list, unless the list defines RPC or action input or output list, unless the list defines RPC or action input or output
parameters. parameters.
7.8.6. NETCONF <edit-config> Operations 7.8.6. NETCONF <edit-config> Operations
List entries can be created, deleted, replaced, and modified through List entries can be created, deleted, replaced, and modified through
<edit-config>, by using the "operation" attribute in the list's XML <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 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 identify a list entry. If all keys are not specified for a list
entry, a "missing-element" error is returned. entry, a "missing-element" error is returned.
In an "ordered-by user" list, the attributes "insert" and "key" in 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 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" 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 during "merge" or "replace"
operations to insert a new list entry or move an existing one. operations to insert a new list entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before", The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "key" and "after". If the value is "before" or "after", the "key"
attribute MUST also be used, to specify an existing element in the 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 list. The value of the "key" attribute is the key predicates of the
full instance identifier (see Section 9.13) for the list entry. full instance identifier (see Section 9.13) for the list entry.
If no "insert" attribute is present in the "create" operation, it If no "insert" attribute is present in the "create" operation, it
defaults to "last". defaults to "last".
If several entries in an "ordered-by user" list are modified in the If several entries in an "ordered-by user" list are modified in the
same <edit-config> request, the entries are modified one at the time, same <edit-config> request, the entries are modified one at a time,
in the order of the XML elements in the request. in the order of the XML elements in the request.
In a <copy-config>, or an <edit-config> with a "replace" operation In a <copy-config> or in an <edit-config> with a "replace" operation
that covers the entire list, the list entry order is the same as the that covers the entire list, the list entry order is the same as the
order of the XML elements in the request. order of the XML elements in the request.
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for a list node are: elements of procedure for a list node are as follows:
If the operation is "merge" or "replace", the list entry is o If the operation is "merge" or "replace", the list entry is
created if it does not exist. If the list entry already exists created if it does not exist. If the list entry already exists
and the "insert" and "key" attributes are present, the list entry and the "insert" and "key" attributes are present, the list entry
is moved according to the values of the "insert" and "key" is moved according to the values of the "insert" and "key"
attributes. If the list entry exists and the "insert" and "key" attributes. If the list entry exists and the "insert" and "key"
attributes are not present, the list entry is not moved. attributes are not present, the list entry is not moved.
If the operation is "create", the list entry is created if it does o If the operation is "create", the list entry is created if it does
not exist. If the list entry already exists, a "data-exists" not exist. If the list entry already exists, a "data-exists"
error is returned. error is returned.
If the operation is "delete", the entry is deleted from the list o If the operation is "delete", the entry is deleted from the list
if it exists. If the list entry does not exist, a "data-missing" if it exists. If the list entry does not exist, a "data-missing"
error is returned. error is returned.
7.8.7. Usage Example 7.8.7. Usage Example
Given the following list: Given the following list:
list user { list user {
key "name"; key "name";
config true; config true;
skipping to change at page 89, line 28 skipping to change at page 93, line 31
yang:key="[ex:name='fred'] yang:key="[ex:name='fred']
[ex:surname='flintstone']"> [ex:surname='flintstone']">
<first-name>barney</first-name> <first-name>barney</first-name>
<surname>rubble</surname> <surname>rubble</surname>
</user> </user>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.9. The choice Statement 7.9. The "choice" Statement
The "choice" statement defines a set of alternatives, only one of The "choice" statement defines a set of alternatives, only one of
which may be present in any one data tree. The argument is an which may be present in any one data tree. The argument is an
identifier, followed by a block of substatements that holds detailed identifier, followed by a block of substatements that holds detailed
choice information. The identifier is used to identify the choice choice information. The identifier is used to identify the choice
node in the schema tree. A choice node does not exist in the data node in the schema tree. A choice node does not exist in the data
tree. tree.
A choice consists of a number of branches, each defined with a "case" A choice consists of a number of branches, each defined with a "case"
substatement. Each branch contains a number of child nodes. The substatement. Each branch contains a number of child nodes. The
skipping to change at page 90, line 25 skipping to change at page 94, line 28
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| mandatory | 7.9.4 | 0..1 | | mandatory | 7.9.4 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.9.2. The choice's case Statement 7.9.2. The choice's "case" Statement
The "case" statement is used to define branches of the choice. It The "case" statement is used to define branches of the choice. It
takes as an argument an identifier, followed by a block of takes as an argument an identifier, followed by a block of
substatements that holds detailed case information. substatements that holds detailed case information.
The identifier is used to identify the case node in the schema tree. The identifier is used to identify the case node in the schema tree.
A case node does not exist in the data tree. A case node does not exist in the data tree.
Within a "case" statement, the "anydata", "anyxml", "choice", Within a "case" statement, the "anydata", "anyxml", "choice",
"container", "leaf", "list", "leaf-list", and "uses" statements can "container", "leaf", "list", "leaf-list", and "uses" statements can
skipping to change at page 91, line 43 skipping to change at page 96, line 5
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.9.3. The choice's default Statement 7.9.3. The choice's "default" Statement
The "default" statement indicates if a case should be considered as The "default" statement indicates if a case should be considered as
the default if no child nodes from any of the choice's cases exist. the default if no child nodes from any of the choice's cases exist.
The argument is the identifier of the default "case" statement. If The argument is the identifier of the default "case" statement. If
the "default" statement is missing, there is no default case. the "default" statement is missing, there is no default case.
The "default" statement MUST NOT be present on choices where The "default" statement MUST NOT be present on choices where
"mandatory" is "true". "mandatory" is "true".
The default case is only important when considering the default The default case is only important when considering the "default"
statements of nodes under the cases (i.e., default values of leafs statements of nodes under the cases (i.e., default values of leafs
and leaf-lists, and default cases of nested choices). The default and leaf-lists, and default cases of nested choices). The default
values and nested default cases under the default case are used if values and nested default cases under the default case are used if
none of the nodes under any of the cases are present. none of the nodes under any of the cases are present.
There MUST NOT be any mandatory nodes (Section 3) directly under the There MUST NOT be any mandatory nodes (Section 3) directly under the
default case. default case.
Default values for child nodes under a case are only used if one of Default values for child nodes under a case are only used if one of
the nodes under that case is present, or if that case is the default the nodes under that case is present or if that case is the default
case. If none of the nodes under a case are present and the case is case. If none of the nodes under a case are present and the case is
not the default case, the default values of the cases' child nodes not the default case, the default values of the cases' child nodes
are ignored. are ignored.
In this example, the choice defaults to "interval", and the default In this example, the choice defaults to "interval", and the default
value will be used if none of "daily", "time-of-day", or "manual" are value will be used if none of "daily", "time-of-day", or "manual" are
present. If "daily" is present, the default value for "time-of-day" present. If "daily" is present, the default value for "time-of-day"
will be used. will be used.
container transfer { container transfer {
skipping to change at page 93, line 5 skipping to change at page 98, line 5
} }
} }
case manual { case manual {
leaf manual { leaf manual {
type empty; type empty;
} }
} }
} }
} }
7.9.4. The choice's mandatory Statement 7.9.4. The choice's "mandatory" Statement
The "mandatory" statement, which is optional, takes as an argument The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false", and puts a constraint on valid data. the string "true" or "false" and puts a constraint on valid data. If
If "mandatory" is "true", at least one node from exactly one of the "mandatory" is "true", at least one node from exactly one of the
choice's case branches MUST exist. choice's case branches MUST exist.
If not specified, the default is "false". If not specified, the default is "false".
The behavior of the constraint depends on the type of the choice's The behavior of the constraint depends on the type of the choice's
closest ancestor node in the schema tree that is not a non-presence closest ancestor node in the schema tree that is not a non-presence
container (see Section 7.5.1): container (see Section 7.5.1):
o If no such ancestor exists in the schema tree, the constraint is o If no such ancestor exists in the schema tree, the constraint is
enforced. enforced.
skipping to change at page 94, line 26 skipping to change at page 99, line 30
} }
} }
} }
A corresponding XML instance example: A corresponding XML instance example:
<protocol> <protocol>
<tcp/> <tcp/>
</protocol> </protocol>
To change the protocol from tcp to udp: To change the protocol from TCP to UDP:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<system xmlns="urn:example:config"> <system xmlns="urn:example:config">
<protocol> <protocol>
<udp nc:operation="create"/> <udp nc:operation="create"/>
</protocol> </protocol>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.10. The anydata Statement 7.10. The "anydata" Statement
The "anydata" statement defines an interior node in the schema tree. The "anydata" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anydata information. substatements that holds detailed anydata information.
The "anydata" statement is used to represent an unknown set of nodes The "anydata" statement is used to represent an unknown set of nodes
that can be modelled with YANG, except anyxml, but for which the data that can be modeled with YANG, except anyxml, but for which the data
model is not known at module design time. It is possible, though not model is not known at module design time. It is possible, though not
required, for the data model for "anydata" content to become known required, for the data model for anydata content to become known
through protocol signalling or other means that are outside the scope through protocol signaling or other means that are outside the scope
of this document. of this document.
An example of where anydata can be useful is a list of received An example of where anydata can be useful is a list of received
notifications, where the specific notifications are not known at notifications where the specific notifications are not known at
design time. design time.
An anydata node cannot be augmented (see Section 7.17). An anydata node cannot be augmented (see Section 7.17).
An anydata node exists in zero or one instances in the data tree. An anydata node exists in zero or one instance in the data tree.
An implementation may or may not know the data model used to model a An implementation may or may not know the data model used to model a
specific instance of an anydata node. specific instance of an anydata node.
Since the use of anydata limits the manipulation of the content, the Since the use of anydata limits the manipulation of the content, the
"anydata" statement SHOULD NOT be used to define configuration data. "anydata" statement SHOULD NOT be used to define configuration data.
7.10.1. The anydata's Substatements 7.10.1. The anydata's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 96, line 9 skipping to change at page 101, line 22
7.10.3. NETCONF <edit-config> Operations 7.10.3. NETCONF <edit-config> Operations
An anydata node is treated as an opaque chunk of data. This data can An anydata node is treated as an opaque chunk of data. This data can
be modified in its entirety only. be modified in its entirety only.
Any "operation" attributes present on subelements of an anydata node Any "operation" attributes present on subelements of an anydata node
are ignored by the NETCONF server. are ignored by the NETCONF server.
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for the anydata node are: elements of procedure for the anydata node are as follows:
If the operation is "merge" or "replace", the node is created if o If the operation is "merge" or "replace", the node is created if
it does not exist, and its value is set to the subelements of the it does not exist, and its value is set to the subelements of the
anydata node found in the XML RPC data. anydata node found in the XML RPC data.
If the operation is "create", the node is created if it does not o If the operation is "create", the node is created if it does not
exist, and its value is set to the subelements of the anydata node exist, and its value is set to the subelements of the anydata node
found in the XML RPC data. If the node already exists, a found in the XML RPC data. If the node already exists, a
"data-exists" error is returned. "data-exists" error is returned.
If the operation is "delete", the node is deleted if it exists. o If the operation is "delete", the node is deleted if it exists.
If the node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.10.4. Usage Example 7.10.4. Usage Example
Given the following "anydata" statement: Given the following "anydata" statement:
list logged-notification { list logged-notification {
key time; key time;
leaf time { leaf time {
type yang:date-and-time; type yang:date-and-time;
skipping to change at page 97, line 4 skipping to change at page 102, line 22
<eventTime>2014-07-29T13:43:01Z</eventTime> <eventTime>2014-07-29T13:43:01Z</eventTime>
<event xmlns="urn:example:event"> <event xmlns="urn:example:event">
<event-class>fault</event-class> <event-class>fault</event-class>
<reporting-entity> <reporting-entity>
<card>Ethernet0</card> <card>Ethernet0</card>
</reporting-entity> </reporting-entity>
<severity>major</severity> <severity>major</severity>
</event> </event>
</notification> </notification>
</data> </data>
</logged-notification>
7.11. The anyxml Statement 7.11. The "anyxml" Statement
The "anyxml" statement defines an interior node in the schema tree. The "anyxml" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anyxml information. substatements that holds detailed anyxml information.
The "anyxml" statement is used to represent an unknown chunk of XML. The "anyxml" statement is used to represent an unknown chunk of XML.
No restrictions are placed on the XML. This can be useful, for No restrictions are placed on the XML. This can be useful, for
example, in RPC replies. An example is the <filter> parameter in the example, in RPC replies. An example is the <filter> parameter in the
<get-config> operation in NETCONF. <get-config> operation in NETCONF.
An anyxml node cannot be augmented (see Section 7.17). An anyxml node cannot be augmented (see Section 7.17).
An anyxml node exists in zero or one instances in the data tree. An anyxml node exists in zero or one instance in the data tree.
Since the use of anyxml limits the manipulation of the content, the Since the use of anyxml limits the manipulation of the content, the
"anyxml" statement SHOULD NOT be used to define configuration data. "anyxml" statement SHOULD NOT be used to define configuration data.
It should be noted that in YANG version 1, anyxml was the only It should be noted that in YANG version 1, "anyxml" was the only
statement that could model an unknown hierarchy of data. In many statement that could model an unknown hierarchy of data. In many
cases this unknown hierarchy of data is actually modelled in YANG, cases, this unknown hierarchy of data is actually modeled in YANG,
but the specific YANG data model is not known at design time. In but the specific YANG data model is not known at design time. In
these situations, it is RECOMMENDED to use anydata (Section 7.10) these situations, it is RECOMMENDED to use "anydata" (Section 7.10)
instead of anyxml. instead of "anyxml".
7.11.1. The anyxml's Substatements 7.11.1. The anyxml's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| mandatory | 7.6.5 | 0..1 | | mandatory | 7.6.5 | 0..1 |
skipping to change at page 98, line 18 skipping to change at page 103, line 40
7.11.3. NETCONF <edit-config> Operations 7.11.3. NETCONF <edit-config> Operations
An anyxml node is treated as an opaque chunk of data. This data can An anyxml node is treated as an opaque chunk of data. This data can
be modified in its entirety only. be modified in its entirety only.
Any "operation" attributes present on subelements of an anyxml node Any "operation" attributes present on subelements of an anyxml node
are ignored by the NETCONF server. are ignored by the NETCONF server.
When a NETCONF server processes an <edit-config> request, the When a NETCONF server processes an <edit-config> request, the
elements of procedure for the anyxml node are: elements of procedure for the anyxml node are as follows:
If the operation is "merge" or "replace", the node is created if o If the operation is "merge" or "replace", the node is created if
it does not exist, and its value is set to the XML content of the it does not exist, and its value is set to the XML content of the
anyxml node found in the XML RPC data. anyxml node found in the XML RPC data.
If the operation is "create", the node is created if it does not o 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 exist, and its value is set to the XML content of the anyxml node
found in the XML RPC data. If the node already exists, a found in the XML RPC data. If the node already exists, a
"data-exists" error is returned. "data-exists" error is returned.
If the operation is "delete", the node is deleted if it exists. o If the operation is "delete", the node is deleted if it exists.
If the node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.11.4. Usage Example 7.11.4. Usage Example
Given the following "anyxml" statement: Given the following "anyxml" statement:
anyxml html-info; anyxml html-info;
The following are two valid encodings of the same anyxml value: The following are two valid encodings of the same anyxml value:
skipping to change at page 99, line 5 skipping to change at page 104, line 25
This is <em>very</em> cool. This is <em>very</em> cool.
</p> </p>
</html-info> </html-info>
<html-info> <html-info>
<x:p xmlns:x="http://www.w3.org/1999/xhtml"> <x:p xmlns:x="http://www.w3.org/1999/xhtml">
This is <x:em>very</x:em> cool. This is <x:em>very</x:em> cool.
</x:p> </x:p>
</html-info> </html-info>
7.12. The grouping Statement 7.12. The "grouping" Statement
The "grouping" statement is used to define a reusable block of nodes, The "grouping" statement is used to define a reusable block of nodes,
which may be used locally in the module or submodule, and by other which may be used locally in the module or submodule, and by other
modules that import from it, according to the rules in Section 5.5. modules that import from it, according to the rules in Section 5.5.
It takes one argument, which is an identifier, followed by a block of It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed grouping information. substatements that holds detailed grouping information.
The "grouping" statement is not a data definition statement and, as The "grouping" statement is not a data definition statement and, as
such, does not define any nodes in the schema tree. such, does not define any nodes in the schema tree.
skipping to change at page 99, line 27 skipping to change at page 104, line 47
programming languages. programming languages.
Once a grouping is defined, it can be referenced in a "uses" Once a grouping is defined, it can be referenced in a "uses"
statement (see Section 7.13). A grouping MUST NOT reference itself, statement (see Section 7.13). A grouping MUST NOT reference itself,
neither directly nor indirectly through a chain of other groupings. neither directly nor indirectly through a chain of other groupings.
If the grouping is defined at the top level of a YANG module or If the grouping is defined at the top level of a YANG module or
submodule, the grouping's identifier MUST be unique within the submodule, the grouping's identifier MUST be unique within the
module. module.
A grouping is more than just a mechanism for textual substitution, A grouping is more than just a mechanism for textual substitution;
but defines a collection of nodes. Identifiers appearing inside the it also defines a collection of nodes. Identifiers appearing inside
grouping are resolved relative to the scope in which the grouping is the grouping are resolved relative to the scope in which the grouping
defined, not where it is used. Prefix mappings, type names, grouping is defined, not where it is used. Prefix mappings, type names,
names, and extension usage are evaluated in the hierarchy where the grouping names, and extension usage are evaluated in the hierarchy
"grouping" statement appears. For extensions, this means that where the "grouping" statement appears. For extensions, this means
extensions defined as direct children to a "grouping" statement are that extensions defined as direct children to a "grouping" statement
applied to the grouping itself. are applied to the grouping itself.
Note that if a grouping defines an "action" or a "notification" node Note that if a grouping defines an action or a notification node in
in its hierarchy, then it cannot be used in all contexts. For its hierarchy, then it cannot be used in all contexts. For example,
example, it cannot be used in an rpc definition. See Section 7.15 it cannot be used in an rpc definition. See Sections 7.15 and 7.16.
and Section 7.16.
7.12.1. The grouping's Substatements 7.12.1. The grouping's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| action | 7.15 | 0..n | | action | 7.15 | 0..n |
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
skipping to change at page 100, line 40 skipping to change at page 106, line 5
grouping endpoint { grouping endpoint {
description "A reusable endpoint group."; description "A reusable endpoint group.";
leaf ip { leaf ip {
type inet:ip-address; type inet:ip-address;
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
} }
} }
7.13. The uses Statement 7.13. The "uses" Statement
The "uses" statement is used to reference a "grouping" definition. The "uses" statement is used to reference a "grouping" definition.
It takes one argument, which is the name of the grouping. It takes one argument, which is the name of the grouping.
The effect of a "uses" reference to a grouping is that the nodes 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 defined by the grouping are copied into the current schema tree and
then updated according to the "refine" and "augment" statements. are then updated according to the "refine" and "augment" statements.
The identifiers defined in the grouping are not bound to a namespace The identifiers defined in the grouping are not bound to a namespace
until the contents of the grouping are added to the schema tree via a until the contents of the grouping are added to the schema tree via a
"uses" statement that does not appear inside a "grouping" statement, "uses" statement that does not appear inside a "grouping" statement,
at which point they are bound to the namespace of the current module. at which point they are bound to the namespace of the current module.
7.13.1. The uses's Substatements 7.13.1. The uses's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| augment | 7.17 | 0..n | | augment | 7.17 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| refine | 7.13.2 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| refine | 7.13.2 | 0..n |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.13.2. The refine Statement 7.13.2. The "refine" Statement
Some of the properties of each node in the grouping can be refined Some of the properties of each node in the grouping can be refined
with the "refine" statement. The argument is a string that with the "refine" statement. The argument is a string that
identifies a node in the grouping. This node is called the refine's 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 a target target node. If a node in the grouping is not present as a target
node of a "refine" statement, it is not refined, and thus used node of a "refine" statement, it is not refined and thus is used
exactly as it was defined in the grouping. exactly as it was defined in the grouping.
The argument string is a descendant schema node identifier (see The argument string is a descendant schema node identifier (see
Section 6.5). Section 6.5).
The following refinements can be done: The following refinements can be done:
o A leaf or choice node may get a default value, or a new default o A leaf or choice node may get a default value, or a new default
value if it already had one. value if it already had one.
skipping to change at page 102, line 47 skipping to change at page 108, line 13
} }
A corresponding XML instance example: A corresponding XML instance example:
<http-server> <http-server>
<name>extern-web</name> <name>extern-web</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>80</port> <port>80</port>
</http-server> </http-server>
If port 80 should be the default for the HTTP server, default can be If port 80 should be the default for the HTTP server, a default can
added: be added:
container http-server { container http-server {
leaf name { leaf name {
type string; type string;
} }
uses sys:endpoint { uses sys:endpoint {
refine port { refine port {
default 80; default 80;
} }
} }
} }
If we want to define a list of servers, and each server has the ip If we want to define a list of servers and each server has "ip" and
and port as keys, we can do: "port" as keys, we can do:
list server { list server {
key "ip port"; key "ip port";
leaf name { leaf name {
type string; type string;
} }
uses sys:endpoint; uses sys:endpoint;
} }
The following is an error: The following is an error:
container http-server { container http-server {
uses sys:endpoint; uses sys:endpoint;
leaf ip { // illegal - same identifier "ip" used twice leaf ip { // illegal - same identifier "ip" used twice
type string; type string;
} }
} }
7.14. The rpc Statement 7.14. The "rpc" Statement
The "rpc" statement is used to define an RPC operation. It takes one The "rpc" statement is used to define an RPC operation. It takes one
argument, which is an identifier, followed by a block of argument, which is an identifier, followed by a block of
substatements that holds detailed rpc information. This argument is substatements that holds detailed rpc information. This argument is
the name of the RPC. the name of the RPC.
The "rpc" statement defines an rpc node in the schema tree. Under The "rpc" statement defines an rpc node in the schema tree. Under
the rpc node, a schema node with the name "input", and a schema node the rpc node, a schema node with the name "input" and a schema node
with the name "output" are also defined. The nodes "input" and with the name "output" are also defined. The nodes "input" and
"output" are defined in the module's namespace. "output" are defined in the module's namespace.
7.14.1. The rpc's Substatements 7.14.1. The rpc's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| input | 7.14.2 | 0..1 | | input | 7.14.2 | 0..1 |
| output | 7.14.3 | 0..1 | | output | 7.14.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
skipping to change at page 104, line 17 skipping to change at page 109, line 25
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| input | 7.14.2 | 0..1 | | input | 7.14.2 | 0..1 |
| output | 7.14.3 | 0..1 | | output | 7.14.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.2. The input Statement 7.14.2. The "input" Statement
The "input" statement, which is optional, is used to define input The "input" statement, which is optional, is used to define input
parameters to the operation. It does not take an argument. The parameters to the operation. It does not take an argument. The
substatements to "input" define nodes under the operation's input substatements to "input" define nodes under the operation's input
node. node.
If a leaf in the input tree has a "mandatory" statement with the If a leaf in the input tree has a "mandatory" statement with the
value "true", the leaf MUST be present in an RPC invocation. value "true", the leaf MUST be present in an RPC invocation.
If a leaf in the input tree has a default value, the server MUST use If a leaf in the input tree has a default value, the server MUST use
this value in the same cases as described in Section 7.6.1. In these this value in the same cases as those described in Section 7.6.1. In
cases, the server MUST operationally behave as if the leaf was these cases, the server MUST operationally behave as if the leaf was
present in the RPC invocation with the default value as its value. present in the RPC invocation with the default value as its value.
If a leaf-list in the input tree has one or more default values, the If a leaf-list in the input tree has one or more default values, the
server MUST use these values in the same cases as described in server MUST use these values in the same cases as those described in
Section 7.7.2. In these cases, the server MUST operationally behave Section 7.7.2. In these cases, the server MUST operationally behave
as if the leaf-list was present in the RPC invocation with the as if the leaf-list was present in the RPC invocation with the
default values as its values. default values as its values.
Since the input tree is not part of any datastore, all "config" Since the input tree is not part of any datastore, all "config"
statements for nodes in the input tree are ignored. statements for nodes in the input tree are ignored.
If any node has a "when" statement that would evaluate to "false", If any node has a "when" statement that would evaluate to "false",
then this node MUST NOT be present in the input tree. then this node MUST NOT be present in the input tree.
skipping to change at page 105, line 20 skipping to change at page 110, line 23
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.3. The output Statement 7.14.3. The "output" Statement
The "output" statement, which is optional, is used to define output The "output" statement, which is optional, is used to define output
parameters to the RPC operation. It does not take an argument. The parameters to the RPC operation. It does not take an argument. The
substatements to "output" define nodes under the operation's output substatements to "output" define nodes under the operation's output
node. node.
If a leaf in the output tree has a "mandatory" statement with the If a leaf in the output tree has a "mandatory" statement with the
value "true", the leaf MUST be present in an RPC reply. value "true", the leaf MUST be present in an RPC reply.
If a leaf in the output tree has a default value, the client MUST use If a leaf in the output tree has a default value, the client MUST use
this value in the same cases as described in Section 7.6.1. In these this value in the same cases as those described in Section 7.6.1. In
cases, the client MUST operationally behave as if the leaf was these cases, the client MUST operationally behave as if the leaf was
present in the RPC reply with the default value as its value. present in the RPC reply with the default value as its value.
If a leaf-list in the output tree has one or more default values, the If a leaf-list in the output tree has one or more default values, the
client MUST use these values in the same cases as described in client MUST use these values in the same cases as those described in
Section 7.7.2. In these cases, the client MUST operationally behave Section 7.7.2. In these cases, the client MUST operationally behave
as if the leaf-list was present in the RPC reply with the default as if the leaf-list was present in the RPC reply with the default
values as its values. values as its values.
Since the output tree is not part of any datastore, all "config" Since the output tree is not part of any datastore, all "config"
statements for nodes in the output tree are ignored. statements for nodes in the output tree are ignored.
If any node has a "when" statement that would evaluate to "false", If any node has a "when" statement that would evaluate to "false",
then this node MUST NOT be present in the output tree. then this node MUST NOT be present in the output tree.
skipping to change at page 106, line 31 skipping to change at page 111, line 34
An rpc node is encoded as a child XML element to the <rpc> element, An rpc node is encoded as a child XML element to the <rpc> element,
as designated by the substitution group "rpcOperation" in [RFC6241]. as designated by the substitution group "rpcOperation" in [RFC6241].
The element's local name is the rpc's identifier, and its namespace The element's local name is the rpc's identifier, and its namespace
is the module's XML namespace (see Section 7.1.3). is the module's XML namespace (see Section 7.1.3).
Input parameters are encoded as child XML elements to the rpc node's 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" XML element, in the same order as they are defined within the "input"
statement. statement.
If the RPC operation invocation succeeded, and no output parameters If the RPC operation invocation succeeded and no output parameters
are returned, the <rpc-reply> contains a single <ok/> element defined are returned, the <rpc-reply> contains a single <ok/> element defined
in [RFC6241]. If output parameters are returned, they are encoded as in [RFC6241]. If output parameters are returned, they are encoded as
child elements to the <rpc-reply> element defined in [RFC6241], in child elements to the <rpc-reply> element defined in [RFC6241], in
the same order as they are defined within the "output" statement. the same order as they are defined within the "output" statement.
7.14.5. Usage Example 7.14.5. Usage Example
The following example defines an RPC operation: The following example defines an RPC operation:
module example-rock { module example-rock {
skipping to change at page 107, line 19 skipping to change at page 112, line 23
rpc rock-the-house { rpc rock-the-house {
input { input {
leaf zip-code { leaf zip-code {
type string; type string;
} }
} }
} }
} }
A corresponding XML instance example of the complete rpc and rpc- A corresponding XML instance example of the complete rpc and
reply: rpc-reply:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rock-the-house xmlns="urn:example:rock"> <rock-the-house xmlns="urn:example:rock">
<zip-code>27606-0100</zip-code> <zip-code>27606-0100</zip-code>
</rock-the-house> </rock-the-house>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.15. The action Statement 7.15. The "action" Statement
The "action" statement is used to define an operation connected to a The "action" statement is used to define an operation connected to a
specific container or list data node. It takes one argument, which specific container or list data node. It takes one argument, which
is an identifier, followed by a block of substatements that holds is an identifier, followed by a block of substatements that holds
detailed action information. The argument is the name of the action. detailed action information. The argument is the name of the action.
The "action" statement defines an action node in the schema tree. The "action" statement defines an action node in the schema tree.
Under the action node, a schema node with the name "input", and a Under the action node, a schema node with the name "input" and a
schema node with the name "output" are also defined. The nodes schema node with the name "output" are also defined. The nodes
"input" and "output" are defined in the module's namespace. "input" and "output" are defined in the module's namespace.
An action MUST NOT be defined within an rpc, another action or a An action MUST NOT be defined within an rpc, another action, or a
notification, i.e., an action node MUST NOT have an rpc, action, or a notification, i.e., an action node MUST NOT have an rpc, action, or a
notification node as one of its ancestors in the schema tree. For notification node as one of its ancestors in the schema tree. For
example, this means that it is an error if a grouping that contains example, this means that it is an error if a grouping that contains
an action somewhere in its node hierarchy is used in a notification an action somewhere in its node hierarchy is used in a notification
definition. definition.
An action MUST NOT have any ancestor node that is a list node without An action MUST NOT have any ancestor node that is a list node without
a "key" statement. a "key" statement.
Since an action cannot be defined at the top-level of a module or in Since an action cannot be defined at the top level of a module or in
a case statement, it is an error if a grouping that contains an a "case" statement, it is an error if a grouping that contains an
action at the top of its node hierarchy is used at the top-level of a action at the top of its node hierarchy is used at the top level of a
module or in a case definition. module or in a case definition.
The difference between an action and an rpc is that an action is tied The difference between an action and an rpc is that an action is tied
to a node in the datastore, whereas an rpc is not. When an action is to a node in the datastore, whereas an rpc is not. When an action is
invoked, the node in the datastore is specified along with the name invoked, the node in the datastore is specified along with the name
of the action and the input parameters. of the action and the input parameters.
7.15.1. The action's Substatements 7.15.1. The action's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 108, line 41 skipping to change at page 114, line 28
+--------------+---------+-------------+ +--------------+---------+-------------+
7.15.2. NETCONF XML Encoding Rules 7.15.2. NETCONF XML Encoding Rules
When an action is invoked, an element with the local name "action" in When an action is invoked, an element with the local name "action" in
the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is
encoded as a child XML element to the <rpc> element defined in encoded as a child XML element to the <rpc> element defined in
[RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241], as designated by the substitution group "rpcOperation" in
[RFC6241]. [RFC6241].
The "action" element contains an hierarchy of nodes that identifies The <action> element contains a hierarchy of nodes that identifies
the node in the datastore. It MUST contain all containers and list the node in the datastore. It MUST contain all containers and list
nodes in the direct path from the top level down to the list or nodes in the direct path from the top level down to the list or
container containing the action. For lists, all key leafs MUST also container containing the action. For lists, all key leafs MUST also
be included. The innermost container or list contains an XML element be included. The innermost container or list contains an XML element
that carries the name of the defined action. Within this element the that carries the name of the defined action. Within this element,
input parameters are encoded as child XML elements, in the same order the input parameters are encoded as child XML elements, in the same
as they are defined within the "input" statement. order as they are defined within the "input" statement.
Only one action can be invoked in one <rpc>. If more than one action Only one action can be invoked in one <rpc>. If more than one action
is present in the <rpc>, the server MUST reply with an "bad-element" is present in the <rpc>, the server MUST reply with a "bad-element"
error-tag in the <rpc-error>. <error-tag> in the <rpc-error>.
If the action operation invocation succeeded, and no output If the action operation invocation succeeded and no output parameters
parameters are returned, the <rpc-reply> contains a single <ok/> are returned, the <rpc-reply> contains a single <ok/> element defined
element defined in [RFC6241]. If output parameters are returned, in [RFC6241]. If output parameters are returned, they are encoded as
they are encoded as child elements to the <rpc-reply> element defined child elements to the <rpc-reply> element defined in [RFC6241], in
in [RFC6241], in the same order as they are defined within the the same order as they are defined within the "output" statement.
"output" statement.
7.15.3. Usage Example 7.15.3. Usage Example
The following example defines an action to reset one server at a The following example defines an action to reset one server at a
server farm: server farm:
module example-server-farm { module example-server-farm {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:server-farm"; namespace "urn:example:server-farm";
prefix "sfarm"; prefix "sfarm";
skipping to change at page 109, line 48 skipping to change at page 116, line 5
output { output {
leaf reset-finished-at { leaf reset-finished-at {
type yang:date-and-time; type yang:date-and-time;
mandatory true; mandatory true;
} }
} }
} }
} }
} }
A corresponding XML instance example of the complete rpc and rpc- A corresponding XML instance example of the complete rpc and
reply: rpc-reply:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1"> <action xmlns="urn:ietf:params:xml:ns:yang:1">
<server xmlns="urn:example:server-farm"> <server xmlns="urn:example:server-farm">
<name>apache-1</name> <name>apache-1</name>
<reset> <reset>
<reset-at>2014-07-29T13:42:00Z</reset-at> <reset-at>2014-07-29T13:42:00Z</reset-at>
</reset> </reset>
</server> </server>
</action> </action>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<reset-finished-at xmlns="urn:example:server-farm"> <reset-finished-at xmlns="urn:example:server-farm">
2014-07-29T13:42:12Z 2014-07-29T13:42:12Z
</reset-finished-at> </reset-finished-at>
</rpc-reply> </rpc-reply>
7.16. The notification Statement 7.16. The "notification" Statement
The "notification" statement is used to define a notification. It The "notification" statement is used to define a notification. It
takes one argument, which is an identifier, followed by a block of takes one argument, which is an identifier, followed by a block of
substatements that holds detailed notification information. The substatements that holds detailed notification information. The
"notification" statement defines a notification node in the schema "notification" statement defines a notification node in the schema
tree. tree.
A notification can be defined at the top-level of a module, or A notification can be defined at the top level of a module, or
connected to a specific container or list data node in the schema connected to a specific container or list data node in the schema
tree. tree.
A notification MUST NOT be defined within an rpc, action or another A notification MUST NOT be defined within an rpc, action, or another
notification, i.e., a notification node MUST NOT have an rpc, action, notification, i.e., a notification node MUST NOT have an rpc, action,
or a notification node as one of its ancestors in the schema tree. or a notification node as one of its ancestors in the schema tree.
For example, this means that it is an error if a grouping that For example, this means that it is an error if a grouping that
contains an notification somewhere in its node hierarchy is used in contains a notification somewhere in its node hierarchy is used in an
an rpc definition. rpc definition.
A notification MUST NOT have any ancestor node that is a list node A notification MUST NOT have any ancestor node that is a list node
without a "key" statement. without a "key" statement.
Since a notification cannot be defined in a case statement, it is an Since a notification cannot be defined in a "case" statement, it is
error if a grouping that contains a notification at the top of its an error if a grouping that contains a notification at the top of its
node hierarchy is used in a case definition. node hierarchy is used in a case definition.
If a leaf in the notification tree has a "mandatory" statement with If a leaf in the notification tree has a "mandatory" statement with
the value "true", the leaf MUST be present in a notification the value "true", the leaf MUST be present in a notification
instance. instance.
If a leaf in the notification tree has a default value, the client If a leaf in the notification tree has a default value, the client
MUST use this value in the same cases as described in Section 7.6.1. MUST use this value in the same cases as those described in
In these cases, the client MUST operationally behave as if the leaf Section 7.6.1. In these cases, the client MUST operationally behave
was present in the notification instance with the default value as as if the leaf was present in the notification instance with the
its value. default value as its value.
If a leaf-list in the notification tree has one or more default If a leaf-list in the notification tree has one or more default
values, the client MUST use these values in the same cases as values, the client MUST use these values in the same cases as those
described in Section 7.7.2. In these cases, the client MUST described in Section 7.7.2. In these cases, the client MUST
operationally behave as if the leaf-list was present in the operationally behave as if the leaf-list was present in the
notification instance with the default values as its values. notification instance with the default values as its values.
Since the notification tree is not part of any datastore, all Since the notification tree is not part of any datastore, all
"config" statements for nodes in the notification tree are ignored. "config" statements for nodes in the notification tree are ignored.
7.16.1. The notification's Substatements 7.16.1. The notification's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 111, line 44 skipping to change at page 117, line 48
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.16.2. NETCONF XML Encoding Rules 7.16.2. NETCONF XML Encoding Rules
A notification node that is defined on the top-level of a module is A notification node that is defined on the top level of a module is
encoded as a child XML element to the <notification> element defined encoded as a child XML element to the <notification> element defined
in NETCONF Event Notifications [RFC5277]. The element's local name in "NETCONF Event Notifications" [RFC5277]. The element's local name
is the notification's identifier, and its namespace is the module's is the notification's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). XML namespace (see Section 7.1.3).
When a notification node is defined as a child to a data node, the When a notification node is defined as a child to a data node, the
<notification> element defined in NETCONF Event Notifications <notification> element defined in [RFC5277] contains a hierarchy of
[RFC5277] contains an hierarchy of nodes that identifies the node in nodes that identifies the node in the datastore. It MUST contain all
the datastore. It MUST contain all containers and list nodes from containers and list nodes from the top level down to the list or
the top level down to the list or container containing the container containing the notification. For lists, all key leafs MUST
notification. For lists, all key leafs MUST also be included. The also be included. The innermost container or list contains an XML
innermost container or list contains an XML element that carries the element that carries the name of the defined notification.
name of the defined notification.
The notification's child nodes are encoded as subelements to the The notification's child nodes are encoded as subelements to the
notification node's XML element, in any order. notification node's XML element, in any order.
7.16.3. Usage Example 7.16.3. Usage Example
The following example defines a notification at the top-level of a The following example defines a notification at the top level of a
module: module:
module example-event { module example-event {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:event"; namespace "urn:example:event";
prefix "ev"; prefix "ev";
notification event { notification event {
leaf event-class { leaf event-class {
type string; type string;
skipping to change at page 113, line 40 skipping to change at page 119, line 42
<interfaces xmlns="urn:example:interface-module"> <interfaces xmlns="urn:example:interface-module">
<interface> <interface>
<name>eth1</name> <name>eth1</name>
<interface-enabled> <interface-enabled>
<by-user>fred</by-user> <by-user>fred</by-user>
</interface-enabled> </interface-enabled>
</interface> </interface>
</interfaces> </interfaces>
</notification> </notification>
7.17. The augment Statement 7.17. The "augment" Statement
The "augment" statement allows a module or submodule to add to a The "augment" statement allows a module or submodule to add to a
schema tree defined in an external module, or in the current module schema tree defined in an external module, or in the current module
and its submodules, and to add to the nodes from a grouping in a and its submodules, and to add to the nodes from a grouping in a
"uses" statement. The argument is a string that identifies a node in "uses" statement. The argument is a string that identifies a node in
the schema tree. This node is called the augment's target node. The the schema tree. This node is called the augment's target node. The
target node MUST be either a container, list, choice, case, input, target node MUST be either a container, list, choice, case, input,
output, or notification node. It is augmented with the nodes defined output, or notification node. It is augmented with the nodes defined
in the substatements that follow the "augment" statement. in the substatements that follow the "augment" statement.
skipping to change at page 114, line 18 skipping to change at page 120, line 21
"descendant-schema-nodeid" in Section 14) MUST be used. "descendant-schema-nodeid" in Section 14) MUST be used.
If the target node is a container, list, case, input, output, or If the target node is a container, list, case, input, output, or
notification node, the "container", "leaf", "list", "leaf-list", notification node, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used within the "augment" "uses", and "choice" statements can be used within the "augment"
statement. statement.
If the target node is a container or list node, the "action" and If the target node is a container or list node, the "action" and
"notification" statements can be used within the "augment" statement. "notification" statements can be used within the "augment" statement.
If the target node is a choice node, the "case" statement, or a case If the target node is a choice node, the "case" statement or a
shorthand statement (see Section 7.9.2) can be used within the shorthand "case" statement (see Section 7.9.2) can be used within the
"augment" statement. "augment" statement.
The "augment" statement MUST NOT add multiple nodes with the same The "augment" statement MUST NOT add multiple nodes with the same
name from the same module to the target node. name from the same module to the target node.
If the augmentation adds mandatory nodes (see Section 3) that If the augmentation adds mandatory nodes (see Section 3) that
represent configuration to a target node in another module, the represent configuration to a target node in another module, the
augmentation MUST be conditional with a "when" statement. Care must augmentation MUST be made conditional with a "when" statement. Care
be taken when defining the "when" expression, so that clients that do must be taken when defining the "when" expression so that clients
not know about the augmenting module do not break. that do not know about the augmenting module do not break.
In the following example, it is OK to augment the "interface" entry In the following example, it is OK to augment the "interface" entry
with "mandatory-leaf" because the augmentation depends on support for with "mandatory-leaf" because the augmentation depends on support for
"some-new-iftype". The old client does not know about this type so "some-new-iftype". The old client does not know about this type, so
it would never select this type, and therefore not be adding a it would never select this type and would therefore not be adding a
mandatory data node. mandatory data node.
module example-augment { module example-augment {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:augment"; namespace "urn:example:augment";
prefix mymod; prefix mymod;
import ietf-interfaces { import ietf-interfaces {
prefix if; prefix if;
} }
skipping to change at page 118, line 5 skipping to change at page 124, line 5
</ex:system> </ex:system>
or or
<ex:system> <ex:system>
<ex:protocol> <ex:protocol>
<other:smtp/> <other:smtp/>
</ex:protocol> </ex:protocol>
</ex:system> </ex:system>
7.18. The identity Statement 7.18. The "identity" Statement
The "identity" statement is used to define a new globally unique, The "identity" statement is used to define a new globally unique,
abstract, and untyped identity. The identity's only purpose is to abstract, and untyped identity. The identity's only purpose is to
denote its name, semantics, and existence. An identity can either be denote its name, semantics, and existence. An identity can be either
defined from scratch or derived from one or more base identities. defined from scratch or derived from one or more base identities.
The identity's argument is an identifier that is the name of the The identity's argument is an identifier that is the name of the
identity. It is followed by a block of substatements that holds identity. It is followed by a block of substatements that holds
detailed identity information. detailed identity information.
The built-in datatype "identityref" (see Section 9.10) can be used to The built-in datatype "identityref" (see Section 9.10) can be used to
reference identities within a data model. reference identities within a data model.
7.18.1. The identity's Substatements 7.18.1. The identity's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| base | 7.18.2 | 0..n | | base | 7.18.2 | 0..n |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.18.2. The base Statement 7.18.2. The "base" Statement
The "base" statement, which is optional, takes as an argument a The "base" statement, which is optional, takes as an argument a
string that is the name of an existing identity, from which the new string that is the name of an existing identity, from which the new
identity is derived. If no "base" statement is present, the identity identity is derived. If no "base" statement is present, the identity
is defined from scratch. If multiple "base" statements are present, is defined from scratch. If multiple "base" statements are present,
the identity is derived from all of them. the identity is derived from all of them.
If a prefix is present on the base name, it refers to an identity If a prefix is present on the base name, it refers to an identity
defined in the module that was imported with that prefix, or the defined in the module that was imported with that prefix, or the
local module if the prefix matches the local module's prefix. local module if the prefix matches the local module's prefix.
skipping to change at page 120, line 40 skipping to change at page 125, line 51
namespace "urn:example:des"; namespace "urn:example:des";
prefix "des"; prefix "des";
import "example-crypto-base" { import "example-crypto-base" {
prefix "crypto"; prefix "crypto";
} }
identity des { identity des {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
base "crypto:symmetric-key"; base "crypto:symmetric-key";
description "DES crypto algorithm"; description "DES crypto algorithm.";
} }
identity des3 { identity des3 {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
base "crypto:symmetric-key"; base "crypto:symmetric-key";
description "Triple DES crypto algorithm"; description "Triple DES crypto algorithm.";
} }
} }
7.19. The extension Statement 7.19. The "extension" Statement
The "extension" statement allows the definition of new statements The "extension" statement allows the definition of new statements
within the YANG language. This new statement definition can be within the YANG language. This new statement definition can be
imported and used by other modules. imported and used by other modules.
The "extension" statement's argument is an identifier that is the new The "extension" statement's argument is an identifier that is the new
keyword for the extension and must be followed by a block of keyword for the extension and must be followed by a block of
substatements that holds detailed extension information. The purpose substatements that holds detailed extension information. The purpose
of the "extension" statement is to define a keyword, so that it can of the "extension" statement is to define a keyword so that it can be
be imported and used by other modules. imported and used by other modules.
The extension can be used like a normal YANG statement, with the The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the statement name followed by an argument if one is defined by the
"extension" statement, and an optional block of substatements. The "extension" statement, and an optional block of substatements. The
statement's name is created by combining the prefix of the module in statement's name is created by combining the prefix of the module in
which the extension was defined, a colon (":"), and the extension's which the extension was defined, a colon (":"), and the extension's
keyword, with no interleaving whitespace. The substatements of an keyword, with no interleaving whitespace. The substatements of an
extension are defined by the "extension" statement, using some extension are defined by the "extension" statement, using some
mechanism outside the scope of this specification. Syntactically, mechanism outside the scope of this specification. Syntactically,
the substatements MUST be YANG statements, or also extensions defined the substatements MUST be YANG statements, including extensions
using "extension" statements. YANG statements in extensions MUST defined using "extension" statements. YANG statements in extensions
follow the syntactical rules in Section 14. MUST follow the syntactical rules in Section 14.
An extension can allow refinement (see Section 7.13.2) and deviations An extension can allow refinement (see Section 7.13.2) and deviations
(Section 7.20.3.2), but the mechanism for how this is defined is (Section 7.20.3.2), but the mechanism for how this is defined is
outside the scope of this specification. outside the scope of this specification.
7.19.1. The extension's Substatements 7.19.1. The extension's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| argument | 7.19.2 | 0..1 | | argument | 7.19.2 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.19.2. The argument Statement 7.19.2. The "argument" Statement
The "argument" statement, which is optional, takes as an argument a The "argument" statement, which is optional, takes as an argument a
string that is the name of the argument to the keyword. If no string that is the name of the argument to the keyword. If no
argument statement is present, the keyword expects no argument when "argument" statement is present, the keyword expects no argument when
it is used. it is used.
The argument's name is used in the YIN mapping, where it is used as 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 an XML attribute or element name, depending on the argument's
"yin-element" statement. "yin-element" statement.
7.19.2.1. The argument's Substatements 7.19.2.1. The argument's Substatement
+--------------+----------+-------------+ +--------------+----------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| yin-element | 7.19.2.2 | 0..1 | | yin-element | 7.19.2.2 | 0..1 |
+--------------+----------+-------------+ +--------------+----------+-------------+
7.19.2.2. The yin-element Statement 7.19.2.2. The "yin-element" Statement
The "yin-element" statement, which is optional, takes as an argument The "yin-element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the the string "true" or "false". This statement indicates whether the
argument is mapped to an XML element in YIN or to an XML attribute argument is mapped to an XML element in YIN or to an XML attribute
(see Section 13). (see Section 13).
If no "yin-element" statement is present, it defaults to "false". If no "yin-element" statement is present, it defaults to "false".
7.19.3. Usage Example 7.19.3. Usage Example
To define an extension: To define an extension:
module example-extensions { module example-extensions {
yang-version 1.1; yang-version 1.1;
... ...
extension c-define { extension c-define {
description description
"Takes as argument a name string. "Takes as an argument a name string.
Makes the code generator use the given name in the Makes the code generator use the given name
#define."; in the #define.";
argument "name"; argument "name";
} }
} }
To use the extension: To use the extension:
module example-interfaces { module example-interfaces {
yang-version 1.1; yang-version 1.1;
... ...
skipping to change at page 123, line 25 skipping to change at page 128, line 27
... ...
myext:c-define "MY_INTERFACES"; myext:c-define "MY_INTERFACES";
} }
} }
7.20. Conformance-Related Statements 7.20. Conformance-Related Statements
This section defines statements related to conformance, as described This section defines statements related to conformance, as described
in Section 5.6. in Section 5.6.
7.20.1. The feature Statement 7.20.1. The "feature" Statement
The "feature" statement is used to define a mechanism by which The "feature" statement is used to define a mechanism by which
portions of the schema are marked as conditional. A feature name is portions of the schema are marked as conditional. A feature name is
defined that can later be referenced using the "if-feature" statement defined that can later be referenced using the "if-feature" statement
(see Section 7.20.2). Schema nodes tagged with an "if-feature" (see Section 7.20.2). Schema nodes tagged with an "if-feature"
statement are ignored by the server unless the server supports the statement are ignored by the server unless the server supports the
given feature expression. This allows portions of the YANG module to given feature expression. This allows portions of the YANG module to
be conditional based on conditions in the server. The model can be conditional based on conditions in the server. The model can
represent the abilities of the server within the model, giving a represent the abilities of the server within the model, giving a
richer model that allows for differing server abilities and roles. richer model that allows for differing server abilities and roles.
The argument to the "feature" statement is the name of the new The argument to the "feature" statement is the name of the new
feature, and follows the rules for identifiers in Section 6.2. This 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 name is used by the "if-feature" statement to tie the schema nodes to
the feature. the feature.
In this example, a feature called "local-storage" represents the In this example, a feature called "local-storage" represents the
ability for a server to store syslog messages on local storage of ability for a server to store syslog messages on local storage of
some sort. This feature is used to make the "local-storage-limit" some sort. This feature is used to make the "local-storage-limit"
leaf conditional on the presence of some sort of local storage. If leaf conditional on the presence of some sort of local storage. If
the server does not report that it supports this feature, the the server does not report that it supports this feature, the
"local-storage-limit" node is not supported. "local-storage-limit" node is not supported.
module example-syslog { module example-syslog {
yang-version 1.1; yang-version 1.1;
... ...
feature local-storage { feature local-storage {
description description
"This feature means the server supports local "This feature means that the server supports local
storage (memory, flash or disk) that can be used to storage (memory, flash, or disk) that can be used to
store syslog messages."; store syslog messages.";
} }
container syslog { container syslog {
leaf local-storage-limit { leaf local-storage-limit {
if-feature local-storage; if-feature local-storage;
type uint64; type uint64;
units "kilobyte"; units "kilobyte";
config false; config false;
description description
skipping to change at page 124, line 38 skipping to change at page 129, line 45
The "if-feature" statement can be used in many places within the YANG The "if-feature" statement can be used in many places within the YANG
syntax. Definitions tagged with "if-feature" are ignored when the syntax. Definitions tagged with "if-feature" are ignored when the
server does not support that feature. server does not support that feature.
A feature MUST NOT reference itself, neither directly nor indirectly A feature MUST NOT reference itself, neither directly nor indirectly
through a chain of other features. through a chain of other features.
In order for a server to support a feature that is dependent on any In order for a server to support a feature that is dependent on any
other features (i.e., the feature has one or more "if-feature" other features (i.e., the feature has one or more "if-feature"
substatements), the server MUST also support all the dependant substatements), the server MUST also support all the dependent
features. features.
7.20.1.1. The feature's Substatements 7.20.1.1. The feature's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| status | 7.21.2 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.20.2. The if-feature Statement 7.20.2. The "if-feature" Statement
The "if-feature" statement makes its parent statement conditional. The "if-feature" statement makes its parent statement conditional.
The argument is a boolean expression over feature names. In this The argument is a boolean expression over feature names. In this
expression, a feature name evaluates to "true" if and only if the expression, a feature name evaluates to "true" if and only if the
feature is supported by the server. The parent statement is feature is supported by the server. The parent statement is
implemented by servers where the boolean expression evaluates to implemented by servers where the boolean expression evaluates to
"true". "true".
The if-feature boolean expression syntax is formally defined by the The if-feature boolean expression syntax is formally defined by the
rule "if-feature-expr" in Section 14. Parenthesis are used to group rule "if-feature-expr" in Section 14. Parentheses are used to group
expressions. When the expression is evaluated, the order of expressions. When the expression is evaluated, the order of
precedence is (highest precedence first): grouping (parenthesis), precedence is (highest precedence first): grouping (parentheses),
"not", "and", "or". "not", "and", "or".
If a prefix is present on a feature name in the boolean expression, If a prefix is present on a feature name in the boolean expression,
the prefixed name refers to a feature defined in the module that was the prefixed name refers to a feature defined in the module that was
imported with that prefix, or the local module if the prefix matches imported with that prefix, or the local module if the prefix matches
the local module's prefix. Otherwise, a feature with the matching the local module's prefix. Otherwise, a feature with the matching
name MUST be defined in the current module or an included submodule. name MUST be defined in the current module or an included submodule.
A leaf that is a list key MUST NOT have any "if-feature" statements. A leaf that is a list key MUST NOT have any "if-feature" statements.
7.20.2.1. Usage Example 7.20.2.1. Usage Example
In this example, the container "target" is implemented if either of In this example, the container "target" is implemented if either the
the features "outbound-tls" or "outbound-ssh" are supported by the "outbound-tls" or "outbound-ssh" feature is supported by the server.
server.
container target { container target {
if-feature "outbound-tls or outbound-ssh"; if-feature "outbound-tls or outbound-ssh";
... ...
} }
The following examples are equivalent: The following examples are equivalent:
if-feature "not foo or bar and baz"; if-feature "not foo or bar and baz";
if-feature "(not foo) or (bar and baz)"; if-feature "(not foo) or (bar and baz)";
7.20.3. The deviation Statement 7.20.3. The "deviation" Statement
The "deviation" statement defines a hierarchy of a module that the The "deviation" statement defines a hierarchy of a module that the
server does not implement faithfully. The argument is a string that server does not implement faithfully. The argument is a string that
identifies the node in the schema tree where a deviation from the identifies the node in the schema tree where a deviation from the
module occurs. This node is called the deviation's target node. The module occurs. This node is called the deviation's target node. The
contents of the "deviation" statement give details about the contents of the "deviation" statement give details about the
deviation. deviation.
The argument string is an absolute schema node identifier (see The argument string is an absolute schema node identifier (see
Section 6.5). Section 6.5).
skipping to change at page 126, line 21 skipping to change at page 131, line 46
implementations vary from the standards. implementations vary from the standards.
Server deviations are strongly discouraged and MUST only be used as a Server deviations are strongly discouraged and MUST only be used as a
last resort. Telling the application how a server fails to follow a last resort. Telling the application how a server fails to follow a
standard is no substitute for implementing the standard correctly. A standard is no substitute for implementing the standard correctly. A
server that deviates from a module is not fully compliant with the server that deviates from a module is not fully compliant with the
module. module.
However, in some cases, a particular device may not have the hardware However, in some cases, a particular device may not have the hardware
or software ability to support parts of a standard module. When this or software ability to support parts of a standard module. When this
occurs, the server makes a choice either to treat attempts to occurs, the server makes a choice to either treat attempts to
configure unsupported parts of the module as an error that is configure unsupported parts of the module as an error that is
reported back to the unsuspecting application or ignore those reported back to the unsuspecting application or ignore those
incoming requests. Neither choice is acceptable. incoming requests. Neither choice is acceptable.
Instead, YANG allows servers to document portions of a base module Instead, YANG allows servers to document portions of a base module
that are not supported or supported but with different syntax, by that are not supported, or that are supported but with different
using the "deviation" statement. syntax, by using the "deviation" statement.
After applying all deviations announced by a server, in any order, After applying all deviations announced by a server, in any order,
the resulting data model MUST still be valid. the resulting data model MUST still be valid.
7.20.3.1. The deviation's Substatements 7.20.3.1. The deviation's Substatements
+--------------+----------+-------------+ +--------------+----------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| deviate | 7.20.3.2 | 1..n | | deviate | 7.20.3.2 | 1..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+--------------+----------+-------------+ +--------------+----------+-------------+
7.20.3.2. The deviate Statement 7.20.3.2. The "deviate" Statement
The "deviate" statement defines how the server's implementation of The "deviate" statement defines how the server's implementation of
the target node deviates from its original definition. The argument the target node deviates from its original definition. The argument
is one of the strings "not-supported", "add", "replace", or "delete". is one of the strings "not-supported", "add", "replace", or "delete".
The argument "not-supported" indicates that the target node is not The argument "not-supported" indicates that the target node is not
implemented by this server. implemented by this server.
The argument "add" adds properties to the target node. The The argument "add" adds properties to the target node. The
properties to add are identified by substatements to the "deviate" properties to add are identified by substatements to the "deviate"
skipping to change at page 127, line 21 skipping to change at page 133, line 5
properties to replace are identified by substatements to the properties to replace are identified by substatements to the
"deviate" statement. The properties to replace MUST exist in the "deviate" statement. The properties to replace MUST exist in the
target node. target node.
The argument "delete" deletes properties from the target node. The The argument "delete" deletes properties from the target node. The
properties to delete are identified by substatements to the "delete" properties to delete are identified by substatements to the "delete"
statement. The substatement's keyword MUST match a corresponding statement. The substatement's keyword MUST match a corresponding
keyword in the target node, and the argument's string MUST be equal keyword in the target node, and the argument's string MUST be equal
to the corresponding keyword's argument string in the target node. to the corresponding keyword's argument string in the target node.
+--------------+-------------+-------------+ +--------------+--------------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+-------------+-------------+ +--------------+--------------+-------------+
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| default | 7.6.4 7.7.4 | 0..n | | default | 7.6.4, 7.7.4 | 0..n |
| mandatory | 7.6.5 | 0..1 | | mandatory | 7.6.5 | 0..1 |
| max-elements | 7.7.6 | 0..1 | | max-elements | 7.7.6 | 0..1 |
| min-elements | 7.7.5 | 0..1 | | min-elements | 7.7.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| type | 7.4 | 0..1 | | type | 7.4 | 0..1 |
| unique | 7.8.3 | 0..n | | unique | 7.8.3 | 0..n |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
+--------------+-------------+-------------+ +--------------+--------------+-------------+
The deviate's Substatements The deviate's Substatements
If the target node has a property defined by an extension, this If the target node has a property defined by an extension, this
property can be deviated if the extension allows deviations. See property can be deviated if the extension allows deviations. See
Section 7.19 for details. Section 7.19 for details.
7.20.3.3. Usage Example 7.20.3.3. Usage Example
In this example, the server is informing client applications that it In this example, the server is informing client applications that it
skipping to change at page 128, line 47 skipping to change at page 134, line 29
} }
} }
If the original definition is: If the original definition is:
container system { container system {
must "daytime or time"; must "daytime or time";
... ...
} }
a server might remove this must constraint by doing: a server might remove this "must" constraint by doing:
deviation /base:system { deviation /base:system {
deviate delete { deviate delete {
must "daytime or time"; must "daytime or time";
} }
} }
7.21. Common Statements 7.21. Common Statements
This section defines substatements common to several other This section defines substatements common to several other
statements. statements.
7.21.1. The config Statement 7.21.1. The "config" Statement
The "config" statement takes as an argument the string "true" or The "config" statement takes as an argument the string "true" or
"false". If "config" is "true", the definition represents "false". If "config" is "true", the definition represents
configuration. Data nodes representing configuration are part of configuration. Data nodes representing configuration are part of
configuration datastores. configuration datastores.
If "config" is "false", the definition represents state data. Data If "config" is "false", the definition represents state data. Data
nodes representing state data are not part of configuration nodes representing state data are not part of configuration
datastores. datastores.
If "config" is not specified, the default is the same as the parent If "config" is not specified, the default is the same as the parent
schema node's "config" value. If the parent node is a "case" node, schema node's "config" value. If the parent node is a case node, the
the value is the same as the "case" node's parent "choice" node. value is the same as the case node's parent choice node.
If the top node does not specify a "config" statement, the default is If the top node does not specify a "config" statement, the default is
"true". "true".
If a node has "config" set to "false", no node underneath it can have If a node has "config" set to "false", no node underneath it can have
"config" set to "true". "config" set to "true".
7.21.2. The status Statement 7.21.2. The "status" Statement
The "status" statement takes as an argument one of the strings The "status" statement takes as an argument one of the strings
"current", "deprecated", or "obsolete". "current", "deprecated", or "obsolete".
o "current" means that the definition is current and valid. o "current" means that the definition is current and valid.
o "deprecated" indicates an obsolete definition, but it permits new/ o "deprecated" indicates an obsolete definition, but it permits
continued implementation in order to foster interoperability with new/continued implementation in order to foster interoperability
older/existing implementations. with older/existing implementations.
o "obsolete" means the definition is obsolete and SHOULD NOT be o "obsolete" means that the definition is obsolete and SHOULD NOT be
implemented and/or can be removed from implementations. implemented and/or can be removed from implementations.
If no status is specified, the default is "current". If no status is specified, the default is "current".
If a definition is "current", it MUST NOT reference a "deprecated" or If a definition is "current", it MUST NOT reference a "deprecated" or
"obsolete" definition within the same module. "obsolete" definition within the same module.
If a definition is "deprecated", it MUST NOT reference an "obsolete" If a definition is "deprecated", it MUST NOT reference an "obsolete"
definition within the same module. definition within the same module.
skipping to change at page 130, line 23 skipping to change at page 136, line 5
typedef my-type { typedef my-type {
status deprecated; status deprecated;
type int32; type int32;
} }
leaf my-leaf { leaf my-leaf {
status current; status current;
type my-type; // illegal, since my-type is deprecated type my-type; // illegal, since my-type is deprecated
} }
7.21.3. The description Statement 7.21.3. The "description" Statement
The "description" statement takes as an argument a string that The "description" statement takes as an argument a string that
contains a human-readable textual description of this definition. contains a human-readable textual description of this definition.
The text is provided in a language (or languages) chosen by the The text is provided in a language (or languages) chosen by the
module developer; for the sake of interoperability, it is RECOMMENDED module developer; for the sake of interoperability, it is RECOMMENDED
to choose a language that is widely understood among the community of to choose a language that is widely understood among the community of
network administrators who will use the module. network administrators who will use the module.
7.21.4. The reference Statement 7.21.4. The "reference" Statement
The "reference" statement takes as an argument a string that is a The "reference" statement takes as an argument a string that is a
human-readable cross-reference to an external document, either human-readable cross-reference to an external document -- either
another module that defines related management information, or a another module that defines related management information or a
document that provides additional information relevant to this document that provides additional information relevant to this
definition. definition.
For example, a typedef for a "uri" data type could look like: For example, a typedef for a "uri" data type could look like:
typedef uri { typedef uri {
type string; type string;
reference reference
"RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax";
... ...
} }
7.21.5. The when Statement 7.21.5. The "when" Statement
The "when" statement makes its parent data definition statement The "when" statement makes its parent data definition statement
conditional. The node defined by the parent data definition conditional. The node defined by the parent data definition
statement is only valid when the condition specified by the "when" statement is only valid when the condition specified by the "when"
statement is satisfied. The statement's argument is an XPath statement is satisfied. The statement's argument is an XPath
expression (see Section 6.4), which is used to formally specify this expression (see Section 6.4), which is used to formally specify this
condition. If the XPath expression conceptually evaluates to "true" condition. If the XPath expression conceptually evaluates to "true"
for a particular instance, then the node defined by the parent data for a particular instance, then the node defined by the parent data
definition statement is valid; otherwise, it is not. definition statement is valid; otherwise, it is not.
A leaf that is a list key MUST NOT have a "when" statement. A leaf that is a list key MUST NOT have a "when" statement.
If a leaf key is defined in a grouping that is used in a list, the If a key leaf is defined in a grouping that is used in a list, the
"uses" statement MUST NOT have a "when" statement. "uses" statement MUST NOT have a "when" statement.
See Section 8.3.2 for additional information. See Section 8.3.2 for additional information.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context, in addition to the definition in Section 6.4.1: context, in addition to the definition in Section 6.4.1:
o If the "when" statement is a child of an "augment" statement, then 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 context node is the augment's target node in the data tree, if
the target node is a data node. Otherwise, the context node is the target node is a data node. Otherwise, the context node is
the closest ancestor node to the target node that is also a data the closest ancestor node to the target node that is also a data
node. If no such node exists, the context node is the root node. node. If no such node exists, the context node is the root node.
The accessible tree is tentatively altered during the processing The accessible tree is tentatively altered during the processing
of the XPath expression by removing all instances (if any) of the of the XPath expression by removing all instances (if any) of the
nodes added by the "augment" statement. nodes added by the "augment" statement.
o If the "when" statement is a child of a "uses", "choice", or o If the "when" statement is a child of a "uses", "choice", or
"case" statement, then the context node is the closest ancestor "case" statement, then the context node is the closest ancestor
node to the "uses", "choice", or "case" node that is also a data node to the node with the "when" statement that is also a data
node. If no such node exists, the context node is the root node. node. If no such node exists, the context node is the root node.
The accessible tree is tentatively altered during the processing The accessible tree is tentatively altered during the processing
of the XPath expression by removing all instances (if any) of the of the XPath expression by removing all instances (if any) of the
nodes added by the "uses", "choice", or "case" statement. nodes added by the "uses", "choice", or "case" statement.
o If the "when" statement is a child of any other data definition o If the "when" statement is a child of any other data definition
statement, the accessible tree is tentatively altered during the statement, the accessible tree is tentatively altered during the
processing of the XPath expression by replacing all instances of processing of the XPath expression by replacing all instances of
the data node for which the "when" statement is defined with a the data node for which the "when" statement is defined with a
single dummy node with the same name, but with no value and no single dummy node with the same name, but with no value and no
skipping to change at page 133, line 27 skipping to change at page 139, line 18
o The "min-elements" and "max-elements" constraints are enforced for o The "min-elements" and "max-elements" constraints are enforced for
lists and leaf-lists, unless the node or any of its ancestors has lists and leaf-lists, unless the node or any of its ancestors has
a "when" condition or "if-feature" expression that evaluates to a "when" condition or "if-feature" expression that evaluates to
"false". "false".
The running configuration datastore MUST always be valid. The running configuration datastore MUST always be valid.
8.2. Configuration Data Modifications 8.2. Configuration Data Modifications
o If a request creates configuration data nodes under a "choice", o If a request creates configuration data nodes under a choice, any
any existing nodes from other "case" branches in the data tree are existing nodes from other case branches in the data tree are
deleted by the server. deleted by the server.
o If a request modifies a configuration data node such that any o If a request modifies a configuration data node such that any
node's "when" expression becomes false, then the node in the data node's "when" expression becomes false, then the node in the data
tree with the "when" expression is deleted by the server. tree with the "when" expression is deleted by the server.
8.3. NETCONF Constraint Enforcement Model 8.3. NETCONF Constraint Enforcement Model
For configuration data, there are three windows when constraints MUST For configuration data, there are three windows when constraints MUST
be enforced: be enforced:
skipping to change at page 134, line 8 skipping to change at page 139, line 48
8.3.1. Payload Parsing 8.3.1. Payload Parsing
When content arrives in RPC payloads, it MUST be well-formed XML, When content arrives in RPC payloads, it MUST be well-formed XML,
following the hierarchy and content rules defined by the set of following the hierarchy and content rules defined by the set of
models the server implements. models the server implements.
o If a leaf data value does not match the type constraints for the o If a leaf data value does not match the type constraints for the
leaf, including those defined in the type's "range", "length", and leaf, including those defined in the type's "range", "length", and
"pattern" properties, the server MUST reply with an "pattern" properties, the server MUST reply with an
"invalid-value" error-tag in the rpc-error, and with the error- "invalid-value" <error-tag> in the <rpc-error>, and with the
app-tag and error-message associated with the constraint, if any error-app-tag (Section 7.5.4.2) and error-message
exist. (Section 7.5.4.1) associated with the constraint, if any exist.
o If all keys of a list entry are not present, the server MUST reply o If all keys of a list entry are not present, the server MUST reply
with a "missing-element" error-tag in the rpc-error. with a "missing-element" <error-tag> in the <rpc-error>.
o If data for more than one case branch of a choice is present, the o If data for more than one case branch of a choice is present, the
server MUST reply with a "bad-element" in the rpc-error. server MUST reply with a "bad-element" <error-tag> in the
<rpc-error>.
o If data for a node tagged with "if-feature" is present, and the o If data for a node tagged with "if-feature" is present and the
if-feature expression evaluates to "false" in the server, the "if-feature" expression evaluates to "false" in the server, the
server MUST reply with an "unknown-element" error-tag in the rpc- server MUST reply with an "unknown-element" <error-tag> in the
error. <rpc-error>.
o If data for a node tagged with "when" is present, and the "when" o If data for a node tagged with "when" is present and the "when"
condition evaluates to "false", the server MUST reply with an condition evaluates to "false", the server MUST reply with an
"unknown-element" error-tag in the rpc-error. "unknown-element" <error-tag> in the <rpc-error>.
o For insert handling, if the value for the attributes "before" and o For insert handling, if the values for the attributes "before" and
"after" are not valid for the type of the appropriate key leafs, "after" are not valid for the type of the appropriate key leafs,
the server MUST reply with a "bad-attribute" error-tag in the rpc- the server MUST reply with a "bad-attribute" <error-tag> in the
error. <rpc-error>.
o If the attributes "before" and "after" appears in any element that o If the attributes "before" and "after" appear in any element that
is not a list whose "ordered-by" property is "user", the server is not a list whose "ordered-by" property is "user", the server
MUST reply with an "unknown-attribute" error-tag in the rpc-error. MUST reply with an "unknown-attribute" <error-tag> in the
<rpc-error>.
8.3.2. NETCONF <edit-config> Processing 8.3.2. NETCONF <edit-config> Processing
After the incoming data is parsed, the NETCONF server performs the After the incoming data is parsed, the NETCONF server performs the
<edit-config> operation by applying the data to the configuration <edit-config> operation by applying the data to the configuration
datastore. During this processing, the following errors MUST be datastore. During this processing, the following errors MUST be
detected: detected:
o Delete requests for non-existent data. o Delete requests for non-existent data.
o Create requests for existent data. o Create requests for existent data.
o Insert requests with "before" or "after" parameters that do not o Insert requests with "before" or "after" parameters that do not
exist. exist.
o Modification requests for nodes tagged with "when", and the "when" o Modification requests for nodes tagged with "when", and the "when"
condition evaluates to "false". In this case the server MUST condition evaluates to "false". In this case, the server MUST
reply with an "unknown-element" error-tag in the rpc-error. reply with an "unknown-element" <error-tag> in the <rpc-error>.
8.3.3. Validation 8.3.3. Validation
When datastore processing is complete, the final contents MUST obey When datastore processing is complete, the final contents MUST obey
all validation constraints. This validation processing is performed all validation constraints. This validation processing is performed
at differing times according to the datastore. If the datastore is at differing times according to the datastore. If the datastore is
"running" or "startup", these constraints MUST be enforced at the end "running" or "startup", these constraints MUST be enforced at the end
of the <edit-config> or <copy-config> operation. If the datastore is of the <edit-config> or <copy-config> operation. If the datastore is
"candidate", the constraint enforcement is delayed until a <commit> "candidate", the constraint enforcement is delayed until a <commit>
or <validate> operation. or <validate> operation takes place.
9. Built-In Types 9. Built-In Types
YANG has a set of built-in types, similar to those of many YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special programming languages, but with some differences due to special
requirements from the management information model. requirements from the management information model.
Additional types may be defined, derived from those built-in types or Additional types may be defined that are derived from those built-in
from other derived types. Derived types may use subtyping to types or from other derived types. Derived types may use subtyping
formally restrict the set of possible values. to formally restrict the set of possible values.
The different built-in types and their derived types allow different The different built-in types and their derived types allow different
kinds of subtyping, namely length and regular expression restrictions kinds of subtyping, namely length and regular expression restrictions
of strings (Section 9.4.4, Section 9.4.5) and range restrictions of of strings (Sections 9.4.4 and 9.4.5) and range restrictions of
numeric types (Section 9.2.4). numeric types (Section 9.2.4).
The lexical representation of a value of a certain type is used in The lexical representation of a value of a certain type is used in
the XML encoding and when specifying default values and numerical the XML encoding and when specifying default values and numerical
ranges in YANG modules. ranges in YANG modules.
9.1. Canonical Representation 9.1. Canonical Representation
For most types, there is a single canonical representation of the For most types, there is a single canonical representation of the
type's values. Some types allow multiple lexical representations of type's values. Some types allow multiple lexical representations of
the same value, for example, the positive integer "17" can be the same value; for example, the positive integer "17" can be
represented as "+17" or "17". Implementations MUST support all represented as "+17" or "17". Implementations MUST support all
lexical representations specified in this document. lexical representations specified in this document.
When a server sends XML encoded data, it MUST use the canonical form When a server sends XML-encoded data, it MUST use the canonical form
defined in this section. Other encodings may introduce alternate defined in this section. Other encodings may introduce alternate
representations. Note, however, that values in the data tree are representations. Note, however, that values in the data tree are
conceptually stored in the canonical representation as defined in conceptually stored in the canonical representation as defined in
this section. In particular, any XPath expression evaluations are this section. In particular, any XPath expression evaluations are
done using the canonical form, if the data type has a canonical form. done using the canonical form if the data type has a canonical form.
If the data type does not have a canonical form, the format of the If the data type does not have a canonical form, the format of the
value MUST match the data type's lexical representation, but the value MUST match the data type's lexical representation, but the
exact format is implementation dependent. exact format is implementation dependent.
Some types have a lexical representation that depends on the Some types have a lexical representation that depends on the
encoding, e.g., the XML context in which they occur. These types do encoding, e.g., the XML context in which they occur. These types do
not have a canonical form. not have a canonical form.
9.2. The Integer Built-In Types 9.2. The Integer Built-In Types
skipping to change at page 136, line 43 skipping to change at page 142, line 43
uint64 represents integer values between 0 and 18446744073709551615, uint64 represents integer values between 0 and 18446744073709551615,
inclusively. inclusively.
9.2.1. Lexical Representation 9.2.1. Lexical Representation
An integer value is lexically represented as an optional sign ("+" or An integer value is lexically represented as an optional sign ("+" or
"-"), followed by a sequence of decimal digits. If no sign is "-"), followed by a sequence of decimal digits. If no sign is
specified, "+" is assumed. specified, "+" is assumed.
For convenience, when specifying a default value for an integer in a For convenience, when specifying a default value for an integer in a
YANG module, an alternative lexical representation can be used, which YANG module, an alternative lexical representation can be used that
represents the value in a hexadecimal or octal notation. The represents the value in a hexadecimal or octal notation. The
hexadecimal notation consists of an optional sign ("+" or "-"), the hexadecimal notation consists of an optional sign ("+" or "-"),
characters "0x" followed a number of hexadecimal digits, where followed by the characters "0x", followed by a number of hexadecimal
letters may be uppercase or lowercase. The octal notation consists digits where letters may be uppercase or lowercase. The octal
of an optional sign ("+" or "-"), the character "0" followed a number notation consists of an optional sign ("+" or "-"), followed by the
of octal digits. character "0", followed by a number of octal digits.
Note that if a default value in a YANG module has a leading zero 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 ("0"), it is interpreted as an octal number. In the XML encoding, an
integer is always interpreted as a decimal number, and leading zeros integer is always interpreted as a decimal number, and leading zeros
are allowed. are allowed.
Examples: Examples:
// legal values // legal values
+4711 // legal positive value +4711 // legal positive value
skipping to change at page 137, line 23 skipping to change at page 143, line 26
0xf00f // legal positive hexadecimal value 0xf00f // legal positive hexadecimal value
-0xf // legal negative hexadecimal value -0xf // legal negative hexadecimal value
052 // legal positive octal value 052 // legal positive octal value
// illegal values // illegal values
- 1 // illegal intermediate space - 1 // illegal intermediate space
9.2.2. Canonical Form 9.2.2. Canonical Form
The canonical form of a positive integer does not include the sign The canonical form of a positive integer does not include the sign
"+". Leading zeros are prohibited. The value zero is represented as "+". Leading zeros are prohibited. The value zero is represented
"0". as "0".
9.2.3. Restrictions 9.2.3. Restrictions
All integer types can be restricted with the "range" statement All integer types can be restricted with the "range" statement
(Section 9.2.4). (Section 9.2.4).
9.2.4. The range Statement 9.2.4. The "range" Statement
The "range" statement, which is an optional substatement to the The "range" statement, which is an optional substatement to the
"type" statement, takes as an argument a range expression string. It "type" statement, takes as an argument a range expression string. It
is used to restrict integer and decimal built-in types, or types is used to restrict integer and decimal built-in types, or types
derived from those. derived from them.
A range consists of an explicit value, or a lower-inclusive bound, A range consists of an explicit value, or a lower-inclusive bound,
two consecutive dots "..", and an upper-inclusive bound. Multiple two consecutive dots "..", and an upper-inclusive bound. Multiple
values or ranges can be given, separated by "|". If multiple values values or ranges can be given, separated by "|". If multiple values
or ranges are given, they all MUST be disjoint and MUST be in or ranges are given, they all MUST be disjoint and MUST be in
ascending order. If a range restriction is applied to an already ascending order. If a range restriction is applied to a type that is
range-restricted type, the new restriction MUST be equal or more already range-restricted, the new restriction MUST be equally
limiting, that is raising the lower bounds, reducing the upper limiting or more limiting, i.e., raising the lower bounds, reducing
bounds, removing explicit values or ranges, or splitting ranges into the upper bounds, removing explicit values or ranges, or splitting
multiple ranges with intermediate gaps. Each explicit value and ranges into multiple ranges with intermediate gaps. Each explicit
range boundary value given in the range expression MUST match the value and range boundary value given in the range expression MUST
type being restricted, or be one of the special values "min" or match the type being restricted or be one of the special values "min"
"max". "min" and "max" mean the minimum and maximum value accepted or "max". "min" and "max" mean the minimum and maximum values
for the type being restricted, respectively. accepted for the type being restricted, respectively.
The range expression syntax is formally defined by the rule The range expression syntax is formally defined by the rule
"range-arg" in Section 14. "range-arg" in Section 14.
9.2.4.1. The range's Substatements 9.2.4.1. The range's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
skipping to change at page 138, line 43 skipping to change at page 144, line 46
typedef my-type2 { typedef my-type2 {
type my-base-int32-type { type my-base-int32-type {
// illegal range restriction // illegal range restriction
range "11..100"; range "11..100";
} }
} }
9.3. The decimal64 Built-In Type 9.3. The decimal64 Built-In Type
The decimal64 type represents a subset of the real numbers, which can The decimal64 built-in type represents a subset of the real numbers,
be represented by decimal numerals. The value space of decimal64 is which can be represented by decimal numerals. The value space of
the set of numbers that can be obtained by multiplying a 64-bit decimal64 is the set of numbers that can be obtained by multiplying a
signed integer by a negative power of ten, i.e., expressible as "i x 64-bit signed integer by a negative power of ten, i.e., expressible
10^-n" where i is an integer64 and n is an integer between 1 and 18, as "i x 10^-n" where i is an integer64 and n is an integer between 1
inclusively. and 18, inclusively.
9.3.1. Lexical Representation 9.3.1. Lexical Representation
A decimal64 value is lexically represented as an optional sign ("+" A decimal64 value is lexically represented as an optional sign ("+"
or "-"), followed by a sequence of decimal digits, optionally or "-"), followed by a sequence of decimal digits, optionally
followed by a period ('.') as a decimal indicator and a sequence of followed by a period ('.') as a decimal indicator and a sequence of
decimal digits. If no sign is specified, "+" is assumed. decimal digits. If no sign is specified, "+" is assumed.
9.3.2. Canonical Form 9.3.2. Canonical Form
The canonical form of a positive decimal64 does not include the sign The canonical form of a positive decimal64 value does not include the
"+". The decimal point is required. Leading and trailing zeros are sign "+". The decimal point is required. Leading and trailing zeros
prohibited, subject to the rule that there MUST be at least one digit are prohibited, subject to the rule that there MUST be at least one
before and after the decimal point. The value zero is represented as digit before and after the decimal point. The value zero is
"0.0". represented as "0.0".
9.3.3. Restrictions 9.3.3. Restrictions
A decimal64 type can be restricted with the "range" statement A decimal64 type can be restricted with the "range" statement
(Section 9.2.4). (Section 9.2.4).
9.3.4. The fraction-digits Statement 9.3.4. The "fraction-digits" Statement
The "fraction-digits" statement, which is a substatement to the The "fraction-digits" statement, which is a substatement to the
"type" statement, MUST be present if the type is "decimal64". It "type" statement, MUST be present if the type is "decimal64". It
takes as an argument an integer between 1 and 18, inclusively. It takes as an argument an integer between 1 and 18, inclusively. It
controls the size of the minimum difference between values of a controls the size of the minimum difference between values of a
decimal64 type, by restricting the value space to numbers that are decimal64 type by restricting the value space to numbers that are
expressible as "i x 10^-n" where n is the fraction-digits argument. expressible as "i x 10^-n" where n is the fraction-digits argument.
The following table lists the minimum and maximum value for each The following table lists the minimum and maximum values for each
fraction-digit value: fraction-digit value:
+----------------+-----------------------+----------------------+ +----------------+-----------------------+----------------------+
| fraction-digit | min | max | | fraction-digit | min | max |
+----------------+-----------------------+----------------------+ +----------------+-----------------------+----------------------+
| 1 | -922337203685477580.8 | 922337203685477580.7 | | 1 | -922337203685477580.8 | 922337203685477580.7 |
| 2 | -92233720368547758.08 | 92233720368547758.07 | | 2 | -92233720368547758.08 | 92233720368547758.07 |
| 3 | -9223372036854775.808 | 9223372036854775.807 | | 3 | -9223372036854775.808 | 9223372036854775.807 |
| 4 | -922337203685477.5808 | 922337203685477.5807 | | 4 | -922337203685477.5808 | 922337203685477.5807 |
| 5 | -92233720368547.75808 | 92233720368547.75807 | | 5 | -92233720368547.75808 | 92233720368547.75807 |
skipping to change at page 141, line 8 skipping to change at page 147, line 8
"yang-string" in Section 14. "yang-string" in Section 14.
9.4.1. Lexical Representation 9.4.1. Lexical Representation
A string value is lexically represented as character data in the XML A string value is lexically represented as character data in the XML
encoding. encoding.
9.4.2. Canonical Form 9.4.2. Canonical Form
The canonical form is the same as the lexical representation. No The canonical form is the same as the lexical representation. No
Unicode normalization is performed of string values. Unicode normalization of string values is performed.
9.4.3. Restrictions 9.4.3. Restrictions
A string can be restricted with the "length" (Section 9.4.4) and A string can be restricted with the "length" (Section 9.4.4) and
"pattern" (Section 9.4.5) statements. "pattern" (Section 9.4.5) statements.
9.4.4. The length Statement 9.4.4. The "length" Statement
The "length" statement, which is an optional substatement to the The "length" statement, which is an optional substatement to the
"type" statement, takes as an argument a length expression string. "type" statement, takes as an argument a length expression string.
It is used to restrict the built-in types "string" and "binary" or It is used to restrict the built-in types "string" and "binary" or
types derived from them. types derived from them.
A "length" statement restricts the number of Unicode characters in A "length" statement restricts the number of Unicode characters in
the string. the string.
A length range consists of an explicit value, or a lower bound, two A length range consists of an explicit value, or a lower bound, two
consecutive dots "..", and an upper bound. Multiple values or ranges consecutive dots "..", and an upper bound. Multiple values or ranges
can be given, separated by "|". Length-restricting values MUST NOT can be given, separated by "|". Length-restricting values MUST NOT
be negative. If multiple values or ranges are given, they all MUST be negative. If multiple values or ranges are given, they all MUST
be disjoint and MUST be in ascending order. If a length restriction be disjoint and MUST be in ascending order. If a length restriction
is applied to an already length-restricted type, the new restriction is applied to a type that is already length-restricted, the new
MUST be equal or more limiting, that is, raising the lower bounds, restriction MUST be equally limiting or more limiting, i.e., raising
reducing the upper bounds, removing explicit length values or ranges, the lower bounds, reducing the upper bounds, removing explicit length
or splitting ranges into multiple ranges with intermediate gaps. A values or ranges, or splitting ranges into multiple ranges with
length value is a non-negative integer, or one of the special values intermediate gaps. A length value is a non-negative integer or one
"min" or "max". "min" and "max" mean the minimum and maximum length of the special values "min" or "max". "min" and "max" mean the
accepted for the type being restricted, respectively. An minimum and maximum lengths accepted for the type being restricted,
implementation is not required to support a length value larger than respectively. An implementation is not required to support a length
18446744073709551615. value larger than 18446744073709551615.
The length expression syntax is formally defined by the rule The length expression syntax is formally defined by the rule
"length-arg" in Section 14. "length-arg" in Section 14.
9.4.4.1. The length's Substatements 9.4.4.1. The length's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.4.5. The pattern Statement 9.4.5. The "pattern" Statement
The "pattern" statement, which is an optional substatement to the The "pattern" statement, which is an optional substatement to the
"type" statement, takes as an argument a regular expression string, "type" statement, takes as an argument a regular expression string,
as defined in [XSD-TYPES]. It is used to restrict the built-in type as defined in [XSD-TYPES]. It is used to restrict the built-in type
"string", or types derived from "string", to values that match the "string", or types derived from "string", to values that match the
pattern. pattern.
If the type has multiple "pattern" statements, the expressions are If the type has multiple "pattern" statements, the expressions are
ANDed together, i.e., all such expressions have to match. ANDed together, i.e., all such expressions have to match.
If a pattern restriction is applied to an already pattern-restricted If a pattern restriction is applied to a type that is already
type, values must match all patterns in the base type, in addition to pattern-restricted, values must match all patterns in the base type,
the new patterns. in addition to the new patterns.
9.4.5.1. The pattern's Substatements 9.4.5.1. The pattern's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| modifier | 9.4.6 | 0..1 | | modifier | 9.4.6 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.4.6. The modifier Statement 9.4.6. The "modifier" Statement
The "modifier" statement, which is an optional substatement to the The "modifier" statement, which is an optional substatement to the
"pattern" statement, takes as an argument the string "invert-match". "pattern" statement, takes as an argument the string "invert-match".
If a pattern has the "invert-match" modifier present, the type is If a pattern has the "invert-match" modifier present, the type is
restricted to values that do not match the pattern. restricted to values that do not match the pattern.
9.4.7. Usage Example 9.4.7. Usage Example
With the following typedef: With the following typedef:
skipping to change at page 143, line 36 skipping to change at page 150, line 7
AB // legal AB // legal
9A00 // legal 9A00 // legal
and the following strings do not match: and the following strings do not match:
00ABAB // illegal, too long 00ABAB // illegal, too long
xx00 // illegal, bad characters xx00 // illegal, bad characters
With the following type: With the following type:
typedef yang-identifier { type string {
type string { length "1..max";
length "1..max"; pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; pattern '[xX][mM][lL].*' {
pattern '[xX][mM][lL].*' { modifier invert-match;
modifier invert-match;
}
} }
} }
the following string match: the following string matches:
enabled // legal enabled // legal
and the following strings do not match: and the following strings do not match:
10-mbit // illegal, starts with a number 10-mbit // illegal, starts with a number
xml-element // illegal, starts with illegal sequence xml-element // illegal, starts with illegal sequence
9.5. The boolean Built-In Type 9.5. The boolean Built-In Type
skipping to change at page 144, line 45 skipping to change at page 151, line 15
9.6.2. Canonical Form 9.6.2. Canonical Form
The canonical form is the assigned name string. The canonical form is the assigned name string.
9.6.3. Restrictions 9.6.3. Restrictions
An enumeration can be restricted with one or more "enum" An