draft-ietf-netmod-yang-13.txt   rfc6020.txt 
Network Working Group M. Bjorklund, Ed. Internet Engineering Task Force (IETF) M. Bjorklund, Ed.
Internet-Draft Tail-f Systems Request for Comments: 6020 Tail-f Systems
Intended status: Standards Track June 1, 2010 Category: Standards Track October 2010
Expires: December 3, 2010 ISSN: 2070-1721
YANG - A data modeling language for the Network Configuration Protocol YANG - A Data Modeling Language for
(NETCONF) the Network Configuration Protocol (NETCONF)
draft-ietf-netmod-yang-13
Abstract Abstract
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
state data manipulated by the Network Configuration Protocol state data manipulated by the Network Configuration Protocol
(NETCONF) protocol, NETCONF remote procedure calls, and NETCONF (NETCONF), NETCONF remote procedure calls, and NETCONF notifications.
notifications.
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Status of This Memo
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at This is an Internet Standards Track document.
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at This document is a product of the Internet Engineering Task Force
http://www.ietf.org/shadow.html. (IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
This Internet-Draft will expire on December 3, 2010. 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/rfc6020.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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 3, line 7 skipping to change at page 2, line 19
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 . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction ....................................................8
2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2. Keywords ........................................................8
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 11 3. Terminology .....................................................8
3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 13 3.1. Mandatory Nodes ...........................................10
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 14 4. YANG Overview ..................................................11
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 14 4.1. Functional Overview .......................................11
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 4.2. Language Overview .........................................13
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 4.2.1. Modules and Submodules .............................13
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16 4.2.2. Data Modeling Basics ...............................13
4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 4.2.3. State Data .........................................18
4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 20 4.2.4. Built-In Types .....................................18
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 4.2.5. Derived Types (typedef) ............................19
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 4.2.6. Reusable Node Groups (grouping) ....................20
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.7. Choices ............................................21
4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 4.2.8. Extending Data Models (augment) ....................22
4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 25 4.2.9. RPC Definitions ....................................23
4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 4.2.10. Notification Definitions ..........................24
5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 5. Language Concepts ..............................................25
5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 5.1. Modules and Submodules ....................................25
5.1.1. Import and Include by Revision . . . . . . . . . . . 29 5.1.1. Import and Include by Revision .....................26
5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 5.1.2. Module Hierarchies .................................27
5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 5.2. File Layout ...............................................28
5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 5.3. XML Namespaces ............................................29
5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 5.3.1. YANG XML Namespace .................................29
5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 5.4. Resolving Grouping, Type, and Identity Names ..............29
5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 5.5. Nested Typedefs and Groupings .............................29
5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 5.6. Conformance ...............................................30
5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 5.6.1. Basic Behavior .....................................31
5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 5.6.2. Optional Features ..................................31
5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 5.6.3. Deviations .........................................31
5.6.4. Announcing Conformance Information in the <hello> 5.6.4. Announcing Conformance Information in the
Message . . . . . . . . . . . . . . . . . . . . . . . 34 <hello> Message ....................................32
5.7. Data Store Modification . . . . . . . . . . . . . . . . . 36 5.7. Data Store Modification ...................................34
6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 37 6. YANG Syntax ....................................................34
6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 37 6.1. Lexical Tokenization ......................................34
6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 37 6.1.1. Comments ...........................................34
6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 37 6.1.2. Tokens .............................................34
6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 37 6.1.3. Quoting ............................................35
6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 39 6.2. Identifiers ...............................................36
6.2.1. Identifiers and their namespaces . . . . . . . . . . 39 6.2.1. Identifiers and Their Namespaces ...................36
6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 40 6.3. Statements ................................................37
6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 40 6.3.1. Language Extensions ................................37
6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 40 6.4. XPath Evaluations .........................................38
6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 41 6.4.1. XPath Context ......................................38
6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 41 6.5. Schema Node Identifier ....................................39
7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 43 7. YANG Statements ................................................39
7.1. The module Statement . . . . . . . . . . . . . . . . . . 43 7.1. The module Statement ......................................39
7.1.1. The module's Substatements . . . . . . . . . . . . . 44 7.1.1. The module's Substatements .........................41
7.1.2. The yang-version Statement . . . . . . . . . . . . . 45 7.1.2. The yang-version Statement .........................41
7.1.3. The namespace Statement . . . . . . . . . . . . . . . 45 7.1.3. The namespace Statement ............................42
7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 46 7.1.4. The prefix Statement ...............................42
7.1.5. The import Statement . . . . . . . . . . . . . . . . 46 7.1.5. The import Statement ...............................42
7.1.6. The include Statement . . . . . . . . . . . . . . . . 47 7.1.6. The include Statement ..............................43
7.1.7. The organization Statement . . . . . . . . . . . . . 48 7.1.7. The organization Statement .........................44
7.1.8. The contact Statement . . . . . . . . . . . . . . . . 48 7.1.8. The contact Statement ..............................44
7.1.9. The revision Statement . . . . . . . . . . . . . . . 48 7.1.9. The revision Statement .............................44
7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 49 7.1.10. Usage Example .....................................45
7.2. The submodule Statement . . . . . . . . . . . . . . . . . 49 7.2. The submodule Statement ...................................46
7.2.1. The submodule's Substatements . . . . . . . . . . . . 51 7.2.1. The submodule's Substatements ......................48
7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 51 7.2.2. The belongs-to Statement ...........................48
7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 52 7.2.3. Usage Example ......................................49
7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 52 7.3. The typedef Statement .....................................49
7.3.1. The typedef's Substatements . . . . . . . . . . . . . 53 7.3.1. The typedef's Substatements ........................50
7.3.2. The typedef's type Statement . . . . . . . . . . . . 53 7.3.2. The typedef's type Statement .......................50
7.3.3. The units Statement . . . . . . . . . . . . . . . . . 53 7.3.3. The units Statement ................................50
7.3.4. The typedef's default Statement . . . . . . . . . . . 53 7.3.4. The typedef's default Statement ....................50
7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 54 7.3.5. Usage Example ......................................51
7.4. The type Statement . . . . . . . . . . . . . . . . . . . 54 7.4. The type Statement ........................................51
7.4.1. The type's Substatements . . . . . . . . . . . . . . 54 7.4.1. The type's Substatements ...........................51
7.5. The container Statement . . . . . . . . . . . . . . . . . 54 7.5. The container Statement ...................................51
7.5.1. Containers with Presence . . . . . . . . . . . . . . 55 7.5.1. Containers with Presence ...........................52
7.5.2. The container's Substatements . . . . . . . . . . . . 56 7.5.2. The container's Substatements ......................53
7.5.3. The must Statement . . . . . . . . . . . . . . . . . 56 7.5.3. The must Statement .................................53
7.5.4. The must's Substatements . . . . . . . . . . . . . . 58 7.5.4. The must's Substatements ...........................55
7.5.5. The presence Statement . . . . . . . . . . . . . . . 59 7.5.5. The presence Statement .............................56
7.5.6. The container's Child Node Statements . . . . . . . . 59 7.5.6. The container's Child Node Statements ..............56
7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 59 7.5.7. XML Mapping Rules ..................................56
7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 59 7.5.8. NETCONF <edit-config> Operations ...................56
7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 60 7.5.9. Usage Example ......................................57
7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 61 7.6. The leaf Statement ........................................58
7.6.1. The leaf's default value . . . . . . . . . . . . . . 61 7.6.1. The leaf's default value ...........................58
7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 62 7.6.2. The leaf's Substatements ...........................59
7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 62 7.6.3. The leaf's type Statement ..........................59
7.6.4. The leaf's default Statement . . . . . . . . . . . . 62 7.6.4. The leaf's default Statement .......................59
7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 63 7.6.5. The leaf's mandatory Statement .....................60
7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 63 7.6.6. XML Mapping Rules ..................................60
7.6.7. NETCONF <edit-config> Operations . . . . . . . . . . 63 7.6.7. NETCONF <edit-config> Operations ...................60
7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 64 7.6.8. Usage Example ......................................61
7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 65 7.7. The leaf-list Statement ...................................62
7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 65 7.7.1. Ordering ...........................................62
7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 66 7.7.2. The leaf-list's Substatements ......................63
7.7.3. The min-elements Statement . . . . . . . . . . . . . 66 7.7.3. The min-elements Statement .........................63
7.7.4. The max-elements Statement . . . . . . . . . . . . . 66 7.7.4. The max-elements Statement .........................63
7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 67 7.7.5. The ordered-by Statement ...........................64
7.7.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 67 7.7.6. XML Mapping Rules ..................................64
7.7.7. NETCONF <edit-config> Operations . . . . . . . . . . 68 7.7.7. NETCONF <edit-config> Operations ...................65
7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 69 7.7.8. Usage Example ......................................66
7.8. The list Statement . . . . . . . . . . . . . . . . . . . 70 7.8. The list Statement ........................................67
7.8.1. The list's Substatements . . . . . . . . . . . . . . 71 7.8.1. The list's Substatements ...........................68
7.8.2. The list's key Statement . . . . . . . . . . . . . . 71 7.8.2. The list's key Statement ...........................68
7.8.3. The list's unique Statement . . . . . . . . . . . . . 72 7.8.3. The list's unique Statement ........................69
7.8.4. The list's Child Node Statements . . . . . . . . . . 73 7.8.4. The list's Child Node Statements ...................70
7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 73 7.8.5. XML Mapping Rules ..................................70
7.8.6. NETCONF <edit-config> Operations . . . . . . . . . . 74 7.8.6. NETCONF <edit-config> Operations ...................71
7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 75 7.8.7. Usage Example ......................................72
7.9. The choice Statement . . . . . . . . . . . . . . . . . . 78 7.9. The choice Statement ......................................75
7.9.1. The choice's Substatements . . . . . . . . . . . . . 79 7.9.1. The choice's Substatements .........................76
7.9.2. The choice's case Statement . . . . . . . . . . . . . 79 7.9.2. The choice's case Statement ........................76
7.9.3. The choice's default Statement . . . . . . . . . . . 80 7.9.3. The choice's default Statement .....................77
7.9.4. The choice's mandatory Statement . . . . . . . . . . 82 7.9.4. The choice's mandatory Statement ...................79
7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 82 7.9.5. XML Mapping Rules ..................................79
7.9.6. NETCONF <edit-config> Operations . . . . . . . . . . 82 7.9.6. NETCONF <edit-config> Operations ...................79
7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 82 7.9.7. Usage Example ......................................79
7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 83 7.10. The anyxml Statement .....................................80
7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 84 7.10.1. The anyxml's Substatements ........................81
7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 84 7.10.2. XML Mapping Rules .................................81
7.10.3. NETCONF <edit-config> Operations . . . . . . . . . . 84 7.10.3. NETCONF <edit-config> Operations ..................81
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 85 7.10.4. Usage Example .....................................82
7.11. The grouping Statement . . . . . . . . . . . . . . . . . 85 7.11. The grouping Statement ...................................82
7.11.1. The grouping's Substatements . . . . . . . . . . . . 86 7.11.1. The grouping's Substatements ......................83
7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 87 7.11.2. Usage Example .....................................84
7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 87 7.12. The uses Statement .......................................84
7.12.1. The uses's Substatements . . . . . . . . . . . . . . 88 7.12.1. The uses's Substatements ..........................85
7.12.2. The refine Statement . . . . . . . . . . . . . . . . 88 7.12.2. The refine Statement ..............................85
7.12.3. XML Mapping Rules . . . . . . . . . . . . . . . . . . 89 7.12.3. XML Mapping Rules .................................86
7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 89 7.12.4. Usage Example .....................................86
7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 90 7.13. The rpc Statement ........................................87
7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 91 7.13.1. The rpc's Substatements ...........................88
7.13.2. The input Statement . . . . . . . . . . . . . . . . . 91 7.13.2. The input Statement ...............................88
7.13.3. The output Statement . . . . . . . . . . . . . . . . 92 7.13.3. The output Statement ..............................89
7.13.4. XML Mapping Rules . . . . . . . . . . . . . . . . . . 93 7.13.4. XML Mapping Rules .................................90
7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 93 7.13.5. Usage Example .....................................91
7.14. The notification Statement . . . . . . . . . . . . . . . 94 7.14. The notification Statement ...............................91
7.14.1. The notification's Substatements . . . . . . . . . . 95 7.14.1. The notification's Substatements ..................92
7.14.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 95 7.14.2. XML Mapping Rules .................................92
7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 95 7.14.3. Usage Example .....................................93
7.15. The augment Statement . . . . . . . . . . . . . . . . . . 96 7.15. The augment Statement ....................................93
7.15.1. The augment's Substatements . . . . . . . . . . . . . 97 7.15.1. The augment's Substatements .......................94
7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . . 97 7.15.2. XML Mapping Rules .................................94
7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 97 7.15.3. Usage Example .....................................95
7.16. The identity Statement . . . . . . . . . . . . . . . . . 99 7.16. The identity Statement ...................................97
7.16.1. The identity's Substatements . . . . . . . . . . . . 100 7.16.1. The identity's Substatements ......................97
7.16.2. The base Statement . . . . . . . . . . . . . . . . . 100 7.16.2. The base Statement ................................97
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 101 7.16.3. Usage Example .....................................98
7.17. The extension Statement . . . . . . . . . . . . . . . . . 101 7.17. The extension Statement ..................................98
7.17.1. The extension's Substatements . . . . . . . . . . . . 102 7.17.1. The extension's Substatements .....................99
7.17.2. The argument Statement . . . . . . . . . . . . . . . 102 7.17.2. The argument Statement ............................99
7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 103 7.17.3. Usage Example ....................................100
7.18. Conformance-related Statements . . . . . . . . . . . . . 103 7.18. Conformance-Related Statements ..........................100
7.18.1. The feature Statement . . . . . . . . . . . . . . . . 103 7.18.1. The feature Statement ............................100
7.18.2. The if-feature Statement . . . . . . . . . . . . . . 105 7.18.2. The if-feature Statement .........................102
7.18.3. The deviation Statement . . . . . . . . . . . . . . . 105 7.18.3. The deviation Statement ..........................102
7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 108 7.19. Common Statements .......................................105
7.19.1. The config Statement . . . . . . . . . . . . . . . . 108 7.19.1. The config Statement .............................105
7.19.2. The status Statement . . . . . . . . . . . . . . . . 108 7.19.2. The status Statement .............................105
7.19.3. The description Statement . . . . . . . . . . . . . . 109 7.19.3. The description Statement ........................106
7.19.4. The reference Statement . . . . . . . . . . . . . . . 109 7.19.4. The reference Statement ..........................106
7.19.5. The when Statement . . . . . . . . . . . . . . . . . 110 7.19.5. The when Statement ...............................107
8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 112 8. Constraints ...................................................108
8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 112 8.1. Constraints on Data ......................................108
8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 112 8.2. Hierarchy of Constraints .................................109
8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 112 8.3. Constraint Enforcement Model .............................109
8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 113 8.3.1. Payload Parsing ...................................109
8.3.2. NETCONF <edit-config> Processing . . . . . . . . . . 113 8.3.2. NETCONF <edit-config> Processing ..................110
8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 114 8.3.3. Validation ........................................111
9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 115 9. Built-In Types ................................................111
9.1. Canonical representation . . . . . . . . . . . . . . . . 115 9.1. Canonical Representation .................................112
9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 115 9.2. The Integer Built-In Types ...............................112
9.2.1. Lexical Representation . . . . . . . . . . . . . . . 116 9.2.1. Lexical Representation ............................113
9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 117 9.2.2. Canonical Form ....................................114
9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 117 9.2.3. Restrictions ......................................114
9.2.4. The range Statement . . . . . . . . . . . . . . . . . 117 9.2.4. The range Statement ...............................114
9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 118 9.2.5. Usage Example .....................................115
9.3. The decimal64 Built-in Type . . . . . . . . . . . . . . . 118 9.3. The decimal64 Built-In Type ..............................115
9.3.1. Lexical Representation . . . . . . . . . . . . . . . 118 9.3.1. Lexical Representation ............................115
9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 118 9.3.2. Canonical Form ....................................115
9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 119 9.3.3. Restrictions ......................................116
9.3.4. The fraction-digits Statement . . . . . . . . . . . . 119 9.3.4. The fraction-digits Statement .....................116
9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 120 9.3.5. Usage Example .....................................117
9.4. The string Built-in Type . . . . . . . . . . . . . . . . 120 9.4. The string Built-In Type .................................117
9.4.1. Lexical Representation . . . . . . . . . . . . . . . 120 9.4.1. Lexical Representation ............................117
9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 120 9.4.2. Canonical Form ....................................117
9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 120 9.4.3. Restrictions ......................................117
9.4.4. The length Statement . . . . . . . . . . . . . . . . 120 9.4.4. The length Statement ..............................117
9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 121 9.4.5. Usage Example .....................................118
9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 122 9.4.6. The pattern Statement .............................119
9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 122 9.4.7. Usage Example .....................................119
9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 123 9.5. The boolean Built-In Type ................................120
9.5.1. Lexical Representation . . . . . . . . . . . . . . . 123 9.5.1. Lexical Representation ............................120
9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 9.5.2. Canonical Form ....................................120
9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 9.5.3. Restrictions ......................................120
9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 123 9.6. The enumeration Built-In Type ............................120
9.6.1. Lexical Representation . . . . . . . . . . . . . . . 123 9.6.1. Lexical Representation ............................120
9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 123 9.6.2. Canonical Form ....................................120
9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 123 9.6.3. Restrictions ......................................120
9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 123 9.6.4. The enum Statement ................................120
9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124 9.6.5. Usage Example .....................................121
9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 125 9.7. The bits Built-In Type ...................................122
9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 125 9.7.1. Restrictions ......................................122
9.7.2. Lexical Representation . . . . . . . . . . . . . . . 125 9.7.2. Lexical Representation ............................122
9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 125 9.7.3. Canonical Form ....................................122
9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 125 9.7.4. The bit Statement .................................122
9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 9.7.5. Usage Example .....................................123
9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 126 9.8. The binary Built-In Type .................................123
9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 9.8.1. Restrictions ......................................124
9.8.2. Lexical Representation . . . . . . . . . . . . . . . 127 9.8.2. Lexical Representation ............................124
9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 127 9.8.3. Canonical Form ....................................124
9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 127 9.9. The leafref Built-In Type ................................124
9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127 9.9.1. Restrictions ......................................124
9.9.2. The path Statement . . . . . . . . . . . . . . . . . 127 9.9.2. The path Statement ................................124
9.9.3. Lexical Representation . . . . . . . . . . . . . . . 128 9.9.3. Lexical Representation ............................125
9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 128 9.9.4. Canonical Form ....................................125
9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 9.9.5. Usage Example .....................................126
9.10. The identityref Built-in Type . . . . . . . . . . . . . . 132 9.10. The identityref Built-In Type ...........................129
9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 132 9.10.1. Restrictions .....................................129
9.10.2. The identityref's base Statement . . . . . . . . . . 132 9.10.2. The identityref's base Statement .................129
9.10.3. Lexical Representation . . . . . . . . . . . . . . . 133 9.10.3. Lexical Representation ...........................130
9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 133 9.10.4. Canonical Form ...................................130
9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 9.10.5. Usage Example ....................................130
9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 134 9.11. The empty Built-In Type .................................131
9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 134 9.11.1. Restrictions .....................................131
9.11.2. Lexical Representation . . . . . . . . . . . . . . . 134 9.11.2. Lexical Representation ...........................131
9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 134 9.11.3. Canonical Form ...................................131
9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 134 9.11.4. Usage Example ....................................131
9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 135 9.12. The union Built-In Type .................................132
9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 9.12.1. Restrictions .....................................132
9.12.2. Lexical Representation . . . . . . . . . . . . . . . 135 9.12.2. Lexical Representation ...........................132
9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 9.12.3. Canonical Form ...................................133
9.13. The instance-identifier Built-in Type . . . . . . . . . . 136 9.13. The instance-identifier Built-In Type ...................133
9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 136 9.13.1. Restrictions .....................................134
9.13.2. The require-instance Statement . . . . . . . . . . . 137 9.13.2. The require-instance Statement ...................134
9.13.3. Lexical Representation . . . . . . . . . . . . . . . 137 9.13.3. Lexical Representation ...........................134
9.13.4. Canonical Form . . . . . . . . . . . . . . . . . . . 137 9.13.4. Canonical Form ...................................134
9.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 137 9.13.5. Usage Example ....................................134
10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 139 10. Updating a Module ............................................135
11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 11. YIN ..........................................................137
11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 142 11.1. Formal YIN Definition ...................................137
11.1.1. Usage Example . . . . . . . . . . . . . . . . . . . . 144 11.1.1. Usage Example ....................................141
12. YANG ABNF Grammar ............................................143
12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 147 13. Error Responses for YANG Related Errors ......................165
13. Error Responses for YANG Related Errors . . . . . . . . . . . 169 13.1. Error Message for Data That Violates a unique
13.1. Error Message for Data that Violates a unique Statement . 169 Statement ...............................................165
13.2. Error Message for Data that Violates a max-elements 13.2. Error Message for Data That Violates a
Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 max-elements Statement ..................................165
13.3. Error Message for Data that Violates a min-elements 13.3. Error Message for Data That Violates a
Statement . . . . . . . . . . . . . . . . . . . . . . . . 169 min-elements Statement ..................................165
13.4. Error Message for Data that Violates a must Statement . . 170 13.4. Error Message for Data That Violates a must Statement ...166
13.5. Error Message for Data that Violates a 13.5. Error Message for Data That Violates a
require-instance Statement . . . . . . . . . . . . . . . 170 require-instance Statement ..............................166
13.6. Error Message for Data that does not Match a leafref 13.6. Error Message for Data That Does Not Match a
Type . . . . . . . . . . . . . . . . . . . . . . . . . . 170 leafref Type ............................................166
13.7. Error Message for Data that Violates a mandatory 13.7. Error Message for Data That Violates a mandatory
choice Statement . . . . . . . . . . . . . . . . . . . . 170 choice Statement ........................................166
13.8. Error Message for the "insert" Operation . . . . . . . . 171 13.8. Error Message for the "insert" Operation ................167
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 172 14. IANA Considerations ..........................................167
14.1. Media type application/yang . . . . . . . . . . . . . . . 173 14.1. Media type application/yang .............................168
14.2. Media type application/yin+xml . . . . . . . . . . . . . 173 14.2. Media type application/yin+xml ..........................169
15. Security Considerations . . . . . . . . . . . . . . . . . . . 175 15. Security Considerations ......................................170
16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 176 16. Contributors .................................................171
17. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 177 17. Acknowledgements .............................................171
18. References . . . . . . . . . . . . . . . . . . . . . . . . . 178 18. References ...................................................171
18.1. Normative References . . . . . . . . . . . . . . . . . . 178 18.1. Normative References ....................................171
18.2. Non-Normative References . . . . . . . . . . . . . . . . 179 18.2. Informative References ..................................172
Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 180
A.1. Version -12 . . . . . . . . . . . . . . . . . . . . . . . 180
A.2. Version -11 . . . . . . . . . . . . . . . . . . . . . . . 180
A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 180
A.4. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 180
A.5. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 181
A.6. Version -07 . . . . . . . . . . . . . . . . . . . . . . . 181
A.7. Version -06 . . . . . . . . . . . . . . . . . . . . . . . 181
A.8. Version -05 . . . . . . . . . . . . . . . . . . . . . . . 181
A.9. Version -04 . . . . . . . . . . . . . . . . . . . . . . . 182
A.10. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 182
A.11. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 183
A.12. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 183
A.13. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 184
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 185
1. Introduction 1. Introduction
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
state data manipulated by the Network Configuration Protocol state data manipulated by the Network Configuration Protocol
(NETCONF) protocol, NETCONF remote procedure calls, and NETCONF (NETCONF), NETCONF remote procedure calls, and NETCONF notifications.
notifications. YANG is used to model the operations and content YANG is used to model the operations and content layers of NETCONF
layers of NETCONF (see the NETCONF Configuration Protocol [RFC4741], (see the NETCONF Configuration Protocol [RFC4741], Section 1.1).
section 1.1).
This document describes the syntax and semantics of the YANG This document describes the syntax and semantics of the YANG
language, how the data model defined in a YANG module is represented language, how the data model defined in a YANG module is represented
in the Extensible Markup Language (XML), and how NETCONF operations in the Extensible Markup Language (XML), and how NETCONF operations
are used to manipulate the data. are used to manipulate the data.
2. Key Words 2. Keywords
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119]. 14, [RFC2119].
3. Terminology 3. Terminology
o anyxml: A data node which can contain an unknown chunk of XML o anyxml: A data node that can contain an unknown chunk of XML data.
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
as uint32 or string. as uint32 or string.
o choice: A schema node where only one of a number of identified o choice: A schema node where only one of a number of identified
alternatives is valid. alternatives is valid.
o configuration data: The set of writable data that is required to o configuration data: The set of writable data that is required to
transform a system from its initial default state into its current transform a system from its initial default state into its current
state [RFC4741]. state [RFC4741].
o conformance: A measure of how accurately a device follows a data o conformance: A measure of how accurately a device follows a data
model. model.
o container: An interior data node which 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, case,
augment, uses, and anyxml. augment, uses, 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, and anyxml. data tree. One of container, leaf, leaf-list, list, and anyxml.
o data tree: The instantiated tree of configuration and state data o data tree: The instantiated tree of configuration and state data
on a device. on a device.
o derived type: A type which is derived from a built-in type (such o derived type: A type that is derived from a built-in type (such as
as uint32), or another derived type. uint32), or another derived type.
o device deviation: A failure of the device to implement the module o device deviation: A failure of the device to implement the module
faithfully. faithfully.
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 devices which support that feature. only valid on devices 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, in modules which include it, and by other locally in the module, in modules that include it, and by other
modules which import from it. The grouping statement is not a modules that import from it. The grouping statement is not a data
data definition statement and, as such, does not define any nodes definition statement and, as such, does not define any nodes in
in the schema tree. the schema tree.
o identifier: Used to identify different kinds of YANG items by o identifier: Used to identify different kinds of YANG items by
name. name.
o instance identifier: A mechanism for identifying a particular node o instance identifier: A mechanism for identifying a particular node
in a data tree. in a data tree.
o interior node: Nodes within a hierarchy that are not leaf nodes. o interior node: Nodes within a hierarchy that are not leaf nodes.
o leaf: A data node which exists in at most one instance in the data o leaf: A data node that exists in at most one instance in the data
tree. A leaf has a value but no child nodes. tree. A leaf has a value but no child nodes.
o leaf-list: Like the leaf node but defines a set of uniquely o leaf-list: Like the leaf node but defines a set of uniquely
identifiable nodes rather than a single node. Each node has a identifiable nodes rather than a single node. Each node has a
value but no child nodes. value but no child nodes.
o list: An interior data node which may exist in multiple instances o list: An interior data node that may exist in multiple instances
in the data tree. A list has no value, but rather a set of child in the data tree. A list has no value, but rather a set of child
nodes. nodes.
o module: A YANG module defines a hierarchy of nodes which can be o module: A YANG module defines a hierarchy of nodes that can be
used for NETCONF-based operations. With its definitions and the used for NETCONF-based operations. With its definitions and the
definitions it imports or includes from elsewhere, a module is definitions it imports or includes from elsewhere, a module is
self-contained and "compilable". self-contained and "compilable".
o RPC: A Remote Procedure Call, as used within the NETCONF protocol. o RPC: A Remote Procedure Call, as used within the NETCONF protocol.
o RPC operation: A specific Remote Procedure Call, as used within o RPC operation: A specific Remote Procedure Call, as used within
the NETCONF protocol. Also called a protocol operation. the NETCONF protocol. It is also called a protocol operation.
o schema node: A node in the schema tree. One of container, leaf, o schema node: A node in the schema tree. One of container, leaf,
leaf-list, list, choice, case, rpc, input, output, notification, leaf-list, list, choice, case, rpc, input, output, notification,
and anyxml. and anyxml.
o schema node identifier: A mechanism for identifying a particular o schema node identifier: A mechanism for identifying a particular
node in the schema tree. node in the schema tree.
o schema tree: The definition hierarchy specified within a module. o schema tree: The definition hierarchy specified within a module.
o state data: The additional data on a system that is not o state data: The additional data on a system that is not
configuration data such as read-only status information and configuration data such as read-only status information and
collected statistics [RFC4741]. collected statistics [RFC4741].
o submodule: A partial module definition which contributes derived o submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, and notifications to a module. types, groupings, data nodes, RPCs, and notifications to a module.
A YANG module can be constructed from a number of submodules. A YANG module can be constructed from a number of submodules.
o 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.
3.1. Mandatory nodes 3.1. Mandatory Nodes
A mandatory node is one of: A mandatory node is one of:
o A leaf, choice, or anyxml node with a "mandatory" statement with o A leaf, choice, or anyxml node with a "mandatory" statement with
the value "true". the value "true".
o A list or leaf-list node with a "min-elements" statement with a o A list or leaf-list node with a "min-elements" statement with a
value greater than zero. value greater than zero.
o A container node without a "presence" statement, which has at o A container node without a "presence" statement, which has at
least one mandatory node as a child. least one mandatory node as a child.
4. YANG Overview 4. YANG Overview
4.1. Functional Overview 4.1. Functional Overview
YANG is a language used to model data for the NETCONF protocol. A YANG is a language used to model data for the NETCONF protocol. A
YANG module defines a hierarchy of data which can be used for YANG module defines a hierarchy of data that can be used for NETCONF-
NETCONF-based operations, including configuration, state data, remote based operations, including configuration, state data, Remote
procedure calls (RPCs), and notifications. This allows a complete Procedure Calls (RPCs), and notifications. This allows a complete
description of all data sent between a NETCONF client and server. description of all data sent between a NETCONF client and server.
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 data from other external modules, and include data from can import data from other external modules, and include data from
submodules. The hierarchy can be augmented, allowing one module to submodules. The hierarchy can be augmented, allowing one module to
skipping to change at page 14, line 40 skipping to change at page 11, line 43
enforceable by either the client or the server, and valid content enforceable by either the client or the server, and valid content
MUST abide by them. MUST abide by them.
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 which additional types may be defined. Derived types can through which additional types may be defined. Derived types can
restrict their base type's set of valid values using mechanisms like restrict their base type's set of valid values using mechanisms like
range or pattern restrictions that can be enforced by clients or range or pattern restrictions that can be enforced by clients or
servers. They can also define usage conventions for use of the servers. They can also define usage conventions for use of the
derived type, such as a string-based type that contains a host name. derived type, such as a string-based type that contains a host name.
YANG permits the definition of reusable grouping of nodes. The YANG permits the definition of reusable groupings of nodes. The
instantiation of these groupings can refine or augment the nodes, instantiation of these groupings can refine or augment the nodes,
allowing it to tailor the nodes to its particular needs. Derived allowing it to tailor the nodes to its particular needs. Derived
types and groupings can be defined in one module or submodule and types and groupings can be defined in one module or submodule and
used in either that location or in another module or submodule that used in either that location or in another module or submodule that
imports or includes it. imports or includes it.
YANG data hierarchy constructs include defining lists where list YANG data hierarchy constructs include defining lists where list
entries are identified by keys which distinguish them from each entries are identified by keys that distinguish them from each other.
other. Such lists may be defined as either sorted by user or Such lists may be defined as either sorted by user or automatically
automatically sorted by the system. For user-sorted lists, sorted by the system. For user-sorted lists, operations are defined
operations are defined for manipulating the order of the list for manipulating the order of the list entries.
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 11), allowing applications YANG Independent Notation (YIN) (Section 11), allowing applications
using XML parsers and XSLT scripts to operate on the models. The using XML parsers and Extensible Stylesheet Language Transformations
conversion from YANG to YIN is loss-less, so content in YIN can be (XSLT) scripts to operate on the models. The conversion from YANG to
round-tripped back into YANG. YIN is lossless, so content in YIN can be round-tripped back into
YANG.
YANG strikes a balance between high-level data modeling and low-level YANG strikes a balance between high-level data modeling and low-level
bits-on-the-wire encoding. The reader of a YANG module can see the bits-on-the-wire encoding. The reader of a YANG module can see the
high-level view of the data model while understanding how the data high-level view of the data model while understanding how the data
will be encoded in NETCONF operations. will be encoded in NETCONF operations.
YANG is an extensible language, allowing extension statements to be YANG is an extensible language, allowing extension statements to be
defined by standards bodies, vendors, and individuals. The statement defined by standards bodies, vendors, and individuals. The statement
syntax allows these extensions to coexist with standard YANG syntax allows these extensions to coexist with standard YANG
statements in a natural way, while extensions in a YANG module stand statements in a natural way, while extensions in a YANG module stand
out sufficiently for the reader to notice them. out sufficiently 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 NETCONF data models, not the problem space to allow expression of NETCONF data models, not
arbitrary XML documents or arbitrary data models. The data models arbitrary XML documents or arbitrary data models. The data models
described by YANG are designed to be easily operated upon by NETCONF described by YANG are designed to be easily operated upon by NETCONF
operations. operations.
To the extent possible, YANG maintains compatibility with SNMP's To the extent possible, YANG maintains compatibility with Simple
SMIv2 (Structure of Management Information version 2 [RFC2578], Network Management Protocol's (SNMP's) SMIv2 (Structure of Management
[RFC2579]). SMIv2-based MIB modules can be automatically translated Information version 2 [RFC2578], [RFC2579]). SMIv2-based MIB modules
into YANG modules for read-only access. However, YANG is not can be automatically translated into YANG modules for read-only
concerned with reverse translation from YANG to SMIv2. access. However, YANG is not concerned with reverse translation from
YANG to SMIv2.
Like NETCONF, YANG targets smooth integration with the device's Like NETCONF, YANG targets smooth integration with the device's
native management infrastructure. This allows implementations to native management infrastructure. This allows implementations to
leverage their existing access control mechanisms to protect or leverage their existing access control mechanisms to protect or
expose elements of the data model. expose elements of the data model.
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
skipping to change at page 16, line 29 skipping to change at page 13, line 44
4.2.2. Data Modeling Basics 4.2.2. Data Modeling Basics
YANG defines four types of nodes for data modeling. In each of the YANG defines four types of nodes for data modeling. In each of the
following subsections, the example shows the YANG syntax as well as a following subsections, the example shows the YANG syntax as well as a
corresponding NETCONF XML representation. corresponding NETCONF XML representation.
4.2.2.1. Leaf Nodes 4.2.2.1. Leaf Nodes
A leaf node contains simple data like an integer or a string. It has A leaf node contains simple data like an integer or a string. It has
exactly one value of a particular type, and no child nodes. 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 "Hostname for this system"; description "Hostname for this system";
} }
NETCONF XML Example: NETCONF XML 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 is a sequence of leaf nodes with exactly one value of a A leaf-list is a sequence of leaf nodes with exactly one value of a
particular type per leaf. particular type per leaf.
YANG Example: YANG Example:
leaf-list domain-search { leaf-list domain-search {
type string; type string;
description "List of domain names to search"; description "List of domain names to search";
} }
skipping to change at page 20, line 18 skipping to change at page 18, line 18
the "config" statement. When a node is tagged with "config false", the "config" statement. When a node is tagged with "config false",
its subhierarchy is flagged as state data, to be reported using its subhierarchy is flagged as state data, to be reported using
NETCONF's <get> operation, not the <get-config> operation. Parent NETCONF's <get> operation, not the <get-config> operation. Parent
containers, lists, and key leafs are reported also, giving the containers, lists, and key leafs are reported also, giving the
context for the state data. context for the state data.
In this example, two leafs are defined for each interface, a In this example, two leafs are defined for each interface, a
configured speed and an observed speed. The observed speed is not configured speed and an observed speed. The observed speed is not
configuration, so it can be returned with NETCONF <get> operations, configuration, so it can be returned with NETCONF <get> operations,
but not with <get-config> operations. The observed speed is not but not with <get-config> operations. The observed speed is not
configuration data, and cannot be manipulated using <edit-config>. configuration data, and it cannot be manipulated using <edit-config>.
list interface { list interface {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf speed { leaf speed {
type enumeration { type enumeration {
enum 10m; enum 10m;
enum 100m; enum 100m;
enum auto; enum auto;
} }
} }
leaf observed-speed { leaf observed-speed {
type uint32; type uint32;
config false; config false;
} }
} }
4.2.4. Built-in Types 4.2.4. Built-In Types
YANG has a set of built-in types, similar to those of many YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special programming languages, but with some differences due to special
requirements from the management domain. The following table requirements from the management domain. The following table
summarizes the built-in types discussed in Section 9: summarizes the built-in types discussed in Section 9:
+---------------------+-------------------------------------+ +---------------------+-------------------------------------+
| Name | Description | | Name | Description |
+---------------------+-------------------------------------+ +---------------------+-------------------------------------+
| binary | Any binary data | | binary | Any binary data |
skipping to change at page 21, line 21 skipping to change at page 19, line 21
| decimal64 | 64-bit signed decimal number | | decimal64 | 64-bit signed decimal number |
| empty | A leaf that does not have any value | | empty | A leaf that does not have any value |
| enumeration | Enumerated strings | | enumeration | Enumerated strings |
| identityref | A reference to an abstract identity | | identityref | A reference to an abstract identity |
| instance-identifier | References a data tree node | | instance-identifier | References a data tree node |
| int8 | 8-bit signed integer | | int8 | 8-bit signed integer |
| int16 | 16-bit signed integer | | int16 | 16-bit signed integer |
| int32 | 32-bit signed integer | | int32 | 32-bit signed integer |
| int64 | 64-bit signed integer | | int64 | 64-bit signed integer |
| leafref | A reference to a leaf instance | | leafref | A reference to a leaf instance |
| string | Human readable string | | string | Human-readable string |
| uint8 | 8-bit unsigned integer | | uint8 | 8-bit unsigned integer |
| uint16 | 16-bit unsigned integer | | uint16 | 16-bit unsigned integer |
| uint32 | 32-bit unsigned integer | | uint32 | 32-bit unsigned integer |
| uint64 | 64-bit unsigned integer | | uint64 | 64-bit unsigned integer |
| union | Choice of member types | | union | Choice of member types |
+---------------------+-------------------------------------+ +---------------------+-------------------------------------+
The "type" statement is covered in Section 7.4. The "type" statement is covered in Section 7.4.
4.2.5. Derived Types (typedef) 4.2.5. Derived Types (typedef)
skipping to change at page 23, line 34 skipping to change at page 21, line 34
} }
} }
} }
The "grouping" statement is covered in Section 7.11. The "grouping" statement is covered in Section 7.11.
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 which 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".
When an element from one case is created, all elements from all other When an element from one case is created, all elements from all other
cases are implicitly deleted. The device handles the enforcement of cases are implicitly deleted. The device handles the enforcement of
the constraint, preventing incompatibilities from existing in the the constraint, preventing incompatibilities from existing in the
configuration. configuration.
The choice and case nodes appear only in the schema tree, not in the The choice and case nodes appear only in the schema tree, not in the
skipping to change at page 25, line 35 skipping to change at page 23, line 37
<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.15. The "augment" statement is covered in Section 7.15.
4.2.9. RPC Definitions 4.2.9. RPC Definitions
YANG allows the definition of NETCONF RPCs. The operation names, YANG allows the definition of NETCONF RPCs. 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. definition statements.
YANG Example: YANG Example:
rpc activate-software-image { rpc activate-software-image {
input { input {
leaf image-name { leaf image-name {
type string; type string;
} }
} }
skipping to change at page 29, line 14 skipping to change at page 26, line 45
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
for this evolution, modules need to be imported using specific for this evolution, modules need to be imported using specific
revisions. When a module is written, it uses the current revisions revisions. When a module is written, it uses the current revisions
of other modules, based on what is available at the time. As future of other modules, based on what is available at the time. As future
revisions of the imported modules are published, the importing module revisions of the imported modules are published, the importing module
is unaffected and its contents are unchanged. When the author of the is unaffected and its contents are unchanged. When the author of the
module is prepared to move to the most recently published revision of module is prepared to move to the most recently published revision of
an imported module, the module is republished with an updated import an imported module, the module is republished with an updated
statement. By republishing with the new revision, the authors "import" statement. By republishing with the new revision, the
explicitly indicate their acceptance of any changes in the imported authors explicitly indicate their acceptance of any changes in the
module. imported module.
For submodules, the issue is related but simpler. A module or For submodules, the issue is related but simpler. A module or
submodule that includes submodules need to specify the revision of submodule that includes submodules needs to specify the revision of
the included submodules. If a submodule changes, any module or the included submodules. If a submodule changes, any module or
submodule that includes it needs to be updated. submodule that includes it needs to be updated.
For example, module "b" imports module "a". For example, module "b" imports module "a".
module a { module a {
revision 2008-01-01 { ... } revision 2008-01-01 { ... }
grouping a { grouping a {
leaf eh { .... } leaf eh { .... }
} }
skipping to change at page 29, line 47 skipping to change at page 27, line 33
} }
container bee { container bee {
uses p:a; uses p:a;
} }
} }
When the author of "a" publishes a new revision, the changes may not When the author of "a" publishes a new revision, the changes may not
be acceptable to the author of "b". If the new revision is be acceptable to the author of "b". If the new revision is
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.
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. Models that have multiple top- have more than one top-level node. Models that have multiple top-
level nodes are sometimes convenient, and are supported by YANG. level nodes are sometimes convenient, and are supported by YANG.
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.
skipping to change at page 31, line 11 skipping to change at page 29, line 8
YANG compilers can find imported modules and included submodules via YANG compilers can find imported modules and included submodules via
this convention. While the YANG language defines modules, tools may this convention. While the YANG language defines modules, tools may
compile submodules independently for performance and manageability compile submodules independently for performance and manageability
reasons. Errors and warnings that cannot be detected during reasons. Errors and warnings that cannot be detected during
submodule compilation may be delayed until the submodules are linked submodule compilation may be delayed until the submodules are linked
into a cohesive module. into a cohesive module.
5.3. XML Namespaces 5.3. XML Namespaces
All YANG definitions are specified within a module that is bound to a All YANG definitions are specified within a module that is bound to a
particular XML Namespace [XML-NAMES], which is a globally unique URI particular XML namespace [XML-NAMES], which is a globally unique URI
[RFC3986]. A NETCONF client or server uses the namespace during XML [RFC3986]. A NETCONF client or server uses the namespace during XML
encoding of data. encoding of data.
Namespaces for modules published in RFC streams [RFC4844] MUST be Namespaces for modules published in RFC streams [RFC4844] MUST be
assigned by IANA, see Section 14. assigned by IANA, see Section 14.
Namespaces for private modules are assigned by the organization 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 name
skipping to change at page 33, line 26 skipping to change at page 31, line 26
of the model are supported or valid for that particular device. of the model are supported or valid for that particular device.
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 device has local storage. If there is no local possible if the device has local storage. If there is no local
storage, an application should not tell the device to save logs. storage, an application should not tell the device to save logs.
YANG supports this conditional mechanism using a construct called YANG supports this conditional mechanism using a construct called
"feature". Features give the modeler a mechanism for making portions "feature". Features give the modeler a mechanism for making portions
of the module conditional in a manner that is controlled by the of the module conditional in a manner that is controlled by the
device. The model can express constructs which are not universally device. The model can express constructs that are not universally
present in all devices. These features are included in the model present in all devices. These features are included in the model
definition, allowing a consistent view and allowing applications to definition, allowing a consistent view and allowing applications to
learn which features are supported and tailor their behavior to the learn which features are supported and tailor their behavior to the
device. device.
A module may declare any number of features, identified by simple A module may declare any number of features, identified by simple
strings, and may make portions of the module optional based on those strings, and may make portions of the module optional based on those
features. If the device supports a feature, then the corresponding features. If the device supports a feature, then the corresponding
portions of the module are valid for that device. If the device portions of the module are valid for that device. If the device
doesn't support the feature, those parts of the module are not valid, doesn't support the feature, those parts of the module are not valid,
skipping to change at page 34, line 15 skipping to change at page 32, line 17
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 device may only support 16 BGP peers. Any application particular device 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.
Device deviations are declared using the "deviation" statement, which Device deviations are declared using the "deviation" statement, which
takes as its argument a string which 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 details the manner in which the
device implementation deviates from the contract as defined in the device implementation deviates from the contract as defined in the
module. module.
Further details are available in Section 7.18.3. Further details are available in Section 7.18.3.
5.6.4. Announcing Conformance Information in the <hello> Message 5.6.4. Announcing Conformance Information in the <hello> Message
The namespace URI MUST be advertised as a capability in the NETCONF The namespace URI MUST be advertised as a capability in the NETCONF
<hello> message to indicate support for the YANG module by a NETCONF <hello> message to indicate support for the YANG module by a NETCONF
server. The capability URI advertised MUST be on the form: server. The capability URI advertised MUST be of the form:
capability-string = namespace-uri [ parameter-list ] capability-string = namespace-uri [ parameter-list ]
parameter-list = "?" parameter *( "&" parameter ) parameter-list = "?" parameter *( "&" parameter )
parameter = revision-parameter / parameter = revision-parameter /
module-parameter / module-parameter /
feature-parameter / feature-parameter /
deviation-parameter deviation-parameter
revision-parameter = "revision=" revision-date revision-parameter = "revision=" revision-date
module-parameter = "module=" module-name module-parameter = "module=" module-name
feature-parameter = "features=" feature *( "," feature ) feature-parameter = "features=" feature *( "," feature )
skipping to change at page 35, line 16 skipping to change at page 33, line 16
Servers indicate the names of supported modules via the <hello> Servers indicate the names of supported modules via the <hello>
message. Module namespaces are encoded as the base URI in the message. Module namespaces are encoded as the base URI in the
capability string, and the module name is encoded as the "module" capability string, and the module name is encoded as the "module"
parameter to the base URI. parameter to the base URI.
A server MUST advertise all revisions of all modules it implements. A server MUST advertise all revisions of all modules it implements.
For example, this <hello> message advertises one module "syslog". For example, this <hello> message advertises one module "syslog".
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capability> <capability>
http://example.com/syslog?module=syslog&revision=2008-04-01 http://example.com/syslog?module=syslog&amp;revision=2008-04-01
</capability> </capability>
</hello> </hello>
5.6.4.2. Features 5.6.4.2. Features
Servers indicate the names of supported features via the <hello> Servers indicate the names of supported features via the <hello>
message. In hello messages, the features are encoded in the message. In <hello> messages, the features are encoded in the
"features" parameter within the URI. The value of this parameter is "features" parameter within the URI. The value of this parameter is
a comma-separated list of feature names which the device supports for a comma-separated list of feature names that the device supports for
the specific module. the specific module.
For example, this <hello> message advertises one module, informing For example, this <hello> message advertises one module, informing
the client that it supports the "local-storage" feature of module the client that it supports the "local-storage" feature of module
"syslog". "syslog".
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capability>
<capability> http://example.com/syslog?module=syslog&amp;features=local-storage
http://example.com/syslog?module=syslog&features=local-storage </capability>
</capability> </hello>
</hello>
5.6.4.3. Deviations 5.6.4.3. Deviations
Device deviations are announced via the "deviations" parameter. The Device deviations are announced via the "deviations" parameter. The
value of the deviations parameter is a comma-separated list of value of the "deviations" parameter is a comma-separated list of
modules containing deviations from the capability's module. modules containing deviations from the capability's module.
For example, this <hello> message advertises two modules, informing For example, this <hello> message advertises two modules, informing
the client that it deviates from module "syslog" according to the the client that it deviates from module "syslog" according to the
deviations listed in the module "my-devs". deviations listed in the module "my-devs".
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capability> <capability>
http://example.com/syslog?module=syslog&deviations=my-devs http://example.com/syslog?module=syslog&amp;deviations=my-devs
</capability> </capability>
<capability> <capability>
http://example.com/my-deviations?module=my-devs http://example.com/my-deviations?module=my-devs
</capability> </capability>
</hello> </hello>
5.7. Data Store Modification 5.7. Data Store Modification
Data models may allow the server to alter the configuration data Data models may allow the server to alter the configuration data
store in ways not explicitly directed via NETCONF protocol messages. store in ways not explicitly directed via NETCONF protocol messages.
For example, a data model may define leafs that are assigned system- For example, a data model may define leafs that are assigned system-
generated values when the client does not provide one. A formal generated values when the client does not provide one. A formal
mechanism for specifying the circumstances where these changes are mechanism for specifying the circumstances where these changes are
allowed is out of scope for this specification. allowed is out of scope for this specification.
6. YANG syntax 6. YANG Syntax
The YANG syntax is similar to that of SMIng [RFC3780] and programming The YANG syntax is similar to that of SMIng [RFC3780] and programming
languages like C and C++. This C-like syntax was chosen specifically languages like C and C++. This C-like syntax was chosen specifically
for its readability, since YANG values the time and effort of the for its readability, since YANG values the time and effort of the
readers of models above those of modules writers and YANG tool-chain readers of models above those of modules writers and YANG tool-chain
developers. This section introduces the YANG syntax. developers. This section introduces the YANG syntax.
YANG modules use the UTF-8 [RFC3629] character encoding. YANG modules use the UTF-8 [RFC3629] character encoding.
6.1. Lexical Tokenization 6.1. Lexical Tokenization
skipping to change at page 37, line 32 skipping to change at page 34, line 50
models in readable formats. models in readable formats.
6.1.1. Comments 6.1.1. Comments
Comments are C++ style. A single line comment starts with "//" and Comments are C++ style. A single line comment starts with "//" and
ends at the end of the line. A block comment is enclosed within "/*" ends at the end of the line. A block comment is enclosed within "/*"
and "*/". and "*/".
6.1.2. Tokens 6.1.2. Tokens
A token in YANG is either a keyword, a string, ";", "{", or "}". A A token in YANG is either a keyword, a string, a semicolon (";"), or
string can be quoted or unquoted. A keyword is either one of the braces ("{" or "}"). A string can be quoted or unquoted. A keyword
YANG keywords defined in this document, or a prefix identifier, is either one of the YANG keywords defined in this document, or a
followed by ":", followed by a language extension keyword. Keywords prefix identifier, followed by ":", followed by a language extension
are case sensitive. See Section 6.2 for a formal definition of keyword. Keywords are case sensitive. See Section 6.2 for a formal
identifiers. definition of identifiers.
6.1.3. Quoting 6.1.3. Quoting
If a string contains any space or tab characters, a semicolon (";"), If a string contains any space or tab characters, a semicolon (";"),
braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then
it MUST be enclosed within double or single quotes. it MUST be enclosed within double or single quotes.
If the double quoted string contains a line break followed by space If the double-quoted string contains a line break followed by space
or tab characters which are used to indent the text according to the or tab characters that are used to indent the text according to the
layout in the YANG file, this leading whitespace is stripped from the layout in the YANG file, this leading whitespace is stripped from the
string, up to and including the column of the double quote character, string, up to and including the column of the double quote character,
or to the first non-whitespace character, whichever occurs first. In or to the first non-whitespace character, whichever occurs first. In
this process, a tab character is treated as 8 space characters. this process, a tab character is treated as 8 space characters.
If the double quoted string contains space or tab characters before a If the double-quoted string contains space or tab characters before a
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 single within the quotes. A single quote character cannot occur in a
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 special character, which depends on the character introduces a special character, which depends on the
character that immediately follows the backslash: character that immediately follows the backslash:
\n new line \n new line
\t a tab character \t a tab character
\" a double quote \" a double quote
\\ a single backslash \\ a single backslash
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 trimming and substition of backslash-escaped characters in Whitespace trimming and substitution of backslash-escaped characters
double quoted strings is done before concatenation. in double-quoted strings is done before concatenation.
6.1.3.1. Quoting Examples 6.1.3.1. Quoting Examples
The following strings are equivalent: The following strings are equivalent:
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 newline character "\n" - string containing a new line 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:
"first line "first line
second line" second line"
"first line\n" + " second line" "first line\n" + " second line"
6.2. Identifiers 6.2. Identifiers
Identifiers are used to identify different kinds of YANG items by Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an upper-case or lower-case ASCII name. Each identifier starts with an 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. Identifiers are case sensitive. The identifier syntax is length. Identifiers are case sensitive. The identifier syntax is
formally defined by the rule "identifier" in Section 12. Identifiers formally defined by the rule "identifier" in Section 12. Identifiers
can be specified as quoted or unquoted strings. can be specified as quoted or unquoted strings.
6.2.1. Identifiers and their namespaces 6.2.1. Identifiers and Their Namespaces
Each identifier is valid in a namespace which depends on the type of Each identifier is valid in a namespace 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.
o All module and submodule names share the same global module o All module and submodule names share the same global module
identifier namespace. identifier namespace.
o All extension names defined in a module and its submodules share o All extension names defined in a module and its submodules share
the same extension identifier namespace. the same extension identifier namespace.
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 descendent 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 descendent 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, o All leafs, leaf-lists, lists, containers, choices, rpcs,
notifications, and anyxmls defined (directly or through a uses notifications, and anyxmls defined (directly or through a uses
statement) within a parent node or at the top-level of the module statement) within a parent node or at the top level of the module
or its submodules share the same identifier namespace. This or its submodules share the same identifier namespace. This
namespace is scoped to the parent node or module, unless the 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 which 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
skipping to change at page 40, line 40 skipping to change at page 38, line 6
A module can introduce YANG extensions by using the "extension" A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.17). The extensions can be imported by other keyword (see Section 7.17). 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 module's prefix. extension's keyword MUST be qualified with the module's prefix.
Since submodules cannot include the parent module, any extensions in Since submodules cannot include the parent module, any extensions in
the module which need to be exposed to submodules MUST be defined in the module that need to be exposed to submodules MUST be defined in a
a submodule. Submodules can then include this submodule to find the submodule. Submodules can then include this submodule to find the
definition of the extension. definition of the extension.
If a YANG compiler does not support a particular extension, which If a YANG compiler does not support a particular extension, which
appears in a YANG module as an unknown-statement (see Section 12), appears in a YANG module as an unknown-statement (see Section 12),
the entire unknown statement MAY be ignored by the compiler. the entire unknown-statement MAY be ignored by the compiler.
6.4. XPath Evaluations 6.4. XPath Evaluations
YANG relies on XPath 1.0 [XPATH] as a notation for specifying many YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation
inter-node references and dependencies. NETCONF clients and servers for specifying many inter-node references and dependencies. NETCONF
are not required to implement an XPath interpreter, but MUST ensure clients and servers are not required to implement an XPath
that the requirements encoded in the data model are enforced. The interpreter, but MUST ensure that the requirements encoded in the
manner of enforcement is an implementation decision. The XPath data model are enforced. The manner of enforcement is an
expressions MUST be syntactically correct, and all prefixes used MUST implementation decision. The XPath expressions MUST be syntactically
be present in the XPath context (see Section 6.4.1). An correct, and all prefixes used MUST be present in the XPath context
implementation may choose to implement them by hand, rather than (see Section 6.4.1). An implementation may choose to implement them
using the XPath expression directly. by hand, rather than 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 [XSLT] (Section 3.1). Specifically, it means
that the root node may have any number of element nodes as its that the root node may have any number of element nodes as its
children. children.
6.4.1. XPath Context 6.4.1. XPath Context
All YANG XPath expressions share the following XPath context All YANG XPath expressions share the following XPath context
definition: definition:
o The set of namespace declarations is the set of all "import" o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs in the module where the statements' prefix and namespace pairs in the module where the
XPath expression is specified, and the "prefix" statement's prefix XPath expression is specified, and the "prefix" statement's prefix
for the "namespace" statement's URI. for the "namespace" statement's URI.
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.12). Section 7.12).
o The function library is the core function library defined in o The function library is the core function library defined in
[XPATH], and a function "current()" which returns a node set with [XPATH], and a function "current()" that returns a node set with
the initial context node. the initial context node.
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 context node varies with the YANG XPath expression, and is The context node varies with the YANG XPath expression, and is
skipping to change at page 42, line 7 skipping to change at page 39, line 22
defined. defined.
6.5. Schema Node Identifier 6.5. Schema Node Identifier
A schema node identifier is a string that identifies a node in the A schema node identifier is a string that identifies a node in the
schema tree. It has two forms, "absolute" and "descendant", defined schema tree. It has two forms, "absolute" and "descendant", defined
by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid"
in Section 12, respectively. A schema node identifier consists of a in Section 12, respectively. A schema node identifier consists of a
path of identifiers, separated by slashes ("/"). In an absolute path of identifiers, separated by slashes ("/"). In an absolute
schema node identifier, the first identifier after the leading slash schema node identifier, the first identifier after the leading slash
is any top-level schema node in local module or all imported modules. is any top-level schema node in the local module or in all imported
modules.
References to identifiers defined in external modules MUST be References to identifiers defined in external modules MUST be
qualified with appropriate prefixes, and references to identifiers qualified with appropriate prefixes, and references to identifiers
defined in the current module and its submodules MAY use a prefix. defined in the current module and its submodules MAY use a prefix.
For example, to identify the child node "b" of top-level node "a", For example, to identify the child node "b" of top-level node "a",
the string "/a/b" can be used. the string "/a/b" can be used.
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 which 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" {
acme:documentation-flag 5; acme: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 which 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 hold detailed module information. The module
name follows the rules for identifiers in Section 6.2. name follows the rules for identifiers in 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. by IANA, see Section 14.
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. It is RECOMMENDED to choose module without a central registry. It is RECOMMENDED to choose
module names that will have a low probability of colliding with module names that will have a low probability of colliding with
skipping to change at page 45, line 49 skipping to change at page 42, line 7
argument is a string. If present, it MUST contain the value "1", argument is a string. If present, it MUST contain the value "1",
which is the current YANG version and the default value. which is the current YANG version and the default value.
Handling of the "yang-version" statement for versions other than "1" Handling of the "yang-version" statement for versions other than "1"
(the version defined here) is out of scope for this specification. (the version defined here) is out of scope for this specification.
Any document that defines a higher version will need to define the Any document that defines a higher version will need to define the
backward compatibility of such a higher version. backward compatibility of such a higher version.
7.1.3. The namespace Statement 7.1.3. The namespace Statement
The "namespace" statement defines the XML namespace which all The "namespace" statement defines the XML namespace that all
identifiers defined by the module are qualified by, with the identifiers defined by the module are qualified by, with the
exception of data node identifiers defined inside a grouping (see exception of data node identifiers defined inside a grouping (see
Section 7.12 for details). The argument to the "namespace" statement Section 7.12 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 which 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 to refer to definitions contained in the prefix string MAY be used to refer to definitions contained in the
module, e.g., "if:ifName". A prefix follows the same rules as an module, e.g., "if:ifName". A prefix follows the same rules as an
identifier (see Section 6.2). identifier (see Section 6.2).
When used inside the "module" statement, the "prefix" statement When used inside the "module" statement, the "prefix" statement
defines the prefix to be used when this module is imported. To defines the prefix to be used when this module is imported. To
improve readability of the NETCONF XML, a NETCONF client or server improve readability of the NETCONF XML, a NETCONF client or server
which generates XML or XPath that use prefixes SHOULD use the prefix that generates XML or XPath that use prefixes SHOULD use the prefix
defined by the module, unless there is a conflict. defined by the module, unless there is a 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 is used in module is used, the prefix string for the imported module is used in
combination with a colon (":") and the identifier, e.g., "if: combination with a colon (":") and the identifier, e.g., "if:
ifIndex". To improve readability of YANG modules, the prefix defined ifIndex". To improve readability of YANG modules, the prefix defined
by a module SHOULD be used when the module is imported, unless there by a module SHOULD be used when the module is imported, unless there
is a conflict. If there is a conflict, i.e., two different modules is a conflict. If there is a conflict, i.e., two different modules
which both have defined the same prefix are imported, at least one of that both have defined the same prefix are imported, at least one of
them MUST be imported with a different prefix. them 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.
o use any extension, feature, and identity defined in the imported o use any extension, feature, and identity defined in the imported
module or its submodules module or its submodules.
o use any node in the imported module's schema tree in "must", o use any node in the imported module's schema tree in "must",
"path", and "when" statements, or as the target node in an "path", and "when" statements, or as the target node in "augment"
"augment" statement and "deviation" statements.
The mandatory "prefix" substatement assigns a prefix for the imported The mandatory "prefix" substatement assigns a prefix for the imported
module which is scoped to the importing module or submodule. module that is scoped to the importing module or submodule. Multiple
Multiple "import" statements may be specified to import from "import" statements may be specified to import from different
different modules. modules.
When the optional "revision-date" substatement is present, any When the optional "revision-date" substatement is present, any
typedef, grouping, extension, feature, and identity referenced by typedef, grouping, extension, feature, and identity referenced by
definitions in the local module are taken from the specified revision definitions in the local module are taken from the specified revision
of the imported module. It is an error if the specified revision of of the imported module. It is an error if the specified revision of
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 MUST NOT be imported. Multiple revisions of the same module MUST NOT be imported.
skipping to change at page 47, line 43 skipping to change at page 43, line 49
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 exact The import's "revision-date" statement is used to specify the exact
version of the module to import. The "revision-date" statement MUST version of the module to import. The "revision-date" statement MUST
match the most recent "revision" statement in the imported module. match the most recent "revision" statement in the imported module.
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, or to another submodule available to that submodule's parent module, or to another submodule
of that parent module. The argument is an identifier which is the of that parent module. The argument is an identifier that is the
name of the submodule to include. Modules are only allowed to name of the submodule to include. Modules are only allowed to
include submodules that belong to that module, as defined by the include submodules that belong to that module, as defined by the
"belongs-to" statement (see Section 7.2.2). Submodules are only "belongs-to" statement (see Section 7.2.2). Submodules are only
allowed to include other submodules belonging to the same module. allowed to include other submodules belonging to the same module.
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. When a the submodule into the node hierarchy of the module. When a
submodule includes another submodule, the target submodule's submodule includes another submodule, the target submodule's
definitions are made available to the current submodule. definitions are made available to the current submodule.
skipping to change at page 48, line 24 skipping to change at page 44, line 32
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| revision-date | 7.1.5.1 | 0..1 | | revision-date | 7.1.5.1 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
7.1.7. The organization Statement 7.1.7. The organization Statement
The "organization" statement defines the party responsible for this The "organization" statement defines the party responsible for this
module. The argument is a string which is used to specify a textual module. The argument is a string 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 which 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
skipping to change at page 50, line 8 skipping to change at page 46, line 14
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 groups
all statements which 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 hold detailed submodule
information. The submodule name follows the rules for identifiers in information. The submodule name follows the rules for identifiers in
Section 6.2. 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. assigned by IANA, see Section 14.
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. It is RECOMMENDED to choose submodule without a central registry. It is RECOMMENDED to choose
skipping to change at page 51, line 40 skipping to change at page 48, line 40
| revision | 7.1.9 | 0..n | | revision | 7.1.9 | 0..n |
| rpc | 7.13 | 0..n | | rpc | 7.13 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
| yang-version | 7.1.2 | 0..1 | | yang-version | 7.1.2 | 0..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 which is the name submodule belongs. The argument is an identifier that is the name of
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 the module to which it belongs,
or by another submodule which belongs to that module. or by 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 local to which the submodule belongs. All definitions in the local
submodule and any included submodules can be accessed by using the submodule and any included submodules can be accessed by using the
prefix. prefix.
The belongs-to's Substatements The belongs-to's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 52, line 49 skipping to change at page 49, line 49
revision "2007-06-09" { revision "2007-06-09" {
description "Initial revision."; description "Initial revision.";
} }
// definitions follows... // definitions follows...
} }
7.3. The typedef Statement 7.3. The typedef Statement
The "typedef" statement defines a new type which may be used locally The "typedef" statement defines a new type that may be used locally
in the module, in modules or submodules which include it, and by in the module, in modules or submodules which include it, and by
other modules which import from it, according to the rules in other modules that import from it, according to the rules in
Section 5.5. The new type is called the "derived type", and the type Section 5.5. The new type is called the "derived type", and the type
from which it was derived is called the "base type". All derived from which it was derived is called the "base type". All derived
types can be traced back to a YANG built-in type. types can be traced back to a YANG built-in type.
The "typedef" statement's argument is an identifier which 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
skipping to change at page 53, line 37 skipping to change at page 50, line 38
+--------------+---------+-------------+ +--------------+---------+-------------+
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 which 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 which contains The "default" statement takes as an argument a string that contains a
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
skipping to change at page 54, line 19 skipping to change at page 51, line 19
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 which 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 are
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
skipping to change at page 55, line 7 skipping to change at page 52, line 7
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 which 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 configuration has an explicit meaning. the configuration 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. This is the default style. only to contain child nodes. This is the default style.
For example, the set of scrambling options for SONET interfaces may For example, the set of scrambling options for Synchronous Optical
be placed inside a "scrambling" container to enhance the organization Network (SONET) interfaces may be placed inside a "scrambling"
of the configuration hierarchy, and to keep these nodes together. container to enhance the organization of the configuration hierarchy,
The "scrambling" node itself has no meaning, so removing the node and to keep these nodes together. The "scrambling" node itself has
when it becomes empty relieves the user from performing this task. no meaning, so removing the node when it becomes empty relieves the
user from performing this task.
In the second style, the presence of the container itself is In the second style, the presence of the container itself is
configuration data, representing a single bit of configuration data. configuration data, representing a single bit of configuration data.
The container acts as both a configuration knob and a means of The container acts as both a configuration knob and a means of
organizing related configuration. These containers are explicitly organizing related configuration. These containers are explicitly
created and deleted. 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.
skipping to change at page 56, line 32 skipping to change at page 53, line 32
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 | | when | 7.19.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 which 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 data node in the data tree, and conceptually evaluated once for each data node in the data tree, and
for all leafs with default values in use (see Section 7.6.1). If a for all leafs with default values in use (see Section 7.6.1). If a
data node does not exist in the data tree, and it does not have a data node does not exist in the data tree, and it does not have a
default value, its "must" statements are not evaluated. default value, its "must" statements are not evaluated.
All such constraints MUST evaluate to true for the data to be valid. All such constraints MUST evaluate to true for the data to be valid.
skipping to change at page 57, line 34 skipping to change at page 54, line 34
child. child.
o If the context node represents RPC output parameters, the tree is o If the context node represents RPC output parameters, the tree is
the RPC reply instance document. The XPath root node has the the RPC reply instance document. The XPath root node has the
elements representing the RPC output parameters as children. elements representing the RPC output parameters as children.
The result of the XPath expression is converted to a boolean value The result of the XPath expression is converted to a boolean value
using the standard XPath rules. using the standard XPath rules.
Note that since all leaf values in the data tree are conceptually Note that since all leaf values in the data tree are conceptually
stored in their canonical form (see Section 7.6 and Section 7.7), any stored in their canonical form (see Sections 7.6 and 7.7), any XPath
XPath comparisons are done on the canonical value. comparisons are done on the canonical value.
Also note that the XPath expression is conceptually evaluated. This Also note that the XPath expression is conceptually evaluated. This
means that an implementation does not have to use an XPath evaluator means that an implementation does not have to use an XPath evaluator
on the device. How the evaluation is done in practice is an on the device. How the evaluation is done in practice is an
implementation decision. implementation decision.
7.5.4. The must's Substatements 7.5.4. The must's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 59, line 8 skipping to change at page 56, line 8
} }
must "ifType != 'atm' or " + must "ifType != 'atm' or " +
"(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" { "(ifType = 'atm' and 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 which 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.
See Section 7.5.1 for additional information. See Section 7.5.1 for additional information.
7.5.6. The container's Child Node Statements 7.5.6. The container's Child Node Statements
skipping to change at page 59, line 33 skipping to change at page 56, line 33
7.5.7. XML Mapping Rules 7.5.7. XML Mapping Rules
A container node is encoded as an XML element. The element's local A container node is encoded as an XML element. The element's local
name is the container's identifier, and its namespace is the module's name is the container's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). XML namespace (see Section 7.1.3).
The container's child nodes are encoded as subelements to the The container's child nodes are encoded as subelements to the
container element. If the container defines RPC input or output container element. If the container defines RPC input or output
parameters, these subelements are encoded in the same order as they parameters, these subelements are encoded in the same order as they
are defined within the container statement. Otherwise, the are defined within the "container" statement. Otherwise, the
subelements are encoded in any order. subelements are encoded in any order.
A NETCONF server that replies to a <get> or <get-config> request MAY A NETCONF server that replies to a <get> or <get-config> request MAY
choose not to send a container element if the container node does not choose not to send a container element if the container node does not
have the "presence" statement and no child nodes exist. Thus, a have the "presence" statement and no child nodes exist. Thus, a
client that receives an <rpc-reply> for a <get> or <get-config> client that receives an <rpc-reply> for a <get> or <get-config>
request, must be prepared to handle the case that a container node request, must be prepared to handle the case that a container node
without a presence statement is not present in the XML. without a "presence" statement is not present in the XML.
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 [RFC4741], <edit-config>, by using the "operation" attribute (see [RFC4741],
section 7.2) in the container's XML element. Section 7.2) 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:
If the operation is "merge" or "replace", the node is created if 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 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. If If the operation is "delete", the node is deleted if it exists.
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 "Contains various system parameters"; description "Contains various system parameters";
container services { container services {
description "Configure externally available services"; description "Configure externally available services";
container "ssh" { container "ssh" {
skipping to change at page 61, line 32 skipping to change at page 58, line 32
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 instances in the data tree.
depending on the value of the "mandatory" statement.
The "leaf" statement is used to define a scalar variable of a 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 which depends on the leaf's closest ancestor node in the schema tree that
is not a non-presence container: is not a non-presence container:
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 if
the case node is the choice's default case, and no nodes from any the case node is the choice's default case, and no nodes from any
other case exist in the data tree. other case exist in the data tree.
skipping to change at page 62, line 48 skipping to change at page 59, line 48
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 which 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.
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 not specified, the default is "false". If 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 which 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.
o Otherwise, the leaf MUST exist if the ancestor node exists in the o Otherwise, the leaf MUST exist if the ancestor node exists in the
data tree. data tree.
skipping to change at page 64, line 9 skipping to change at page 61, line 9
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:
If the operation is "merge" or "replace", the node is created if 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 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. If If the operation is "delete", the node is deleted if it exists.
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 defined Given the following "leaf" statement, placed in the previously
"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 "The port which the SSH server listens to" description "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 65, line 49 skipping to change at page 62, line 49
indicated with the statement "ordered-by user". indicated with the statement "ordered-by user".
For example, the order in which firewall filters entries are applied For example, the order in which firewall filters entries are applied
to incoming traffic may affect how that traffic is filtered. The to incoming traffic may affect how that traffic is filtered. The
user would need to decide if the filter entry that discards all TCP user 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 which allow 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.5. The "ordered-by" statement is covered in Section 7.7.5.
7.7.2. The leaf-list's Substatements 7.7.2. The leaf-list's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 66, line 29 skipping to change at page 63, line 29
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.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.19.5 | 0..1 | | when | 7.19.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.7.3. The min-elements Statement 7.7.3. 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 which 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 which is not a or list's closest ancestor node in the schema tree that is not a non-
non-presence container (see Section 7.5.1): presence container (see Section 7.5.1):
o If this ancestor is a case node, the constraint is enforced if any o If this ancestor is a case node, the constraint is enforced if any
other node from the case exists. 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.4. The max-elements Statement 7.7.4. The max-elements Statement
skipping to change at page 67, line 26 skipping to change at page 64, line 26
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.5.1. ordered-by system 7.7.5.1. ordered-by system
The entries in the list are sorted according to an unspecified order. The entries in the list are sorted according to an unspecified order.
Thus an implementation is free to sort the entries in the most Thus, an implementation is free to sort the entries in the most
appropriate order. An implementation SHOULD use the same order for appropriate order. An implementation SHOULD use the same order for
the same data, regardless of how the data were created. Using a the same data, regardless of how the data were created. Using a
deterministic order will make comparisons possible using simple tools deterministic order will make comparisons possible using simple tools
like "diff". like "diff".
This is the default order. This is the default order.
7.7.5.2. ordered-by user 7.7.5.2. ordered-by user
The entries in the list are sorted according to an order defined by The entries in the list are sorted according to an order defined by
skipping to change at page 67, line 50 skipping to change at page 64, line 50
7.7.6. XML Mapping Rules 7.7.6. XML Mapping 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 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 other sibling representing leaf-list entries MAY be interleaved with other sibling
elements, unless the leaf-list defines RPC input or output elements, unless the leaf-list defines RPC input or output
parameters. parameters.
See Section 7.7.8 for an example. See Section 7.7.8 for an example.
7.7.7. NETCONF <edit-config> Operations 7.7.7. 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 68, line 35 skipping to change at page 65, line 36
list. 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 the
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 an <edit-config> with a "replace" operation
which 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:
If the operation is "merge" or "replace" the leaf-list entry is 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 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- If the operation is "delete", the entry is deleted from the leaf-
list if it exists. If the leaf-list entry does not exist, a 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.8. Usage Example 7.7.8. Usage Example
leaf-list allow-user { leaf-list allow-user {
type string; type string;
description "A list of user name patterns to allow"; description "A list of user name patterns to allow";
} }
skipping to change at page 70, line 32 skipping to change at page 67, line 32
</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.
7.8.1. The list's Substatements 7.8.1. The list's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 71, line 37 skipping to change at page 68, line 37
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| unique | 7.8.3 | 0..n | | unique | 7.8.3 | 0..n |
| uses | 7.12 | 0..n | | uses | 7.12 | 0..n |
| when | 7.19.5 | 0..1 | | when | 7.19.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 which specifies a space separated list of leaf identifiers of string that specifies a space-separated list of leaf identifiers of
this list. A leaf identifier MUST NOT appear more than once in the this list. A leaf identifier MUST NOT appear more than once in the
key. Each such leaf identifier MUST refer to a child leaf of the key. Each such leaf identifier MUST refer to a child leaf of the
list. The leafs can be defined directly in substatements to the list. The leafs can be defined directly in substatements to the
list, or in groupings used in the list. 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. It also implies that any mandatory
statement in the key leafs are ignored. statement in the key leafs are ignored.
skipping to change at page 72, line 12 skipping to change at page 69, line 14
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 12. Section 12.
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 which 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 12). Each such schema node identifier MUST refer to a leaf. Section 12). 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.
The "unique" constraint specifies that the combined values of all the The "unique" constraint specifies that the combined values of all the
leaf instances specified in the argument string, including leafs with leaf instances specified in the argument string, including leafs with
default values, MUST be unique within all list entry instances in default values, MUST be unique within all list entry instances in
skipping to change at page 73, line 51 skipping to change at page 71, line 7
to the list. to the list.
7.8.5. XML Mapping Rules 7.8.5. XML Mapping Rules
A list is encoded as a series of XML elements, one for each entry in A list is encoded as a series of XML elements, one for each entry in
the list. Each element's local name is the list's identifier, and the list. Each element's local name is the list's identifier, and
its namespace is the module's XML namespace (see Section 7.1.3). its namespace is the module's XML namespace (see Section 7.1.3).
The list's key nodes are encoded as subelements to the list's The list's key nodes are encoded as subelements to the list's
identifier element, in the same order as they are defined within the identifier element, in the same order as they are defined within the
key statement. "key" statement.
The rest of the list's child nodes are encoded as subelements to the The rest of the list's child nodes are encoded as subelements to the
list element, after the keys. If the list defines RPC input or list element, after the keys. If the list defines RPC input or
output parameters, the subelements are encoded in the same order as output parameters, the subelements are encoded in the same order as
they are defined within the list statement. Otherwise, the they are defined within the "list" statement. Otherwise, the
subelements are encoded in any order. subelements are encoded in any order.
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 the
order is implementation-dependent. The XML elements representing order is implementation-dependent. The XML elements representing
list entries MAY be interleaved with other sibling elements, unless list entries MAY be interleaved with other sibling elements, unless
the list defines RPC input or output parameters. the list defines RPC input or output 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.
skipping to change at page 74, line 45 skipping to change at page 71, line 49
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 the 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 an <edit-config> with a "replace" operation
which 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:
If the operation is "merge" or "replace", the list entry is 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 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 if If the operation is "delete", the entry is deleted from the list
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;
description "This is a list of users in the system."; description "This is a list of users in the system.";
skipping to change at page 82, line 32 skipping to change at page 79, line 32
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.9.5. XML Mapping Rules 7.9.5. XML Mapping Rules
The choice and case nodes are not visible in XML. The choice and case nodes are not visible in XML.
The child nodes of the selected "case" statement MUST be encoded in The child nodes of the selected "case" statement MUST be encoded in
the same order as they are defined in the "case" statement if they the same order as they are defined in the "case" statement if they
are part of a RPC input or output parameter definition. Otherwise, are part of an RPC input or output parameter definition. Otherwise,
the subelements are encoded in any order. the subelements are encoded in any order.
7.9.6. NETCONF <edit-config> Operations 7.9.6. NETCONF <edit-config> Operations
Since only one of the choice's cases can be valid at any time, the Since only one of the choice's cases can be valid at any time, the
creation of a node from one case implicitly deletes all nodes from creation of a node from one case implicitly deletes all nodes from
all other cases. If an <edit-config> operation creates a node from a all other cases. If an <edit-config> operation creates a node from a
case, the NETCONF server will delete any existing nodes that are case, the NETCONF server will delete any existing nodes that are
defined in other cases inside the choice. defined in other cases inside the choice.
skipping to change at page 83, line 51 skipping to change at page 81, line 5
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.10. The anyxml Statement 7.10. The anyxml Statement
The "anyxml" statement defines an interior node in the schema tree. The "anyxml" statement defines an interior node in the schema tree.
It takes one argument, which is an identifier, followed by a block of It takes one argument, which is an identifier, followed by a block of
substatements that holds detailed anyxml information. substatements that holds detailed anyxml information.
The anyxml statement is used to represent an unknown chunk of XML. The "anyxml" statement is used to represent an unknown chunk of XML.
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. <get-config> operation.
An anyxml node cannot be augmented (see Section 7.15). An anyxml node cannot be augmented (see Section 7.15).
Since the use of anyxml limits the manipulation of the content, it is Since the use of anyxml limits the manipulation of the content, it is
RECOMMENDED that the anyxml statement not be used to represent RECOMMENDED that the "anyxml" statement not be used to represent
configuration data. configuration data.
An anyxml node exists in zero or one instances in the data tree. An anyxml node exists in zero or one instances in the data tree.
7.10.1. The anyxml's Substatements 7.10.1. The anyxml's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
skipping to change at page 85, line 9 skipping to change at page 82, line 12
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:
If the operation is "merge" or "replace", the node is created if 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 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. If If the operation is "delete", the node is deleted if it exists.
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 anyxml statement: Given the following "anyxml" statement:
anyxml data; anyxml data;
The following are two valid encodings of the same anyxml value: The following are two valid encodings of the same anyxml value:
<data xmlns:if="http://example.com/ns/interface"> <data xmlns:if="http://example.com/ns/interface">
<if:interface> <if:interface>
<if:ifIndex>1</if:ifIndex> <if:ifIndex>1</if:ifIndex>
</if:interface> </if:interface>
</data> </data>
<data> <data>
<interface xmlns="http://example.com/ns/interface"> <interface xmlns="http://example.com/ns/interface">
<ifIndex>1</ifIndex> <ifIndex>1</ifIndex>
</interface> </interface>
</data> </data>
7.11. The grouping Statement 7.11. 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, in modules which include it, which may be used locally in the module, in modules that include it,
and by other modules which import from it, according to the rules in and by other modules that import from it, according to the rules in
Section 5.5. It takes one argument which is an identifier, followed Section 5.5. It takes one argument, which is an identifier, followed
by a block of substatements that holds detailed grouping information. by a block of 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.
A grouping is like a "structure" or a "record" in conventional A grouping is like a "structure" or a "record" in conventional
programming languages. programming languages.
Once a grouping is defined, it can be referenced in a "uses" Once a grouping is defined, it can be referenced in a "uses"
statement (see Section 7.12). A grouping MUST NOT reference itself, statement (see Section 7.12). 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 but defines a collection of nodes. Identifiers appearing inside the
grouping are resolved relative to the scope in which the grouping is grouping are resolved relative to the scope in which the grouping is
defined, not where it is used. Prefix mappings, type names, grouping defined, not where it is used. Prefix mappings, type names, grouping
names, and extension usage are evaluated in the hierarchy where the names, and extension usage are evaluated in the hierarchy where the
grouping statement appears. For extensions, this means that "grouping" statement appears. For extensions, this means that
extensions are applied to the grouping node, not the uses node. extensions are applied to the grouping node, not the uses node.
7.11.1. The grouping's Substatements 7.11.1. The grouping's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
skipping to change at page 87, line 28 skipping to change at page 84, line 28
} }
} }
7.12. The uses Statement 7.12. 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 refinement and augment statements. 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.12.1. The uses's Substatements 7.12.1. The uses's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
skipping to change at page 88, line 22 skipping to change at page 85, line 22
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| refine | 7.12.2 | 0..1 | | refine | 7.12.2 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
| when | 7.19.5 | 0..1 | | when | 7.19.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.12.2. The refine Statement 7.12.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 which 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 exactly node of a "refine" statement, it is not refined, and thus used
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.
o Any node may get a specialized "description" string. o Any node may get a specialized "description" string.
skipping to change at page 91, line 39 skipping to change at page 88, line 39
If a leaf in the input tree has a default value, the NETCONF server If a leaf in the input tree has a default value, the NETCONF server
MUST use this value in the same cases as described in Section 7.6.1. MUST use this value in the same cases as described in Section 7.6.1.
In these cases, the server MUST operationally behave as if the leaf In these cases, the server MUST operationally behave as if the leaf
was present in the NETCONF RPC invocation with the default value as was present in the NETCONF RPC invocation with the default value as
its value. its value.
If a "config" statement is present for any node in the input tree, If a "config" statement is present for any node in the input tree,
the "config" statement is ignored. the "config" statement is ignored.
If any node has a "when" statement which would evaluate to false, If any node has a "when" statement that would evaluate to false, then
then this node MUST NOT be present in the input tree. this node MUST NOT be present in the input tree.
7.13.2.1. The input's Substatements 7.13.2.1. The input's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
skipping to change at page 92, line 39 skipping to change at page 89, line 39
If a leaf in the output tree has a default value, the NETCONF client If a leaf in the output tree has a default value, the NETCONF client
MUST use this value in the same cases as described in Section 7.6.1. MUST use this value in the same cases as described in Section 7.6.1.
In these cases, the client MUST operationally behave as if the leaf In these cases, the client MUST operationally behave as if the leaf
was present in the NETCONF RPC reply with the default value as its was present in the NETCONF RPC reply with the default value as its
value. value.
If a "config" statement is present for any node in the output tree, If a "config" statement is present for any node in the output tree,
the "config" statement is ignored. the "config" statement is ignored.
If any node has a "when" statement which would evaluate to false, If any node has a "when" statement that would evaluate to false, then
then this node MUST NOT be present in the output tree. this node MUST NOT be present in the output tree.
7.13.3.1. The output's Substatements 7.13.3.1. The output's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
skipping to change at page 93, line 29 skipping to change at page 90, line 29
+--------------+---------+-------------+ +--------------+---------+-------------+
7.13.4. XML Mapping Rules 7.13.4. XML Mapping Rules
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
defined in [RFC4741]. The element's local name is the rpc's defined in [RFC4741]. The element's local name is the rpc's
identifier, and its namespace is the module's XML namespace (see identifier, and its namespace is the module's XML namespace (see
Section 7.1.3). 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 [RFC4741]. If output parameters are returned, they are encoded as in [RFC4741]. If output parameters are returned, they are encoded as
child elements to the <rpc-reply> element defined in [RFC4741], in child elements to the <rpc-reply> element defined in [RFC4741], in
the same order as they are defined within the output statement. the same order as they are defined within the "output" statement.
7.13.5. Usage Example 7.13.5. Usage Example
The following example defines an RPC operation: The following example defines an RPC operation:
module rock { module rock {
namespace "http://example.net/rock"; namespace "http://example.net/rock";
prefix "rock"; prefix "rock";
rpc rock-the-house { rpc rock-the-house {
skipping to change at page 96, line 24 skipping to change at page 93, line 44
</reporting-entity> </reporting-entity>
<severity>major</severity> <severity>major</severity>
</event> </event>
</notification> </notification>
7.15. The augment Statement 7.15. The augment Statement
The "augment" statement allows a module or submodule to add to the The "augment" statement allows a module or submodule to add to the
schema tree defined in an external module, or the current module and schema tree defined in an external module, or the current module and
its submodules, and to add to the nodes from a grouping in a "uses" its submodules, and to add to the nodes from a grouping in a "uses"
statement. The argument is a string which identifies a node in the statement. The argument is a string that identifies a node in the
schema tree. This node is called the augment's target node. 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.
The argument string is a schema node identifier (see Section 6.5). The argument string is a schema node identifier (see Section 6.5).
If the "augment" statement is on the top-level in a module or If the "augment" statement is on the top level in a module or
submodule, the absolute form (defined by the rule submodule, the absolute form (defined by the rule
"absolute-schema-nodeid" in Section 12) of a schema node identifier "absolute-schema-nodeid" in Section 12) of a schema node identifier
MUST be used. If the "augment" statement is a substatement to the MUST be used. If the "augment" statement is a substatement to the
"uses" statement, the descendant form (defined by the rule "uses" statement, the descendant form (defined by the rule
"descendant-schema-nodeid" in Section 12) MUST be used. "descendant-schema-nodeid" in Section 12) 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 choice node, the "case" statement, or a case If the target node is a choice node, the "case" statement, or a case
shorthand statement (see Section 7.9.2) can be used within the shorthand statement (see Section 7.9.2) can be used within the
"augment" statement. "augment" statement.
If the target node is in another module, then nodes added by the If the target node is in another module, then nodes added by the
augmentation MUST NOT be mandatory nodes (see Section 3.1). augmentation MUST NOT be mandatory nodes (see Section 3.1).
The augment statement MUST NOT add multiple nodes with the same name The "augment" statement MUST NOT add multiple nodes with the same
from the same module to the target node. name from the same module to the target node.
7.15.1. The augment's Substatements 7.15.1. The augment's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| case | 7.9.2 | 0..n | | case | 7.9.2 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
skipping to change at page 98, line 24 skipping to change at page 95, line 28
} }
leaf ifType { leaf ifType {
type iana:IfType; type iana:IfType;
} }
leaf ifMtu { leaf ifMtu {
type int32; type int32;
} }
} }
} }
Then in namespace http://example.com/schema/ds0, we have: Then, in namespace http://example.com/schema/ds0, we have:
import interface-module { import interface-module {
prefix "if"; prefix "if";
} }
augment "/if:interfaces/if:ifEntry" { augment "/if:interfaces/if:ifEntry" {
when "if:ifType='ds0'"; when "if:ifType='ds0'";
leaf ds0ChannelNumber { leaf ds0ChannelNumber {
type ChannelNumber; type ChannelNumber;
} }
} }
skipping to change at page 99, line 36 skipping to change at page 97, line 8
<ex:system> <ex:system>
<ex:protocol> <ex:protocol>
<other:smtp/> <other:smtp/>
</ex:protocol> </ex:protocol>
</ex:system> </ex:system>
7.16. The identity Statement 7.16. 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. Its only purpose is to denote its abstract, and untyped identity. Its only purpose is to denote its
name, semantics, and existence. An identity can be defined either name, semantics, and existence. An identity can either be defined
from scratch or derived from a base identity. The identity's from scratch or derived from a base identity. The identity's
argument is an identifier that is the name of the identity. It is argument is an identifier that is the name of the identity. It is
followed by a block of substatements that holds detailed identity followed by a block of substatements that holds detailed identity
information. 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.16.1. The identity's Substatements 7.16.1. The identity's Substatements
skipping to change at page 100, line 18 skipping to change at page 97, line 31
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| base | 7.16.2 | 0..1 | | base | 7.16.2 | 0..1 |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.16.2. The base Statement 7.16.2. The base Statement
The base statement, which is optional, takes as an argument a string The "base" statement, which is optional, takes as an argument a
which 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. is defined from scratch.
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 which 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.
Otherwise an identity with the matching name MUST be defined in the Otherwise, an identity with the matching name MUST be defined in the
current module or an included submodule. current module or an included submodule.
Since submodules cannot include the parent module, any identities in Since submodules cannot include the parent module, any identities in
the module which need to be exposed to submodules MUST be defined in the module that need to be exposed to submodules MUST be defined in a
a submodule. Submodules can then include this submodule to find the submodule. Submodules can then include this submodule to find the
definition of the identity. definition of the identity.
An identity MUST NOT reference itself, neither directly nor An identity MUST NOT reference itself, neither directly nor
indirectly through a chain of other identities. indirectly through a chain of other identities.
7.16.3. Usage Example 7.16.3. Usage Example
module crypto-base { module crypto-base {
namespace "http://example.com/crypto-base"; namespace "http://example.com/crypto-base";
prefix "crypto"; prefix "crypto";
skipping to change at page 101, line 45 skipping to change at page 98, line 45
} }
7.17. The extension Statement 7.17. 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 statement's argument is an identifier that is the new keyword for The statement's argument is an identifier that is the new keyword for
the extension and must be followed by a block of substatements that the extension and must be followed by a block of substatements that
holds detailed extension information. The purpose of the extension holds detailed extension information. The purpose of the "extension"
statement is to define a keyword, so that it can be imported and used statement is to define a keyword, so that it can be imported and used
by other modules. by other modules.
The extension can be used like a normal YANG statement, with the The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the statement name followed by an argument if one is defined by the
extension, and an optional block of substatements. The statement's extension, and an optional block of substatements. The statement's
name is created by combining the prefix of the module in which the name is created by combining the prefix of the module in which the
extension was defined, a colon (":"), and the extension's keyword, extension was defined, a colon (":"), and the extension's keyword,
with no interleaving whitespace. The substatements of an extension with no interleaving whitespace. The substatements of an extension
are defined by the extension, using some mechanism outside the scope are defined by the extension, using some mechanism outside the scope
skipping to change at page 102, line 26 skipping to change at page 99, line 26
+--------------+---------+-------------+ +--------------+---------+-------------+
| argument | 7.17.2 | 0..1 | | argument | 7.17.2 | 0..1 |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.17.2. The argument Statement 7.17.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 which 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 text an XML attribute or element name, depending on the argument's "yin-
statement. element" statement.
7.17.2.1. The argument's Substatements 7.17.2.1. The argument's Substatements
+--------------+----------+-------------+ +--------------+----------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| yin-element | 7.17.2.2 | 0..1 | | yin-element | 7.17.2.2 | 0..1 |
+--------------+----------+-------------+ +--------------+----------+-------------+
7.17.2.2. The yin-element Statement 7.17.2.2. The yin-element Statement
The "yin-element" statement, which is optional, takes as an argument The "yin-element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the the string "true" or "false". This statement indicates if the
argument 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 11). (see Section 11).
If no "yin-element" statement is present, it defaults to "false". If no "yin-element" statement is present, it defaults to "false".
7.17.3. Usage Example 7.17.3. Usage Example
To define an extension: To define an extension:
module my-extensions { module my-extensions {
... ...
skipping to change at page 103, line 36 skipping to change at page 100, line 36
prefix "myext"; prefix "myext";
} }
... ...
container interfaces { container interfaces {
... ...
myext:c-define "MY_INTERFACES"; myext:c-define "MY_INTERFACES";
} }
} }
7.18. Conformance-related Statements 7.18. 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.18.1. The feature Statement 7.18.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.18.2). Schema nodes tagged with a feature are ignored (see Section 7.18.2). Schema nodes tagged with a feature are ignored
skipping to change at page 105, line 22 skipping to change at page 102, line 22
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.18.2. The if-feature Statement 7.18.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 the name of a feature, as defined by a "feature" The argument is the name of a feature, as defined by a "feature"
statement. The parent statement is implemented by servers that statement. The parent statement is implemented by servers that
support this feature. If a prefix is present on the feature name, it support this feature. If a prefix is present on the feature name, it
refers to a feature defined in the module which was imported with refers to a feature defined in the module that was imported with that
that prefix, or the local module if the prefix matches the local prefix, or the local module if the prefix matches the local module's
module's prefix. Otherwise a feature with the matching name MUST be prefix. Otherwise, a feature with the matching name MUST be defined
defined in the current module or an included submodule. in the current module or an included submodule.
Since submodules cannot include the parent module, any features in Since submodules cannot include the parent module, any features in
the module which need to be exposed to submodules MUST be defined in the module that need to be exposed to submodules MUST be defined in a
a submodule. Submodules can then include this submodule to find the submodule. Submodules can then include this submodule to find the
definition of the feature. definition of the feature.
7.18.3. The deviation Statement 7.18.3. The deviation Statement
The deviation statement defines a hierarchy of a module which the The "deviation" statement defines a hierarchy of a module that the
device does not implement faithfully. The argument is a string that device 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 deviation. contents of the "deviation" statement give details about the
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).
Deviations define the way a device or class of devices deviate from a Deviations define the way a device or class of devices deviate from a
standard. This means that deviations MUST never be part of a standard. This means that deviations MUST never be part of a
published standard, since they are the mechanism for learning how published standard, since they are the mechanism for learning how
implementations vary from the standards. implementations vary from the standards.
Device deviations are strongly discouraged and MUST only be used as a Device deviations are strongly discouraged and MUST only be used as a
last resort. Telling the application how a device fails to follow a last resort. Telling the application how a device fails to follow a
standard is no substitute for implementing the standard correctly. A standard is no substitute for implementing the standard correctly. A
device that deviates from a module is not fully compliant with the device 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 device makes a choice to treat attempts to configure occurs, the device makes a choice either to treat attempts to
unsupported parts of the module as either an error that is reported configure unsupported parts of the module as an error that is
back to the unsuspecting application, or ignore those incoming reported back to the unsuspecting application or ignore those
requests. Neither choice is acceptable. incoming requests. Neither choice is acceptable.
Instead, YANG allows devices to document portions of a base module Instead, YANG allows devices to document portions of a base module
which are not supported or supported but with different syntax, by that are not supported or supported but with different syntax, by
using the "deviation" statement. using the "deviation" statement.
7.18.3.1. The deviation's Substatements 7.18.3.1. The deviation's Substatements
+--------------+----------+-------------+ +--------------+----------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| deviate | 7.18.3.2 | 1..n | | deviate | 7.18.3.2 | 1..n |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
skipping to change at page 106, line 36 skipping to change at page 103, line 42
7.18.3.2. The deviate Statement 7.18.3.2. The deviate Statement
The "deviate" statement defines how the device's implementation of The "deviate" statement defines how the device'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 device. implemented by this device.
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 as a substatement to the "deviate" properties to add are identified by substatements to the "deviate"
statement. If the property can only appear once, the property MUST statement. If a property can only appear once, the property MUST NOT
NOT exist in the target node. exist in the target node.
The argument "replace" replaces properties of the target node. The The argument "replace" replaces properties of the target node. The
properties to replace are identified by substatements to the properties to replace are identified by substatements to the
"deviate" statement. The property 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 substatement 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.
The deviates's Substatements The deviates's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
skipping to change at page 107, line 24 skipping to change at page 104, line 30
| min-elements | 7.7.3 | 0..1 | | min-elements | 7.7.3 | 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 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.18.3.3. Usage Example 7.18.3.3. Usage Example
In this example, the device is informing client applications that it In this example, the device is informing client applications that it
does not support the old RFC867-style "daytime" service. does not support the "daytime" service in the style of RFC 867.
deviation /base:system/base:daytime { deviation /base:system/base:daytime {
deviate not-supported; deviate not-supported;
} }
The following example sets a device-specific default value to a leaf The following example sets a device-specific default value to a leaf
that does not have a default value defined: that does not have a default value defined:
deviation /base:system/base:user/base:type { deviation /base:system/base:user/base:type {
deviate add { deviate add {
skipping to change at page 108, line 15 skipping to change at page 105, line 22
a device might remove this must constraint by doing: a device 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.19. Common Statements 7.19. Common Statements
This section defines sub-statements common to several other This section defines substatements common to several other
statements. statements.
7.19.1. The config Statement 7.19.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 will be part of configuration. Data nodes representing configuration will be part of
the reply to a <get-config> request, and can be sent in a the reply to a <get-config> request, and can be sent in a
<copy-config> or <edit-config> request. <copy-config> or <edit-config> request.
skipping to change at page 108, line 38 skipping to change at page 105, line 45
but not to a <get-config> request, and cannot be sent in a but not to a <get-config> request, and cannot be sent in a
<copy-config> or <edit-config> request. <copy-config> or <edit-config> request.
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 value is the same as the "case" node's parent "choice" node. the 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" "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.19.2. The status Statement 7.19.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 new/
skipping to change at page 109, line 30 skipping to change at page 106, line 36
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.19.3. The description Statement 7.19.3. The description Statement
The "description" statement takes as an argument a string which The "description" statement takes as an argument a string that
contains a high-level 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
module developer; for the sake of interoperability, it is RECOMMENDED
to choose a language that is widely understood among the community of
network administrators who will use the module.
7.19.4. The reference Statement 7.19.4. The reference Statement
The "reference" statement takes as an argument a string which is used The "reference" statement takes as an argument a string that is used
to specify a textual cross-reference to an external document, either to specify a textual cross-reference to an external document, either
another module which defines related management information, or a another module that defines related management information, or a
document which 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.19.5. The when Statement 7.19.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.
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 which is also a data the closest ancestor node to the target node that is also a data
node. node.
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 which is also a data node to the "uses", "choice", or "case" node that is also a data
node. node.
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 context node is the data definition's node in the statement, the context node is the data definition's node in the
data tree. data tree.
o The accessible tree is made up of all nodes in the data tree, and o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values in use (see Section 7.6.1). all leafs with default values in use (see Section 7.6.1).
The accessible tree depends on the context node: The accessible tree depends on the context node:
skipping to change at page 112, line 36 skipping to change at page 109, line 22
true in the RPC reply. true in the RPC reply.
8.2. Hierarchy of Constraints 8.2. Hierarchy of Constraints
Conditions on parent nodes affect constraints on child nodes as a Conditions on parent nodes affect constraints on child nodes as a
natural consequence of the hierarchy of nodes. "must", "mandatory", natural consequence of the hierarchy of nodes. "must", "mandatory",
"min-elements", and "max-elements" constraints are not enforced if "min-elements", and "max-elements" constraints are not enforced if
the parent node has a "when" or "if-feature" property that is not the parent node has a "when" or "if-feature" property that is not
satisfied on the current device. satisfied on the current device.
In this example, the mandatory constraints on the "longitude" leaf is In this example, the "mandatory" constraint on the "longitude" leaf
not enforced on devices that lack the "has-gps" feature: are not enforced on devices that lack the "has-gps" feature:
container location { container location {
if-feature has-gps; if-feature has-gps;
leaf longitude { leaf longitude {
mandatory true; mandatory true;
... ...
} }
} }
8.3. Constraint Enforcement Model 8.3. 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:
o during parsing of RPC payloads o during parsing of RPC payloads
o during processing of NETCONF operations o during processing of NETCONF operations
o during validation o during validation
Each of these scenarios are considered in the following sections. Each of these scenarios is considered in the following sections.
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 device implements. models the device 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 "invalid-value" "pattern" properties, the server MUST reply with an
error-tag in the rpc-error, and with the error-app-tag and error- "invalid-value" error-tag in the rpc-error, and with the error-
message associated with the constraint, if any exist. app-tag and error-message 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" 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
feature is not supported by the device, the server MUST reply with feature is not supported by the device, the server MUST reply with
an "unknown-element" error-tag in the rpc-error. an "unknown-element" error-tag in the rpc-error.
skipping to change at page 113, line 52 skipping to change at page 110, line 39
error. error.
o If the attributes "before" and "after" appears in any element that o If the attributes "before" and "after" appears 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 which do not o Insert requests with "before" or "after" parameters that do not
exist. exist.
During <edit-config> processing: During <edit-config> processing:
o If the NETCONF operation creates data nodes under a "choice", any o If the NETCONF operation creates data nodes under a "choice", any
existing nodes from other "case" branches are deleted by the existing nodes from other "case" branches are deleted by the
server. server.
o If the NETCONF operation modifies a data node such that any node's o If the NETCONF operation modifies a data node such that any node's
"when" expression becomes false, then the node with the "when" "when" expression becomes false, then the node with the "when"
expression is deleted by the server. expression is deleted by the server.
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 time 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 <running/> or <startup/>, these constraints MUST be enforced at the
end of the <edit-config> or <copy-config> operation. If the end of the <edit-config> or <copy-config> operation. If the
datastore is <candidate/>, the constraint enforcement is delayed datastore is <candidate/>, the constraint enforcement is delayed
until a <commit> or <validate> operation. until a <commit> or <validate> operation.
o Any "must" constraints MUST evaluate to "true". o Any "must" constraints MUST evaluate to "true".
o Any referential integrity constraints defined via the "path" o Any referential integrity constraints defined via the "path"
statement MUST be satisfied. statement MUST be satisfied.
o Any "unique" constraints on lists MUST be satisfied. o Any "unique" constraints on lists MUST be satisfied.
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. lists and leaf-lists.
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, derived from those built-in types or
from other derived types. Derived types may use subtyping to from other derived types. Derived types may use subtyping to
formally restrict the set of possible values. 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.6) and range restrictions of of strings (Sections 9.4.4 and 9.4.6) 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 NETCONF messages, and when specifying default values and the NETCONF messages and when specifying default values and numerical
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 NETCONF server sends data, it MUST be in the canonical form. When a NETCONF server sends data, it MUST be in the canonical form.
Some types have a lexical representation that depends on the XML Some types have a lexical representation that depends on the XML
context in which they occur. These types do not have a canonical context in which they occur. These types do not have a canonical
form. form.
9.2. The Integer Built-in Types 9.2. The Integer Built-In Types
The integer built-in types are int8, int16, int32, int64, uint8, The integer built-in types are int8, int16, int32, int64, uint8,
uint16, uint32, and uint64. They represent signed and unsigned uint16, uint32, and uint64. They represent signed and unsigned
integers of different sizes: integers of different sizes:
int8 represents integer values between -128 and 127, inclusively. int8 represents integer values between -128 and 127, inclusively.
int16 represents integer values between -32768 and 32767, int16 represents integer values between -32768 and 32767,
inclusively. inclusively.
skipping to change at page 116, line 29 skipping to change at page 113, line 16
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, which
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 "-"), the
characters "0x" followed a number of hexadecimal digits, where characters "0x" followed a number of hexadecimal digits, where
letters may be upper- or lowercase. The octal notation consists of letters may be uppercase or lowercase. The octal notation consists
an optional sign ("+" or "-"), the character "0" followed a number of of an optional sign ("+" or "-"), the character "0" followed a number
octal digits. 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 instance ("0"), it is interpreted as an octal number. In the XML instance
documents, an integer is always interpreted as a decimal number, and documents, an integer is always interpreted as a decimal number, and
leading zeros are allowed. leading zeros are allowed.
Examples: Examples:
// legal values // legal values
+4711 // legal positive value +4711 // legal positive value
skipping to change at page 117, line 23 skipping to change at page 114, line 23
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 those.
A range consists of an explicit value, or a lower inclusive bound, A range consists of an explicit value, or a lower-inclusive bound,
two consecutive dots "..", and an upper inclusive bound. Multiple two consecutive dots "..", and an upper-inclusive bound. Multiple
values or ranges can be given, separated by "|". If multiple values values or ranges can be given, separated by "|". If multiple values
or ranges are given they all MUST be disjoint and MUST be in or ranges are given, they all MUST be disjoint and MUST be in
ascending order. If a range restriction is applied to an already ascending order. If a range restriction is applied to an already
range restricted type, the new restriction MUST be equal or more range-restricted type, the new restriction MUST be equal or more
limiting, that is raising the lower bounds, reducing the upper limiting, that is raising the lower bounds, reducing the upper
bounds, removing explicit values or ranges, or splitting ranges into bounds, removing explicit values or ranges, or splitting ranges into
multiple ranges with intermediate gaps. Each explicit value and multiple ranges with intermediate gaps. Each explicit value and
range boundary value given in the range expression MUST match the range boundary value given in the range expression MUST match the
type being restricted, or be one of the special values "min" or type being restricted, or be one of the special values "min" or
"max". "min" and "max" means the minimum and maximum value accepted "max". "min" and "max" mean the minimum and maximum value accepted
for the type being restricted, respectively. 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 12. "range-arg" in Section 12.
9.2.4.1. The range's Substatements 9.2.4.1. The range's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
skipping to change at page 118, line 27 skipping to change at page 115, line 27
} }
} }
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 type represents a subset of the real numbers, which can
be represented by decimal numerals. The value space of decimal64 is be represented by decimal numerals. The value space of decimal64 is
the set of numbers that can be obtained by multiplying a 64 bit the set of numbers that can be obtained by multiplying a 64-bit
signed integer by a negative power of ten, i.e., expressible as signed integer by a negative power of ten, i.e., expressible as
"i x 10^-n" where i is an integer64 and n is an integer between 1 and "i x 10^-n" where i is an integer64 and n is an integer between 1 and
18, inclusively. 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.
skipping to change at page 120, line 14 skipping to change at page 117, line 14
9.3.5. Usage Example 9.3.5. Usage Example
typedef my-decimal { typedef my-decimal {
type decimal64 { type decimal64 {
fraction-digits 2; fraction-digits 2;
range "1 .. 3.14 | 10 | 20..max"; range "1 .. 3.14 | 10 | 20..max";
} }
} }
9.4. The string Built-in Type 9.4. The string Built-In Type
The string built-in type represents human readable strings in YANG. The string built-in type represents human-readable strings in YANG.
Legal characters are tab, carriage return, line feed, and the legal Legal characters are tab, carriage return, line feed, and the legal
characters of Unicode and ISO/IEC 10646 [ISO.10646]: characters of Unicode and ISO/IEC 10646 [ISO.10646]:
;; any Unicode character, excluding the surrogate blocks, ;; any Unicode character, excluding the surrogate blocks,
;; FFFE, and FFFF. ;; FFFE, and FFFF.
string = *char string = *char
char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD / char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD /
%x10000-10FFFF %x10000-10FFFF
9.4.1. Lexical Representation 9.4.1. Lexical Representation
skipping to change at page 121, line 4 skipping to change at page 118, line 7
The "length" statement, which is an optional substatement to the The "length" statement, which is an optional substatement to the
"type" statement, takes as an argument a length expression string. "type" statement, takes as an argument a length expression string.
It is used to restrict the built-in type "string", or types derived It is used to restrict the built-in type "string", or types derived
from "string". from "string".
A "length" statement restricts the number of 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 an already length-restricted type, the new restriction
MUST be equal or more limiting, that is, raising the lower bounds, MUST be equal or more limiting, that is, raising the lower bounds,
reducing the upper bounds, removing explicit length values or ranges, reducing the upper bounds, removing explicit length values or ranges,
or splitting ranges into multiple ranges with intermediate gaps. A or splitting ranges into multiple ranges with intermediate gaps. A
length value is a non-negative integer, or one of the special values length value is a non-negative integer, or one of the special values
"min" or "max". "min" and "max" means the minimum and maximum length "min" or "max". "min" and "max" mean the minimum and maximum length
accepted for the type being restricted, respectively. An accepted for the type being restricted, respectively. An
implementation is not required to support a length value larger than implementation is not required to support a length value larger than
18446744073709551615. 18446744073709551615.
The length expression syntax is formally defined by the rule The length expression syntax is formally defined by the rule
"length-arg" in Section 12. "length-arg" in Section 12.
9.4.4.1. The length's Substatements 9.4.4.1. The length's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
skipping to change at page 122, line 10 skipping to change at page 119, line 10
type my-base-str-type { type my-base-str-type {
// illegal length refinement // illegal length refinement
length "1..999"; length "1..999";
} }
9.4.6. The pattern Statement 9.4.6. 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 matches 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 an already pattern-restricted
type, values must match all patterns in the base type, in addition to type, values must match all patterns in the base type, in addition to
the new patterns. the new patterns.
9.4.6.1. The pattern's Substatements 9.4.6.1. The pattern's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
skipping to change at page 123, line 5 skipping to change at page 120, line 5
the following strings match: the following strings match:
AB // legal AB // legal
9A00 // legal 9A00 // legal
and the following strings do not match: and the following strings do not match:
00ABAB // illegal, too long 00ABAB // illegal, too long
xx00 // illegal, bad characters xx00 // illegal, bad characters
9.5. The boolean Built-in Type 9.5. The boolean Built-In Type
The boolean built-in type represents a boolean value. The boolean built-in type represents a boolean value.
9.5.1. Lexical Representation 9.5.1. Lexical Representation
The lexical representation of a boolean value is a string with a The lexical representation of a boolean value is a string with a
value of "true" or "false". These values MUST be in lowercase. value of "true" or "false". These values MUST be in lowercase.
9.5.2. Canonical Form 9.5.2. Canonical Form
The canonical form is the same as the lexical representation. The canonical form is the same as the lexical representation.
9.5.3. Restrictions 9.5.3. Restrictions
A boolean cannot be restricted. A boolean cannot be restricted.
9.6. The enumeration Built-in Type 9.6. The enumeration Built-In Type
The enumeration built-in type represents values from a set of The enumeration built-in type represents values from a set of
assigned names. assigned names.
9.6.1. Lexical Representation 9.6.1. Lexical Representation
The lexical representation of an enumeration value is the assigned The lexical representation of an enumeration value is the assigned
name string. name string.
9.6.2. Canonical Form 9.6.2. Canonical Form
skipping to change at page 123, line 50 skipping to change at page 120, line 50
9.6.4. The enum Statement 9.6.4. The enum Statement
The "enum" statement, which is a substatement to the "type" The "enum" statement, which is a substatement to the "type"
statement, MUST be present if the type is "enumeration". It is statement, MUST be present if the type is "enumeration". It is
repeatedly used to specify each assigned name of an enumeration type. repeatedly used to specify each assigned name of an enumeration type.
It takes as an argument a string which is the assigned name. The It takes as an argument a string which is the assigned name. The
string MUST NOT be empty and MUST NOT have any leading or trailing string MUST NOT be empty and MUST NOT have any leading or trailing
whitespace characters. The use of Unicode control codes SHOULD be whitespace characters. The use of Unicode control codes SHOULD be
avoided. avoided.
The statement is optionally followed by a block of substatements The statement is optionally followed by a block of substatements that
which holds detailed enum information. holds detailed enum information.
All assigned names in an enumeration MUST be unique. All assigned names in an enumeration MUST be unique.
9.6.4.1. The enum's Substatements 9.6.4.1. The enum's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
skipping to change at page 124, line 27 skipping to change at page 121, line 27
9.6.4.2. The value Statement 9.6.4.2. The value Statement
The "value" statement, which is optional, is used to associate an The "value" statement, which is optional, is used to associate an
integer value with the assigned name for the enum. This integer integer value with the assigned name for the enum. This integer
value MUST be in the range -2147483648 to 2147483647, and it MUST be value MUST be in the range -2147483648 to 2147483647, and it MUST be
unique within the enumeration type. The value is unused by YANG and unique within the enumeration type. The value is unused by YANG and
the XML encoding, but is carried as a convenience to implementors. the XML encoding, but is carried as a convenience to implementors.
If a value is not specified, then one will be automatically assigned. If a value is not specified, then one will be automatically assigned.
If the enum sub-statement is the first one defined, the assigned If the "enum" substatement is the first one defined, the assigned
value is zero (0), otherwise the assigned value is one greater than value is zero (0); otherwise, the assigned value is one greater than
the current highest enum value. the current highest enum value.
If the current highest value is equal to 2147483647, then an enum If the current highest value is equal to 2147483647, then an enum
value MUST be specified for enum sub-statements following the one value MUST be specified for "enum" substatements following the one
with the current highest value. with the current highest value.
9.6.5. Usage Example 9.6.5. Usage Example
leaf myenum { leaf myenum {
type enumeration { type enumeration {
enum zero; enum zero;
enum one; enum one;
enum seven { enum seven {
value 7; value 7;
} }
} }
} }
The lexical representation of the leaf "myenum" with value "seven" The lexical representation of the leaf "myenum" with value "seven"
is: is:
<myenum>seven</myenum> <myenum>seven</myenum>
9.7. The bits Built-in Type 9.7. The bits Built-In Type
The bits built-in type represents a bit set. That is, a bits value The bits built-in type represents a bit set. That is, a bits value
is a set of flags identified by small integer position numbers is a set of flags identified by small integer position numbers
starting at 0. Each bit number has an assigned name. starting at 0. Each bit number has an assigned name.
9.7.1. Restrictions 9.7.1. Restrictions
A bits type cannot be restricted. A bits type cannot be restricted.
9.7.2. Lexical Representation 9.7.2. Lexical Representation
The lexical representation of the bits type is a space separated list The lexical representation of the bits type is a space-separated list
of the individual bit values that are set. An empty string thus of the individual bit values that are set. An empty string thus
represents a value where no bits are set. represents a value where no bits are set.
9.7.3. Canonical Form 9.7.3. Canonical Form
In the canonical form, the bit values are separated by a single space In the canonical form, the bit values are separated by a single space
character and they appear ordered by their position (see character and they appear ordered by their position (see
Section 9.7.4.2). Section 9.7.4.2).
9.7.4. The bit Statement 9.7.4. The bit Statement
The "bit" statement, which is a substatement to the "type" statement, The "bit" statement, which is a substatement to the "type" statement,
MUST be present if the type is "bits". It is repeatedly used to MUST be present if the type is "bits". It is repeatedly used to
specify each assigned named bit of a bits type. It takes as an specify each assigned named bit of a bits type. It takes as an
argument a string which is the assigned name of the bit. It is argument a string that is the assigned name of the bit. It is
followed by a block of substatements which holds detailed bit followed by a block of substatements that holds detailed bit
information. The assigned name follows the same syntax rules as an information. The assigned name follows the same syntax rules as an
identifier (see Section 6.2). identifier (see Section 6.2).
All assigned names in a bits type MUST be unique. All assigned names in a bits type MUST be unique.
9.7.4.1. The bit's Substatements 9.7.4.1. The bit's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
| status | 7.19.2 | 0..1 | | status | 7.19.2 | 0..1 |
| position | 9.7.4.2 | 0..1 | | position | 9.7.4.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
9.7.4.2. The position Statement 9.7.4.2. The position Statement
The "position" statement, which is optional, takes as an argument a The "position" statement, which is optional, takes as an argument a
non-negative integer value which specifies the bit's position within non-negative integer value that specifies the bit's position within a
a hypothetical bit field. The position value MUST be in the range 0 hypothetical bit field. The position value MUST be in the range 0 to
to 4294967295, and it MUST be unique within the bits type. The value 4294967295, and it MUST be unique within the bits type. The value is
is unused by YANG and the NETCONF messages, but is carried as a unused by YANG and the NETCONF messages, but is carried as a
convenience to implementors. convenience to implementors.
If a bit position is not specified, then one will be automatically If a bit position is not specified, then one will be automatically
assigned. If the bit sub-statement is the first one defined, the assigned. If the "bit" substatement is the first one defined, the
assigned value is zero (0), otherwise the assigned value is one assigned value is zero (0); otherwise, the assigned value is one
greater than the current highest bit position. greater than the current highest bit position.
If the current highest bit position value is equal to 4294967295, If the current highest bit position value is equal to 4294967295,
then a position value MUST be specified for bit sub-statements then a position value MUST be specified for "bit" substatements
following the one with the current highest position value. following the one with the current highest position value.
9.7.5. Usage Example 9.7.5. Usage Example
Given the following leaf: Given the following leaf:
leaf mybits { leaf mybits {
type bits { type bits {
bit disable-nagle { bit disable-nagle {
position 0; position 0;
skipping to change at page 126, line 47 skipping to change at page 123, line 47
} }
} }
default "auto-sense-speed"; default "auto-sense-speed";
} }
The lexical representation of this leaf with bit values disable-nagle The lexical representation of this leaf with bit values disable-nagle
and 10-Mb-only set would be: and 10-Mb-only set would be:
<mybits>disable-nagle 10-Mb-only</mybits> <mybits>disable-nagle 10-Mb-only</mybits>
9.8. The binary Built-in Type 9.8. The binary Built-In Type
The binary built-in type represents any binary data, i.e., a sequence The binary built-in type represents any binary data, i.e., a sequence
of octets. of octets.
9.8.1. Restrictions 9.8.1. Restrictions
A binary can be restricted with the "length" (Section 9.4.4) A binary can be restricted with the "length" (Section 9.4.4)
statement. The length of a binary value is the number of octets it statement. The length of a binary value is the number of octets it
contains. contains.
9.8.2. Lexical Representation 9.8.2. Lexical Representation
Binary values are encoded with the base64 encoding scheme (see Binary values are encoded with the base64 encoding scheme (see
[RFC4648], section 4). [RFC4648], Section 4).
9.8.3. Canonical Form 9.8.3. Canonical Form
The canonical form of a binary value follow the rules in [RFC4648]. The canonical form of a binary value follows the rules in [RFC4648].
9.9. The leafref Built-in Type 9.9. The leafref Built-In Type
The leafref type is used to reference a particular leaf instance in The leafref type is used to reference a particular leaf instance in
the data tree. The "path" substatement (Section 9.9.2) selects a set the data tree. The "path" substatement (Section 9.9.2) selects a set
of leaf instances, and the leafref value space is the set of values of leaf instances, and the leafref value space is the set of values
of these leaf instances. of these leaf instances.
If the leaf with the leafref type represents configuration data, the If the leaf with the leafref type represents configuration data, the
leaf it refers to MUST also represent configuration. Such a leaf leaf it refers to MUST also represent configuration. Such a leaf
puts a constraint on valid data. All leafref nodes MUST reference puts a constraint on valid data. All leafref nodes MUST reference
existing leaf instances or leafs with default values in use (see existing leaf instances or leafs with default values in use (see
Section 7.6.1) for the data to be valid. This constraint is enforced Section 7.6.1) for the data to be valid. This constraint is enforced
according to the rules in Section 8. according to the rules in Section 8.
There MUST NOT be any circular chains of leafrefs. There MUST NOT be any circular chains of leafrefs.
If the leaf that the leafref refers to is conditional based on one or If the leaf that the leafref refers to is conditional based on one or
more feature (see Section 7.18.2), then the leaf with the leafref more features (see Section 7.18.2), then the leaf with the leafref
type MUST also be conditional based on at least the same set of type MUST also be conditional based on at least the same set of
features. features.
9.9.1. Restrictions 9.9.1. Restrictions
A leafref cannot be restricted. A leafref cannot be restricted.
9.9.2. The path Statement 9.9.2. The path Statement
The "path" statement, which is a substatement to the "type" The "path" statement, which is a substatement to the "type"
statement, MUST be present if the type is "leafref". It takes as an statement, MUST be present if the type is "leafref". It takes as an
argument a string which MUST refer to a leaf or leaf-list node. argument a string that MUST refer to a leaf or leaf-list node.
The syntax for a path argument is a subset of the XPath abbreviated The syntax for a path argument is a subset of the XPath abbreviated
syntax. Predicates are used only for constraining the values for the syntax. Predicates are used only for constraining the values for the
key nodes for list entries. Each predicate consists of exactly one key nodes for list entries. Each predicate consists of exactly one
equality test per key, and multiple adjacent predicates MAY be equality test per key, and multiple adjacent predicates MAY be
present if a list has multiple keys. The syntax is formally defined present if a list has multiple keys. The syntax is formally defined
by the rule "path-arg" in Section 12. by the rule "path-arg" in Section 12.
The predicates are only used when more than one key reference is The predicates are only used when more than one key reference is
needed to uniquely identify a leaf instance. This occurs if a list needed to uniquely identify a leaf instance. This occurs if a list
has multiple keys, or a reference to a leaf other than the key in a has multiple keys, or a reference to a leaf other than the key in a
list is needed. In these cases, multiple leafrefs are typically list is needed. In these cases, multiple leafrefs are typically
specified, and predicates are used to tie them together. specified, and predicates are used to tie them together.
The "path" expression evaluates to a node set consisting of zero, one The "path" expression evaluates to a node set consisting of zero,
or more nodes. If the leaf with the leafref type represents one, or more nodes. If the leaf with the leafref type represents
configuration data, this node set MUST be non-empty. configuration data, this node set MUST be non-empty.
The "path" XPath expression is conceptually evaluated in the The "path" XPath expression is conceptually evaluated in the
following context, in addition to the definition in Section 6.4.1: following context, in addition to the definition in Section 6.4.1:
o The context node is the node in the data tree for which the "path" o The context node is the node in the data tree for which the "path"
statement is defined. statement is defined.
The accessible tree depends on the context node: The accessible tree depends on the context node:
o If the context node represents configuration data, the tree is the o If the context node represents configuration data, the tree is the
data in the NETCONF datastore where the context node exists. The data in the NETCONF datastore where the context node exists. The
XPath root node has all top-level configuration data nodes in all XPath root node has all top-level configuration data nodes in all
modules as children. modules as children.
o Otherwise the tree is all state data on the device, and the o Otherwise, the tree is all state data on the device, and the
<running/> datastore. The XPath root node has all top-level data <running/> datastore. The XPath root node has all top-level data
nodes in all modules as children. nodes in all modules as children.
9.9.3. Lexical Representation 9.9.3. Lexical Representation
A leafref value is encoded the same way as the leaf it references. A leafref value is encoded the same way as the leaf it references.
9.9.4. Canonical Form 9.9.4. Canonical Form
The canonical form of a leafref is the same as the canonical form of The canonical form of a leafref is the same as the canonical form of
skipping to change at page 132, line 31 skipping to change at page 129, line 34
<notification <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-04-01T00:01:00Z</eventTime> <eventTime>2008-04-01T00:01:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system"> <link-failure xmlns="http://acme.example.com/system">
<if-name>eth0</if-name> <if-name>eth0</if-name>
<admin-status>up</admin-status> <admin-status>up</admin-status>
</link-failure> </link-failure>
</notification> </notification>
9.10. The identityref Built-in Type 9.10. The identityref Built-In Type
The identityref type is used to reference an existing identity (see The identityref type is used to reference an existing identity (see
Section 7.16). Section 7.16).
9.10.1. Restrictions 9.10.1. Restrictions
An identityref cannot be restricted. An identityref cannot be restricted.
9.10.2. The identityref's base Statement 9.10.2. The identityref's base Statement
The "base" statement, which is a substatement to the "type" The "base" statement, which is a substatement to the "type"
statement, MUST be present if the type is "identityref". The statement, MUST be present if the type is "identityref". The
argument is the name of an identity, as defined by an "identity" argument is the name of an identity, as defined by an "identity"
statement. If a prefix is present on the identity name, it refers to statement. If a prefix is present on the identity name, it refers to
an identity defined in the module which was imported with that an identity defined in the module that was imported with that prefix.
prefix. Otherwise an identity with the matching name MUST be defined Otherwise, an identity with the matching name MUST be defined in the
in the current module or an included submodule. current module or an included submodule.
Valid values for an identityref are any identities derived from the Valid values for an identityref are any identities derived from the
identityref's base identity. On a particular server, the valid identityref's base identity. On a particular server, the valid
values are further restricted to the set of identities defined in the values are further restricted to the set of identities defined in the
modules supported by the server. modules supported by the server.
9.10.3. Lexical Representation 9.10.3. Lexical Representation
An identityref is encoded as the referred identity's Qualified Name An identityref is encoded as the referred identity's qualified name
as defined in [XML-NAMES]. If the Prefix is not present, the as defined in [XML-NAMES]. If the prefix is not present, the
namespace of the identityref is the default namespace in effect on namespace of the identityref is the default namespace in effect on
the element which contains the identityref value. the element that contains the identityref value.
When an identityref is given a default value using the "default" When an identityref is given a default value using the "default"
statement, the identity name in the default value MAY have a prefix. statement, the identity name in the default value MAY have a prefix.
If a prefix is present on the identity name, it refers to an identity If a prefix is present on the identity name, it refers to an identity
defined in the module which was imported with that prefix. Otherwise defined in the module that was imported with that prefix. Otherwise,
an identity with the matching name MUST be defined in the current an identity with the matching name MUST be defined in the current
module or an included submodule. module or an included submodule.
9.10.4. Canonical Form 9.10.4. Canonical Form
Since the lexical form depends on the XML context in which the value Since the lexical form depends on the XML context in which the value
occurs, this type does not have a canonical form. occurs, this type does not have a canonical form.
9.10.5. Usage Example 9.10.5. Usage Example
With the identity definitions in Section 7.16.3, and the following With the identity definitions in Section 7.16.3 and the following
module: module:
module my-crypto { module my-crypto {
namespace "http://example.com/my-crypto"; namespace "http://example.com/my-crypto";
prefix mc; prefix mc;
import "crypto-base" { import "crypto-base" {
prefix "crypto"; prefix "crypto";
} }
skipping to change at page 133, line 50 skipping to change at page 131, line 5
base "crypto:crypto-alg"; base "crypto:crypto-alg";
} }
leaf crypto { leaf crypto {
type identityref { type identityref {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
} }
} }
} }
The leaf "crypto" will be encoded as follows, if the value is the the leaf "crypto" will be encoded as follows, if the value is the
"des3" identity defined in the "des" module: "des3" identity defined in the "des" module:
<crypto xmlns:des="http://example.com/des">des:des3</crypto> <crypto xmlns:des="http://example.com/des">des:des3</crypto>
Any prefixes used in the encoding are local to each instance Any prefixes used in the encoding are local to each instance
encoding. This means that the same identityref may be encoded encoding. This means that the same identityref may be encoded
differently by different implementations. For example, the following differently by different implementations. For example, the following
example encodes the same leaf as above: example encodes the same leaf as above:
<crypto xmlns:x="http://example.com/des">x:des3</crypto> <crypto xmlns:x="http://example.com/des">x:des3</crypto>
If the "crypto" leaf's value instead is "aes" defined in the If the "crypto" leaf's value instead is "aes" defined in the
"my-crypto" module it can be encoded as: "my-crypto" module, it can be encoded as:
<crypto xmlns:mc="http://example.com/my-crypto">mc:aes</crypto> <crypto xmlns:mc="http://example.com/my-crypto">mc:aes</crypto>
or, using the default namespace: or, using the default namespace:
<crypto>aes</crypto> <crypto>aes</crypto>
9.11. The empty Built-in Type 9.11. The empty Built-In Type
The empty built-in type represents a leaf that does not have any The empty built-in type represents a leaf that does not have any
value, it conveys information by its presence or absence. value, it conveys information by its presence or absence.
An empty type cannot have a default value. An empty type cannot have a default value.
9.11.1. Restrictions 9.11.1. Restrictions
An empty type cannot be restricted. An empty type cannot be restricted.
skipping to change at page 135, line 7 skipping to change at page 132, line 11
leaf enable-qos { leaf enable-qos {
type empty; type empty;
} }
will be encoded as will be encoded as
<enable-qos/> <enable-qos/>
if it exists. if it exists.
9.12. The union Built-in Type 9.12. The union Built-In Type
The union built-in type represents a value that corresponds to one of The union built-in type represents a value that corresponds to one of
its member types. its member types.
When the type is "union", the "type" statement (Section 7.4) MUST be When the type is "union", the "type" statement (Section 7.4) MUST be
present. It is used to repeatedly specify each member type of the present. It is used to repeatedly specify each member type of the
union. It takes as an argument a string which is the name of a union. It takes as an argument a string that is the name of a member
member type. type.
A member type can be of any built-in or derived type, except it MUST A member type can be of any built-in or derived type, except it MUST
NOT be one of the built-in types "empty" or "leafref". NOT be one of the built-in types "empty" or "leafref".
When a string representing a union data type is validated, the string When a string representing a union data type is validated, the string
is validated against each member type, in the order they are is validated against each member type, in the order they are
specified in the type statement, until a match is found. specified in the "type" statement, until a match is found.
Any default values or units properties defined in the member types Any default value or "units" property defined in the member types is
are not inherited by the union type. not inherited by the union type.
Example: Example:
type union { type union {
type int32; type int32;
type enumeration { type enumeration {
enum "unbounded"; enum "unbounded";
} }
} }
9.12.1. Restrictions 9.12.1. Restrictions
A union cannot be restricted. However, each member type can be A union cannot be restricted. However, each member type can be
restricted, based on the rules defined in Section 9. restricted, based on the rules defined in Section 9.
9.12.2. Lexical Representation 9.12.2. Lexical Representation
The lexical representation of an union is a value that corresponds to The lexical representation of a union is a value that corresponds to
the representation of any one of the member types. the representation of any one of the member types.
9.12.3. Canonical Form 9.12.3. Canonical Form
The canonical form of a union value is the same as the canonical form The canonical form of a union value is the same as the canonical form
of the member type of the value. of the member type of the value.
9.13. The instance-identifier Built-in Type 9.13. The instance-identifier Built-In Type
The instance-identifier built-in type is used to uniquely identify a The instance-identifier built-in type is used to uniquely identify a
particular instance node in the data tree. particular instance node in the data tree.
The syntax for an instance-identifier is a subset of the XPath The syntax for an instance-identifier is a subset of the XPath
abbreviated syntax, formally defined by the rule abbreviated syntax, formally defined by the rule
"instance-identifier" in Section 12. It is used to uniquely identify "instance-identifier" in Section 12. It is used to uniquely identify
a node in the data tree. Predicates are used only for specifying the a node in the data tree. Predicates are used only for specifying the
values for the key nodes for list entries, a value of a leaf-list values for the key nodes for list entries, a value of a leaf-list
entry, or a positional index for list without keys. For identifying entry, or a positional index for a list without keys. For
list entries with keys, each predicate consists of one equality test identifying list entries with keys, each predicate consists of one
per key, and each key MUST have a corresponding predicate. equality test per key, and each key MUST have a corresponding
predicate.
If the leaf with the instance-identifier type represents If the leaf with the instance-identifier type represents
configuration data, and the "require-instance" property configuration data, and the "require-instance" property
(Section 9.13.2) is "true", the node it refers to MUST also represent (Section 9.13.2) is "true", the node it refers to MUST also represent
configuration. Such a leaf puts a constraint on valid data. All configuration. Such a leaf puts a constraint on valid data. All
such leaf nodes MUST reference existing nodes or leaf nodes with such leaf nodes MUST reference existing nodes or leaf nodes with
their default value in use (see Section 7.6.1) for the data to be their default value in use (see Section 7.6.1) for the data to be
valid. This constraint is enforced according to the rules in valid. This constraint is enforced according to the rules in
Section 8. Section 8.
skipping to change at page 136, line 42 skipping to change at page 133, line 48
o The context node is the root node in the accessible tree. o The context node is the root node in the accessible tree.
The accessible tree depends on the leaf with the instance-identifier The accessible tree depends on the leaf with the instance-identifier
type: type:
o If this leaf represents configuration data, the tree is the data o If this leaf represents configuration data, the tree is the data
in the NETCONF datastore where the leaf exists. The XPath root in the NETCONF datastore where the leaf exists. The XPath root
node has all top-level configuration data nodes in all modules as node has all top-level configuration data nodes in all modules as
children. children.
o Otherwise the tree is all state data on the device, and the o Otherwise, the tree is all state data on the device, and the
<running/> datastore. The XPath root node has all top-level data <running/> datastore. The XPath root node has all top-level data
nodes in all modules as children. nodes in all modules as children.
9.13.1. Restrictions 9.13.1. Restrictions
An instance-identifier can be restricted with the "require-instance" An instance-identifier can be restricted with the "require-instance"
statement (Section 9.13.2). statement (Section 9.13.2).
9.13.2. The require-instance Statement 9.13.2. The require-instance Statement
skipping to change at page 137, line 23 skipping to change at page 134, line 28
referred MUST exist for the data to be valid. This constraint is referred MUST exist for the data to be valid. This constraint is
enforced according to the rules in Section 8. enforced according to the rules in Section 8.
If "require-instance" is "false", it means that the instance being If "require-instance" is "false", it means that the instance being
referred MAY exist in valid data. referred MAY exist in valid data.
9.13.3. Lexical Representation 9.13.3. Lexical Representation
An instance-identifier value is lexically represented as a string. An instance-identifier value is lexically represented as a string.
All node names in an instance-identifier value MUST be qualified with All node names in an instance-identifier value MUST be qualified with
explicit namespace prefixes and these prefixes MUST be declared in explicit namespace prefixes, and these prefixes MUST be declared in
the XML namespace scope in the instance-identifier's XML element. the XML namespace scope in the instance-identifier's XML element.
Any prefixes used in the encoding are local to each instance Any prefixes used in the encoding are local to each instance
encoding. This means that the same instance-identifier may be encoding. This means that the same instance-identifier may be
encoded differently by different implementations. encoded differently by different implementations.
9.13.4. Canonical Form 9.13.4. Canonical Form
Since the lexical form depends on the XML context in which the value Since the lexical form depends on the XML context in which the value
occurs, this type does not have a canonical form. occurs, this type does not have a canonical form.
skipping to change at page 139, line 14 skipping to change at page 135, line 25
10. Updating a Module 10. Updating a Module
As experience is gained with a module, it may be desirable to revise As experience is gained with a module, it may be desirable to revise
that module. However, changes are not allowed if they have any that module. However, changes are not allowed if they have any
potential to cause interoperability problems between a client using potential to cause interoperability problems between a client using
an original specification and a server using an updated an original specification and a server using an updated
specification. specification.
For any published change, a new "revision" statement (Section 7.1.9) For any published change, a new "revision" statement (Section 7.1.9)
MUST be included in front of the existing revision statements. If MUST be included in front of the existing "revision" statements. If
there are no existing revision statements, then one MUST be added to there are no existing "revision" statements, then one MUST be added
identify the new revision. Furthermore, any necessary changes MUST to identify the new revision. Furthermore, any necessary changes
be applied to any meta data statements, including the "organization" MUST be applied to any meta-data statements, including the
and "contact" statements (Section 7.1.7, Section 7.1.8). "organization" and "contact" statements (Sections 7.1.7, 7.1.8).
Note that definitions contained in a module are available to be Note that definitions contained in a module are available to be
imported by any other module, and are referenced in "import" imported by any other module, and are referenced in "import"
statements via the module name. Thus, a module name MUST NOT be statements via the module name. Thus, a module name MUST NOT be
changed. Furthermore, the "namespace" statement MUST NOT be changed, changed. Furthermore, the "namespace" statement MUST NOT be changed,
since all XML elements are qualified by the namespace. since all XML elements are qualified by the namespace.
Obsolete definitions MUST NOT be removed from modules since their Obsolete definitions MUST NOT be removed from modules since their
identifiers may still be referenced by other modules. identifiers may still be referenced by other modules.
skipping to change at page 140, line 14 skipping to change at page 136, line 26
o A "min-elements" statement may be removed, or changed to require o A "min-elements" statement may be removed, or changed to require
fewer elements. fewer elements.
o A "max-elements" statement may be removed, or changed to allow o A "max-elements" statement may be removed, or changed to allow
more elements. more elements.
o A "description" statement may be added or clarified without o A "description" statement may be added or clarified without
changing the semantics of the definition. changing the semantics of the definition.
o New typedefs, groupings, rpc, notifications, extensions, features, o New typedefs, groupings, rpcs, notifications, extensions,
and identities may be added. features, and identities may be added.
o New data definition statements may be added if they do not add o New data definition statements may be added if they do not add
mandatory nodes (Section 3.1) to existing nodes or at the top- mandatory nodes (Section 3.1) to existing nodes or at the top
level in a module or submodule, or if they are conditionally level in a module or submodule, or if they are conditionally
dependent on a new feature (i.e., have a "if-feature" statement dependent on a new feature (i.e., have an "if-feature" statement
which refers to a new feature). that refers to a new feature).
o A new "case" statement may be added. o A new "case" statement may be added.
o A node that represented state data may be changed to represent o A node that represented state data may be changed to represent
configuration, provided it is not mandatory (Section 3.1). configuration, provided it is not mandatory (Section 3.1).
o An "if-feature" statement may be removed, provided its node is not o An "if-feature" statement may be removed, provided its node is not
mandatory (Section 3.1). mandatory (Section 3.1).
o A "status" statement may be added, or changed from "current" to o A "status" statement may be added, or changed from "current" to
"deprecated" or "obsolete", or from "deprecated" to "obsolete". "deprecated" or "obsolete", or from "deprecated" to "obsolete".
o A "type" statement may be replaced with another "type" statement o A "type" statement may be replaced with another "type" statement
which does not change the syntax or semantics of the type. For that does not change the syntax or semantics of the type. For
example, an inline type definition may be replaced with a typedef, example, an inline type definition may be replaced with a typedef,
but a int8 type cannot be replaced by a int16, since the syntax but an int8 type cannot be replaced by an int16, since the syntax
would change. would change.
o Any set of data definition nodes may be replaced with another set o Any set of data definition nodes may be replaced with another set
of syntactically and semantically equivalent nodes. For example, of syntactically and semantically equivalent nodes. For example,
a set of leafs may be replaced by a uses of a grouping with the a set of leafs may be replaced by a uses of a grouping with the
same leafs. same leafs.
o A module may be split into a set of submodules, or submodule may o A module may be split into a set of submodules, or a submodule may
be removed, provided the definitions in the module do not change be removed, provided the definitions in the module do not change
in any other way than allowed here. in any other way than allowed here.
o The "prefix" statement may be changed, provided all local uses of o The "prefix" statement may be changed, provided all local uses of
the prefix also are changed. the prefix also are changed.
Otherwise, if the semantics of any previous definition are changed Otherwise, if the semantics of any previous definition are changed
(i.e., if a non-editorial change is made to any definition other than (i.e., if a non-editorial change is made to any definition other than
those specifically allowed above), then this MUST be achieved by a those specifically allowed above), then this MUST be achieved by a
new definition with a new identifier. new definition with a new identifier.
In statements which have any data definition statements as In statements that have any data definition statements as
substatements, those data definition substatements MUST NOT be substatements, those data definition substatements MUST NOT be
reordered. reordered.
11. YIN 11. YIN
A YANG module can be translated into an alternative XML-based syntax A YANG module can be translated into an alternative XML-based syntax
called YIN. The translated module is called a YIN module. This called YIN. The translated module is called a YIN module. This
section describes symmetric mapping rules between the two formats. section describes symmetric mapping rules between the two formats.
The YANG and YIN formats contain equivalent information using The YANG and YIN formats contain equivalent information using
skipping to change at page 142, line 25 skipping to change at page 137, line 46
generation of code and documentation, and other tasks. Tools like generation of code and documentation, and other tasks. Tools like
XSLT or XML validators can be utilized. XSLT or XML validators can be utilized.
The mapping between YANG and YIN does not modify the information The mapping between YANG and YIN does not modify the information
content of the model. Comments and whitespace are not preserved. content of the model. Comments and whitespace are not preserved.
11.1. Formal YIN Definition 11.1. Formal YIN Definition
There is a one-to-one correspondence between YANG keywords and YIN There is a one-to-one correspondence between YANG keywords and YIN
elements. The local name of a YIN element is identical to the elements. The local name of a YIN element is identical to the
corresponding YANG keyword. This means in particular that the corresponding YANG keyword. This means, in particular, that the
document element (root) of a YIN document is always <module> or document element (root) of a YIN document is always <module> or
<submodule>. <submodule>.
YIN elements corresponding to the YANG keywords belong to the YIN elements corresponding to the YANG keywords belong to the
namespace whose associated URI is namespace whose associated URI is
"urn:ietf:params:xml:ns:yang:yin:1". "urn:ietf:params:xml:ns:yang:yin:1".
YIN elements corresponding to extension keywords belong to the YIN elements corresponding to extension keywords belong to the
namespace of the YANG module where the extension keyword is declared namespace of the YANG module where the extension keyword is declared
via the "extension" statement. via the "extension" statement.
skipping to change at page 148, line 35 skipping to change at page 144, line 39
leaf-stmt / leaf-stmt /
leaf-list-stmt / leaf-list-stmt /
list-stmt / list-stmt /
choice-stmt / choice-stmt /
anyxml-stmt / anyxml-stmt /
uses-stmt uses-stmt
yang-version-stmt = yang-version-keyword sep yang-version-arg-str yang-version-stmt = yang-version-keyword sep yang-version-arg-str
optsep stmtend optsep stmtend
yang-version-arg-str = < a string which matches the rule yang-version-arg-str = < a string that matches the rule
yang-version-arg > yang-version-arg >
yang-version-arg = "1" yang-version-arg = "1"
import-stmt = import-keyword sep identifier-arg-str optsep import-stmt = import-keyword sep identifier-arg-str optsep
"{" stmtsep "{" stmtsep
prefix-stmt stmtsep prefix-stmt stmtsep
[revision-date-stmt stmtsep] [revision-date-stmt stmtsep]
"}" "}"
include-stmt = include-keyword sep identifier-arg-str optsep include-stmt = include-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
[revision-date-stmt stmtsep] [revision-date-stmt stmtsep]
"}") "}")
namespace-stmt = namespace-keyword sep uri-str optsep stmtend namespace-stmt = namespace-keyword sep uri-str optsep stmtend
uri-str = < a string which matches the rule
uri-str = < a string that matches the rule
URI in RFC 3986 > URI in RFC 3986 >
prefix-stmt = prefix-keyword sep prefix-arg-str prefix-stmt = prefix-keyword sep prefix-arg-str
optsep stmtend optsep stmtend
belongs-to-stmt = belongs-to-keyword sep identifier-arg-str belongs-to-stmt = belongs-to-keyword sep identifier-arg-str
optsep optsep
"{" stmtsep "{" stmtsep
prefix-stmt stmtsep prefix-stmt stmtsep
"}" "}"
skipping to change at page 150, line 4 skipping to change at page 146, line 17
;; these stmts can appear in any order ;; these stmts can appear in any order
[argument-stmt stmtsep] [argument-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
argument-stmt = argument-keyword sep identifier-arg-str optsep argument-stmt = argument-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
[yin-element-stmt stmtsep] [yin-element-stmt stmtsep]
"}") "}")
yin-element-stmt = yin-element-keyword sep yin-element-arg-str yin-element-stmt = yin-element-keyword sep yin-element-arg-str
stmtend stmtend
yin-element-arg-str = < a string which matches the rule yin-element-arg-str = < a string that matches the rule
yin-element-arg > yin-element-arg >
yin-element-arg = true-keyword / false-keyword yin-element-arg = true-keyword / false-keyword
identity-stmt = identity-keyword sep identifier-arg-str optsep identity-stmt = identity-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[base-stmt stmtsep] [base-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
skipping to change at page 151, line 38 skipping to change at page 148, line 5
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
decimal64-specification = fraction-digits-stmt decimal64-specification = fraction-digits-stmt
fraction-digits-stmt = fraction-digits-keyword sep fraction-digits-stmt = fraction-digits-keyword sep
fraction-digits-arg-str stmtend fraction-digits-arg-str stmtend
fraction-digits-arg-str = < a string which matches the rule fraction-digits-arg-str = < a string that matches the rule
fraction-digits-arg > fraction-digits-arg >
fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" / fraction-digits-arg = ("1" ["0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8"]) "5" / "6" / "7" / "8"])
/ "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"
string-restrictions = ;; these stmts can appear in any order string-restrictions = ;; these stmts can appear in any order
[length-stmt stmtsep] [length-stmt stmtsep]
*(pattern-stmt stmtsep) *(pattern-stmt stmtsep)
skipping to change at page 152, line 45 skipping to change at page 149, line 15
leafref-specification = leafref-specification =
;; these stmts can appear in any order ;; these stmts can appear in any order
path-stmt stmtsep path-stmt stmtsep
[require-instance-stmt stmtsep] [require-instance-stmt stmtsep]
path-stmt = path-keyword sep path-arg-str stmtend path-stmt = path-keyword sep path-arg-str stmtend
require-instance-stmt = require-instance-keyword sep require-instance-stmt = require-instance-keyword sep
require-instance-arg-str stmtend require-instance-arg-str stmtend
require-instance-arg-str = < a string which matches the rule require-instance-arg-str = < a string that matches the rule
require-instance-arg > require-instance-arg >
require-instance-arg = true-keyword / false-keyword require-instance-arg = true-keyword / false-keyword
instance-identifier-specification = instance-identifier-specification =
[require-instance-stmt stmtsep] [require-instance-stmt stmtsep]
identityref-specification = identityref-specification =
base-stmt stmtsep base-stmt stmtsep
skipping to change at page 153, line 26 skipping to change at page 149, line 44
[position-stmt stmtsep] [position-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}" "}"
"}") "}")
position-stmt = position-keyword sep position-stmt = position-keyword sep
position-value-arg-str stmtend position-value-arg-str stmtend
position-value-arg-str = < a string which matches the rule position-value-arg-str = < a string that matches the rule
position-value-arg > position-value-arg >
position-value-arg = non-negative-integer-value position-value-arg = non-negative-integer-value
status-stmt = status-keyword sep status-arg-str stmtend status-stmt = status-keyword sep status-arg-str stmtend
status-arg-str = < a string that matches the rule
status-arg-str = < a string which matches the rule
status-arg > status-arg >
status-arg = current-keyword / status-arg = current-keyword /
obsolete-keyword / obsolete-keyword /
deprecated-keyword deprecated-keyword
config-stmt = config-keyword sep config-stmt = config-keyword sep
config-arg-str stmtend config-arg-str stmtend
config-arg-str = < a string which matches the rule config-arg-str = < a string that matches the rule
config-arg > config-arg >
config-arg = true-keyword / false-keyword config-arg = true-keyword / false-keyword
mandatory-stmt = mandatory-keyword sep mandatory-stmt = mandatory-keyword sep
mandatory-arg-str stmtend mandatory-arg-str stmtend
mandatory-arg-str = < a string which matches the rule mandatory-arg-str = < a string that matches the rule
mandatory-arg > mandatory-arg >
mandatory-arg = true-keyword / false-keyword mandatory-arg = true-keyword / false-keyword
presence-stmt = presence-keyword sep string stmtend presence-stmt = presence-keyword sep string stmtend
ordered-by-stmt = ordered-by-keyword sep ordered-by-stmt = ordered-by-keyword sep
ordered-by-arg-str stmtend ordered-by-arg-str stmtend
ordered-by-arg-str = < a string which matches the rule ordered-by-arg-str = < a string that matches the rule
ordered-by-arg > ordered-by-arg >
ordered-by-arg = user-keyword / system-keyword ordered-by-arg = user-keyword / system-keyword
must-stmt = must-keyword sep string optsep must-stmt = must-keyword sep string optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
skipping to change at page 154, line 30 skipping to change at page 151, line 4
;; these stmts can appear in any order ;; these stmts can appear in any order
[error-message-stmt stmtsep] [error-message-stmt stmtsep]
[error-app-tag-stmt stmtsep] [error-app-tag-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
error-message-stmt = error-message-keyword sep string stmtend error-message-stmt = error-message-keyword sep string stmtend
error-app-tag-stmt = error-app-tag-keyword sep string stmtend error-app-tag-stmt = error-app-tag-keyword sep string stmtend
min-elements-stmt = min-elements-keyword sep min-elements-stmt = min-elements-keyword sep
min-value-arg-str stmtend min-value-arg-str stmtend
min-value-arg-str = < a string which matches the rule min-value-arg-str = < a string that matches the rule
min-value-arg > min-value-arg >
min-value-arg = non-negative-integer-value min-value-arg = non-negative-integer-value
max-elements-stmt = max-elements-keyword sep max-elements-stmt = max-elements-keyword sep
max-value-arg-str stmtend max-value-arg-str stmtend
max-value-arg-str = < a string which matches the rule max-value-arg-str = < a string that matches the rule
max-value-arg > max-value-arg >
max-value-arg = unbounded-keyword / max-value-arg = unbounded-keyword /
positive-integer-value positive-integer-value
value-stmt = value-keyword sep integer-value stmtend value-stmt = value-keyword sep integer-value stmtend
grouping-stmt = grouping-keyword sep identifier-arg-str optsep grouping-stmt = grouping-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
skipping to change at page 156, line 38 skipping to change at page 153, line 11
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*((typedef-stmt / *((typedef-stmt /
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
1*(data-def-stmt stmtsep) 1*(data-def-stmt stmtsep)
"}" "}"
key-stmt = key-keyword sep key-arg-str stmtend key-stmt = key-keyword sep key-arg-str stmtend
key-arg-str = < a string which matches the rule key-arg-str = < a string that matches the rule
key-arg > key-arg >
key-arg = node-identifier *(sep node-identifier) key-arg = node-identifier *(sep node-identifier)
unique-stmt = unique-keyword sep unique-arg-str stmtend unique-stmt = unique-keyword sep unique-arg-str stmtend
unique-arg-str = < a string which matches the rule unique-arg-str = < a string that matches the rule
unique-arg > unique-arg >
unique-arg = descendant-schema-nodeid unique-arg = descendant-schema-nodeid
*(sep descendant-schema-nodeid) *(sep descendant-schema-nodeid)
choice-stmt = choice-keyword sep identifier-arg-str optsep choice-stmt = choice-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
skipping to change at page 158, line 26 skipping to change at page 154, line 49
"{" stmtsep "{" stmtsep
(refine-container-stmts / (refine-container-stmts /
refine-leaf-stmts / refine-leaf-stmts /
refine-leaf-list-stmts / refine-leaf-list-stmts /
refine-list-stmts / refine-list-stmts /
refine-choice-stmts / refine-choice-stmts /
refine-case-stmts / refine-case-stmts /
refine-anyxml-stmts) refine-anyxml-stmts)
"}") "}")
refine-arg-str = < a string which matches the rule refine-arg-str = < a string that matches the rule
refine-arg > refine-arg >
refine-arg = descendant-schema-nodeid refine-arg = descendant-schema-nodeid
refine-container-stmts = refine-container-stmts =
;; these stmts can appear in any order ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[presence-stmt stmtsep] [presence-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
refine-leaf-stmts = ;; these stmts can appear in any order refine-leaf-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
skipping to change at page 159, line 47 skipping to change at page 156, line 21
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
*(if-feature-stmt stmtsep) *(if-feature-stmt stmtsep)
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
1*((data-def-stmt stmtsep) / 1*((data-def-stmt stmtsep) /
(case-stmt stmtsep)) (case-stmt stmtsep))
"}" "}"
uses-augment-arg-str = < a string which matches the rule uses-augment-arg-str = < a string that matches the rule
uses-augment-arg > uses-augment-arg >
uses-augment-arg = descendant-schema-nodeid uses-augment-arg = descendant-schema-nodeid
augment-stmt = augment-keyword sep augment-arg-str optsep augment-stmt = augment-keyword sep augment-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
*(if-feature-stmt stmtsep) *(if-feature-stmt stmtsep)
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
1*((data-def-stmt stmtsep) / 1*((data-def-stmt stmtsep) /
(case-stmt stmtsep)) (case-stmt stmtsep))
skipping to change at page 160, line 16 skipping to change at page 156, line 38
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
*(if-feature-stmt stmtsep) *(if-feature-stmt stmtsep)
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
1*((data-def-stmt stmtsep) / 1*((data-def-stmt stmtsep) /
(case-stmt stmtsep)) (case-stmt stmtsep))
"}" "}"
augment-arg-str = < a string which matches the rule augment-arg-str = < a string that matches the rule
augment-arg > augment-arg >
augment-arg = absolute-schema-nodeid augment-arg = absolute-schema-nodeid
unknown-statement = prefix ":" identifier [sep string] optsep unknown-statement = prefix ":" identifier [sep string] optsep
(";" / "{" *unknown-statement2 "}") (";" / "{" *unknown-statement2 "}")
unknown-statement2 = [prefix ":"] identifier [sep string] optsep unknown-statement2 = [prefix ":"] identifier [sep string] optsep
(";" / "{" *unknown-statement2 "}") (";" / "{" *unknown-statement2 "}")
skipping to change at page 161, line 43 skipping to change at page 158, line 17
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
(deviate-not-supported-stmt / (deviate-not-supported-stmt /
1*(deviate-add-stmt / 1*(deviate-add-stmt /
deviate-replace-stmt / deviate-replace-stmt /
deviate-delete-stmt)) deviate-delete-stmt))
"}" "}"
deviation-arg-str = < a string which matches the rule deviation-arg-str = < a string that matches the rule
deviation-arg > deviation-arg >
deviation-arg = absolute-schema-nodeid deviation-arg = absolute-schema-nodeid
deviate-not-supported-stmt = deviate-not-supported-stmt =
deviate-keyword sep deviate-keyword sep
not-supported-keyword optsep not-supported-keyword optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
"}") "}")
skipping to change at page 162, line 43 skipping to change at page 159, line 19
[units-stmt stmtsep] [units-stmt stmtsep]
[default-stmt stmtsep] [default-stmt stmtsep]
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
"}") "}")
;; Ranges ;; Ranges
range-arg-str = < a string which matches the rule range-arg-str = < a string that matches the rule
range-arg > range-arg >
range-arg = range-part *(optsep "|" optsep range-part) range-arg = range-part *(optsep "|" optsep range-part)
range-part = range-boundary range-part = range-boundary
[optsep ".." optsep range-boundary] [optsep ".." optsep range-boundary]
range-boundary = min-keyword / max-keyword / range-boundary = min-keyword / max-keyword /
integer-value / decimal-value integer-value / decimal-value
;; Lengths ;; Lengths
length-arg-str = < a string which matches the rule length-arg-str = < a string that matches the rule
length-arg > length-arg >
length-arg = length-part *(optsep "|" optsep length-part) length-arg = length-part *(optsep "|" optsep length-part)
length-part = length-boundary length-part = length-boundary
[optsep ".." optsep length-boundary] [optsep ".." optsep length-boundary]
length-boundary = min-keyword / max-keyword / length-boundary = min-keyword / max-keyword /
non-negative-integer-value non-negative-integer-value
;; Date ;; Date
date-arg-str = < a string which matches the rule date-arg-str = < a string that matches the rule
date-arg > date-arg >
date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT date-arg = 4DIGIT "-" 2DIGIT "-" 2DIGIT
;; Schema Node Identifiers ;; Schema Node Identifiers
schema-nodeid = absolute-schema-nodeid / schema-nodeid = absolute-schema-nodeid /
descendant-schema-nodeid descendant-schema-nodeid
absolute-schema-nodeid = 1*("/" node-identifier) absolute-schema-nodeid = 1*("/" node-identifier)
descendant-schema-nodeid = descendant-schema-nodeid =
node-identifier node-identifier
absolute-schema-nodeid absolute-schema-nodeid
skipping to change at page 164, line 4 skipping to change at page 160, line 28
instance-identifier = 1*("/" (node-identifier *predicate)) instance-identifier = 1*("/" (node-identifier *predicate))
predicate = "[" *WSP (predicate-expr / pos) *WSP "]" predicate = "[" *WSP (predicate-expr / pos) *WSP "]"
predicate-expr = (node-identifier / ".") *WSP "=" *WSP predicate-expr = (node-identifier / ".") *WSP "=" *WSP
((DQUOTE string DQUOTE) / ((DQUOTE string DQUOTE) /
(SQUOTE string SQUOTE)) (SQUOTE string SQUOTE))
pos = non-negative-integer-value pos = non-negative-integer-value
;; leafref path ;; leafref path
path-arg-str = < a string which matches the rule path-arg-str = < a string that matches the rule
path-arg > path-arg >
path-arg = absolute-path / relative-path path-arg = absolute-path / relative-path
absolute-path = 1*("/" (node-identifier *path-predicate)) absolute-path = 1*("/" (node-identifier *path-predicate))
relative-path = 1*(".." "/") descendant-path relative-path = 1*(".." "/") descendant-path
descendant-path = node-identifier descendant-path = node-identifier
[*path-predicate absolute-path] [*path-predicate absolute-path]
skipping to change at page 166, line 18 skipping to change at page 163, line 4
false-keyword = 'false' false-keyword = 'false'
max-keyword = 'max' max-keyword = 'max'
min-keyword = 'min' min-keyword = 'min'
not-supported-keyword = 'not-supported' not-supported-keyword = 'not-supported'
obsolete-keyword = 'obsolete' obsolete-keyword = 'obsolete'
replace-keyword = 'replace' replace-keyword = 'replace'
system-keyword = 'system' system-keyword = 'system'
true-keyword = 'true' true-keyword = 'true'
unbounded-keyword = 'unbounded' unbounded-keyword = 'unbounded'
user-keyword = 'user' user-keyword = 'user'
current-function-invocation = current-keyword *WSP "(" *WSP ")" current-function-invocation = current-keyword *WSP "(" *WSP ")"
;; Basic Rules ;; Basic Rules
prefix-arg-str = < a string which matches the rule prefix-arg-str = < a string that matches the rule
prefix-arg > prefix-arg >
prefix-arg = prefix prefix-arg = prefix
prefix = identifier prefix = identifier
identifier-arg-str = < a string which matches the rule identifier-arg-str = < a string that matches the rule
identifier-arg > identifier-arg >
identifier-arg = identifier identifier-arg = identifier
;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l')) ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l'))
identifier = (ALPHA / "_") identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".") *(ALPHA / DIGIT / "_" / "-" / ".")
identifier-ref-arg-str = < a string which matches the rule identifier-ref-arg-str = < a string that matches the rule
identifier-ref-arg > identifier-ref-arg >
identifier-ref-arg = [prefix ":"] identifier identifier-ref-arg = [prefix ":"] identifier
string = < an unquoted string as returned by string = < an unquoted string as returned by
the scanner > the scanner >
integer-value = ("-" non-negative-integer-value) / integer-value = ("-" non-negative-integer-value) /
non-negative-integer-value non-negative-integer-value
skipping to change at page 167, line 37 skipping to change at page 164, line 22
;; RFC 5234 core rules. ;; RFC 5234 core rules.
;; ;;
ALPHA = %x41-5A / %x61-7A ALPHA = %x41-5A / %x61-7A
; A-Z / a-z ; A-Z / a-z
CR = %x0D CR = %x0D
; carriage return ; carriage return
CRLF = CR LF CRLF = CR LF
; Internet standard newline ; Internet standard new line
DIGIT = %x30-39 DIGIT = %x30-39
; 0-9 ; 0-9
DQUOTE = %x22 DQUOTE = %x22
; " (Double Quote) ; " (Double Quote)
HEXDIG = DIGIT / HEXDIG = DIGIT /
%x61 / %x62 / %x63 / %x64 / %x65 / %x66 %x61 / %x62 / %x63 / %x64 / %x65 / %x66
; only lower-case a..f ; only lower-case a..f
skipping to change at page 169, line 12 skipping to change at page 165, line 12
<CODE ENDS> <CODE ENDS>
13. Error Responses for YANG Related Errors 13. Error Responses for YANG Related Errors
A number of NETCONF error responses are defined for error cases A number of NETCONF error responses are defined for error cases
related to the data-model handling. If the relevant YANG statement related to the data-model handling. If the relevant YANG statement
has an "error-app-tag" substatement, that overrides the default value has an "error-app-tag" substatement, that overrides the default value
specified below. specified below.
13.1. Error Message for Data that Violates a unique Statement 13.1. Error Message for Data That Violates a unique Statement
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
unique constraint is invalidated, the following error is returned: unique constraint is invalidated, the following error is returned:
error-tag: operation-failed error-tag: operation-failed
error-app-tag: data-not-unique error-app-tag: data-not-unique
error-info: <non-unique>: Contains an instance identifier which error-info: <non-unique>: Contains an instance identifier that
points to a leaf which invalidates the unique points to a leaf that invalidates the unique
constraint. This element is present once for each constraint. This element is present once for each
non-unique leaf. non-unique leaf.
The <non-unique> element is in the YANG The <non-unique> element is in the YANG
namespace ("urn:ietf:params:xml:ns:yang:1"). namespace ("urn:ietf:params:xml:ns:yang:1").
13.2. Error Message for Data that Violates a max-elements Statement 13.2. Error Message for Data That Violates a max-elements Statement
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
list or a leaf-list would have too many entries the following error list or a leaf-list would have too many entries the following error
is returned: is returned:
error-tag: operation-failed error-tag: operation-failed
error-app-tag: too-many-elements error-app-tag: too-many-elements
This error is returned once, with the error-path identifying the list This error is returned once, with the error-path identifying the list
node, even if there are more than one extra child present. node, even if there are more than one extra child present.
13.3. Error Message for Data that Violates a min-elements Statement 13.3. Error Message for Data That Violates a min-elements Statement
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
list or a leaf-list would have too few entries the following error is list or a leaf-list would have too few entries the following error is
returned: returned:
error-tag: operation-failed error-tag: operation-failed
error-app-tag: too-few-elements error-app-tag: too-few-elements
This error is returned once, with the error-path identifying the list This error is returned once, with the error-path identifying the list
node, even if there are more than one child missing. node, even if there are more than one child missing.
13.4. Error Message for Data that Violates a must Statement 13.4. Error Message for Data That Violates a must Statement
If a NETCONF operation would result in configuration data where the If a NETCONF operation would result in configuration data where the
restrictions imposed by a "must" statement is violated the following restrictions imposed by a "must" statement is violated the following
error is returned, unless a specific "error-app-tag" substatement is error is returned, unless a specific "error-app-tag" substatement is
present for the "must" statement. present for the "must" statement.
error-tag: operation-failed error-tag: operation-failed
error-app-tag: must-violation error-app-tag: must-violation
13.5. Error Message for Data that Violates a require-instance Statement 13.5. Error Message for Data That Violates a require-instance Statement
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
leaf of type "instance-identifier" marked with require-instance leaf of type "instance-identifier" marked with require-instance
"true" refers to a non-existing instance, the following error is "true" refers to a non-existing instance, the following error is
returned: returned:
error-tag: data-missing error-tag: data-missing
error-app-tag: instance-required error-app-tag: instance-required
error-path: Path to the instance-identifier leaf. error-path: Path to the instance-identifier leaf.
13.6. Error Message for Data that does not Match a leafref Type 13.6. Error Message for Data That Does Not Match a leafref Type
If a NETCONF operation would result in configuration data where a If a NETCONF operation would result in configuration data where a
leaf of type "leafref" refers to a non-existing instance, the leaf of type "leafref" refers to a non-existing instance, the
following error is returned: following error is returned:
error-tag: data-missing error-tag: data-missing
error-app-tag: instance-required error-app-tag: instance-required
error-path: Path to the leafref leaf. error-path: Path to the leafref leaf.
13.7. Error Message for Data that Violates a mandatory choice Statement 13.7. Error Message for Data That Violates a mandatory choice Statement
If a NETCONF operation would result in configuration data where no If a NETCONF operation would result in configuration data where no
nodes exists in a mandatory choice, the following error is returned: nodes exists in a mandatory choice, the following error is returned:
error-tag: data-missing error-tag: data-missing
error-app-tag: missing-choice error-app-tag: missing-choice
error-path: Path to the element with the missing choice. error-path: Path to the element with the missing choice.
error-info: <missing-choice>: Contains the name of the missing error-info: <missing-choice>: Contains the name of the missing
mandatory choice. mandatory choice.
skipping to change at page 172, line 31 skipping to change at page 167, line 40
number) number)
There are no initial assignments. There are no initial assignments.
For allocation, RFC publication is required as per RFC 5226 For allocation, RFC publication is required as per RFC 5226
[RFC5226]. All registered YANG module names MUST comply with the [RFC5226]. All registered YANG module names MUST comply with the
rules for identifiers stated in Section 6.2, and MUST have a module rules for identifiers stated in Section 6.2, and MUST have a module
name prefix. name prefix.
The module name prefix 'ietf-' is reserved for IETF stream documents The module name prefix 'ietf-' is reserved for IETF stream documents
[RFC4844] while the module name prefix 'irtf-' is reserved for IRTF [RFC4844], while the module name prefix 'irtf-' is reserved for IRTF
stream documents. Modules published in other RFC streams MUST have a stream documents. Modules published in other RFC streams MUST have a
similar suitable prefix. similar suitable prefix.
All module and submodule names in the registry MUST be unique. All module and submodule names in the registry MUST be unique.
All XML namespaces in the registry MUST be unique. All XML namespaces in the registry MUST be unique.
This document registers two URIs for the YANG and YIN XML namespaces This document registers two URIs for the YANG and YIN XML namespaces
in the IETF XML registry [RFC3688]. Following the format in RFC in the IETF XML registry [RFC3688]. Following the format in RFC
3688, the following registration is requested. 3688, the following have been registered.
URI: urn:ietf:params:xml:ns:yang:yin:1 URI: urn:ietf:params:xml:ns:yang:yin:1
URI: urn:ietf:params:xml:ns:yang:1 URI: urn:ietf:params:xml:ns:yang:1
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URIs are XML namespaces. XML: N/A, the requested URIs are XML namespaces.
This document registers two new media types as defined in the This document registers two new media types as defined in the
following sections. following sections.
skipping to change at page 173, line 15 skipping to change at page 168, line 23
14.1. Media type application/yang 14.1. Media type application/yang
MIME media type name: application MIME media type name: application
MIME subtype name: yang MIME subtype name: yang
Mandatory parameters: none Mandatory parameters: none
Optional parameters: none Optional parameters: none
Encoding considerations: 8bit Encoding considerations: 8-bit
Security considerations: See section 15 in RFC XXXX Security considerations: See Section 15 in RFC 6020
Interoperability considerations: None Interoperability considerations: None
Published specification: RFC XXXX (currently draft-ietf-netmod-yang) Published specification: RFC 6020
Applications that use this media type: Applications that use this media type:
YANG module validators, web servers used for downloading YANG YANG module validators, web servers used for downloading YANG
modules, email clients etc. modules, email clients, etc.
Additional information: Additional information:
Magic Number: None Magic Number: None
File Extension: .yang File Extension: .yang
Macintosh file type code: 'TEXT' Macintosh file type code: 'TEXT'
Personal and email address for further information: Personal and email address for further information:
skipping to change at page 174, line 4 skipping to change at page 169, line 9
Intended usage: COMMON Intended usage: COMMON
Author: Author:
This specification is a work item of the IETF NETMOD working group, This specification is a work item of the IETF NETMOD working group,
with mailing list address <netmod@ietf.org>. with mailing list address <netmod@ietf.org>.
Change controller: Change controller:
The IESG <iesg@ietf.org> The IESG <iesg@ietf.org>
14.2. Media type application/yin+xml 14.2. Media type application/yin+xml
MIME media type name: application MIME media type name: application
MIME subtype name: yin+xml MIME subtype name: yin+xml
Mandatory parameters: none Mandatory parameters: none
Optional parameters: Optional parameters:
"charset": This parameter has identical semantics to the charset "charset": This parameter has identical semantics to the charset
parameter of the "application/xml" media type as specified in parameter of the "application/xml" media type as specified in
[RFC3023]. [RFC3023].
Encoding considerations: Encoding considerations:
Identical to those of "application/xml" as Identical to those of "application/xml" as
described in [RFC3023], Section 3.2. described in [RFC3023], Section 3.2.
Security considerations: See section 15 in RFC XXXX Security considerations: See Section 15 in RFC 6020
Interoperability considerations: None Interoperability considerations: None
Published specification: RFC XXXX (currently draft-ietf-netmod-yang) Published specification: RFC 6020
Applications that use this media type: Applications that use this media type:
YANG module validators, web servers used for downloading YANG YANG module validators, web servers used for downloading YANG
modules, email clients etc. modules, email clients, etc.
Additional information: Additional information:
Magic Number: As specified for "application/xml" in [RFC3023], Magic Number: As specified for "application/xml" in [RFC3023],
Section 3.2. Section 3.2.
File Extension: .yin File Extension: .yin
Macintosh file type code: 'TEXT' Macintosh file type code: 'TEXT'
skipping to change at page 175, line 12 skipping to change at page 170, line 18
Change controller: Change controller:
The IESG <iesg@ietf.org> The IESG <iesg@ietf.org>
15. Security Considerations 15. Security Considerations
This document defines a language with which to write and read This document defines a language with which to write and read
descriptions of management information. The language itself has no descriptions of management information. The language itself has no
security impact on the Internet. security impact on the Internet.
The same considerations are relevant as for the base NETCONF protocol The same considerations are relevant as for the base NETCONF protocol
(see [RFC4741], section 9). (see [RFC4741], Section 9).
Data modeled in YANG might contain sensitive information. RPCs or Data modeled in YANG might contain sensitive information. RPCs or
notifications defined in YANG might transfer sensitive information. notifications defined in YANG might transfer sensitive information.
Security issues are related to the usage of data modeled in YANG. Security issues are related to the usage of data modeled in YANG.
Such issues shall be dealt with in documents describing the data Such issues shall be dealt with in documents describing the data
models and documents about the interfaces used to manipulate the data models and documents about the interfaces used to manipulate the data
e.g., the NETCONF documents. e.g., the NETCONF documents.
Data modeled in YANG is dependent upon: Data modeled in YANG is dependent upon:
o the security of the transmission infrastructure used to send o the security of the transmission infrastructure used to send
sensitive information sensitive information.
o the security of applications which store or release such sensitive o the security of applications that store or release such sensitive
information. information.
o adequate authentication and access control mechanisms to restrict o adequate authentication and access control mechanisms to restrict
the usage of sensitive data. the usage of sensitive data.
YANG parsers need to be robust with respect to malformed documents. YANG parsers need to be robust with respect to malformed documents.
Reading malformed documents from unknown or untrusted sources could Reading malformed documents from unknown or untrusted sources could
result in an attacker gaining privileges of the user running the YANG result in an attacker gaining privileges of the user running the YANG
parser. In an extreme situation, the entire machine could be parser. In an extreme situation, the entire machine could be
compromised. compromised.
16. Contributors 16. Contributors
The following people all contributed significantly to the initial The following people all contributed significantly to the initial
YANG draft: YANG document:
- Andy Bierman (Netconf Central) - Andy Bierman (Brocade)
- Balazs Lengyel (Ericsson) - Balazs Lengyel (Ericsson)
- David Partain (Ericsson) - David Partain (Ericsson)
- Juergen Schoenwaelder (Jacobs University Bremen) - Juergen Schoenwaelder (Jacobs University Bremen)
- Phil Shafer (Juniper Networks) - Phil Shafer (Juniper Networks)
17. Acknowledgements 17. Acknowledgements
The editor wishes to thank the following individuals, who all The editor wishes to thank the following individuals, who all
provided helpful comments on various versions of this document: provided helpful comments on various versions of this document:
Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav Mehmet Ersue, Washam Fan, Joel Halpern, Leif Johansson, Ladislav
Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert Lhotka, Gerhard Muenz, Tom Petch, Randy Presuhn, David Reid, and Bert
Wijnen. Wijnen.
18. References 18. References
18