draft-ietf-netmod-rfc6087bis-16.txt   draft-ietf-netmod-rfc6087bis-17.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Obsoletes: 6087 (if approved) January 18, 2018 Obsoletes: 6087 (if approved) February 5, 2018
Intended status: BCP Intended status: BCP
Expires: July 22, 2018 Expires: August 9, 2018
Guidelines for Authors and Reviewers of YANG Data Model Documents Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-rfc6087bis-16 draft-ietf-netmod-rfc6087bis-17
Abstract Abstract
This memo provides guidelines for authors and reviewers of Standards This memo provides guidelines for authors and reviewers of Standards
Track specifications containing YANG data model modules. Applicable Track specifications containing YANG data model modules. Applicable
portions may be used as a basis for reviews of other YANG data model portions may be used as a basis for reviews of other YANG data model
documents. Recommendations and procedures are defined, which are documents. Recommendations and procedures are defined, which are
intended to increase interoperability and usability of Network intended to increase interoperability and usability of Network
Configuration Protocol (NETCONF) and RESTCONF protocol Configuration Protocol (NETCONF) and RESTCONF protocol
implementations that utilize YANG data model modules. This document implementations that utilize YANG data model modules. This document
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 July 22, 2018. This Internet-Draft will expire on August 9, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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 29 skipping to change at page 2, line 29
3. General Documentation Guidelines . . . . . . . . . . . . . . . 10 3. General Documentation Guidelines . . . . . . . . . . . . . . . 10
3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10
3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 10 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 10
3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11
3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11
3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11
3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12
3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12
3.7. Security Considerations Section . . . . . . . . . . . . . 13 3.7. Security Considerations Section . . . . . . . . . . . . . 13
3.7.1. Security Considerations Section Template . . . . . . . 13 3.7.1. Security Considerations Section Template . . . . . . . 13
3.8. IANA Considerations Section . . . . . . . . . . . . . . . 14 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 15
3.8.1. Documents that Create a New Namespace . . . . . . . . 15 3.8.1. Documents that Create a New Namespace . . . . . . . . 15
3.8.2. Documents that Extend an Existing Namespace . . . . . 15 3.8.2. Documents that Extend an Existing Namespace . . . . . 15
3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15
3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16
3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16
3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 16 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 17
4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 17 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 18
4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 17 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 18
4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 19 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 20
4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 19 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 20
4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 20 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 21
4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 21 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 22
4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 21 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 22
4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 22 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 23
4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 23 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 24 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 25
4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 24 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 26
4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 25 4.7. YANG Definition Lifecycle Management . . . . . . . . . . . 27
4.8. Module Header, Meta, and Revision Statements . . . . . . . 26 4.8. Module Header, Meta, and Revision Statements . . . . . . . 28
4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 27 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 29
4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 28 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 30
4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 29 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 31
4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 29 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 31
4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 30 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 32
4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 31 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 33
4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 32 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 33
4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 33 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 34
4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 34 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 35
4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 35 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 36
4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 35 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 37
4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 37 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 38
4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 37 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 39
4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 38 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 39
4.16. Notification Definitions . . . . . . . . . . . . . . . . . 38 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 39
4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 39 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 40
4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 39 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 41
4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 39 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 41
4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 40 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 41
4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 40 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 41
4.19.1. Conditional Augment Statements . . . . . . . . . . . . 40 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 42
4.19.2. Conditionally Mandatory Data Definition Statements . . 41 4.19.2. Conditionally Mandatory Data Definition Statements . . 42
4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 42 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 44
4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 43 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 44 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 45
4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 45 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 46
4.23. Operational State . . . . . . . . . . . . . . . . . . . . 46 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47
4.23.1. Combining Operational State and Configuration Data . . 46 4.23.1. Combining Operational State and Configuration Data . . 47
4.23.2. Representing Operational Values of Configuration 4.23.2. Representing Operational Values of Configuration
Data . . . . . . . . . . . . . . . . . . . . . . . . . 47 Data . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 47 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 48
4.24. Performance Considerations . . . . . . . . . . . . . . . . 51 4.24. Performance Considerations . . . . . . . . . . . . . . . . 52
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 51 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 53
4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 52 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 53
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 52 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 53
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 52 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 53
4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 52 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 54
4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 52 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 54
4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 53 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 55
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56
6. Security Considerations . . . . . . . . . . . . . . . . . . . 56 6. Security Considerations . . . . . . . . . . . . . . . . . . . 57
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 57 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59
8.1. Normative References . . . . . . . . . . . . . . . . . . . 58 8.1. Normative References . . . . . . . . . . . . . . . . . . . 59
8.2. Informative References . . . . . . . . . . . . . . . . . . 58 8.2. Informative References . . . . . . . . . . . . . . . . . . 59
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 62
A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.2. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.2. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.3. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.3. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.4. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 A.4. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.5. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.5. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 62
A.6. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.6. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.7. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.7. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.8. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.8. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.9. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.9. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.10. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.10. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.11. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.11. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.12. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.12. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.13. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.13. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.14. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.14. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.15. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.15. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.16. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.16. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 65
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66 A.17. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 65
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 67
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 69
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71
1. Introduction 1. Introduction
The standardization of network configuration interfaces for use with The standardization of network configuration interfaces for use with
network configuration management protocols, such as the Network network configuration management protocols, such as the Network
Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a Configuration Protocol [RFC6241] and RESTCONF [RFC8040], requires a
modular set of data models, which can be reused and extended over modular set of data models, which can be reused and extended over
time. time.
This document defines a set of usage guidelines for Standards Track This document defines a set of usage guidelines for Standards Track
documents containing [RFC7950] data models. YANG is used to define documents containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data
the data structures, protocol operations, and notification content models. YANG is used to define the data structures, protocol
used within a NETCONF and/or RESTCONF server. A NETCONF or RESTCONF operations, and notification content used within a NETCONF and/or
server that supports a particular YANG module will support client RESTCONF server. A NETCONF or RESTCONF server that supports a
NETCONF and/or RESTCONF operation requests, as indicated by the particular YANG module will support client NETCONF and/or RESTCONF
specific content defined in the YANG module. operation requests, as indicated by the specific content defined in
the YANG module.
Many YANG constructs are defined as optional to use, such as the Many YANG constructs are defined as optional to use, such as the
description statement. However, in order to make YANG modules more description statement. However, in order to make YANG modules more
useful, it is desirable to define a set of usage guidelines that useful, it is desirable to define a set of usage guidelines that
entails a higher level of compliance than the minimum level defined entails a higher level of compliance than the minimum level defined
in the YANG specification. in the YANG specification.
In addition, YANG allows constructs such as infinite length In addition, YANG allows constructs such as infinite length
identifiers and string values, or top-level mandatory nodes, that a identifiers and string values, or top-level mandatory nodes, that a
compliant server is not required to support. Only constructs that compliant server is not required to support. Only constructs that
skipping to change at page 10, line 5 skipping to change at page 9, line 43
is considered an unstable publication that is a work-in-progress, is considered an unstable publication that is a work-in-progress,
subject to change at any time. subject to change at any time.
o YANG fragment: A set of YANG statements that are not intended to o YANG fragment: A set of YANG statements that are not intended to
represent a complete YANG module or submodule. These statements represent a complete YANG module or submodule. These statements
are not intended for actual use, except to provide an example of are not intended for actual use, except to provide an example of
YANG statement usage. The invalid syntax "..." is sometimes used YANG statement usage. The invalid syntax "..." is sometimes used
to indicate that additional YANG statements would be present in a to indicate that additional YANG statements would be present in a
real YANG module. real YANG module.
o YANG tree diagram: a diagram representing the contents of a YANG
module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also
called a "tree diagram".
3. General Documentation Guidelines 3. General Documentation Guidelines
YANG data model modules under review are likely to be contained in YANG data model modules under review are likely to be contained in
Internet-Drafts. All guidelines for Internet-Draft authors MUST be Internet-Drafts. All guidelines for Internet-Draft authors MUST be
followed. The RFC Editor provides guidelines for authors of RFCs, followed. The RFC Editor provides guidelines for authors of RFCs,
which are first published as Internet-Drafts. These guidelines which are first published as Internet-Drafts. These guidelines
should be followed and are defined in [RFC7322] and updated in should be followed and are defined in [RFC7322] and updated in
[RFC7841] and "RFC Document Style" [RFC-STYLE]. [RFC7841] and "RFC Document Style" [RFC-STYLE].
The following sections MUST be present in an Internet-Draft The following sections MUST be present in an Internet-Draft
skipping to change at page 10, line 36 skipping to change at page 10, line 36
There are three usage scenarios for YANG that can appear in an There are three usage scenarios for YANG that can appear in an
Internet-Draft or RFC: Internet-Draft or RFC:
o normative module or submodule o normative module or submodule
o example module or submodule o example module or submodule
o example YANG fragment not part of any module or submodule o example YANG fragment not part of any module or submodule
The guidelines in this document refer mainly to a normative complete The guidelines in this document refer mainly to a normative module or
module or submodule, but may be applicable to example modules and submodule, but may be applicable to example modules and YANG
YANG fragments as well. fragments as well.
3.1. Module Copyright 3.1. Module Copyright
The module description statement MUST contain a reference to the The module description statement MUST contain a reference to the
latest approved IETF Trust Copyright statement, which is available latest approved IETF Trust Copyright statement, which is available
online at: online at:
http://trustee.ietf.org/license-info/ http://trustee.ietf.org/license-info/
3.2. Code Components 3.2. Code Components
Each normative YANG module or submodule contained within an Internet- Each normative YANG module or submodule contained within an Internet-
Draft or RFC is considered to be a code component. The strings Draft or RFC is considered to be a code component. The strings
"<CODE BEGINS>" and "<CODE ENDS>" MUST be used to identify each code "<CODE BEGINS>" and "<CODE ENDS>" MUST be used to identify each code
component. component.
The "<CODE BEGINS>" tag SHOULD be followed by a string identifying The "<CODE BEGINS>" tag SHOULD be followed by a string identifying
the file name specified in Section 5.2 of [RFC7950]. The name string the file name specified in Section 5.2 of [RFC7950]. The name string
form that includes the revision-date SHOULD be used. The following form that includes the revision-date SHOULD be used. The revision
example is for the '2010-01-18' revision of the 'ietf-foo' module: date MUST match the date used in the most recent revision of the
module.
The following example is for the '2010-01-18' revision of the
'ietf-foo' module:
<CODE BEGINS> file "ietf-foo@2016-03-20.yang" <CODE BEGINS> file "ietf-foo@2016-03-20.yang"
module ietf-foo { module ietf-foo {
namespace "urn:ietf:params:xml:ns:yang:ietf-foo"; namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
prefix "foo"; prefix "foo";
organization "..."; organization "...";
contact "..."; contact "...";
description "..."; description "...";
revision 2016-03-20 { revision 2016-03-20 {
skipping to change at page 11, line 35 skipping to change at page 11, line 39
<CODE ENDS> <CODE ENDS>
3.2.1. Example Modules 3.2.1. Example Modules
Example modules are not code components. The <CODE BEGINS> Example modules are not code components. The <CODE BEGINS>
convention MUST NOT be used for example modules. convention MUST NOT be used for example modules.
An example module SHOULD be named using the term "example", followed An example module SHOULD be named using the term "example", followed
by a hyphen, followed by a descriptive name, e.g., "example-toaster". by a hyphen, followed by a descriptive name, e.g., "example-toaster".
See Section 4.9 regarding the namespace guidelines for example
modules.
3.3. Terminology Section 3.3. Terminology Section
A terminology section MUST be present if any terms are defined in the A terminology section MUST be present if any terms are defined in the
document or if any terms are imported from other documents. document or if any terms are imported from other documents.
If YANG tree diagrams are used, then a normative reference to the
YANG tree diagrams specification MUST be provided for each diagram.
(Refer to the example in the next section.)
3.4. Tree Diagrams 3.4. Tree Diagrams
YANG tree diagrams provide a concise representation of a YANG module, YANG tree diagrams provide a concise representation of a YANG module,
and SHOULD be included to help readers understand YANG module and SHOULD be included to help readers understand YANG module
structure. Guidelines on tree diagrams can be found in Section 3 of structure. Guidelines on tree diagrams can be found in Section 3 of
[I-D.ietf-netmod-yang-tree-diagrams].
The following example shows a simple YANG tree diagram [I-D.ietf-netmod-yang-tree-diagrams].
[I-D.ietf-netmod-yang-tree-diagrams]:
+--rw top-level-config-container If YANG tree diagrams are used, then an informative reference to the
| +--rw config-list* [key-name] YANG tree diagrams specification MUST be included in the document.
| +--rw key-name string Refer to Section 2.2 of [I-D.ietf-netmod-rfc8022bis] for an example
| +--rw optional-parm? string of such a reference.
| +--rw mandatory-parm identityref
| +--ro read-only-leaf string
+--ro top-level-nonconfig-container
+--ro nonconfig-list* [name]
+--ro name string
+--ro type string
3.5. Narrative Sections 3.5. Narrative Sections
The narrative part MUST include an overview section that describes The narrative part MUST include an overview section that describes
the scope and field of application of the module(s) defined by the the scope and field of application of the module(s) defined by the
specification and that specifies the relationship (if any) of these specification and that specifies the relationship (if any) of these
modules to other standards, particularly to standards containing modules to other standards, particularly to standards containing
other YANG modules. The narrative part SHOULD include one or more other YANG modules. The narrative part SHOULD include one or more
sections to briefly describe the structure of the modules defined in sections to briefly describe the structure of the modules defined in
the specification. the specification.
If the module(s) defined by the specification imports definitions If the module(s) defined by the specification imports definitions
from other modules (except for those defined in the [RFC7950] or from other modules (except for those defined in the [RFC7950] or
[RFC6991] documents), or are always implemented in conjunction with [RFC6991] documents), or are always implemented in conjunction with
other modules, then those facts MUST be noted in the overview other modules, then those facts MUST be noted in the overview
section, as MUST be noted any special interpretations of definitions section, as MUST be noted any special interpretations of definitions
in other modules. in other modules. Refer to section 2.3 of
[I-D.ietf-netmod-rfc8022bis] for an example of this overview section.
If the documents contains YANG module(s) that are compliant with the
Network Management Datastore Architecture (NMDA)
[I-D.ietf-netmod-revised-datastores], then the Abstract and
Introduction sections should mention this fact.
Example:
The YANG model in this document conforms to the Network Management
Datastore Architecture defined in I-D.ietf-netmod-revised-datastores.
3.6. Definitions Section 3.6. Definitions Section
This section contains the module(s) defined by the specification. This section contains the module(s) defined by the specification.
These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax. These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax.
YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs or
semantics are needed in the module. semantics are needed in the module. If any of the imported YANG
modules are written using YANG 1.1, then the module MUST be written
using YANG 1.1.
A YIN syntax version of the module MAY also be present in the A YIN syntax version of the module MAY also be present in the
document. There MAY also be other types of modules present in the document. There MAY also be other types of modules present in the
document, such as SMIv2, which are not affected by these guidelines. document, such as SMIv2, which are not affected by these guidelines.
Note that all YANG statements within a YANG module are considered Note that all YANG statements within a YANG module are considered
normative, if the module itself is considered normative, and not an normative, if the module itself is considered normative, and not an
example module. The use of keywords defined in [RFC2119] apply to example module or example YANG fragment. The use of keywords defined
YANG description statements in normative modules exactly as they in [RFC2119] apply to YANG description statements in normative
would in any other normative section. modules exactly as they would in any other normative section.
Example YANG modules MUST NOT contain any normative text, including Example YANG modules and example YANG fragments MUST NOT contain any
any reserved words from [RFC2119]. normative text, including any reserved words from [RFC2119].
See Section 4 for guidelines on YANG usage. See Section 4 for guidelines on YANG usage.
3.7. Security Considerations Section 3.7. Security Considerations Section
Each specification that defines one or more modules MUST contain a Each specification that defines one or more modules MUST contain a
section that discusses security considerations relevant to those section that discusses security considerations relevant to those
modules. modules.
This section MUST be patterned after the latest approved template This section MUST be patterned after the latest approved template
skipping to change at page 16, line 22 skipping to change at page 16, line 27
https://github.com/mbj4668/pyang https://github.com/mbj4668/pyang
If the 'pyang' compiler is used to validate a normative module, then If the 'pyang' compiler is used to validate a normative module, then
the "--ietf" command line option MUST be used to identify any IETF the "--ietf" command line option MUST be used to identify any IETF
guideline issues. guideline issues.
If the 'pyang' compiler is used to validate an example module, then If the 'pyang' compiler is used to validate an example module, then
the "--ietf" command line option MAY be used to identify any IETF the "--ietf" command line option MAY be used to identify any IETF
guideline issues. guideline issues.
The "yanglint" program is also freely available from github.
https://github.com/CESNET/libyang
This tool can be used to validate XPath statements within YANG
modules.
3.11. Module Extraction Tools 3.11. Module Extraction Tools
A version of 'rfcstrip' is available which will extract YANG modules A version of 'rfcstrip' is available which will extract YANG modules
from an Internet Draft or RFC. The 'rfcstrip' tool which supports from an Internet Draft or RFC. The 'rfcstrip' tool which supports
YANG module extraction is freely available: YANG module extraction is freely available:
http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip http://www.yang-central.org/twiki/pub/Main/YangTools/rfcstrip
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE This tool can be used to verify that the "<CODE BEGINS>" and "<CODE
ENDS>" tags are used correctly and that the normative YANG modules ENDS>" tags are used correctly and that the normative YANG modules
can be extracted correctly. can be extracted correctly.
The "xym" tool is freely available on github and can be used to
extract YANG modules from a document.
https://github.com/xym-tool/xym
3.12. Module Usage Examples 3.12. Module Usage Examples
Each specification that defines one or more modules SHOULD contain Each specification that defines one or more modules SHOULD contain
usage examples, either throughout the document or in an appendix. usage examples, either throughout the document or in an appendix.
This includes example instance document snippets in an appropriate This includes example instance document snippets in an appropriate
encoding (e.g., XML and/or JSON) to demonstrate the intended usage of encoding (e.g., XML and/or JSON) to demonstrate the intended usage of
the YANG module(s). the YANG module(s). Example modules MUST be validated. Refer to
Section 3.10 for tools which validate YANG modules.
4. YANG Usage Guidelines 4. YANG Usage Guidelines
Modules in IETF Standards Track specifications MUST comply with all Modules in IETF Standards Track specifications MUST comply with all
syntactic and semantic requirements of YANG [RFC7950]. The syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the
guidelines in this section are intended to supplement the YANG exception for YANG 1.0 in Section 3.6. The guidelines in this
specification, which is intended to define a minimum set of section are intended to supplement the YANG specification, which is
conformance requirements. intended to define a minimum set of conformance requirements.
In order to promote interoperability and establish a set of practices In order to promote interoperability and establish a set of practices
based on previous experience, the following sections establish usage based on previous experience, the following sections establish usage
guidelines for specific YANG constructs. guidelines for specific YANG constructs.
Only guidelines that clarify or restrict the minimum conformance Only guidelines that clarify or restrict the minimum conformance
requirements are included here. requirements are included here.
4.1. Module Naming Conventions 4.1. Module Naming Conventions
skipping to change at page 20, line 36 skipping to change at page 21, line 36
4.5. Conditional Statements 4.5. Conditional Statements
A module may be conceptually partitioned in several ways, using the A module may be conceptually partitioned in several ways, using the
'if-feature' and/or 'when' statements. 'if-feature' and/or 'when' statements.
Data model designers need to carefully consider all modularity Data model designers need to carefully consider all modularity
aspects, including the use of YANG conditional statements. aspects, including the use of YANG conditional statements.
If a data definition is optional, depending on server support for a If a data definition is optional, depending on server support for a
NETCONF or RESTCONF protocol capability, then a YANG 'feature' NETCONF or RESTCONF protocol capability, then a YANG 'feature'
statement SHOULD be defined to indicate that the NETCONF or RESTCONF statement SHOULD be defined. The defined "feature" statement SHOULD
capability is supported within the data model. then be used in the conditional "if-feature" statement referencing
the optional data definition.
If any notification data, or any data definition, for a non- If any notification data, or any data definition, for a non-
configuration data node is not mandatory, then the server may or may configuration data node is not mandatory, then the server may or may
not be required to return an instance of this data node. If any not be required to return an instance of this data node. If any
conditional requirements exist for returning the data node in a conditional requirements exist for returning the data node in a
notification payload or retrieval request, they MUST be documented notification payload or retrieval request, they MUST be documented
somewhere. For example, a 'when' or 'if-feature' statement could somewhere. For example, a 'when' or 'if-feature' statement could
apply to the data node, or the conditional requirements could be apply to the data node, or the conditional requirements could be
explained in a 'description' statement within the data node or one of explained in a 'description' statement within the data node or one of
its ancestors (if any). its ancestors (if any).
skipping to change at page 23, line 5 skipping to change at page 24, line 12
function results can also be different. Any function call that function results can also be different. Any function call that
implicitly converts a node-set to a string will also have this issue. implicitly converts a node-set to a string will also have this issue.
The 'local-name' function SHOULD NOT be used to reference local names The 'local-name' function SHOULD NOT be used to reference local names
outside of the YANG module defining the must or when expression outside of the YANG module defining the must or when expression
containing the 'local-name' function. Example of a local-name containing the 'local-name' function. Example of a local-name
function that should not be used: function that should not be used:
/*[local-name()='foo'] /*[local-name()='foo']
The 'derived-from-or-self' function SHOULD be used instead of an
equality expression for identityref values. This allows the
identities to be conceptually augmented.
Example:
// do not use
when "md-name-format = 'name-format-null'";
// this is preferred
when "derived-from-or-self(md-name-format, 'name-format-null')";
4.6.3. Axes 4.6.3. Axes
The 'attribute' and 'namespace' axes are not supported in YANG, and The 'attribute' and 'namespace' axes are not supported in YANG, and
MAY be empty in a NETCONF or RESTCONF server implementation. MAY be empty in a NETCONF or RESTCONF server implementation.
The 'preceding', and 'following' axes SHOULD NOT be used. These The 'preceding', and 'following' axes SHOULD NOT be used. These
constructs rely on XML document order within a NETCONF or RESTCONF constructs rely on XML document order within a NETCONF or RESTCONF
server configuration database, which may not be supported server configuration database, which may not be supported
consistently or produce reliable results across implementations. consistently or produce reliable results across implementations.
Predicate expressions based on static node properties (e.g., element Predicate expressions based on static node properties (e.g., element
skipping to change at page 25, line 41 skipping to change at page 27, line 17
enum one; enum one;
enum two; enum two;
enum three; enum three;
enum four; enum four;
} }
} }
Now the first XPath expression will allow the enum "four" to be Now the first XPath expression will allow the enum "four" to be
accepted in addition to the "one" and "three" enum values. accepted in addition to the "one" and "three" enum values.
4.7. Lifecycle Management 4.7. YANG Definition Lifecycle Management
The status statement MUST be present if its value is 'deprecated' or The YANG status statement MUST be present within a definition if its
'obsolete'. The status SHOULD NOT be changed from 'current' directly value is 'deprecated' or 'obsolete'. The status SHOULD NOT be
to 'obsolete'. An object SHOULD be available for at least one year changed from 'current' directly to 'obsolete'. An object SHOULD be
with 'deprecated' status before it is changed to 'obsolete'. available for at least one year with 'deprecated' status before it is
changed to 'obsolete'.
The module or submodule name MUST NOT be changed, once the document The module or submodule name MUST NOT be changed, once the document
containing the module or submodule is published. containing the module or submodule is published.
The module namespace URI value MUST NOT be changed, once the document The module namespace URI value MUST NOT be changed, once the document
containing the module is published. containing the module is published.
The revision-date substatement within the import statement SHOULD be The revision-date substatement within the import statement SHOULD be
present if any groupings are used from the external module. present if any groupings are used from the external module.
skipping to change at page 27, line 6 skipping to change at page 28, line 30
contained in a document intended for IETF Standards Track status, contained in a document intended for IETF Standards Track status,
then the organization SHOULD be the IETF working group chartered to then the organization SHOULD be the IETF working group chartered to
write the document. For other standards organizations, a similar write the document. For other standards organizations, a similar
approach is also suggested. approach is also suggested.
The contact statement MUST be present. If the module is contained in The contact statement MUST be present. If the module is contained in
a document intended for Standards Track status, then the working a document intended for Standards Track status, then the working
group web and mailing information MUST be present, and the main group web and mailing information MUST be present, and the main
document author or editor contact information SHOULD be present. If document author or editor contact information SHOULD be present. If
additional authors or editors exist, their contact information MAY be additional authors or editors exist, their contact information MAY be
present. present. There is no need to include the contact information for
Working Group chairs.
The description statement MUST be present. For modules published The description statement MUST be present. For modules published
within IETF documents, the appropriate IETF Trust Copyright text MUST within IETF documents, the appropriate IETF Trust Copyright text MUST
be present, as described in Section 3.1. be present, as described in Section 3.1.
If the module relies on information contained in other documents, If the module relies on information contained in other documents,
which are not the same documents implied by the import statements which are not the same documents implied by the import statements
present in the module, then these documents MUST be identified in the present in the module, then these documents MUST be identified in the
reference statement. reference statement.
skipping to change at page 29, line 5 skipping to change at page 30, line 30
The top-level data organization SHOULD be considered carefully, in The top-level data organization SHOULD be considered carefully, in
advance. Data model designers need to consider how the functionality advance. Data model designers need to consider how the functionality
for a given protocol or protocol family will grow over time. for a given protocol or protocol family will grow over time.
The separation of configuration data and operational state SHOULD be The separation of configuration data and operational state SHOULD be
considered carefully. It is sometimes useful to define separate top- considered carefully. It is sometimes useful to define separate top-
level containers for configuration and non-configuration data. For level containers for configuration and non-configuration data. For
some existing top-level data nodes, configuration data was not in some existing top-level data nodes, configuration data was not in
scope, so only one container representing operational state was scope, so only one container representing operational state was
created. created. Refer to the Network Management Datastore Architecture
(NMDA) [I-D.ietf-netmod-revised-datastores]. for details.
The number of top-level data nodes within a module SHOULD be The number of top-level data nodes within a module SHOULD be
minimized. It is often useful to retrieve related information within minimized. It is often useful to retrieve related information within
a single subtree. If data is too distributed, is becomes difficult a single subtree. If data is too distributed, is becomes difficult
to retrieve all at once. to retrieve all at once.
The names and data organization SHOULD reflect persistent The names and data organization SHOULD reflect persistent
information, such as the name of a protocol. The name of the working information, such as the name of a protocol. The name of the working
group SHOULD NOT be used because this may change over time. group SHOULD NOT be used because this may change over time.
skipping to change at page 37, line 47 skipping to change at page 39, line 10
Use of non-presence containers to organize data is a subjective Use of non-presence containers to organize data is a subjective
matter similar to use of sub-directories in a file system. The matter similar to use of sub-directories in a file system. The
NETCONF and RESTCONF protocols do not currently support the ability NETCONF and RESTCONF protocols do not currently support the ability
to delete all list (or leaf-list) entries at once. This deficiency to delete all list (or leaf-list) entries at once. This deficiency
is sometimes avoided by use of a parent container (i.e., deleting the is sometimes avoided by use of a parent container (i.e., deleting the
container also removes all child entries). container also removes all child entries).
4.14.2. Top-Level Data Nodes 4.14.2. Top-Level Data Nodes
Use of top-level objects needs to be considered carefully Use of top-level objects needs to be considered carefully:
o top-level siblings are not ordered
o top-level siblings not are not static, and depends on the modules
that are loaded
-top-level siblings are not ordered -top-level siblings not are not
static, and depends on the modules that are loaded
o for sub-tree filtering, retrieval of a top-level leaf-list will be o for sub-tree filtering, retrieval of a top-level leaf-list will be
treated as a content-match node for all top-level-siblings treated as a content-match node for all top-level-siblings
o a top-level list with many instances may impact performance o a top-level list with many instances may impact performance
4.15. Operation Definitions 4.15. Operation Definitions
If the operation semantics are defined in an external document (other If the operation semantics are defined in an external document (other
than another YANG module indicated by an import statement), then a than another YANG module indicated by an import statement), then a
reference statement MUST be present. reference statement MUST be present.
skipping to change at page 39, line 9 skipping to change at page 40, line 24
Note that there are no formal YANG statements to identify any data Note that there are no formal YANG statements to identify any data
node resources associated with a notification. The description node resources associated with a notification. The description
statement for the notification SHOULD specify if and how the statement for the notification SHOULD specify if and how the
notification identifies any data node resources associated with the notification identifies any data node resources associated with the
specific event. specific event.
4.17. Feature Definitions 4.17. Feature Definitions
The YANG "feature" statement is used to define a label for a set of The YANG "feature" statement is used to define a label for a set of
optional functionality within a module. The "if-feature" statement optional functionality within a module. The "if-feature" statement
is used in the YANG statements associated with a feature. is used in the YANG statements associated with a feature. The
description-stmt within a feature-stmt MUST specify any interactions
with other features.
The set of YANG features available in a module should be considered The set of YANG features defined in a module should be considered
carefully. The description-stmt within a feature-stmt MUST specify carefully. Very fine granular features increase interoperability
any interactions with other features. complexity and should be avoided. A likely misuse of the feature
mechanism is the tagging of individual leafs (e.g., counters) with
separate features.
If there is a large set of objects associated with a YANG feature, If there is a large set of objects associated with a YANG feature,
then consider moving those objects to a separate module, instead of then consider moving those objects to a separate module, instead of
using a YANG feature. Note that the set of features within a module using a YANG feature. Note that the set of features within a module
is easily discovered by the reader, but the set of related modules is easily discovered by the reader, but the set of related modules
within the entire YANG library is not as easy to identity. Module within the entire YANG library is not as easy to identity. Module
names with a common prefix can help readers identity the set of names with a common prefix can help readers identity the set of
related modules, but this assumes the reader will have discovered and related modules, but this assumes the reader will have discovered and
installed all the relevant modules. installed all the relevant modules.
skipping to change at page 46, line 30 skipping to change at page 47, line 30
} }
} }
leaf addon { leaf addon {
type string; type string;
mandatory true; mandatory true;
} }
} }
4.23. Operational State 4.23. Operational State
The modeling operational state with YANG has been refined over time. The modeling of operational state with YANG has been refined over
At first, only data that has a "config" statement value of "false" time. At first, only data that has a "config" statement value of
was considered to be operational state. This data was not considered "false" was considered to be operational state. This data was not
to be part of any datastore, which made YANG XPath definition much considered to be part of any datastore, which made YANG XPath
more complicated. definition much more complicated.
Operational state is now modeled using YANG according to new NMDA, Operational state is now modeled using YANG according to new NMDA,
and is now conceptually contained in the operational state datastore, and is now conceptually contained in the operational state datastore,
which also includes the operational values of configuration data. which also includes the operational values of configuration data.
There is no longer any need to duplicate data structures to provide There is no longer any need to duplicate data structures to provide
separate configuration and operational state sections. separate configuration and operational state sections.
This section describes some data modeling issues related to This section describes some data modeling issues related to
operational state, and guidelines for transitioning YANG data model operational state, and guidelines for transitioning YANG data model
design to be NMDA-compatible. design to be NMDA-compatible.
skipping to change at page 48, line 30 skipping to change at page 49, line 30
type of module MAY exist, either an existing model or a model created type of module MAY exist, either an existing model or a model created
either by hand or with suitable tools that mirror the current either by hand or with suitable tools that mirror the current
modeling strategies. Both the NMDA and the non-NMDA modules SHOULD modeling strategies. Both the NMDA and the non-NMDA modules SHOULD
be published in the same document, with NMDA modules in the document be published in the same document, with NMDA modules in the document
main body and the non-NMDA modules in a non-normative appendix. The main body and the non-NMDA modules in a non-normative appendix. The
use of the non-NMDA module will allow temporary bridging of the time use of the non-NMDA module will allow temporary bridging of the time
period until NMDA implementations are available. period until NMDA implementations are available.
(b) For published models, the model should be republished with an (b) For published models, the model should be republished with an
NMDA-compatible structure, deprecating non-NMDA constructs. For NMDA-compatible structure, deprecating non-NMDA constructs. For
example, the "ietf-interfaces" model in [RFC7223] will be example, the "ietf-interfaces" model in [RFC7223] has been
restructured as an NMDA-compatible model. The "/interfaces-state" restructured as an NMDA-compatible model in
hierarchy will be marked "status deprecated". Models that mark their [I-D.ietf-netmod-rfc7223bis]. The "/interfaces-state" hierarchy has
"/foo-state" hierarchy with "status deprecated" will allow NMDA- been marked "status deprecated". Models that mark their "/foo-state"
capable implementations to avoid the cost of duplicating the state hierarchy with "status deprecated" will allow NMDA-capable
nodes, while enabling non-NMDA-capable implementations to utilize implementations to avoid the cost of duplicating the state nodes,
them for access to the operational values. while enabling non-NMDA-capable implementations to utilize them for
access to the operational values.
(c) For models that augment models which have not been structured (c) For models that augment models which have not been structured
with the NMDA, the modeler will have to consider the structure of the with the NMDA, the modeler will have to consider the structure of the
base model and the guidelines listed above. Where possible, such base model and the guidelines listed above. Where possible, such
models should move to new revisions of the base model that are NMDA- models should move to new revisions of the base model that are NMDA-
compatible. When that is not possible, augmenting "state" containers compatible. When that is not possible, augmenting "state" containers
SHOULD be avoided, with the expectation that the base model will be SHOULD be avoided, with the expectation that the base model will be
re-released with the state containers marked as deprecated. It is re-released with the state containers marked as deprecated. It is
RECOMMENDED to augment only the "/foo" hierarchy of the base model. RECOMMENDED to augment only the "/foo" hierarchy of the base model.
Where this recommendation cannot be followed, then any new "state" Where this recommendation cannot be followed, then any new "state"
skipping to change at page 59, line 5 skipping to change at page 60, line 5
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-netmod-revised-datastores] [I-D.ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-10 Architecture", draft-ietf-netmod-revised-datastores-10
(work in progress), January 2018. (work in progress), January 2018.
[I-D.ietf-netmod-rfc7223bis]
Bjorklund, M., "A YANG Data Model for Interface
Management", draft-ietf-netmod-rfc7223bis-03 (work in
progress), January 2018.
[I-D.ietf-netmod-rfc8022bis]
Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for
Routing Management (NMDA Version)",
draft-ietf-netmod-rfc8022bis-11 (work in progress),
January 2018.
[I-D.ietf-netmod-yang-tree-diagrams] [I-D.ietf-netmod-yang-tree-diagrams]
Bjorklund, M. and L. Berger, "YANG Tree Diagrams", Bjorklund, M. and L. Berger, "YANG Tree Diagrams",
draft-ietf-netmod-yang-tree-diagrams-04 (work in draft-ietf-netmod-yang-tree-diagrams-05 (work in
progress), December 2017. progress), January 2018.
[RFC-STYLE] [RFC-STYLE]
Braden, R., Ginoza, S., and A. Hagens, "RFC Document Braden, R., Ginoza, S., and A. Hagens, "RFC Document
Style", September 2009, Style", September 2009,
<http://www.rfc-editor.org/rfc-style-guide/rfc-style>. <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996,
<http://www.rfc-editor.org/info/rfc2026>. <http://www.rfc-editor.org/info/rfc2026>.
skipping to change at page 61, line 11 skipping to change at page 62, line 11
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
Appendix A. Change Log Appendix A. Change Log
-- RFC Ed.: remove this section before publication. -- RFC Ed.: remove this section before publication.
A.1. v15 to v16 A.1. v15 to v16
o address Area Director review comments posted 2018-01-25
A.2. v15 to v16
o address document shephard comments posted 2018-01-15 o address document shephard comments posted 2018-01-15
o add yang-version to template module o add yang-version to template module
A.2. v14 to v15 A.3. v14 to v15
o changed Intended status from Informational to BCP o changed Intended status from Informational to BCP
o update tree diagram guidelines section o update tree diagram guidelines section
o Change IANA template to list IESG instead of NETMOD WG as the o Change IANA template to list IESG instead of NETMOD WG as the
Registrant Registrant
o Update some references o Update some references
A.3. v13 to v14 A.4. v13 to v14
o Replaced sec. 4.23 Operational Data with Operational Data from o Replaced sec. 4.23 Operational Data with Operational Data from
NMDA text by Lou Berger and Kent Watsen NMDA text by Lou Berger and Kent Watsen
o Added NMDA Terms section o Added NMDA Terms section
o Changed term operational data to operational state o Changed term operational data to operational state
o Clarified that reference-stmt SHOULD be present in import-stmt o Clarified that reference-stmt SHOULD be present in import-stmt
A.4. v12 to v13 A.5. v12 to v13
o Clarify that the revision-date SHOULD be used in a CODE BEGINS o Clarify that the revision-date SHOULD be used in a CODE BEGINS
YANG file extraction macro. YANG file extraction macro.
o Clarify the IANA requirements section wrt/ XML namespace and YANG o Clarify the IANA requirements section wrt/ XML namespace and YANG
module name registries. module name registries.
o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. o Clarify YANG Usage section wrt/ XML and/or JSON encoding format.
o Update Operation Data section to consider revised datastores. o Update Operation Data section to consider revised datastores.
o Add reference to YANG Tree Diagrams and update 2 sections that use o Add reference to YANG Tree Diagrams and update 2 sections that use
this reference. this reference.
o Add reference to Revised Datastores and guidelines drafts o Add reference to Revised Datastores and guidelines drafts
A.5. v11 to v12 A.6. v11 to v12
o fix incorrect location of new Module Usage Examples section o fix incorrect location of new Module Usage Examples section
A.6. v10 to v11 A.7. v10 to v11
o updated YANG tree diagram syntax to align with pyang 1.7.1 o updated YANG tree diagram syntax to align with pyang 1.7.1
o added general guideline to include module usage examples o added general guideline to include module usage examples
A.7. v09 to v10 A.8. v09 to v10
o clarified <CODE BEGINS> is only for normative modules o clarified <CODE BEGINS> is only for normative modules
o clarified example module namespace URI conventions o clarified example module namespace URI conventions
o clarified pyang usage for normative and example modules o clarified pyang usage for normative and example modules
o updated YANG tree diagrams section with text from RFC 8022 o updated YANG tree diagrams section with text from RFC 8022
A.8. v08 to v09 A.9. v08 to v09
o fixed references o fixed references
o added mention of RESTCONF to abstract and intro o added mention of RESTCONF to abstract and intro
o created separate section for code components o created separate section for code components
o fixed document status o fixed document status
A.9. v07 to v08 A.10. v07 to v08
o changed CODE BEGINS guideline for example modules o changed CODE BEGINS guideline for example modules
o updated tree diagram guidelines o updated tree diagram guidelines
o clarified published and unpublished terms o clarified published and unpublished terms
o added section on Empty and Boolean data types o added section on Empty and Boolean data types
o clarified how to update the revision statement o clarified how to update the revision statement
skipping to change at page 62, line 48 skipping to change at page 64, line 4
o changed CODE BEGINS guideline for example modules o changed CODE BEGINS guideline for example modules
o updated tree diagram guidelines o updated tree diagram guidelines
o clarified published and unpublished terms o clarified published and unpublished terms
o added section on Empty and Boolean data types o added section on Empty and Boolean data types
o clarified how to update the revision statement o clarified how to update the revision statement
o updated operational state guidelines o updated operational state guidelines
o added 'YANG fragment' to terminology section o added 'YANG fragment' to terminology section
A.10. v06 to v07 A.11. v06 to v07
o update contact statement guideline o update contact statement guideline
o update example modules guidelines o update example modules guidelines
o add guidelines on top-level data nodes o add guidelines on top-level data nodes
o add guideline on use of NP containers o add guideline on use of NP containers
o added guidelines on union types o added guidelines on union types
o add guideline on deviations o add guideline on deviations
o added section on open systems considerations o added section on open systems considerations
o added guideline about definitions reserved for future use o added guideline about definitions reserved for future use
A.11. v05 to v06 A.12. v05 to v06
o Changed example 'my-module' to 'example-module' o Changed example 'my-module' to 'example-module'
o Added section Updating YANG Modules (Published vs. Unpublished) o Added section Updating YANG Modules (Published vs. Unpublished)
o Added Example Modules section o Added Example Modules section
o Added "<EXAMPLE BEGINS>" convention for full example modules o Added "<EXAMPLE BEGINS>" convention for full example modules
o Added section on using action vs. rpc o Added section on using action vs. rpc
o Changed term "operational state" to "operational data" o Changed term "operational state" to "operational data"
o Added section on YANG Data Node Constraints o Added section on YANG Data Node Constraints
o Added guidelines on using must vs. when statements o Added guidelines on using must vs. when statements
o Made ietf-foo module validate for I-D submission o Made ietf-foo module validate for I-D submission
A.12. v04 to v05 A.13. v04 to v05
o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if
no YANG 1.1 features needed no YANG 1.1 features needed
o Changed SHOULD follow YANG naming conventions to MUST follow (for o Changed SHOULD follow YANG naming conventions to MUST follow (for
standards track documents only) standards track documents only)
o Clarified module naming conventions for normative modules, example o Clarified module naming conventions for normative modules, example
modules, and modules from other SDOs. modules, and modules from other SDOs.
skipping to change at page 64, line 16 skipping to change at page 65, line 22
o Added new section on guidelines for reusable groupings o Added new section on guidelines for reusable groupings
o Made header guidelines less IETF-specific o Made header guidelines less IETF-specific
o Added new section on guidelines for extension statements o Added new section on guidelines for extension statements
o Added guidelines for nested "choice" statement within a "case" o Added guidelines for nested "choice" statement within a "case"
statement statement
A.13. v03 ot v04 A.14. v03 ot v04
o Added sections for deviation statements and performance o Added sections for deviation statements and performance
considerations considerations
o Added YANG 1.1 section o Added YANG 1.1 section
o Updated YANG reference from 1.0 to 1.1 o Updated YANG reference from 1.0 to 1.1
A.14. v02 to v03 A.15. v02 to v03
o Updated draft based on github data tracker issues added by Benoit o Updated draft based on github data tracker issues added by Benoit
Clause (Issues 12 - 18) Clause (Issues 12 - 18)
A.15. v01 to v02 A.16. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.16. v00 to v01 A.17. v00 to v01
All issues from the issue tracker have been addressed. All issues from the issue tracker have been addressed.
https://github.com/netmod-wg/rfc6087bis/issues https://github.com/netmod-wg/rfc6087bis/issues
o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with
YANG modules can use an Informative reference to this RFC for tree YANG modules can use an Informative reference to this RFC for tree
diagrams. Updated guidelines to reference this RFC when tree diagrams. Updated guidelines to reference this RFC when tree
diagrams are used diagrams are used
 End of changes. 55 change blocks. 
172 lines changed or deleted 236 lines changed or added

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