draft-ietf-netmod-yang-02.txt   draft-ietf-netmod-yang-03.txt 
Network Working Group M. Bjorklund, Ed. Network Working Group M. Bjorklund, Ed.
Internet-Draft Tail-f Systems Internet-Draft Tail-f Systems
Intended status: Standards Track November 3, 2008 Intended status: Standards Track January 12, 2009
Expires: May 7, 2009 Expires: July 16, 2009
YANG - A data modeling language for NETCONF YANG - A data modeling language for NETCONF
draft-ietf-netmod-yang-02 draft-ietf-netmod-yang-03
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any This Internet-Draft is submitted to IETF in full conformance with the
applicable patent or other IPR claims of which he or she is aware provisions of BCP 78 and BCP 79.
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on May 7, 2009. This Internet-Draft will expire on July 16, 2009.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2008). Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Abstract Abstract
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
state data manipulated by the NETCONF protocol, NETCONF remote state data manipulated by the NETCONF protocol, NETCONF remote
procedure calls, and NETCONF notifications. procedure calls, and NETCONF notifications.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12 3.1. Mandatory nodes . . . . . . . . . . . . . . . . . . . . . 12
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 14
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15
4.2.3. Operational Data . . . . . . . . . . . . . . . . . . 20 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19
4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 20 4.2.4. Built-in Types . . . . . . . . . . . . . . . . . . . 19
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 20
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 21
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 22
4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 23
4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 25 4.2.9. RPC Definitions . . . . . . . . . . . . . . . . . . . 24
4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 4.2.10. Notification Definitions . . . . . . . . . . . . . . 25
5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27
5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27
5.1.1. Module Hierarchies . . . . . . . . . . . . . . . . . 28 5.1.1. Import and Include by Revision . . . . . . . . . . . 28
5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 28 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 28
5.3. Object Based View of YANG . . . . . . . . . . . . . . . . 29 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 29
5.4. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 29 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 30
5.4.1. YANG Namespace . . . . . . . . . . . . . . . . . . . 30 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 30
5.5. Ordering . . . . . . . . . . . . . . . . . . . . . . . . 30 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 30
5.6. Containers with Presence . . . . . . . . . . . . . . . . 31 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 30
5.7. Scoping . . . . . . . . . . . . . . . . . . . . . . . . . 32 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 31
5.8. Nested Typedefs and Groupings . . . . . . . . . . . . . . 32 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 31
5.9. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 32
5.9.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 32
5.9.2. Optional Features . . . . . . . . . . . . . . . . . . 33 5.6.4. Announcing Conformance Information in the <hello>
5.9.3. Deviations . . . . . . . . . . . . . . . . . . . . . 34 Message . . . . . . . . . . . . . . . . . . . . . . . 33
5.9.4. Announcing Conformance Information in the <hello> 5.6.5. Mapping to the NETCONF Schema Discovery Mechanism . . 35
Message . . . . . . . . . . . . . . . . . . . . . . . 34
6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36 6. YANG syntax . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36 6.1. Lexicographical Tokenization . . . . . . . . . . . . . . 36
6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 36
6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 36
6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 38
6.2.1. Identifiers and their namespaces . . . . . . . . . . 38 6.2.1. Identifiers and their namespaces . . . . . . . . . . 38
6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 39
6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 39
6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 39
7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 40
7.1. The module Statement . . . . . . . . . . . . . . . . . . 40 7.1. The module Statement . . . . . . . . . . . . . . . . . . 40
7.1.1. The module's Substatements . . . . . . . . . . . . . 41 7.1.1. The module's Substatements . . . . . . . . . . . . . 41
7.1.2. The yang-version Statement . . . . . . . . . . . . . 42 7.1.2. The yang-version Statement . . . . . . . . . . . . . 42
7.1.3. The namespace Statement . . . . . . . . . . . . . . . 43 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 42
7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 43 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 43
7.1.5. The import Statement . . . . . . . . . . . . . . . . 43 7.1.5. The import Statement . . . . . . . . . . . . . . . . 43
7.1.6. The include Statement . . . . . . . . . . . . . . . . 44 7.1.6. The include Statement . . . . . . . . . . . . . . . . 44
7.1.7. The organization Statement . . . . . . . . . . . . . 44 7.1.7. The organization Statement . . . . . . . . . . . . . 44
7.1.8. The contact Statement . . . . . . . . . . . . . . . . 44 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 44
7.1.9. The revision Statement . . . . . . . . . . . . . . . 44 7.1.9. The revision Statement . . . . . . . . . . . . . . . 45
7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 45 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 46
7.2. The submodule Statement . . . . . . . . . . . . . . . . . 45 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 46
7.2.1. The submodule's Substatements . . . . . . . . . . . . 47 7.2.1. The submodule's Substatements . . . . . . . . . . . . 47
7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 48 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 48
7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 49 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 49
7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 49 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 49
7.3.1. The typedef's Substatements . . . . . . . . . . . . . 50 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 50
7.3.2. The typedef's type Statement . . . . . . . . . . . . 50 7.3.2. The typedef's type Statement . . . . . . . . . . . . 50
7.3.3. The units Statement . . . . . . . . . . . . . . . . . 50 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 50
7.3.4. The typedef's default Statement . . . . . . . . . . . 50 7.3.4. The typedef's default Statement . . . . . . . . . . . 50
7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 51 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 51
7.4. The type Statement . . . . . . . . . . . . . . . . . . . 51 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 51
7.4.1. The type's Substatements . . . . . . . . . . . . . . 51 7.4.1. The type's Substatements . . . . . . . . . . . . . . 51
7.5. The container Statement . . . . . . . . . . . . . . . . . 51 7.5. The container Statement . . . . . . . . . . . . . . . . . 51
7.5.1. The container's Substatements . . . . . . . . . . . . 52 7.5.1. Containers with Presence . . . . . . . . . . . . . . 52
7.5.2. The must Statement . . . . . . . . . . . . . . . . . 52 7.5.2. The container's Substatements . . . . . . . . . . . . 53
7.5.3. The must's Substatements . . . . . . . . . . . . . . 53 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 53
7.5.4. The presence Statement . . . . . . . . . . . . . . . 54 7.5.4. The must's Substatements . . . . . . . . . . . . . . 55
7.5.5. The container's Child Node Statements . . . . . . . . 55 7.5.5. The presence Statement . . . . . . . . . . . . . . . 56
7.5.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 55 7.5.6. The container's Child Node Statements . . . . . . . . 56
7.5.7. NETCONF <edit-config> Operations . . . . . . . . . . 55 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 56
7.5.8. Usage Example . . . . . . . . . . . . . . . . . . . . 56 7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 56
7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 57 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 57
7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 58 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 58
7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 58 7.6.1. The leaf's Substatements . . . . . . . . . . . . . . 59
7.6.3. The leaf's default Statement . . . . . . . . . . . . 58 7.6.2. The leaf's type Statement . . . . . . . . . . . . . . 59
7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 58 7.6.3. The leaf's default Statement . . . . . . . . . . . . 59
7.6.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 59 7.6.4. The leaf's mandatory Statement . . . . . . . . . . . 59
7.6.6. NETCONF <edit-config> Operations . . . . . . . . . . 59 7.6.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 60
7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 59 7.6.6. NETCONF <edit-config> Operations . . . . . . . . . . 60
7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 60 7.6.7. Usage Example . . . . . . . . . . . . . . . . . . . . 60
7.7.1. The leaf-list's Substatements . . . . . . . . . . . . 61 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 61
7.7.2. The min-elements Statement . . . . . . . . . . . . . 61 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 61
7.7.3. The max-elements Statement . . . . . . . . . . . . . 61 7.7.2. The leaf-list's Substatements . . . . . . . . . . . . 63
7.7.4. The ordered-by Statement . . . . . . . . . . . . . . 61 7.7.3. The min-elements Statement . . . . . . . . . . . . . 63
7.7.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 62 7.7.4. The max-elements Statement . . . . . . . . . . . . . 63
7.7.6. NETCONF <edit-config> operations . . . . . . . . . . 62 7.7.5. The ordered-by Statement . . . . . . . . . . . . . . 63
7.7.7. Usage Example . . . . . . . . . . . . . . . . . . . . 63 7.7.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 64
7.8. The list Statement . . . . . . . . . . . . . . . . . . . 65 7.7.7. NETCONF <edit-config> operations . . . . . . . . . . 64
7.8.1. The list's Substatements . . . . . . . . . . . . . . 65 7.7.8. Usage Example . . . . . . . . . . . . . . . . . . . . 65
7.8.2. The list's key Statement . . . . . . . . . . . . . . 66 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 67
7.8.3. The lists's unique Statement . . . . . . . . . . . . 67 7.8.1. The list's Substatements . . . . . . . . . . . . . . 67
7.8.4. The list's Child Node Statements . . . . . . . . . . 68 7.8.2. The list's key Statement . . . . . . . . . . . . . . 68
7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 68 7.8.3. The lists's unique Statement . . . . . . . . . . . . 69
7.8.6. NETCONF <edit-config> operations . . . . . . . . . . 68 7.8.4. The list's Child Node Statements . . . . . . . . . . 70
7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 69 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 70
7.9. The choice Statement . . . . . . . . . . . . . . . . . . 72 7.8.6. NETCONF <edit-config> operations . . . . . . . . . . 70
7.9.1. The choice's Substatements . . . . . . . . . . . . . 73 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 71
7.9.2. The choice's case Statement . . . . . . . . . . . . . 73 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 74
7.9.3. The choice's default Statement . . . . . . . . . . . 74 7.9.1. The choice's Substatements . . . . . . . . . . . . . 75
7.9.4. The choice's mandatory Statement . . . . . . . . . . 76 7.9.2. The choice's case Statement . . . . . . . . . . . . . 75
7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 76 7.9.3. The choice's default Statement . . . . . . . . . . . 76
7.9.6. NETCONF <edit-config> operations . . . . . . . . . . 76 7.9.4. The choice's mandatory Statement . . . . . . . . . . 78
7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 76 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 78
7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 77 7.9.6. NETCONF <edit-config> operations . . . . . . . . . . 78
7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 78 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 78
7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 78 7.10. The anyxml Statement . . . . . . . . . . . . . . . . . . 79
7.10.3. NETCONF <edit-config> operations . . . . . . . . . . 78 7.10.1. The anyxml's Substatements . . . . . . . . . . . . . 80
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 79 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 80
7.11. The grouping Statement . . . . . . . . . . . . . . . . . 79 7.10.3. NETCONF <edit-config> operations . . . . . . . . . . 80
7.11.1. The grouping's Substatements . . . . . . . . . . . . 80 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 81
7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 80 7.11. The grouping Statement . . . . . . . . . . . . . . . . . 81
7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 80 7.11.1. The grouping's Substatements . . . . . . . . . . . . 82
7.12.1. The uses's Substatements . . . . . . . . . . . . . . 81 7.11.2. Usage Example . . . . . . . . . . . . . . . . . . . . 82
7.12.2. The refine Statement . . . . . . . . . . . . . . . . 81 7.12. The uses Statement . . . . . . . . . . . . . . . . . . . 82
7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 82 7.12.1. The uses's Substatements . . . . . . . . . . . . . . 83
7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 82 7.12.2. The refine Statement . . . . . . . . . . . . . . . . 83
7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 83 7.12.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 84
7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 84 7.12.4. Usage Example . . . . . . . . . . . . . . . . . . . . 84
7.13.2. The input Statement . . . . . . . . . . . . . . . . . 84 7.13. The rpc Statement . . . . . . . . . . . . . . . . . . . . 85
7.13.3. The output Statement . . . . . . . . . . . . . . . . 85 7.13.1. The rpc's Substatements . . . . . . . . . . . . . . . 86
7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 86 7.13.2. The input Statement . . . . . . . . . . . . . . . . . 86
7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 86 7.13.3. The output Statement . . . . . . . . . . . . . . . . 87
7.14. The notification Statement . . . . . . . . . . . . . . . 87 7.13.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 88
7.14.1. The notification's Substatements . . . . . . . . . . 88 7.13.5. Usage Example . . . . . . . . . . . . . . . . . . . . 88
7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 88 7.14. The notification Statement . . . . . . . . . . . . . . . 89
7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 88 7.14.1. The notification's Substatements . . . . . . . . . . 90
7.15. The augment Statement . . . . . . . . . . . . . . . . . . 89 7.14.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 90
7.15.1. The augment's Substatements . . . . . . . . . . . . . 90 7.14.3. Usage Example . . . . . . . . . . . . . . . . . . . . 90
7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 90 7.15. The augment Statement . . . . . . . . . . . . . . . . . . 91
7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 91 7.15.1. The augment's Substatements . . . . . . . . . . . . . 92
7.16. The identity Statement . . . . . . . . . . . . . . . . . 93 7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 92
7.16.1. The identity's Substatements . . . . . . . . . . . . 93 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . . 93
7.16.2. The base Statement . . . . . . . . . . . . . . . . . 93 7.16. The identity Statement . . . . . . . . . . . . . . . . . 95
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 94 7.16.1. The identity's Substatements . . . . . . . . . . . . 95
7.17. The extension Statement . . . . . . . . . . . . . . . . . 94 7.16.2. The base Statement . . . . . . . . . . . . . . . . . 95
7.17.1. The extension's Substatements . . . . . . . . . . . . 95 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . . 96
7.17.2. The argument Statement . . . . . . . . . . . . . . . 95 7.17. The extension Statement . . . . . . . . . . . . . . . . . 96
7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 96 7.17.1. The extension's Substatements . . . . . . . . . . . . 97
7.18. Conformance-related Statements . . . . . . . . . . . . . 96 7.17.2. The argument Statement . . . . . . . . . . . . . . . 97
7.18.1. The feature Statement . . . . . . . . . . . . . . . . 96 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . . 98
7.18.2. The if-feature Statement . . . . . . . . . . . . . . 98 7.18. Conformance-related Statements . . . . . . . . . . . . . 98
7.18.3. The deviation Statement . . . . . . . . . . . . . . . 98 7.18.1. The feature Statement . . . . . . . . . . . . . . . . 98
7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 101 7.18.2. The if-feature Statement . . . . . . . . . . . . . . 100
7.19.1. The config Statement . . . . . . . . . . . . . . . . 101 7.18.3. The deviation Statement . . . . . . . . . . . . . . . 100
7.19.2. The status Statement . . . . . . . . . . . . . . . . 101 7.19. Common Statements . . . . . . . . . . . . . . . . . . . . 103
7.19.3. The description Statement . . . . . . . . . . . . . . 102 7.19.1. The config Statement . . . . . . . . . . . . . . . . 103
7.19.4. The reference Statement . . . . . . . . . . . . . . . 102 7.19.2. The status Statement . . . . . . . . . . . . . . . . 103
7.19.5. The when Statement . . . . . . . . . . . . . . . . . 102 7.19.3. The description Statement . . . . . . . . . . . . . . 104
8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 104 7.19.4. The reference Statement . . . . . . . . . . . . . . . 104
9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 105 7.19.5. The when Statement . . . . . . . . . . . . . . . . . 104
9.1. Canonical representation . . . . . . . . . . . . . . . . 105 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 106
9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 105 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 106
9.2.1. Lexicographic Representation . . . . . . . . . . . . 106 8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 106
9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 106 8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 106
9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 106 8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 107
9.2.4. The range Statement . . . . . . . . . . . . . . . . . 107 8.3.2. NETCONF <edit-config> Processing . . . . . . . . . . 107
9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 108 8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 108
9.3. The Floating Point Built-in Types . . . . . . . . . . . . 108 9. Built-in Types . . . . . . . . . . . . . . . . . . . . . . . 109
9.3.1. Lexicographic Representation . . . . . . . . . . . . 108 9.1. Canonical representation . . . . . . . . . . . . . . . . 109
9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 108 9.2. The Integer Built-in Types . . . . . . . . . . . . . . . 109
9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 108 9.2.1. Lexicographic Representation . . . . . . . . . . . . 110
9.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 109 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 111
9.4. The string Built-in Type . . . . . . . . . . . . . . . . 109 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 111
9.4.1. Lexicographic Representation . . . . . . . . . . . . 109 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 111
9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 109 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 112
9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 109 9.3. The Floating Point Built-in Types . . . . . . . . . . . . 112
9.4.4. The length Statement . . . . . . . . . . . . . . . . 109 9.3.1. Lexicographic Representation . . . . . . . . . . . . 112
9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 110 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 112
9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 111 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 112
9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 111 9.3.4. Usage Example . . . . . . . . . . . . . . . . . . . . 113
9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 111 9.4. The string Built-in Type . . . . . . . . . . . . . . . . 113
9.5.1. Lexicographic Representation . . . . . . . . . . . . 112 9.4.1. Lexicographic Representation . . . . . . . . . . . . 113
9.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 112 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 113
9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 112 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 113
9.6.1. Lexicographic Representation . . . . . . . . . . . . 112 9.4.4. The length Statement . . . . . . . . . . . . . . . . 113
9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 112 9.4.5. Usage Example . . . . . . . . . . . . . . . . . . . . 114
9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 112 9.4.6. The pattern Statement . . . . . . . . . . . . . . . . 115
9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 112 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 115
9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 113 9.5. The boolean Built-in Type . . . . . . . . . . . . . . . . 115
9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 114 9.5.1. Lexicographic Representation . . . . . . . . . . . . 116
9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 114 9.5.2. Restrictions . . . . . . . . . . . . . . . . . . . . 116
9.7.2. Lexicographic Representation . . . . . . . . . . . . 114 9.6. The enumeration Built-in Type . . . . . . . . . . . . . . 116
9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 114 9.6.1. Lexicographic Representation . . . . . . . . . . . . 116
9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 114 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 116
9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 115 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 116
9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 115 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 116
9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 116 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117
9.8.2. Lexicographic Representation . . . . . . . . . . . . 116 9.7. The bits Built-in Type . . . . . . . . . . . . . . . . . 118
9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 116 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 118
9.9. The keyref Built-in Type . . . . . . . . . . . . . . . . 116 9.7.2. Lexicographic Representation . . . . . . . . . . . . 118
9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 116 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 118
9.9.2. The path Statement . . . . . . . . . . . . . . . . . 116 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 118
9.9.3. Lexicographic Representation . . . . . . . . . . . . 117 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 119
9.9.4. Canonical Form . . . . . . . . . . . . . . . . . . . 117 9.8. The binary Built-in Type . . . . . . . . . . . . . . . . 119
9.9.5. Usage Example . . . . . . . . . . . . . . . . . . . . 117 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120
9.10. The identityref Built-in Type . . . . . . . . . . . . . . 118 9.8.2. Lexicographic Representation . . . . . . . . . . . . 120
9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 118 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 120
9.10.2. The identityref's base Statement . . . . . . . . . . 119 9.9. The leafref Built-in Type . . . . . . . . . . . . . . . . 120
9.10.3. Lexicographic Representation . . . . . . . . . . . . 119 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120
9.10.4. Usage Example . . . . . . . . . . . . . . . . . . . . 119 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 120
9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 120 9.9.3. The require-instance Statement . . . . . . . . . . . 121
9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 120 9.9.4. Lexicographic Representation . . . . . . . . . . . . 121
9.11.2. Lexicographic Representation . . . . . . . . . . . . 120 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 121
9.11.3. Canonical Representation . . . . . . . . . . . . . . 120 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 121
9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 120 9.10. The identityref Built-in Type . . . . . . . . . . . . . . 124
9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 120 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 124
9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 121 9.10.2. The identityref's base Statement . . . . . . . . . . 124
9.12.2. Lexicographic Representation . . . . . . . . . . . . 121 9.10.3. Lexicographic Representation . . . . . . . . . . . . 124
9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 121 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 124
9.13. The instance-identifier Built-in Type . . . . . . . . . . 121 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . . 124
9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 121 9.11. The empty Built-in Type . . . . . . . . . . . . . . . . . 125
9.13.2. Lexicographic Representation . . . . . . . . . . . . 121 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 126
9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 122 9.11.2. Lexicographic Representation . . . . . . . . . . . . 126
9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . . 122 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 126
10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 123 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . . 126
11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 9.12. The union Built-in Type . . . . . . . . . . . . . . . . . 126
11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 126 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127
11.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 126 9.12.2. Lexicographic Representation . . . . . . . . . . . . 127
11.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 128 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 127
11.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 129 9.13. The instance-identifier Built-in Type . . . . . . . . . . 127
11.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 129 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 127
12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 130 9.13.2. Lexicographic Representation . . . . . . . . . . . . 127
13. Error Responses for YANG Related Errors . . . . . . . . . . . 151 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 128
9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . . 128
10. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 129
11. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
11.1. Formal YIN Definition . . . . . . . . . . . . . . . . . . 132
11.2. Transformation Algorithm YANG-2-YIN . . . . . . . . . . . 132
11.2.1. Usage Example . . . . . . . . . . . . . . . . . . . . 134
11.3. Transformation Algorithm YIN-2-YANG . . . . . . . . . . . 135
11.3.1. Tabulation, Formatting . . . . . . . . . . . . . . . 135
12. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 136
13. Error Responses for YANG Related Errors . . . . . . . . . . . 158
13.1. Error Message for Data that Violates a YANG unique 13.1. Error Message for Data that Violates a YANG unique
Statement: . . . . . . . . . . . . . . . . . . . . . . . 151 Statement: . . . . . . . . . . . . . . . . . . . . . . . 158
13.2. Error Message for Data that Violates a YANG 13.2. Error Message for Data that Violates a YANG
max-elements Statement: . . . . . . . . . . . . . . . . . 151 max-elements Statement: . . . . . . . . . . . . . . . . . 158
13.3. Error Message for Data that Violates a YANG 13.3. Error Message for Data that Violates a YANG
min-elements Statement: . . . . . . . . . . . . . . . . . 151 min-elements Statement: . . . . . . . . . . . . . . . . . 158
13.4. Error Message for Data that Violates a YANG must 13.4. Error Message for Data that Violates a YANG must
statement: . . . . . . . . . . . . . . . . . . . . . . . 152 statement: . . . . . . . . . . . . . . . . . . . . . . . 159
13.5. Error Message for the "insert" Operation . . . . . . . . 152 13.5. Error Message for the "insert" Operation . . . . . . . . 159
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 153 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 160
15. Security Considerations . . . . . . . . . . . . . . . . . . . 154 15. Security Considerations . . . . . . . . . . . . . . . . . . . 161
16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 155 16. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 162
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 156 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 163
17.1. Normative References . . . . . . . . . . . . . . . . . . 156 17.1. Normative References . . . . . . . . . . . . . . . . . . 163
17.2. Non-Normative References . . . . . . . . . . . . . . . . 157 17.2. Non-Normative References . . . . . . . . . . . . . . . . 164
Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 158 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 165
A.1. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 158 A.1. Version -03 . . . . . . . . . . . . . . . . . . . . . . . 165
A.2. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 158 A.2. Version -02 . . . . . . . . . . . . . . . . . . . . . . . 165
A.3. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 159 A.3. Version -01 . . . . . . . . . . . . . . . . . . . . . . . 165
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 160 A.4. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 166
Intellectual Property and Copyright Statements . . . . . . . . . 161 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 168
1. Introduction 1. Introduction
Today, the NETCONF protocol [RFC4741] lacks a standardized way to Today, the NETCONF protocol [RFC4741] lacks a standardized way to
create data models. Instead, vendors are forced to use proprietary create data models. Instead, vendors are forced to use proprietary
solutions. In order for NETCONF to be a interoperable protocol, solutions. In order for NETCONF to be a interoperable protocol,
models must be defined in a vendor-neutral way. YANG provides the models must be defined in a vendor-neutral way. YANG provides the
language and rules for defining such models for use with NETCONF. language and rules for defining such models for use with NETCONF.
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration and
skipping to change at page 10, line 18 skipping to change at page 10, line 18
o augment: Adds new nodes to a previously defined node. o augment: Adds new nodes to a previously defined node.
o base type: The type from which a derived type was derived, which o base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type. may be either a built-in type or another derived type.
o built-in type: A YANG data type defined in the YANG language, such o built-in type: A YANG data type defined in the YANG language, such
as uint32 or string. as uint32 or string.
o choice: A node where only one of a number of identified o choice: A node where only one of a number of identified
alternative values is valid. alternative nodes 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 the o conformance: A measure of how accurately a device follows the
model. model.
o container: An interior node in the data tree which exist in at o container: An interior node in the data tree which exist in at
most one instance. A container node has no value, but rather a most one instance. A container node has no value, but rather a
skipping to change at page 13, line 10 skipping to change at page 13, line 10
value greater than zero. value greater than zero.
o A container node without a "presence" statement, which has has at o A container node without a "presence" statement, which has 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 nodes which can be used for YANG module defines a hierarchy of data which can be used for
NETCONF-based operations, including configuration, state data, remote NETCONF-based operations, including configuration, state data, remote
procedure calls (RPCs), and notifications. This allows a complete procedure calls (RPCs), and notifications. This allows a complete
description of all data sent between a NETCONF client and server. description of all data sent between a NETCONF client and server.
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 extended, allowing one module to submodules. The hierarchy can be extended, allowing one module to
add data nodes to the hierarchy defined in another module. This add data nodes to the hierarchy defined in another module. This
augmentation can be conditional, with new nodes to appearing only if augmentation can be conditional, with new nodes appearing only if
certain conditions are met. certain conditions are met.
YANG models can describe constraints to be enforced on the data, YANG models can describe constraints to be enforced on the data,
restricting the appearance or value of nodes based on the presence or restricting the appearance or value of nodes based on the presence or
value of other nodes in the hierarchy. These constraints are value of other nodes in the hierarchy. These constraints are
enforceable by either the client or the server, 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
skipping to change at page 13, line 47 skipping to change at page 13, line 47
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 complex types using reusable grouping YANG permits the definition of complex types using reusable grouping
of nodes. The instantiation of these groupings can refine or augment of nodes. The instantiation of these groupings can refine or augment
the nodes, allowing it to tailor the nodes to its particular needs. the nodes, allowing it to tailor the nodes to its particular needs.
Derived types and groupings can be defined in one module or submodule Derived types and groupings can be defined in one module or submodule
and used in either that location or in another module or submodule and used in either that location or in another module or submodule
that imports or includes it. that imports or includes it.
YANG organizational constructs include defining lists of nodes with YANG organizational constructs include defining lists where list
the same names and identifying the keys which distinguish list entries are identified by keys which distinguish them from each
members from each other. Such lists may be defined as either sorted other. Such lists may be defined as either sorted by user or
by user or automatically sorted by the system. For user-sorted automatically sorted by the system. For user-sorted lists,
lists, operations are defined for manipulating the order of the operations are defined for manipulating the order of the list
nodes. entries.
YANG modules can be translated into an XML format called YIN YANG modules can be translated into an XML format called YIN
(Section 11), allowing applications using XML parsers and XSLT (Section 11), allowing applications using XML parsers and XSLT
scripts to operate on the models. scripts to operate on the models. The conversion from YANG to YIN is
loss-less, so content in YIN can round-tripped back into YANG.
YANG strikes a balance between high-level object-oriented modeling YANG strikes a balance between high-level data modeling and low-level
and low-level bits-on-the-wire encoding. The reader of a YANG module bits-on-the-wire encoding. The reader of a YANG module can see the
can easily see the high-level view of the data model while seeing how high-level view of the data model while understanding how the data
the object 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 making extensions stand out statements in a natural way, while making extensions stand out
sufficiently for the reader to notice them. sufficiently for the reader to notice them.
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
skipping to change at page 14, line 41 skipping to change at page 14, line 42
Like NETCONF, YANG targets smooth integration with device's native Like NETCONF, YANG targets smooth integration with device's native
management infrastructure. This allows implementations to leverage management infrastructure. This allows implementations to leverage
their existing access control mechanisms to protect or expose their existing access control mechanisms to protect or expose
elements of the data model. 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
sections. sections. This progressive approach handles the inter-related nature
of YANG concepts and statements. Specifics about YANG statements and
syntax begins in Section 7.
4.2.1. Modules and Submodules 4.2.1. Modules and Submodules
YANG defines modules using the "module" statement. This statement A module contains three types of statements: module-header
defines the name of the module, which is typically used as the base statements, revision statements, and definition statements. The
name of the file containing the module. The file suffix ".yang" is module header statements describe the module and give information
typically used for YANG files. A module contains three types of about the module itself, the revision statements give information
statements: module-header statements, revision statements, and about the history of the module, and the definition statements are
definition statements. The module header statements describe the the body of the module where the data model is defined.
module and give information about the module itself, the revision
statements give information about the history of the module, and the
definition statements are the body of the module where the data model
is defined.
Submodule are partial modules that contribute derived types,
groupings, data nodes, RPCs and notifications to a module. A module
may include a number of submodules, but each submodule may belong to
only one module. The "include" statement allows a module or
submodule to reference material in submodules, and the "import"
statement allows references to material defined in other modules.
To reference an item that is defined in an external module it MUST be
imported. Identifiers that are neither defined, imported nor
included MUST NOT be visible in the local module.
To reference an item that is defined in one of its submodules, the
module MUST include the submodule.
A submodule that needs to reference an item defined in another
submodule of the same module, MUST include this submodule.
There MUST NOT be any circular chains of imports or includes. For A NETCONF server may implement a number of modules, allowing multiple
example, if submodule "a" includes submodule "b", "b" cannot include views of the same data, or multiple views of disjoint subsections of
"a". the device's data. Alternatively, the server may implement only one
module that defines all available data.
When a definition in an external module is referenced, a locally A module may be divided into submodules, based on the needs of the
defined prefix MUST be used, followed by ":", and then the external module owner. The external view remains that of a single module,
identifier. References to definitions in the local module MAY use regardless of the presence or size of its submodules.
the prefix notation. References to built-in data types (e.g., int32)
MUST NOT use the prefix notation.
Forward references are allowed in YANG. The "include" statement allows a module or submodule to reference
material in submodules, and the "import" statement allows references
to material defined in other modules.
4.2.2. Data Modeling Basics 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
skipping to change at page 17, line 15 skipping to change at page 16, line 49
<system> <system>
<login> <login>
<message>Good morning, Dave</message> <message>Good morning, Dave</message>
</login> </login>
</system> </system>
The "container" statement is covered in Section 7.5. The "container" statement is covered in Section 7.5.
4.2.2.4. List Nodes 4.2.2.4. List Nodes
A list is a sequence of list entries. An entry is like a structure A list defines a sequence of list entries. Each entry is like a
or a record. A list entry is uniquely identified by the values of structure or a record instance, and is uniquely identified by the
its key leafs. A list entry can have multiple keys. A list entry values of its key leafs. A list can define multiple keys and may
may contain any number of child nodes of any type (including leafs, contain any number of child nodes of any type (including leafs,
lists, containers etc.). lists, containers etc.).
YANG Example: YANG Example:
list user { list user {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf full-name { leaf full-name {
skipping to change at page 20, line 5 skipping to change at page 19, line 5
type string; type string;
} }
leaf class { leaf class {
type string; type string;
} }
} }
} }
} }
} }
4.2.3. Operational Data 4.2.3. State Data
YANG can model operational data, as well as configuration data, based YANG can model state data, as well as configuration data, based on
on the "config" statement. When a node is tagged with "config the "config" statement. When a node is tagged with "config false",
false", its subhierarchy is flagged as operational data, to be its subhierarchy is flagged as state data, to be reported using
reported using NETCONF's <get> operation, not the <get-config> NETCONF's <get> operation, not the <get-config> operation. Parent
operation. Parent containers, lists, and key leafs are reported containers, lists, and key leafs are reported also, giving the
also, giving the context for the operational 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 cannot be manipulated using <edit-config>.
list interface { list interface {
key "name"; key "name";
config true; config true;
skipping to change at page 21, line 26 skipping to change at page 20, line 26
| | | real number | | | | real number |
| float64 | Number | 64-bit IEEE floating point | | float64 | Number | 64-bit IEEE floating point |
| | | real number | | | | real number |
| identityref | Text | A reference to an abstract | | identityref | Text | A reference to an abstract |
| | | identity | | | | identity |
| instance-identifier | Text | References a data tree node | | instance-identifier | Text | References a data tree node |
| int8 | Number | 8-bit signed integer | | int8 | Number | 8-bit signed integer |
| int16 | Number | 16-bit signed integer | | int16 | Number | 16-bit signed integer |
| int32 | Number | 32-bit signed integer | | int32 | Number | 32-bit signed integer |
| int64 | Number | 64-bit signed integer | | int64 | Number | 64-bit signed integer |
| keyref | Text/Number | A reference to a list's key | | leafref | Text/Number | A reference to a leaf |
| | | value | | | | instance |
| string | Text | Human readable string | | string | Text | Human readable string |
| uint8 | Number | 8-bit unsigned integer | | uint8 | Number | 8-bit unsigned integer |
| uint16 | Number | 16-bit unsigned integer | | uint16 | Number | 16-bit unsigned integer |
| uint32 | Number | 32-bit unsigned integer | | uint32 | Number | 32-bit unsigned integer |
| uint64 | Number | 64-bit unsigned integer | | uint64 | Number | 64-bit unsigned integer |
| union | Text/Number | Choice of member types | | union | Text/Number | Choice of member types |
+---------------------+-------------+-------------------------------+ +---------------------+-------------+-------------------------------+
The "type" statement is covered in Section 9. The "type" statement is covered in Section 9.
skipping to change at page 26, line 33 skipping to change at page 25, line 33
YANG allows the definition of notifications suitable for NETCONF. YANG allows the definition of notifications suitable for NETCONF.
YANG data definition statements are used to model the content of the YANG data definition statements are used to model the content of the
notification. notification.
YANG Example: YANG Example:
notification link-failure { notification link-failure {
description "A link failure has been detected"; description "A link failure has been detected";
leaf if-name { leaf if-name {
type keyref { type leafref {
path "/interfaces/interface/name"; path "/interfaces/interface/name";
} }
} }
leaf if-admin-status { leaf if-admin-status {
type ifAdminStatus; type ifAdminStatus;
} }
} }
NETCONF XML Encoding: NETCONF XML Encoding:
skipping to change at page 28, line 13 skipping to change at page 27, line 13
The "notification" statement is covered in Section 7.14. The "notification" statement is covered in Section 7.14.
5. Language Concepts 5. Language Concepts
5.1. Modules and Submodules 5.1. Modules and Submodules
The module is the base unit of definition in YANG. A module defines The module is the base unit of definition in YANG. A module defines
a single data model. A module can define a complete, cohesive model, a single data model. A module can define a complete, cohesive model,
or augment an existing data model with additional nodes. or augment an existing data model with additional nodes.
A NETCONF server may implement a number of modules, allowing multiple Submodule are partial modules that contribute definitions to a
views of the same data, or multiple views of disjoint subsections of module. A module may include any number of submodules, but each
the device's data. Alternatively, the server may implement only one submodule may belong to only one module.
module that defines all available data. Any modules that are
implemented MUST be available for all defined datastores.
A module may be divided into submodules, based on the needs of the The names of all standard modules and submodules MUST be unique.
module owner. The external view remains that of a single module, Developers of enterprise modules are RECOMMENDED to choose names for
regardless of the presence or size of its submodules. their modules that will have a low probability of colliding with
standard or other enterprise modules, e.g. by using the enterprise or
organization name as a prefix.
A module uses the "include" statement to include its submodules, and A module uses the "include" statement to include its submodules, and
the "import" statement to reference external modules. Similarly, a the "import" statement to reference external modules. Similarly, a
submodule may use the "import" statement to reference other modules, submodule uses the "import" statement to reference other modules, and
and may use the "include" statement to reference other submodules uses the "include" statement to reference other submodules within its
within its module. A module or submodule may not include submodules module. A module or submodule MUST NOT include submodules from other
from other modules, nor may a submodule import its own module. modules, and a submodule MUST NOT import its own module.
The names of all standard modules must be unique, but different
revisions of the same module should have the same name. Developers
of enterprise modules are encouraged to choose names for their
modules that will have a low probability of colliding with standard
or other enterprise modules, e.g., by using the enterprise or
organization name as a prefix.
5.1.1. Module Hierarchies
YANG allows modeling of data in multiple hierarchies, where data may The import and include statements are used to make definitions
have more than one root node. Models that have multiple roots nodes available to other modules and submodules:
are sometimes convenient, and are supported by YANG.
5.2. File Layout o For a module to reference definitions in an external module, the
external module MUST be imported.
YANG modules and submodules are typically stored in files, one module o For a module to reference definitions in one of its submodules,
or submodule per file, with the name of the file given by the the module MUST include the submodule.
concatenation of the module or submodule name and the file suffix
".yang". YANG compilers can find imported modules and included
submodules via this convention. While the YANG language defines
modules, tools may compile submodules independently for performance
and manageability reasons. Many errors and warnings that cannot be
detected during submodule compilation may be delayed until the
submodules are linked into a cohesive module.
5.3. Object Based View of YANG o For a submodule to reference definitions in a second submodule of
the same module, the first submodule MUST include the second
submodule.
While YANG models the configuration as a data tree, it can be used in There MUST NOT be any circular chains of imports or includes. For
an object-based manner as well. example, if submodule "a" includes submodule "b", "b" cannot include
"a".
The configuration and state data of the device is modeled as a tree When a definition in an external module is referenced, a locally
of object instances (objects for short). Each object in the tree has defined prefix MUST be used, followed by ":", and then the external
a type name (or managed object class name), a namespace, a (possibly identifier. References to definitions in the local module MAY use
empty) set of attributes and a (possibly empty) set of child objects. the prefix notation. Since built-in data types do not belong to any
module and have no prefix, references to built-in data types (e.g.
int32) cannot use the prefix notation.
A managed object class could be defined as a grouping, containing 5.1.1. Import and Include by Revision
just one list. Attributes should be defined as leafs inside the
list. Child objects should be defined with the corresponding uses
statements.
A defined grouping unambiguously defines its properties, it has its Published modules evolve independently over time. In order to allow
own unique name, so when it is referred to in the "uses" statement it for this evolution, modules need to be imported using specific
is always the same well defined set of properties that we are using. revisions. When a module is written, it uses the current revisions
of other modules, based on what is available at the time. As future
revisions of the imported modules are published, the importing module
is unaffected and its contents are unchanged. When the author of the
module is prepared to move to the most recently published revision of
an imported module, the module is republished with an updated import
statement. By republishing with the new revision, the author is
explicitly indicating their acceptance of any changes in the imported
module.
The data tree can be defined as one or more top level containers For submodules, the issue is related but simpler. A module or
containing managed object classes defined as groupings. All further submodule that includes submodules need to specify the revision of
levels of the data tree are defined by managed object classes the included submodules. If a submodule changes, any module or
containing further managed objects. submodule that includes it needs to be updated.
5.4. XML Namespaces For example, module "b" imports module "a".
All YANG definitions are specified within a particular XML Namespace. module a {
Each module defines an XML namespace as a globally unique URI revision 2008-01-01 { ... }
[RFC3986]. A NETCONF client or server uses the namespace during XML grouping a {
encoding of data. leaf eh { .... }
}
}
The namespace URI is advertised as a capability in the NETCONF module b {
<hello> message to indicate support for the YANG module by a NETCONF import a {
server. The capability URI advertised MUST be on the form: prefix a;
revision 2008-01-01;
}
capability-string = namespace-uri [ parameter-list ] container bee {
parameter-list = "?" parameter *( "&" parameter ) uses a:a;
parameter = revision-parameter / }
module-parameter / }
feature-parameter /
deviation-parameter
revision-parameter = "revision=" revision-number
module-parameter = "module=" module-name
feature-parameter = "features=" feature *( "," feature )
deviation-parameter = "deviations=" deviation *( "," deviation )
Where "revision-number" is the revision of the module (see
Section 7.1.9) that the server implements, "module-name" is the name
of module as it appears in the "module" statement (see Section 7.1),
"namespace-uri" is the namespace for the module as it appears in the
"namespace" statement, "feature" is the name of an optional feature
implemented by the device (see Section 7.18.1), and "deviation" is
the name of a module defining device deviations (see Section 7.18.3).
Namespaces for standard module names will be assigned by IANA. They When the author of "a" publishes a new revision, the changes may not
MUST be unique (but different revisions of the same module should be acceptable to the author of "b". If the new revision is
have the same namespace). acceptable, the author of "a" can republish with an updated revision
in the import statement.
Namespaces for private module names will be assigned by the 5.1.2. Module Hierarchies
organization owning the module without a central registry. It is
recommended to choose namespaces that will have a low probability of
colliding with standard or other enterprise modules, e.g. by using
the enterprise or organization name in the namespace.
The "namespace" statement is covered in Section 7.1.3. YANG allows modeling of data in multiple hierarchies, where data may
have more than one top-level node. Models that have multiple top-
level nodes are sometimes convenient, and are supported by YANG.
5.4.1. YANG Namespace NETCONF is capable of carrying any XML content as the payload in the
<config> element. The top-level nodes of YANG modules are encoded as
child elements within the <config> element.
YANG defines its own namespace for NETCONF <edit-config> operations. For example:
This namespace is "urn:ietf:params:xml:ns:yang:1" [XXX IANA].
5.5. Ordering module my-config {
namespace "http://example.com/schema/config";
prefix "co";
YANG supports two styles for ordering the entries within a list. In container system { ... }
many lists, the order of list entries does not impact the container routing { ... }
implementation of the list's configuration, and the device is free to }
sort the list entries in any reasonable order. The "description"
string for the list may suggest an order. YANG calls this style of
list "system ordered" and they are indicated with the statement
"ordered-by system".
For example, a list of valid users would typically be sorted could be encoded in NETCONF as:
alphabetically, since the order in which the users appeared in the
configuration would not impact the creation of those users' accounts.
In the other style of lists, the order of list entries matters for <rpc message-id="101"
the implementation of the list's configuration and the user is xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
responsible for ordering the entries, while the device maintains that xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
order. YANG calls this style of list "user ordered" and they are <edit-config>
indicated with the statement "ordered-by user". <target>
<running/>
</target>
<config>
<system xmlns="http://example.com/schema/config">
<!-- system data here -->
</system>
<routing xmlns="http://example.com/schema/config">
<!-- routing data here -->
</routing>
</config>
</edit-config>
</rpc>
For example, the order in which firewall filters entries are applied 5.2. File Layout
to incoming traffic may affect how that traffic is filtered. The
user would need to decide if the filter entry that discards all TCP
traffic should be applied before or after the filter entry that
allows all traffic from trusted interfaces. The choice of order
would be crucial.
YANG provides a rich set of facilities within NETCONF's <edit-config> YANG modules and submodules are typically stored in files, one module
operation which allow the order of list entries in user-ordered lists or submodule per file, with the name of the file on the form:
to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned
before or after another specific entry.
The "ordered-by" statement is covered in Section 7.7.4. module-or-submodule-name ['.' revision-number] ( '.yang' / '.yin' )
5.6. Containers with Presence YANG compilers can find imported modules and included submodules via
this convention. While the YANG language defines modules, tools may
compile submodules independently for performance and manageability
reasons. Many errors and warnings that cannot be detected during
submodule compilation may be delayed until the submodules are linked
into a cohesive module.
YANG supports two styles of containers, those which exist only for 5.3. XML Namespaces
organizing the hierarchy of data nodes, and those whose presence in
the configuration has an explicit meaning.
In the first style, the container has no meaning of its own, existing All YANG definitions are specified within a module that is bound to a
only to contain child nodes. The container data node is implicitly particular XML Namespace [XML-NAMES], which is a globally unique URI
created when the first child data node is created. The data node is [RFC3986]. A NETCONF client or server uses the namespace during XML
implicitly deleted when the last non-key child is deleted, since an encoding of data.
empty container has no meaning.
For example, the set of scrambling options for SONET interfaces may Namespaces for standard modules MUST be assigned by IANA.
be placed inside a "scrambling" container to enhance the organization
of the configuration hierarchy, and to keep these nodes together.
The "scrambling" node itself has no meaning, so removing the node
when it becomes empty relieves the user from the task of performing
this task.
In the second style, the presence of the container itself is Namespaces for private modules are assigned by the organization
configuration data, representing a single bit of configuration data. owning the module without a central registry. It is RECOMMENDED to
The container acts as both a configuration knob and a means of choose namespaces that will have a low probability of colliding with
organizing related configuration. These containers are explicitly standard or other enterprise modules, e.g. by using the enterprise or
created and deleted. organization name in the namespace.
YANG calls this style a "presence container" and they are indicated The "namespace" statement is covered in Section 7.1.3.
using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into 5.3.1. YANG XML Namespace
the device using ssh, but can also contain any ssh-related
configuration knobs, such as connection rates or retry limits.
The "presence" statement is covered in Section 7.5.4. YANG defines its own XML namespace for NETCONF <edit-config>
operations. This namespace is "urn:ietf:params:xml:ns:yang:1" [XXX
IANA].
5.7. Scoping 5.4. Resolving Grouping, Type, and Identity Names
YANG uses static scoping. Grouping definitions are resolved in the Grouping, type, and identity names are resolved in the context in
context in which they are defined, rather than the context in which which they are defined, rather than the context in which they are
they are used. Users of groupings are not required to import modules used. Users of groupings, typedefs, and identities are not required
or include submodules to satisfy all references made by the grouping. to import modules or include submodules to satisfy all references
made by the original definition. This behaves like static scoping in
a conventional programming language.
For example, if a module defines a grouping in which a type is For example, if a module defines a grouping in which a type is
referenced, when the grouping is used in a second module, the type is referenced, when the grouping is used in a second module, the type is
resolved in the original module, not the second module. There is no resolved in the context of the original module, not the second
worry over conflicts if both modules define the type, since there is module. There is no worry over conflicts if both modules define the
no ambiguity. type, since there is no ambiguity.
5.8. Nested Typedefs and Groupings 5.5. Nested Typedefs and Groupings
Typedefs and groupings may appear nested under many YANG statements, Typedefs and groupings may appear nested under many YANG statements,
allowing these to be lexically scoped by the hierarchy under which allowing these to be lexically scoped by the hierarchy under which
they appear. This allows types and groupings to be defined near they appear. This allows types and groupings to be defined near
where they are used, rather than placing them at the top level of the where they are used, rather than placing them at the top level of the
hierarchy. The close proximity increases readability. hierarchy. The close proximity increases readability.
Scoping also allows types to be defined without concern for naming Scoping also allows types to be defined without concern for naming
conflicts between types in different submodules. Type names can be conflicts between types in different submodules. Type names can be
specified without adding leading strings designed to prevent name specified without adding leading strings designed to prevent name
skipping to change at page 32, line 48 skipping to change at page 31, line 27
Scoped definitions MUST NOT shadow definitions at a higher scope. A Scoped definitions MUST NOT shadow definitions at a higher scope. A
type or group cannot be defined if a higher level in the schema type or group cannot be defined if a higher level in the schema
hierarchy has a definition with a matching identifier. hierarchy has a definition with a matching identifier.
When a YANG implementation resolves a reference to an unprefixed type When a YANG implementation resolves a reference to an unprefixed type
or grouping, or one which uses the prefix of the local module, it or grouping, or one which uses the prefix of the local module, it
searches up the levels of hierarchy in the schema tree, starting at searches up the levels of hierarchy in the schema tree, starting at
the current level, for the definition of the type or grouping. the current level, for the definition of the type or grouping.
5.9. Conformance 5.6. Conformance
Conformance is a measure of how accurately a device follows the Conformance is a measure of how accurately a device follows the
model. Generally speaking, devices are responsible for implementing model. Generally speaking, devices are responsible for implementing
the model faithfully, allowing applications to treat devices which the model faithfully, allowing applications to treat devices which
implement the model identically. Deviations from the model can implement the model identically. Deviations from the model can
reduce the utility of the model and increase fragility into reduce the utility of the model and increase fragility into
applications that use it. applications that use it.
YANG modelers have three levels of conformance: YANG modelers have three mechanisms for conformance:
o the basic behavior of the model o the basic behavior of the model
o optional features that are part of the model o optional features that are part of the model
o deviations from the model o deviations from the model
We will consider each of these in sequence. We will consider each of these in sequence.
5.9.1. Basic Behavior 5.6.1. Basic Behavior
The model defines a contract between the client and server, which The model defines a contract between the NETCONF client and server,
allows both parties to have faith the other knows the syntax and which allows both parties to have faith the other knows the syntax
semantics behind the modeled data. The strength of YANG lies in the and semantics behind the modeled data. The strength of YANG lies in
strength of this contract and the mindless devotion with which the strength of this contract and the mindless devotion with which
implementers follow it. implementers follow it.
5.9.2. Optional Features 5.6.2. Optional Features
In many models, the modeler will allow sections of the model to be In many models, the modeler will allow sections of the model to be
conditional, based on the device. The device controls whether these conditional, based on the device. The device controls whether these
conditional portions of the model are supported or valid for that conditional portions of the model are supported or valid for that
particular device. 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
"features". A module may declare any number of features, identified "features". Features give the modeler a mechanism for making
by simple strings, and may make portions of the module optional based portions of the module conditional in a manner that is controlled by
on those feature. If the device supports a feature, then the the device. The model can express constructs which are not
corresponding portions of the module are valid for that device. If universally present in all devices. These features are included in
the device doesn't support the feature, those parts of the module are the model definition, allowing a consistent view and allowing
not valid, and applications should behave accordingly. applications to learn which features are supported and tailor their
behavior to the device.
Features give the modeler a mechanism for making portions of the A module may declare any number of features, identified by simple
module conditional in a manner that is controlled by the device. The strings, and may make portions of the module optional based on those
model can express constructs which are not universally present in all feature. If the device supports a feature, then the corresponding
devices. These features are included in the model definition, portions of the module are valid for that device. If the device
allowing a consistent view and allowing applications to learn which doesn't support the feature, those parts of the module are not valid,
features are supported and tailor their behavior to the device. and applications should behave accordingly.
Features are defined using the "feature" statement. Definitions in Features are defined using the "feature" statement. Definitions in
the module that are conditional to the feature are noted by the "if- the module that are conditional to the feature are noted by the "if-
feature" statement with the name of the feature as its argument. feature" statement with the name of the feature as its argument.
Further details are available in Section 7.18.1. Further details are available in Section 7.18.1.
5.9.3. Deviations 5.6.3. Deviations
In an ideal world, all devices would be required to implement the In an ideal world, all devices would be required to implement the
model exactly as defined, and deviations from the model would not be model exactly as defined, and deviations from the model would not be
allowed. But in the real world, devices are often not able or allowed. But in the real world, devices are often not able or
willing to implement the model as written. For YANG-based automation willing to implement the model as written. For YANG-based automation
to deal with these device deviations, a mechanism must exist for to deal with these device deviations, a mechanism must exist for
devices to inform applications of the specifics of such deviations. devices to inform applications of the specifics of such deviations.
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
skipping to change at page 34, line 34 skipping to change at page 33, line 13
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 which 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.
5.9.4. Announcing Conformance Information in the <hello> Message 5.6.4. Announcing Conformance Information in the <hello> Message
Devices indicate the names of supported features and device The namespace URI is advertised as a capability in the NETCONF
deviations via the <hello> message. In hello messages, the features <hello> message to indicate support for the YANG module by a NETCONF
are encoded in the "features" parameter within the URI. The value of server. The capability URI advertised MUST be on the form:
this parameter is a comma-separated list of feature names which the
device supports for the specific module. capability-string = namespace-uri [ parameter-list ]
parameter-list = "?" parameter *( "&" parameter )
parameter = revision-parameter /
module-parameter /
feature-parameter /
deviation-parameter
revision-parameter = "revision=" revision-number
module-parameter = "module=" module-name
feature-parameter = "features=" feature *( "," feature )
deviation-parameter = "deviations=" deviation *( "," deviation )
Where "revision-number" is the revision of the module (see
Section 7.1.9) that the NETCONF server implements, "module-name" is
the name of module as it appears in the "module" statement (see
Section 7.1), "namespace-uri" is the namespace for the module as it
appears in the "namespace" statement, "feature" is the name of an
optional feature implemented by the device (see Section 7.18.1), and
"deviation" is the name of a module defining device deviations (see
Section 7.18.3).
5.6.4.1. Modules
Devices indicate the names of supported modules via the <hello>
message. Module namespaces are encoded as the base URI in the
capability string, and the module name is encoded as the "module"
parameter to the base URI.
Modules that do not contribute any data definitions, rpcs,
notifications, or deviations to the device are not advertised in the
<hello> message.
For example, this <hello> message advertises one module "my-syslog".
<hello> <hello>
<capability> <capability>
http://example.com/mod/mcp?features=feat1&module=mcp http://example.com/syslog?module=my-syslog&revision=2008-04-01
</capability> </capability>
</hello>
5.6.4.2. Features
Devices indicate the names of supported features via the <hello>
message. In hello messages, the features are encoded in the
"features" parameter within the URI. The value of this parameter is
a comma-separated list of feature names which the device supports for
the specific module.
For example, this <hello> message advertises one module, informing
the client that it supports the "local-storage" feature of module
"my-syslog".
<hello>
<capability> <capability>
http://example.com/mod/some?module=some&features=one,two,three http://example.com/syslog?module=my-syslog&features=local-storage
</capability> </capability>
</hello> </hello>
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
the client that it deviates from module "my-syslog" according to the
deviations listed in the module "my-devs".
<hello> <hello>
<capability> <capability>
http://example.com/abc?deviations=my-devs http://example.com/syslog?module=my-syslog&deviations=my-devs
</capability>
<capability>
http://example.com/my-deviations?module=my-devs
</capability> </capability>
</hello> </hello>
5.6.5. Mapping to the NETCONF Schema Discovery Mechanism
+--------------------------------------------------------------+
| Open Question |
+--------------------------------------------------------------+
| Move this section to the monitoring spec? |
+--------------------------------------------------------------+
The NETCONF Schema Discovery process is defined in [TBD]. It
specifies a "schema" list where each entry is identified by
"identifier", "version", and "format".
All revisions of all YANG modules and submodules supported by a
device SHOULD be present in the "schema" list, including modules with
only typedefs and groupings.
The following table specifies how the fields in the "schema" list are
used for YANG modules and submodules:
identifier - the name of the module or submodule.
version - the supported YANG revision string.
format - the string "YANG".
namespace - the module's namespace. if the list entry describes a
submodule, this field contains the namespace of the
module to which the submodule belongs.
Note that the format is "YANG", even if the YIN syntax is used.
6. YANG syntax 6. YANG syntax
The YANG syntax is similar to that of SMIng [RFC3780] and programming The YANG syntax is similar to that of SMIng [RFC3780] and programming
languages like C and C++. This C-like syntax was chosen specifically languages like C and C++. This C-like syntax was chosen specifically
for its readability, since YANG values the time and effort of the for its readability, since YANG values the time and effort of the
readers of models above those of modules writers and YANG tool-chain readers of models above those of modules writers and YANG tool-chain
developers. This section introduces the YANG syntax. developers. This section introduces the YANG syntax.
YANG modules are written in the UTF-8 [RFC3629] character set. YANG modules are written in the UTF-8 [RFC3629] character set.
skipping to change at page 36, line 42 skipping to change at page 36, line 42
A token in YANG is either a keyword, a string, ";", "{", or "}". A A token in YANG is either a keyword, a string, ";", "{", or "}". A
string can be quoted or unquoted. A keyword is either one of the string can be quoted or unquoted. A keyword is either one of the
core YANG keywords defined in this document, or a prefix identifier, core YANG keywords defined in this document, or a prefix identifier,
followed by ":", followed by a language extension keyword. Keywords followed by ":", followed by a language extension keyword. Keywords
are case sensitive. See Section 6.2 for a formal definition of are case sensitive. See Section 6.2 for a formal definition of
identifiers. identifiers.
6.1.3. Quoting 6.1.3. Quoting
If a string contains any whitespace characters, a semicolon (";"), If a string contains any whitespace characters, a semicolon (";"),
curly braces ("{" or "}"), or comment sequences ("//", "/*", or braces ("{" or "}"), or comment sequences ("//", "/*", or "*/"), then
"*/"), 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 If the double quoted string contains a line break followed by
whitespace which is used to indent the text according to the layout whitespace which is used to indent the text according to the layout
in the YANG file, this leading whitespace is stripped from the in the YANG file, this leading whitespace is stripped from the
string, up to at most the same column of the double quote character. string, up to at most the same column of the double quote character.
If the double quoted string contains whitespace before a line break, If the double quoted string contains whitespace before a line break,
this trailing whitespace is stripped from the string. this trailing whitespace is stripped from the string.
A single quoted string (enclosed within ' ') preserves each character A single quoted string (enclosed within ' ') preserves each character
skipping to change at page 39, line 5 skipping to change at page 39, line 5
the module or its submodules share the same identifier namespace. the module or its submodules share the same identifier namespace.
This namespace is scoped to the parent node or module, unless the This namespace is scoped to the parent node or module, unless the
parent node is a case node. In that case, the namespace is scoped parent node is a case node. In that case, the namespace is scoped
to the parent node of the case node's parent choice node. to the parent node of the case node's parent 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.
All identifiers defined in a namespace MUST be unique. All identifiers defined in a namespace MUST be unique.
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
either by a semicolon (";") or a block of substatements enclosed either by a semicolon (";") or a block of substatements enclosed
within curly braces ("{ }"): within braces ("{ }"):
statement = keyword [argument] (";" / "{" *statement "}") statement = keyword [argument] (";" / "{" *statement "}")
The argument is a string, as defined in Section 6.1.2. The argument is a string, as defined in Section 6.1.2.
6.3.1. Language Extensions 6.3.1. Language Extensions
A module can introduce YANG extensions by using the "extension" A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.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 which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the a submodule. Submodules can then include this submodule to find the
definition of the extension. definition of the extension.
6.4. XPath Evaluations 6.4. XPath Evaluations
YANG relies on XPath 1.0 [XPATH] as a notation for specifying many YANG relies on XPath 1.0 [XPATH] as a notation for specifying many
inter-node references and dependencies. NETCONF clients and servers inter-node references and dependencies. NETCONF clients and servers
are not required to implement an XPath interpreter, but MUST ensure are not required to implement an XPath interpreter, but MUST ensure
that the requirements encoded in the data model are enforced. The that the requirements encoded in the data model are enforced. The
manner of enforcement is an implementation decision. The XPath manner of enforcement is an implementation decision. The XPath
skipping to change at page 40, line 27 skipping to change at page 40, line 27
} }
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 which 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.
Standard module names will be assigned by IANA. The names of all Standard module names MUST be assigned by IANA.
standard modules MUST be unique (but different revisions of the same
module should have the same name).
Private module names will be 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 names module without a central registry. It is RECOMMENDED to choose
for their modules that will have a low probability of colliding with submodule names that will have a low probability of colliding with
standard or other enterprise modules, e.g. by using the enterprise or standard or other enterprise modules and submodules, e.g. by using
organization name as a prefix. the enterprise or organization name as a prefix.
A module SHOULD have the following layout: A module SHOULD have the following layout:
module <module-name> { module <module-name> {
// header information // header information
<yang-version statement> <yang-version statement>
<namespace statement> <namespace statement>
<prefix statement> <prefix statement>
skipping to change at page 41, line 26 skipping to change at page 41, line 26
// meta information // meta information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<extension statements> <other statements>
<feature statements>
<typedef statements>
<grouping statements>
<container statements>
<leaf statements>
<leaf-list statements>
<list statements>
<choice statements>
<uses statements>
<rpc statements>
<notification statements>
<augment statements>
<deviation statements>
} }
7.1.1. The module's Substatements 7.1.1. The module's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n | | augment | 7.15 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| contact | 7.1.8 | 0..1 | | contact | 7.1.8 | 0..1 |
skipping to change at page 42, line 41 skipping to change at page 42, line 41
| yang-version | 7.1.2 | 0..1 | | yang-version | 7.1.2 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.2. The yang-version Statement 7.1.2. The yang-version Statement
The "yang-version" statement specifies which version of the YANG The "yang-version" statement specifies which version of the YANG
language was used in developing the module. The statement's argument language was used in developing the module. The statement's argument
contains value "1", which is the current yang version and the default contains value "1", which is the current yang version and the default
value. value.
This statement is intended for future-proofing the syntax of YANG
against possible changes in later versions of YANG. Since the
current version is the default value, the statement need not appear
in YANG modules until a future version is defined. When a new
version is defined, YANG modules can either use version 2 statements
and add the "yang-version 2" statement, or remain within the version
1 feature set and continue to use the default setting of "yang-
version 1".
7.1.3. The namespace Statement 7.1.3. The namespace Statement
The "namespace" statement defines the XML namespace for all XML The "namespace" statement defines the XML namespace for all XML
elements defined by the module. Its argument is the URI of the elements defined by the module. Its argument is the URI of the
namespace. namespace.
See also Section 5.4. 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 namespace of a module. The "prefix" statement's argument is the the module and its namespace. The "prefix" statement's argument is
prefix string which is used as a prefix to access a module. The the prefix string which is used as a prefix to access a module. The
prefix string may be used to refer to definitions contained in the prefix string MAY be used to refer to definitions contained in the
module, e.g. "if:ifName". A prefix follows the same rules as an module, e.g. "if:ifName". A prefix follows the same rules as an
identifier (see Section 6.2). identifier (see Section 6.2).
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, the prefix defined by which generates XML or XPath that use prefixes, the prefix defined by
a module SHOULD be used, unless there is a conflict. a module SHOULD be used, unless there is a conflict.
When used inside the "import" statement, the "prefix" statement When used inside the "import" statement, the "prefix" statement
skipping to change at page 43, line 47 skipping to change at page 43, line 39
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. substatements that holds detailed import information.
All identifiers contained in an imported module are imported into the The mandatory "prefix" substatement assigns a prefix for the imported
current module or submodule, so that they can be referenced by module which is scoped to the importing module or submodule.
definitions in the current module or submodule. The mandatory Multiple "import" statements may be specified to import from
"prefix" substatement assigns a prefix for the imported module which different modules.
is scoped to the importing module or submodule. Multiple "import"
statements may be specified to import from different modules. When the optional "revision" is present, any typedef, grouping,
extension, feature, and identity referenced by definitions in the
local module are taken from the specified revision of the imported
module.
The import's Substatements The import's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| prefix | 7.1.4 | 1 | | prefix | 7.1.4 | 1 |
| revision | 7.1.9 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.6. The include Statement 7.1.6. The include Statement
The "include" statement is used to make content from a submodule The "include" statement is used to make content from a submodule
available to the module. The argument is an identifier which is the available to the module. The argument is an identifier which is the
name of the submodule to include. Modules are only allowed to name of the submodule to include. Modules are only allowed to
include submodules that belong to that module, as defined by the include submodules that belong to that module, as defined by the
"belongs-to" statement (see Section 7.2.2). "belongs-to" statement (see Section 7.2.2).
When a module includes a submodule, it incorporates the contents of 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.
When the optional "revision" is present, the specified revision of
the submodule is included in the module.
The includes's Substatements
+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| revision | 7.1.9 | 0..1 |
+--------------+---------+-------------+
7.1.7. The organization Statement 7.1.7. The organization Statement
The "organization" statement defines the party responsible for this The "organization" statement defines the party responsible for this
module. The argument is a string which is used to specify a textual module. The argument is a string which is used to specify a textual
description of the organization(s) under whose auspices this module description of the organization(s) under whose auspices this module
was developed. was developed.
7.1.8. The contact Statement 7.1.8. The contact Statement
The "contact" statement provides contact information for the module. The "contact" statement provides contact information for the module.
skipping to change at page 45, line 50 skipping to change at page 46, line 42
revision "2007-06-09" { revision "2007-06-09" {
description "Initial revision."; description "Initial revision.";
} }
// definitions follows... // definitions follows...
} }
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 to split be constructed out of several submodules. Submodules allows a module
a complex module in several pieces where all the submodules designer to split a complex model into several pieces where all the
contribute to a single namespace, which is defined by the module submodules contribute to a single namespace, which is defined by the
including the submodules. module that includes the submodules.
The "submodule" statement is used to give the submodule a name, and The "submodule" statement is used to give the submodule a name, and
to group all statements which belong to the submodule together. to group all statements which belong to the submodule together.
The "submodule" statement, which must be present at most once, takes The "submodule" statement, which MUST be present at most once, takes
as an argument an identifier which is the name of the submodule, as an argument an identifier which 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. information.
Standard submodule names will be assigned by IANA. Name of all Standard submodule names MUST be assigned by IANA.
standard submodules must be unique and in addition not conflict with
module names (but different revisions of the same submodule should
have the same name).
Private submodule names will be assigned by the organization owning Private submodule names are assigned by the organization owning the
the submodule without a central registry. It is recommended to submodule without a central registry. It is RECOMMENDED to choose
choose names for their submodules that will have a low probability of submodule names that will have a low probability of colliding with
colliding with standard or other enterprise modules and submodules, standard or other enterprise modules and submodules, e.g. by using
e.g. by using the enterprise or organization name as a prefix. the enterprise or organization name as a prefix.
A submodule SHOULD have the following layout: A submodule SHOULD have the following layout:
submodule <module-name> { submodule <module-name> {
<yang-version statement> <yang-version statement>
// module identification // module identification
<belongs-to statement> <belongs-to statement>
// linkage statements // linkage statements
<import statements> <import statements>
<include statements> <include statements>
// meta information // meta information
<organization statement> <organization statement>
<contact statement> <contact statement>
skipping to change at page 47, line 21 skipping to change at page 47, line 37
// meta information // meta information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<extension statements> <other statements>
<feature statements>
<typedef statements>
<grouping statements>
<container statements>
<leaf statements>
<leaf-list statements>
<list statements>
<choice statements>
<uses statements>
<rpc statements>
<notification statements>
<augment statements>
<deviation statements>
} }
7.2.1. The submodule's Substatements 7.2.1. The submodule's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n | | augment | 7.15 | 0..n |
| belongs-to | 7.2.2 | 1 | | belongs-to | 7.2.2 | 1 |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
skipping to change at page 48, line 37 skipping to change at page 48, line 37
| 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 which is the name
of the module. Only the module to which a submodule belongs, or of the module.
another submodule that belongs to the same module, are allowed to
include that submodule. A submodule MUST only be included by the module to which it belongs,
or by another submodule which belongs to that module.
The mandatory "prefix" substatement assigns a prefix for the module 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 49, line 51 skipping to change at page 49, line 51
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 which 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. The new type is called the other modules which import from it, according to the rules in
"derived type", and the type from which it was derived is called the Section 5.5. The new type is called the "derived type", and the type
"base type". All derived types can be traced back to a YANG built-in from which it was derived is called the "base type". All derived
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 which 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. For details about scoping for nested typedef, see the module.
Section 5.8.
7.3.1. The typedef's Substatements 7.3.1. The typedef's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| default | 7.3.4 | 0..1 | | default | 7.3.4 | 0..1 |
| description | 7.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 |
| type | 7.3.2 | 1 | | type | 7.3.2 | 1 |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.3.2. The typedef's type Statement 7.3.2. The typedef's type Statement
The "type" statement, which must be present, defines the base type The "type" statement, which MUST be present, defines the base type
from which this type is derived. See Section 7.4 for details. from which this type is derived. See Section 7.4 for details.
7.3.3. The units Statement 7.3.3. The units Statement
The "units" statement, which is optional, takes as an argument a The "units" statement, which is optional, takes as an argument a
string which contains a textual definition of the units associated string which 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 which contains
a default value for the new type. a default value for the new type.
The value of the "default" statement MUST correspond to the type The value of the "default" statement MUST be valid according to the
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. The default value also the default value of the new derived type. If the base type's
MUST correspond to any restrictions in the derived type. default value is not valid according to the new restrictions, the
derived type MUST define a new default value.
If the base type's default value does not correspond to the new
restrictions, the derived type MUST define a new default value.
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 which 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 depends on the type being The restrictions that can be applied depend on the type being
restricted. All restriction statements are described in conjunction restricted. The restriction statements are described in subsections
with the built-in types in Section 9. for each built-in type in Section 9.
7.4.1. The type's Substatements 7.4.1. The type's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| bit | 9.7.4 | 0..n | | bit | 9.7.4 | 0..n |
| enum | 9.6.4 | 0..n | | enum | 9.6.4 | 0..n |
| length | 9.4.4 | 0..1 | | length | 9.4.4 | 0..1 |
| path | 9.9.2 | 0..1 | | path | 9.9.2 | 0..1 |
skipping to change at page 52, line 5 skipping to change at page 52, line 5
The "container" statement is used to define an interior node in the The "container" statement is used to define an interior node in the
schema tree. It takes one argument, which is an identifier, followed schema tree. It takes one argument, which is an identifier, followed
by a block of substatements that holds detailed container by a block of substatements that holds detailed container
information. information.
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.
By default, a container does not carry any information, but is used 7.5.1. Containers with Presence
to organize and give structure to the data being defined. The
"presence" statement (see Section 7.5.4) is used to give semantics to
the existence of the container in the data tree.
7.5.1. The container's Substatements YANG supports two styles of containers, those which exist only for
organizing the hierarchy of data nodes, and those whose presence in
the configuration has an explicit meaning.
In the first style, the container has no meaning of its own, existing
only to contain child nodes. This is the default style.
For example, the set of scrambling options for SONET interfaces may
be placed inside a "scrambling" container to enhance the organization
of the configuration hierarchy, and to keep these nodes together.
The "scrambling" node itself has no meaning, so removing the node
when it becomes empty relieves the user from the task of performing
this task.
In the second style, the presence of the container itself is
configuration data, representing a single bit of configuration data.
The container acts as both a configuration knob and a means of
organizing related configuration. These containers are explicitly
created and deleted.
YANG calls this style a "presence container" and they are indicated
using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into
the device using ssh, but can also contain any ssh-related
configuration knobs, such as connection rates or retry limits.
The "presence" statement (see Section 7.5.5) is used to give
semantics to the existence of the container in the data tree.
7.5.2. The container's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| augment | 7.15 | 0..n | | augment | 7.15 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| must | 7.5.2 | 0..n | | must | 7.5.3 | 0..n |
| presence | 7.5.4 | 0..1 | | presence | 7.5.5 | 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 |
| 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.2. 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. It is used to formally string which contains an XPath expression. It is used to formally
declare a constraint on valid data. The constraint is enforced declare a constraint on valid data. The constraint is enforced
according to the rules in Section 8. according to the rules in Section 8.
When a data is validated, all "must" constraints are conceptually When a data store is validated, all "must" constraints are
evaluated once for each corresponding instance in the data tree, and conceptually evaluated once for each corresponding instance in the
for all leafs with default values in effect. If an instance does not data tree, and for all leafs with default values in effect. If an
exist in the data tree, and it does not have a default value, its instance does not exist in the data tree, and it does not have a
"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.
The "must" statement is ignored if the data does not represent
configuration.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context: context:
o The context node is the node in the data tree for which the "must" o The context node is the node in the data tree for which the "must"
statement is defined. statement is defined.
o The accessible tree is made up of all nodes in the data tree, and o The accessible tree is made up of all nodes in the data tree, and
all leafs with default values. all leafs with default values.
o The set of namespace declarations is the set of all "import" o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix" statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI. statement's prefix for the "namespace" statement's URI.
o Elements without a namespace refer to nodes in the current module. o Elements without a namespace refer to nodes in the current module.
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()" which returns a node set with
the initial context node. the initial context node.
The accessible data tree depends on the context node:
o If the context node represents configuration, the tree is the data
in one of the datastores <startup/>, <running/>, or <candidate/>.
The XPath root node has all top-level configuration data nodes in
all modules as children.
o If the context node represents state data, the tree is all state
data on the device, and the <running/> datastore. The XPath root
node has all top-level data nodes in all modules as children.
o If the context node represents notification content, the tree is
the notification XML instance document. The XPath root node has
the element representing the notification being defined as the
only child.
o If the context node represents RPC input parameters, the tree is
the RPC XML instance document. The XPath root node has the
element representing the RPC method being defined as the only
child.
o If the context node represents RPC output parameters, the tree is
the RPC reply instance document. The XPath root node has the
elements representing the RPC output parameters as children.
The result of the XPath expression is converted to a boolean value The result of the XPath expression is converted to a boolean value
using the standard XPath rules. using the standard XPath rules.
If the node with the must statement represents configuration data,
any node referenced in the XPath expression MUST also represent
configuration.
Note that 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 Section 7.6 and Section 7.7), any
XPath comparisons are done on the canonical value. XPath 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.3. The must's Substatements 7.5.4. The must'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.3.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
7.5.3.1. The error-message Statement 7.5.4.1. The error-message Statement
The "error-message" statement, which is optional, takes a string as The "error-message" statement, which is optional, takes a string as
an argument. If the constraint evaluates to false, the string is an argument. If the constraint evaluates to false, the string is
passed as <error-message> in the <rpc-error>. passed as <error-message> in the <rpc-error>.
7.5.3.2. The error-app-tag Statement 7.5.4.2. The error-app-tag Statement
The "error-app-tag" statement, which is optional, takes a string as The "error-app-tag" statement, which is optional, takes a string as
an argument. If the constraint evaluates to false, the string is an argument. If the constraint evaluates to false, the string is
passed as <error-app-tag> in the <rpc-error>. passed as <error-app-tag> in the <rpc-error>.
7.5.3.3. Usage Example of must and error-message 7.5.4.3. Usage Example of must and error-message
container interface { container interface {
leaf ifType { leaf ifType {
type enumeration { type enumeration {
enum ethernet; enum ethernet;
enum atm; enum atm;
} }
} }
leaf ifMTU { leaf ifMTU {
type uint32; type uint32;
skipping to change at page 54, line 39 skipping to change at page 56, line 5
must "ifType != 'ethernet' or " + must "ifType != 'ethernet' or " +
"(ifType = 'ethernet' and ifMTU = 1500)" { "(ifType = 'ethernet' and ifMTU = 1500)" {
error-message "An ethernet MTU must be 1500"; error-message "An ethernet MTU must be 1500";
} }
must "ifType != 'atm' or " + must "ifType != 'atm' or " +
"(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.4. 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 which
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 5.6 for additional information. See Section 7.5.1 for additional information.
7.5.5. The container's Child Node Statements 7.5.6. The container's Child Node Statements
Within a container, the "container", "leaf", "list", "leaf-list", Within a container, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used to define child nodes to "uses", and "choice" statements can be used to define child nodes to
the container. the container.
7.5.6. XML Encoding Rules 7.5.7. XML Encoding Rules
A container node is encoded as an XML element. The element's name is A container node is encoded as an XML element. The element's name is
the container's identifier, and its XML namespace is the module's XML the container's identifier, and its XML namespace is the module's XML
namespace. namespace.
The container's child nodes are encoded as subelements to the The container's child nodes are encoded as subelements to the
container element, in the same order as they are defined within the container element, in the same order as they are defined within the
container statement. container statement.
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.7. NETCONF <edit-config> Operations 7.5.8. 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 container node are: elements of procedure for the container node are:
If the operation is "merge" the node is created if it does not If the operation is "merge" the node is created if it does not
exist. exist.
If the operation is "replace" and the node exists, all child nodes If the operation is "replace" and the node exists, all child nodes
not present in the XML are deleted, and child nodes present in the not present in the XML are deleted, and child nodes present in the
XML but not present in the datastore are created. XML but not present in the datastore are created.
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. exist.
If the operation is "delete" the node is deleted if it exists. If the operation is "delete" the node is deleted if it exists.
If the container has a "presence" statement, it may be implicitly If the container has a "presence" statement, it MAY be implicitly
created if it does not exist, even if the operation is "none". created if it does not exist, even if the operation is "none".
If a container has a "presence" statement and the last child node If a container has a "presence" statement and the last child node
is deleted, the NETCONF server MAY delete the container. is deleted, the NETCONF server MAY delete the container.
7.5.8. 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" {
presence "Enables SSH"; presence "Enables SSH";
description "SSH service specific configuration"; description "SSH service specific configuration";
skipping to change at page 58, line 15 skipping to change at page 59, line 15
7.6.1. The leaf's Substatements 7.6.1. The leaf's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
| default | 7.6.3 | 0..1 | | default | 7.6.3 | 0..1 |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| mandatory | 7.6.4 | 0..1 | | mandatory | 7.6.4 | 0..1 |
| must | 7.5.2 | 0..n | | must | 7.5.3 | 0..n |
| 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.6.2 | 1 | | type | 7.6.2 | 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.6.2. The leaf's type Statement 7.6.2. 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.3. The leaf's default Statement 7.6.3. 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 which contains a default value for the leaf.
The value of the "default" statement MUST correspond to the type The value of the "default" statement MUST be valid according to the
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.4. The leaf's mandatory Statement 7.6.4. 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". If not specified, the default is the string "true" or "false". If not specified, the default is
"false". "false".
If "mandatory" is "true", the node MUST exist if its parent node If "mandatory" is "true", the node MUST exist if its parent node
exists. This constraint is enforced according to the rules in exists. This constraint is enforced according to the rules in
Section 8. Section 8.
Since containers without a "presence" statement are implicitly Containers without a "presence" statement are ignored when performing
created and deleted when needed, they are ignored when performing
mandatory tests for leafs. A mandatory leaf within such a container mandatory tests for leafs. A mandatory leaf within such a container
is mandatory even if the container's data node does not exist. is mandatory even if the container's data node does not exist.
7.6.5. XML Encoding Rules 7.6.5. XML Encoding Rules
A leaf node is encoded as an XML element. The element's name is the A leaf node is encoded as an XML element. The element's name is the
leaf's identifier, and its XML namespace is the module's XML leaf's identifier, and its XML namespace is the module's XML
namespace. namespace.
The value of the leaf node is encoded to XML according to the type, The value of the leaf node is encoded to XML according to the type,
and sent as character data in the element. and sent as character data in the element.
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 the leaf element if its value is the default choose not to send the leaf element if its value is the default
value. Thus, a client that receives an <rpc-reply> for a <get> or value. Thus, a client that receives an <rpc-reply> for a <get> or
<get-config> request, must be prepared to handle the case that a leaf <get-config> request, MUST be prepared to handle the case that a leaf
node with a default value is not present in the XML. In this case, node with a default value is not present in the XML. In this case,
the value used by the server is known to be the default value. the value used by the server is known to be the default value.
See Section 7.6.7 for an example. See Section 7.6.7 for an example.
7.6.6. NETCONF <edit-config> Operations 7.6.6. 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:
skipping to change at page 61, line 5 skipping to change at page 61, line 45
substatements that holds detailed leaf-list information. substatements that holds detailed leaf-list information.
The values in a leaf-list MUST be unique. The values in a leaf-list MUST be unique.
Conceptually, the values in the data tree are always in the canonical Conceptually, the values in the data tree are always in the canonical
form (see Section 9.1). form (see Section 9.1).
If the type referenced by the leaf-list has a default value, it has If the type referenced by the leaf-list has a default value, it has
no effect in the leaf-list. no effect in the leaf-list.
7.7.1. The leaf-list's Substatements 7.7.1. Ordering
YANG supports two styles for ordering the entries within a list. In
many lists, the order of list entries does not impact the
implementation of the list's configuration, and the device is free to
sort the list entries in any reasonable order. The "description"
string for the list may suggest an order. YANG calls this style of
list "system ordered" and they are indicated with the statement
"ordered-by system".
For example, a list of valid users would typically be sorted
alphabetically, since the order in which the users appeared in the
configuration would not impact the creation of those users' accounts.
In the other style of lists, the order of list entries matters for
the implementation of the list's configuration and the user is
responsible for ordering the entries, while the device maintains that
order. YANG calls this style of list "user ordered" and they are
indicated with the statement "ordered-by user".
For example, the order in which firewall filters entries are applied
to incoming traffic may affect how that traffic is filtered. The
user would need to decide if the filter entry that discards all TCP
traffic should be applied before or after the filter entry that
allows all traffic from trusted interfaces. The choice of order
would be crucial.
YANG provides a rich set of facilities within NETCONF's <edit-config>
operation which allow the order of list entries in user-ordered lists
to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned
before or after another specific entry.
The "ordered-by" statement is covered in Section 7.7.5.
7.7.2. The leaf-list's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| max-elements | 7.7.3 | 0..1 | | max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.2 | 0..1 | | min-elements | 7.7.3 | 0..1 |
| must | 7.5.2 | 0..n | | must | 7.5.3 | 0..n |
| ordered-by | 7.7.4 | 0..1 | | ordered-by | 7.7.5 | 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 |
| 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.2. 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 which puts a constraint on valid list entries.
A valid leaf-list or list always has at least min-elements entries. A valid leaf-list or list always has at least min-elements entries.
If no "min-elements" statement is present, it defaults to zero. If no "min-elements" statement is present, it defaults to zero.
The "min-elements" constraint is enforced according to the rules in The "min-elements" constraint is enforced according to the rules in
Section 8. Section 8.
7.7.3. The max-elements Statement 7.7.4. The max-elements Statement
The "max-elements" statement, which is optional, takes as an argument The "max-elements" statement, which is optional, takes as an argument
a positive integer or the string "unbounded", which puts a constraint a positive integer or the string "unbounded", which puts a constraint
on valid list entries. A valid leaf-list or list always has at most on valid list entries. A valid leaf-list or list always has at most
max-elements entries. max-elements entries.
If no "max-elements" statement is present, it defaults to If no "max-elements" statement is present, it defaults to
"unbounded". "unbounded".
The "max-elements" constraint is enforced according to the rules in The "max-elements" constraint is enforced according to the rules in
Section 8. Section 8.
7.7.4. The ordered-by Statement 7.7.5. The ordered-by Statement
The "ordered-by" statement defines whether the order of entries The "ordered-by" statement defines whether the order of entries
within a list are determined by the user or the system. The argument within a list are determined by the user or the system. The argument
is one of the strings "system" or "user". If not present, order is one of the strings "system" or "user". If not present, order
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 5.5 for additional information. See Section 7.7.1 for additional information.
7.7.4.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 makes comparisons possible using simple deterministic order will makes comparisons possible using simple
tools like "diff". tools like "diff".
This is the default order. This is the default order.
7.7.4.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
the user. This order is controlled by using special XML attributes the user. This order is controlled by using special XML attributes
in the <edit-config> request. See Section 7.7.6 for details. in the <edit-config> request. See Section 7.7.7 for details.
7.7.5. XML Encoding Rules 7.7.6. XML Encoding Rules
A leaf-list node is encoded as a series of XML elements. Each A leaf-list node is encoded as a series of XML elements. Each
element's name is the leaf-list's identifier, and its XML namespace element's name is the leaf-list's identifier, and its XML namespace
is the module's XML namespace. is the module's XML namespace.
The value of the leaf-list node is encoded to XML according to the The value of the leaf-list node 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.
See Section 7.7.7 for an example. See Section 7.7.8 for an example.
7.7.6. 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
leaf-list entry's XML element. leaf-list entry's XML element.
In an "ordered-by user" leaf-list, the attributes "insert" and In an "ordered-by user" leaf-list, the attributes "insert" and
"value" in the YANG namespace (Section 5.4.1) can be used to control "value" in the YANG XML namespace (Section 5.3.1) can be used to
where in the leaf-list the entry is inserted. These can be used control where in the leaf-list the entry is inserted. These can be
during "create" operations to insert a new leaf-list entry, or during used during "create" operations to insert a new leaf-list entry, or
"merge" or "replace" operations to insert a new leaf-list entry or during "merge" or "replace" operations to insert a new leaf-list
move an existing one. entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before", The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "value" and "after". If the value is "before" or "after", the "value"
attribute must also be used to specify an existing entry in the leaf- attribute MUST also be used to specify an existing entry in the leaf-
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".
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 which 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
skipping to change at page 63, line 29 skipping to change at page 65, line 29
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. does not exist.
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. list if it exists.
7.7.7. 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";
} }
A corresponding XML encoding: A corresponding XML encoding:
<allow-user>alice</allow-user> <allow-user>alice</allow-user>
<allow-user>bob</allow-user> <allow-user>bob</allow-user>
skipping to change at page 66, line 19 skipping to change at page 68, line 19
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| grouping | 7.11 | 0..n | | grouping | 7.11 | 0..n |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| key | 7.8.2 | 0..1 | | key | 7.8.2 | 0..1 |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| max-elements | 7.7.3 | 0..1 | | max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.2 | 0..1 | | min-elements | 7.7.3 | 0..1 |
| must | 7.5.2 | 0..n | | must | 7.5.3 | 0..n |
| ordered-by | 7.7.4 | 0..1 | | ordered-by | 7.7.5 | 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 |
| 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
skipping to change at page 68, line 46 skipping to change at page 70, line 46
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 namespace (Section 5.4.1) can be used to control where in the YANG XML namespace (Section 5.3.1) can be used to control where
the list the entry is inserted. These can be used during "create" in the list the entry is inserted. These can be used during "create"
operations to insert a new list entry, or during "merge" or "replace" operations to insert a new list entry, or during "merge" or "replace"
operations to insert a new list entry or move an existing one. operations to insert a new list entry or move an existing one.
The "insert" attribute can take the values "first", "last", "before", The "insert" attribute can take the values "first", "last", "before",
and "after". If the value is "before" or "after", the "key" and "after". If the value is "before" or "after", the "key"
attribute must also be used, to specify an existing element in the attribute MUST also be used, to specify an existing element in the
list. The value of the "key" attribute is the key predicates of the list. The value of the "key" attribute is the key predicates of the
full instance identifier (see Section 9.13) for the list entry. full instance identifier (see Section 9.13) for the list entry.
If no "insert" attribute is present in the "create" operation, it If no "insert" attribute is present in the "create" operation, it
defaults to "last". defaults to "last".
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 which 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.
skipping to change at page 72, line 34 skipping to change at page 74, line 34
</rpc> </rpc>
7.9. The choice Statement 7.9. The choice Statement
The "choice" statement defines a set of alternatives, only one of The "choice" statement defines a set of alternatives, only one of
which may exist at any one time. The argument is an identifier, which may exist at any one time. The argument is an identifier,
followed by a block of substatements that holds detailed choice followed by a block of substatements that holds detailed choice
information. The identifier is used to identify the choice node in information. The identifier is used to identify the choice node in
the schema tree. A choice node does not exist in the data tree. the schema tree. A choice node does not exist in the data tree.
A choice consists of a number of branches, defined with the case A choice consists of a number of branches, defined with the "case"
substatement. Each branch contains a number of child nodes. The substatement. Each branch contains a number of child nodes. The
"choice" statement puts a constraint on a valid configuration. In a nodes from at most one of the choice's branches exist at the same
valid configuration, the nodes from at most one of the choice's time.
branches exist at the same time.
See Section 4.2.7 for additional information. See Section 8.3.2 for additional information.
7.9.1. The choice's Substatements 7.9.1. The choice's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anyxml | 7.10 | 0..n | | anyxml | 7.10 | 0..n |
| case | 7.9.2 | 0..n | | case | 7.9.2 | 0..n |
| config | 7.19.1 | 0..1 | | config | 7.19.1 | 0..1 |
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
skipping to change at page 73, line 38 skipping to change at page 75, line 38
The "case" statement is used to define branches of the choice. It The "case" statement is used to define branches of the choice. It
takes as an argument an identifier, followed by a block of takes as an argument an identifier, followed by a block of
substatements that holds detailed case information. substatements that holds detailed case information.
The identifier is used to identify the case node in the schema tree. The identifier is used to identify the case node in the schema tree.
A case node does not exist in the data tree. A case node does not exist in the data tree.
Within a "case" statement, the "anyxml", "container", "leaf", "list", Within a "case" statement, the "anyxml", "container", "leaf", "list",
"leaf-list", "uses", and "augment" statements can be used to define "leaf-list", "uses", and "augment" statements can be used to define
child nodes to the case node. The identifiers of all these child child nodes to the case node. The identifiers of all these child
nodes must be unique within all cases in a choice. For example, the nodes MUST be unique within all cases in a choice. For example, the
following is illegal: following is illegal:
choice interface-type { // This example is illegal YANG choice interface-type { // This example is illegal YANG
case a { case a {
leaf ethernet { ... } leaf ethernet { ... }
} }
case b { case b {
container ethernet { ...} container ethernet { ...}
} }
} }
skipping to change at page 77, line 35 skipping to change at page 79, line 35
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 in e.g. No restrictions are placed on the XML. This can be useful in e.g.
RPC replies. An example is the <filter> parameter in the <get- RPC replies. An example is the <filter> parameter in the <get-
config> operation. config> operation.
An anyxml node cannot be augmented. An anyxml node cannot be augmented.
It is NOT RECOMMENDED that the anyxml statement is used to represent Since the use of anyxml limits the manipulation of the content, it is
RECOMMENDED that the anyxml statement not be used to represent
configuration data. configuration data.
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 |
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| mandatory | 7.6.4 | 0..1 | | mandatory | 7.6.4 | 0..1 |
| must | 7.5.3 | 0..n |
| 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.10.2. XML Encoding Rules 7.10.2. XML Encoding Rules
An anyxml node is encoded as an XML element. The element's name is An anyxml node is encoded as an XML element. The element's name is
the anyxml's identifier, and its XML namespace is the module's XML the anyxml's identifier, and its XML namespace is the module's XML
namespace. The value of the anyxml node is encoded as XML content of namespace. The value of the anyxml node is encoded as XML content of
skipping to change at page 79, line 31 skipping to change at page 81, line 31
<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 which include it,
and by other modules which import from it. It takes one argument and by other modules which import from it, according to the rules in
which is an identifier, followed by a block of substatements that Section 5.5. It takes one argument which is an identifier, followed
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. For details about scoping for nested groupings, see module.
Section 5.8.
A grouping is more than just a mechanism for textual substitution, A grouping is more than just a mechanism for textual substitution,
but defines a collection of nodes. References from inside the but defines a collection of nodes. References from inside the
grouping are relative to the scope in which the grouping is defined, grouping are relative to the scope in which the grouping is defined,
not where it is used. Prefix mappings, type names, grouping names, not where it is used. Prefix mappings, type names, grouping names,
and extension usage are evaluated in the hierarchy where the grouping and extension usage are evaluated in the hierarchy where the grouping
statement appears. For extensions, this means that extensions are statement appears. For extensions, this means that extensions are
applied to the grouping node, not the use node. applied to the grouping node, not the use node.
7.11.1. The grouping's Substatements 7.11.1. The grouping's Substatements
skipping to change at page 86, line 32 skipping to change at page 88, line 32
7.13.4. XML Encoding Rules 7.13.4. XML Encoding 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 name is the rpc's identifier, defined in [RFC4741]. The element's name is the rpc's identifier,
and its XML namespace is the module's XML namespace. and its XML namespace is the module's XML namespace.
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 method invocation succeeded, and no output parameters are If the RPC method invocation succeeded, and no output parameters are
returned, the <rpc-reply> contains a single <ok/> element defined in returned, the <rpc-reply> contains a single <ok/> element defined in
[RFC4741]. If output parameters are returned, they are encoded as [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 method: The following example defines an RPC method:
module rock { module rock {
skipping to change at page 93, line 39 skipping to change at page 95, line 39
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 string
which is the name of an existing identity, from which the new which 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 which 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 which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the a 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
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";
identitiy crypto-alg { identity crypto-alg {
description description
"Base identity from which all crypto algorithms "Base identity from which all crypto algorithms
are derived."; are derived.";
} }
} }
}
module des { module des {
namespace "http://example.com/des"; namespace "http://example.com/des";
prefix "des"; prefix "des";
import "crypto-base" { import "crypto-base" {
prefix "crypto"; prefix "crypto";
} }
identity des { identity des {
skipping to change at page 95, line 47 skipping to change at page 97, line 46
+--------------+----------+-------------+ +--------------+----------+-------------+
| 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 should be mapped to an XML element in YIN or to an XML argument is mapped to an XML element in YIN or to an XML attribute.
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 96, line 39 skipping to change at page 98, line 39
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.9. 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
unless the device supports the given feature. This allows portions unless the device supports the given feature. This allows portions
of the YANG module to be conditional based on conditions on the of the YANG module to be conditional based on conditions on the
device. The model can represent the abilities of the device within device. The model can represent the abilities of the device within
skipping to change at page 97, line 20 skipping to change at page 99, line 20
In this example, a feature called "local-storage" represents the In this example, a feature called "local-storage" represents the
ability for a device to store syslog messages on local storage of ability for a device to store syslog messages on local storage of
some sort. This feature is used to make the "local-storage-limit" some sort. This feature is used to make the "local-storage-limit"
leaf conditional on the presence of some sort of local-storage. If leaf conditional on the presence of some sort of local-storage. If
the device does not report that it supports this feature, the local- the device does not report that it supports this feature, the local-
storage-limit node is not supported. storage-limit node is not supported.
module my-syslog { module my-syslog {
... ...
feature local-storage { feature local-storage {
description "This feature means the device supports local description
"This feature means the device supports local
storage (memory, flash or disk) that can be used to storage (memory, flash or disk) that can be used to
store syslog messages."; store syslog messages.";
} }
container syslog { container syslog {
leaf local-storage-limit { leaf local-storage-limit {
if-feature local-storage; if-feature local-storage;
type uint64;
units "kilobyte";
config false; config false;
description "The amount of local storage that can be description
"The amount of local storage that can be
used to hold syslog messages."; used to hold syslog messages.";
} }
} }
} }
The "if-feature" statement can be used in many places within the YANG The "if-feature" statement can be used in many places within the YANG
syntax. Definitions tagged with "if-feature" are ignored when the syntax. Definitions tagged with "if-feature" are ignored when the
device does not support that feature. device does not support that feature.
A feature MUST NOT reference itself, neither directly nor indirectly
through a chain of other features.
7.18.1.1. The feature's Substatements 7.18.1.1. The feature's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| if-feature | 7.18.2 | 0..n | | if-feature | 7.18.2 | 0..n |
| 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 is used to mark portions of the model as The "if-feature" statement is used to mark portions of the model as
conditional. The argument is the name of a feature, as defined by a conditional. The argument is the name of a feature, as defined by a
"feature" statement. If a prefix is present on the feature name, it "feature" statement. If a prefix is present on the feature name, it
refers to a feature defined the module which was imported with that refers to a feature defined the module which was imported with that
prefix, or the local module if the prefix matches the local module's prefix, or the local module if the prefix matches the local module's
prefix. Otherwise a feature with the matching name must be defined prefix. Otherwise a feature with the matching name MUST be 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 which need to be exposed to submodules MUST be defined in
a submodule. Submodules can then include this submodule to find the a 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 the module which the The deviation statement defines a hierarchy of the module which 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's syntax is formally defined by the rule "deviation-arg" The argument's syntax is formally defined by the rule "deviation-arg"
in Section 12. in Section 12.
Deviations define the way a device or class of devices deviate from Deviations define the way a device or class of devices deviate from
the standard. This means that deviations MUST never be part of a the 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 should only be used as Device deviations are strongly discouraged and SHOULD 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
the standard is no substitute for implementing the standard directly. the standard is no substitute for implementing the standard
correctly.
However in some cases the cost of following the standard is heavy and However in some cases a particular device may not have the hardware
the payoff may be small. A particular device may not have the or software ability to support parts of a standard module. When this
hardware or software ability to support parts of a standard module. occurs, the device makes a choice to treat attempts to configure
When this occurs, the device makes a choice to treat attempts to unsupported parts of the module as either an error that is reported
configure unsupported parts of the module as either an error that is back to the unsuspecting application, or ignore that incoming
reported back to the unsuspecting application, or ignore that requests. Neither choice is acceptable.
incoming requests. Neither choice is acceptable.
Instead, YANG allows devices to document portions of the base module Instead, YANG allows devices to document portions of the base module
which are not supported or supported but with different syntax, by which 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 |
+--------------+----------+-------------+ +--------------+----------+-------------+
skipping to change at page 100, line 13 skipping to change at page 102, line 13
corresponding keyword's argument string in the target node. 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 |
| default | 7.6.3 | 0..1 | | default | 7.6.3 | 0..1 |
| mandatory | 7.6.4 | 0..1 | | mandatory | 7.6.4 | 0..1 |
| max-elements | 7.7.3 | 0..1 | | max-elements | 7.7.4 | 0..1 |
| min-elements | 7.7.2 | 0..1 | | min-elements | 7.7.3 | 0..1 |
| must | 7.5.2 | 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 old RFC867-style "daytime" service.
skipping to change at page 101, line 44 skipping to change at page 103, line 44
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/
continued implementation in order to foster interoperability with continued implementation in order to foster interoperability with
older/existing implementations. older/existing implementations.
o "obsolete" means the definition is obsolete and should not be o "obsolete" means the definition is obsolete and SHOULD NOT be
implemented and/or can be removed if previously implemented. implemented and/or can be removed if previously implemented.
If no status is specified, the default is "current". If no status is specified, the default is "current".
If a definition is "current", it MUST NOT reference a "deprecated" or If a definition is "current", it MUST NOT reference a "deprecated" or
"obsolete" definition within the same module. "obsolete" definition within the same module.
If a definition is "deprecated", it MUST NOT reference an "obsolete" If a definition is "deprecated", it MUST NOT reference an "obsolete"
definition within the same module. definition within the same module.
skipping to change at page 102, line 24 skipping to change at page 104, line 24
The "reference" statement takes as an argument a string which is used The "reference" statement takes as an argument a string which 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 which defines related management information, or a
document which provides additional information relevant to this document which provides additional information relevant to this
definition. definition.
7.19.5. The when Statement 7.19.5. The when Statement
The "when" statement allows a data definition statement to be The "when" statement allows a data definition statement to be
conditional, with the node(s) defined by the data defined statement conditional, with the node(s) defined by the data definition
only being valid when a specific criteria is satisfied. The statement only being valid when a specific criteria is satisfied.
statement's argument is an XPath expression, which is used to The statement's argument is an XPath expression, which is used to
formally specify this criteria. If the XPath expression conceptually formally specify this criteria. If the XPath expression conceptually
evaluates to "true" for a particular instance, then the nodes defined evaluates to "true" for a particular instance, then the nodes defined
by the data definition statement are valid, otherwise they are not. by the data definition statement are valid, otherwise they are not.
See Section 8.3.2 for additional information.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context: context:
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 which is also a data
node. node.
o If the "when" statement is a child of a "choice" or "case" o If the "when" statement is a child of a "choice" or "case"
statement, then the context node is the closest ancestor node to statement, then the context node is the closest ancestor node to
the "choice" or "case" node which is also a data node. the "choice" or "case" node which is also a data 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, teh 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. all leafs with default values.
o The set of namespace declarations is the set of all "import" o The set of namespace declarations is the set of all "import"
statements' prefix and namespace pairs, and the "prefix" statements' prefix and namespace pairs, and the "prefix"
statement's prefix for the "namespace" statement's URI. statement's prefix for the "namespace" statement's URI.
o Elements without a namespace refer to nodes in the current module. o Elements without a namespace refer to nodes in the current module.
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()" which returns a node set with
the initial context node. the initial context node.
The accessible data tree depends on the context node:
o If the context node represents configuration, the tree is the data
in one of the datastores <startup/>, <running/>, or <candidate/>.
The XPath root node has all top-level configuration data nodes in
all modules as children.
o If the context node represents state data, the tree is all state
data on the device, and the <running/> datastore. The XPath root
node has all top-level data nodes in all modules as children.
o If the context node represents notification content, the tree is
the notification XML instance document. The XPath root node has
the element representing the notification being defined as the
only child.
o If the context node represents RPC input parameters, the tree is
the RPC XML instance document. The XPath root node has the
element representing the RPC method being defined as the only
child.
o If the context node represents RPC output parameters, the tree is
the RPC reply instance document. The XPath root node has the
elements representing the RPC output parameters as children.
The result of the XPath expression is converted to a boolean value The result of the XPath expression is converted to a boolean value
using the standard XPath rules. using the standard XPath rules.
Note that the XPath expression is conceptually evaluated. This means Note that the XPath expression is conceptually evaluated. This means
that an implementation does not have to use an XPath evaluator on the that an implementation does not have to use an XPath evaluator on the
device. The augment can very well be implemented with specially device. The augment can very well be implemented with specially
written code. written code.
8. Constraints 8. Constraints
8.1. Constraints on Data
Several YANG statements define constraints on valid data. These Several YANG statements define constraints on valid data. These
constraints are enforced at different times, depending on what type constraints are enforced in different ways, depending on what type of
of data the statement defines. data the statement defines.
If the constraint is defined on configuration data, it MUST be true o If the constraint is defined on configuration data, it MUST be
in a valid configuration data tree. true in a valid configuration data tree.
If the constraint is defined on state data, it MUST be true in a o If the constraint is defined on state data, it MUST be true in a
reply to the <get> command. reply to the <get> command.
If the constraint is defined on notification content, it MUST be true o If the constraint is defined on notification content, it MUST be
in any notification instance. true in any notification instance.
If the constraint is defined on RPC input parameters, it MUST be true o If the constraint is defined on RPC input parameters, it MUST be
in an invocation of the RPC method. true in an invocation of the RPC method.
If the constraint is defined on RPC output parameters, it MUST be o If the constraint is defined on RPC output parameters, it MUST be
true in the RPC reply. true in the RPC reply.
8.2. Hierarchy of Constraints
Conditions on parent nodes affect constraints on child nodes as a
natural consequence of the hierarchy of nodes. "must" and "mandatory"
constraints are not enforced if the parent node has a "when" or "if-
feature" property that is not satisfied on the current device.
In this example, the mandatory constraints on the "longitude" leaf is
not enforced on devices that lack the the "has-gps" feature:
container location {
if-feature has-gps;
leaf longitude {
mandatory true;
...
}
}
8.3. Constraint Enforcement Model
For configuration data, there are three windows when constraints can
be enforced:
o during parsing of RPC payloads
o during processing of NETCONF operations
o during validation
Each of these scenarios are considered in the following sections.
8.3.1. Payload Parsing
When content arrives in RPC payloads, it MUST be well-formed and
valid XML, following the hierarchy and content rules defined by the
set of models the device implements.
o Leaf data values MUST match the type constraints for those leafs,
including those defined in the type's range, length, and pattern
properties.
o Key data MUST be present for all list instances.
o Only data for a single case MUST be present for any choices.
o Data for nodes tagged with "if-feature" MUST NOT be present if the
feature is not supported by the device.
o Data for nodes tagged with "when" MUST NOT be present if the
condition does not evaluate to "true".
o For insert handling, the value for the attributes "before" and
"after" MUST be valid for the type of the appropriate key leafs.
o The attributes "before" and "after" MUST NOT appear for lists
whose "ordered-by" property is "system".
8.3.2. NETCONF <edit-config> Processing
After the incoming data is parsed, the NETCONF server performs the
<edit-config> operation by applying the data to the configuration
datastore. During this processing the following errors MUST be
detected:
o Delete requests for non-existent data.
o Create requests for existent data.
o Insert requests with "before" or "after" parameters which do not
exist.
During <edit-config> processing:
o If the NETCONF operation creates data nodes under a "choice", any
existing nodes from other "case" branches are deleted by the
server.
o If the NETCONF operation modifies a data node such that any node's
"when" expression becomes false, then that node is deleted by the
server.
8.3.3. Validation
When datastore processing is complete, the final contents MUST obey
all validation constraints. This validation processing is performed
at differing time according to the datastore. If the datastore is
<running/> or <startup/>, these constraints MUST be enforced at the
end of the <edit-config> or <copy-config> operation. If the
datastore is <candidate>, the constraint enforcement is delayed until
a <commit> or <validate> operation.
o Any "must" constraints MUST evaluate to "true".
o Any referential integrity constraints defined via the "path"
statement MUST be satisfied.
o Any "unique" constraints on lists MUST be satisfied.
o The "min-elements" and "max-elements" constraints are enforced for
lists and leaf-lists.
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.
skipping to change at page 105, line 26 skipping to change at page 109, line 26
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 (Section 9.4.4, Section 9.4.6) and range restrictions of
numeric types (Section 9.2.4). numeric types (Section 9.2.4).
The lexicographic representation of a value of a certain type is used The lexicographic representation of a value of a certain type is used
in the XML encoding over NETCONF, and when specifying default values in the XML encoding over NETCONF, and when specifying default values
in a YANG module. in a YANG module.
9.1. Canonical representation 9.1. Canonical representation
For each type, 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 lexicographic type's values. Some types allow multiple lexicographic
representations of the same value, for example the positive integer representations of the same value, for example the positive integer
"17" can be represented as "+17" or "17". "17" can be represented as "+17" or "17".
When NETCONF servers sends data, it MUST be in the canonical form.
Some types have a lexical representation that depends on the XML
context in which they occur. These types do not have a canonical
form.
9.2. The Integer Built-in Types 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 106, line 28 skipping to change at page 110, line 33
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 lexicographic representation can be used, YANG module, an alternative lexicographic representation can be used,
which represents the value in a hexadecimal or octal notation. The which 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 upper- or lowercase. The octal notation consists of
an optional sign ("+" or "-"), the character "0" followed a number of an optional sign ("+" or "-"), the character "0" followed a number of
octal digits. octal digits.
Note that if a default value in a YANG module has a leading zero
("0"), it is interpreted as an octal number. In the XML encoding, an
integer is always interpreted as a decimal number, and leading zeros
are allowed.
Examples: Examples:
// legal values // legal values
+4711 // legal positive value +4711 // legal positive value
4711 // legal positive value 4711 // legal positive value
-123 // legal negative value -123 // legal negative value
0xf00f // legal positive hexadecimal value 0xf00f // legal positive hexadecimal value
-0xf // legal negative hexadecimal value -0xf // legal negative hexadecimal value
052 // legal positive octal value 052 // legal positive octal value
// illegal values // illegal values
- 1 // illegal intermediate space - 1 // illegal intermediate space
9.2.2. Canonical Form 9.2.2. Canonical Form
The canonical form of a positive integer does not include the sign The canonical form of a positive integer does not include the sign
"+". "+". Leading zeros are prohibited. The value zero is represented as
"0".
9.2.3. Restrictions 9.2.3. Restrictions
All integer types can be restricted with the "range" statement All integer types can be restricted with the "range" statement
(Section 9.2.4). (Section 9.2.4).
9.2.4. The range Statement 9.2.4. The range Statement
The "range" statement, which is an optional substatement to the The "range" statement, which is an optional substatement to the
"type" statement, takes as an argument a range expression string. It "type" statement, takes as an argument a range expression string. It
skipping to change at page 107, line 35 skipping to change at page 111, line 46
The range expression syntax is formally defined by the rule "range- The range expression syntax is formally defined by the rule "range-
arg" in Section 12. 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 |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.19.3 | 0..1 | | description | 7.19.3 | 0..1 |
| error-app-tag | 7.5.3.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.2.5. Usage Example 9.2.5. Usage Example
typedef my-base-int32-type { typedef my-base-int32-type {
type int32 { type int32 {
range "1..4 | 10..20"; range "1..4 | 10..20";
} }
} }
skipping to change at page 110, line 29 skipping to change at page 114, line 29
The length expression syntax is formally defined by the rule "length- The length expression syntax is formally defined by the rule "length-
arg" in Section 12. arg" in Section 12.
9.4.4.1. The length's Substatements 9.4.4.1. The length'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.3.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.4.5. Usage Example 9.4.5. Usage Example
typedef my-base-str-type { typedef my-base-str-type {
type string { type string {
length "1..255"; length "1..255";
} }
} }
skipping to change at page 111, line 22 skipping to change at page 115, line 22
If the type has multiple "pattern" statements, the expressions are If the type has multiple "pattern" statements, the expressions are
AND:ed together, i.e. all such expressions have to match. AND:ed together, i.e. all such expressions have to match.
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.3.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.3.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.19.4 | 0..1 | | reference | 7.19.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.4.7. Usage Example 9.4.7. Usage Example
With the following type: With the following type:
type string { type string {
length "0..4"; length "0..4";
pattern "[0-9a-fA-F]*"; pattern "[0-9a-fA-F]*";
skipping to change at page 114, line 23 skipping to change at page 118, line 23
A bits type cannot be restricted. A bits type cannot be restricted.
9.7.2. Lexicographic Representation 9.7.2. Lexicographic Representation
The lexicographical representation of the bits type is a space The lexicographical representation of the bits type is a space
separated list of the individual bit values that are set. An empty separated list of the individual bit values that are set. An empty
string thus represents a value where no bits are set. string thus 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 in the space separated list In the canonical form, the bit values are separated by a single space
appear in the same order as they are specified in the "bits" character and they appear in the same order as they are specified in
statement. the "bits" statement.
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 which 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 which holds detailed bit
information. A bit name follows the same syntax rules as an information. A bit name follows the same syntax rules as an
identifier (see Section 6.2). identifier (see Section 6.2).
skipping to change at page 116, line 19 skipping to change at page 120, line 19
contains. contains.
9.8.2. Lexicographic Representation 9.8.2. Lexicographic Representation
Binary values are encoded with the base64 encoding scheme [RFC4648]. Binary values are encoded with the base64 encoding scheme [RFC4648].
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 follow the rules in [RFC4648].
9.9. The keyref Built-in Type 9.9. The leafref Built-in Type
The keyref type is used to reference a particular list entry in the The leafref type is used to reference a particular leaf instance in
data tree. Its value is constrained to be the same as the key of an the data tree. Its value is constrained to be the same as the value
existing list entry. of an existing leaf.
If the leaf with the keyref type represents configuration data, the If the leaf with the leafref type represents configuration data, and
list entry it refers to MUST also represent configuration. Such a the "require-instance" property (Section 9.9.3) is "true", the leaf
leaf puts a constraint on valid data. All keyref nodes MUST it refers to MUST also represent configuration. Such a leaf puts a
reference existing list entries for the data to be valid. This constraint on valid data. All leafref nodes MUST reference existing
constraint is enforced according to the rules in Section 8. leaf instances for the data to be valid. This constraint is enforced
according to the rules in Section 8.
9.9.1. Restrictions 9.9.1. Restrictions
A keyref cannot be restricted. A leafref can be restricted with the "require-instance" statement
(Section 9.9.3).
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 "keyref". It takes as an statement, MUST be present if the type is "leafref". It takes as an
argument a string which MUST refer to one key node of a list entry. argument a string which MUST refer to a leaf node. The value of the
referring leaf MUST match the type of the referred leaf.
The syntax for a path argument is a subset of the XPath syntax. It The syntax for a path argument is a subset of the XPath syntax. It
is an absolute or relative XPath location path in abbreviated syntax, is an absolute or relative XPath location path in abbreviated syntax,
where axes are not permitted, and predicates are used only for where axes are not permitted, and predicates are used only for
constraining the values for the key nodes for list entries. Each constraining the values for the key nodes for list entries. Each
predicate consists of at most one equality test per key. predicate consists of exactly one equality test per key.
The predicates are only used when more than one key reference is The predicates are only used when more than one key reference is
needed to uniquely identify a list entry. This occurs if the list needed to uniquely identify a leaf instance. This occurs if a list
has multiple keys, or a reference to a list within a list is needed. has multiple keys, or a reference to a leaf other than the key in a
In these cases, multiple keyref leafs are typically specified, and list is needed. In these cases, multiple leafrefs are typically
predicates are used to tie them together. specified, and predicates are used to tie them together.
The syntax is formally defined by the rule "path-arg" in Section 12. The syntax is formally defined by the rule "path-arg" in Section 12.
9.9.3. Lexicographic Representation For leafs of type "leafref", the "path" expression evaluates to a
node set consisting of zero, one or more nodes. If "require-
instance" is "true", the node set MUST be non-empty.
A keyref value is encoded the same way as the key it references. 9.9.3. The require-instance Statement
9.9.4. Canonical Form The "require-instance" statement, which is a substatement to the
"type" statement, MAY be present if the type is "leafref" or
"instance-identifier". It takes as an argument the string "true" or
"false". If this statement is not present, it defaults to "true".
The canonical form of a keyref is the same as the canonical form of If "require-instance" is "true", it means that the instance being
the key it references. referred MUST exist for the data to be valid. This constraint is
enforced according to the rules in Section 8.
9.9.5. Usage Example 9.9.4. Lexicographic Representation
A leafref value is encoded the same way as the leaf it references.
9.9.5. Canonical Form
The canonical form of a leafref is the same as the canonical form of
the leaf it references.
9.9.6. Usage Example
With the following list: With the following list:
list interface { list interface {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf ifIndex {
type uint32;
}
list address { list address {
key "ip"; key "ip";
leaf ip { leaf ip {
type yang:ip-address; type yang:ip-address;
} }
} }
} }
The following leafref refers to an existing interface:
The following keyref refers to an existing interface:
leaf mgmt-interface { leaf mgmt-interface {
type keyref { type leafref {
path "../interface/name"; path "../interface/name";
} }
} }
A corresponding XML snippet is e.g.: An example of a corresponding XML snippet:
<interface> <interface>
<name>eth0</name> <name>eth0</name>
</interface> </interface>
<interface> <interface>
<name>lo</name> <name>lo</name>
</interface> </interface>
<mgmt-interface>eth0</mgmt-interface> <mgmt-interface>eth0</mgmt-interface>
The following keyrefs refer to an existing address of an interface: The following leafrefs refer to an existing address of an interface:
container default-address { container default-address {
leaf ifname { leaf ifname {
type keyref { type leafref {
path "../../interface/name"; path "../../interface/name";
} }
} }
leaf address { leaf address {
type keyref { type leafref {
path "../../interface[name = current()/../ifname]" path "../../interface[name = current()/../ifname]"
+ "/address/ip"; + "/address/ip";
} }
} }
} }
A corresponding XML snippet is e.g.: An example of a corresponding XML snippet:
<interface> <interface>
<name>eth0</name> <name>eth0</name>
<address> <address>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
</address> </address>
<address> <address>
<ip>192.0.2.2</ip> <ip>192.0.2.2</ip>
</address> </address>
</interface> </interface>
skipping to change at page 118, line 42 skipping to change at page 123, line 26
<address> <address>
<ip>127.0.0.1</ip> <ip>127.0.0.1</ip>
</address> </address>
</interface> </interface>
<default-address> <default-address>
<ifname>eth0</ifname> <ifname>eth0</ifname>
<address>192.0.2.2</address> <address>192.0.2.2</address>
</default-address> </default-address>
The following notification defines two leafrefs to refer to an
existing ifIndex:
notification link-failure {
leaf if-name {
path "/interfaces/interface/name";
}
leaf index {
path "/interfaces/interface[name = current()/../if-name]"
+ "/ifIndex";
}
}
An example of a corresponding XML notification:
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-04-01T00:01:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system">
<if-name>eth0</if-name>
<index>2</index>
</link-failure>
</notification>
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 the module which was imported with that prefix. an identity defined the module which was imported with that 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.
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. identityref's base identity.
9.10.3. Lexicographic Representation 9.10.3. Lexicographic Representation
An identityref is encoded as the referred identity's qualified name An identityref is encoded as the referred identity's Qualified Name
[XML-NAMES]. as defined in [XML-NAMES]. If the Prefix is not present, the
namespace of the identityref is the default namespace in effect on
the element which contains the identityref value.
[Editor's Note: TBD. How to handle prefixes?] 9.10.4. Canonical Form
9.10.4. Usage Example Since the lexicographic form depends on the XML context in which the
value occurs, this type does not have a canonical form.
With the identity definitions in Section 7.16.3, the leaf: 9.10.5. Usage Example
With the identity definitions in Section 7.16.3, and the following
module:
module my-crypto {
namespace "http://example.com/my-crypto";
prefix mc;
import "crypto-base" { import "crypto-base" {
prefix "crypto"; prefix "crypto";
} }
identity aes {
base "crypto:crypto-alg";
}
leaf crypto { leaf crypto {
type identity-ref { type identityref {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
} }
} }
}
will be encoded as: The leaf "crypto" will be encoded as follows, if the value is the
"des3" identity defined in the "des" module:
<crypto xmlns:des="http://example.com/des">des:des3</crypto> <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 "my-
crypto" module it can be encoded as:
<crypto xmlns:mc="http://example.com/my-crypto">mc:aes</crypto>
or, using the default namespace:
<crypto>aes</crypto>
9.11. The empty Built-in Type 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.
9.11.2. Lexicographic Representation 9.11.2. Lexicographic Representation
Not applicable. Not applicable.
9.11.3. Canonical Representation 9.11.3. Canonical Form
Not applicable. Not applicable.
9.11.4. Usage Example 9.11.4. Usage Example
The following leaf The following leaf
leaf enable-qos { leaf enable-qos {
type empty; type empty;
} }
skipping to change at page 120, line 49 skipping to change at page 126, line 42
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 which is the name of a
member type. member 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 "keyref". NOT be one of the built-in types "empty" or "leafref".
Example: Example:
type union { type union {
type int32; type int32;
type enumeration { type enumeration {
enum "unbounded"; enum "unbounded";
} }
} }
skipping to change at page 121, line 40 skipping to change at page 127, line 33
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
syntax, which is used to uniquely identify a node in the data tree. syntax, which is used to uniquely identify a node in the data tree.
It is an absolute XPath location path in abbreviated syntax, where It is an absolute XPath location path in abbreviated syntax, where
axes are not permitted, and predicates are used only for specifying axes are not permitted, and predicates are used only for specifying
the values for the key nodes for list entries, or a value of a leaf- the values for the key nodes for list entries, or a value of a leaf-
list. Each predicate consists of one equality test per key. Each list. Each predicate consists of one equality test per key. Each
key MUST have a corresponding predicate. key MUST have a corresponding predicate.
If the leaf with the instance-identifier type represents
configuration data, and the "require-instance" property
(Section 9.9.3) is "true", the node it refers to MUST also represent
configuration. Such a leaf puts a constraint on valid data. All
such leaf nodes MUST reference existing nodes for the data to be
valid. This constraint is enforced according to the rules in
Section 8.
The syntax is formally defined by the rule "absolute-instid" in The syntax is formally defined by the rule "absolute-instid" in
Section 12. Section 12.
9.13.1. Restrictions 9.13.1. Restrictions
An instance-identifier cannot be restricted. An instance-identifier can be restricted with the "require-instance"
statement (Section 9.9.3).
9.13.2. Lexicographic Representation 9.13.2. Lexicographic Representation
An instance-identifier value is lexicographically represented as a An instance-identifier value is lexicographically represented as a
string in the XML encoding. The namespace prefixes used in the string in the XML encoding. The namespace prefixes used in the
encoding MUST be declared in the XML namespace scope in the instance- encoding MUST be declared in the XML namespace scope in the instance-
idenfitier's XML element. idenfitier'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.3. Canonical Form 9.13.3. Canonical Form
[Editor's Note: TBD. How to handle prefixes?] Since the lexicographic form depends on the XML context in which the
value occurs, this type does not have a canonical form.
9.13.4. Usage Example 9.13.4. Usage Example
The following are examples of instance identifiers: The following are examples of instance identifiers:
/ex:system/ex:services/ex:ssh/ex:port /ex:system/ex:services/ex:ssh/ex:port
/ex:system/ex:user[ex:name='fred'] /ex:system/ex:user[ex:name='fred']
/ex:system/ex:user[ex:name='fred']/ex:type /ex:system/ex:user[ex:name='fred']/ex:type
skipping to change at page 125, line 9 skipping to change at page 132, line 5
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 which have any data definition statements as
substatements, those data definition substatements MUST NOT be substatements, those data definition substatements MUST NOT be
reordered. reordered.
[Editor's Note: These rules work as long as we have import/include by
revision]
11. YIN 11. YIN
A YANG module can be specified in an alternative XML-based syntax A YANG module can be specified in an alternative XML-based syntax
called YIN. This section describes symmetric mapping rules between called YIN. This section describes symmetric mapping rules between
the two formats. the two formats.
The YANG and YIN formats contain equivalent information using The YANG and YIN formats contain equivalent information using
different notations. The purpose of the YIN notation is to allow the different notations. The purpose of the YIN notation is to allow the
user to translate YANG into YIN, use the rich set of XML based tools user to translate YANG into YIN, use the rich set of XML based tools
on the YIN format to transform, or filter the model information. on the YIN format to transform, or filter the model information.
skipping to change at page 127, line 11 skipping to change at page 133, line 11
argument is encoded as an XML attribute to the keyword's element. If argument is encoded as an XML attribute to the keyword's element. If
"yin-element" is true, the argument is encoded as a subelement to the "yin-element" is true, the argument is encoded as a subelement to the
keyword's element. The name of the attribute or element is the name keyword's element. The name of the attribute or element is the name
of the argument. of the argument.
The core YANG keywords have arguments according to the table below. The core YANG keywords have arguments according to the table below.
Extension keywords have arguments according to Section 7.17.2. Extension keywords have arguments according to Section 7.17.2.
YANG to YIN keyword map YANG to YIN keyword map
+---------------+---------------+-------------+ +------------------+---------------+-------------+
| keyword | argument name | yin-element | | keyword | argument name | yin-element |
+---------------+---------------+-------------+ +------------------+---------------+-------------+
| anyxml | name | false | | anyxml | name | false |
| argument | name | false | | argument | name | false |
| augment | target-node | false | | augment | target-node | false |
| base | name | false | | base | name | false |
| belongs-to | module | false | | belongs-to | module | false |
| bit | name | false | | bit | name | false |
| case | name | false | | case | name | false |
| choice | name | false | | choice | name | false |
| config | value | false | | config | value | false |
| contact | info | true | | contact | info | true |
| container | name | false | | container | name | false |
| default | value | false | | default | value | false |
| description | text | true | | description | text | true |
| deviate | value | false |
| deviation | target-node | false |
| enum | name | false | | enum | name | false |
| error-app-tag | value | false | | error-app-tag | value | false |
| error-message | value | true | | error-message | value | true |
| extension | name | false | | extension | name | false |
| deviate | target-node | false |
| deviation | value | false |
| feature | name | false | | feature | name | false |
| grouping | name | false | | grouping | name | false |
| identity | name | false | | identity | name | false |
| if-feature | name | false | | if-feature | name | false |
| import | module | false | | import | module | false |
| include | module | false | | include | module | false |
| input | <no argument> | n/a | | input | <no argument> | n/a |
| key | value | false | | key | value | false |
| leaf | name | false | | leaf | name | false |
| leaf-list | name | false | | leaf-list | name | false |
skipping to change at page 128, line 15 skipping to change at page 134, line 15
| organization | info | true | | organization | info | true |
| output | <no argument> | n/a | | output | <no argument> | n/a |
| path | value | false | | path | value | false |
| pattern | value | false | | pattern | value | false |
| position | value | false | | position | value | false |
| prefix | value | false | | prefix | value | false |
| presence | value | false | | presence | value | false |
| range | value | false | | range | value | false |
| reference | info | false | | reference | info | false |
| refine | target-node | false | | refine | target-node | false |
| require-instance | value | false |
| revision | date | false | | revision | date | false |
| rpc | name | false | | rpc | name | false |
| status | value | false | | status | value | false |
| submodule | name | false | | submodule | name | false |
| type | name | false | | type | name | false |
| typedef | name | false | | typedef | name | false |
| unique | tag | false | | unique | tag | false |
| units | name | false | | units | name | false |
| uses | name | false | | uses | name | false |
| value | value | false | | value | value | false |
| when | condition | false | | when | condition | false |
| yang-version | value | false | | yang-version | value | false |
| yin-element | value | false | | yin-element | value | false |
+---------------+---------------+-------------+ +------------------+---------------+-------------+
Table 35 Table 1
If a statement is followed by substatements, those substatements are If a statement is followed by substatements, those substatements are
subelements in the YIN mapping. subelements in the YIN mapping.
Comments in YANG MAY be transformed into XML comments. Comments in YANG MAY be transformed into XML comments.
11.2.1. Usage Example 11.2.1. Usage Example
The following YANG snippet: The following YANG snippet:
leaf mtu { leaf mtu {
type uint32; type uint32;
description "The MTU of the interface."; description "The MTU of the interface.";
} }
is translated into the following YIN snippet: is translated into the following YIN snippet:
<leaf name="mtu"> <leaf name="mtu">
<type name="uint32"/> <type name="uint32"/>
<description> <description>
<text>The MTU of the interface."</text> <text>The MTU of the interface.</text>
</description> </description>
</leaf> </leaf>
11.3. Transformation Algorithm YIN-2-YANG 11.3. Transformation Algorithm YIN-2-YANG
The transformation is based on a recursive algorithm that is started The transformation is based on a recursive algorithm that is started
on the <module> or <submodule> element. on the <module> or <submodule> element.
The element is transformed into a YANG keyword. If the keyword in The element is transformed into a YANG keyword. If the keyword in
Table 35 is marked as yin-element true, the subelement with the Table 1 is marked as yin-element true, the subelement with the
keyword's argument name in Table 35 contains the YANG keyword's keyword's argument name in Table 1 contains the YANG keyword's
argument as text content. If the keyword in Table 35 is marked as argument as text content. If the keyword in Table 1 is marked as
yin-element false, the element's attribute with keyword's argument yin-element false, the element's attribute with keyword's argument
name in Table 35 contains the YANG keyword's argument. name in Table 1 contains the YANG keyword's argument.
If there are no other subelements to the element, the YANG statement If there are no other subelements to the element, the YANG statement
is closed with a ";". Otherwise, each such subelement is is closed with a ";". Otherwise, each such subelement is
transformed, according to the same algorithm, as substatements to the transformed, according to the same algorithm, as substatements to the
current YANG statement, enclosed within "{" and "}". current YANG statement, enclosed within "{" and "}".
XML comments in YIN MAY be transformed into YANG comments. XML comments in YIN MAY be transformed into YANG comments.
11.3.1. Tabulation, Formatting 11.3.1. Tabulation, Formatting
skipping to change at page 131, line 26 skipping to change at page 137, line 26
rpc-stmt / rpc-stmt /
notification-stmt / notification-stmt /
deviation-stmt) stmtsep) deviation-stmt) stmtsep)
data-def-stmt = container-stmt / data-def-stmt = container-stmt /
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
case-data-def-stmt = container-stmt / case-data-def-stmt = container-stmt /
leaf-stmt / leaf-stmt /
leaf-list-stmt / leaf-list-stmt /
list-stmt / list-stmt /
anyxml-stmt / anyxml-stmt /
uses-stmt uses-stmt
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 which 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-stmt stmtsep]
"}" "}"
include-stmt = include-keyword sep identifier-arg-str optsep include-stmt = include-keyword sep identifier-arg-str optsep
stmtend (";" /
"{" stmtsep
[revision-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 which 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
skipping to change at page 134, line 8 skipping to change at page 140, line 14
type-stmt = type-keyword sep identifier-ref-arg-str optsep type-stmt = type-keyword sep identifier-ref-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
type-body-stmts type-body-stmts
"}") "}")
type-body-stmts = numerical-restrictions / type-body-stmts = numerical-restrictions /
string-restrictions / string-restrictions /
enum-specification / enum-specification /
keyref-specification / leafref-specification /
identityref-specification / identityref-specification /
bits-specification / bits-specification /
union-specification union-specification
numerical-restrictions = range-stmt stmtsep numerical-restrictions = range-stmt stmtsep
range-stmt = range-keyword sep range-arg-str optsep range-stmt = range-keyword sep range-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
skipping to change at page 135, line 15 skipping to change at page 141, line 20
enum-stmt = enum-keyword sep string optsep enum-stmt = enum-keyword sep string optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[value-stmt stmtsep] [value-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
keyref-specification = path-stmt stmtsep leafref-specification = ;; these stmts can appear in any order
path-stmt stmtsep
[require-instance-stmt stmtsep]
path-stmt = path-keyword sep path-arg-str stmtend path-stmt = path-keyword sep path-arg-str stmtend
identityref-specification = base-stmt stmtsep require-instance-stmt = require-instance-keyword sep
require-instance-arg-str stmtend
require-instance-arg-str = < a string which matches the rule
require-instance-arg >
require-instance-arg = true-keyword / false-keyword
identityref-specification = ;; these stmts can appear in any order
base-stmt stmtsep
[require-instance-stmt stmtsep]
union-specification = 1*(type-stmt stmtsep) union-specification = 1*(type-stmt stmtsep)
bits-specification = 1*(bit-stmt stmtsep) bits-specification = 1*(bit-stmt stmtsep)
bit-stmt = bit-keyword sep identifier-arg-str optsep bit-stmt = bit-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[position-stmt stmtsep] [position-stmt stmtsep]
skipping to change at page 140, line 7 skipping to change at page 146, line 27
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(case-data-def-stmt stmtsep) *(case-data-def-stmt stmtsep)
"}") "}")
anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep anyxml-stmt = anyxml-keyword sep identifier-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[when-stmt stmtsep] [when-stmt stmtsep]
*(if-feature-stmt stmtsep) *(if-feature-stmt stmtsep)
*(must-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[status-stmt stmtsep] [status-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
"}") "}")
uses-stmt = uses-keyword sep identifier-ref-arg-str optsep uses-stmt = uses-keyword sep identifier-ref-arg-str optsep
(";" / (";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[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]
*(refinement-stmt stmtsep) *(refine-stmt stmtsep)
*(uses-augment-stmt stmtsep) *(uses-augment-stmt stmtsep)
"}") "}")
refinement-stmt = refine-keyword sep refine-arg-str optsep refine-stmt = refine-keyword sep refine-arg-str optsep
(";" /
"{" 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 which matches the rule
refine-arg > refine-arg >
refine-arg = descendant-schema-nodeid refine-arg = descendant-schema-nodeid
refine-container-stmts = ;; these stmts can appear in any order refine-container-stmts = ;; 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]
skipping to change at page 141, line 29 skipping to change at page 147, line 50
refine-list-stmts = ;; these stmts can appear in any order refine-list-stmts = ;; these stmts can appear in any order
*(must-stmt stmtsep) *(must-stmt stmtsep)
[config-stmt stmtsep] [config-stmt stmtsep]
[min-elements-stmt stmtsep] [min-elements-stmt stmtsep]
[max-elements-stmt stmtsep] [max-elements-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
refine-choice-stmts = ;; these stmts can appear in any order refine-choice-stmts = ;; these stmts can appear in any order
[default-stmt stmtsep] [default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep] [mandatory-stmt stmtsep]
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
refine-case-stmts = ;; these stmts can appear in any order refine-case-stmts = ;; these stmts can appear in any order
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
refine-anyxml-stmts = ;; these stmts can appear in any order refine-anyxml-stmts = ;; these stmts can appear in any order
[config-stmt stmtsep] [config-stmt stmtsep]
skipping to change at page 143, line 37 skipping to change at page 150, line 11
grouping-stmt) stmtsep) grouping-stmt) stmtsep)
*(data-def-stmt stmtsep) *(data-def-stmt stmtsep)
"}") "}")
deviation-stmt = deviation-keyword sep deviation-stmt = deviation-keyword sep
deviation-arg-str optsep deviation-arg-str optsep
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order ;; these stmts can appear in any order
[description-stmt stmtsep] [description-stmt stmtsep]
[reference-stmt stmtsep] [reference-stmt stmtsep]
*(deviate-stmt stmtsep) (deviate-not-supported-stmt /
1*(deviate-add-stmt /
deviate-replace-stmt /
deviate-delete-stmt))
"}" "}"
deviation-arg-str = < a string which matches the rule deviation-arg-str = < a string which matches the rule
deviation-arg > deviation-arg >
deviation-arg = absolute-schema-nodeid deviation-arg = absolute-schema-nodeid
deviate-stmt = deviate-keyword sep deviate-arg-str optsep deviate-not-supported-stmt =
deviate-keyword sep
not-supported-keyword optsep
(";" /
"{" stmtsep
"}")
deviate-add-stmt = deviate-keyword sep add-keyword optsep
(";" /
"{" stmtsep "{" stmtsep
;; these stmts can appear in any order
[type-stmt stmtsep]
[units-stmt stmtsep] [units-stmt stmtsep]
*(must-stmt stmtsep) *(must-stmt stmtsep)
*(unique-stmt stmtsep) *(unique-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]
"}" "}")
deviate-arg-str = < a string which matches the rule deviate-delete-stmt = deviate-keyword sep delete-keyword optsep
deviate-arg > (";" /
"{" stmtsep
[units-stmt stmtsep]
*(must-stmt stmtsep)
*(unique-stmt stmtsep)
[default-stmt stmtsep]
"}")
deviate-arg = add-keyword / deviate-replace-stmt = deviate-keyword sep replace-keyword optsep
delete-keyword / (";" /
replace-keyword / "{" stmtsep
not-supported-keyword [type-stmt stmtsep]
[units-stmt stmtsep]
[default-stmt stmtsep]
[config-stmt stmtsep]
[mandatory-stmt stmtsep]
[min-elements-stmt stmtsep]
[max-elements-stmt stmtsep]
"}")
;; Ranges ;; Ranges
range-arg-str = < a string which matches the rule range-arg-str = < a string which 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]
skipping to change at page 145, line 47 skipping to change at page 152, line 42
descendant-instid = node-identifier *predicate descendant-instid = node-identifier *predicate
absolute-instid absolute-instid
predicate = "[" *WSP predicate-expr *WSP "]" predicate = "[" *WSP predicate-expr *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))
;; keyref path ;; leafref path
path-arg-str = < a string which matches the rule path-arg-str = < a string which matches the rule
path-arg > path-arg >
path-arg = absolute-path / relative-path path-arg = absolute-path / relative-path
absolute-path = 1*("/" (node-identifier *path-predicate)) absolute-path = 1*("/" (node-identifier *path-predicate))
relative-path = descendant-path / relative-path = 1*(".." "/") descendant-path
(".." "/"
*relative-path)
descendant-path = node-identifier *path-predicate descendant-path = node-identifier
absolute-path [*path-predicate absolute-path]
path-predicate = "[" *WSP path-equality-expr *WSP "]" path-predicate = "[" *WSP path-equality-expr *WSP "]"
path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr path-equality-expr = node-identifier *WSP "=" *WSP path-key-expr
path-key-expr = current-function-invocation "/" path-key-expr = current-function-invocation *WSP "/" *WSP
rel-path-keyexpr rel-path-keyexpr
rel-path-keyexpr = 1*(".." "/") *(node-identifier "/") rel-path-keyexpr = 1*(".." *WSP "/" *WSP)
*(node-identifier *WSP "/" *WSP)
node-identifier node-identifier
;;; Keywords, using abnfgen's syntax for case-sensitive strings ;;; Keywords, using abnfgen's syntax for case-sensitive strings
;; statment keywords ;; statment keywords
anyxml-keyword = 'anyxml' anyxml-keyword = 'anyxml'
argument-keyword = 'argument' argument-keyword = 'argument'
augment-keyword = 'augment' augment-keyword = 'augment'
base-keyword = 'base' base-keyword = 'base'
belongs-to-keyword = 'belongs-to' belongs-to-keyword = 'belongs-to'
skipping to change at page 147, line 30 skipping to change at page 154, line 23
organization-keyword = 'organization' organization-keyword = 'organization'
output-keyword = 'output' output-keyword = 'output'
path-keyword = 'path' path-keyword = 'path'
pattern-keyword = 'pattern' pattern-keyword = 'pattern'
position-keyword = 'position' position-keyword = 'position'
prefix-keyword = 'prefix' prefix-keyword = 'prefix'
presence-keyword = 'presence' presence-keyword = 'presence'
range-keyword = 'range' range-keyword = 'range'
reference-keyword = 'reference' reference-keyword = 'reference'
refine-keyword = 'refine' refine-keyword = 'refine'
require-instance-keyword = 'require-instance'
revision-keyword = 'revision' revision-keyword = 'revision'
rpc-keyword = 'rpc' rpc-keyword = 'rpc'
status-keyword = 'status' status-keyword = 'status'
submodule-keyword = 'submodule' submodule-keyword = 'submodule'
type-keyword = 'type' type-keyword = 'type'
typedef-keyword = 'typedef' typedef-keyword = 'typedef'
unique-keyword = 'unique' unique-keyword = 'unique'
units-keyword = 'units' units-keyword = 'units'
uses-keyword = 'uses' uses-keyword = 'uses'
value-keyword = 'value' value-keyword = 'value'
skipping to change at page 148, line 4 skipping to change at page 154, line 47
;; other keywords ;; other keywords
add-keyword = 'add' add-keyword = 'add'
current-keyword = 'current' current-keyword = 'current'
delete-keyword = 'delete' delete-keyword = 'delete'
deprecated-keyword = 'deprecated' deprecated-keyword = 'deprecated'
false-keyword = 'false' false-keyword = 'false'
max-keyword = 'max' max-keyword = 'max'
min-keyword = 'min' min-keyword = 'min'
nan-keyword = 'NaN' nan-keyword = 'NaN'
neginf-keyword = '-INF' neginf-keyword = '-INF'
not-supported-keyword = 'not-supported' not-supported-keyword = 'not-supported'
obsolete-keyword = 'obsolete' obsolete-keyword = 'obsolete'
posinf-keyword = 'INF' posinf-keyword = 'INF'
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()' current-function-invocation = current-keyword *WSP "(" *WSP ")"
;; Basic Rules ;; Basic Rules
keyword = [prefix ":"] identifier
prefix-arg-str = < a string which matches the rule prefix-arg-str = < a string which 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 which matches the rule
identifier-arg > identifier-arg >
skipping to change at page 153, line 7 skipping to change at page 160, line 7
If the "insert" and "key" or "value" attributes are used in an <edit- If the "insert" and "key" or "value" attributes are used in an <edit-
config> for a list or leaf-list node, and the "key" or "value" refers config> for a list or leaf-list node, and the "key" or "value" refers
to a non-existing instance, the following error is returned: to a non-existing instance, the following error is returned:
Tag: bad-attribute Tag: bad-attribute
Error-app-tag: missing-instance Error-app-tag: missing-instance
14. IANA Considerations 14. IANA Considerations
+-------------------------------------------------------------------+
| Open Question |
+-------------------------------------------------------------------+
| Write this section properly. We need a registry for (sub)module |
| names and module namespaces. |
+-------------------------------------------------------------------+
This document registers two URIs for the YANG XML namespace in the This document registers two URIs for the YANG XML namespace in the
IETF XML registry [RFC3688]. IETF XML registry [RFC3688].
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
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
skipping to change at page 158, line 7 skipping to change at page 165, line 7
[RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J.
Schoenwaelder, Ed., "Textual Conventions for SMIv2", Schoenwaelder, Ed., "Textual Conventions for SMIv2",
STD 58, RFC 2579, April 1999. STD 58, RFC 2579, April 1999.
[RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation [RFC3780] Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation
Structure of Management Information", RFC 3780, May 2004. Structure of Management Information", RFC 3780, May 2004.
Appendix A. ChangeLog Appendix A. ChangeLog
A.1. Version -02 A.1. Version -03
o Added import by revision (yang-00413)
o Changed type "keyref" to "leafref", and added the statement
"require-instance" (yang-01253)
o Clarified that data sent from the server must be in the canonical
form.
o Clarified when and how constraints in the models are enforced.
o Many editorial fixes
o Added more strict grammar for the "deviate" statement.
A.2. Version -02
o Added module update rules. (yang-00000) o Added module update rules. (yang-00000)
o Added "refine" statement as a substatement to "uses". (yang-00088) o Added "refine" statement as a substatement to "uses". (yang-00088)
o Allow "augment" on top-level and in "uses" only. (yang-00088) o Allow "augment" on top-level and in "uses" only. (yang-00088)
o Allow "when" on all data defintion statements. (yang-00088) o Allow "when" on all data defintion statements. (yang-00088)
o Added section "Constraints" and clarified when constraints are o Added section "Constraints" and clarified when constraints are
skipping to change at page 158, line 32 skipping to change at page 165, line 48
o Added "prefix" as a substatement to "belongs-to". (yang-00755) o Added "prefix" as a substatement to "belongs-to". (yang-00755)
o Added section on Conformance. (yang-01281) o Added section on Conformance. (yang-01281)
o Added "deviation" statement. (yang-01281) o Added "deviation" statement. (yang-01281)
o Added "identity" statement and "identityref" type. (yang-01339) o Added "identity" statement and "identityref" type. (yang-01339)
o Aligned grammar for "enum" with text. o Aligned grammar for "enum" with text.
A.2. Version -01 A.3. Version -01
o Removed "Appendix A. Derived YANG Types". o Removed "Appendix A. Derived YANG Types".
o Removed "Appendix C. XML Schema Considerations". o Removed "Appendix C. XML Schema Considerations".
o Removed "Appendix F. Why We Need a New Modeling Language". o Removed "Appendix F. Why We Need a New Modeling Language".
o Moved "Appendix B. YIN" to its own section. o Moved "Appendix B. YIN" to its own section.
o Moved "Appendix D. YANG ABNF Grammar" to its own section. o Moved "Appendix D. YANG ABNF Grammar" to its own section.
skipping to change at page 159, line 29 skipping to change at page 166, line 46
o Fixed whitespace issues in the ABNF grammar. o Fixed whitespace issues in the ABNF grammar.
o Added the term "mandatory node", and refer to it in the o Added the term "mandatory node", and refer to it in the
description of augment (see Section 7.15), and choice (see description of augment (see Section 7.15), and choice (see
Section 7.9.3). Section 7.9.3).
o Added support for multiple "pattern" statements in "type". o Added support for multiple "pattern" statements in "type".
o Several clarifications and fixed typos. o Several clarifications and fixed typos.
A.3. Version -00 A.4. Version -00
Changes from draft-bjorklund-netconf-yang-02.txt Changes from draft-bjorklund-netconf-yang-02.txt
o Fixed bug in grammar for bit-stmt o Fixed bug in grammar for bit-stmt
o Fixed bugs in example XPath expressions o Fixed bugs in example XPath expressions
o Added keyword 'presence' to the YIN mapping table o Added keyword 'presence' to the YIN mapping table
Author's Address Author's Address
Martin Bjorklund (editor) Martin Bjorklund (editor)
Tail-f Systems Tail-f Systems
Email: mbj@tail-f.com Email: mbj@tail-f.com
skipping to change at page 161, line 4 skipping to change at line 7093
o Fixed bugs in example XPath expressions o Fixed bugs in example XPath expressions
o Added keyword 'presence' to the YIN mapping table o Added keyword 'presence' to the YIN mapping table
Author's Address Author's Address
Martin Bjorklund (editor) Martin Bjorklund (editor)
Tail-f Systems Tail-f Systems
Email: mbj@tail-f.com Email: mbj@tail-f.com
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
 End of changes. 284 change blocks. 
781 lines changed or deleted 1191 lines changed or added

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