draft-ietf-netmod-rfc6087bis-18.txt   draft-ietf-netmod-rfc6087bis-19.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Obsoletes: 6087 (if approved) February 20, 2018 Obsoletes: 6087 (if approved) March 11, 2018
Intended status: BCP Intended status: BCP
Expires: August 24, 2018 Expires: September 12, 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-18 draft-ietf-netmod-rfc6087bis-19
Abstract Abstract
This memo provides guidelines for authors and reviewers of Standards This memo provides guidelines for authors and reviewers of
Track specifications containing YANG data model modules. Applicable specifications containing YANG data model modules. Recommendations
portions may be used as a basis for reviews of other YANG data model and procedures are defined, which are intended to increase
documents. Recommendations and procedures are defined, which are interoperability and usability of Network Configuration Protocol
intended to increase interoperability and usability of Network (NETCONF) and RESTCONF protocol implementations that utilize YANG
Configuration Protocol (NETCONF) and RESTCONF protocol data model modules. This document obsoletes RFC 6087.
implementations that utilize YANG data model modules. This document
obsoletes RFC 6087.
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 August 24, 2018. This Internet-Draft will expire on September 12, 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 21 skipping to change at page 2, line 19
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5 1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8
2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8
2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . . . . . . . . . . . . 11
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 . . . . . . . . . . . . . . . . . . . . . . 12
3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12
3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 13
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 . . . . . . . 14
3.8. IANA Considerations Section . . . . . . . . . . . . . . . 15 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 . . . . . 16
3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 16
3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16
3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 17
3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 17 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 17
4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 18 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 18
4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 18 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 18
4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 20 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 20
4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 20 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 20
4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 21 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 21
4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 22 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 22
4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 22 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 22
4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 23 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 23
4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 24 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 24
4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 25 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 25
4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 26 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 26
4.7. YANG Definition Lifecycle Management . . . . . . . . . . . 27 4.7. YANG Definition Lifecycle Management . . . . . . . . . . . 27
4.8. Module Header, Meta, and Revision Statements . . . . . . . 28 4.8. Module Header, Meta, and Revision Statements . . . . . . . 28
4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 29 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 29
4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 30 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 31
4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 31 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 31
4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 31 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 32
4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 32 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 32
4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 33 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 33
4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 33 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 34
4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 34 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 35
4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 35 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 36
4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 36 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 37
4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 37 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 37
4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 38 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 39
4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 39 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 40
4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 39 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 40
4.16. Notification Definitions . . . . . . . . . . . . . . . . . 39 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 40
4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 40 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 41
4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 41 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 42
4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 41 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 42
4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 41 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 42
4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 41 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 42
4.19.1. Conditional Augment Statements . . . . . . . . . . . . 42 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 43
4.19.2. Conditionally Mandatory Data Definition Statements . . 42 4.19.2. Conditionally Mandatory Data Definition Statements . . 43
4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 44 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 44
4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 45
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 45 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 46
4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 46 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 47
4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 48
4.23.1. Combining Operational State and Configuration Data . . 47 4.23.1. Combining Operational State and Configuration Data . . 48
4.23.2. Representing Operational Values of Configuration 4.23.2. Representing Operational Values of Configuration
Data . . . . . . . . . . . . . . . . . . . . . . . . . 48 Data . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 48 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 49
4.24. Performance Considerations . . . . . . . . . . . . . . . . 52 4.24. Performance Considerations . . . . . . . . . . . . . . . . 53
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 53 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 54
4.26. Guidelines for YANG 1.1 Specific Constructs . . . . . . . 53 4.26. Guidelines for YANG 1.1 Specific Constructs . . . . . . . 54
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 53 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 54
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 53 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 54
4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 54 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 55
4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 54 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 55
4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 55 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 56
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57
6. Security Considerations . . . . . . . . . . . . . . . . . . . 57 6. Security Considerations . . . . . . . . . . . . . . . . . . . 58
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 58 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60
8.1. Normative References . . . . . . . . . . . . . . . . . . . 59 8.1. Normative References . . . . . . . . . . . . . . . . . . . 60
8.2. Informative References . . . . . . . . . . . . . . . . . . 59 8.2. Informative References . . . . . . . . . . . . . . . . . . 61
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 62 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 63
A.1. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.1. v18 to v19 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.2. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.2. v17 to v18 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.3. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.3. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.4. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.5. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.5. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.6. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 62 A.6. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.7. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.7. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 63
A.8. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.8. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.9. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.9. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.10. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.10. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.11. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 63 A.11. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.12. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.12. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 64
A.13. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.13. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.14. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 64 A.14. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.15. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.15. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 65
A.16. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.16. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 66
A.17. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.17. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 66
A.18. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 65 A.18. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 66
A.19. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 66 A.19. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 67
Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 67 A.20. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 67
Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 69 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 68
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 70
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72
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 documents
documents containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models.
models. YANG is used to define the data structures, protocol YANG is used to define the data structures, protocol operations, and
operations, and notification content used within a NETCONF and/or notification content used within a NETCONF and/or RESTCONF server. A
RESTCONF server. A NETCONF or RESTCONF server that supports a NETCONF or RESTCONF server that supports a particular YANG module
particular YANG module will support client NETCONF and/or RESTCONF will support client NETCONF and/or RESTCONF operation requests, as
operation requests, as indicated by the specific content defined in indicated by the specific content defined in the YANG module.
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 7, line 4 skipping to change at page 6, line 48
o Clarified use of mandatory nodes with conditional augmentations o Clarified use of mandatory nodes with conditional augmentations
o Clarified namespace and domain conventions for example modules o Clarified namespace and domain conventions for example modules
o Clarified conventions for identifying code components o Clarified conventions for identifying code components
o Added YANG 1.1 guidelines o Added YANG 1.1 guidelines
o Added Data Model Constraints section o Added Data Model Constraints section
o Added mention of RESTCONF protocol
o Added mention of RESTCONF protocol
o Added guidelines for NMDA Revised Datastores o Added guidelines for NMDA Revised Datastores
2. Terminology 2. Terminology
2.1. Requirements Notation 2.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 [RFC2119] document are to be interpreted as described in BCP 14 [RFC2119]
[RFC8174] when, and only when, they appear in all capitals, as shown [RFC8174] when, and only when, they appear in all capitals, as shown
here. here.
RFC 2119 language is used here to express the views of the NETMOD
working group regarding content for YANG modules. YANG modules
complying with this document will treat the RFC 2119 terminology as
if it were describing best current practices.
2.2. NETCONF Terms 2.2. NETCONF Terms
The following terms are defined in [RFC6241] and are not redefined The following terms are defined in [RFC6241] and are not redefined
here: here:
o capabilities o capabilities
o client o client
o operation o operation
skipping to change at page 10, line 8 skipping to change at page 10, line 8
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 o YANG tree diagram: a diagram representing the contents of a YANG
module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also module, as defined in [I-D.ietf-netmod-yang-tree-diagrams]. Also
called a "tree diagram". 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
followed. The RFC Editor provides guidelines for authors of RFCs, [ID-Guidelines] MUST be followed. The RFC Editor provides guidelines
which are first published as Internet-Drafts. These guidelines for authors of RFCs, which are first published as Internet-Drafts.
should be followed and are defined in [RFC7322] and updated in These guidelines should be followed and are defined in [RFC7322] and
[RFC7841] and "RFC Document Style" [RFC-STYLE]. updated in [RFC7841], "RFC Document Style" [RFC-STYLE], and
[I-D.flanagan-7322bis].
The following sections MUST be present in an Internet-Draft The following sections MUST be present in an Internet-Draft
containing a module: containing a module:
o Narrative sections o Narrative sections
o Definitions section o Definitions section
o Security Considerations section o Security Considerations section
skipping to change at page 10, line 46 skipping to change at page 10, line 47
The guidelines in this document refer mainly to a normative module or The guidelines in this document refer mainly to a normative module or
submodule, but may be applicable to example modules and YANG submodule, but may be applicable to example modules and 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/ https://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 revision form that includes the revision-date SHOULD be used. The revision
date MUST match the date used in the most recent revision of the date MUST match the date used in the most recent revision of the
module. module.
The following example is for the '2010-01-18' revision of the The following example is for the '2016-03-20' revision of the
'ietf-foo' module: '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 "...";
skipping to change at page 12, line 32 skipping to change at page 12, line 37
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. Refer to section 2.3 of in other modules. Refer to section 2.3 of
[I-D.ietf-netmod-rfc8022bis] for an example of this overview section. [I-D.ietf-netmod-rfc8022bis] for an example of this overview section.
If the documents contains YANG module(s) that are compliant with the If the documents contains YANG module(s) that are compliant with the
Network Management Datastore Architecture (NMDA) Network Management Datastore Architecture (NMDA)
[I-D.ietf-netmod-revised-datastores], then the Abstract and [I-D.ietf-netmod-revised-datastores], then the Introduction section
Introduction sections should mention this fact. should mention this fact.
Example: Example:
The YANG model in this document conforms to the Network Management The YANG model in this document conforms to the Network
Datastore Architecture defined in I-D.ietf-netmod-revised-datastores. Management Datastore Architecture defined in
[I-D.ietf-netmod-revised-datastores].
Consistent indentation SHOULD be used for all examples, including
YANG fragments and protocol message instance data. If line wrapping
is done for formatting purposes, then this SHOULD be noted, as shown
in the following example:
[note: '\' line wrapping for formatting only]
<myleaf xmlns="tag:example.com,2017:example-two">\
this is a long value so the line needs to wrap to stay\
within 72 characters\
</myleaf>
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. If any of the imported YANG 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 modules are written using YANG 1.1, then the module MUST be written
using YANG 1.1. 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 if the module itself is considered normative and not an
normative, if the module itself is considered normative, and not an example module or example YANG fragment, then all YANG statements
example module or example YANG fragment. The use of keywords defined within a YANG module are considered normative. The use of keywords
in [RFC2119] apply to YANG description statements in normative defined in [RFC2119] apply to YANG description statements in
modules exactly as they would in any other normative section. normative modules exactly as they would in any other normative
section.
Example YANG modules and example YANG fragments MUST NOT contain any Example YANG modules and example YANG fragments MUST NOT contain any
normative text, including any reserved words from [RFC2119]. normative text, including any all-uppercase reserved words from
[RFC2119].
Consistent indentation and formatting SHOULD be used in all YANG
statements within a module.
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
(available at http://trac.tools.ietf.org/area/ops/trac/wiki/ (available at
yang-security-guidelines). Section 3.7.1 contains the security https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines).
considerations template dated 2013-05-08 and last updated 2017-12-21. Section 3.7.1 contains the security considerations template dated
Authors MUST check the WEB page at the URL listed above in case there 2013-05-08 and last updated 2017-12-21. Authors MUST check the WEB
is a more recent version available. page at the URL listed above in case there is a more recent version
available.
In particular: In particular:
o Writable data nodes that could be especially disruptive if abused o Writable data nodes that could be especially disruptive if abused
MUST be explicitly listed by name and the associated security MUST be explicitly listed by name and the associated security
risks MUST be explained. risks MUST be explained.
o Readable data nodes that contain especially sensitive information o Readable data nodes that contain especially sensitive information
or that raise significant privacy concerns MUST be explicitly or that raise significant privacy concerns MUST be explicitly
listed by name and the reasons for the sensitivity/privacy listed by name and the reasons for the sensitivity/privacy
skipping to change at page 15, line 8 skipping to change at page 15, line 33
Some of the RPC operations in this YANG module may be considered Some of the RPC operations in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the important to control access to these operations. These are the
operations and their sensitivity/vulnerability: operations and their sensitivity/vulnerability:
<list RPC operations and state why they are sensitive> <list RPC operations and state why they are sensitive>
3.8. IANA Considerations Section 3.8. IANA Considerations Section
In order to comply with IESG policy as set forth in In order to comply with IESG policy as set forth in
http://www.ietf.org/id-info/checklist.html, every Internet-Draft that https://www.ietf.org/id-info/checklist.html, every Internet-Draft
is submitted to the IESG for publication MUST contain an IANA that is submitted to the IESG for publication MUST contain an IANA
Considerations section. The requirements for this section vary Considerations section. The requirements for this section vary
depending on what actions are required of the IANA. If there are no depending on what actions are required of the IANA. If there are no
IANA considerations applicable to the document, then the IANA IANA considerations applicable to the document, then the IANA
Considerations section stating that there are no actions is removed Considerations section stating that there are no actions might be
by the RFC Editor before publication. Refer to the guidelines in removed by the RFC Editor before publication. Refer to the
[RFC8126] for more details. guidelines in [RFC8126] for more details.
Each normative YANG module MUST be registered in the XML namespace Each normative YANG module MUST be registered in the XML namespace
Registry [RFC3688], and the YANG Module Names Registry [RFC6020]. Registry [RFC3688], and the YANG Module Names Registry [RFC6020].
This applies to new modules and updated modules. Examples of these This applies to new modules and updated modules. Examples of these
registrations for the "ietf-template" module can be found in registrations for the "ietf-template" module can be found in
Section 5. Section 5.
3.8.1. Documents that Create a New Namespace 3.8.1. Documents that Create a New Namespace
If an Internet-Draft defines a new namespace that is to be If an Internet-Draft defines a new namespace that is to be
skipping to change at page 15, line 46 skipping to change at page 16, line 23
3.8.2. Documents that Extend an Existing Namespace 3.8.2. Documents that Extend an Existing Namespace
It is possible to extend an existing namespace using a YANG submodule It is possible to extend an existing namespace using a YANG submodule
that belongs to an existing module already administered by IANA. In that belongs to an existing module already administered by IANA. In
this case, the document containing the main module MUST be updated to this case, the document containing the main module MUST be updated to
use the latest revision of the submodule. use the latest revision of the submodule.
3.9. Reference Sections 3.9. Reference Sections
For every import or include statement that appears in a module For every import or include statement that appears in a module
contained in the specification, which identifies a module in a contained in the specification, that identifies a module in a
separate document, a corresponding normative reference to that separate document, a corresponding normative reference to that
document MUST appear in the Normative References section. The document MUST appear in the Normative References section. The
reference MUST correspond to the specific module version actually reference MUST correspond to the specific module version actually
used within the specification. used within the specification.
For every normative reference statement that appears in a module For every normative reference statement that appears in a module
contained in the specification, which identifies a separate document, contained in the specification, that identifies a separate document,
a corresponding normative reference to that document SHOULD appear in a corresponding normative reference to that document SHOULD appear in
the Normative References section. The reference SHOULD correspond to the Normative References section. The reference SHOULD correspond to
the specific document version actually used within the specification. the specific document version actually used within the specification.
If the reference statement identifies an informative reference, which If the reference statement identifies an informative reference, that
identifies a separate document, a corresponding informative reference identifies a separate document, a corresponding informative reference
to that document MAY appear in the Informative References section. to that document MAY appear in the Informative References section.
3.10. Validation Tools 3.10. Validation Tools
All modules need to be validated before submission in an Internet All modules need to be validated before submission in an Internet
Draft. The 'pyang' YANG compiler is freely available from github: Draft. The 'pyang' YANG compiler is freely available from github:
https://github.com/mbj4668/pyang https://github.com/mbj4668/pyang
skipping to change at page 17, line 12 skipping to change at page 17, line 36
https://github.com/xym-tool/xym 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). Example modules MUST be validated. Refer to the YANG module(s). Example modules MUST be validated. Refer to
Section 3.10 for tools which validate YANG modules. Section 3.10 for tools which validate YANG modules. If IP addresses
are used, then either a mix of IPv4 and IPv6 addresses or IPv6
addresses exclusively SHOULD be used in the examples.
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 1.1 [RFC7950]. See the syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the
exception for YANG 1.0 in Section 3.6. The guidelines in this exception for YANG 1.0 in Section 3.6. The guidelines in this
section are intended to supplement the YANG specification, which is section are intended to supplement the YANG specification, which is
intended to define a minimum set of 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
skipping to change at page 19, line 13 skipping to change at page 19, line 13
a new module, not a name change. a new module, not a name change.
4.2. Prefixes 4.2. Prefixes
All YANG definitions are scoped by the module containing the All YANG definitions are scoped by the module containing the
definition being referenced. This allows definitions from multiple definition being referenced. This allows definitions from multiple
modules to be used, even if the names are not unique. In the example modules to be used, even if the names are not unique. In the example
below, the identifier "foo" is used in all 3 modules: below, the identifier "foo" is used in all 3 modules:
module example-foo { module example-foo {
namespace "http://example.com/ns/foo"; namespace "tag:example.com,2017:example-foo";
prefix f; prefix f;
container foo; container foo;
} }
module example-bar { module example-bar {
namespace "http://example.com/ns/bar"; namespace "tag:example.com,2017:example-bar";
prefix b; prefix b;
typedef foo { type uint32; } typedef foo { type uint32; }
} }
module example-one { module example-one {
namespace "http://example.com/ns/one"; namespace "tag:example.com,2017:example-one";
prefix one; prefix one;
import example-foo { prefix f; } import example-foo { prefix f; }
import example-bar { prefix b; } import example-bar { prefix b; }
augment "/f:foo" { augment "/f:foo" {
leaf foo { type b:foo; } leaf foo { type b:foo; }
} }
} }
YANG defines the following rules for prefix usage: YANG defines the following rules for prefix usage:
o Prefixes are never allowed for built in data types and YANG o Prefixes are never used for built in data types and YANG keywords.
keywords.
o A prefix MUST be used for any external statement (i.e., a o A prefix MUST be used for any external statement (i.e., a
statement defined with the YANG "extension" statement) statement defined with the YANG "extension" statement)
o The proper module prefix MUST be used for all identifiers imported o The proper module prefix MUST be used for all identifiers imported
from other modules from other modules
o The proper module prefix MUST be used for all identifiers included o The proper module prefix MUST be used for all identifiers included
from a submodule. from a submodule.
skipping to change at page 20, line 31 skipping to change at page 20, line 31
Identifiers for all YANG identifiers in published modules MUST be Identifiers for all YANG identifiers in published modules MUST be
between 1 and 64 characters in length. These include any construct between 1 and 64 characters in length. These include any construct
specified as an 'identifier-arg-str' token in the ABNF in Section 13 specified as an 'identifier-arg-str' token in the ABNF in Section 13
of [RFC7950]. of [RFC7950].
4.3.1. Identifier Naming Conventions 4.3.1. Identifier Naming Conventions
Identifiers SHOULD follow a consistent naming pattern throughout the Identifiers SHOULD follow a consistent naming pattern throughout the
module. Only lower-case letters, numbers, and dashes SHOULD be used module. Only lower-case letters, numbers, and dashes SHOULD be used
in identifier names. Upper-case characters and the underscore in identifier names. Upper-case characters, the period character,
character MAY be used if the identifier represents a well-known value and the underscore character MAY be used if the identifier represents
that uses these characters. a well-known value that uses these characters. YANG does not permit
any other characters in YANG identifiers.
Identifiers SHOULD include complete words and/or well-known acronyms Identifiers SHOULD include complete words and/or well-known acronyms
or abbreviations. Child nodes within a container or list SHOULD NOT or abbreviations. Child nodes within a container or list SHOULD NOT
replicate the parent identifier. YANG identifiers are hierarchical replicate the parent identifier. YANG identifiers are hierarchical
and are only meant to be unique within the the set of sibling nodes and are only meant to be unique within the the set of sibling nodes
defined in the same module namespace. defined in the same module namespace.
It is permissible to use common identifiers such as "name" or "id" in It is permissible to use common identifiers such as "name" or "id" in
data definition statements, especially if these data nodes share a data definition statements, especially if these data nodes share a
common data type. common data type.
skipping to change at page 28, line 27 skipping to change at page 28, line 27
as defined in [RFC3986]. This value is usually assigned by the IANA. as defined in [RFC3986]. This value is usually assigned by the IANA.
The organization statement MUST be present. If the module is The organization statement MUST be present. If the module is
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 SHOULD 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. There is no need to include the contact information for present. There is no need to include the contact information for
Working Group chairs. 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,
skipping to change at page 28, line 50 skipping to change at page 28, line 50
reference statement. reference statement.
A revision statement MUST be present for each published version of A revision statement MUST be present for each published version of
the module. The revision statement MUST have a reference the module. The revision statement MUST have a reference
substatement. It MUST identify the published document that contains substatement. It MUST identify the published document that contains
the module. Modules are often extracted from their original the module. Modules are often extracted from their original
documents, and it is useful for developers and operators to know how documents, and it is useful for developers and operators to know how
to find the original source document in a consistent manner. The to find the original source document in a consistent manner. The
revision statement MAY have a description substatement. revision statement MAY have a description substatement.
It is not required to keep the full revision history of draft The following example shows the revision statement for a published
versions (e.g., modules contained within Internet-Drafts). That is, YANG module:
within a sequence of draft versions, only the most recent revision
need be recorded in the module. However, whenever a new (i.e. revision "2012-02-22" {
changed) version is made available (e.g., via a new version of an description
Internet-Draft), the revision date of that new version MUST be "Initial version";
updated to a date later than that of the previous version. reference
"RFC 6536: Network Configuration Protocol (NETCONF)
Access Control Model";
}
For an unpublished module, a complete history of each unpublished
module revision is not required. That is, within a sequence of draft
versions, only the most recent revision need be recorded in the
module. Do not remove or reuse a revision statement for a published
module. A new revision date is not required unless the module
contents have changed. If the module contents have changed, then the
revision date of that new module version MUST be updated to a date
later than that of the previous version.
The following example shows the two revision statements for an
unpublished update to a published YANG module:
revision "2017-12-11" {
description
"Added support for YANG 1.1 actions and notifications tied to
data nodes. Clarify how NACM extensions can be used by other
data models.";
reference
"RFC XXXX: Network Configuration Protocol (NETCONF)
Access Control Model";
}
revision "2012-02-22" {
description
"Initial version";
reference
"RFC 6536: Network Configuration Protocol (NETCONF)
Access Control Model";
}
4.9. Namespace Assignments 4.9. Namespace Assignments
It is RECOMMENDED that only valid YANG modules be included in It is RECOMMENDED that only valid YANG modules be included in
documents, whether or not they are published yet. This allows: documents, whether or not the modules are published yet. This
allows:
o the module to compile correctly instead of generating disruptive o the module to compile correctly instead of generating disruptive
fatal errors. fatal errors.
o early implementors to use the modules without picking a random o early implementors to use the modules without picking a random
value for the XML namespace. value for the XML namespace.
o early interoperability testing since independent implementations o early interoperability testing since independent implementations
will use the same XML namespace value. will use the same XML namespace value.
skipping to change at page 30, line 5 skipping to change at page 30, line 41
urn:ietf:params:xml:ns:yang:ietf-netconf-state urn:ietf:params:xml:ns:yang:ietf-netconf-state
urn:ietf:params:xml:ns:yang:ietf-netconf urn:ietf:params:xml:ns:yang:ietf-netconf
Note that a different URN prefix string SHOULD be used for non- Note that a different URN prefix string SHOULD be used for non-
Standards-Track modules. The string SHOULD be selected according to Standards-Track modules. The string SHOULD be selected according to
the guidelines in [RFC7950]. the guidelines in [RFC7950].
The following URIs exemplify what might be used by non Standards The following URIs exemplify what might be used by non Standards
Track modules. Note that the domain "example.com" SHOULD be used by Track modules. Note that the domain "example.com" SHOULD be used by
example modules in IETF drafts. example modules in IETF drafts. These URIs are not intended to be
de-referenced. They are used for module namespace identification
only.
Example URIs using URLs per RFC 3986 [RFC3986]: Example URIs using URLs per RFC 3986 [RFC3986]:
http://example.com/ns/example-interfaces https://example.com/ns/example-interfaces
http://example.com/ns/example-system https://example.com/ns/example-system
Example URIs using tags per RFC 4151 [RFC4151]: Example URIs using tags per RFC 4151 [RFC4151]:
tag:example.com,2017:example-interfaces tag:example.com,2017:example-interfaces
tag:example.com,2017:example-system tag:example.com,2017:example-system
4.10. Top-Level Data Definitions 4.10. Top-Level Data Definitions
The top-level data organization SHOULD be considered carefully, in The top-level data organization SHOULD be considered carefully, in
skipping to change at page 32, line 12 skipping to change at page 32, line 48
Note that any module can declare an identity with base "foo-type" Note that any module can declare an identity with base "foo-type"
that is valid for the "foo" leaf. Identityref values are considered that is valid for the "foo" leaf. Identityref values are considered
to be qualified names. to be qualified names.
4.11.2. Patterns and Ranges 4.11.2. Patterns and Ranges
For string data types, if a machine-readable pattern can be defined For string data types, if a machine-readable pattern can be defined
for the desired semantics, then one or more pattern statements SHOULD for the desired semantics, then one or more pattern statements SHOULD
be present. A single quoted string SHOULD be used to specify the be present. A single quoted string SHOULD be used to specify the
pattern, since a double-quoted string can modify the content. pattern, since a double-quoted string can modify the content. If the
patterns used in a type definition have known limitations such as
false negative or false positive matches, then these limitations
SHOULD be documented within the typedef or data definition.
The following typedef from [RFC6991] demonstrates the proper use of The following typedef from [RFC6991] demonstrates the proper use of
the "pattern" statement: the "pattern" statement:
typedef ipv4-address-no-zone { typedef ipv4-address-no-zone {
type inet:ipv4-address { type inet:ipv4-address {
pattern '[0-9\.]*'; pattern '[0-9\.]*';
} }
... ...
} }
skipping to change at page 39, line 4 skipping to change at page 39, line 41
container bars { container bars {
list bar { ... } list bar { ... }
} }
} }
Example without container wrappers: Example without container wrappers:
container top { container top {
list foo { ... } list foo { ... }
list bar { ... } list bar { ... }
} }
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. Although
NETCONF and RESTCONF protocols do not currently support the ability these containers do not have any semantics, they can impact protocol
to delete all list (or leaf-list) entries at once. This deficiency operations for the descendant data nodes within a non-presence
is sometimes avoided by use of a parent container (i.e., deleting the container, so use of these containers SHOULD be considered carefully.
container also removes all child entries).
The NETCONF and RESTCONF protocols do not currently support the
ability 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 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 are not ordered
o top-level siblings not are not static, and depends on the modules o top-level siblings not are not static, and depends on the modules
that are loaded that are loaded
skipping to change at page 43, line 17 skipping to change at page 44, line 13
of target data node because the client does not have any control over of target data node because the client does not have any control over
this external data. this external data.
In the following dummy example, it is OK to augment the "interface" In the following dummy example, it is OK to augment the "interface"
entry with "mandatory-leaf" because the augmentation depends on entry with "mandatory-leaf" because the augmentation depends on
support for "some-new-iftype". The old client does not know about support for "some-new-iftype". The old client does not know about
this type so it would never select this type, and therefore not be this type so it would never select this type, and therefore not be
adding a mandatory data node. adding a mandatory data node.
module example-module { module example-module {
namespace "http://example.com/ns/example-module"; namespace "tag:example.com,2017:example-module";
prefix mymod; prefix mymod;
import iana-if-type { prefix iana; } import iana-if-type { prefix iana; }
import ietf-interfaces { prefix if; } import ietf-interfaces { prefix if; }
identity some-new-iftype { identity some-new-iftype {
base iana:iana-interface-type; base iana:iana-interface-type;
} }
augment "/if:interfaces/if:interface" { augment "/if:interfaces/if:interface" {
skipping to change at page 44, line 7 skipping to change at page 44, line 48
In the example above, the "some-new-iftype" identity is defined in In the example above, the "some-new-iftype" identity is defined in
the same module as the "mandatory-leaf" data definition statement. the same module as the "mandatory-leaf" data definition statement.
This practice is not safe for identities defined in a common module This practice is not safe for identities defined in a common module
such as "iana-if-type" because the client is not required to know such as "iana-if-type" because the client is not required to know
about "my-module" just because it knows about the "iana-if-type" about "my-module" just because it knows about the "iana-if-type"
module. module.
4.20. Deviation Statements 4.20. Deviation Statements
The YANG "deviation" statement cannot appear in IETF YANG modules, Per RFC 7950, 7.20.3, the YANG "deviation" statement is not allowed
but it can be useful for documenting server capabilities. Deviation to appear in IETF YANG modules, but it can be useful for documenting
statements are not reusable and typically not shared across all server capabilities. Deviation statements are not reusable and
platforms. typically not shared across all platforms.
There are several reasons that deviations might be needed in an There are several reasons that deviations might be needed in an
implementation, e.g., an object cannot be supported on all platforms, implementation, e.g., an object cannot be supported on all platforms,
or feature delivery is done in multiple development phases. or feature delivery is done in multiple development phases.
Deviation statements can also be used to add annotations to a module, Deviation statements can also be used to add annotations to a module,
which does not affect the conformance requirements for the module. which does not affect the conformance requirements for the module.
It is suggested that deviation statements be defined in separate It is suggested that deviation statements be defined in separate
modules from regular YANG definitions. This allows the deviations to modules from regular YANG definitions. This allows the deviations to
be platform-specific and/or temporary. be platform-specific and/or temporary.
skipping to change at page 53, line 22 skipping to change at page 54, line 22
o "identityref" leafs are generally more expensive than o "identityref" leafs are generally more expensive than
"enumeration" leafs "enumeration" leafs
o "leafref" and "instance-identifier" types with "require-instance" o "leafref" and "instance-identifier" types with "require-instance"
set to true are generally more expensive than if set to true are generally more expensive than if
"require-instance" is set to false "require-instance" is set to false
4.25. Open Systems Considerations 4.25. Open Systems Considerations
A YANG module MUST NOT be designed such that the set of modules found Only the modules imported by a particular module can be assumed to be
on a server implementation can be predetermined in advance. Only the present in an implementation. An open system MAY include any
modules imported by a particular module can be assumed to be present combination of YANG modules.
in an implementation. An open system MAY include any combination of
YANG modules.
4.26. Guidelines for YANG 1.1 Specific Constructs 4.26. Guidelines for YANG 1.1 Specific Constructs
The set of YANG 1.1 guidelines will grow as operational experience is The set of YANG 1.1 guidelines will grow as operational experience is
gained with the new language features. This section contains an gained with the new language features. This section contains an
initial set of guidelines for new YANG 1.1 language features. initial set of guidelines for new YANG 1.1 language features.
4.26.1. Importing Multiple Revisions 4.26.1. Importing Multiple Revisions
Standard modules SHOULD NOT import multiple revisions of the same Standard modules SHOULD NOT import multiple revisions of the same
skipping to change at page 54, line 31 skipping to change at page 55, line 29
protocol operation is specific to a subset of all data nodes instead protocol operation is specific to a subset of all data nodes instead
of all possible data nodes. of all possible data nodes.
The same action name MAY be used in different definitions within The same action name MAY be used in different definitions within
different data node. For example, a "reset" action defined with a different data node. For example, a "reset" action defined with a
data node definition for an interface might have different parameters data node definition for an interface might have different parameters
than for a power supply or a VLAN. The same action name SHOULD be than for a power supply or a VLAN. The same action name SHOULD be
used to represent similar semantics. used to represent similar semantics.
The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis] The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis]
does not support parameter access control for RPC operations. The does not support parameter-based access control for RPC operations.
user is given permission (or not) to invoke the RPC operation with The user is given permission (or not) to invoke the RPC operation
any parameters. For example, if each client is only allowed to reset with any parameters. For example, if each client is only allowed to
their own interface, then NACM cannot be used. reset their own interface, then NACM cannot be used.
For example, NACM cannot enforce access access control based on the For example, NACM cannot enforce access access control based on the
value of the "interface" parameter, only the "reset" operation value of the "interface" parameter, only the "reset" operation
itself: itself:
rpc reset { rpc reset {
input { input {
leaf interface { leaf interface {
type if:interface-ref; type if:interface-ref;
mandatory true; mandatory true;
skipping to change at page 59, line 9 skipping to change at page 60, line 9
[RFC4181], guidelines for MIB Documents, by C. M. Heard. [RFC4181], guidelines for MIB Documents, by C. M. Heard.
The working group thanks Martin Bjorklund, Juergen Schoenwaelder, The working group thanks Martin Bjorklund, Juergen Schoenwaelder,
Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive
reviews and contributions to this document. reviews and contributions to this document.
8. References 8. References
8.1. Normative References 8.1. Normative References
[I-D.ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-10
(work in progress), January 2018.
[ID-Guidelines]
Housley, R., Ed., "Guidelines to Authors of Internet-
Drafts", December 2010,
<https://www.ietf.org/standards/ids/guidelines/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004. January 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
skipping to change at page 59, line 47 skipping to change at page 61, line 9
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[W3C.REC-xpath-19991116] [W3C.REC-xpath-19991116]
Clark, J. and S. DeRose, "XML Path Language (XPath) Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999, Recommendation REC-xpath-19991116, November 1999,
<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.flanagan-7322bis]
Flanagan, H. and R. Editor, "RFC Style Guide",
draft-flanagan-7322bis-02 (work in progress),
September 2017.
[I-D.ietf-netconf-rfc6536bis] [I-D.ietf-netconf-rfc6536bis]
Bierman, A. and M. Bjorklund, "Network Configuration Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Module", draft-ietf-netconf-rfc6536bis-09 Access Control Module", draft-ietf-netconf-rfc6536bis-09
(work in progress), December 2017. (work in progress), December 2017.
[I-D.ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-10
(work in progress), January 2018.
[I-D.ietf-netmod-rfc7223bis] [I-D.ietf-netmod-rfc7223bis]
Bjorklund, M., "A YANG Data Model for Interface Bjorklund, M., "A YANG Data Model for Interface
Management", draft-ietf-netmod-rfc7223bis-03 (work in Management", draft-ietf-netmod-rfc7223bis-03 (work in
progress), January 2018. progress), January 2018.
[I-D.ietf-netmod-rfc8022bis] [I-D.ietf-netmod-rfc8022bis]
Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for
Routing Management (NMDA Version)", Routing Management (NMDA Version)",
draft-ietf-netmod-rfc8022bis-11 (work in progress), draft-ietf-netmod-rfc8022bis-11 (work in progress),
January 2018. 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-06 (work in draft-ietf-netmod-yang-tree-diagrams-06 (work in
progress), February 2018. progress), February 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/styleguide/>.
[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>.
[RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme",
RFC 4151, DOI 10.17487/RFC4151, October 2005, RFC 4151, DOI 10.17487/RFC4151, October 2005,
<http://www.rfc-editor.org/info/rfc4151>. <http://www.rfc-editor.org/info/rfc4151>.
[RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB [RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB
skipping to change at page 62, line 9 skipping to change at page 63, line 9
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
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. v17 to v18 A.1. v18 to v19
o address IESG ballot comments
A.2. v17 to v18
o address Area Director review comments Part 2 o address Area Director review comments Part 2
o clarify preferred list key order o clarify preferred list key order
A.2. v16 to v17 A.3. v16 to v17
o address Area Director review comments Part 1 o address Area Director review comments Part 1
A.3. v15 to v16 A.4. v15 to v16
o address Area Director review comments posted 2018-01-25 o address Area Director review comments posted 2018-01-25
A.4. v15 to v16 A.5. 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.5. v14 to v15 A.6. 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.6. v13 to v14 A.7. 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.7. v12 to v13 A.8. 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.8. v11 to v12 A.9. v11 to v12
o fix incorrect location of new Module Usage Examples section o fix incorrect location of new Module Usage Examples section
A.9. v10 to v11 A.10. 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.10. v09 to v10 A.11. 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.11. v08 to v09 A.12. 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.12. v07 to v08 A.13. 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
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.13. v06 to v07 A.14. 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.14. v05 to v06 A.15. 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
skipping to change at page 64, line 50 skipping to change at page 66, line 4
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.15. v04 to v05 A.16. 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 65, line 32 skipping to change at page 66, line 34
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.16. v03 ot v04 A.17. 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.17. v02 to v03 A.18. 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.18. v01 to v02 A.19. v01 to v02
o Updated draft based on mailing list comments. o Updated draft based on mailing list comments.
A.19. v00 to v01 A.20. 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
skipping to change at page 67, line 16 skipping to change at page 68, line 16
This section is adapted from RFC 4181. This section is adapted from RFC 4181.
The purpose of a YANG module review is to review the YANG module both The purpose of a YANG module review is to review the YANG module both
for technical correctness and for adherence to IETF documentation for technical correctness and for adherence to IETF documentation
requirements. The following checklist may be helpful when reviewing requirements. The following checklist may be helpful when reviewing
an Internet-Draft: an Internet-Draft:
o I-D Boilerplate -- verify that the draft contains the required o I-D Boilerplate -- verify that the draft contains the required
Internet-Draft boilerplate (see Internet-Draft boilerplate (see
http://www.ietf.org/id-info/guidelines.html), including the https://www.ietf.org/id-info/guidelines.html), including the
appropriate statement to permit publication as an RFC, and that appropriate statement to permit publication as an RFC, and that
I-D boilerplate does not contain references or section numbers. I-D boilerplate does not contain references or section numbers.
o Abstract -- verify that the abstract does not contain references, o Abstract -- verify that the abstract does not contain references,
that it does not have a section number, and that its content that it does not have a section number, and that its content
follows the guidelines in follows the guidelines in
http://www.ietf.org/id-info/guidelines.html. https://www.ietf.org/id-info/guidelines.html.
o Copyright Notice -- verify that the draft has the appropriate text o Copyright Notice -- verify that the draft has the appropriate text
regarding the rights that document contributers provide to the regarding the rights that document contributers provide to the
IETF Trust [RFC5378]. Verify that it contains the full IETF Trust IETF Trust [RFC5378]. Verify that it contains the full IETF Trust
copyright notice at the beginning of the document. The IETF Trust copyright notice at the beginning of the document. The IETF Trust
Legal Provisions (TLP) can be found at: Legal Provisions (TLP) can be found at:
http://trustee.ietf.org/license-info/ https://trustee.ietf.org/license-info/
o Security Considerations section -- verify that the draft uses the o Security Considerations section -- verify that the draft uses the
latest approved template from the OPS area website (http:// latest approved template from the OPS area website (https://
trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines) trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines)
and that the guidelines therein have been followed. and that the guidelines therein have been followed.
o IANA Considerations section -- this section must always be o IANA Considerations section -- this section must always be
present. For each module within the document, ensure that the present. For each module within the document, ensure that the
IANA Considerations section contains entries for the following IANA Considerations section contains entries for the following
IANA registries: IANA registries:
XML Namespace Registry: Register the YANG module namespace. XML Namespace Registry: Register the YANG module namespace.
skipping to change at page 68, line 28 skipping to change at page 69, line 28
Internet Draft (I-D), then the I-D is included as an Informative Internet Draft (I-D), then the I-D is included as an Informative
Reference. Reference.
o License -- verify that the draft contains the Simplified BSD o License -- verify that the draft contains the Simplified BSD
License in each YANG module or submodule. Some guidelines related License in each YANG module or submodule. Some guidelines related
to this requirement are described in Section 3.1. Make sure that to this requirement are described in Section 3.1. Make sure that
the correct year is used in all copyright dates. Use the approved the correct year is used in all copyright dates. Use the approved
text from the latest Trust Legal Provisions (TLP) document, which text from the latest Trust Legal Provisions (TLP) document, which
can be found at: can be found at:
http://trustee.ietf.org/license-info/ https://trustee.ietf.org/license-info/
o Other Issues -- check for any issues mentioned in o Other Issues -- check for any issues mentioned in
http://www.ietf.org/id-info/checklist.html that are not covered https://www.ietf.org/id-info/checklist.html that are not covered
elsewhere. elsewhere.
o Technical Content -- review the actual technical content for o Technical Content -- review the actual technical content for
compliance with the guidelines in this document. The use of a compliance with the guidelines in this document. The use of a
YANG module compiler is recommended when checking for syntax YANG module compiler is recommended when checking for syntax
errors. A list of freely available tools and other information errors. A list of freely available tools and other information
can be found at: can be found at:
http://trac.tools.ietf.org/wg/netconf/trac/wiki https://trac.tools.ietf.org/wg/netconf/trac/wiki
Checking for correct syntax, however, is only part of the job. Checking for correct syntax, however, is only part of the job.
It is just as important to actually read the YANG module document It is just as important to actually read the YANG module document
from the point of view of a potential implementor. It is from the point of view of a potential implementor. It is
particularly important to check that description statements are particularly important to check that description statements are
sufficiently clear and unambiguous to allow interoperable sufficiently clear and unambiguous to allow interoperable
implementations to be created. implementations to be created.
Appendix C. YANG Module Template Appendix C. YANG Module Template
 End of changes. 87 change blocks. 
201 lines changed or deleted 267 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/