draft-ietf-netmod-rfc6020bis-06.txt   draft-ietf-netmod-rfc6020bis-07.txt 
Network Working Group M. Bjorklund, Ed. Network Working Group M. Bjorklund, Ed.
Internet-Draft Tail-f Systems Internet-Draft Tail-f Systems
Obsoletes: 6020 (if approved) July 6, 2015 Intended status: Standards Track September 23, 2015
Intended status: Standards Track Expires: March 26, 2016
Expires: January 7, 2016
YANG - A Data Modeling Language for the Network Configuration Protocol The YANG 1.1 Data Modeling Language
(NETCONF) draft-ietf-netmod-rfc6020bis-07
draft-ietf-netmod-rfc6020bis-06
Abstract Abstract
YANG is a data modeling language used to model configuration and YANG is a data modeling language used to model configuration data,
state data manipulated by the Network Configuration Protocol state data, remote procedure calls, and notifications for network
(NETCONF), NETCONF remote procedure calls, and NETCONF notifications. management protocols like the Network Configuration Protocol
This document obsoletes RFC 6020. (NETCONF).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on January 7, 2016. This Internet-Draft will expire on March 26, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 30 skipping to change at page 2, line 28
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8 1.1. Summary of Changes from RFC 6020 . . . . . . . . . . . . 8
2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13 3.1. Mandatory Nodes . . . . . . . . . . . . . . . . . . . . . 13
4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 4. YANG Overview . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13 4.1. Functional Overview . . . . . . . . . . . . . . . . . . . 13
4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15 4.2. Language Overview . . . . . . . . . . . . . . . . . . . . 15
4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15 4.2.1. Modules and Submodules . . . . . . . . . . . . . . . 15
4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 15 4.2.2. Data Modeling Basics . . . . . . . . . . . . . . . . 16
4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 20 4.2.3. State Data . . . . . . . . . . . . . . . . . . . . . 19
4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20 4.2.4. Built-In Types . . . . . . . . . . . . . . . . . . . 20
4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21 4.2.5. Derived Types (typedef) . . . . . . . . . . . . . . . 21
4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22 4.2.6. Reusable Node Groups (grouping) . . . . . . . . . . . 22
4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.7. Choices . . . . . . . . . . . . . . . . . . . . . . . 23
4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24 4.2.8. Extending Data Models (augment) . . . . . . . . . . . 24
4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25 4.2.9. Operation Definitions . . . . . . . . . . . . . . . . 25
4.2.10. Notification Definitions . . . . . . . . . . . . . . 26 4.2.10. Notification Definitions . . . . . . . . . . . . . . 27
5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 27 5. Language Concepts . . . . . . . . . . . . . . . . . . . . . . 28
5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 27 5.1. Modules and Submodules . . . . . . . . . . . . . . . . . 28
5.1.1. Import and Include by Revision . . . . . . . . . . . 28 5.1.1. Import and Include by Revision . . . . . . . . . . . 29
5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 29 5.1.2. Module Hierarchies . . . . . . . . . . . . . . . . . 30
5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 30 5.2. File Layout . . . . . . . . . . . . . . . . . . . . . . . 31
5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 31 5.3. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 32
5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 31 5.3.1. YANG XML Namespace . . . . . . . . . . . . . . . . . 32
5.4. Resolving Grouping, Type, and Identity Names . . . . . . 31 5.4. Resolving Grouping, Type, and Identity Names . . . . . . 32
5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 31 5.5. Nested Typedefs and Groupings . . . . . . . . . . . . . . 32
5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 32 5.6. Conformance . . . . . . . . . . . . . . . . . . . . . . . 33
5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33 5.6.1. Basic Behavior . . . . . . . . . . . . . . . . . . . 33
5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 33 5.6.2. Optional Features . . . . . . . . . . . . . . . . . . 34
5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 33 5.6.3. Deviations . . . . . . . . . . . . . . . . . . . . . 34
5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 34 5.6.4. Implementing a Module . . . . . . . . . . . . . . . . 35
5.6.5. Announcing Conformance Information in NETCONF . . . . 37 5.6.5. Announcing Conformance Information in NETCONF . . . . 38
5.7. Data Store Modification . . . . . . . . . . . . . . . . . 38 5.7. Datastore Modification . . . . . . . . . . . . . . . . . 38
6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38 6. YANG Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 38 6.1. Lexical Tokenization . . . . . . . . . . . . . . . . . . 39
6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 38 6.1.1. Comments . . . . . . . . . . . . . . . . . . . . . . 39
6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 38 6.1.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 39
6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.3. Quoting . . . . . . . . . . . . . . . . . . . . . . . 39
6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 40 6.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 41
6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 40 6.2.1. Identifiers and Their Namespaces . . . . . . . . . . 41
6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 41 6.3. Statements . . . . . . . . . . . . . . . . . . . . . . . 42
6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 41 6.3.1. Language Extensions . . . . . . . . . . . . . . . . . 42
6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 42 6.4. XPath Evaluations . . . . . . . . . . . . . . . . . . . . 43
6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 42 6.4.1. XPath Context . . . . . . . . . . . . . . . . . . . . 43
6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 44 6.5. Schema Node Identifier . . . . . . . . . . . . . . . . . 45
7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 44 7. YANG Statements . . . . . . . . . . . . . . . . . . . . . . . 45
7.1. The module Statement . . . . . . . . . . . . . . . . . . 45 7.1. The module Statement . . . . . . . . . . . . . . . . . . 46
7.1.1. The module's Substatements . . . . . . . . . . . . . 46 7.1.1. The module's Substatements . . . . . . . . . . . . . 47
7.1.2. The yang-version Statement . . . . . . . . . . . . . 47 7.1.2. The yang-version Statement . . . . . . . . . . . . . 48
7.1.3. The namespace Statement . . . . . . . . . . . . . . . 48 7.1.3. The namespace Statement . . . . . . . . . . . . . . . 49
7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 48 7.1.4. The prefix Statement . . . . . . . . . . . . . . . . 49
7.1.5. The import Statement . . . . . . . . . . . . . . . . 48 7.1.5. The import Statement . . . . . . . . . . . . . . . . 49
7.1.6. The include Statement . . . . . . . . . . . . . . . . 49 7.1.6. The include Statement . . . . . . . . . . . . . . . . 50
7.1.7. The organization Statement . . . . . . . . . . . . . 50 7.1.7. The organization Statement . . . . . . . . . . . . . 51
7.1.8. The contact Statement . . . . . . . . . . . . . . . . 50 7.1.8. The contact Statement . . . . . . . . . . . . . . . . 51
7.1.9. The revision Statement . . . . . . . . . . . . . . . 50 7.1.9. The revision Statement . . . . . . . . . . . . . . . 51
7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 51 7.1.10. Usage Example . . . . . . . . . . . . . . . . . . . . 52
7.2. The submodule Statement . . . . . . . . . . . . . . . . . 52 7.2. The submodule Statement . . . . . . . . . . . . . . . . . 53
7.2.1. The submodule's Substatements . . . . . . . . . . . . 53 7.2.1. The submodule's Substatements . . . . . . . . . . . . 54
7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 54 7.2.2. The belongs-to Statement . . . . . . . . . . . . . . 55
7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 55 7.2.3. Usage Example . . . . . . . . . . . . . . . . . . . . 56
7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 55 7.3. The typedef Statement . . . . . . . . . . . . . . . . . . 56
7.3.1. The typedef's Substatements . . . . . . . . . . . . . 56 7.3.1. The typedef's Substatements . . . . . . . . . . . . . 57
7.3.2. The typedef's type Statement . . . . . . . . . . . . 56 7.3.2. The typedef's type Statement . . . . . . . . . . . . 57
7.3.3. The units Statement . . . . . . . . . . . . . . . . . 56 7.3.3. The units Statement . . . . . . . . . . . . . . . . . 57
7.3.4. The typedef's default Statement . . . . . . . . . . . 56 7.3.4. The typedef's default Statement . . . . . . . . . . . 57
7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 57 7.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 58
7.4. The type Statement . . . . . . . . . . . . . . . . . . . 57 7.4. The type Statement . . . . . . . . . . . . . . . . . . . 58
7.4.1. The type's Substatements . . . . . . . . . . . . . . 57 7.4.1. The type's Substatements . . . . . . . . . . . . . . 58
7.5. The container Statement . . . . . . . . . . . . . . . . . 57 7.5. The container Statement . . . . . . . . . . . . . . . . . 58
7.5.1. Containers with Presence . . . . . . . . . . . . . . 58 7.5.1. Containers with Presence . . . . . . . . . . . . . . 59
7.5.2. The container's Substatements . . . . . . . . . . . . 58 7.5.2. The container's Substatements . . . . . . . . . . . . 59
7.5.3. The must Statement . . . . . . . . . . . . . . . . . 59 7.5.3. The must Statement . . . . . . . . . . . . . . . . . 60
7.5.4. The must's Substatements . . . . . . . . . . . . . . 60 7.5.4. The must's Substatements . . . . . . . . . . . . . . 61
7.5.5. The presence Statement . . . . . . . . . . . . . . . 61 7.5.5. The presence Statement . . . . . . . . . . . . . . . 62
7.5.6. The container's Child Node Statements . . . . . . . . 61 7.5.6. The container's Child Node Statements . . . . . . . . 62
7.5.7. XML Mapping Rules . . . . . . . . . . . . . . . . . . 61 7.5.7. XML Encoding Rules . . . . . . . . . . . . . . . . . 62
7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 62 7.5.8. NETCONF <edit-config> Operations . . . . . . . . . . 63
7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 62 7.5.9. Usage Example . . . . . . . . . . . . . . . . . . . . 63
7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 63 7.6. The leaf Statement . . . . . . . . . . . . . . . . . . . 65
7.6.1. The leaf's default value . . . . . . . . . . . . . . 64 7.6.1. The leaf's default value . . . . . . . . . . . . . . 65
7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 64 7.6.2. The leaf's Substatements . . . . . . . . . . . . . . 66
7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 65 7.6.3. The leaf's type Statement . . . . . . . . . . . . . . 66
7.6.4. The leaf's default Statement . . . . . . . . . . . . 65 7.6.4. The leaf's default Statement . . . . . . . . . . . . 66
7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 65 7.6.5. The leaf's mandatory Statement . . . . . . . . . . . 66
7.6.6. XML Mapping Rules . . . . . . . . . . . . . . . . . . 65 7.6.6. XML Encoding Rules . . . . . . . . . . . . . . . . . 67
7.6.7. NETCONF <edit-config> Operations . . . . . . . . . . 66 7.6.7. NETCONF <edit-config> Operations . . . . . . . . . . 67
7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 66 7.6.8. Usage Example . . . . . . . . . . . . . . . . . . . . 67
7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 67 7.7. The leaf-list Statement . . . . . . . . . . . . . . . . . 68
7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 67 7.7.1. Ordering . . . . . . . . . . . . . . . . . . . . . . 69
7.7.2. The leaf-list's default values . . . . . . . . . . . 68 7.7.2. The leaf-list's default values . . . . . . . . . . . 69
7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 69 7.7.3. The leaf-list's Substatements . . . . . . . . . . . . 70
7.7.4. The leaf-list's default Statement . . . . . . . . . . 69 7.7.4. The leaf-list's default Statement . . . . . . . . . . 70
7.7.5. The min-elements Statement . . . . . . . . . . . . . 69 7.7.5. The min-elements Statement . . . . . . . . . . . . . 71
7.7.6. The max-elements Statement . . . . . . . . . . . . . 70 7.7.6. The max-elements Statement . . . . . . . . . . . . . 71
7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 70 7.7.7. The ordered-by Statement . . . . . . . . . . . . . . 71
7.7.8. XML Mapping Rules . . . . . . . . . . . . . . . . . . 71 7.7.8. XML Encoding Rules . . . . . . . . . . . . . . . . . 72
7.7.9. NETCONF <edit-config> Operations . . . . . . . . . . 71 7.7.9. NETCONF <edit-config> Operations . . . . . . . . . . 72
7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 72 7.7.10. Usage Example . . . . . . . . . . . . . . . . . . . . 73
7.8. The list Statement . . . . . . . . . . . . . . . . . . . 74 7.8. The list Statement . . . . . . . . . . . . . . . . . . . 75
7.8.1. The list's Substatements . . . . . . . . . . . . . . 74 7.8.1. The list's Substatements . . . . . . . . . . . . . . 75
7.8.2. The list's key Statement . . . . . . . . . . . . . . 75 7.8.2. The list's key Statement . . . . . . . . . . . . . . 76
7.8.3. The list's unique Statement . . . . . . . . . . . . . 76 7.8.3. The list's unique Statement . . . . . . . . . . . . . 77
7.8.4. The list's Child Node Statements . . . . . . . . . . 77 7.8.4. The list's Child Node Statements . . . . . . . . . . 78
7.8.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 77 7.8.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 78
7.8.6. NETCONF <edit-config> Operations . . . . . . . . . . 78 7.8.6. NETCONF <edit-config> Operations . . . . . . . . . . 79
7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 79 7.8.7. Usage Example . . . . . . . . . . . . . . . . . . . . 80
7.9. The choice Statement . . . . . . . . . . . . . . . . . . 82 7.9. The choice Statement . . . . . . . . . . . . . . . . . . 83
7.9.1. The choice's Substatements . . . . . . . . . . . . . 82 7.9.1. The choice's Substatements . . . . . . . . . . . . . 83
7.9.2. The choice's case Statement . . . . . . . . . . . . . 83 7.9.2. The choice's case Statement . . . . . . . . . . . . . 84
7.9.3. The choice's default Statement . . . . . . . . . . . 84 7.9.3. The choice's default Statement . . . . . . . . . . . 85
7.9.4. The choice's mandatory Statement . . . . . . . . . . 86 7.9.4. The choice's mandatory Statement . . . . . . . . . . 87
7.9.5. XML Mapping Rules . . . . . . . . . . . . . . . . . . 86 7.9.5. XML Encoding Rules . . . . . . . . . . . . . . . . . 87
7.9.6. NETCONF <edit-config> Operations . . . . . . . . . . 86 7.9.6. NETCONF <edit-config> Operations . . . . . . . . . . 87
7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 86 7.9.7. Usage Example . . . . . . . . . . . . . . . . . . . . 87
7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 87 7.10. The anydata Statement . . . . . . . . . . . . . . . . . . 88
7.10.1. The anydata's Substatements . . . . . . . . . . . . 88 7.10.1. The anydata's Substatements . . . . . . . . . . . . 89
7.10.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 88 7.10.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 89
7.10.3. NETCONF <edit-config> Operations . . . . . . . . . . 88 7.10.3. NETCONF <edit-config> Operations . . . . . . . . . . 89
7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 89 7.10.4. Usage Example . . . . . . . . . . . . . . . . . . . 90
7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 89 7.11. The anyxml Statement . . . . . . . . . . . . . . . . . . 90
7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 90 7.11.1. The anyxml's Substatements . . . . . . . . . . . . . 91
7.11.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 90 7.11.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 91
7.11.3. NETCONF <edit-config> Operations . . . . . . . . . . 90 7.11.3. NETCONF <edit-config> Operations . . . . . . . . . . 92
7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 91 7.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 92
7.12. The grouping Statement . . . . . . . . . . . . . . . . . 91 7.12. The grouping Statement . . . . . . . . . . . . . . . . . 92
7.12.1. The grouping's Substatements . . . . . . . . . . . . 92 7.12.1. The grouping's Substatements . . . . . . . . . . . . 93
7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 92 7.12.2. Usage Example . . . . . . . . . . . . . . . . . . . 94
7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 93 7.13. The uses Statement . . . . . . . . . . . . . . . . . . . 94
7.13.1. The uses's Substatements . . . . . . . . . . . . . . 93 7.13.1. The uses's Substatements . . . . . . . . . . . . . . 94
7.13.2. The refine Statement . . . . . . . . . . . . . . . . 93 7.13.2. The refine Statement . . . . . . . . . . . . . . . . 95
7.13.3. XML Mapping Rules . . . . . . . . . . . . . . . . . 94 7.13.3. XML Encoding Rules . . . . . . . . . . . . . . . . . 96
7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 94 7.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 96
7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 96 7.14. The rpc Statement . . . . . . . . . . . . . . . . . . . . 97
7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 96 7.14.1. The rpc's Substatements . . . . . . . . . . . . . . 97
7.14.2. The input Statement . . . . . . . . . . . . . . . . 96 7.14.2. The input Statement . . . . . . . . . . . . . . . . 98
7.14.3. The output Statement . . . . . . . . . . . . . . . . 97 7.14.3. The output Statement . . . . . . . . . . . . . . . . 99
7.14.4. XML Mapping Rules . . . . . . . . . . . . . . . . . 98 7.14.4. XML Encoding Rules . . . . . . . . . . . . . . . . . 100
7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 99 7.14.5. Usage Example . . . . . . . . . . . . . . . . . . . 100
7.15. The action Statement . . . . . . . . . . . . . . . . . . 99 7.15. The action Statement . . . . . . . . . . . . . . . . . . 101
7.15.1. The action's Substatements . . . . . . . . . . . . . 100 7.15.1. The action's Substatements . . . . . . . . . . . . . 101
7.15.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 100 7.15.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 102
7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 101 7.15.3. Usage Example . . . . . . . . . . . . . . . . . . . 102
7.16. The notification Statement . . . . . . . . . . . . . . . 102 7.16. The notification Statement . . . . . . . . . . . . . . . 104
7.16.1. The notification's Substatements . . . . . . . . . . 103 7.16.1. The notification's Substatements . . . . . . . . . . 105
7.16.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 103 7.16.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 105
7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 104 7.16.3. Usage Example . . . . . . . . . . . . . . . . . . . 106
7.17. The augment Statement . . . . . . . . . . . . . . . . . . 105 7.17. The augment Statement . . . . . . . . . . . . . . . . . . 107
7.17.1. The augment's Substatements . . . . . . . . . . . . 106 7.17.1. The augment's Substatements . . . . . . . . . . . . 108
7.17.2. XML Mapping Rules . . . . . . . . . . . . . . . . . 107 7.17.2. XML Encoding Rules . . . . . . . . . . . . . . . . . 109
7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 107 7.17.3. Usage Example . . . . . . . . . . . . . . . . . . . 109
7.18. The identity Statement . . . . . . . . . . . . . . . . . 109 7.18. The identity Statement . . . . . . . . . . . . . . . . . 111
7.18.1. The identity's Substatements . . . . . . . . . . . . 109 7.18.1. The identity's Substatements . . . . . . . . . . . . 111
7.18.2. The base Statement . . . . . . . . . . . . . . . . . 109 7.18.2. The base Statement . . . . . . . . . . . . . . . . . 111
7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 110 7.18.3. Usage Example . . . . . . . . . . . . . . . . . . . 112
7.19. The extension Statement . . . . . . . . . . . . . . . . . 110 7.19. The extension Statement . . . . . . . . . . . . . . . . . 112
7.19.1. The extension's Substatements . . . . . . . . . . . 111 7.19.1. The extension's Substatements . . . . . . . . . . . 113
7.19.2. The argument Statement . . . . . . . . . . . . . . . 111 7.19.2. The argument Statement . . . . . . . . . . . . . . . 113
7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 112 7.19.3. Usage Example . . . . . . . . . . . . . . . . . . . 114
7.20. Conformance-Related Statements . . . . . . . . . . . . . 112 7.20. Conformance-Related Statements . . . . . . . . . . . . . 114
7.20.1. The feature Statement . . . . . . . . . . . . . . . 112 7.20.1. The feature Statement . . . . . . . . . . . . . . . 115
7.20.2. The if-feature Statement . . . . . . . . . . . . . . 114 7.20.2. The if-feature Statement . . . . . . . . . . . . . . 116
7.20.3. The deviation Statement . . . . . . . . . . . . . . 115 7.20.3. The deviation Statement . . . . . . . . . . . . . . 117
7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 117 7.21. Common Statements . . . . . . . . . . . . . . . . . . . . 120
7.21.1. The config Statement . . . . . . . . . . . . . . . . 117 7.21.1. The config Statement . . . . . . . . . . . . . . . . 120
7.21.2. The status Statement . . . . . . . . . . . . . . . . 118 7.21.2. The status Statement . . . . . . . . . . . . . . . . 120
7.21.3. The description Statement . . . . . . . . . . . . . 119 7.21.3. The description Statement . . . . . . . . . . . . . 121
7.21.4. The reference Statement . . . . . . . . . . . . . . 119 7.21.4. The reference Statement . . . . . . . . . . . . . . 121
7.21.5. The when Statement . . . . . . . . . . . . . . . . . 119 7.21.5. The when Statement . . . . . . . . . . . . . . . . . 122
8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 120 8. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 123
8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 120 8.1. Constraints on Data . . . . . . . . . . . . . . . . . . . 123
8.2. Hierarchy of Constraints . . . . . . . . . . . . . . . . 121 8.2. NETCONF Constraint Enforcement Model . . . . . . . . . . 124
8.3. Constraint Enforcement Model . . . . . . . . . . . . . . 121 8.2.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 124
8.3.1. Payload Parsing . . . . . . . . . . . . . . . . . . . 121 8.2.2. NETCONF <edit-config> Processing . . . . . . . . . . 125
8.3.2. NETCONF <edit-config> Processing . . . . . . . . . . 122 8.2.3. Validation . . . . . . . . . . . . . . . . . . . . . 125
8.3.3. Validation . . . . . . . . . . . . . . . . . . . . . 123 9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 126
9. Built-In Types . . . . . . . . . . . . . . . . . . . . . . . 123 9.1. Canonical Representation . . . . . . . . . . . . . . . . 126
9.1. Canonical Representation . . . . . . . . . . . . . . . . 123 9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 126
9.2. The Integer Built-In Types . . . . . . . . . . . . . . . 124 9.2.1. Lexical Representation . . . . . . . . . . . . . . . 127
9.2.1. Lexical Representation . . . . . . . . . . . . . . . 124 9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 128
9.2.2. Canonical Form . . . . . . . . . . . . . . . . . . . 125 9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 128
9.2.3. Restrictions . . . . . . . . . . . . . . . . . . . . 125 9.2.4. The range Statement . . . . . . . . . . . . . . . . . 128
9.2.4. The range Statement . . . . . . . . . . . . . . . . . 125 9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 129
9.2.5. Usage Example . . . . . . . . . . . . . . . . . . . . 126 9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 129
9.3. The decimal64 Built-In Type . . . . . . . . . . . . . . . 126 9.3.1. Lexical Representation . . . . . . . . . . . . . . . 129
9.3.1. Lexical Representation . . . . . . . . . . . . . . . 127 9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129
9.3.2. Canonical Form . . . . . . . . . . . . . . . . . . . 127 9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 130
9.3.3. Restrictions . . . . . . . . . . . . . . . . . . . . 127 9.3.4. The fraction-digits Statement . . . . . . . . . . . . 130
9.3.4. The fraction-digits Statement . . . . . . . . . . . . 127 9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 130
9.3.5. Usage Example . . . . . . . . . . . . . . . . . . . . 128 9.4. The string Built-In Type . . . . . . . . . . . . . . . . 131
9.4. The string Built-In Type . . . . . . . . . . . . . . . . 128 9.4.1. Lexical Representation . . . . . . . . . . . . . . . 131
9.4.1. Lexical Representation . . . . . . . . . . . . . . . 128 9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 131
9.4.2. Canonical Form . . . . . . . . . . . . . . . . . . . 129 9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 131
9.4.3. Restrictions . . . . . . . . . . . . . . . . . . . . 129 9.4.4. The length Statement . . . . . . . . . . . . . . . . 131
9.4.4. The length Statement . . . . . . . . . . . . . . . . 129 9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 132
9.4.5. The pattern Statement . . . . . . . . . . . . . . . . 130 9.4.6. The modifier Statement . . . . . . . . . . . . . . . 132
9.4.6. The modifier Statement . . . . . . . . . . . . . . . 130 9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 132
9.4.7. Usage Example . . . . . . . . . . . . . . . . . . . . 130 9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 134
9.5. The boolean Built-In Type . . . . . . . . . . . . . . . . 131 9.5.1. Lexical Representation . . . . . . . . . . . . . . . 134
9.5.1. Lexical Representation . . . . . . . . . . . . . . . 132 9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134
9.5.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134
9.5.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 134
9.6. The enumeration Built-In Type . . . . . . . . . . . . . . 132 9.6.1. Lexical Representation . . . . . . . . . . . . . . . 134
9.6.1. Lexical Representation . . . . . . . . . . . . . . . 132 9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 134
9.6.2. Canonical Form . . . . . . . . . . . . . . . . . . . 132 9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 134
9.6.3. Restrictions . . . . . . . . . . . . . . . . . . . . 132 9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 135
9.6.4. The enum Statement . . . . . . . . . . . . . . . . . 132 9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136
9.6.5. Usage Example . . . . . . . . . . . . . . . . . . . . 133 9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 137
9.7. The bits Built-In Type . . . . . . . . . . . . . . . . . 135 9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137
9.7.1. Restrictions . . . . . . . . . . . . . . . . . . . . 135 9.7.2. Lexical Representation . . . . . . . . . . . . . . . 137
9.7.2. Lexical Representation . . . . . . . . . . . . . . . 135 9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137
9.7.3. Canonical Form . . . . . . . . . . . . . . . . . . . 135 9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 137
9.7.4. The bit Statement . . . . . . . . . . . . . . . . . . 135 9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 138
9.7.5. Usage Example . . . . . . . . . . . . . . . . . . . . 136 9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 139
9.8. The binary Built-In Type . . . . . . . . . . . . . . . . 137 9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 139
9.8.1. Restrictions . . . . . . . . . . . . . . . . . . . . 137 9.8.2. Lexical Representation . . . . . . . . . . . . . . . 139
9.8.2. Lexical Representation . . . . . . . . . . . . . . . 137 9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 139
9.8.3. Canonical Form . . . . . . . . . . . . . . . . . . . 137 9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 139
9.9. The leafref Built-In Type . . . . . . . . . . . . . . . . 137 9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 140
9.9.1. Restrictions . . . . . . . . . . . . . . . . . . . . 138 9.9.2. The path Statement . . . . . . . . . . . . . . . . . 140
9.9.2. The path Statement . . . . . . . . . . . . . . . . . 138 9.9.3. The require-instance Statement . . . . . . . . . . . 141
9.9.3. The require-instance Statement . . . . . . . . . . . 138 9.9.4. Lexical Representation . . . . . . . . . . . . . . . 141
9.9.4. Lexical Representation . . . . . . . . . . . . . . . 139 9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 141
9.9.5. Canonical Form . . . . . . . . . . . . . . . . . . . 139 9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 141
9.9.6. Usage Example . . . . . . . . . . . . . . . . . . . . 139 9.10. The identityref Built-In Type . . . . . . . . . . . . . . 145
9.10. The identityref Built-In Type . . . . . . . . . . . . . . 143 9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145
9.10.1. Restrictions . . . . . . . . . . . . . . . . . . . . 143 9.10.2. The identityref's base Statement . . . . . . . . . . 145
9.10.2. The identityref's base Statement . . . . . . . . . . 143 9.10.3. Lexical Representation . . . . . . . . . . . . . . . 146
9.10.3. Lexical Representation . . . . . . . . . . . . . . . 143 9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 146
9.10.4. Canonical Form . . . . . . . . . . . . . . . . . . . 144 9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 146
9.10.5. Usage Example . . . . . . . . . . . . . . . . . . . 144 9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 148
9.11. The empty Built-In Type . . . . . . . . . . . . . . . . . 145 9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148
9.11.1. Restrictions . . . . . . . . . . . . . . . . . . . . 145 9.11.2. Lexical Representation . . . . . . . . . . . . . . . 148
9.11.2. Lexical Representation . . . . . . . . . . . . . . . 145 9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148
9.11.3. Canonical Form . . . . . . . . . . . . . . . . . . . 145 9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 148
9.11.4. Usage Example . . . . . . . . . . . . . . . . . . . 145 9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 148
9.12. The union Built-In Type . . . . . . . . . . . . . . . . . 146 9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 149
9.12.1. Restrictions . . . . . . . . . . . . . . . . . . . . 146 9.12.2. Lexical Representation . . . . . . . . . . . . . . . 149
9.12.2. Lexical Representation . . . . . . . . . . . . . . . 146 9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 149
9.12.3. Canonical Form . . . . . . . . . . . . . . . . . . . 146 9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 149
9.12.4. Usage Example . . . . . . . . . . . . . . . . . . . 146 9.13. The instance-identifier Built-In Type . . . . . . . . . . 150
9.13. The instance-identifier Built-In Type . . . . . . . . . . 147 9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 151
9.13.1. Restrictions . . . . . . . . . . . . . . . . . . . . 148 9.13.2. Lexical Representation . . . . . . . . . . . . . . . 151
9.13.2. Lexical Representation . . . . . . . . . . . . . . . 148 9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 151
9.13.3. Canonical Form . . . . . . . . . . . . . . . . . . . 148 9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 151
9.13.4. Usage Example . . . . . . . . . . . . . . . . . . . 148 10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 152
10. XPath Functions . . . . . . . . . . . . . . . . . . . . . . . 149 10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 152
10.1. Functions for Node Sets . . . . . . . . . . . . . . . . 149 10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 152
10.1.1. current() . . . . . . . . . . . . . . . . . . . . . 149 10.2. Functions for Strings . . . . . . . . . . . . . . . . . 152
10.2. Functions for Strings . . . . . . . . . . . . . . . . . 149 10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 152
10.2.1. re-match() . . . . . . . . . . . . . . . . . . . . . 149
10.3. Functions for the YANG Types "leafref" and "instance- 10.3. Functions for the YANG Types "leafref" and "instance-
identifier" . . . . . . . . . . . . . . . . . . . . . . 150 identifier" . . . . . . . . . . . . . . . . . . . . . . 153
10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 150 10.3.1. deref() . . . . . . . . . . . . . . . . . . . . . . 153
10.4. Functions for the YANG Type "identityref" . . . . . . . 151 10.4. Functions for the YANG Type "identityref" . . . . . . . 154
10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 151 10.4.1. derived-from() . . . . . . . . . . . . . . . . . . . 154
10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 151 10.4.2. derived-from-or-self() . . . . . . . . . . . . . . . 154
10.5. Functions for the YANG Type "enumeration" . . . . . . . 152 10.5. Functions for the YANG Type "enumeration" . . . . . . . 155
10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 152 10.5.1. enum-value() . . . . . . . . . . . . . . . . . . . . 156
10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 153 10.6. Functions for the YANG Type "bits" . . . . . . . . . . . 157
10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 153 10.6.1. bit-is-set() . . . . . . . . . . . . . . . . . . . . 157
11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 154 11. Updating a Module . . . . . . . . . . . . . . . . . . . . . . 157
12. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 12. Coexistence with YANG version 1 . . . . . . . . . . . . . . . 159
12.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 157 13. YIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 159 13.1. Formal YIN Definition . . . . . . . . . . . . . . . . . 160
13. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 160 13.1.1. Usage Example . . . . . . . . . . . . . . . . . . . 163
14. Error Responses for YANG Related Errors . . . . . . . . . . . 184 14. YANG ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 164
14.1. Error Message for Data That Violates a unique Statement 184 15. NETCONF Error Responses for YANG Related Errors . . . . . . . 188
14.2. Error Message for Data That Violates a max-elements 15.1. Error Message for Data That Violates a unique Statement 188
Statement . . . . . . . . . . . . . . . . . . . . . . . 185 15.2. Error Message for Data That Violates a max-elements
Statement . . . . . . . . . . . . . . . . . . . . . . . 189
14.3. Error Message for Data That Violates a min-elements 15.3. Error Message for Data That Violates a min-elements
Statement . . . . . . . . . . . . . . . . . . . . . . . 185 Statement . . . . . . . . . . . . . . . . . . . . . . . 189
14.4. Error Message for Data That Violates a must Statement . 185 15.4. Error Message for Data That Violates a must Statement . 189
14.5. Error Message for Data That Violates a require-instance 15.5. Error Message for Data That Violates a require-instance
Statement . . . . . . . . . . . . . . . . . . . . . . . 186 Statement . . . . . . . . . . . . . . . . . . . . . . . 190
14.6. Error Message for Data That Does Not Match a leafref 15.6. Error Message for Data That Does Not Match a leafref
Type . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Type . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.7. Error Message for Data That Violates a mandatory choice 15.7. Error Message for Data That Violates a mandatory choice
Statement . . . . . . . . . . . . . . . . . . . . . . . 186 Statement . . . . . . . . . . . . . . . . . . . . . . . 190
14.8. Error Message for the "insert" Operation . . . . . . . . 186 15.8. Error Message for the "insert" Operation . . . . . . . . 190
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 187 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 191
15.1. Media type application/yang . . . . . . . . . . . . . . 188 17. Security Considerations . . . . . . . . . . . . . . . . . . . 191
15.2. Media type application/yin+xml . . . . . . . . . . . . . 189 18. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191
16. Security Considerations . . . . . . . . . . . . . . . . . . . 191 19. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192
17. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 191 20. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192
18. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 192 20.1. Version -07 . . . . . . . . . . . . . . . . . . . . . . 192
19. ChangeLog . . . . . . . . . . . . . . . . . . . . . . . . . . 192 20.2. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192
19.1. Version -06 . . . . . . . . . . . . . . . . . . . . . . 192 20.3. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192
19.2. Version -05 . . . . . . . . . . . . . . . . . . . . . . 192 20.4. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192
19.3. Version -04 . . . . . . . . . . . . . . . . . . . . . . 192 20.5. Version -03 . . . . . . . . . . . . . . . . . . . . . . 193
19.4. Version -03 . . . . . . . . . . . . . . . . . . . . . . 192 20.6. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193
19.5. Version -02 . . . . . . . . . . . . . . . . . . . . . . 193 20.7. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193
19.6. Version -01 . . . . . . . . . . . . . . . . . . . . . . 193 20.8. Version -00 . . . . . . . . . . . . . . . . . . . . . . 194
19.7. Version -00 . . . . . . . . . . . . . . . . . . . . . . 193 21. References . . . . . . . . . . . . . . . . . . . . . . . . . 194
20. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 21.1. Normative References . . . . . . . . . . . . . . . . . . 194
20.1. Normative References . . . . . . . . . . . . . . . . . . 194 21.2. Informative References . . . . . . . . . . . . . . . . . 195
20.2. Informative References . . . . . . . . . . . . . . . . . 195
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 196 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 196
1. Introduction 1. Introduction
YANG is a data modeling language used to model configuration and YANG is a data modeling language originally designed to model
state data manipulated by the Network Configuration Protocol configuration and state data manipulated by the Network Configuration
(NETCONF), NETCONF remote procedure calls, and NETCONF notifications. Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF
YANG is used to model the operations and content layers of NETCONF notifications [RFC6241]. Since the publication of YANG version 1
(see the NETCONF Configuration Protocol [RFC6241], Section 1.2). [RFC6020], YANG has been used or proposed to be used for other
protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI
[I-D.vanderstok-core-comi]). Further, other encodings than XML has
been propsed (e.g., JSON [I-D.ietf-netmod-yang-json]).
This document describes the syntax and semantics of the YANG This document describes the syntax and semantics of version 1.1 of
language, how the data model defined in a YANG module is represented the YANG language. It also describes how the data model defined in a
in the Extensible Markup Language (XML), and how NETCONF operations YANG module is represented in the Extensible Markup Language (XML),
are used to manipulate the data. and how NETCONF operations are used to manipulate the data. Other
protocols and encodings are possible, but out of scope for this
specification.
1.1. Summary of Changes from RFC 6020 1.1. Summary of Changes from RFC 6020
This document defines version 1.1 of the YANG language. YANG version This document defines version 1.1 of the YANG language. YANG version
1.1 is a maintenance release of the YANG language, addressing 1.1 is a maintenance release of the YANG language, addressing
ambiguities and defects in the original specification [RFC6020]. ambiguities and defects in the original specification [RFC6020].
o Changed the YANG version from "1" to "1.1". o Changed the YANG version from "1" to "1.1".
o Made the "yang-version" statement mandatory. o Made the "yang-version" statement mandatory.
skipping to change at page 10, line 30 skipping to change at page 10, line 30
2. Keywords 2. Keywords
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119]. 14, [RFC2119].
3. Terminology 3. Terminology
The following terms are used within this document:
o action: An operation defined for a node in the data tree. o action: An operation defined for a node in the data tree.
o anydata: A data node that can contain an unknown set of nodes that o anydata: A data node that can contain an unknown set of nodes that
can be modelled by YANG. can be modelled by YANG.
o anyxml: A data node that can contain an unknown chunk of XML data. o anyxml: A data node that can contain an unknown chunk of XML data.
o augment: Adds new schema nodes to a previously defined schema o augment: Adds new schema nodes to a previously defined schema
node. node.
o base type: The type from which a derived type was derived, which o base type: The type from which a derived type was derived, which
may be either a built-in type or another derived type. may be either a built-in type or another derived type.
o built-in type: A YANG data type defined in the YANG language, such o built-in type: A YANG data type defined in the YANG language, such
as uint32 or string. as uint32 or string.
o choice: A schema node where only one of a number of identified o choice: A schema node where only one of a number of identified
alternatives is valid. alternatives is valid.
o configuration data: The set of writable data that is required to
transform a system from its initial default state into its current
state [RFC6241].
o conformance: A measure of how accurately a device follows a data o conformance: A measure of how accurately a device follows a data
model. model.
o container: An interior data node that exists in at most one o container: An interior data node that exists in at most one
instance in the data tree. A container has no value, but rather a instance in the data tree. A container has no value, but rather a
set of child nodes. set of child nodes.
o data definition statement: A statement that defines new data o data definition statement: A statement that defines new data
nodes. One of container, leaf, leaf-list, list, choice, case, nodes. One of container, leaf, leaf-list, list, choice, case,
augment, uses, anydata, and anyxml. augment, uses, anydata, and anyxml.
o data model: A data model describes how data is represented and o data model: A data model describes how data is represented and
accessed. accessed.
o data node: A node in the schema tree that can be instantiated in a o data node: A node in the schema tree that can be instantiated in a
data tree. One of container, leaf, leaf-list, list, anydata, and data tree. One of container, leaf, leaf-list, list, anydata, and
anyxml. anyxml.
o data tree: The instantiated tree of configuration and state data o data tree: An instantiated tree of any data modeled with YANG,
on a device. e.g., configuration data, state data, combined configuration and
state data, RPC or action input, RPC or action output, or
notification.
o derived type: A type that is derived from a built-in type (such as o derived type: A type that is derived from a built-in type (such as
uint32), or another derived type. uint32), or another derived type.
o device deviation: A failure of the device to implement the module o device deviation: A failure of the device to implement the module
faithfully. faithfully.
o extension: An extension attaches non-YANG semantics to statements. o extension: An extension attaches non-YANG semantics to statements.
The extension statement defines new statements to express these The extension statement defines new statements to express these
semantics. semantics.
o feature: A mechanism for marking a portion of the model as o feature: A mechanism for marking a portion of the model as
optional. Definitions can be tagged with a feature name and are optional. Definitions can be tagged with a feature name and are
only valid on devices that support that feature. only valid on devices that support that feature.
o grouping: A reusable set of schema nodes, which may be used o grouping: A reusable set of schema nodes, which may be used
locally in the module, in modules that include it, and by other locally in the module and by other modules that import from it.
modules that import from it. The grouping statement is not a data The grouping statement is not a data definition statement and, as
definition statement and, as such, does not define any nodes in such, does not define any nodes in the schema tree.
the schema tree.
o identifier: Used to identify different kinds of YANG items by o identifier: Used to identify different kinds of YANG items by
name. name.
o instance identifier: A mechanism for identifying a particular node o instance identifier: A mechanism for identifying a particular node
in a data tree. in a data tree.
o interior node: Nodes within a hierarchy that are not leaf nodes. o interior node: Nodes within a hierarchy that are not leaf nodes.
o leaf: A data node that exists in at most one instance in the data o leaf: A data node that exists in at most one instance in the data
tree. A leaf has a value but no child nodes. tree. A leaf has a value but no child nodes.
o leaf-list: Like the leaf node but defines a set of uniquely o leaf-list: Like the leaf node but defines a set of uniquely
identifiable nodes rather than a single node. Each node has a identifiable nodes rather than a single node. Each node has a
value but no child nodes. value but no child nodes.
o list: An interior data node that may exist in multiple instances o list: An interior data node that may exist in multiple instances
in the data tree. A list has no value, but rather a set of child in the data tree. A list has no value, but rather a set of child
nodes. nodes.
o module: A YANG module defines a hierarchy of nodes that can be o module: A YANG module defines a hierarchy of schema nodes. With
used for NETCONF-based operations. With its definitions and the its definitions and the definitions it imports or includes from
definitions it imports or includes from elsewhere, a module is elsewhere, a module is self-contained and "compilable".
self-contained and "compilable".
o RPC: A Remote Procedure Call, as used within the NETCONF protocol. o RPC: A Remote Procedure Call.
o RPC operation: A specific Remote Procedure Call, as used within o RPC operation: A specific Remote Procedure Call.
the NETCONF protocol. It is also called a protocol operation.
o schema node: A node in the schema tree. One of action, container, o schema node: A node in the schema tree. One of action, container,
leaf, leaf-list, list, choice, case, rpc, input, output, leaf, leaf-list, list, choice, case, rpc, input, output,
notification, anydata, and anyxml. notification, anydata, and anyxml.
o schema node identifier: A mechanism for identifying a particular o schema node identifier: A mechanism for identifying a particular
node in the schema tree. node in the schema tree.
o schema tree: The definition hierarchy specified within a module. o schema tree: The definition hierarchy specified within a module.
o state data: The additional data on a system that is not
configuration data such as read-only status information and
collected statistics [RFC6241].
o submodule: A partial module definition that contributes derived o submodule: A partial module definition that contributes derived
types, groupings, data nodes, RPCs, actions, and notifications to types, groupings, data nodes, RPCs, actions, and notifications to
a module. A YANG module can be constructed from a number of a module. A YANG module can be constructed from a number of
submodules. submodules.
o top-level data node: A data node where there is no other data node o top-level data node: A data node where there is no other data node
between it and a module or submodule statement. between it and a module or submodule statement.
o uses: The "uses" statement is used to instantiate the set of o uses: The "uses" statement is used to instantiate the set of
schema nodes defined in a grouping statement. The instantiated schema nodes defined in a grouping statement. The instantiated
nodes may be refined and augmented to tailor them to any specific nodes may be refined and augmented to tailor them to any specific
needs. needs.
The following terms are defined in [RFC6241]:
o client
o configuration data
o configuration datastore: a configuration datastore is an
instantiated data tree with configuration data
o datastore: an instantiated data tree
o running configuration datastore
o server
o state data
3.1. Mandatory Nodes 3.1. Mandatory Nodes
A mandatory node is one of: A mandatory node is one of:
o A leaf, choice, anydata, or anyxml node with a "mandatory" o A leaf, choice, anydata, or anyxml node with a "mandatory"
statement with the value "true". statement with the value "true".
o A list or leaf-list node with a "min-elements" statement with a o A list or leaf-list node with a "min-elements" statement with a
value greater than zero. value greater than zero.
o A container node without a "presence" statement, which has at o A container node without a "presence" statement, which has at
least one mandatory node as a child. least one mandatory node as a child.
4. YANG Overview 4. YANG Overview
4.1. Functional Overview 4.1. Functional Overview
YANG is a language used to model data for the NETCONF protocol. A YANG is a language originally designed to model data for the NETCONF
YANG module defines a hierarchy of data that can be used for NETCONF- protocol. A YANG module defines a hierarchy of data that can be used
based operations, including configuration, state data, Remote for NETCONF-based operations, including configuration, state data,
Procedure Calls (RPCs), and notifications. This allows a complete Remote Procedure Calls (RPCs), and notifications. This allows a
description of all data sent between a NETCONF client and server. complete description of all data sent between a NETCONF client and
server. Altough out of scope for this specification, YANG can also
be used for other protocols than NETCONF.
YANG models the hierarchical organization of data as a tree in which YANG models the hierarchical organization of data as a tree in which
each node has a name, and either a value or a set of child nodes. each node has a name, and either a value or a set of child nodes.
YANG provides clear and concise descriptions of the nodes, as well as YANG provides clear and concise descriptions of the nodes, as well as
the interaction between those nodes. the interaction between those nodes.
YANG structures data models into modules and submodules. A module YANG structures data models into modules and submodules. A module
can import data from other external modules, and include data from can import data from other external modules, and include data from
submodules. The hierarchy can be augmented, allowing one module to submodules. The hierarchy can be augmented, allowing one module to
add data nodes to the hierarchy defined in another module. This add data nodes to the hierarchy defined in another module. This
skipping to change at page 14, line 8 skipping to change at page 14, line 21
YANG defines a set of built-in types, and has a type mechanism YANG defines a set of built-in types, and has a type mechanism
through which additional types may be defined. Derived types can through which additional types may be defined. Derived types can
restrict their base type's set of valid values using mechanisms like restrict their base type's set of valid values using mechanisms like
range or pattern restrictions that can be enforced by clients or range or pattern restrictions that can be enforced by clients or
servers. They can also define usage conventions for use of the servers. They can also define usage conventions for use of the
derived type, such as a string-based type that contains a host name. derived type, such as a string-based type that contains a host name.
YANG permits the definition of reusable groupings of nodes. The YANG permits the definition of reusable groupings of nodes. The
instantiation of these groupings can refine or augment the nodes, instantiation of these groupings can refine or augment the nodes,
allowing it to tailor the nodes to its particular needs. Derived allowing it to tailor the nodes to its particular needs. Derived
types and groupings can be defined in one module or submodule and types and groupings can be defined in one module and used in either
used in either that location or in another module or submodule that the same module or in another module that imports it.
imports or includes it.
YANG data hierarchy constructs include defining lists where list YANG data hierarchy constructs include defining lists where list
entries are identified by keys that distinguish them from each other. entries are identified by keys that distinguish them from each other.
Such lists may be defined as either sorted by user or automatically Such lists may be defined as either sorted by user or automatically
sorted by the system. For user-sorted lists, operations are defined sorted by the system. For user-sorted lists, operations are defined
for manipulating the order of the list entries. for manipulating the order of the list entries.
YANG modules can be translated into an equivalent XML syntax called YANG modules can be translated into an equivalent XML syntax called
YANG Independent Notation (YIN) (Section 12), allowing applications YANG Independent Notation (YIN) (Section 13), allowing applications
using XML parsers and Extensible Stylesheet Language Transformations using XML parsers and Extensible Stylesheet Language Transformations
(XSLT) scripts to operate on the models. The conversion from YANG to (XSLT) scripts to operate on the models. The conversion from YANG to
YIN is lossless, so content in YIN can be round-tripped back into YIN is lossless, so content in YIN can be round-tripped back into
YANG. YANG.
YANG strikes a balance between high-level data modeling and low-level YANG strikes a balance between high-level data modeling and low-level
bits-on-the-wire encoding. The reader of a YANG module can see the bits-on-the-wire encoding. The reader of a YANG module can see the
high-level view of the data model while understanding how the data high-level view of the data model while understanding how the data
will be encoded in NETCONF operations. will be encoded in NETCONF operations.
skipping to change at page 15, line 22 skipping to change at page 15, line 34
4.2.1. Modules and Submodules 4.2.1. Modules and Submodules
A module contains three types of statements: module-header A module contains three types of statements: module-header
statements, revision statements, and definition statements. The statements, revision statements, and definition statements. The
module header statements describe the module and give information module header statements describe the module and give information
about the module itself, the revision statements give information about the module itself, the revision statements give information
about the history of the module, and the definition statements are about the history of the module, and the definition statements are
the body of the module where the data model is defined. the body of the module where the data model is defined.
A NETCONF server may implement a number of modules, allowing multiple A device may implement a number of modules, allowing multiple views
views of the same data, or multiple views of disjoint subsections of of the same data, or multiple views of disjoint subsections of the
the device's data. Alternatively, the server may implement only one device's data. Alternatively, the server may implement only one
module that defines all available data. module that defines all available data.
A module may be divided into submodules, based on the needs of the A module may be divided into submodules, based on the needs of the
module owner. The external view remains that of a single module, module owner. The external view remains that of a single module,
regardless of the presence or size of its submodules. regardless of the presence or size of its submodules.
The "import" statement allows a module or submodule to reference The "import" statement allows a module or submodule to reference
material defined in other modules. material defined in other modules.
The "include" statement is used by a module to incorporate the The "include" statement is used by a module to incorporate the
contents of its submodules into the module. contents of its submodules into the module.
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 examples show 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 instance contains simple data like an integer or a string. It
exactly one value of a particular type and no child nodes. has exactly one value of a particular type and no child nodes.
YANG Example: YANG Example:
leaf host-name { leaf host-name {
type string; type string;
description "Hostname for this system"; description
} "Hostname for this system";
}
NETCONF XML Example: NETCONF XML Example:
<host-name>my.example.com</host-name> <host-name>my.example.com</host-name>
The "leaf" statement is covered in Section 7.6. The "leaf" statement is covered in Section 7.6.
4.2.2.2. Leaf-List Nodes 4.2.2.2. Leaf-List Nodes
A leaf-list defines a sequence of values of a particular type. A leaf-list defines a sequence of values of a particular type.
YANG Example: YANG Example:
leaf-list domain-search { leaf-list domain-search {
type string; type string;
description "List of domain names to search"; description
"List of domain names to search";
} }
NETCONF XML Example: NETCONF XML Example:
<domain-search>high.example.com</domain-search> <domain-search>high.example.com</domain-search>
<domain-search>low.example.com</domain-search> <domain-search>low.example.com</domain-search>
<domain-search>everywhere.example.com</domain-search> <domain-search>everywhere.example.com</domain-search>
The "leaf-list" statement is covered in Section 7.7. The "leaf-list" statement is covered in Section 7.7.
4.2.2.3. Container Nodes 4.2.2.3. Container Nodes
A container node is used to group related nodes in a subtree. A A container is used to group related nodes in a subtree. A container
container has only child nodes and no value. A container may contain has only child nodes and no value. A container may contain any
any number of child nodes of any type (including leafs, lists, number of child nodes of any type (leafs, lists, containers, leaf-
containers, and leaf-lists). lists, and actions).
YANG Example: YANG Example:
container system { container system {
container login { container login {
leaf message { leaf message {
type string; type string;
description description
"Message given at start of login session"; "Message given at start of login session";
}
} }
}
} }
NETCONF XML Example: NETCONF XML Example:
<system> <system>
<login> <login>
<message>Good morning</message> <message>Good morning</message>
</login> </login>
</system> </system>
skipping to change at page 17, line 26 skipping to change at page 18, line 6
A list defines a sequence of list entries. Each entry is like a A list defines a sequence of list entries. Each entry is like a
structure or a record instance, and is uniquely identified by the structure or a record instance, and is uniquely identified by the
values of its key leafs. A list can define multiple key leafs and values of its key leafs. A list can define multiple key leafs and
may contain any number of child nodes of any type (including leafs, may 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 {
type string; type string;
} }
leaf class { leaf class {
type string; type string;
} }
} }
NETCONF XML Example: NETCONF XML Example:
<user> <user>
<name>glocks</name> <name>glocks</name>
<full-name>Goldie Locks</full-name> <full-name>Goldie Locks</full-name>
<class>intruder</class> <class>intruder</class>
</user> </user>
<user> <user>
skipping to change at page 19, line 7 skipping to change at page 18, line 44
</user> </user>
The "list" statement is covered in Section 7.8. The "list" statement is covered in Section 7.8.
4.2.2.5. Example Module 4.2.2.5. Example Module
These statements are combined to define the module: These statements are combined to define the module:
// Contents of "acme-system.yang" // Contents of "acme-system.yang"
module acme-system { module acme-system {
yang-version 1.1; yang-version 1.1;
namespace "http://acme.example.com/system"; namespace "http://acme.example.com/system";
prefix "acme"; prefix "acme";
organization "ACME Inc."; organization "ACME Inc.";
contact "joe@acme.example.com"; contact "joe@acme.example.com";
description description
"The module for entities implementing the ACME system."; "The module for entities implementing the ACME system.";
revision 2007-06-09 { revision 2007-06-09 {
description "Initial revision."; description "Initial revision.";
} }
container system { container system {
leaf host-name { leaf host-name {
type string; type string;
description "Hostname for this system"; description
} "Hostname for this system";
}
leaf-list domain-search { leaf-list domain-search {
type string; type string;
description "List of domain names to search"; description
} "List of domain names to search";
}
container login { container login {
leaf message { leaf message {
type string; type string;
description description
"Message given at start of login session"; "Message given at start of login session";
} }
list user { list user {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf full-name { leaf full-name {
type string; type string;
} }
leaf class { leaf class {
type string; type string;
}
}
} }
}
} }
}
} }
4.2.3. State Data 4.2.3. State Data
YANG can model state data, as well as configuration data, based on YANG can model state data, as well as configuration data, based on
the "config" statement. When a node is tagged with "config false", the "config" statement. When a node is tagged with "config false",
its subhierarchy is flagged as state data, to be reported using its subhierarchy is flagged as state data. In NETCONF, state data is
NETCONF's <get> operation, not the <get-config> operation. Parent reported using the <get> operation, not the <get-config> operation.
containers, lists, and key leafs are reported also, giving the Parent containers, lists, and key leafs are reported also, giving the
context for the state data. context for the state data.
In this example, two leafs are defined for each interface, a In this example, two leafs are defined for each interface, a
configured speed and an observed speed. The observed speed is not configured speed and an observed speed. The observed speed is not
configuration, so it can be returned with NETCONF <get> operations, configuration, so it can be returned with NETCONF <get> operations,
but not with <get-config> operations. The observed speed is not but not with <get-config> operations. The observed speed is not
configuration data, and it cannot be manipulated using <edit-config>. configuration data, and it cannot be manipulated using <edit-config>.
list interface { list interface {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
leaf speed { leaf speed {
type enumeration { type enumeration {
enum 10m; enum 10m;
enum 100m; enum 100m;
enum auto; enum auto;
}
}
leaf observed-speed {
type uint32;
config false;
} }
}
leaf observed-speed {
type uint32;
config false;
}
} }
4.2.4. Built-In Types 4.2.4. Built-In Types
YANG has a set of built-in types, similar to those of many YANG has a set of built-in types, similar to those of many
programming languages, but with some differences due to special programming languages, but with some differences due to special
requirements from the management domain. The following table requirements from the management domain. The following table
summarizes the built-in types discussed in Section 9: summarizes the built-in types discussed in Section 9:
+---------------------+-------------------------------------+ +---------------------+-------------------------------------+
skipping to change at page 21, line 42 skipping to change at page 21, line 42
YANG can define derived types from base types using the "typedef" YANG can define derived types from base types using the "typedef"
statement. A base type can be either a built-in type or a derived statement. A base type can be either a built-in type or a derived
type, allowing a hierarchy of derived types. type, allowing a hierarchy of derived types.
A derived type can be used as the argument for the "type" statement. A derived type can be used as the argument for the "type" statement.
YANG Example: YANG Example:
typedef percent { typedef percent {
type uint8 { type uint8 {
range "0 .. 100"; range "0 .. 100";
} }
description "Percentage";
} }
leaf completed { leaf completed {
type percent; type percent;
} }
NETCONF XML Example: NETCONF XML Example:
<completed>20</completed> <completed>20</completed>
The "typedef" statement is covered in Section 7.3. The "typedef" statement is covered in Section 7.3.
4.2.6. Reusable Node Groups (grouping) 4.2.6. Reusable Node Groups (grouping)
Groups of nodes can be assembled into reusable collections using the Groups of nodes can be assembled into reusable collections using the
"grouping" statement. A grouping defines a set of nodes that are "grouping" statement. A grouping defines a set of nodes that are
instantiated with the "uses" statement: instantiated with the "uses" statement:
grouping target { grouping target {
leaf address { leaf address {
type inet:ip-address; type inet:ip-address;
description "Target IP address"; description "Target IP address";
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
description "Target port number"; description "Target port number";
} }
} }
container peer { container peer {
container destination { container destination {
uses target; uses target;
} }
} }
NETCONF XML Example: NETCONF XML Example:
<peer> <peer>
<destination> <destination>
<address>192.0.2.1</address> <address>192.0.2.1</address>
<port>830</port> <port>830</port>
</destination> </destination>
</peer> </peer>
The grouping can be refined as it is used, allowing certain The grouping can be refined as it is used, allowing certain
statements to be overridden. In this example, the description is statements to be overridden. In this example, the description is
refined: refined:
container connection { container connection {
container source { container source {
uses target { uses target {
refine "address" { refine "address" {
description "Source IP address"; description "Source IP address";
} }
refine "port" { refine "port" {
description "Source port number"; description "Source port number";
} }
}
} }
container destination { }
uses target { container destination {
refine "address" { uses target {
description "Destination IP address"; refine "address" {
} description "Destination IP address";
refine "port" { }
description "Destination port number"; refine "port" {
} description "Destination port number";
} }
} }
}
} }
The "grouping" statement is covered in Section 7.12. The "grouping" statement is covered in Section 7.12.
4.2.7. Choices 4.2.7. Choices
YANG allows the data model to segregate incompatible nodes into YANG allows the data model to segregate incompatible nodes into
distinct choices using the "choice" and "case" statements. The distinct choices using the "choice" and "case" statements. The
"choice" statement contains a set of "case" statements that define "choice" statement contains a set of "case" statements that define
sets of schema nodes that cannot appear together. Each "case" may sets of schema nodes that cannot appear together. Each "case" may
contain multiple nodes, but each node may appear in only one "case" contain multiple nodes, but each node may appear in only one "case"
under a "choice". under a "choice".
When a node from one case is created in the data tree, all nodes from When a node from one case is created in the data tree, all nodes from
all other cases are implicitly deleted. The device handles the all other cases are implicitly deleted. The device handles the
enforcement of the constraint, preventing incompatibilities from enforcement of the constraint, preventing incompatibilities from
existing in the configuration. existing in the configuration.
The choice and case nodes appear only in the schema tree, not in the The choice and case nodes appear only in the schema tree but not in
data tree or NETCONF messages. The additional levels of hierarchy the data tree. The additional levels of hierarchy are not needed
are not needed beyond the conceptual schema. beyond the conceptual schema.
YANG Example: YANG Example:
container food { container food {
choice snack { choice snack {
case sports-arena { case sports-arena {
leaf pretzel { leaf pretzel {
type empty; type empty;
}
leaf beer {
type empty;
}
} }
case late-night { leaf beer {
leaf chocolate { type empty;
type enumeration { }
enum dark; }
enum milk; case late-night {
enum first-available; leaf chocolate {
} type enumeration {
} enum dark;
enum milk;
enum first-available;
}
} }
}
} }
} }
NETCONF XML Example: NETCONF XML Example:
<food> <food>
<pretzel/> <pretzel/>
<beer/> <beer/>
</food> </food>
The "choice" statement is covered in Section 7.9. The "choice" statement is covered in Section 7.9.
skipping to change at page 25, line 6 skipping to change at page 25, line 6
module. This is useful for example for vendors to add vendor- module. This is useful for example for vendors to add vendor-
specific parameters to standard data models in an interoperable way. specific parameters to standard data models in an interoperable way.
The "augment" statement defines the location in the data model The "augment" statement defines the location in the data model
hierarchy where new nodes are inserted, and the "when" statement hierarchy where new nodes are inserted, and the "when" statement
defines the conditions when the new nodes are valid. defines the conditions when the new nodes are valid.
YANG Example: YANG Example:
augment /system/login/user { augment /system/login/user {
when "class != 'wheel'"; when "class != 'wheel'";
leaf uid { leaf uid {
type uint16 { type uint16 {
range "1000 .. 30000"; range "1000 .. 30000";
}
} }
}
} }
This example defines a "uid" node that only is valid when the user's This example defines a "uid" node that only is valid when the user's
"class" is not "wheel". "class" is not "wheel".
If a module augments another module, the XML representation of the If a module augments another module, the XML representation of the
data will reflect the prefix of the augmenting module. For example, data will reflect the prefix of the augmenting module. For example,
if the above augmentation were in a module with prefix "other", the if the above augmentation were in a module with prefix "other", the
XML would look like: XML would look like:
skipping to change at page 26, line 6 skipping to change at page 26, line 6
YANG allows the definition of operations. The operations' names, YANG allows the definition of operations. The operations' names,
input parameters, and output parameters are modeled using YANG data input parameters, and output parameters are modeled using YANG data
definition statements. Operations on the top-level in a module are definition statements. Operations on the top-level in a module are
defined with the "rpc" statement. Operations can also be tied to a defined with the "rpc" statement. Operations can also be tied to a
node in the data hierarchy. Such operations are defined with the node in the data hierarchy. Such operations are defined with the
"action" statement. "action" statement.
YANG Example: YANG Example:
rpc activate-software-image { rpc activate-software-image {
input { input {
leaf image-name { leaf image-name {
type string; type string;
}
} }
output { }
leaf status { output {
type string; leaf status {
} type string;
} }
}
} }
NETCONF XML Example: NETCONF XML Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<activate-software-image xmlns="http://acme.example.com/system"> <activate-software-image xmlns="http://acme.example.com/system">
<image-name>acmefw-2.3</image-name> <image-name>acmefw-2.3</image-name>
</activate-software-image> </activate-software-image>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<status xmlns="http://acme.example.com/system"> <status xmlns="http://acme.example.com/system">
The image acmefw-2.3 is being installed. The image acmefw-2.3 is being installed.
</status> </status>
</rpc-reply> </rpc-reply>
YANG Example:
list interface {
key "name";
leaf name {
type string;
}
action ping {
input {
leaf destination {
type inet:ip-address;
}
}
output {
leaf packet-loss {
type uint8;
}
}
}
}
NETCONF XML Example:
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<interface xmlns="http://acme.example.com/system">
<name>eth1</name>
<ping>
<destination>192.0.2.1</destination>
</ping>
</interface>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:acme="http://acme.example.com/system">
<acme:packet-loss>60</acme:packet-loss>
</rpc-reply>
The "rpc" statement is covered in Section 7.14, and the "action" The "rpc" statement is covered in Section 7.14, and the "action"
statement in Section 7.15. statement in Section 7.15.
4.2.10. Notification Definitions 4.2.10. Notification Definitions
YANG allows the definition of notifications suitable for NETCONF. YANG allows the definition of notifications. YANG data definition
YANG data definition statements are used to model the content of the 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
leaf if-name { "A link failure has been detected";
type leafref { leaf if-name {
path "/interface/name"; type leafref {
} path "/interface/name";
}
leaf if-admin-status {
type admin-status;
}
leaf if-oper-status {
type oper-status;
} }
}
leaf if-admin-status {
type admin-status;
}
leaf if-oper-status {
type oper-status;
}
} }
NETCONF XML Example: NETCONF XML Example:
<notification <notification
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> xmlns="urn:ietf:params:netconf:capability:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime> <eventTime>2007-09-01T10:00:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system"> <link-failure xmlns="http://acme.example.com/system">
<if-name>so-1/2/3.0</if-name> <if-name>so-1/2/3.0</if-name>
<if-admin-status>up</if-admin-status> <if-admin-status>up</if-admin-status>
skipping to change at page 28, line 30 skipping to change at page 29, line 30
o For a module or submodule to reference definitions in an external o For a module or submodule to reference definitions in an external
module, the external module MUST be imported. module, the external module MUST be imported.
o A module MUST include all its submodules. o A module MUST include all its submodules.
o A module or submodule belonging to that module can reference o A module or submodule belonging to that module can reference
definitions in the module and all submodules included by the definitions in the module and all submodules included by the
module. module.
There MUST NOT be any circular chains of imports or includes. For There MUST NOT be any circular chains of imports. For example, if
example, if module "a" imports module "b", "b" cannot import "a". module "a" imports module "b", "b" cannot import "a".
When a definition in an external module is referenced, a locally When a definition in an external module is referenced, a locally
defined prefix MUST be used, followed by ":", and then the external defined prefix MUST be used, followed by ":", and then the external
identifier. References to definitions in the local module MAY use identifier. References to definitions in the local module MAY use
the prefix notation. Since built-in data types do not belong to any 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., module and have no prefix, references to built-in data types (e.g.,
int32) cannot use the prefix notation. The syntax for a reference to int32) cannot use the prefix notation. The syntax for a reference to
a definition is formally defined by the rule "identifier-ref" in a definition is formally defined by the rule "identifier-ref" in
Section 13. Section 14.
5.1.1. Import and Include by Revision 5.1.1. Import and Include by Revision
Published modules evolve independently over time. In order to allow Published modules evolve independently over time. In order to allow
for this evolution, modules need to be imported using specific for this evolution, modules need to be imported using specific
revisions. When a module is written, it uses the current revisions revisions. When a module is written, it uses the current revisions
of other modules, based on what is available at the time. As future of other modules, based on what is available at the time. As future
revisions of the imported modules are published, the importing module revisions of the imported modules are published, the importing module
is unaffected and its contents are unchanged. When the author of the is unaffected and its contents are unchanged. When the author of the
module is prepared to move to the most recently published revision of module is prepared to move to the most recently published revision of
skipping to change at page 29, line 15 skipping to change at page 30, line 15
imported module. imported module.
For submodules, the issue is related but simpler. A module or For submodules, the issue is related but simpler. A module or
submodule that includes submodules needs to specify the revision of submodule that includes submodules needs to specify the revision of
the included submodules. If a submodule changes, any module or the included submodules. If a submodule changes, any module or
submodule that includes it needs to be updated. submodule that includes it needs to be updated.
For example, module "b" imports module "a". For example, module "b" imports module "a".
module a { module a {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/a"; namespace "http://example.com/a";
prefix "a"; prefix "a";
revision 2008-01-01 { ... } revision 2008-01-01 { ... }
grouping a { grouping a {
leaf eh { .... } leaf eh { .... }
} }
} }
module b { module b {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/b"; namespace "http://example.com/b";
prefix "b"; prefix "b";
import a { import a {
prefix p; prefix "p";
revision-date 2008-01-01; revision-date 2008-01-01;
} }
container bee { container bee {
uses p:a; uses p:a;
} }
} }
When the author of "a" publishes a new revision, the changes may not When the author of "a" publishes a new revision, the changes may not
be acceptable to the author of "b". If the new revision is be acceptable to the author of "b". If the new revision is
acceptable, the author of "b" can republish with an updated revision acceptable, the author of "b" can republish with an updated revision
in the "import" statement. in the "import" statement.
5.1.2. Module Hierarchies 5.1.2. Module Hierarchies
YANG allows modeling of data in multiple hierarchies, where data may YANG allows modeling of data in multiple hierarchies, where data may
have more than one top-level node. Models that have multiple top- have more than one top-level node. Models that have multiple top-
level nodes are sometimes convenient, and are supported by YANG. level nodes are sometimes convenient, and are supported by YANG.
5.1.2.1. NETCONF XML Encoding
NETCONF is capable of carrying any XML content as the payload in the NETCONF is capable of carrying any XML content as the payload in the
<config> and <data> elements. The top-level nodes of YANG modules <config> and <data> elements. The top-level nodes of YANG modules
are encoded as child elements, in any order, within these elements. are encoded as child elements, in any order, within these elements.
This encapsulation guarantees that the corresponding NETCONF messages This encapsulation guarantees that the corresponding NETCONF messages
are always well-formed XML documents. are always well-formed XML documents.
For example: For example:
module my-config { module my-config {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/schema/config"; namespace "http://example.com/schema/config";
prefix "co"; prefix "co";
container system { ... } container system { ... }
container routing { ... } container routing { ... }
} }
could be encoded in NETCONF as: could be encoded in NETCONF as:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
skipping to change at page 30, line 49 skipping to change at page 31, line 51
</edit-config> </edit-config>
</rpc> </rpc>
5.2. File Layout 5.2. File Layout
YANG modules and submodules are typically stored in files, one module YANG modules and submodules are typically stored in files, one module
or submodule per file. The name of the file SHOULD be of the form: or submodule per file. The name of the file SHOULD be of the form:
module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' ) module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )
YANG compilers can find imported modules and included submodules via YANG parsers can find imported modules and included submodules via
this convention. While the YANG language defines modules, tools may this convention.
compile submodules independently for performance and manageability
reasons. Errors and warnings that cannot be detected during
submodule compilation may be delayed until the submodules are linked
into a cohesive module.
5.3. XML Namespaces 5.3. XML Namespaces
All YANG definitions are specified within a module that is bound to a All YANG definitions are specified within a module that is bound to a
particular XML namespace [XML-NAMES], which is a globally unique URI particular XML namespace [XML-NAMES], which is a globally unique URI
[RFC3986]. A NETCONF client or server uses the namespace during XML [RFC3986]. A NETCONF client or server uses the namespace during XML
encoding of data. encoding of data.
Namespaces for modules published in RFC streams [RFC4844] MUST be XML namespaces for modules published in RFC streams [RFC4844] MUST be
assigned by IANA, see Section 15. assigned by IANA, see section 14 in [RFC6020].
Namespaces for private modules are assigned by the organization XML namespaces for private modules are assigned by the organization
owning the module without a central registry. Namespace URIs MUST be owning the module without a central registry. Namespace URIs MUST be
chosen so they cannot collide with standard or other enterprise chosen so they cannot collide with standard or other enterprise
namespaces, for example by using the enterprise or organization name namespaces, for example by using the enterprise or organization name
in the namespace. in the namespace.
The "namespace" statement is covered in Section 7.1.3. The "namespace" statement is covered in Section 7.1.3.
5.3.1. YANG XML Namespace 5.3.1. YANG XML Namespace
YANG defines an XML namespace for NETCONF <edit-config> operations, YANG defines an XML namespace for NETCONF <edit-config> operations,
skipping to change at page 32, line 27 skipping to change at page 33, line 25
pieces of their module are presented to the outside world, supporting pieces of their module are presented to the outside world, supporting
the need to hide internal information and maintaining a boundary the need to hide internal information and maintaining a boundary
between what is shared with the outside world and what is kept between what is shared with the outside world and what is kept
private. private.
Scoped definitions MUST NOT shadow definitions at a higher scope. A Scoped definitions MUST NOT shadow definitions at a higher scope. A
type or grouping cannot be defined if a higher level in the schema type or grouping 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.
A reference to an unprefixed type or grouping, or one which uses the A reference to an unprefixed type or grouping, or one which uses the
prefix of the current module, is resolved by locating the closest prefix of the current module, is resolved by locating the matching
matching "typedef" or "grouping" statement among the immediate "typedef" or "grouping" statement among the immediate substatements
substatements of each ancestor statement. of each ancestor statement.
5.6. 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 of reduce the utility of the model and increase fragility of
applications that use it. applications that use it.
skipping to change at page 33, line 7 skipping to change at page 33, line 50
o the basic behavior of the model o the basic behavior of the model
o optional features that are part of the model o optional features that are part of the model
o deviations from the model o deviations from the model
We will consider each of these in sequence. We will consider each of these in sequence.
5.6.1. Basic Behavior 5.6.1. Basic Behavior
The model defines a contract between the NETCONF client and server, The model defines a contract between a YANG-based client and server,
which allows both parties to have faith the other knows the syntax which allows both parties to have faith the other knows the syntax
and semantics behind the modeled data. The strength of YANG lies in and semantics behind the modeled data. The strength of YANG lies in
the strength of this contract. the strength of this contract.
5.6.2. Optional Features 5.6.2. Optional Features
In many models, the modeler will allow sections of the model to be In many models, the modeler will allow sections of the model to be
conditional. The device controls whether these conditional portions conditional. The device controls whether these conditional portions
of the model are supported or valid for that particular device. of the model are supported or valid for that particular device.
skipping to change at page 34, line 26 skipping to change at page 35, line 21
takes as its argument a string that identifies a node in the schema takes as its argument a string that identifies a node in the schema
tree. The contents of the statement details the manner in which the tree. The contents of the statement details the manner in which the
device implementation deviates from the contract as defined in the device implementation deviates from the contract as defined in the
module. module.
Further details are available in Section 7.20.3. Further details are available in Section 7.20.3.
5.6.4. Implementing a Module 5.6.4. Implementing a Module
A server implements a module if it implements the module's data A server implements a module if it implements the module's data
nodes, rpcs, notifications, and deviations. nodes, rpcs, actions, notifications, and deviations.
A server MUST NOT implement more than one revision of a module. A server MUST NOT implement more than one revision of a module.
If a server implements a module A that imports a module B, and A uses If a server implements a module A that imports a module B, and A uses
any node from B in an "augment" or "path" statement that the server any node from B in an "augment" or "path" statement that the server
supports, then the server MUST implement a revision of module B that supports, then the server MUST implement a revision of module B that
has these nodes defined. This is regardless of if module B is has these nodes defined. This is regardless of if module B is
imported by revision or not. imported by revision or not.
NOTE: The next paragraph needs to be aligned with NOTE: The next paragraph needs to be aligned with
skipping to change at page 35, line 6 skipping to change at page 35, line 48
and it MUST set the leaf "default-revision" to "true" for this and it MUST set the leaf "default-revision" to "true" for this
module. module.
The reason for these rules is that clients need to be able to know The reason for these rules is that clients need to be able to know
the exact data model structure and types of all leafs and leaf-lists the exact data model structure and types of all leafs and leaf-lists
implemented in a server. implemented in a server.
For example, with these modules: For example, with these modules:
module a { module a {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/a"; namespace "http://example.com/a";
prefix "a"; prefix "a";
import b {
import b { revision-date 2015-01-01;
revision-date 2015-01-01; }
} import c;
import c;
revision 2015-01-01; revision 2015-01-01;
feature foo; feature foo;
augement "/b:x" { augment "/b:x" {
if-feature foo; if-feature foo;
leaf y { leaf y {
type b:myenum; type b:myenum;
}
} }
}
container a { container a {
leaf x { leaf x {
type c:bar; type c:bar;
}
} }
}
} }
module b { module b {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/b"; namespace "http://example.com/b";
prefix "b"; prefix "b";
revision 2015-04-04; revision 2015-04-04;
revision 2015-01-01; revision 2015-01-01;
typedef myenum { typedef myenum {
type enumeration { type enumeration {
enum zero; // added in 2015-01-01 enum zero; // added in 2015-01-01
enum one; // added in 2015-04-04 enum one; // added in 2015-04-04
}
} }
}
container x { // added in 2015-01-01 container x { // added in 2015-01-01
container y; // added in 2015-04-04 container y; // added in 2015-04-04
} }
} }
module c {
yang-version 1.1;
namespace "http://example.com/c";
prefix "c";
revision 2015-03-03; module c {
revision 2015-02-02; yang-version 1.1;
namespace "http://example.com/c";
prefix "c";
revision 2015-03-03;
revision 2015-02-02;
typedef foo { typedef foo {
... ...
} }
} }
A server that implements revision "2015-01-01" of module "a" and A server that implements revision "2015-01-01" of module "a" and
supports feature "foo" can implement revision "2015-01-01" or supports feature "foo" can implement revision "2015-01-01" or
"2015-04-04" of module "b". Since "b" was imported by revision, the "2015-04-04" of module "b". Since "b" was imported by revision, the
type of leaf "/b:x/a:y" is the same regardless of which revision of type of leaf "/b:x/a:y" is the same regardless of which revision of
"b" the server implements. "b" the server implements.
A server that implements module "a", but does not support feature A server that implements module "a", but does not support feature
"foo" does not have to implement module "b". "foo" does not have to implement module "b".
skipping to change at page 37, line 24 skipping to change at page 38, line 4
<name>b</module> <name>b</module>
<revision>2015-04-04</revision> <revision>2015-04-04</revision>
<conformance>implement</conformance> <conformance>implement</conformance>
</module> </module>
<module> <module>
<name>c</module> <name>c</module>
<revision>2015-02-02</revision> <revision>2015-02-02</revision>
<conformance>import</conformance> <conformance>import</conformance>
</module> </module>
</modules> </modules>
#}}
5.6.5. Announcing Conformance Information in NETCONF 5.6.5. Announcing Conformance Information in NETCONF
This document defines the following mechanism for announcing This document defines the following mechanism for announcing
conformance information. Other mechanisms may be defined by future conformance information. Other mechanisms may be defined by future
specifications. specifications.
A NETCONF server announces the modules it implements by implementing A NETCONF server announces the modules it implements by implementing
the YANG module "ietf-yang-library" defined in the YANG module "ietf-yang-library" defined in
[I-D.ietf-netconf-yang-library], and listing all implemented modules [I-D.ietf-netconf-yang-library], and listing all implemented modules
skipping to change at page 38, line 5 skipping to change at page 38, line 31
module-set-id=<id> module-set-id=<id>
The parameter "module-set-id" has the same value as the leaf The parameter "module-set-id" has the same value as the leaf
"/modules/module-set-id" from "ietf-yang-library". This parameter "/modules/module-set-id" from "ietf-yang-library". This parameter
MUST be present. MUST be present.
With this mechanism, a client can cache the supported modules for a With this mechanism, a client can cache the supported modules for a
server, and only update the cache if the "module-set-id" value in the server, and only update the cache if the "module-set-id" value in the
<hello> message changes. <hello> message changes.
5.7. Data Store Modification 5.7. Datastore Modification
Data models may allow the server to alter the configuration data Data models may allow the server to alter the configuration datastore
store in ways not explicitly directed via NETCONF protocol messages. in ways not explicitly directed via NETCONF protocol messages. For
For example, a data model may define leafs that are assigned system- example, a data model may define leafs that are assigned system-
generated values when the client does not provide one. A formal generated values when the client does not provide one. A formal
mechanism for specifying the circumstances where these changes are mechanism for specifying the circumstances where these changes are
allowed is out of scope for this specification. allowed is out of scope for this specification.
6. YANG Syntax 6. YANG Syntax
The YANG syntax is similar to that of SMIng [RFC3780] and programming The YANG syntax is similar to that of SMIng [RFC3780] and programming
languages like C and C++. This C-like syntax was chosen specifically languages like C and C++. This C-like syntax was chosen specifically
for its readability, since YANG values the time and effort of the for its readability, since YANG values the time and effort of the
readers of models above those of modules writers and YANG tool-chain readers of models above those of modules writers and YANG tool-chain
developers. This section introduces the YANG syntax. developers. This section introduces the YANG syntax.
YANG modules use the UTF-8 [RFC3629] character encoding. YANG modules use the UTF-8 [RFC3629] character encoding.
Legal characters in YANG modules are the Unicode and ISO/IEC 10646 Legal characters in YANG modules are the Unicode and ISO/IEC 10646
[ISO.10646] characters, including tab, carriage return, and line feed [ISO.10646] characters, including tab, carriage return, and line feed
but excluding the other C0 control characters, the surrogate blocks, but excluding the other C0 control characters, the surrogate blocks,
and the noncharacters. The character syntax is formally defined by and the noncharacters. The character syntax is formally defined by
the rule "yang-char" in Section 13. the rule "yang-char" in Section 14.
6.1. Lexical Tokenization 6.1. Lexical Tokenization
YANG modules are parsed as a series of tokens. This section details YANG modules are parsed as a series of tokens. This section details
the rules for recognizing tokens from an input stream. YANG the rules for recognizing tokens from an input stream. YANG
tokenization rules are both simple and powerful. The simplicity is tokenization rules are both simple and powerful. The simplicity is
driven by a need to keep the parsers easy to implement, while the driven by a need to keep the parsers easy to implement, while the
power is driven by the fact that modelers need to express their power is driven by the fact that modelers need to express their
models in readable formats. models in readable formats.
skipping to change at page 39, line 40 skipping to change at page 40, line 20
\t a tab character \t a tab character
\" a double quote \" a double quote
\\ a single backslash \\ a single backslash
It is an error if any other character follows the backslash It is an error if any other character follows the backslash
character. character.
If a quoted string is followed by a plus character ("+"), followed by If a quoted string is followed by a plus character ("+"), followed by
another quoted string, the two strings are concatenated into one another quoted string, the two strings are concatenated into one
string, allowing multiple concatenations to build one string. string, allowing multiple concatenations to build one string.
Whitespace trimming and substitution of backslash-escaped characters Whitespace trimming is done before substitution of backslash-escaped
in double-quoted strings is done before concatenation. characters in double-quoted strings. Concatenation is performed as
the last step.
6.1.3.1. Quoting Examples 6.1.3.1. Quoting Examples
The following strings are equivalent: The following strings are equivalent:
hello hello
"hello" "hello"
'hello' 'hello'
"hel" + "lo" "hel" + "lo"
'hel' + "lo" 'hel' + "lo"
skipping to change at page 40, line 32 skipping to change at page 41, line 12
"first line\n" + " second line" "first line\n" + " second line"
6.2. Identifiers 6.2. Identifiers
Identifiers are used to identify different kinds of YANG items by Identifiers are used to identify different kinds of YANG items by
name. Each identifier starts with an uppercase or lowercase ASCII name. Each identifier starts with an uppercase or lowercase ASCII
letter or an underscore character, followed by zero or more ASCII letter or an underscore character, followed by zero or more ASCII
letters, digits, underscore characters, hyphens, and dots. letters, digits, underscore characters, hyphens, and dots.
Implementations MUST support identifiers up to 64 characters in Implementations MUST support identifiers up to 64 characters in
length. Identifiers are case sensitive. The identifier syntax is length, and MAY support longer identifiers. Identifiers are case
formally defined by the rule "identifier" in Section 13. Identifiers sensitive. The identifier syntax is formally defined by the rule
can be specified as quoted or unquoted strings. "identifier" in Section 14. Identifiers can be specified as quoted
or unquoted strings.
6.2.1. Identifiers and Their Namespaces 6.2.1. Identifiers and Their Namespaces
Each identifier is valid in a namespace that depends on the type of Each identifier is valid in a namespace that depends on the type of
the YANG item being defined. All identifiers defined in a namespace the YANG item being defined. All identifiers defined in a namespace
MUST be unique. MUST be unique.
o All module and submodule names share the same global module o All module and submodule names share the same global module
identifier namespace. identifier namespace.
skipping to change at page 42, line 6 skipping to change at page 42, line 36
A module can introduce YANG extensions by using the "extension" A module can introduce YANG extensions by using the "extension"
keyword (see Section 7.19). The extensions can be imported by other keyword (see Section 7.19). The extensions can be imported by other
modules with the "import" statement (see Section 7.1.5). When an modules with the "import" statement (see Section 7.1.5). When an
imported extension is used, the extension's keyword MUST be qualified imported extension is used, the extension's keyword MUST be qualified
using the prefix with which the extension's module was imported. If using the prefix with which the extension's module was imported. If
an extension is used in the module where it is defined, the an extension is used in the module where it is defined, the
extension's keyword MUST be qualified with the module's prefix. extension's keyword MUST be qualified with the module's prefix.
If a YANG compiler does not support a particular extension, which If a YANG compiler does not support a particular extension, which
appears in a YANG module as an unknown-statement (see Section 13), appears in a YANG module as an unknown-statement (see Section 14),
the entire unknown-statement MAY be ignored by the compiler. the entire unknown-statement MAY be ignored by the compiler.
If a YANG parser does not support a particular extension, which
appears in a YANG module as an unknown-statement (see Section 14),
the entire unknown-statement MAY be ignored by the parser. Note that
even in this case the semantics associated with the extension still
apply (as if they were part of a description statement).
Care must be taken when defining extensions so that modules that use
the extensions are meaningful also for applications that do not
support the extensions.
6.4. XPath Evaluations 6.4. XPath Evaluations
YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation YANG relies on XML Path Language (XPath) 1.0 [XPATH] as a notation
for specifying many inter-node references and dependencies. NETCONF for specifying many inter-node references and dependencies. An
clients and servers are not required to implement an XPath implementation is not required to implement an XPath interpreter, but
interpreter, but MUST ensure that the requirements encoded in the MUST ensure that the requirements encoded in the data model are
data model are enforced. The manner of enforcement is an enforced. The manner of enforcement is an implementation decision.
implementation decision. The XPath expressions MUST be syntactically The XPath expressions MUST be syntactically correct, and all prefixes
correct, and all prefixes used MUST be present in the XPath context used MUST be present in the XPath context (see Section 6.4.1). An
(see Section 6.4.1). An implementation may choose to implement them implementation may choose to implement them by hand, rather than
by hand, rather than using the XPath expression directly. using the XPath expression directly.
The data model used in the XPath expressions is the same as that used The data model used in the XPath expressions is the same as that used
in XPath 1.0 [XPATH], with the same extension for root node children in XPath 1.0 [XPATH], with the same extension for root node children
as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means as used by XSLT 1.0 [XSLT] (Section 3.1). Specifically, it means
that the root node may have any number of element nodes as its that the root node may have any number of element nodes as its
children. children.
The data tree has no concept of document order. An implementation
needs to choose some document order but how it is done is an
implementation decision. This means that XPath expressions in YANG
modules SHOULD not rely on any specific document order.
Numbers in XPath 1.0 are IEEE 754 double-precision floating-point Numbers in XPath 1.0 are IEEE 754 double-precision floating-point
values, see Section 3.5 in [XPATH]. This means that some values of values, see Section 3.5 in [XPATH]. This means that some values of
int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3) int64, uint64 and decimal64 types (see Section 9.2 and Section 9.3)
cannot be exactly represented in XPath expressions. Therefore, due cannot be exactly represented in XPath expressions. Therefore, due
caution should be exercised when using nodes with 64-bit numeric caution should be exercised when using nodes with 64-bit numeric
values in XPath expressions. In particular, numerical comparisons values in XPath expressions. In particular, numerical comparisons
involving equality may yield unexpected results. involving equality may yield unexpected results.
For example, consider the following definition: For example, consider the following definition:
leaf lxiv { leaf lxiv {
type decimal64 { type decimal64 {
fraction-digits 18; fraction-digits 18;
} }
must ". <= 10"; must ". <= 10";
} }
An instance of the "lxiv" leaf having the value of An instance of the "lxiv" leaf having the value of
10.0000000000000001 will then successfully pass validation. 10.0000000000000001 will then successfully pass validation.
6.4.1. XPath Context 6.4.1. XPath Context
All YANG XPath expressions share the following XPath context All YANG XPath expressions share the following XPath context
definition: definition:
skipping to change at page 43, line 33 skipping to change at page 44, line 33
The mechanism for handling unprefixed names is adopted from XPath 2.0 The mechanism for handling unprefixed names is adopted from XPath 2.0
[XPATH2.0], and helps simplify XPath expressions in YANG. No [XPATH2.0], and helps simplify XPath expressions in YANG. No
ambiguity may ever arise because YANG node identifiers are always ambiguity may ever arise because YANG node identifiers are always
qualified names with a non-null namespace URI. qualified names with a non-null namespace URI.
The accessible tree depends on where the statement with the XPath The accessible tree depends on where the statement with the XPath
expression is defined: expression is defined:
o If the XPath expression is defined in substatement to a data node o If the XPath expression is defined in substatement to a data node
that represents configuration, the accessible tree is the data in that represents configuration, the accessible tree is the data in
the NETCONF datastore where the context node exists. The root the datastore where the context node exists. The root node has
node has all top-level configuration data nodes in all modules as all top-level configuration data nodes in all modules as children.
children.
o If the XPath expression is defined in a substatement to a data o If the XPath expression is defined in a substatement to a data
node that represents state data, the accessible tree is all all node that represents state data, the accessible tree is all state
state data on the device, and the "running" datastore. The root data on the device, and the running configuration datastore. The
node has all top-level data nodes in all modules as children. root node has all top-level data nodes in all modules as children.
o If the XPath expression is defined in a substatement to a o If the XPath expression is defined in a substatement to a
"notification" statement, the accessible tree is the notification "notification" statement, the accessible tree is the notification
instance, all state data on the device, and the "running" instance, all state data on the device, and the running
datastore. The root node has the node representing the configuration datastore. The root node has the node representing
notification being defined and all top-level data nodes in all the notification being defined and all top-level data nodes in all
modules as children. modules as children.
o If the XPath expression is defined in a substatement to an "input" o If the XPath expression is defined in a substatement to an "input"
statement in an "rpc" statement, the accessible tree is the RPC statement in an "rpc" or "action" statement, the accessible tree
operation instance, all state data on the device, and the is the RPC or action operation instance, all state data on the
"running" datastore. The root node has the node representing the device, and the running configuration datastore. The root node
operation being defined and all top-level data nodes in all has the node representing the operation being defined and all top-
modules as children. The node representing the operation being level data nodes in all modules as children. The node
defined has the operation's input parameters as children. representing the operation being defined has the operation's input
parameters as children.
o If the XPath expression is defined in a substatement to an o If the XPath expression is defined in a substatement to an
"output" statement in an "rpc" statement, the accessible tree is "output" statement in an "rpc" or "action" statement, the
the RPC operation's output, all state data on the device, and the accessible tree is the RPC or action operation's output, all state
"running" datastore. The root node has the node representing the data on the device, and the running configuration datastore. The
operation being defined and all top-level data nodes in all root node has the node representing the operation being defined
modules as children. The node representing the operation being and all top-level data nodes in all modules as children. The node
defined has the operation's output parameters as children. representing the operation being defined has the operation's
output parameters as children.
In the accessible tree, all leafs and leaf-lists with default values In the accessible tree, all leafs and leaf-lists with default values
in use exist (See Section 7.6.1 and Section 7.7.2). in use exist (See Section 7.6.1 and Section 7.7.2).
If a node that exists in the accessible tree has a non-presence If a node that exists in the accessible tree has a non-presence
container as a child, then the non-presence container also exists in container as a child, then the non-presence container also exists in
the tree. the tree.
The context node varies with the YANG XPath expression, and is The context node varies with the YANG XPath expression, and is
specified where the YANG statement with the XPath expression is specified where the YANG statement with the XPath expression is
defined. defined.
6.5. Schema Node Identifier 6.5. Schema Node Identifier
A schema node identifier is a string that identifies a node in the A schema node identifier is a string that identifies a node in the
schema tree. It has two forms, "absolute" and "descendant", defined schema tree. It has two forms, "absolute" and "descendant", defined
by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid" by the rules "absolute-schema-nodeid" and "descendant-schema-nodeid"
in Section 13, respectively. A schema node identifier consists of a in Section 14, respectively. A schema node identifier consists of a
path of identifiers, separated by slashes ("/"). In an absolute path of identifiers, separated by slashes ("/"). In an absolute
schema node identifier, the first identifier after the leading slash schema node identifier, the first identifier after the leading slash
is any top-level schema node in the local module or in all imported is any top-level schema node in the local module or in all imported
modules. modules.
References to identifiers defined in external modules MUST be References to identifiers defined in external modules MUST be
qualified with appropriate prefixes, and references to identifiers qualified with appropriate prefixes, and references to identifiers
defined in the current module and its submodules MAY use a prefix. defined in the current module and its submodules MAY use a prefix.
For example, to identify the child node "b" of top-level node "a", For example, to identify the child node "b" of top-level node "a",
skipping to change at page 45, line 9 skipping to change at page 46, line 9
The following sections describe all of the YANG statements. The following sections describe all of the YANG statements.
Note that even a statement that does not have any substatements Note that even a statement that does not have any substatements
defined in YANG can have vendor-specific extensions as substatements. defined in YANG can have vendor-specific extensions as substatements.
For example, the "description" statement does not have any For example, the "description" statement does not have any
substatements defined in YANG, but the following is legal: substatements defined in YANG, but the following is legal:
description "some text" { description "some text" {
acme:documentation-flag 5; acme:documentation-flag 5;
} }
7.1. The module Statement 7.1. The module Statement
The "module" statement defines the module's name, and groups all The "module" statement defines the module's name, and groups all
statements that belong to the module together. The "module" statements that belong to the module together. The "module"
statement's argument is the name of the module, followed by a block statement's argument is the name of the module, followed by a block
of substatements that hold detailed module information. The module of substatements that hold detailed module information. The module
name follows the rules for identifiers in Section 6.2. name follows the rules for identifiers in Section 6.2.
Names of modules published in RFC streams [RFC4844] MUST be assigned Names of modules published in RFC streams [RFC4844] MUST be assigned
by IANA, see Section 15. by IANA, see section 14 in [RFC6020].
Private module names are assigned by the organization owning the Private module names are assigned by the organization owning the
module without a central registry. It is RECOMMENDED to choose module without a central registry. It is RECOMMENDED to choose
module names that will have a low probability of colliding with module names that will have a low probability of colliding with
standard or other enterprise modules and submodules, e.g., by using standard or other enterprise modules and submodules, e.g., by using
the enterprise or organization name as a prefix for the module name. the enterprise or organization name as a prefix for the module name.
A module typically has the following layout: A module typically has the following layout:
module <module-name> { module <module-name> {
// header information // header information
<yang-version statement> <yang-version statement>
<namespace statement> <namespace statement>
<prefix statement> <prefix statement>
// linkage statements // linkage statements
<import statements> <import statements>
<include statements> <include statements>
// meta information // meta information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<other statements> <other statements>
} }
7.1.1. The module's Substatements 7.1.1. The module's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| augment | 7.17 | 0..n | | augment | 7.17 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
skipping to change at page 48, line 5 skipping to change at page 49, line 5
A module or submodule that doesn't contain the "yang-version" A module or submodule that doesn't contain the "yang-version"
statement, or one that contains the value "1", is developed for YANG statement, or one that contains the value "1", is developed for YANG
version 1, defined in [RFC6020]. version 1, defined in [RFC6020].
Handling of the "yang-version" statement for versions other than Handling of the "yang-version" statement for versions other than
"1.1" (the version defined here) is out of scope for this "1.1" (the version defined here) is out of scope for this
specification. Any document that defines a higher version will need specification. Any document that defines a higher version will need
to define the backward compatibility of such a higher version. to define the backward compatibility of such a higher version.
For compatibility between YANG version 1 and 1.1, see Section 12.
7.1.3. The namespace Statement 7.1.3. The namespace Statement
The "namespace" statement defines the XML namespace that all The "namespace" statement defines the XML namespace that all
identifiers defined by the module are qualified by, with the identifiers defined by the module are qualified by, with the
exception of data node identifiers defined inside a grouping (see exception of data node identifiers defined inside a grouping (see
Section 7.13 for details). The argument to the "namespace" statement Section 7.13 for details). The argument to the "namespace" statement
is the URI of the namespace. is the URI of the namespace.
See also Section 5.3. See also Section 5.3.
skipping to change at page 49, line 43 skipping to change at page 50, line 45
+---------------+---------+-------------+ +---------------+---------+-------------+
| prefix | 7.1.4 | 1 | | prefix | 7.1.4 | 1 |
| revision-date | 7.1.5.1 | 0..1 | | revision-date | 7.1.5.1 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
The import's Substatements The import's Substatements
7.1.5.1. The import's revision-date Statement 7.1.5.1. The import's revision-date Statement
The import's "revision-date" statement is used to specify the exact The import's "revision-date" statement is used to specify the exact
version of the module to import. The "revision-date" statement MUST version of the module to import.
match the most recent "revision" statement in the imported module.
7.1.6. The include Statement 7.1.6. The include Statement
The "include" statement is used to make content from a submodule The "include" statement is used to make content from a submodule
available to that submodule's parent module. The argument is an available to that submodule's parent module. The argument is an
identifier that is the name of the submodule to include. Modules are identifier that is the name of the submodule to include. Modules are
only allowed to include submodules that belong to that module, as only allowed to include submodules that belong to that module, as
defined by the "belongs-to" statement (see Section 7.2.2). defined by the "belongs-to" statement (see Section 7.2.2).
Submodules are only allowed to include other submodules belonging to
the same module.
When a module includes a submodule, it incorporates the contents of When a module includes a submodule, it incorporates the contents of
the submodule into the node hierarchy of the module. the submodule into the node hierarchy of the module.
For backward compatibility with YANG version 1, a submodule is For backward compatibility with YANG version 1, a submodule is
allowed to include another submodule belonging to the same module, allowed to include another submodule belonging to the same module,
but this is not necessary in YANG version 1.1. but this is not necessary in YANG version 1.1.
When the optional "revision-date" substatement is present, the When the optional "revision-date" substatement is present, the
specified revision of the submodule is included in the module. It is specified revision of the submodule is included in the module. It is
an error if the specified revision of the submodule does not exist. an error if the specified revision of the submodule does not exist.
skipping to change at page 51, line 21 skipping to change at page 52, line 21
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.1.10. Usage Example 7.1.10. Usage Example
module acme-system { module acme-system {
yang-version 1.1; yang-version 1.1;
namespace "http://acme.example.com/system"; namespace "http://acme.example.com/system";
prefix "acme"; prefix "acme";
import ietf-yang-types { import ietf-yang-types {
prefix "yang"; prefix "yang";
} }
include acme-types; include acme-types;
organization "ACME Inc."; organization "ACME Inc.";
contact contact
"Joe L. User "Joe L. User
ACME, Inc. ACME, Inc.
42 Anywhere Drive 42 Anywhere Drive
Nowhere, CA 95134 Nowhere, CA 95134
USA USA
Phone: +1 800 555 0100 Phone: +1 800 555 0100
EMail: joe@acme.example.com"; EMail: joe@acme.example.com";
description description
"The module for entities implementing the ACME protocol."; "The module for entities implementing the ACME protocol.";
revision "2007-06-09" { revision "2007-06-09" {
description "Initial revision."; description "Initial revision.";
} }
// definitions follow... // definitions follow...
} }
7.2. The submodule Statement 7.2. The submodule Statement
While the primary unit in YANG is a module, a YANG module can itself While the primary unit in YANG is a module, a YANG module can itself
be constructed out of several submodules. Submodules allow a module be constructed out of several submodules. Submodules allow a module
designer to split a complex model into several pieces where all the designer to split a complex model into several pieces where all the
submodules contribute to a single namespace, which is defined by the submodules contribute to a single namespace, which is defined by the
module that includes the submodules. module that includes the submodules.
The "submodule" statement defines the submodule's name, and groups The "submodule" statement defines the submodule's name, and groups
all statements that belong to the submodule together. The all statements that belong to the submodule together. The
"submodule" statement's argument is the name of the submodule, "submodule" statement's argument is the name of the submodule,
followed by a block of substatements that hold detailed submodule followed by a block of substatements that hold detailed submodule
information. The submodule name follows the rules for identifiers in information. The submodule name follows the rules for identifiers in
Section 6.2. Section 6.2.
Names of submodules published in RFC streams [RFC4844] MUST be Names of submodules published in RFC streams [RFC4844] MUST be
assigned by IANA, see Section 15. assigned by IANA, see section 14 in [RFC6020].
Private submodule names are assigned by the organization owning the Private submodule names are assigned by the organization owning the
submodule without a central registry. It is RECOMMENDED to choose submodule without a central registry. It is RECOMMENDED to choose
submodule names 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 and submodules, e.g., by using standard or other enterprise modules and submodules, e.g., by using
the enterprise or organization name as a prefix for the submodule the enterprise or organization name as a prefix for the submodule
name. name.
A submodule typically has the following layout: A submodule typically has the following layout:
submodule <module-name> { submodule <module-name> {
<yang-version statement> <yang-version statement>
// module identification // module identification
<belongs-to statement> <belongs-to statement>
// linkage statements // linkage statements
<import statements> <import statements>
// meta information // meta information
<organization statement> <organization statement>
<contact statement> <contact statement>
<description statement> <description statement>
<reference statement> <reference statement>
// revision history // revision history
<revision statements> <revision statements>
// module definitions // module definitions
<other statements> <other statements>
} }
7.2.1. The submodule's Substatements 7.2.1. The submodule's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| augment | 7.17 | 0..n | | augment | 7.17 | 0..n |
| belongs-to | 7.2.2 | 1 | | belongs-to | 7.2.2 | 1 |
skipping to change at page 55, line 16 skipping to change at page 56, line 16
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| prefix | 7.1.4 | 1 | | prefix | 7.1.4 | 1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
The belongs-to's Substatements The belongs-to's Substatements
7.2.3. Usage Example 7.2.3. Usage Example
submodule acme-types { submodule acme-types {
yang-version 1.1; yang-version 1.1;
belongs-to "acme-system" { belongs-to "acme-system" {
prefix "acme"; prefix "acme";
} }
import ietf-yang-types { import ietf-yang-types {
prefix "yang"; prefix "yang";
} }
organization "ACME Inc."; organization "ACME Inc.";
contact contact
"Joe L. User "Joe L. User
ACME, Inc. ACME, Inc.
42 Anywhere Drive 42 Anywhere Drive
Nowhere, CA 95134 Nowhere, CA 95134
USA USA
Phone: +1 800 555 0100 Phone: +1 800 555 0100
EMail: joe@acme.example.com"; EMail: joe@acme.example.com";
description description
"This submodule defines common ACME types."; "This submodule defines common ACME types.";
revision "2007-06-09" { revision "2007-06-09" {
description "Initial revision."; description "Initial revision.";
} }
// definitions follows... // definitions follows...
} }
7.3. The typedef Statement 7.3. The typedef Statement
The "typedef" statement defines a new type that may be used locally The "typedef" statement defines a new type that may be used locally
in the module or submodule, and by other modules that import from it, in the module or submodule, and by other modules that import from it,
according to the rules in Section 5.5. The new type is called the according to the rules in Section 5.5. The new type is called the
"derived type", and the type from which it was derived is called the "derived type", and the type from which it was derived is called the
"base type". All derived types can be traced back to a YANG built-in "base type". All derived types can be traced back to a YANG built-in
type. type.
skipping to change at page 57, line 13 skipping to change at page 58, line 13
also the default value of the new derived type. also the default value of the new derived type.
If the type's default value is not valid according to the new If the type's default value is not valid according to the new
restrictions specified in a derived type or leaf definition, the restrictions specified in a derived type or leaf definition, the
derived type or leaf definition MUST specify a new default value derived type or leaf definition MUST specify a new default value
compatible with the restrictions. compatible with the restrictions.
7.3.5. Usage Example 7.3.5. Usage Example
typedef listen-ipv4-address { typedef listen-ipv4-address {
type inet:ipv4-address; type inet:ipv4-address;
default "0.0.0.0"; default "0.0.0.0";
} }
7.4. The type Statement 7.4. The type Statement
The "type" statement takes as an argument a string that is the name The "type" statement takes as an argument a string that is the name
of a YANG built-in type (see Section 9) or a derived type (see of a YANG built-in type (see Section 9) or a derived type (see
Section 7.3), followed by an optional block of substatements that are Section 7.3), followed by an optional block of substatements that are
used to put further restrictions on the type. used to put further restrictions on the type.
The restrictions that can be applied depend on the type being The restrictions that can be applied depend on the type being
skipping to change at page 58, line 13 skipping to change at page 59, line 13
information. information.
A container node does not have a value, but it has a list of child A container node does not have a value, but it has a list of child
nodes in the data tree. The child nodes are defined in the nodes in the data tree. The child nodes are defined in the
container's substatements. container's substatements.
7.5.1. Containers with Presence 7.5.1. Containers with Presence
YANG supports two styles of containers, those that exist only for YANG supports two styles of containers, those that exist only for
organizing the hierarchy of data nodes, and those whose presence in organizing the hierarchy of data nodes, and those whose presence in
the configuration has an explicit meaning. the data tree has an explicit meaning.
In the first style, the container has no meaning of its own, existing In the first style, the container has no meaning of its own, existing
only to contain child nodes. This is the default style. only to contain child nodes. This is the default style.
For example, the set of scrambling options for Synchronous Optical For example, the set of scrambling options for Synchronous Optical
Network (SONET) interfaces may be placed inside a "scrambling" Network (SONET) interfaces may be placed inside a "scrambling"
container to enhance the organization of the configuration hierarchy, container to enhance the organization of the configuration hierarchy,
and to keep these nodes together. The "scrambling" node itself has and to keep these nodes together. The "scrambling" node itself has
no meaning, so removing the node when it becomes empty relieves the no meaning, so removing the node when it becomes empty relieves the
user from performing this task. user from performing this task.
In the second style, the presence of the container itself is In the second style, the presence of the container itself carries
configuration data, representing a single bit of configuration data. some meaning, representing a single bit of data.
The container acts as both a configuration knob and a means of
organizing related configuration. These containers are explicitly In configuration data, the container acts as both a configuration
created and deleted. knob and a means of organizing related configuration. These
containers are explicitly created and deleted.
YANG calls this style a "presence container" and it is indicated YANG calls this style a "presence container" and it is indicated
using the "presence" statement, which takes as its argument a text using the "presence" statement, which takes as its argument a text
string indicating what the presence of the node means. string indicating what the presence of the node means.
For example, an "ssh" container may turn on the ability to log into For example, an "ssh" container may turn on the ability to log into
the device using ssh, but can also contain any ssh-related the device using ssh, but can also contain any ssh-related
configuration knobs, such as connection rates or retry limits. configuration knobs, such as connection rates or retry limits.
The "presence" statement (see Section 7.5.5) is used to give The "presence" statement (see Section 7.5.5) is used to give
skipping to change at page 61, line 5 skipping to change at page 62, line 5
passed as <error-message> in the <rpc-error>. passed as <error-message> in the <rpc-error>.
7.5.4.2. The error-app-tag Statement 7.5.4.2. The error-app-tag Statement
The "error-app-tag" statement, which is optional, takes a string as The "error-app-tag" statement, which is optional, takes a string as
an argument. If the constraint evaluates to false, the string is an argument. If the constraint evaluates to false, the string is
passed as <error-app-tag> in the <rpc-error>. passed as <error-app-tag> in the <rpc-error>.
7.5.4.3. Usage Example of must and error-message 7.5.4.3. Usage Example of must and error-message
container interface { container interface {
leaf ifType { leaf ifType {
type enumeration { type enumeration {
enum ethernet; enum ethernet;
enum atm; enum atm;
}
}
leaf ifMTU {
type uint32;
}
must "ifType != 'ethernet' or " +
"(ifType = 'ethernet' and ifMTU = 1500)" {
error-message "An ethernet MTU must be 1500";
}
must "ifType != 'atm' or " +
"(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" {
error-message "An atm MTU must be 64 .. 17966";
} }
}
leaf ifMTU {
type uint32;
}
must "ifType != 'ethernet' or " +
"(ifType = 'ethernet' and ifMTU = 1500)" {
error-message "An ethernet MTU must be 1500";
}
must "ifType != 'atm' or " +
"(ifType = 'atm' and ifMTU <= 17966 and ifMTU >= 64)" {
error-message "An atm MTU must be 64 .. 17966";
}
} }
7.5.5. The presence Statement 7.5.5. The presence Statement
The "presence" statement assigns a meaning to the presence of a The "presence" statement assigns a meaning to the presence of a
container in the data tree. It takes as an argument a string that container in the data tree. It takes as an argument a string that
contains a textual description of what the node's presence means. contains a textual description of what the node's presence means.
If a container has the "presence" statement, the container's If a container has the "presence" statement, the container's
existence in the data tree carries some meaning. Otherwise, the existence in the data tree carries some meaning. Otherwise, the
skipping to change at page 61, line 43 skipping to change at page 62, line 43
no meaning by itself. no meaning by itself.
See Section 7.5.1 for additional information. See Section 7.5.1 for additional information.
7.5.6. The container's Child Node Statements 7.5.6. The container's Child Node Statements
Within a container, the "container", "leaf", "list", "leaf-list", Within a container, the "container", "leaf", "list", "leaf-list",
"uses", "choice", "anydata", and "anyxml" statements can be used to "uses", "choice", "anydata", and "anyxml" statements can be used to
define child nodes to the container. define child nodes to the container.
7.5.7. XML Mapping Rules 7.5.7. XML Encoding Rules
A container node is encoded as an XML element. The element's local A container node is encoded as an XML element. The element's local
name is the container's identifier, and its namespace is the module's name is the container's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). XML namespace (see Section 7.1.3).
The container's child nodes are encoded as subelements to the The container's child nodes are encoded as subelements to the
container element. If the container defines RPC input or output container element. If the container defines RPC or action input or
parameters, these subelements are encoded in the same order as they output parameters, these subelements are encoded in the same order as
are defined within the "container" statement. Otherwise, the they are defined within the "container" statement. Otherwise, the
subelements are encoded in any order. subelements are encoded in any order.
A NETCONF server that replies to a <get> or <get-config> request MAY A NETCONF server that replies to a <get> or <get-config> request MAY
choose not to send a container element if the container node does not choose not to send a container element if the container node does not
have the "presence" statement and no child nodes exist. Thus, a have the "presence" statement and no child nodes exist. Thus, a
client that receives an <rpc-reply> for a <get> or <get-config> client that receives an <rpc-reply> for a <get> or <get-config>
request, must be prepared to handle the case that a container node request, must be prepared to handle the case that a container node
without a "presence" statement is not present in the XML. without a "presence" statement is not present in the XML.
7.5.8. NETCONF <edit-config> Operations 7.5.8. NETCONF <edit-config> Operations
skipping to change at page 62, line 41 skipping to change at page 64, line 6
returned. returned.
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 node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.5.9. Usage Example 7.5.9. Usage Example
Given the following container definition: Given the following container definition:
container system { container system {
description "Contains various system parameters"; description
container services { "Contains various system parameters";
description "Configure externally available services"; container services {
container "ssh" { description
presence "Enables SSH"; "Configure externally available services";
description "SSH service specific configuration"; container "ssh" {
// more leafs, containers and stuff here... presence "Enables SSH";
} description
"SSH service specific configuration";
// more leafs, containers and stuff here...
} }
}
} }
A corresponding XML instance example: A corresponding XML instance example:
<system> <system>
<services> <services>
<ssh/> <ssh/>
</services> </services>
</system> </system>
skipping to change at page 65, line 44 skipping to change at page 67, line 13
exist. exist.
o Otherwise, if this ancestor is a case node, the leaf MUST exist if o Otherwise, if this ancestor is a case node, the leaf MUST exist if
any node from the case exists in the data tree. any node from the case exists in the data tree.
o Otherwise, the leaf MUST exist if the ancestor node exists in the o Otherwise, the leaf MUST exist if the ancestor node exists in the
data tree. data tree.
This constraint is enforced according to the rules in Section 8. This constraint is enforced according to the rules in Section 8.
7.6.6. XML Mapping Rules 7.6.6. XML Encoding Rules
A leaf node is encoded as an XML element. The element's local name A leaf node is encoded as an XML element. The element's local name
is the leaf's identifier, and its namespace is the module's XML is the leaf's identifier, and its namespace is the module's XML
namespace (see Section 7.1.3). namespace (see Section 7.1.3).
The value of the leaf node is encoded to XML according to the type, The value of the leaf node is encoded to XML according to the type,
and sent as character data in the element. and 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
skipping to change at page 66, line 36 skipping to change at page 68, line 6
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 node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.6.8. Usage Example 7.6.8. Usage Example
Given the following "leaf" statement, placed in the previously Given the following "leaf" statement, placed in the previously
defined "ssh" container (see Section 7.5.9): defined "ssh" container (see Section 7.5.9):
leaf port { leaf port {
type inet:port-number; type inet:port-number;
default 22; default 22;
description "The port to which the SSH server listens" description
"The port to which the SSH server listens"
} }
A corresponding XML instance example: A corresponding XML instance example:
<port>2022</port> <port>2022</port>
To set the value of a leaf with an <edit-config>: To set the value of a leaf with an <edit-config>:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
skipping to change at page 68, line 8 skipping to change at page 69, line 25
For example, a list of valid users would typically be sorted For example, a list of valid users would typically be sorted
alphabetically, since the order in which the users appeared in the alphabetically, since the order in which the users appeared in the
configuration would not impact the creation of those users' accounts. configuration would not impact the creation of those users' accounts.
In the other style of lists, the order of list entries matters for In the other style of lists, the order of list entries matters for
the implementation of the list's configuration and the user is the implementation of the list's configuration and the user is
responsible for ordering the entries, while the device maintains that responsible for ordering the entries, while the device maintains that
order. YANG calls this style of list "user ordered" and they are order. YANG calls this style of list "user ordered" and they are
indicated with the statement "ordered-by user". indicated with the statement "ordered-by user".
For example, the order in which firewall filters entries are applied For example, the order in which packet filters entries are applied to
to incoming traffic may affect how that traffic is filtered. The incoming traffic may affect how that traffic is filtered. The user
user would need to decide if the filter entry that discards all TCP would need to decide if the filter entry that discards all TCP
traffic should be applied before or after the filter entry that traffic should be applied before or after the filter entry that
allows all traffic from trusted interfaces. The choice of order allows all traffic from trusted interfaces. The choice of order
would be crucial. would be crucial.
YANG provides a rich set of facilities within NETCONF's <edit-config> YANG provides a rich set of facilities within NETCONF's <edit-config>
operation that allows the order of list entries in user-ordered lists operation that allows the order of list entries in user-ordered lists
to be controlled. List entries may be inserted or rearranged, to be controlled. List entries may be inserted or rearranged,
positioned as the first or last entry in the list, or positioned positioned as the first or last entry in the list, or positioned
before or after another specific entry. before or after another specific entry.
skipping to change at page 71, line 11 skipping to change at page 72, line 22
like "diff". like "diff".
This is the default order. This is the default order.
7.7.7.2. ordered-by user 7.7.7.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.9 for details. in the <edit-config> request. See Section 7.7.9 for details.
7.7.8. XML Mapping Rules 7.7.8. XML Encoding Rules
A leaf-list node is encoded as a series of XML elements. Each A leaf-list node is encoded as a series of XML elements. Each
element's local name is the leaf-list's identifier, and its namespace element's local name is the leaf-list's identifier, and its namespace
is the module's XML namespace (see Section 7.1.3). is the module's XML namespace (see Section 7.1.3).
The value of each leaf-list entry is encoded to XML according to the The value of each leaf-list entry is encoded to XML according to the
type, and sent as character data in the element. type, and sent as character data in the element.
The XML elements representing leaf-list entries MUST appear in the The XML elements representing leaf-list entries MUST appear in the
order specified by the user if the leaf-list is "ordered-by user"; order specified by the user if the leaf-list is "ordered-by user";
otherwise, the order is implementation-dependent. The XML elements otherwise, the order is implementation-dependent. The XML elements
representing leaf-list entries MAY be interleaved with other sibling representing leaf-list entries MAY be interleaved with other sibling
elements, unless the leaf-list defines RPC input or output elements, unless the leaf-list defines RPC or action input or output
parameters. parameters.
See Section 7.7.10 for an example. See Section 7.7.10 for an example.
7.7.9. NETCONF <edit-config> Operations 7.7.9. NETCONF <edit-config> Operations
Leaf-list entries can be created and deleted, but not modified, Leaf-list entries can be created and deleted, but not modified,
through <edit-config>, by using the "operation" attribute in the through <edit-config>, by using the "operation" attribute in the
leaf-list entry's XML element. leaf-list entry's XML element.
skipping to change at page 72, line 26 skipping to change at page 73, line 38
does not exist. If the leaf-list entry already exists, a does not exist. If the leaf-list entry already exists, a
"data-exists" error is returned. "data-exists" error is returned.
If the operation is "delete", the entry is deleted from the leaf- If the operation is "delete", the entry is deleted from the leaf-
list if it exists. If the leaf-list entry does not exist, a list if it exists. If the leaf-list entry does not exist, a
"data-missing" error is returned. "data-missing" error is returned.
7.7.10. Usage Example 7.7.10. 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 instance example: A corresponding XML instance example:
<allow-user>alice</allow-user> <allow-user>alice</allow-user>
<allow-user>bob</allow-user> <allow-user>bob</allow-user>
To create a new element in this list, using the default <edit-config> To create a new element in this list, using the default <edit-config>
operation "merge": operation "merge":
skipping to change at page 73, line 27 skipping to change at page 74, line 27
</ssh> </ssh>
</services> </services>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
Given the following ordered-by user leaf-list: Given the following ordered-by user leaf-list:
leaf-list cipher { leaf-list cipher {
type string; type string;
ordered-by user; ordered-by user;
description "A list of ciphers"; description
"A list of ciphers";
} }
The following would be used to insert a new cipher "blowfish-cbc" The following would be used to insert a new cipher "blowfish-cbc"
after "3des-cbc": after "3des-cbc":
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1"> xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config> <edit-config>
skipping to change at page 76, line 9 skipping to change at page 77, line 9
leafs or their types are ignored. It also implies that any mandatory leafs or their types are ignored. It also implies that any mandatory
statement in the key leafs are ignored. statement in the key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived A leaf that is part of the key can be of any built-in or derived
type. type.
All key leafs in a list MUST have the same value for their "config" All key leafs in a list MUST have the same value for their "config"
as the list itself. as the list itself.
The key string syntax is formally defined by the rule "key-arg" in The key string syntax is formally defined by the rule "key-arg" in
Section 13. Section 14.
7.8.3. The list's unique Statement 7.8.3. The list's unique Statement
The "unique" statement is used to put constraints on valid list The "unique" statement is used to put constraints on valid list
entries. It takes as an argument a string that contains a space- entries. It takes as an argument a string that contains a space-
separated list of schema node identifiers, which MUST be given in the separated list of schema node identifiers, which MUST be given in the
descendant form (see the rule "descendant-schema-nodeid" in descendant form (see the rule "descendant-schema-nodeid" in
Section 13). Each such schema node identifier MUST refer to a leaf. Section 14). Each such schema node identifier MUST refer to a leaf.
If one of the referenced leafs represents configuration data, then If one of the referenced leafs represents configuration data, then
all of the referenced leafs MUST represent configuration data. all of the referenced leafs MUST represent configuration data.
The "unique" constraint specifies that the combined values of all the The "unique" constraint specifies that the combined values of all the
leaf instances specified in the argument string, including leafs with leaf instances specified in the argument string, including leafs with
default values, MUST be unique within all list entry instances in default values, MUST be unique within all list entry instances in
which all referenced leafs exist. The constraint is enforced which all referenced leafs exist. The constraint is enforced
according to the rules in Section 8. according to the rules in Section 8.
The unique string syntax is formally defined by the rule "unique-arg" The unique string syntax is formally defined by the rule "unique-arg"
in Section 13. in Section 14.
7.8.3.1. Usage Example 7.8.3.1. Usage Example
With the following list: With the following list:
list server { list server {
key "name"; key "name";
unique "ip port"; unique "ip port";
leaf name { leaf name {
type string; type string;
} }
leaf ip { leaf ip {
type inet:ip-address; type inet:ip-address;
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
} }
} }
The following configuration is not valid: The following configuration is not valid:
<server> <server>
<name>smtp</name> <name>smtp</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>25</port> <port>25</port>
</server> </server>
skipping to change at page 77, line 43 skipping to change at page 78, line 43
<name>ftp</name> <name>ftp</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
</server> </server>
7.8.4. The list's Child Node Statements 7.8.4. The list's Child Node Statements
Within a list, the "container", "leaf", "list", "leaf-list", "uses", Within a list, the "container", "leaf", "list", "leaf-list", "uses",
"choice", "anydata", and "anyxml" statements can be used to define "choice", "anydata", and "anyxml" statements can be used to define
child nodes to the list. child nodes to the list.
7.8.5. XML Mapping Rules 7.8.5. XML Encoding Rules
A list is encoded as a series of XML elements, one for each entry in A list is encoded as a series of XML elements, one for each entry in
the list. Each element's local name is the list's identifier, and the list. Each element's local name is the list's identifier, and
its namespace is the module's XML namespace (see Section 7.1.3). its namespace is the module's XML namespace (see Section 7.1.3).
The list's key nodes are encoded as subelements to the list's The list's key nodes are encoded as subelements to the list's
identifier element, in the same order as they are defined within the identifier element, in the same order as they are defined within the
"key" statement. "key" statement.
The rest of the list's child nodes are encoded as subelements to the The rest of the list's child nodes are encoded as subelements to the
list element, after the keys. If the list defines RPC input or list element, after the keys. If the list defines RPC or action
output parameters, the subelements are encoded in the same order as input or output parameters, the subelements are encoded in the same
they are defined within the "list" statement. Otherwise, the order as they are defined within the "list" statement. Otherwise,
subelements are encoded in any order. the subelements are encoded in any order.
The XML elements representing list entries MUST appear in the order The XML elements representing list entries MUST appear in the order
specified by the user if the list is "ordered-by user", otherwise the specified by the user if the list is "ordered-by user", otherwise the
order is implementation-dependent. The XML elements representing order is implementation-dependent. The XML elements representing
list entries MAY be interleaved with other sibling elements, unless list entries MAY be interleaved with other sibling elements, unless
the list defines RPC input or output parameters. the list defines RPC or action input or output parameters.
7.8.6. NETCONF <edit-config> Operations 7.8.6. NETCONF <edit-config> Operations
List entries can be created, deleted, replaced, and modified through List entries can be created, deleted, replaced, and modified through
<edit-config>, by using the "operation" attribute in the list's XML <edit-config>, by using the "operation" attribute in the list's XML
element. In each case, the values of all keys are used to uniquely element. In each case, the values of all keys are used to uniquely
identify a list entry. If all keys are not specified for a list identify a list entry. If all keys are not specified for a list
entry, a "missing-element" error is returned. entry, a "missing-element" error is returned.
In an "ordered-by user" list, the attributes "insert" and "key" in In an "ordered-by user" list, the attributes "insert" and "key" in
skipping to change at page 79, line 22 skipping to change at page 80, line 22
If the operation is "delete", the entry is deleted from the list If the operation is "delete", the entry is deleted from the list
if it exists. If the list entry does not exist, a "data-missing" if it exists. If the list entry does not exist, a "data-missing"
error is returned. error is returned.
7.8.7. Usage Example 7.8.7. Usage Example
Given the following list: Given the following list:
list user { list user {
key "name"; key "name";
config true; config true;
description "This is a list of users in the system."; description
"This is a list of users in the system.";
leaf name { leaf name {
type string; type string;
} }
leaf type { leaf type {
type string; type string;
} }
leaf full-name { leaf full-name {
type string; type string;
} }
} }
A corresponding XML instance example: A corresponding XML instance example:
<user> <user>
<name>fred</name> <name>fred</name>
<type>admin</type> <type>admin</type>
<full-name>Fred Flintstone</full-name> <full-name>Fred Flintstone</full-name>
</user> </user>
skipping to change at page 81, line 6 skipping to change at page 82, line 6
<type>superuser</type> <type>superuser</type>
</user> </user>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
Given the following ordered-by user list: Given the following ordered-by user list:
list user { list user {
description "This is a list of users in the system."; description
ordered-by user; "This is a list of users in the system.";
config true; ordered-by user;
config true;
key "name"; key "first-name surname";
leaf name { leaf first-name {
type string; type string;
} }
leaf type { leaf surname {
type string; type string;
} }
leaf full-name { leaf type {
type string; type string;
} }
} }
The following would be used to insert a new user "barney" after the The following would be used to insert a new user "barney rubble"
user "fred": after the user "fred flintstone":
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1"> xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<system xmlns="http://example.com/schema/config" <system xmlns="http://example.com/schema/config"
xmlns:ex="http://example.com/schema/config"> xmlns:ex="http://example.com/schema/config">
<user nc:operation="create" <user nc:operation="create"
yang:insert="after" yang:insert="after"
yang:key="[ex:name='fred']"> yang:key="[ex:first-name='fred']
<name>barney</name> [ex:surname='flintstone']">
<first-name>barney</first-name>
<surname>rubble</surname>
<type>admin</type> <type>admin</type>
<full-name>Barney Rubble</full-name>
</user> </user>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
The following would be used to move the user "barney" before the user The following would be used to move the user "barney rubble" before
"fred": the user "fred flintstone":
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:yang="urn:ietf:params:xml:ns:yang:1"> xmlns:yang="urn:ietf:params:xml:ns:yang:1">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
<config> <config>
<system xmlns="http://example.com/schema/config" <system xmlns="http://example.com/schema/config"
xmlns:ex="http://example.com/schema/config"> xmlns:ex="http://example.com/schema/config">
<user nc:operation="merge" <user nc:operation="merge"
yang:insert="before" yang:insert="before"
yang:key="[ex:name='fred']"> yang:key="[ex:name='fred']
<name>barney</name> [ex:surname='flintstone']">
<first-name>barney</first-name>
<surname>rubble</surname>
</user> </user>
</system> </system>
</config> </config>
</edit-config> </edit-config>
</rpc> </rpc>
7.9. The choice Statement 7.9. The choice Statement
The "choice" statement defines a set of alternatives, only one of The "choice" statement defines a set of alternatives, only one of
which may 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
nodes from at most one of the choice's branches exist at the same nodes from at most one of the choice's branches exist at the same
time. time.
See Section 8.3.2 for additional information. See Section 8.2.2 for additional information.
7.9.1. The choice's Substatements 7.9.1. The choice's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| case | 7.9.2 | 0..n | | case | 7.9.2 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
skipping to change at page 83, line 41 skipping to change at page 84, line 41
The identifier is used to identify the case node in the schema tree. The identifier is used to identify the case node in the schema tree.
A case node does not exist in the data tree. A case node does not exist in the data tree.
Within a "case" statement, the "anydata", "anyxml", "choice", Within a "case" statement, the "anydata", "anyxml", "choice",
"container", "leaf", "list", "leaf-list", and "uses" statements can "container", "leaf", "list", "leaf-list", and "uses" statements can
be used to define child nodes to the case node. The identifiers of be used to define child nodes to the case node. The identifiers of
all these child nodes MUST be unique within all cases in a choice. all these child nodes MUST be unique within all cases in a choice.
For example, the following is illegal: For example, the 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 { ...}
} }
} }
As a shorthand, the "case" statement can be omitted if the branch As a shorthand, the "case" statement can be omitted if the branch
contains a single "anydata", "anyxml", "choice", "container", "leaf", contains a single "anydata", "anyxml", "choice", "container", "leaf",
"list", or "leaf-list" statement. In this case, the identifier of "list", or "leaf-list" statement. In this case, the case node still
the case node is the same as the identifier in the branch statement. exists in the schema tree, and its identifier is the same as the
identifier in the branch statement. Schema node identifiers
(Section 6.5) MUST always explicitly include case node identifiers.
The following example: The following example:
choice interface-type { choice interface-type {
container ethernet { ... } container ethernet { ... }
} }
is equivalent to: is equivalent to:
choice interface-type { choice interface-type {
case ethernet { case ethernet {
container ethernet { ... } container ethernet { ... }
} }
} }
The case identifier MUST be unique within a choice. The case identifier MUST be unique within a choice.
7.9.2.1. The case's Substatements 7.9.2.1. The case's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
skipping to change at page 85, line 25 skipping to change at page 86, line 25
case. If none of the nodes under a case are present and the case is case. If none of the nodes under a case are present and the case is
not the default case, the default values of the cases' child nodes not the default case, the default values of the cases' child nodes
are ignored. are ignored.
In this example, the choice defaults to "interval", and the default In this example, the choice defaults to "interval", and the default
value will be used if none of "daily", "time-of-day", or "manual" are value will be used if none of "daily", "time-of-day", or "manual" are
present. If "daily" is present, the default value for "time-of-day" present. If "daily" is present, the default value for "time-of-day"
will be used. will be used.
container transfer { container transfer {
choice how { choice how {
default interval; default interval;
case interval { case interval {
leaf interval { leaf interval {
type uint16; type uint16;
default 30; default 30;
units minutes; units minutes;
} }
} }
case daily { case daily {
leaf daily { leaf daily {
type empty; type empty;
} }
leaf time-of-day { leaf time-of-day {
type string; type string;
units 24-hour-clock; units 24-hour-clock;
default 1am; default 1am;
} }
}
case manual {
leaf manual {
type empty;
}
}
} }
case manual {
leaf manual {
type empty;
}
}
}
} }
7.9.4. The choice's mandatory Statement 7.9.4. The choice's mandatory Statement
The "mandatory" statement, which is optional, takes as an argument The "mandatory" statement, which is optional, takes as an argument
the string "true" or "false", and puts a constraint on valid data. the string "true" or "false", and puts a constraint on valid data.
If "mandatory" is "true", at least one node from exactly one of the If "mandatory" is "true", at least one node from exactly one of the
choice's case branches MUST exist. choice's case branches MUST exist.
If not specified, the default is "false". If not specified, the default is "false".
skipping to change at page 86, line 26 skipping to change at page 87, line 26
container (see Section 7.5.1): container (see Section 7.5.1):
o If this ancestor is a case node, the constraint is enforced if any o If this ancestor is a case node, the constraint is enforced if any
other node from the case exists. other node from the case exists.
o Otherwise, it is enforced if the ancestor node exists. o Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in The constraint is further enforced according to the rules in
Section 8. Section 8.
7.9.5. XML Mapping Rules 7.9.5. XML Encoding Rules
The choice and case nodes are not visible in XML. The choice and case nodes are not visible in XML.
The child nodes of the selected "case" statement MUST be encoded in The child nodes of the selected "case" statement MUST be encoded in
the same order as they are defined in the "case" statement if they the same order as they are defined in the "case" statement if they
are part of an RPC input or output parameter definition. Otherwise, are part of an RPC or action input or output parameter definition.
the subelements are encoded in any order. Otherwise, the subelements are encoded in any order.
7.9.6. NETCONF <edit-config> Operations 7.9.6. NETCONF <edit-config> Operations
Since only one of the choice's cases can be valid at any time, the Since only one of the choice's cases can be valid at any time, the
creation of a node from one case implicitly deletes all nodes from creation of a node from one case implicitly deletes all nodes from
all other cases. If an <edit-config> operation creates a node from a all other cases. If an <edit-config> operation creates a node from a
case, the NETCONF server will delete any existing nodes that are case, the NETCONF server will delete any existing nodes that are
defined in other cases inside the choice. defined in other cases inside the choice.
7.9.7. Usage Example 7.9.7. Usage Example
Given the following choice: Given the following choice:
container protocol { container protocol {
choice name { choice name {
case a { case a {
leaf udp { leaf udp {
type empty; type empty;
} }
} }
case b { case b {
leaf tcp { leaf tcp {
type empty; type empty;
} }
}
} }
}
} }
A corresponding XML instance example: A corresponding XML instance example:
<protocol> <protocol>
<tcp/> <tcp/>
</protocol> </protocol>
To change the protocol from tcp to udp: To change the protocol from tcp to udp:
skipping to change at page 88, line 11 skipping to change at page 89, line 11
The "anydata" statement is used to represent an unknown set of nodes The "anydata" statement is used to represent an unknown set of nodes
that can be modelled with YANG. An example of where this can be that can be modelled with YANG. An example of where this can be
useful is a list of received notifications, where the exact useful is a list of received notifications, where the exact
notifications are not known as design time. notifications are not known as design time.
An anydata node cannot be augmented (see Section 7.17). An anydata node cannot be augmented (see Section 7.17).
An anydata node exists in zero or one instances in the data tree. An anydata node exists in zero or one instances in the data tree.
An implementation may or may not know the data model used to model a
specific instance of an anydata node.
Since the use of anydata limits the manipulation of the content, it Since the use of anydata limits the manipulation of the content, it
is RECOMMENDED that the "anydata" statement not be used to define is RECOMMENDED that the "anydata" statement not be used to define
configuration data. configuration data.
7.10.1. The anydata's Substatements 7.10.1. The anydata's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| mandatory | 7.6.5 | 0..1 | | mandatory | 7.6.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.10.2. XML Mapping Rules 7.10.2. XML Encoding Rules
An anydata node is encoded as an XML element. The element's local An anydata node is encoded as an XML element. The element's local
name is the anydata's identifier, and its namespace is the module's name is the anydata's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). The value of the anydata node is XML namespace (see Section 7.1.3). The value of the anydata node is
a set of nodes, which are encoded as XML subelements to the anydata a set of nodes, which are encoded as XML subelements to the anydata
element. element.
7.10.3. NETCONF <edit-config> Operations 7.10.3. NETCONF <edit-config> Operations
An anydata node is treated as an opaque chunk of data. This data can An anydata node is treated as an opaque chunk of data. This data can
skipping to change at page 89, line 18 skipping to change at page 90, line 22
"data-exists" error is returned. "data-exists" error is returned.
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 node does not exist, a "data-missing" error is returned. If the node does not exist, a "data-missing" error is returned.
7.10.4. Usage Example 7.10.4. Usage Example
Given the following "anydata" statement: Given the following "anydata" statement:
list logged-notification { list logged-notification {
key time; key time;
leaf time { leaf time {
type yang:date-and-time; type yang:date-and-time;
} }
anydata data; anydata data;
} }
The following is a valid encoding of such a list instance: The following is a valid encoding of such a list instance:
<logged-notification> <logged-notification>
<time>2014-07-29T13:43:12Z</time> <time>2014-07-29T13:43:12Z</time>
<data> <data>
<notification <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2014-07-29T13:43:01Z</eventTime> <eventTime>2014-07-29T13:43:01Z</eventTime>
skipping to change at page 90, line 35 skipping to change at page 91, line 40
| config | 7.21.1 | 0..1 | | config | 7.21.1 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| mandatory | 7.6.5 | 0..1 | | mandatory | 7.6.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.11.2. XML Mapping Rules 7.11.2. XML Encoding Rules
An anyxml node is encoded as an XML element. The element's local An anyxml node is encoded as an XML element. The element's local
name is the anyxml's identifier, and its namespace is the module's name is the anyxml's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). The value of the anyxml node is XML namespace (see Section 7.1.3). The value of the anyxml node is
encoded as XML content of this element. encoded as XML content of this element.
Note that any XML prefixes used in the encoding are local to each Note that any XML prefixes used in the encoding are local to each
instance encoding. This means that the same XML may be encoded instance encoding. This means that the same XML may be encoded
differently by different implementations. differently by different implementations.
skipping to change at page 92, line 19 skipping to change at page 93, line 28
If the grouping is defined at the top level of a YANG module or If the grouping is defined at the top level of a YANG module or
submodule, the grouping's identifier MUST be unique within the submodule, the grouping's identifier MUST be unique within the
module. module.
A grouping is more than just a mechanism for textual substitution, A grouping is more than just a mechanism for textual substitution,
but defines a collection of nodes. Identifiers appearing inside the but defines a collection of nodes. Identifiers appearing inside the
grouping are resolved relative to the scope in which the grouping is grouping are resolved relative to the scope in which the grouping is
defined, not where it is used. Prefix mappings, type names, grouping defined, not where it is used. Prefix mappings, type names, grouping
names, and extension usage are evaluated in the hierarchy where the names, and extension usage are evaluated in the hierarchy where the
"grouping" statement appears. For extensions, this means that "grouping" statement appears. For extensions, this means that
extensions are applied to the grouping node, not the uses node. extensions defined as direct children to a "grouping" statement are
applied to the grouping itself.
7.12.1. The grouping's Substatements 7.12.1. The grouping's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| action | 7.15 | 0..n | | action | 7.15 | 0..n |
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
| anyxml | 7.11 | 0..n | | anyxml | 7.11 | 0..n |
| choice | 7.9 | 0..n | | choice | 7.9 | 0..n |
skipping to change at page 93, line 4 skipping to change at page 94, line 6
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| notification | 7.16 | 0..n | | notification | 7.16 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.12.2. Usage Example 7.12.2. Usage Example
import ietf-inet-types { import ietf-inet-types {
prefix "inet"; prefix "inet";
} }
grouping endpoint { grouping endpoint {
description "A reusable endpoint group."; description "A reusable endpoint group.";
leaf ip { leaf ip {
type inet:ip-address; type inet:ip-address;
} }
leaf port { leaf port {
type inet:port-number; type inet:port-number;
} }
} }
7.13. The uses Statement 7.13. The uses Statement
The "uses" statement is used to reference a "grouping" definition. The "uses" statement is used to reference a "grouping" definition.
It takes one argument, which is the name of the grouping. It takes one argument, which is the name of the grouping.
The effect of a "uses" reference to a grouping is that the nodes The effect of a "uses" reference to a grouping is that the nodes
defined by the grouping are copied into the current schema tree, and defined by the grouping are copied into the current schema tree, and
then updated according to the "refine" and "augment" statements. then updated according to the "refine" and "augment" statements.
skipping to change at page 94, line 15 skipping to change at page 95, line 22
exactly as it was defined in the grouping. exactly as it was defined in the grouping.
The argument string is a descendant schema node identifier (see The argument string is a descendant schema node identifier (see
Section 6.5). Section 6.5).
The following refinements can be done: The following refinements can be done:
o A leaf or choice node may get a default value, or a new default o A leaf or choice node may get a default value, or a new default
value if it already had one. value if it already had one.
o A leaf-list node may get a set of default values, or a new set of
default values if it already had defaults; i.e., the set of
refined default values replaces the defaults already given.
o Any node may get a specialized "description" string. o Any node may get a specialized "description" string.
o Any node may get a specialized "reference" string. o Any node may get a specialized "reference" string.
o Any node may get a different "config" statement. o Any node may get a different "config" statement.
o A leaf, anydata, anyxml, or choice node may get a different o A leaf, anydata, anyxml, or choice node may get a different
"mandatory" statement. "mandatory" statement.
o A container node may get a "presence" statement. o A container node may get a "presence" statement.
o A leaf, leaf-list, list, container, anydata, or anyxml node may o A leaf, leaf-list, list, container, anydata, or anyxml node may
get additional "must" expressions. get additional "must" expressions.
o A leaf-list or list node may get a different "min-elements" or o A leaf-list or list node may get a different "min-elements" or
"max-elements" statement. "max-elements" statement.
o A leaf, leaf-list, list, container, anydata, or anyxml node may o A leaf, leaf-list, list, container, anydata, or anyxml node may
get additional "if-feature" expressions. get additional "if-feature" expressions.
7.13.3. XML Mapping Rules o Any node can get refined extensions, if the extension allows
refinement. See Section 7.19 for details.
7.13.3. XML Encoding Rules
Each node in the grouping is encoded as if it was defined inline, Each node in the grouping is encoded as if it was defined inline,
even if it is imported from another module with another XML even if it is imported from another module with another XML
namespace. namespace.
7.13.4. Usage Example 7.13.4. Usage Example
To use the "endpoint" grouping defined in Section 7.12.2 in a To use the "endpoint" grouping defined in Section 7.12.2 in a
definition of an HTTP server in some other module, we can do: definition of an HTTP server in some other module, we can do:
import acme-system { import acme-system {
prefix "acme"; prefix "acme";
} }
container http-server { container http-server {
leaf name { leaf name {
type string; type string;
} }
uses acme:endpoint; uses acme:endpoint;
} }
A corresponding XML instance example: A corresponding XML instance example:
<http-server> <http-server>
<name>extern-web</name> <name>extern-web</name>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
<port>80</port> <port>80</port>
</http-server> </http-server>
If port 80 should be the default for the HTTP server, default can be If port 80 should be the default for the HTTP server, default can be
added: added:
container http-server { container http-server {
leaf name { leaf name {
type string; type string;
} }
uses acme:endpoint { uses acme:endpoint {
refine port { refine port {
default 80; default 80;
}
} }
}
} }
If we want to define a list of servers, and each server has the ip If we want to define a list of servers, and each server has the ip
and port as keys, we can do: and port as keys, we can do:
list server { list server {
key "ip port"; key "ip port";
leaf name { leaf name {
type string; type string;
} }
uses acme:endpoint; uses acme:endpoint;
} }
The following is an error: The following is an error:
container http-server { container http-server {
uses acme:endpoint; uses acme:endpoint;
leaf ip { // illegal - same identifier "ip" used twice leaf ip { // illegal - same identifier "ip" used twice
type string; type string;
} }
} }
7.14. The rpc Statement 7.14. The rpc Statement
The "rpc" statement is used to define an RPC operation. It takes one The "rpc" statement is used to define an RPC operation. It takes one
argument, which is an identifier, followed by a block of argument, which is an identifier, followed by a block of
substatements that holds detailed rpc information. This argument is substatements that holds detailed rpc information. This argument is
the name of the RPC, and is used as the element name directly under the name of the RPC, and is used as the element name directly under
the <rpc> element, as designated by the substitution group the <rpc> element, as designated by the substitution group
"rpcOperation" in [RFC6241]. "rpcOperation" in [RFC6241].
skipping to change at page 96, line 49 skipping to change at page 98, line 13
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.2. The input Statement 7.14.2. The input Statement
The "input" statement, which is optional, is used to define input The "input" statement, which is optional, is used to define input
parameters to the operation. It does not take an argument. The parameters to the operation. It does not take an argument. The
substatements to "input" define nodes under the operation's input substatements to "input" define nodes under the operation's input
node. node.
If a leaf in the input tree has a "mandatory" statement with the If a leaf in the input tree has a "mandatory" statement with the
value "true", the leaf MUST be present in a NETCONF RPC invocation. value "true", the leaf MUST be present in an RPC invocation.
Otherwise, the server MUST return a "missing-element" error.
If a leaf in the input tree has a default value, the NETCONF server If a leaf in the input tree has a default value, the server MUST use
MUST use this value in the same cases as described in Section 7.6.1. this value in the same cases as described in Section 7.6.1. In these
In these cases, the server MUST operationally behave as if the leaf cases, the server MUST operationally behave as if the leaf was
was present in the NETCONF RPC invocation with the default value as present in the RPC invocation with the default value as its value.
its value.
If a leaf-list in the input tree has one or more default values, the If a leaf-list in the input tree has one or more default values, the
NETCONF server MUST use these values in the same cases as described server MUST use these values in the same cases as described in
in Section 7.7.2. In these cases, the server MUST operationally Section 7.7.2. In these cases, the server MUST operationally behave
behave as if the leaf-list was present in the NETCONF RPC invocation as if the leaf-list was present in the RPC invocation with the
with the default values as its values. default values as its values.
If a "config" statement is present for any node in the input tree, If a "config" statement is present for any node in the input tree,
the "config" statement is ignored. the "config" statement is ignored.
If any node has a "when" statement that would evaluate to false, then If any node has a "when" statement that would evaluate to false, then
this node MUST NOT be present in the input tree. this node MUST NOT be present in the input tree.
7.14.2.1. The input's Substatements 7.14.2.1. The input's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 97, line 49 skipping to change at page 99, line 13
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.3. The output Statement 7.14.3. The output Statement
The "output" statement, which is optional, is used to define output The "output" statement, which is optional, is used to define output
parameters to the RPC operation. It does not take an argument. The parameters to the RPC operation. It does not take an argument. The
substatements to "output" define nodes under the operation's output substatements to "output" define nodes under the operation's output
node. node.
If a leaf in the output tree has a "mandatory" statement with the If a leaf in the output tree has a "mandatory" statement with the
value "true", the leaf MUST be present in a NETCONF RPC reply. value "true", the leaf MUST be present in an RPC reply.
If a leaf in the output tree has a default value, the NETCONF client
MUST use this value in the same cases as described in Section 7.6.1.
In these cases, the client MUST operationally behave as if the leaf If a leaf in the output tree has a default value, the client MUST use
was present in the NETCONF RPC reply with the default value as its this value in the same cases as described in Section 7.6.1. In these
value. cases, the client MUST operationally behave as if the leaf was
present in the RPC reply with the default value as its value.
If a leaf-list in the output tree has one or more default values, the If a leaf-list in the output tree has one or more default values, the
NETCONF client MUST use these values in the same cases as described client MUST use these values in the same cases as described in
in Section 7.7.2. In these cases, the client MUST operationally Section 7.7.2. In these cases, the client MUST operationally behave
behave as if the leaf-list was present in the NETCONF RPC reply with as if the leaf-list was present in the RPC reply with the default
the default values as its values. values as its values.
If a "config" statement is present for any node in the output tree, If a "config" statement is present for any node in the output tree,
the "config" statement is ignored. the "config" statement is ignored.
If any node has a "when" statement that would evaluate to false, then If any node has a "when" statement that would evaluate to false, then
this node MUST NOT be present in the output tree. this node MUST NOT be present in the output tree.
7.14.3.1. The output's Substatements 7.14.3.1. The output's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
skipping to change at page 98, line 39 skipping to change at page 100, line 5
| container | 7.5 | 0..n | | container | 7.5 | 0..n |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.14.4. XML Mapping Rules 7.14.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 [RFC6241]. The element's local name is the rpc's defined in [RFC6241]. The element's local name is the rpc's
identifier, and its namespace is the module's XML namespace (see identifier, and its namespace is the module's XML namespace (see
Section 7.1.3). Section 7.1.3).
Input parameters are encoded as child XML elements to the rpc node's Input parameters are encoded as child XML elements to the rpc node's
XML element, in the same order as they are defined within the "input" XML element, in the same order as they are defined within the "input"
statement. statement.
skipping to change at page 99, line 12 skipping to change at page 100, line 27
are returned, the <rpc-reply> contains a single <ok/> element defined are returned, the <rpc-reply> contains a single <ok/> element defined
in [RFC6241]. If output parameters are returned, they are encoded as in [RFC6241]. If output parameters are returned, they are encoded as
child elements to the <rpc-reply> element defined in [RFC6241], in child elements to the <rpc-reply> element defined in [RFC6241], in
the same order as they are defined within the "output" statement. the same order as they are defined within the "output" statement.
7.14.5. Usage Example 7.14.5. Usage Example
The following example defines an RPC operation: The following example defines an RPC operation:
module rock { module rock {
yang-version 1.1; yang-version 1.1;
namespace "http://example.net/rock"; namespace "http://example.net/rock";
prefix "rock"; prefix "rock";
rpc rock-the-house { rpc rock-the-house {
input { input {
leaf zip-code { leaf zip-code {
type string; type string;
} }
}
} }
}
} }
A corresponding XML instance example of the complete rpc and rpc- A corresponding XML instance example of the complete rpc and rpc-
reply: reply:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rock-the-house xmlns="http://example.net/rock"> <rock-the-house xmlns="http://example.net/rock">
<zip-code>27606-0100</zip-code> <zip-code>27606-0100</zip-code>
</rock-the-house> </rock-the-house>
skipping to change at page 100, line 18 skipping to change at page 101, line 42
example, this means that it is an error if a grouping that contains example, this means that it is an error if a grouping that contains
an action somewhere in its node hierarchy is used in a notification an action somewhere in its node hierarchy is used in a notification
definition. definition.
Since an action cannot be defined an the top-level of a module or in Since an action cannot be defined an the top-level of a module or in
a case statement, it is an error if a grouping that contains an a case statement, it is an error if a grouping that contains an
action at the top of its node hierarchy is used at the top-level of a action at the top of its node hierarchy is used at the top-level of a
module or in a case definition. module or in a case definition.
The difference between an action and an rpc is that an action is tied The difference between an action and an rpc is that an action is tied
to a node in the data tree, whereas an rpc is not. When an action is to a node in the datastore, whereas an rpc is not. When an action is
invoked, the node in the data tree is specified along with the name invoked, the node in the datastore is specified along with the name
of the action and the input parameters. of the action and the input parameters.
7.15.1. The action's Substatements 7.15.1. The action's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| input | 7.14.2 | 0..1 | | input | 7.14.2 | 0..1 |
| output | 7.14.3 | 0..1 | | output | 7.14.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
skipping to change at page 100, line 37 skipping to change at page 102, line 17
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| grouping | 7.12 | 0..n | | grouping | 7.12 | 0..n |
| if-feature | 7.20.2 | 0..n | | if-feature | 7.20.2 | 0..n |
| input | 7.14.2 | 0..1 | | input | 7.14.2 | 0..1 |
| output | 7.14.3 | 0..1 | | output | 7.14.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.15.2. XML Mapping Rules 7.15.2. XML Encoding Rules
When an action is invoked, an element with the local name "action" in When an action is invoked, an element with the local name "action" in
the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is the namespace "urn:ietf:params:xml:ns:yang:1" (see Section 5.3.1) is
encoded as a child XML element to the <rpc> element defined in encoded as a child XML element to the <rpc> element defined in
[RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241], as designated by the substitution group "rpcOperation" in
[RFC6241]. [RFC6241].
The "action" element contains an hierarchy of nodes that identifies The "action" element contains an hierarchy of nodes that identifies
the node in the data tree. It MUST contain all containers and list the node in the datastore. It MUST contain all containers and list
nodes from the top level down to the list or container containing the nodes from the top level down to the list or container containing the
action. For lists, all key leafs MUST also be included. The last action. For lists, all key leafs MUST also be included. The last
container or list contains an XML element that carries the name of container or list contains an XML element that carries the name of
the defined action. Within this element the input parameters are the defined action. Within this element the input parameters are
encoded as child XML elements, in the same order as they are defined encoded as child XML elements, in the same order as they are defined
within the "input" statement. within the "input" statement.
Only one action can be invoked in one <rpc>. If more than one action Only one action can be invoked in one <rpc>. If more than one action
is present in the <rpc>, the server MUST reply with an "bad-element" is present in the <rpc>, the server MUST reply with an "bad-element"
error-tag in the <rpc-error>. error-tag in the <rpc-error>.
skipping to change at page 101, line 22 skipping to change at page 103, line 6
they are encoded as child elements to the <rpc-reply> element defined they are encoded as child elements to the <rpc-reply> element defined
in [RFC6241], in the same order as they are defined within the in [RFC6241], in the same order as they are defined within the
"output" statement. "output" statement.
7.15.3. Usage Example 7.15.3. Usage Example
The following example defines an action to reset one server at a The following example defines an action to reset one server at a
server farm: server farm:
module server-farm { module server-farm {
yang-version 1.1; yang-version 1.1;
namespace "http://example.net/server-farm"; namespace "http://example.net/server-farm";
prefix "sfarm"; prefix "sfarm";
import ietf-yang-types { import ietf-yang-types {
prefix "yang"; prefix "yang";
} }
list server { list server {
key name; key name;
leaf name { leaf name {
type string; type string;
}
action reset {
input {
leaf reset-at {
type yang:date-and-time;
mandatory true;
}
}
output {
leaf reset-finished-at {
type yang:date-and-time;
mandatory true;
}
}
}
} }
action reset {
input {
leaf reset-at {
type yang:date-and-time;
mandatory true;
}
}
output {
leaf reset-finished-at {
type yang:date-and-time;
mandatory true;
}
}
}
}
} }
A corresponding XML instance example of the complete rpc and rpc- A corresponding XML instance example of the complete rpc and rpc-
reply: reply:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1"> <action xmlns="urn:ietf:params:xml:ns:yang:1">
<server xmlns="http://example.net/server-farm"> <server xmlns="http://example.net/server-farm">
<name>apache-1</name> <name>apache-1</name>
skipping to change at page 102, line 24 skipping to change at page 104, line 21
<reset-at>2014-07-29T13:42:00Z</reset-at> <reset-at>2014-07-29T13:42:00Z</reset-at>
</reset> </reset>
</server> </server>
</action> </action>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<reset-finished-at xmlns="http://example.net/server-farm"> <reset-finished-at xmlns="http://example.net/server-farm">
2014-07-29T13:42:12Z 2014-07-29T13:42:12Z
</reset-at> </reset-finished-at>
</rpc-reply> </rpc-reply>
7.16. The notification Statement 7.16. The notification Statement
The "notification" statement is used to define a NETCONF The "notification" statement is used to define a notification. It
notification. It takes one argument, which is an identifier, takes one argument, which is an identifier, followed by a block of
followed by a block of substatements that holds detailed notification substatements that holds detailed notification information. The
information. The "notification" statement defines a notification "notification" statement defines a notification node in the schema
node in the schema tree. tree.
A notification can be defined at the top-level of a module, or A notification can be defined at the top-level of a module, or
connected to a specific container or list data node in the schema connected to a specific container or list data node in the schema
tree. tree.
A notification MUST NOT be defined within an rpc, action or another A notification MUST NOT be defined within an rpc, action or another
notification, i.e., a notification node MUST NOT have an rpc, action, notification, i.e., a notification node MUST NOT have an rpc, action,
or a notification node as one of its ancestors in the schema tree. or a notification node as one of its ancestors in the schema tree.
For example, this means that it is an error if a grouping that For example, this means that it is an error if a grouping that
contains an notification somewhere in its node hierarchy is used in contains an notification somewhere in its node hierarchy is used in
an rpc definition. an rpc definition.
Since a notification cannot be defined in a case statement, it is an Since a notification cannot be defined in a case statement, it is an
error if a grouping that contains a notification at the top of its error if a grouping that contains a notification at the top of its
node hierarchy is used in a case definition. node hierarchy is used in a case definition.
If a leaf in the notification tree has a "mandatory" statement with If a leaf in the notification tree has a "mandatory" statement with
the value "true", the leaf MUST be present in a NETCONF notification. the value "true", the leaf MUST be present in a notification
instance.
If a leaf in the notification tree has a default value, the NETCONF If a leaf in the notification tree has a default value, the client
client MUST use this value in the same cases as described in MUST use this value in the same cases as described in Section 7.6.1.
Section 7.6.1. In these cases, the client MUST operationally behave
as if the leaf was present in the NETCONF notification with the In these cases, the client MUST operationally behave as if the leaf
default value as its value. was present in the notification instance with the default value as
its value.
If a leaf-list in the notification tree has one or more default If a leaf-list in the notification tree has one or more default
values, the NETCONF client MUST use these values in the same cases as values, the client MUST use these values in the same cases as
described in Section 7.7.2. In these cases, the client MUST described in Section 7.7.2. In these cases, the client MUST
operationally behave as if the leaf-list was present in the NETCONF operationally behave as if the leaf-list was present in the
notification with the default values as its values. notification instance with the default values as its values.
If a "config" statement is present for any node in the notification If a "config" statement is present for any node in the notification
tree, the "config" statement is ignored. tree, the "config" statement is ignored.
7.16.1. The notification's Substatements 7.16.1. The notification's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| anydata | 7.10 | 0..n | | anydata | 7.10 | 0..n |
skipping to change at page 103, line 42 skipping to change at page 105, line 40
| leaf | 7.6 | 0..n | | leaf | 7.6 | 0..n |
| leaf-list | 7.7 | 0..n | | leaf-list | 7.7 | 0..n |
| list | 7.8 | 0..n | | list | 7.8 | 0..n |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| typedef | 7.3 | 0..n | | typedef | 7.3 | 0..n |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.16.2. XML Mapping Rules 7.16.2. XML Encoding Rules
A notification node that is defined on the top-level of a module is A notification node that is defined on the top-level of a module is
encoded as a child XML element to the <notification> element defined encoded as a child XML element to the <notification> element defined
in NETCONF Event Notifications [RFC5277]. The element's local name in NETCONF Event Notifications [RFC5277]. The element's local name
is the notification's identifier, and its namespace is the module's is the notification's identifier, and its namespace is the module's
XML namespace (see Section 7.1.3). XML namespace (see Section 7.1.3).
When a notification node is defined as a child to a data node, the When a notification node is defined as a child to a data node, the
<notification> element defined in NETCONF Event Notifications <notification> element defined in NETCONF Event Notifications
[RFC5277] contains an hierarchy of nodes that identifies the node in [RFC5277] contains an hierarchy of nodes that identifies the node in
the data tree. It MUST contain all containers and list nodes from the datastore. It MUST contain all containers and list nodes from
the top level down to the list or container containing the the top level down to the list or container containing the
notification. For lists, all key leafs MUST also be included. The notification. For lists, all key leafs MUST also be included. The
last container or list contains an XML element that carries the name last container or list contains an XML element that carries the name
of the defined notification. of the defined notification.
The notification's child nodes are encoded as subelements to the The notification's child nodes are encoded as subelements to the
notification node's XML element, in any order. notification node's XML element, in any order.
7.16.3. Usage Example 7.16.3. Usage Example
The following example defines a notification at the top-level of a The following example defines a notification at the top-level of a
module: module:
module event { module event {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/event"; namespace "http://example.com/event";
prefix "ev"; prefix "ev";
notification event { notification event {
leaf event-class { leaf event-class {
type string; type string;
} }
leaf reporting-entity { leaf reporting-entity {
type instance-identifier; type instance-identifier;
} }
leaf severity { leaf severity {
type string; type string;
}
} }
}
} }
A corresponding XML instance example of the complete notification: A corresponding XML instance example of the complete notification:
<notification <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-07-08T00:01:00Z</eventTime> <eventTime>2008-07-08T00:01:00Z</eventTime>
<event xmlns="http://example.com/event"> <event xmlns="http://example.com/event">
<event-class>fault</event-class> <event-class>fault</event-class>
<reporting-entity> <reporting-entity>
/ex:interface[ex:name='Ethernet0'] /ex:interface[ex:name='Ethernet0']
</reporting-entity> </reporting-entity>
<severity>major</severity> <severity>major</severity>
</event> </event>
</notification> </notification>
The following example defines a notification in a data node: The following example defines a notification in a data node:
module interface-module { module interface-module {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/schema/interfaces"; namespace "http://example.com/schema/interfaces";
prefix "if"; prefix "if";
container interfaces { container interfaces {
list interface { list interface {
key "name"; key "name";
leaf name { leaf name {
type string; type string;
} }
notification interface-enabled { notification interface-enabled {
leaf by-user { leaf by-user {
type string; type string;
} }
} }
}
} }
}
} }
A corresponding XML instance example of the complete notification: A corresponding XML instance example of the complete notification:
<notification <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-07-08T00:01:00Z</eventTime> <eventTime>2008-07-08T00:01:00Z</eventTime>
<interfaces xmlns="http://example.com/schema/interfaces"> <interfaces xmlns="http://example.com/schema/interfaces">
<interface> <interface>
<name>eth1</name> <name>eth1</name>
skipping to change at page 106, line 5 skipping to change at page 108, line 5
its submodules, and to add to the nodes from a grouping in a "uses" its submodules, and to add to the nodes from a grouping in a "uses"
statement. The argument is a string that identifies a node in the statement. The argument is a string that identifies a node in the
schema tree. This node is called the augment's target node. The schema tree. This node is called the augment's target node. The
target node MUST be either a container, list, choice, case, input, target node MUST be either a container, list, choice, case, input,
output, or notification node. It is augmented with the nodes defined output, or notification node. It is augmented with the nodes defined
in the substatements that follow the "augment" statement. in the substatements that follow the "augment" statement.
The argument string is a schema node identifier (see Section 6.5). The argument string is a schema node identifier (see Section 6.5).
If the "augment" statement is on the top level in a module or If the "augment" statement is on the top level in a module or
submodule, the absolute form (defined by the rule submodule, the absolute form (defined by the rule
"absolute-schema-nodeid" in Section 13) of a schema node identifier "absolute-schema-nodeid" in Section 14) of a schema node identifier
MUST be used. If the "augment" statement is a substatement to the MUST be used. If the "augment" statement is a substatement to the
"uses" statement, the descendant form (defined by the rule "uses" statement, the descendant form (defined by the rule
"descendant-schema-nodeid" in Section 13) MUST be used. "descendant-schema-nodeid" in Section 14) MUST be used.
If the target node is a container, list, case, input, output, or If the target node is a container, list, case, input, output, or
notification node, the "container", "leaf", "list", "leaf-list", notification node, the "container", "leaf", "list", "leaf-list",
"uses", and "choice" statements can be used within the "augment" "uses", and "choice" statements can be used within the "augment"
statement. statement.
If the target node is a choice node, the "case" statement, or a case If the target node is a choice node, the "case" statement, or a case
shorthand statement (see Section 7.9.2) can be used within the shorthand statement (see Section 7.9.2) can be used within the
"augment" statement. "augment" statement.
skipping to change at page 107, line 5 skipping to change at page 109, line 5
| 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 |
| notification | 7.16 | 0..n | | notification | 7.16 | 0..n |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
| uses | 7.13 | 0..n | | uses | 7.13 | 0..n |
| when | 7.21.5 | 0..1 | | when | 7.21.5 | 0..1 |
+--------------+---------+-------------+ +--------------+---------+-------------+
7.17.2. XML Mapping Rules 7.17.2. XML Encoding Rules
All data nodes defined in the "augment" statement are defined as XML All data nodes defined in the "augment" statement are defined as XML
elements in the XML namespace of the module where the "augment" is elements in the XML namespace of the module where the "augment" is
specified. specified.
When a node is augmented, the augmenting child nodes are encoded as When a node is augmented, the augmenting child nodes are encoded as
subelements to the augmented node, in any order. subelements to the augmented node, in any order.
7.17.3. Usage Example 7.17.3. Usage Example
In namespace http://example.com/schema/interfaces, we have: In namespace http://example.com/schema/interfaces, we have:
container interfaces { container interfaces {
list ifEntry { list ifEntry {
key "ifIndex"; key "ifIndex";
leaf ifIndex { leaf ifIndex {
type uint32; type uint32;
} }
leaf ifDescr { leaf ifDescr {
type string; type string;
}
leaf ifType {
type iana:IfType;
}
leaf ifMtu {
type int32;
}
} }
leaf ifType {
type iana:IfType;
}
leaf ifMtu {
type int32;
}
}
} }
Then, in namespace http://example.com/schema/ds0, we have: Then, in namespace http://example.com/schema/ds0, we have:
import interface-module { import interface-module {
prefix "if"; prefix "if";
} }
augment "/if:interfaces/if:ifEntry" { augment "/if:interfaces/if:ifEntry" {
when "if:ifType='ds0'"; when "if:ifType='ds0'";
leaf ds0ChannelNumber { leaf ds0ChannelNumber {
type ChannelNumber; type ChannelNumber;
} }
} }
A corresponding XML instance example: A corresponding XML instance example:
<interfaces xmlns="http://example.com/schema/interfaces" <interfaces xmlns="http://example.com/schema/interfaces"
xmlns:ds0="http://example.com/schema/ds0"> xmlns:ds0="http://example.com/schema/ds0">
<ifEntry> <ifEntry>
<ifIndex>1</ifIndex> <ifIndex>1</ifIndex>
<ifDescr>Flintstone Inc Ethernet A562</ifDescr> <ifDescr>Flintstone Inc Ethernet A562</ifDescr>
<ifType>ethernetCsmacd</ifType> <ifType>ethernetCsmacd</ifType>
skipping to change at page 108, line 26 skipping to change at page 110, line 26
<ifType>ds0</ifType> <ifType>ds0</ifType>
<ds0:ds0ChannelNumber>1</ds0:ds0ChannelNumber> <ds0:ds0ChannelNumber>1</ds0:ds0ChannelNumber>
</ifEntry> </ifEntry>
</interfaces> </interfaces>
As another example, suppose we have the choice defined in As another example, suppose we have the choice defined in
Section 7.9.7. The following construct can be used to extend the Section 7.9.7. The following construct can be used to extend the
protocol definition: protocol definition:
augment /ex:system/ex:protocol/ex:name { augment /ex:system/ex:protocol/ex:name {
case c { case c {
leaf smtp { leaf smtp {
type empty; type empty;
}
} }
}
} }
A corresponding XML instance example: A corresponding XML instance example:
<ex:system> <ex:system>
<ex:protocol> <ex:protocol>
<ex:tcp/> <ex:tcp/>
</ex:protocol> </ex:protocol>
</ex:system> </ex:system>
skipping to change at page 110, line 11 skipping to change at page 112, line 11
o It is irreflexive, which means that an identity is not derived o It is irreflexive, which means that an identity is not derived
from itself. from itself.
o It is transitive, which means that if identity B is derived from A o It is transitive, which means that if identity B is derived from A
and C is derived from B, then C is also derived from A. and C is derived from B, then C is also derived from A.
7.18.3. Usage Example 7.18.3. Usage Example
module crypto-base { module crypto-base {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/crypto-base"; namespace "http://example.com/crypto-base";
prefix "crypto"; prefix "crypto";
identity 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 {
yang-version 1.1; yang-version 1.1;
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 {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
description "DES crypto algorithm"; description "DES crypto algorithm";
} }
identity des3 { identity des3 {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
description "Triple DES crypto algorithm"; description "Triple DES crypto algorithm";
} }
} }
7.19. The extension Statement 7.19. The extension Statement
The "extension" statement allows the definition of new statements The "extension" statement allows the definition of new statements
within the YANG language. This new statement definition can be within the YANG language. This new statement definition can be
imported and used by other modules. imported and used by other modules.
The statement's argument is an identifier that is the new keyword for The statement's argument is an identifier that is the new keyword for
the extension and must be followed by a block of substatements that the extension and must be followed by a block of substatements that
skipping to change at page 111, line 15 skipping to change at page 113, line 15
The extension can be used like a normal YANG statement, with the The extension can be used like a normal YANG statement, with the
statement name followed by an argument if one is defined by the statement name followed by an argument if one is defined by the
"extension" statement, and an optional block of substatements. The "extension" statement, and an optional block of substatements. The
statement's name is created by combining the prefix of the module in statement's name is created by combining the prefix of the module in
which the extension was defined, a colon (":"), and the extension's which the extension was defined, a colon (":"), and the extension's
keyword, with no interleaving whitespace. The substatements of an keyword, with no interleaving whitespace. The substatements of an
extension are defined by the "extension" statement, using some extension are defined by the "extension" statement, using some
mechanism outside the scope of this specification. Syntactically, mechanism outside the scope of this specification. Syntactically,
the substatements MUST be YANG statements, or also extensions defined the substatements MUST be YANG statements, or also extensions defined
using "extension" statements. YANG statements in extensions MUST using "extension" statements. YANG statements in extensions MUST
follow the syntactical rules in Section 13. follow the syntactical rules in Section 14.
An extension can allow refinement (see Section 7.13.2) and deviations
(Section 7.20.3.2), but the mechanism for how this is defined is
outside the scope of this specification.
7.19.1. The extension's Substatements 7.19.1. The extension's Substatements
+--------------+---------+-------------+ +--------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+---------+-------------+ +--------------+---------+-------------+
| argument | 7.19.2 | 0..1 | | argument | 7.19.2 | 0..1 |
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 | | status | 7.21.2 | 0..1 |
skipping to change at page 111, line 52 skipping to change at page 114, line 10
| substatement | section | cardinality | | substatement | section | cardinality |
+--------------+----------+-------------+ +--------------+----------+-------------+
| yin-element | 7.19.2.2 | 0..1 | | yin-element | 7.19.2.2 | 0..1 |
+--------------+----------+-------------+ +--------------+----------+-------------+
7.19.2.2. The yin-element Statement 7.19.2.2. The yin-element Statement
The "yin-element" statement, which is optional, takes as an argument The "yin-element" statement, which is optional, takes as an argument
the string "true" or "false". This statement indicates if the the string "true" or "false". This statement indicates if the
argument is mapped to an XML element in YIN or to an XML attribute argument is mapped to an XML element in YIN or to an XML attribute
(see Section 12). (see Section 13).
If no "yin-element" statement is present, it defaults to "false". If no "yin-element" statement is present, it defaults to "false".
7.19.3. Usage Example 7.19.3. Usage Example
To define an extension: To define an extension:
module my-extensions { module my-extensions {
... ...
extension c-define { extension c-define {
description description
"Takes as argument a name string. "Takes as argument a name string.
Makes the code generator use the given name in the Makes the code generator use the given name in the
#define."; #define.";
argument "name"; argument "name";
} }
} }
To use the extension: To use the extension:
module my-interfaces { module my-interfaces {
... ...
import my-extensions { import my-extensions {
prefix "myext"; prefix "myext";
skipping to change at page 113, line 20 skipping to change at page 115, line 30
the feature. the feature.
In this example, a feature called "local-storage" represents the In this example, a feature called "local-storage" represents the
ability for a 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 the device does not report that it supports this feature, the
"local-storage-limit" node is not supported. "local-storage-limit" node is not supported.
module syslog { module syslog {
... ...
feature local-storage { feature local-storage {
description description
"This feature means the device supports local "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; type uint64;
units "kilobyte"; units "kilobyte";
config false; config false;
description description
"The amount of local storage that can be "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 A feature MUST NOT reference itself, neither directly nor indirectly
through a chain of other features. through a chain of other features.
In order for a device to implement a feature that is dependent on any In order for a device to implement a feature that is dependent on any
skipping to change at page 114, line 26 skipping to change at page 116, line 38
7.20.2. The if-feature Statement 7.20.2. The if-feature Statement
The "if-feature" statement makes its parent statement conditional. The "if-feature" statement makes its parent statement conditional.
The argument is a boolean expression over feature names. In this The argument is a boolean expression over feature names. In this
expression, a feature name evaluates to "true" if and only if the expression, a feature name evaluates to "true" if and only if the
feature is implemented by the server. The parent statement is feature is implemented by the server. The parent statement is
implemented by servers where the boolean expression evaluates to implemented by servers where the boolean expression evaluates to
"true". "true".
The if-feature boolean expression syntax is formally defined by the The if-feature boolean expression syntax is formally defined by the
rule "if-feature-expr" in Section 13. When this boolean expression rule "if-feature-expr" in Section 14. When this boolean expression
is evaluated, the operator order of precedence is (highest precedence is evaluated, the operator order of precedence is (highest precedence
first): "not", "and", "or". first): "not", "and", "or".
If a prefix is present on a feature name in the boolean expression, If a prefix is present on a feature name in the boolean expression,
the prefixed name refers to a feature defined in the module that was the prefixed name refers to a feature defined in the module that was
imported with that prefix, or the local module if the prefix matches imported with that prefix, or the local module if the prefix matches
the local module's prefix. Otherwise, a feature with the matching the local module's prefix. Otherwise, a feature with the matching
name MUST be defined in the current module or an included submodule. name MUST be defined in the current module or an included submodule.
A leaf that is a list key MUST NOT have any "if-feature" statements. A leaf that is a list key MUST NOT have any "if-feature" statements.
7.20.2.1. Usage Example 7.20.2.1. Usage Example
In this example, the container "target" is implemented if any of the In this example, the container "target" is implemented if any of the
features "outbound-tls" or "outbound-ssh" is implemented by the features "outbound-tls" or "outbound-ssh" is implemented by the
server. server.
container target { container target {
if-feature "outbound-tls or outbound-ssh"; if-feature "outbound-tls or outbound-ssh";
... ...
} }
7.20.3. The deviation Statement 7.20.3. The deviation Statement
The "deviation" statement defines a hierarchy of a module that the The "deviation" statement defines a hierarchy of a module that the
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 contents of the "deviation" statement give details about the
deviation. deviation.
skipping to change at page 116, line 46 skipping to change at page 119, line 21
| max-elements | 7.7.6 | 0..1 | | max-elements | 7.7.6 | 0..1 |
| min-elements | 7.7.5 | 0..1 | | min-elements | 7.7.5 | 0..1 |
| must | 7.5.3 | 0..n | | must | 7.5.3 | 0..n |
| type | 7.4 | 0..1 | | type | 7.4 | 0..1 |
| unique | 7.8.3 | 0..n | | unique | 7.8.3 | 0..n |
| units | 7.3.3 | 0..1 | | units | 7.3.3 | 0..1 |
+--------------+-------------+-------------+ +--------------+-------------+-------------+
The deviate's Substatements The deviate's Substatements
If the target node has a property defined by an extension, this
property can be deviated if the extension allows deviations. See
Section 7.19 for details.
7.20.3.3. Usage Example 7.20.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 "daytime" service in the style of RFC 867. does not support the "daytime" service in the style of RFC 867.
deviation /base:system/base:daytime { deviation /base:system/base:daytime {
deviate not-supported; deviate not-supported;
} }
The following example sets a device-specific default value to a leaf The following example sets a device-specific default value to a leaf
that does not have a default value defined: that does not have a default value defined:
deviation /base:system/base:user/base:type { deviation /base:system/base:user/base:type {
deviate add { deviate add {
default "admin"; // new users are 'admin' by default default "admin"; // new users are 'admin' by default
} }
} }
In this example, the device limits the number of name servers to 3: In this example, the device limits the number of name servers to 3:
deviation /base:system/base:name-server { deviation /base:system/base:name-server {
deviate replace { deviate replace {
max-elements 3; max-elements 3;
} }
} }
If the original definition is: If the original definition is:
container system { container system {
must "daytime or time"; must "daytime or time";
... ...
} }
a device might remove this must constraint by doing: a device might remove this must constraint by doing:
deviation "/base:system" { deviation "/base:system" {
deviate delete { deviate delete {
must "daytime or time"; must "daytime or time";
} }
} }
7.21. Common Statements 7.21. Common Statements
This section defines substatements common to several other This section defines substatements common to several other
statements. statements.
7.21.1. The config Statement 7.21.1. The config Statement
The "config" statement takes as an argument the string "true" or The "config" statement takes as an argument the string "true" or
skipping to change at page 119, line 44 skipping to change at page 122, line 25
conditional. The node defined by the parent data definition conditional. The node defined by the parent data definition
statement is only valid when the condition specified by the "when" statement is only valid when the condition specified by the "when"
statement is satisfied. The statement's argument is an XPath statement is satisfied. The statement's argument is an XPath
expression (see Section 6.4), which is used to formally specify this expression (see Section 6.4), which is used to formally specify this
condition. If the XPath expression conceptually evaluates to "true" condition. If the XPath expression conceptually evaluates to "true"
for a particular instance, then the node defined by the parent data for a particular instance, then the node defined by the parent data
definition statement is valid; otherwise, it is not. definition statement is valid; otherwise, it is not.
A leaf that is a list key MUST NOT have a "when" statement. A leaf that is a list key MUST NOT have a "when" statement.
See Section 8.3.2 for additional information. See Section 8.2.2 for additional information.
The XPath expression is conceptually evaluated in the following The XPath expression is conceptually evaluated in the following
context, in addition to the definition in Section 6.4.1: context, in addition to the definition in Section 6.4.1:
o If the "when" statement is a child of an "augment" statement, then o If the "when" statement is a child of an "augment" statement, then
the context node is the augment's target node in the data tree, if the context node is the augment's target node in the data tree, if
the target node is a data node. Otherwise, the context node is the target node is a data node. Otherwise, the context node is
the closest ancestor node to the target node that is also a data the closest ancestor node to the target node that is also a data
node. node.
skipping to change at page 120, line 44 skipping to change at page 123, line 25
8.1. Constraints on Data 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 in different ways, depending on what type of constraints are enforced in different ways, depending on what type of
data the statement defines. data the statement defines.
o If the constraint is defined on configuration data, it MUST be o If the constraint is defined on configuration data, it MUST be
true in a valid configuration data tree. true in a valid configuration data tree.
o 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 a <get> operation without a filter. valid state data tree.
o If the constraint is defined on notification content, it MUST be o If the constraint is defined on notification content, it MUST be
true in any notification instance. true in any notification instance data tree.
o If the constraint is defined on RPC input parameters, it MUST be o If the constraint is defined on RPC or action input parameters, it
true in an invocation of the RPC operation. MUST be true in an invocation of the RPC or action operation.
o If the constraint is defined on RPC output parameters, it MUST be o If the constraint is defined on RPC or action output parameters,
true in the RPC reply. it MUST be true in the RPC or action reply.
8.2. Hierarchy of Constraints The following properties are true in all data trees:
Conditions on parent nodes affect constraints on child nodes as a o All leaf data values MUST match the type constraints for the leaf,
natural consequence of the hierarchy of nodes. "must", "mandatory", including those defined in the type's "range", "length", and
"min-elements", and "max-elements" constraints are not enforced if "pattern" properties.
the parent node has a "when" or "if-feature" property that is not
satisfied on the current device.
In this example, the "mandatory" constraint on the "longitude" leaf o All key leafs MUST be present for all list entries.
is not enforced on devices that lack the "has-gps" feature:
container location { o Nodes MUST be present for at most one case branch in all choices.
if-feature has-gps;
leaf longitude {
mandatory true;
...
}
}
8.3. Constraint Enforcement Model o There MUST be no nodes tagged with "if-feature" present if the
"if-feature" expression evaluates to "false" on the device.
o There MUST be no nodes tagged with "when" present if the "when"
condition evaluates to "false" in the data tree.
The following properties are true in a valid data tree:
o All "must" constraints MUST evaluate to "true".
o All referential integrity constraints defined via the "path"
statement MUST be satisfied.
o All "unique" constraints on lists MUST be satisfied.
o The "min-elements" and "max-elements" constraints are enforced for
lists and leaf-lists.
The running configuration datastore MUST always be valid.
8.2. NETCONF Constraint Enforcement Model
For configuration data, there are three windows when constraints MUST For configuration data, there are three windows when constraints MUST
be enforced: be enforced:
o during parsing of RPC payloads o during parsing of RPC payloads
o during processing of NETCONF operations o during processing of NETCONF operations
o during validation o during validation
Each of these scenarios is considered in the following sections. Each of these scenarios is considered in the following sections.
8.3.1. Payload Parsing 8.2.1. Payload Parsing
When content arrives in RPC payloads, it MUST be well-formed XML, When content arrives in RPC payloads, it MUST be well-formed XML,
following the hierarchy and content rules defined by the set of following the hierarchy and content rules defined by the set of
models the device implements. models the device implements.
o If a leaf data value does not match the type constraints for the o If a leaf data value does not match the type constraints for the
leaf, including those defined in the type's "range", "length", and leaf, including those defined in the type's "range", "length", and
"pattern" properties, the server MUST reply with an "pattern" properties, the server MUST reply with an
"invalid-value" error-tag in the rpc-error, and with the error- "invalid-value" error-tag in the rpc-error, and with the error-
app-tag and error-message associated with the constraint, if any app-tag and error-message associated with the constraint, if any
skipping to change at page 122, line 29 skipping to change at page 125, line 18
o For insert handling, if the value for the attributes "before" and o For insert handling, if the value for the attributes "before" and
"after" are not valid for the type of the appropriate key leafs, "after" are not valid for the type of the appropriate key leafs,
the server MUST reply with a "bad-attribute" error-tag in the rpc- the server MUST reply with a "bad-attribute" error-tag in the rpc-
error. error.
o If the attributes "before" and "after" appears in any element that o If the attributes "before" and "after" appears in any element that
is not a list whose "ordered-by" property is "user", the server is not a list whose "ordered-by" property is "user", the server
MUST reply with an "unknown-attribute" error-tag in the rpc-error. MUST reply with an "unknown-attribute" error-tag in the rpc-error.
8.3.2. NETCONF <edit-config> Processing 8.2.2. NETCONF <edit-config> Processing
After the incoming data is parsed, the NETCONF server performs the After the incoming data is parsed, the NETCONF server performs the
<edit-config> operation by applying the data to the configuration <edit-config> operation by applying the data to the configuration
datastore. During this processing, the following errors MUST be datastore. During this processing, the following errors MUST be
detected: detected:
o Delete requests for non-existent data. o Delete requests for non-existent data.
o Create requests for existent data. o Create requests for existent data.
skipping to change at page 123, line 5 skipping to change at page 125, line 42
During <edit-config> processing: During <edit-config> processing:
o If the NETCONF operation creates data nodes under a "choice", any o If the NETCONF operation creates data nodes under a "choice", any
existing nodes from other "case" branches are deleted by the existing nodes from other "case" branches are deleted by the
server. server.
o If the NETCONF operation modifies a data node such that any node's o If the NETCONF operation modifies a data node such that any node's
"when" expression becomes false, then the node with the "when" "when" expression becomes false, then the node with the "when"
expression is deleted by the server. expression is deleted by the server.
8.3.3. Validation 8.2.3. Validation
When datastore processing is complete, the final contents MUST obey When datastore processing is complete, the final contents MUST obey
all validation constraints. This validation processing is performed all validation constraints. This validation processing is performed
at differing times according to the datastore. If the datastore is at differing times according to the datastore. If the datastore is
"running" or "startup", these constraints MUST be enforced at the end "running" or "startup", these constraints MUST be enforced at the end
of the <edit-config> or <copy-config> operation. If the datastore is of the <edit-config> or <copy-config> operation. If the datastore is
"candidate", the constraint enforcement is delayed until a <commit> "candidate", the constraint enforcement is delayed until a <commit>
or <validate> operation. or <validate> operation.
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 126, line 6 skipping to change at page 128, line 38
range-restricted type, the new restriction MUST be equal or more range-restricted type, the new restriction MUST be equal or more
limiting, that is raising the lower bounds, reducing the upper limiting, that is raising the lower bounds, reducing the upper
bounds, removing explicit values or ranges, or splitting ranges into bounds, removing explicit values or ranges, or splitting ranges into
multiple ranges with intermediate gaps. Each explicit value and multiple ranges with intermediate gaps. Each explicit value and
range boundary value given in the range expression MUST match the range boundary value given in the range expression MUST match the
type being restricted, or be one of the special values "min" or type being restricted, or be one of the special values "min" or
"max". "min" and "max" mean the minimum and maximum value accepted "max". "min" and "max" mean the minimum and maximum value accepted
for the type being restricted, respectively. for the type being restricted, respectively.
The range expression syntax is formally defined by the rule The range expression syntax is formally defined by the rule
"range-arg" in Section 13. "range-arg" in Section 14.
9.2.4.1. The range's Substatements 9.2.4.1. The range's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.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";
} }
} }
typedef my-type1 { typedef my-type1 {
type my-base-int32-type { type my-base-int32-type {
// legal range restriction // legal range restriction
range "11..max"; // 11..20 range "11..max"; // 11..20
} }
} }
typedef my-type2 { typedef my-type2 {
type my-base-int32-type { type my-base-int32-type {
// illegal range restriction // illegal range restriction
range "11..100"; range "11..100";
} }
} }
9.3. The decimal64 Built-In Type 9.3. The decimal64 Built-In Type
The decimal64 type represents a subset of the real numbers, which can The decimal64 type represents a subset of the real numbers, which can
be represented by decimal numerals. The value space of decimal64 is be represented by decimal numerals. The value space of decimal64 is
the set of numbers that can be obtained by multiplying a 64-bit the set of numbers that can be obtained by multiplying a 64-bit
signed integer by a negative power of ten, i.e., expressible as "i x signed integer by a negative power of ten, i.e., expressible as "i x
10^-n" where i is an integer64 and n is an integer between 1 and 18, 10^-n" where i is an integer64 and n is an integer between 1 and 18,
inclusively. inclusively.
skipping to change at page 128, line 31 skipping to change at page 130, line 48
| 14 | -92233.72036854775808 | 92233.72036854775807 | | 14 | -92233.72036854775808 | 92233.72036854775807 |
| 15 | -9223.372036854775808 | 9223.372036854775807 | | 15 | -9223.372036854775808 | 9223.372036854775807 |
| 16 | -922.3372036854775808 | 922.3372036854775807 | | 16 | -922.3372036854775808 | 922.3372036854775807 |
| 17 | -92.23372036854775808 | 92.23372036854775807 | | 17 | -92.23372036854775808 | 92.23372036854775807 |
| 18 | -9.223372036854775808 | 9.223372036854775807 | | 18 | -9.223372036854775808 | 9.223372036854775807 |
+----------------+-----------------------+----------------------+ +----------------+-----------------------+----------------------+
9.3.5. Usage Example 9.3.5. Usage Example
typedef my-decimal { typedef my-decimal {
type decimal64 { type decimal64 {
fraction-digits 2; fraction-digits 2;
range "1 .. 3.14 | 10 | 20..max"; range "1 .. 3.14 | 10 | 20..max";
} }
} }
9.4. The string Built-In Type 9.4. The string Built-In Type
The string built-in type represents human-readable strings in YANG. The string built-in type represents human-readable strings in YANG.
Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646] Legal characters are the Unicode and ISO/IEC 10646 [ISO.10646]
characters, including tab, carriage return, and line feed but characters, including tab, carriage return, and line feed but
excluding the other C0 control characters, the surrogate blocks, and excluding the other C0 control characters, the surrogate blocks, and
the noncharacters. The string syntax is formally defined by the rule the noncharacters. The string syntax is formally defined by the rule
"yang-string" in Section 13. "yang-string" in Section 14.
9.4.1. Lexical Representation 9.4.1. Lexical Representation
A string value is lexically represented as character data in the XML A string value is lexically represented as character data in the XML
instance documents. instance documents.
9.4.2. Canonical Form 9.4.2. Canonical Form
The canonical form is the same as the lexical representation. No The canonical form is the same as the lexical representation. No
Unicode normalization is performed of string values. Unicode normalization is performed of string values.
skipping to change at page 129, line 41 skipping to change at page 132, line 6
MUST be equal or more limiting, that is, raising the lower bounds, MUST be equal or more limiting, that is, raising the lower bounds,
reducing the upper bounds, removing explicit length values or ranges, reducing the upper bounds, removing explicit length values or ranges,
or splitting ranges into multiple ranges with intermediate gaps. A or splitting ranges into multiple ranges with intermediate gaps. A
length value is a non-negative integer, or one of the special values length value is a non-negative integer, or one of the special values
"min" or "max". "min" and "max" mean the minimum and maximum length "min" or "max". "min" and "max" mean the minimum and maximum length
accepted for the type being restricted, respectively. An accepted for the type being restricted, respectively. An
implementation is not required to support a length value larger than implementation is not required to support a length value larger than
18446744073709551615. 18446744073709551615.
The length expression syntax is formally defined by the rule The length expression syntax is formally defined by the rule
"length-arg" in Section 13. "length-arg" in Section 14.
9.4.4.1. The length's Substatements 9.4.4.1. The length's Substatements
+---------------+---------+-------------+ +---------------+---------+-------------+
| substatement | section | cardinality | | substatement | section | cardinality |
+---------------+---------+-------------+ +---------------+---------+-------------+
| description | 7.21.3 | 0..1 | | description | 7.21.3 | 0..1 |
| error-app-tag | 7.5.4.2 | 0..1 | | error-app-tag | 7.5.4.2 | 0..1 |
| error-message | 7.5.4.1 | 0..1 | | error-message | 7.5.4.1 | 0..1 |
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
skipping to change at page 130, line 39 skipping to change at page 133, line 6
| reference | 7.21.4 | 0..1 | | reference | 7.21.4 | 0..1 |
+---------------+---------+-------------+ +---------------+---------+-------------+
9.4.6. The modifier Statement 9.4.6. The modifier Statement
9.4.7. Usage Example 9.4.7. Usage Example
With the following typedef: With the following typedef:
typedef my-base-str-type { typedef my-base-str-type {
type string { type string {
length "1..255"; length "1..255";
} }
} }
the following refinement is legal: the following refinement is legal:
type my-base-str-type { type my-base-str-type {
// legal length refinement // legal length refinement
length "11 | 42..max"; // 11 | 42..255 length "11 | 42..max"; // 11 | 42..255
} }
and the following refinement is illegal: and the following refinement is illegal:
type my-base-str-type { type my-base-str-type {
// illegal length refinement // illegal length refinement
length "1..999"; length "1..999";
} }
With the following type: With the following type:
type string { type string {
length "0..4"; length "0..4";
pattern "[0-9a-fA-F]*"; pattern "[0-9a-fA-F]*";
} }
the following strings match: the following strings match:
AB // legal AB // legal
9A00 // legal 9A00 // legal
and the following strings do not match: and the following strings do not match:
00ABAB // illegal, too long 00ABAB // illegal, too long
xx00 // illegal, bad characters xx00 // illegal, bad characters
With the following type: With the following type:
typedef yang-identifier { typedef yang-identifier {
type string { type string {
length "1..max"; length "1..max";
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
pattern '[xX][mM][lL].*' { pattern '[xX][mM][lL].*' {
modifier invert-match; modifier invert-match;
}
} }
}
} }
the following string match: the following string match:
enabled // legal enabled // legal
and the following strings do not match: and the following strings do not match:
10-mbit // illegal, starts with a number 10-mbit // illegal, starts with a number
xml-element // illegal, starts with illegal sequence xml-element // illegal, starts with illegal sequence
skipping to change at page 134, line 4 skipping to change at page 136, line 14
If the current highest value is equal to 2147483647, then an enum If the current highest value is equal to 2147483647, then an enum
value MUST be specified for "enum" substatements following the one value MUST be specified for "enum" substatements following the one
with the current highest value. with the current highest value.
When an existing enumeration type is restricted, the "value" When an existing enumeration type is restricted, the "value"
statement MUST either have the same value as in the base type or not statement MUST either have the same value as in the base type or not
be present, in which case the value is the same as in the base type. be present, in which case the value is the same as in the base type.
9.6.5. Usage Example 9.6.5. Usage Example
leaf myenum { leaf myenum {
type enumeration { type enumeration {
enum zero; enum zero;
enum one; enum one;
enum seven { enum seven {
value 7; value 7;
}
} }
}
} }
The lexical representation of the leaf "myenum" with value "seven" The lexical representation of the leaf "myenum" with value "seven"
is: is:
<myenum>seven</myenum> <myenum>seven</myenum>
With the following typedef: With the following typedef:
typedef my-base-enumeration-type { typedef my-base-enumeration-type {
type enumeration { type enumeration {
enum white { enum white {
value 1; value 1;
} }
enum yellow { enum yellow {
value 2; value 2;
} }
enum red { enum red {
value 3; value 3;
}
} }
}
} }
the following refinement is legal: the following refinement is legal:
type my-base-enumeration-type { type my-base-enumeration-type {
// legal enum refinement // legal enum refinement
enum yellow; enum yellow;
enum red { enum red {
value 3; value 3;
} }
} }
and the following refinement is illegal: and the following refinement is illegal:
type my-base-enumeration-type { type my-base-enumeration-type {
// illegal enum refinement // illegal enum refinement
enum yellow { enum yellow {
value 4; // illegal value change value 4; // illegal value change
} }
enum black; // illegal addition of new name enum black; // illegal addition of new name
} }
9.7. The bits Built-In Type 9.7. The bits Built-In Type
The bits built-in type represents a bit set. That is, a bits value The bits built-in type represents a bit set. That is, a bits value
is a set of flags identified by small integer position numbers is a set of flags identified by small integer position numbers
starting at 0. Each bit number has an assigned name. starting at 0. Each bit number has an assigned name.
9.7.1. Restrictions 9.7.1. Restrictions
skipping to change at page 136, line 37 skipping to change at page 139, line 6
If the current highest bit position value is equal to 4294967295, If the current highest bit position value is equal to 4294967295,
then a position value MUST be specified for "bit" substatements then a position value MUST be specified for "bit" substatements
following the one with the current highest position value. following the one with the current highest position value.
9.7.5. Usage Example 9.7.5. Usage Example
Given the following leaf: Given the following leaf:
leaf mybits { leaf mybits {
type bits { type bits {
bit disable-nagle { bit disable-nagle {
position 0; position 0;
}
bit auto-sense-speed {
position 1;
}
bit ten-mb-only {
position 2;
}
} }
default "auto-sense-speed"; bit auto-sense-speed {
position 1;
}
bit ten-mb-only {
position 2;
}
}
default "auto-sense-speed";
} }
The lexical representation of this leaf with bit values disable-nagle The lexical representation of this leaf with bit values disable-nagle
and ten-mb-only set would be: and ten-mb-only set would be:
<mybits>disable-nagle ten-mb-only</mybits> <mybits>disable-nagle ten-mb-only</mybits>
9.8. The binary Built-In Type 9.8. The binary Built-In Type
The binary built-in type represents any binary data, i.e., a sequence The binary built-in type represents any binary data, i.e., a sequence
skipping to change at page 138, line 21 skipping to change at page 140, line 36
The "path" statement, which is a substatement to the "type" The "path" statement, which is a substatement to the "type"
statement, MUST be present if the type is "leafref". It takes as an statement, MUST be present if the type is "leafref". It takes as an
argument a string that MUST refer to a leaf or leaf-list node. argument a string that MUST refer to a leaf or leaf-list node.
The syntax for a path argument is a subset of the XPath abbreviated The syntax for a path argument is a subset of the XPath abbreviated
syntax. Predicates are used only for constraining the values for the syntax. Predicates are used only for constraining the values for the
key nodes for list entries. Each predicate consists of exactly one key nodes for list entries. Each predicate consists of exactly one
equality test per key, and multiple adjacent predicates MAY be equality test per key, and multiple adjacent predicates MAY be
present if a list has multiple keys. The syntax is formally defined present if a list has multiple keys. The syntax is formally defined
by the rule "path-arg" in Section 13. by the rule "path-arg" in Section 14.
The predicates are only used when more than one key reference is The predicates are only used when more than one key reference is
needed to uniquely identify a leaf instance. This occurs if a list needed to uniquely identify a leaf instance. This occurs if a list
has multiple keys, or a reference to a leaf other than the key in a has multiple keys, or a reference to a leaf other than the key in a
list is needed. In these cases, multiple leafrefs are typically list is needed. In these cases, multiple leafrefs are typically
specified, and predicates are used to tie them together. specified, and predicates are used to tie them together.
The "path" expression evaluates to a node set consisting of zero, The "path" expression evaluates to a node set consisting of zero,
one, or more nodes. If the leaf with the leafref type represents one, or more nodes. If the leaf with the leafref type represents
configuration data, this node set MUST be non-empty. configuration data, this node set MUST be non-empty.
skipping to change at page 139, line 22 skipping to change at page 142, line 6
9.9.5. Canonical Form 9.9.5. Canonical Form
The canonical form of a leafref is the same as the canonical form of The canonical form of a leafref is the same as the canonical form of
the leaf it references. the leaf it references.
9.9.6. Usage Example 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 admin-status { leaf admin-status {
type admin-status; type admin-status;
} }
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 leafref refers to an existing interface:
leaf mgmt-interface { leaf mgmt-interface {
type leafref { type leafref {
path "../interface/name"; path "../interface/name";
} }
} }
An example of a corresponding XML snippet: 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 leafrefs 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 leafref { type leafref {
path "../../interface/name"; path "../../interface/name";
}
} }
leaf address { }
type leafref { leaf address {
path "../../interface[name = current()/../ifname]" type leafref {
+ "/address/ip"; path "../../interface[name = current()/../ifname]"
} + "/address/ip";
} }
}
} }
An example of a corresponding XML snippet: An example of a corresponding XML snippet:
<interface> <interface>
<name>eth0</name> <name>eth0</name>
<admin-status>up</admin-status> <admin-status>up</admin-status>
<address> <address>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
</address> </address>
skipping to change at page 141, line 32 skipping to change at page 144, line 6
<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 list uses a leafref for one of its keys. This is The following list uses a leafref for one of its keys. This is
similar to a foreign key in a relational database. similar to a foreign key in a relational database.
list packet-filter { list packet-filter {
key "if-name filter-id"; key "if-name filter-id";
leaf if-name { leaf if-name {
type leafref { type leafref {
path "/interface/name"; path "/interface/name";
}
}
leaf filter-id {
type uint32;
} }
... }
leaf filter-id {
type uint32;
}
...
} }
An example of a corresponding XML snippet: An example of a corresponding XML snippet:
<interface> <interface>
<name>eth0</name> <name>eth0</name>
<admin-status>up</admin-status> <admin-status>up</admin-status>
<address> <address>
<ip>192.0.2.1</ip> <ip>192.0.2.1</ip>
</address> </address>
skipping to change at page 142, line 31 skipping to change at page 145, line 6
<packet-filter> <packet-filter>
<if-name>eth0</if-name> <if-name>eth0</if-name>
<filter-id>2</filter-id> <filter-id>2</filter-id>
... ...
</packet-filter> </packet-filter>
The following notification defines two leafrefs to refer to an The following notification defines two leafrefs to refer to an
existing admin-status: existing admin-status:
notification link-failure { notification link-failure {
leaf if-name { leaf if-name {
type leafref { type leafref {
path "/interface/name"; path "/interface/name";
}
} }
leaf admin-status { }
type leafref { leaf admin-status {
path type leafref {
"/interface[name = current()/../if-name]" path "/interface[name = current()/../if-name]"
+ "/admin-status"; + "/admin-status";
}
} }
}
} }
An example of a corresponding XML notification: An example of a corresponding XML notification:
<notification <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2008-04-01T00:01:00Z</eventTime> <eventTime>2008-04-01T00:01:00Z</eventTime>
<link-failure xmlns="http://acme.example.com/system"> <link-failure xmlns="http://acme.example.com/system">
<if-name>eth0</if-name> <if-name>eth0</if-name>
<admin-status>up</admin-status> <admin-status>up</admin-status>
skipping to change at page 143, line 36 skipping to change at page 145, line 52
statement, MUST be present at least once if the type is statement, MUST be present at least once if the type is
"identityref". The argument is the name of an identity, as defined "identityref". The argument is the name of an identity, as defined
by an "identity" statement. If a prefix is present on the identity by an "identity" statement. If a prefix is present on the identity
name, it refers to an identity defined in the module that was name, it refers to an identity defined in the module that was
imported with that prefix. Otherwise, an identity with the matching imported with that prefix. Otherwise, an identity with the matching
name MUST be defined in the current module or an included submodule. name MUST be defined in the current module or an included submodule.
Valid values for an identityref are any identities derived from all Valid values for an identityref are any identities derived from all
the identityref's base identities. On a particular server, the valid the identityref's base identities. On a particular server, the valid
values are further restricted to the set of identities defined in the values are further restricted to the set of identities defined in the
modules supported by the server. modules implemented by the server.
9.10.3. Lexical Representation 9.10.3. Lexical Representation
An identityref is encoded as the referred identity's qualified name An identityref is encoded as the referred identity's qualified name
as defined in [XML-NAMES]. If the prefix is not present, the as defined in [XML-NAMES]. If the prefix is not present, the
namespace of the identityref is the default namespace in effect on namespace of the identityref is the default namespace in effect on
the element that contains the identityref value. the element that contains the identityref value.
When an identityref is given a default value using the "default" When an identityref is given a default value using the "default"
statement, the identity name in the default value MAY have a prefix. statement, the identity name in the default value MAY have a prefix.
skipping to change at page 144, line 23 skipping to change at page 147, line 6
Since the lexical form depends on the XML context in which the value Since the lexical form depends on the XML context in which the value
occurs, this type does not have a canonical form. occurs, this type does not have a canonical form.
9.10.5. Usage Example 9.10.5. Usage Example
With the identity definitions in Section 7.18.3 and the following With the identity definitions in Section 7.18.3 and the following
module: module:
module my-crypto { module my-crypto {
yang-version 1.1; yang-version 1.1;
namespace "http://example.com/my-crypto"; namespace "http://example.com/my-crypto";
prefix mc; prefix mc;
import "crypto-base" { import "crypto-base" {
prefix "crypto"; prefix "crypto";
} }
identity aes { identity aes {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
} }
leaf crypto { leaf crypto {
type identityref { type identityref {
base "crypto:crypto-alg"; base "crypto:crypto-alg";
}
} }
}
container aes-parameters { container aes-parameters {
when "../crypto = 'mc:aes'"; when "../crypto = 'mc:aes'";
... ...
} }
} }
the following is an example how the leaf "crypto" can be encoded, if the following is an example how the leaf "crypto" can be encoded, if
the value is the "des3" identity defined in the "des" module: 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
skipping to change at page 145, line 45 skipping to change at page 148, line 29
9.11.3. Canonical Form 9.11.3. Canonical Form
Not applicable. Not applicable.
9.11.4. Usage Example 9.11.4. Usage Example
With the following leaf With the following leaf
leaf enable-qos { leaf enable-qos {
type empty; type empty;
} }
the following is an example of a valid encoding the following is an example of a valid encoding
<enable-qos/> <enable-qos/>
if the leaf exists. if the leaf exists.
9.12. The union Built-In Type 9.12. The union Built-In Type
skipping to change at page 146, line 45 skipping to change at page 149, line 30
9.12.3. Canonical Form 9.12.3. Canonical Form
The canonical form of a union value is the same as the canonical form The canonical form of a union value is the same as the canonical form
of the member type of the value. of the member type of the value.
9.12.4. Usage Example 9.12.4. Usage Example
The following is a union of an int32 an enumeration: The following is a union of an int32 an enumeration:
type union { type union {
type int32; type int32;
type enumeration { type enumeration {
enum "unbounded"; enum "unbounded";
} }
} }
Care must be taken when a member type is a leafref where the Care must be taken when a member type is a leafref where the
"require-instance" property (Section 9.9.3) is "true". If a leaf of "require-instance" property (Section 9.9.3) is "true". If a leaf of
such a type refers to an existing instance, the leaf's value must be such a type refers to an existing instance, the leaf's value must be
re-validated if the target instance is deleted. For example, with re-validated if the target instance is deleted. For example, with
the following definitions: the following definitions:
list filter { list filter {
key name; key name;
leaf name { leaf name {
type string; type string;
} }
... ...
} }
leaf outbound-filter { leaf outbound-filter {
type union { type union {
type leafref { type leafref {
path "/filter/name"; path "/filter/name";
} }
type enumeration { type enumeration {
enum default-filter; enum default-filter;
}
} }
}
} }
assume that there exists an entry in the filter list with the name assume that there exists an entry in the filter list with the name
"http", and that the outbound-filter leaf has this value: "http", and that the outbound-filter leaf has this value:
<filter> <filter>
<name>http</name> <name>http</name>
</filter> </filter>
<outbound-filter>http</outbound-filter> <outbound-filter>http</outbound-filter>
skipping to change at page 147, line 51 skipping to change at page 150, line 48
instead of an enumeration, the current value would have matched, and instead of an enumeration, the current value would have matched, and
the resulting configuration would have been valid. the resulting configuration would have been valid.
9.13. The instance-identifier Built-In Type 9.13. The instance-identifier Built-In Type
The instance-identifier built-in type is used to uniquely identify a The instance-identifier built-in type is used to uniquely identify a
particular instance node in the data tree. particular instance node in the data tree.
The syntax for an instance-identifier is a subset of the XPath The syntax for an instance-identifier is a subset of the XPath
abbreviated syntax, formally defined by the rule abbreviated syntax, formally defined by the rule
"instance-identifier" in Section 13. It is used to uniquely identify "instance-identifier" in Section 14. It is used to uniquely identify
a node in the data tree. Predicates are used only for specifying the a node in the data tree. Predicates are used only for specifying the
values for the key nodes for list entries, a value of a leaf-list values for the key nodes for list entries, a value of a leaf-list
entry, or a positional index for a list without keys. For entry, or a positional index for a list without keys. For
identifying list entries with keys, each predicate consists of one identifying list entries with keys, each predicate consists of one
equality test per key, and each key MUST have a corresponding equality test per key, and each key MUST have a corresponding
predicate. predicate.
If the leaf with the instance-identifier type represents If the leaf with the instance-identifier type represents
configuration data, and the "require-instance" property configuration data, and the "require-instance" property
(Section 9.9.3) is "true", the node it refers to MUST also represent (Section 9.9.3) is "true", the node it refers to MUST also represent
skipping to change at page 151, line 5 skipping to change at page 154, line 5
an empty node-set is returned. an empty node-set is returned.
If the first argument node is of type leafref, the function returns a If the first argument node is of type leafref, the function returns a
node set that contains the nodes that the leafref refers to. node set that contains the nodes that the leafref refers to.
If the first argument node is of any other type, an empty node set is If the first argument node is of any other type, an empty node set is
returned. returned.
10.3.1.1. Usage Example 10.3.1.1. Usage Example
list interface { list interface {
key name; key "name type";
leaf name { ... } leaf name { ... }
leaf enabled { leaf type { ... }
type boolean; leaf enabled {
} type boolean;
... }
...
} }
leaf mgmt-inter