Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8407 YumaWorks
BCP: 216 October 2018
Obsoletes: 6087
Category: Best Current Practice
ISSN: 2070-1721
Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8407 YumaWorks
BCP: 216 October 2018
Obsoletes: 6087
Category: Best Current Practice
ISSN: 2070-1721
Guidelines for Authors and Reviewers of Documents Containing YANG Data Models
包含YANG数据模型的文件的作者和审阅者指南
Abstract
摘要
This memo provides guidelines for authors and reviewers of specifications containing YANG modules. Recommendations and procedures are defined, which are intended to increase interoperability and usability of Network Configuration Protocol (NETCONF) and RESTCONF protocol implementations that utilize YANG modules. This document obsoletes RFC 6087.
本备忘录为包含模块的规范的作者和评审人员提供了指南。定义了建议和过程，旨在提高网络配置协议（NETCONF）和利用模块的RESTCONF协议实现的互操作性和可用性。本文件淘汰RFC 6087。
Status of This Memo
关于下段备忘
This memo documents an Internet Best Current Practice.
本备忘录记录了互联网最佳实践。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关BCP的更多信息，请参见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8407.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问https://www.rfc-editor.org/info/rfc8407.
Copyright Notice
版权公告
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2018 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(https://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Changes since RFC 6087 . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 7
2.2. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . 7
2.3. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . 7
2.4. Requirements Notation . . . . . . . . . . . . . . . . . . 8
3. General Documentation Guidelines . . . . . . . . . . . . . . 8
3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . 9
3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9
3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9
3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10
3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10
3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . 10
3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11
3.7. Security Considerations Section . . . . . . . . . . . . . 11
3.7.1. Security Considerations Section Template . . . . . . 12
3.8. IANA Considerations Section . . . . . . . . . . . . . . . 13
3.8.1. Documents That Create a New Namespace . . . . . . . . 14
3.8.2. Documents That Extend an Existing Namespace . . . . . 14
3.9. References Sections . . . . . . . . . . . . . . . . . . . 14
3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . 14
3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 15
3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 15
4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15
4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 16
4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 18
4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . 19
4.5. Conditional Statements . . . . . . . . . . . . . . . . . 19
4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 20
4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 20
4.6.2. Function Library . . . . . . . . . . . . . . . . . . 21
4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . 22
4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 23
4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 24
4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 24
4.7. YANG Definition Lifecycle Management . . . . . . . . . . 25
4.8. Module Header, Meta, and Revision Statements . . . . . . 26
4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 28
4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . 29
4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . 30
4.11.1. Fixed-Value Extensibility . . . . . . . . . . . . . 30
4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . 31
4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . 32
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Changes since RFC 6087 . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 7
2.2. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . 7
2.3. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . 7
2.4. Requirements Notation . . . . . . . . . . . . . . . . . . 8
3. General Documentation Guidelines . . . . . . . . . . . . . . 8
3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . 9
3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 9
3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9
3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 10
3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10
3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . 10
3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 11
3.7. Security Considerations Section . . . . . . . . . . . . . 11
3.7.1. Security Considerations Section Template . . . . . . 12
3.8. IANA Considerations Section . . . . . . . . . . . . . . . 13
3.8.1. Documents That Create a New Namespace . . . . . . . . 14
3.8.2. Documents That Extend an Existing Namespace . . . . . 14
3.9. References Sections . . . . . . . . . . . . . . . . . . . 14
3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . 14
3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 15
3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 15
4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 15
4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 16
4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 18
4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . 19
4.5. Conditional Statements . . . . . . . . . . . . . . . . . 19
4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 20
4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 20
4.6.2. Function Library . . . . . . . . . . . . . . . . . . 21
4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . 22
4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 23
4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 24
4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 24
4.7. YANG Definition Lifecycle Management . . . . . . . . . . 25
4.8. Module Header, Meta, and Revision Statements . . . . . . 26
4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 28
4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . 29
4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . 30
4.11.1. Fixed-Value Extensibility . . . . . . . . . . . . . 30
4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . 31
4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . 32
4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . 33
4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . 34
4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 35
4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . 35
4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . 36
4.14.1. Non-Presence Containers . . . . . . . . . . . . . . 38
4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . 38
4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 39
4.16. Notification Definitions . . . . . . . . . . . . . . . . 39
4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 40
4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . 41
4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . 41
4.18.2. "must" versus "when" . . . . . . . . . . . . . . . . 41
4.19. "augment" Statements . . . . . . . . . . . . . . . . . . 41
4.19.1. Conditional Augment Statements . . . . . . . . . . . 41
4.19.2. Conditionally Mandatory Data Definition Statements . 42
4.20. Deviation Statements . . . . . . . . . . . . . . . . . . 43
4.21. Extension Statements . . . . . . . . . . . . . . . . . . 44
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . 45
4.22.1. Use of "leafref" for Key Correlation . . . . . . . . 46
4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47
4.23.1. Combining Operational State and Configuration Data . 47
4.23.2. Representing Operational Values of Configuration
Data . . . . . . . . . . . . . . . . . . . . . . . . 47
4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . 48
4.24. Performance Considerations . . . . . . . . . . . . . . . 52
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 52
4.26. Guidelines for Constructs Specific to YANG 1.1 . . . . . 53
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . 53
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . 53
4.26.3. "anyxml" versus "anydata" . . . . . . . . . . . . . 53
4.26.4. "action" versus "rpc" . . . . . . . . . . . . . . . 53
4.27. Updating YANG Modules (Published versus Unpublished) . . 54
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
6. Security Considerations . . . . . . . . . . . . . . . . . . . 55
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.1. Normative References . . . . . . . . . . . . . . . . . . 56
7.2. Informative References . . . . . . . . . . . . . . . . . 57
Appendix A. Module Review Checklist . . . . . . . . . . . . . . 59
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 61
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 62
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 63
4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . 33
4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . 34
4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 35
4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . 35
4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . 36
4.14.1. Non-Presence Containers . . . . . . . . . . . . . . 38
4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . 38
4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 39
4.16. Notification Definitions . . . . . . . . . . . . . . . . 39
4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 40
4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . 41
4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . 41
4.18.2. "must" versus "when" . . . . . . . . . . . . . . . . 41
4.19. "augment" Statements . . . . . . . . . . . . . . . . . . 41
4.19.1. Conditional Augment Statements . . . . . . . . . . . 41
4.19.2. Conditionally Mandatory Data Definition Statements . 42
4.20. Deviation Statements . . . . . . . . . . . . . . . . . . 43
4.21. Extension Statements . . . . . . . . . . . . . . . . . . 44
4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . 45
4.22.1. Use of "leafref" for Key Correlation . . . . . . . . 46
4.23. Operational State . . . . . . . . . . . . . . . . . . . . 47
4.23.1. Combining Operational State and Configuration Data . 47
4.23.2. Representing Operational Values of Configuration
Data . . . . . . . . . . . . . . . . . . . . . . . . 47
4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . 48
4.24. Performance Considerations . . . . . . . . . . . . . . . 52
4.25. Open Systems Considerations . . . . . . . . . . . . . . . 52
4.26. Guidelines for Constructs Specific to YANG 1.1 . . . . . 53
4.26.1. Importing Multiple Revisions . . . . . . . . . . . . 53
4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . 53
4.26.3. "anyxml" versus "anydata" . . . . . . . . . . . . . 53
4.26.4. "action" versus "rpc" . . . . . . . . . . . . . . . 53
4.27. Updating YANG Modules (Published versus Unpublished) . . 54
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
6. Security Considerations . . . . . . . . . . . . . . . . . . . 55
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.1. Normative References . . . . . . . . . . . . . . . . . . 56
7.2. Informative References . . . . . . . . . . . . . . . . . 57
Appendix A. Module Review Checklist . . . . . . . . . . . . . . 59
Appendix B. YANG Module Template . . . . . . . . . . . . . . . . 61
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 62
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 63
The standardization of network configuration interfaces for use with network configuration management protocols, such as the Network Configuration Protocol [RFC6241] and the RESTCONF protocol [RFC8040], requires a modular set of data models that can be reused and extended over time.
与网络配置管理协议（如网络配置协议[RFC6241]和RESTCONF协议[RFC8040]）一起使用的网络配置接口的标准化需要一组模块化的数据模型，这些数据模型可以随着时间的推移进行重用和扩展。
This document defines a set of usage guidelines for documents containing YANG 1.1 [RFC7950] and YANG 1.0 [RFC6020] data models. YANG is used to define the data structures, protocol operations, and notification content used within a NETCONF and/or RESTCONF server. A NETCONF or RESTCONF server that supports a particular YANG module will support client NETCONF and/or RESTCONF operation requests, as indicated by the specific content defined in the YANG module.
本文档为包含YANG 1.1[RFC7950]和YANG 1.0[RFC6020]数据模型的文档定义了一套使用指南。YANG用于定义NETCONF和/或RESTCONF服务器中使用的数据结构、协议操作和通知内容。支持特定YANG模块的NETCONF或RESTCONF服务器将支持客户端NETCONF和/或RESTCONF操作请求，如YANG模块中定义的特定内容所示。
Many YANG constructs are defined as optional to use, such as the "description" statement. However, in order to make YANG modules more useful, it is desirable to define a set of usage guidelines that entails a higher level of compliance than the minimum level defined in the YANG specification [RFC7950].
许多构造被定义为可选的，例如“description”语句。然而，为了使YANG模块更有用，需要定义一组使用指南，该指南需要比YANG规范[RFC7950]中定义的最低级别更高的合规性。
In addition, YANG allows constructs such as infinite length identifiers and string values, or top-level mandatory nodes, that a compliant server is not required to support. Only constructs that all servers are required to support can be used in IETF YANG modules.
此外，YANG还允许构建，如无限长标识符和字符串值，或顶级强制节点，而兼容服务器不需要支持这些构造。IETF模块中只能使用所有服务器都需要支持的结构。
This document defines usage guidelines related to the NETCONF operations layer and NETCONF content layer, as defined in [RFC6241], and the RESTCONF methods and RESTCONF resources, as defined in [RFC8040].
本文档定义了与[RFC6241]中定义的NETCONF操作层和NETCONF内容层以及[RFC8040]中定义的RESTCONF方法和RESTCONF资源相关的使用指南。
These guidelines are intended to be used by authors and reviewers to improve the readability and interoperability of published YANG data models.
这些指南旨在供作者和评审人员使用，以提高已发布数据模型的可读性和互操作性。
Note that this document is not a YANG tutorial, and the reader is expected to know the YANG data modeling language before implementing the guidance in this document.
请注意，本文档不是YANG教程，在实现本文档中的指南之前，读者应了解YANG数据建模语言。
The following changes have been made to the guidelines published in [RFC6087]:
对[RFC6087]中发布的指南进行了以下更改：
o Updated NETCONF reference from RFC 4741 to RFC 6241
o 将NETCONF参考从RFC 4741更新为RFC 6241
o Updated NETCONF over the Secure Shell (SSH) citation from RFC 4742 to RFC 6242
o 通过安全外壳（SSH）引用将NETCONF从RFC 4742更新为RFC 6242
o Updated YANG Types reference from RFC 6021 to RFC 6991
o 将杨氏类型参考从RFC 6021更新为RFC 6991
o Updated obsolete URLs for IETF resources
o 更新了IETF资源的过时URL
o Changed top-level data node guideline
o 更改了顶级数据节点指南
o Clarified XML Path Language (XPath) usage for a literal value representing a YANG identity
o 阐明了XML路径语言（XPath）对表示标识的文本值的用法
o Clarified XPath usage for a when-stmt
o 阐明了when stmt的XPath用法
o Clarified XPath usage for "preceding-sibling" and "following-sibling" axes
o 阐明了“前同级”和“后同级”轴的XPath用法
o Added terminology guidelines
o 增加了术语指南
o Added mention of RFC 8174, which updates RFC 2119 by clarifying the use of capitalized key words
o 增加了对RFC 8174的提及，它通过澄清大写关键字的使用更新了RFC 2119
o Added YANG tree diagram guidelines
o 增加了杨树图指南
o Updated XPath guidelines for type conversions and function library usage
o 更新了类型转换和函数库使用的XPath指南
o Updated "Data Types" section
o 更新了“数据类型”部分
o Updated "Notification Definitions" section
o 更新了“通知定义”部分
o Clarified conditional key leaf nodes
o 澄清条件键叶节点
o Clarified usage of "uint64" and "int64" data types
o 阐明了“uint64”和“int64”数据类型的用法
o Added text on YANG feature usage
o 添加了有关功能用法的文本
o Added "Identifier Naming Conventions" section
o 增加了“标识符命名约定”部分
o Clarified use of mandatory nodes with conditional augmentations
o 阐明了带条件扩充的强制节点的使用
o Clarified namespace and domain conventions for example modules
o 澄清了示例模块的命名空间和域约定
o Clarified conventions for identifying code components
o 阐明了识别代码组件的约定
o Added YANG 1.1 guidelines
o 增加了1.1指南
o Added "YANG Data Node Constraints" section
o 增加了“数据节点约束”部分
o Added mention of the RESTCONF protocol
o 增加了对RESTCONF协议的提及
o Added guidelines for datastores revised by the Network Management Datastore Architecture (NMDA)
o 增加了由网络管理数据存储体系结构（NMDA）修订的数据存储指南
The following terms are used throughout this document:
本文件中使用了以下术语：
o published: A stable release of a module or submodule. For example, the "Request for Comments" described in Section 2.1 of [RFC2026] is considered a stable publication.
o 已发布：模块或子模块的稳定版本。例如，[RFC2026]第2.1节所述的“征求意见”被视为稳定的出版物。
o unpublished: An unstable release of a module or submodule. For example the "Internet-Draft" described in Section 2.2 of [RFC2026] is considered an unstable publication that is a work in progress, subject to change at any time.
o 未发布：模块或子模块的不稳定版本。例如，[RFC2026]第2.2节中所述的“互联网草案”被视为不稳定的出版物，是正在进行的工作，随时可能更改。
o YANG fragment: A set of YANG statements that are not intended to represent a complete YANG module or submodule. These statements are not intended for actual use, except to provide an example of YANG statement usage. The invalid syntax "..." is sometimes used to indicate that additional YANG statements would be present in a real YANG module.
o YANG片段：一组YANG语句，不表示完整的YANG模块或子模块。这些语句不是为了实际使用，只是为了提供一个YANG语句用法的示例。无效语法“…”有时用于表示在真实的YANG模块中会出现其他YANG语句。
o YANG tree diagram: A diagram representing the contents of a YANG module, as defined in [RFC8340]. It is also called a "tree diagram".
o 阳树图：表示阳模块内容的图，如[RFC8340]中所定义。它也被称为“树形图”。
The following terms are defined in [RFC6241] and are not redefined here:
[RFC6241]中定义了以下术语，此处未重新定义：
o capabilities
o 能力
o client
o 客户
o operation
o 活动
o server
o 服务器
The following terms are defined in [RFC7950] and are not redefined here:
[RFC7950]中定义了以下术语，此处未重新定义：
o data node
o 数据节点
o module
o 单元
o namespace
o 名称空间
o submodule
o 子模块
o version
o 版本
o YANG
o 杨
o YIN
o 尹
Note that the term 'module' may be used as a generic term for a YANG module or submodule. When describing properties that are specific to submodules, the term 'submodule' is used instead.
注意，术语“模块”可用作YANG模块或子模块的通用术语。在描述特定于子模块的属性时，使用术语“子模块”。
The following terms are defined in [RFC8342] and are not redefined here:
[RFC8342]中定义了以下术语，此处未重新定义：
o configuration
o 配置
o conventional configuration datastore
o 常规配置数据存储
o datastore
o 数据存储
o operational state
o 运行状态
o operational state datastore
o 操作状态数据存储
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可”和“可选”在所有大写字母出现时（如图所示）应按照BCP 14[RFC2119][RFC8174]所述进行解释。
YANG modules under review are likely to be contained in Internet-Drafts (I-Ds). All guidelines for I-D authors [ID-Guidelines] MUST be followed. The guidelines for RFCs should be followed and are defined in the following: [RFC7322] (and any future RFCs that obsolete it), [RFC-STYLE], and [RFC7841].
正在审查的模块可能包含在互联网草案（I-D）中。必须遵守身份证作者的所有指南[身份证指南]。应遵循RFC指南，并在以下内容中定义：[RFC7322]（以及任何未来淘汰它的RFC）、[RFC-STYLE]和[RFC7841]。
The following sections MUST be present in an I-D containing a module:
包含模块的I-D中必须包含以下部分：
o Narrative sections
o 叙述部分
o Definition sections
o 定义部分
o Security Considerations section
o 安全考虑科
o IANA Considerations section
o IANA考虑事项组
o References section
o 参考资料部分
There are three usage scenarios for YANG that can appear in an I-D or RFC:
I-D或RFC中可能出现三种YANG的使用场景：
o normative module or submodule
o 规范模或子模
o example module or submodule
o 示例模块或子模块
o example YANG fragment not part of any module or submodule
o 示例1不属于任何模块或子模块的一部分
The guidelines in this document refer mainly to a normative module or submodule but may be applicable to example modules and YANG fragments as well.
本文件中的指南主要涉及规范性模块或子模块，但也可能适用于示例模块和子模块。
The module "description" statement MUST contain a reference to the latest approved IETF Trust Copyright statement, which is available online at:
模块“说明”声明必须包含对最新批准的IETF信托版权声明的引用，该声明可在线访问：
<https://trustee.ietf.org/license-info/>
<https://trustee.ietf.org/license-info/>
Each normative YANG module or submodule contained within an I-D or RFC is considered to be a code component. The strings "<CODE BEGINS>" and "<CODE ENDS>" MUST be used to identify each code component.
I-D或RFC中包含的每个模块或子模块都被视为代码组件。字符串“<CODE BEGINS>”和“<CODE ENDS>”必须用于标识每个代码组件。
The "<CODE BEGINS>" tag SHOULD be followed by a string identifying the file name specified in Section 5.2 of [RFC7950]. The name string form that includes the revision date SHOULD be used. The revision date MUST match the date used in the most recent revision of the module.
“<CODE BEGINS>”标记后面应该跟一个字符串，用于标识[RFC7950]第5.2节中指定的文件名。应使用包含修订日期的名称字符串表单。修订日期必须与模块最新版本中使用的日期匹配。
The following example is for the "2016-03-20" revision of the "ietf-foo" module:
以下示例适用于“ietf foo”模块的“2016-03-20”版本：
<CODE BEGINS> file "ietf-foo@2016-03-20.yang"
<CODE BEGINS> file "ietf-foo@2016-03-20.yang"
module ietf-foo {
namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
prefix "foo";
organization "...";
contact "...";
description "...";
revision 2016-03-20 {
description "Latest revision";
reference "RFC XXXX: Foo Protocol";
}
// ... more statements
}
module ietf-foo {
namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
prefix "foo";
organization "...";
contact "...";
description "...";
revision 2016-03-20 {
description "Latest revision";
reference "RFC XXXX: Foo Protocol";
}
// ... more statements
}
<CODE ENDS>
<代码结束>
Example modules are not code components. The <CODE BEGINS> convention MUST NOT be used for example modules.
示例模块不是代码组件。<CODE BEGINS>约定不得用于示例模块。
An example module SHOULD be named using the term "example", followed by a hyphen, followed by a descriptive name, e.g., "example-toaster".
示例模块应使用术语“示例”命名，后跟连字符，后跟描述性名称，例如“示例烤面包机”。
See Section 4.9 regarding the namespace guidelines for example modules.
有关示例模块的命名空间指南，请参见第4.9节。
A terminology section MUST be present if any terms are defined in the document or if any terms are imported from other documents.
如果文件中定义了任何术语或从其他文件中导入了任何术语，则必须提供术语部分。
YANG tree diagrams provide a concise representation of a YANG module and SHOULD be included to help readers understand YANG module structure. Guidelines on tree diagrams can be found in Section 3 of [RFC8340].
阳树图提供了阳模块的简明表示，应包括在内，以帮助读者理解阳模块结构。有关树形图的指南，请参见[RFC8340]的第3节。
If YANG tree diagrams are used, then an informative reference to the YANG tree diagrams specification MUST be included in the document. Refer to Section 2.2 of [RFC8349] for an example of such a reference.
如果使用杨树图，则必须在文件中包含杨树图规范的参考资料。参考[RFC8349]第2.2节了解此类参考的示例。
The narrative part MUST include an overview section that describes the scope and field of application of the module(s) defined by the specification and that specifies the relationship (if any) of these modules to other standards, particularly to standards containing other YANG modules. The narrative part SHOULD include one or more sections to briefly describe the structure of the modules defined in the specification.
叙述部分必须包括一个概述部分，描述规范中定义的模块的范围和应用领域，并规定这些模块与其他标准的关系（如有），特别是与包含其他模块的标准的关系。叙述部分应包括一个或多个章节，简要描述规范中定义的模块结构。
If the module or modules defined by the specification imports definitions from other modules (except for those defined in [RFC7950] or [RFC6991]) or are always implemented in conjunction with other modules, then those facts MUST be noted in the overview section; any special interpretations of definitions in other modules MUST be noted as well. Refer to Section 2.3 of [RFC8349] for an example of this overview section.
如果规范中定义的一个或多个模块从其他模块（除[RFC7950]或[RFC6991]中定义的模块外）导入定义，或始终与其他模块一起实现，则必须在概述部分中注明这些事实；其他模块中定义的任何特殊解释也必须注意。参考[RFC8349]第2.3节，了解本概述部分的示例。
If the document contains a YANG module(s) that is compliant with NMDA [RFC8342], then the Introduction section should mention this fact.
如果文件中包含符合NMDA[RFC8342]的YANG模块，则介绍部分应提及这一事实。
Example:
例子：
The YANG data model in this document conforms to the Network Management Datastore Architecture defined in RFC 8342.
本文件中的YANG数据模型符合RFC 8342中定义的网络管理数据存储体系结构。
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:
所有示例都应使用一致的缩进，包括YANG片段和协议消息实例数据。如果换行是为了格式化，则应注意这一点，如以下示例所示：
[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>
<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>
This section contains the module(s) defined by the specification. 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 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.
本节包含规范定义的模块。这些模块应使用YANG 1.1[RFC7950]语法编写。如果模块中不需要YANG 1.1结构或语义，则可以使用YANG 1.0[RFC6020]语法。如果任何导入的YANG模块使用YANG 1.1编写，则必须使用YANG 1.1编写该模块。
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, such as Structure of Management Information Version 2 (SMIv2), which are not affected by these guidelines.
文档中还可能包含模块的语法版本。文档中还可能存在其他类型的模块，如管理信息结构版本2（SMIv2），这些模块不受这些指南的影响。
Note that if the module itself is considered normative and not an example module or example YANG fragment, then all YANG statements within a YANG module are considered normative. The use of keywords defined in [RFC2119] and [RFC8174] apply to YANG "description" statements in normative modules exactly as they would in any other normative section.
注意，如果模块本身被认为是规范的，而不是示例模块或示例YANG片段，那么YANG模块中的所有YANG语句都被认为是规范的。[RFC2119]和[RFC8174]中定义的关键字的使用适用于规范性模块中的“描述”语句，就像它们在任何其他规范性章节中一样。
Example YANG modules and example YANG fragments MUST NOT contain any normative text, including any all-uppercase reserved words from [RFC2119] and [RFC8174].
示例YANG模块和示例YANG片段不得包含任何规范性文本，包括[RFC2119]和[RFC8174]中的所有大写保留字。
Consistent indentation and formatting SHOULD be used in all YANG statements within a module.
模块内的所有语句都应使用一致的缩进和格式。
See Section 4 for guidelines on YANG usage.
请参阅第4节，了解使用指南。
Each specification that defines one or more modules MUST contain a section that discusses security considerations relevant to those modules.
定义一个或多个模块的每个规范必须包含一节，讨论与这些模块相关的安全注意事项。
This section MUST be patterned after the latest approved template (available at <https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines>). Section 3.7.1 contains the security considerations template dated 2013-05-08 and last updated on 2018-07-02. Authors MUST check the web page at the URL listed above in case there is a more recent version available.
此部分必须按照最新批准的模板（可在<https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines>). 第3.7.1节包含日期为2013-05-08的安全注意事项模板，最后更新日期为2018-07-02。作者必须在上面列出的URL处检查网页，以防有更新的版本可用。
In particular:
特别地：
o Writable data nodes that could be especially disruptive if abused MUST be explicitly listed by name, and the associated security risks MUST be explained.
o 必须按名称明确列出在滥用时可能特别具有破坏性的可写数据节点，并且必须解释相关的安全风险。
o Readable data nodes that contain especially sensitive information or that raise significant privacy concerns MUST be explicitly listed by name, and the reasons for the sensitivity/privacy concerns MUST be explained.
o 包含特别敏感信息或引起重大隐私问题的可读数据节点必须按名称明确列出，并且必须解释敏感/隐私问题的原因。
o Operations (i.e., YANG "rpc" statements) that are potentially harmful to system behavior or that raise significant privacy concerns MUST be explicitly listed by name, and the reasons for the sensitivity/privacy concerns MUST be explained.
o 必须按名称明确列出可能对系统行为有害或引起重大隐私问题的操作（即“rpc”语句），并且必须解释敏感度/隐私问题的原因。
X. Security Considerations
十、安全考虑
The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].
本文档中指定的模块为数据定义了一个模式，该模式旨在通过网络管理协议（如NETCONF[RFC6241]或restcconf[RFC8040]）进行访问。最低的NETCONF层是安全传输层，实现安全传输的强制要求是安全Shell（SSH）[RFC6242]。最低的RESTCONF层是HTTPS，实现安全传输的强制层是TLS[RFC8446]。
The NETCONF access control model [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
NETCONF访问控制模型[RFC8341]提供了将特定NETCONF或RESTCONF用户的访问限制为所有可用NETCONF或RESTCONF协议操作和内容的预配置子集的方法。
-- if you have any writable data nodes (those are all the
-- "config true" nodes, and remember, that is the default)
-- describe their specific sensitivity or vulnerability.
-- if you have any writable data nodes (those are all the
-- "config true" nodes, and remember, that is the default)
-- describe their specific sensitivity or vulnerability.
There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., "config true", which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config)
此模块中定义了许多可写/可创建/可删除的数据节点（即默认值为“config true”）。在某些网络环境中，这些数据节点可能被视为敏感或易受攻击。写入操作（例如，编辑配置）
to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability:
对这些数据节点不进行适当的保护可能会对网络运行产生负面影响。这些是子树和数据节点及其敏感性/漏洞：
<list subtrees and data nodes and state why they are sensitive>
<列出子树和数据节点并说明其敏感的原因>
-- for all YANG modules you must evaluate whether any readable data
-- nodes (those are all the "config false" nodes, but also all other
-- nodes, because they can also be read via operations like get or
-- get-config) are sensitive or vulnerable (for instance, if they
-- might reveal customer information or violate personal privacy
-- laws such as those of the European Union if exposed to
-- unauthorized parties)
-- for all YANG modules you must evaluate whether any readable data
-- nodes (those are all the "config false" nodes, but also all other
-- nodes, because they can also be read via operations like get or
-- get-config) are sensitive or vulnerable (for instance, if they
-- might reveal customer information or violate personal privacy
-- laws such as those of the European Union if exposed to
-- unauthorized parties)
Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to these data nodes. These are the subtrees and data nodes and their sensitivity/vulnerability:
在某些网络环境中，此模块中的某些可读数据节点可能被视为敏感或易受攻击。因此，控制对这些数据节点的读取访问（例如，通过get、get config或通知）非常重要。这些是子树和数据节点及其敏感性/漏洞：
<list subtrees and data nodes and state why they are sensitive>
<列出子树和数据节点并说明其敏感的原因>
-- if your YANG module has defined any RPC operations
-- describe their specific sensitivity or vulnerability.
-- if your YANG module has defined any RPC operations
-- describe their specific sensitivity or vulnerability.
Some of the RPC operations in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control access to these operations. These are the operations and their sensitivity/vulnerability:
在某些网络环境中，此模块中的某些RPC操作可能被视为敏感或易受攻击。因此，控制对这些操作的访问非常重要。这些是操作及其敏感性/脆弱性：
<list RPC operations and state why they are sensitive>
<列出RPC操作并说明其敏感的原因>
In order to comply with IESG policy as set forth in <https://www.ietf.org/id-info/checklist.html>, every I-D that is submitted to the IESG for publication MUST contain an IANA Considerations section. The requirements for this section vary depending on what actions are required of the IANA. If there are no IANA considerations applicable to the document, then the IANA Considerations section will state that "This document has no IANA actions". Refer to the guidelines in [RFC8126] for more details.
为了遵守IESG政策，如<https://www.ietf.org/id-info/checklist.html>，提交给IESG发布的每个I-D必须包含IANA注意事项部分。本节的要求因IANA要求采取的行动而异。如果没有适用于本文件的IANA注意事项，则IANA注意事项部分将说明“本文件没有IANA行动”。有关更多详细信息，请参阅[RFC8126]中的指南。
Each normative YANG module MUST be registered in both the "IETF XML Registry" [RFC3688] [IANA-XML] and the "YANG Module Names" registry [RFC6020] [IANA-MOD-NAMES]. This applies to new modules and updated modules. An example of an update registration for the "ietf-template" module can be found in Section 5.
每个模块必须在“IETF XML注册表”[RFC3688][IANA-XML]和“模块名称”注册表[RFC6020][IANA-MOD-NAME]中注册。这适用于新模块和更新模块。“ietf模板”模块的更新注册示例见第5节。
If an I-D defines a new namespace that is to be administered by the IANA, then the document MUST include an IANA Considerations section that specifies how the namespace is to be administered.
如果I-D定义了一个由IANA管理的新名称空间，那么文档必须包含一个IANA注意事项部分，该部分指定如何管理名称空间。
Specifically, if any YANG module namespace statement value contained in the document is not already registered with IANA, then a new entry in the "ns" subregistry within the "IETF XML Registry" MUST be requested from the IANA.
具体而言，如果文档中包含的任何模块名称空间语句值尚未向IANA注册，则必须向IANA请求“IETF XML注册表”中“ns”子域中的新条目。
It is possible to extend an existing namespace using a YANG submodule that belongs to an existing module already administered by IANA. In this case, the document containing the main module MUST be updated to use the latest revision of the submodule.
可以使用属于已由IANA管理的现有模块的子模块扩展现有名称空间。在这种情况下，必须更新包含主模块的文档，以使用子模块的最新版本。
For every import or include statement that appears in a module contained in the specification that identifies a module in a separate document, a corresponding normative reference to that document MUST appear in the Normative References section. The reference MUST correspond to the specific module version actually used within the specification.
对于规范中包含的模块中出现的每个导入或包含语句（在单独的文档中标识模块），该文档的相应规范性引用必须出现在规范性引用部分。参考必须与规范中实际使用的特定模块版本相对应。
For every normative reference statement that appears in a module contained in the specification that identifies a separate document, a corresponding normative reference to that document SHOULD appear in the Normative References section. The reference SHOULD correspond to the specific document version actually used within the specification. If the reference statement identifies an informative reference that identifies a separate document, a corresponding informative reference to that document MAY appear in the Informative References section.
对于规范中包含的标识单独文件的模块中出现的每个规范性引用声明，该文件的相应规范性引用应出现在规范性引用部分。参考文件应与规范中实际使用的特定文件版本相对应。如果参考声明确定了识别单独文件的信息性参考，则该文件的相应信息性参考可能会出现在信息性参考部分。
All modules need to be validated before submission in an I-D. The 'pyang' YANG compiler is freely available from GitHub:
所有模块在提交I-D之前都需要进行验证。“pyang”YANG编译器可从GitHub免费获得：
<https://github.com/mbj4668/pyang>
<https://github.com/mbj4668/pyang>
If the 'pyang' compiler is used to validate a normative module, then the "--ietf" command-line option MUST be used to identify any IETF guideline issues.
如果使用“pyang”编译器验证规范模块，则必须使用“-ietf”命令行选项来识别任何ietf指南问题。
If the 'pyang' compiler is used to validate an example module, then the "--ietf" command-line option MAY be used to identify any IETF guideline issues.
如果“pyang”编译器用于验证示例模块，则“-ietf”命令行选项可用于识别任何ietf指南问题。
The "yanglint" program is also freely available from GitHub.
“yanglint”程序也可以从GitHub免费获得。
<https://github.com/CESNET/libyang>
<https://github.com/CESNET/libyang>
This tool can be used to validate XPath statements within YANG modules.
此工具可用于验证模块内的XPath语句。
A version of 'rfcstrip' that will extract YANG modules from an I-D or RFC is available. The 'rfcstrip' tool that supports YANG module extraction is freely available at:
“rfcstrip”的一个版本将从I-D或RFC中提取模块。支持模块提取的“rfcstrip”工具可在以下网站免费获得：
<https://github.com/mbj4668/rfcstrip>
<https://github.com/mbj4668/rfcstrip>
This tool can be used to verify that the "<CODE BEGINS>" and "<CODE ENDS>" tags are used correctly and that the normative YANG modules can be extracted correctly.
此工具可用于验证“<CODE BEGINS>”和“<CODE ENDS>”标记是否正确使用，以及模块是否可以正确提取。
The "xym" tool is freely available on GitHub and can be used to extract YANG modules from a document.
“xym”工具在GitHub上免费提供，可用于从文档中提取模块。
<https://github.com/xym-tool/xym>
<https://github.com/xym-tool/xym>
Each specification that defines one or more modules SHOULD contain usage examples, either throughout the document or in an appendix. This includes example instance document snippets in an appropriate encoding (e.g., XML and/or JSON) to demonstrate the intended usage of the YANG module(s). Example modules MUST be validated. Refer to Section 3.10 for tools that validate YANG modules. If IP addresses are used, then a mix of either IPv4 and IPv6 addresses or IPv6 addresses exclusively SHOULD be used in the examples.
定义一个或多个模块的每个规范应包含整个文档或附录中的使用示例。这包括采用适当编码（例如，XML和/或JSON）的示例实例文档片段，以演示YANG模块的预期用途。必须验证示例模块。有关验证模块的工具，请参阅第3.10节。如果使用IP地址，则应在示例中混合使用IPv4和IPv6地址或专用IPv6地址。
Modules in IETF Standards Track specifications MUST comply with all syntactic and semantic requirements of YANG 1.1 [RFC7950]. See the exception for YANG 1.0 in Section 3.6. The guidelines in this section are intended to supplement the YANG specification [RFC7950], which is intended to define a minimum set of conformance requirements.
IETF标准轨道规范中的模块必须符合YANG 1.1[RFC7950]的所有语法和语义要求。参见第3.6节中YANG 1.0的例外情况。本节中的指南旨在补充YANG规范[RFC7950]，该规范旨在定义一组最低合规性要求。
In order to promote interoperability and establish a set of practices based on previous experience, the following sections establish usage guidelines for specific YANG constructs.
为了促进互操作性并根据以前的经验建立一套实践，以下各节将为特定构造建立使用指南。
Only guidelines that clarify or restrict the minimum conformance requirements are included here.
此处仅包含澄清或限制最低合规性要求的指南。
Normative modules contained in Standards Track documents MUST be named according to the guidelines in the IANA Considerations section of [RFC7950].
标准跟踪文件中包含的规范性模块必须根据[RFC7950]的IANA注意事项部分中的指南命名。
A distinctive word or abbreviation (e.g., protocol name or working group abbreviation) SHOULD be used in the module name. If new definitions are being defined to extend one or more existing modules, then the same word or abbreviation should be reused, instead of creating a new one.
模块名称中应使用独特的单词或缩写（例如，协议名称或工作组缩写）。如果正在定义新定义以扩展一个或多个现有模块，则应重复使用相同的单词或缩写，而不是创建新的。
All published module names MUST be unique. For a YANG module published in an RFC, this uniqueness is guaranteed by IANA. For unpublished modules, the authors need to check that no other work in progress is using the same module name.
所有发布的模块名称必须是唯一的。对于RFC中发布的YANG模块，IANA保证了这种唯一性。对于未发布的模块，作者需要检查其他正在进行的工作是否使用相同的模块名称。
Example modules are non-normative and SHOULD be named with the prefix "example-".
示例模块是非规范性的，应使用前缀“Example-”命名。
It is suggested that a stable prefix be selected that represents the entire organization. All normative YANG modules published by the IETF MUST begin with the prefix "ietf-". Another standards organization, such as the IEEE, might use the prefix "ieee-" for all YANG modules.
建议选择代表整个组织的稳定前缀。IETF发布的所有标准模块必须以前缀“IETF-”开头。另一个标准组织，如IEEE，可能会对所有模块使用前缀“IEEE-”。
Once a module name is published, it MUST NOT be reused, even if the RFC containing the module is reclassified to "Historic" status. A module name cannot be changed in YANG, and this would be treated as a new module, not a name change.
模块名称发布后，不得重复使用，即使包含该模块的RFC被重新分类为“历史”状态。在YANG中无法更改模块名称，这将被视为新模块，而不是名称更改。
All YANG definitions are scoped by the module containing the definition being referenced. This allows definitions from multiple modules to be used, even if the names are not unique. In the example below, the identifier "foo" is used in all three modules:
所有定义都由包含所引用定义的模块确定范围。这允许使用来自多个模块的定义，即使名称不唯一。在下面的示例中，标识符“foo”用于所有三个模块：
module example-foo {
namespace "tag:example.com,2017:example-foo";
prefix f;
module example-foo {
namespace "tag:example.com,2017:example-foo";
prefix f;
container foo;
}
container foo;
}
module example-bar {
namespace "tag:example.com,2017:example-bar";
prefix b;
module example-bar {
namespace "tag:example.com,2017:example-bar";
prefix b;
typedef foo { type uint32; }
}
typedef foo { type uint32; }
}
module example-one {
namespace "tag:example.com,2017:example-one";
prefix one;
import example-foo { prefix f; }
import example-bar { prefix b; }
module example-one {
namespace "tag:example.com,2017:example-one";
prefix one;
import example-foo { prefix f; }
import example-bar { prefix b; }
augment "/f:foo" {
leaf foo { type b:foo; }
}
}
augment "/f:foo" {
leaf foo { type b:foo; }
}
}
YANG defines the following rules for prefix usage:
YANG为前缀的使用定义了以下规则：
o Prefixes are never used for built-in data types and YANG keywords.
o 前缀从不用于内置数据类型和关键字。
o A prefix MUST be used for any external statement (i.e., a statement defined with the YANG "extension" statement).
o 任何外部语句（即使用“扩展”语句定义的语句）都必须使用前缀。
o The proper module prefix MUST be used for all identifiers imported from other modules.
o 从其他模块导入的所有标识符必须使用正确的模块前缀。
o The proper module prefix MUST be used for all identifiers included from a submodule.
o 子模块中包含的所有标识符必须使用正确的模块前缀。
The following guidelines apply to prefix usage of the current (local) module:
以下准则适用于当前（本地）模块的前缀用法：
o The local module prefix SHOULD be used instead of no prefix in all path expressions.
o 应在所有路径表达式中使用本地模块前缀，而不是不使用前缀。
o The local module prefix MUST be used instead of no prefix in all "default" statements for an "identityref" or "instance-identifier" data type.
o 对于“identityref”或“instance identifier”数据类型，必须使用本地模块前缀，而不是在所有“default”语句中不使用前缀。
o The local module prefix MAY be used for references to typedefs, groupings, extensions, features, and identities defined in the module.
o 本地模块前缀可用于引用模块中定义的typedef、分组、扩展、功能和标识。
Prefix values SHOULD be short but are also likely to be unique. Prefix values SHOULD NOT conflict with known modules that have been previously published.
前缀值应该很短，但也可能是唯一的。前缀值不应与以前发布的已知模块冲突。
Identifiers for all YANG identifiers in published modules MUST be between 1 and 64 characters in length. These include any construct specified as an "identifier-arg-str" token in the ABNF in Section 14 of [RFC7950].
已发布模块中所有标识符的标识符长度必须介于1到64个字符之间。其中包括[RFC7950]第14节中ABNF中指定为“标识符arg str”标记的任何构造。
Identifiers SHOULD follow a consistent naming pattern throughout the module. Only lowercase letters, numbers, and dashes SHOULD be used in identifier names. Uppercase characters, the period character, and the underscore character MAY be used if the identifier represents a well-known value that uses these characters. YANG does not permit any other characters in YANG identifiers.
标识符在整个模块中应遵循一致的命名模式。标识符名称中只能使用小写字母、数字和破折号。如果标识符表示使用这些字符的已知值，则可以使用大写字符、句点字符和下划线字符。YANG不允许在YANG标识符中使用任何其他字符。
Identifiers SHOULD include complete words and/or well-known acronyms or abbreviations. Child nodes within a container or list SHOULD NOT replicate the parent identifier. YANG identifiers are hierarchical and are only meant to be unique within the set of sibling nodes defined in the same module namespace.
标识符应包括完整的单词和/或众所周知的首字母缩略词或缩写。容器或列表中的子节点不应复制父标识符。YANG标识符是分层的，仅在同一模块名称空间中定义的同级节点集中是唯一的。
It is permissible to use common identifiers such as "name" or "id" in data definition statements, especially if these data nodes share a common data type.
允许在数据定义语句中使用公共标识符，例如“name”或“id”，特别是当这些数据节点共享公共数据类型时。
Identifiers SHOULD NOT carry any special semantics that identify data modeling properties. Only YANG statements and YANG extension statements are designed to convey machine-readable data modeling properties. For example, naming an object "config" or "state" does
标识符不应带有任何标识数据建模属性的特殊语义。只有YANG语句和YANG扩展语句被设计用于传递机器可读的数据建模属性。例如，将一个对象命名为“config”或“state”不起作用
not change whether it is configuration data or state data. Only defined YANG statements or YANG extension statements can be used to assign semantics in a machine-readable format in YANG.
不更改它是配置数据还是状态数据。在YANG中，只有已定义的YANG语句或YANG扩展语句可用于以机器可读格式分配语义。
In general, it is suggested that substatements containing very common default values SHOULD NOT be present. The following substatements are commonly used with the default value, which would make the module difficult to read if used everywhere they are allowed.
通常，建议不存在包含非常常见的默认值的子语句。以下子语句通常与默认值一起使用，如果在允许的任何地方使用，则会使模块难以读取。
+--------------+---------------+
| Statement | Default Value |
+--------------+---------------+
| config | true |
| mandatory | false |
| max-elements | unbounded |
| min-elements | 0 |
| ordered-by | system |
| status | current |
| yin-element | false |
+--------------+---------------+
+--------------+---------------+
| Statement | Default Value |
+--------------+---------------+
| config | true |
| mandatory | false |
| max-elements | unbounded |
| min-elements | 0 |
| ordered-by | system |
| status | current |
| yin-element | false |
+--------------+---------------+
Statement Defaults
语句默认值
A module may be conceptually partitioned in several ways, using the "if-feature" and/or "when" statements.
一个模块可以使用“if-feature”和/或“when”语句以多种方式进行概念性分区。
Data model designers need to carefully consider all modularity aspects, including the use of YANG conditional statements.
数据模型设计者需要仔细考虑所有模块化方面，包括使用杨条件语句。
If a data definition is optional, depending on server support for a NETCONF or RESTCONF protocol capability, then a YANG "feature" statement SHOULD be defined. The defined "feature" statement SHOULD then be used in the conditional "if-feature" statement referencing the optional data definition.
如果数据定义是可选的，这取决于服务器对NETCONF或RESTCONF协议功能的支持，那么应该定义一个“feature”语句。然后，应在引用可选数据定义的条件“if feature”语句中使用已定义的“feature”语句。
If any notification data, or any data definition, for a non-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 conditional requirements exist for returning the data node in a notification payload or retrieval request, they MUST be documented somewhere. For example, a "when" or "if-feature" statement could apply to the data node, or the conditional requirements could be explained in a "description" statement within the data node or one of its ancestors (if any).
如果非配置数据节点的任何通知数据或任何数据定义不是强制性的，则服务器可能需要也可能不需要返回此数据节点的实例。如果在通知负载或检索请求中存在返回数据节点的任何条件要求，则必须在某处记录这些条件要求。例如，“when”或“if feature”语句可以应用于数据节点，或者条件要求可以在数据节点或其祖先之一（如果有）内的“description”语句中解释。
If any "if-feature" statements apply to a list node, then the same "if-feature" statements MUST apply to any key leaf nodes for the list. There MUST NOT be any "if-feature" statements applied to any key leafs that do not also apply to the parent list node.
如果任何“If feature”语句应用于列表节点，则相同的“If feature”语句必须应用于列表的任何键叶节点。不得将任何“if feature”语句应用于任何不适用于父列表节点的键叶。
There SHOULD NOT be any "when" statements applied to a key leaf node. It is possible that a "when" statement for an ancestor node of a key leaf will have the exact node-set result as the key leaf. In such a case, the "when" statement for the key leaf is redundant and SHOULD be avoided.
不应该对键叶节点应用任何“when”语句。键叶的祖先节点的“when”语句可能将精确的节点集结果作为键叶。在这种情况下，键叶的“when”语句是多余的，应该避免使用。
This section describes guidelines for using the XML Path Language (XPath) [W3C.REC-xpath] within YANG modules.
本节介绍在模块中使用XML路径语言（XPath）[W3C.REC XPath]的指导原则。
YANG defines five separate contexts for evaluation of XPath statements:
YANG为XPath语句的计算定义了五种不同的上下文：
1. The "running" datastore: collection of all YANG configuration data nodes. The document root is the conceptual container (e.g., "config" in the "edit-config" operation), which is the parent of all top-level data definition statements with a "config" statement value of "true".
1. “运行”数据存储：所有配置数据节点的集合。文档根是概念容器（例如，“编辑配置”操作中的“配置”），它是所有顶级数据定义语句的父级，其“配置”语句值为“true”。
2. State data + the "running" datastore: collection of all YANG data nodes. The document root is the conceptual container, parent of all top-level data definition statements.
2. 状态数据+正在运行的数据存储：所有数据节点的集合。文档根是概念容器，是所有顶级数据定义语句的父级。
3. Notification: an event notification document. The document root is the notification element.
3. 通知：事件通知文档。文档根是通知元素。
4. RPC Input: The document root is the conceptual "input" node, which is the parent of all RPC input parameter definitions.
4. RPC输入：文档根是概念上的“输入”节点，它是所有RPC输入参数定义的父节点。
5. RPC Output: The document root is the conceptual "output" node, which is the parent of all RPC output parameter definitions.
5. RPC输出：文档根是概念上的“输出”节点，它是所有RPC输出参数定义的父节点。
Note that these XPath contexts cannot be mixed. For example, a "when" statement in a notification context cannot reference configuration data.
请注意，这些XPath上下文不能混合。例如，通知上下文中的“when”语句不能引用配置数据。
notification foo {
leaf mtu {
// NOT okay because when-stmt context is this notification
when "/if:interfaces/if:interface[name='eth0']";
type leafref {
// Okay because path-stmt has a different context
path "/if:interfaces/if:interface/if:mtu";
}
}
}
notification foo {
leaf mtu {
// NOT okay because when-stmt context is this notification
when "/if:interfaces/if:interface[name='eth0']";
type leafref {
// Okay because path-stmt has a different context
path "/if:interfaces/if:interface/if:mtu";
}
}
}
It is especially important to consider the XPath evaluation context for XPath expressions defined in groupings. An XPath expression defined in a grouping may not be portable, meaning it cannot be used in multiple contexts and produce proper results.
对于分组定义的XPath表达式，考虑XPath评估上下文尤为重要。分组中定义的XPath表达式可能不可移植，这意味着它不能在多个上下文中使用并产生正确的结果。
If the XPath expressions defined in a grouping are intended for a particular context, then this context SHOULD be identified in the "description" statement for the grouping.
如果分组中定义的XPath表达式用于特定上下文，则应在分组的“description”语句中标识该上下文。
The "position" and "last" functions SHOULD NOT be used. This applies to implicit use of the "position" function as well (e.g., '//chapter[42]'). A server is only required to maintain the relative XML document order of all instances of a particular user-ordered list or leaf-list. The "position" and "last" functions MAY be used if they are evaluated in a context where the context node is a user-ordered "list" or "leaf-list".
不应使用“位置”和“最后”功能。这也适用于“position”函数的隐式使用（例如，“//chapter[42]”）。服务器只需要维护特定用户排序列表或叶列表的所有实例的相对XML文档顺序。如果在上下文节点是用户排序的“列表”或“叶列表”的上下文中评估“位置”和“最后”函数，则可以使用它们。
The "id" function SHOULD NOT be used. The "ID" attribute is not present in YANG documents, so this function has no meaning. The YANG compiler SHOULD return an empty string for this function.
不应使用“id”功能。YANG文档中不存在“ID”属性，因此此函数没有任何意义。编译器应该为此函数返回一个空字符串。
The "namespace-uri" and "name" functions SHOULD NOT be used. Expanded names in XPath are different than YANG. A specific canonical representation of a YANG-expanded name does not exist.
不应使用“名称空间uri”和“名称”函数。XPath中的扩展名称与YANG不同。扩展名称的特定规范表示形式不存在。
The "lang" function SHOULD NOT be used. This function does not apply to YANG because there is no "lang" attribute set with the document. The YANG compiler SHOULD return 'false' for this function.
不应使用“lang”函数。此函数不适用于YANG，因为文档中没有设置“lang”属性。编译器应为此函数返回“false”。
The "local-name", "namespace-uri", "name", "string", and "number" functions SHOULD NOT be used if the argument is a node-set. If so, the function result will be determined by the document order of the node-set. Since this order can be different on each server, the function results can also be different. Any function call that implicitly converts a node-set to a string will also have this issue.
如果参数是节点集，则不应使用“local name”、“namespace uri”、“name”、“string”和“number”函数。如果是，则功能结果将由节点集的文档顺序确定。由于每个服务器上的顺序可能不同，因此函数结果也可能不同。任何将节点集隐式转换为字符串的函数调用也会出现此问题。
The "local-name" function SHOULD NOT be used to reference local names outside of the YANG module that defines the must or when expression containing the "local-name" function. Example of a "local-name" function that should not be used:
“local name”函数不应用于引用定义包含“local name”函数的must或when表达式的YANG模块之外的本地名称。不应使用的“本地名称”函数示例：
/*[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.
对于identityref值，应使用“派生自或自”函数，而不是等式表达式。这允许在概念上扩充标识。
Example:
例子：
// do not use
when "md-name-format = 'name-format-null'";
// do not use
when "md-name-format = 'name-format-null'";
// this is preferred
when "derived-from-or-self(md-name-format, 'name-format-null')";
// this is preferred
when "derived-from-or-self(md-name-format, 'name-format-null')";
The "attribute" and "namespace" axes are not supported in YANG and MAY be empty in a NETCONF or RESTCONF server implementation.
YANG中不支持“属性”和“名称空间”轴，在NETCONF或RESTCONF服务器实现中可能为空。
The "preceding" and "following" axes SHOULD NOT be used. These constructs rely on XML document order within a NETCONF or RESTCONF server configuration database, which may not be supported consistently or produce reliable results across implementations. Predicate expressions based on static node properties (e.g., element name or value, and "ancestor" or "descendant" axes) SHOULD be used instead. The "preceding" and "following" axes MAY be used if document order is not relevant to the outcome of the expression (e.g., check for global uniqueness of a parameter value).
不应使用“前”轴和“后”轴。这些构造依赖于NETCONF或RESTCONF服务器配置数据库中的XML文档顺序，这可能不受一致支持，也可能无法跨实现产生可靠的结果。应使用基于静态节点属性（例如，元素名称或值以及“祖先”或“后代”轴）的谓词表达式。如果文档顺序与表达式的结果无关（例如，检查参数值的全局唯一性），则可以使用“前”和“后”轴。
The "preceding-sibling" and "following-sibling" axes SHOULD NOT be used; however, they MAY be used if document order is not relevant to the outcome of the expression.
不应使用“前同级”和“后同级”轴；但是，如果文档顺序与表达式的结果不相关，则可以使用它们。
A server is only required to maintain the relative XML document order of all instances of a particular user-ordered list or leaf-list. The "preceding-sibling" and "following-sibling" axes MAY be used if they are evaluated in a context where the context node is a user-ordered "list" or "leaf-list".
服务器只需要维护特定用户排序列表或叶列表的所有实例的相对XML文档顺序。如果在上下文节点是用户订购的“列表”或“叶列表”的上下文中对“前同级”和“后同级”轴进行评估，则可以使用“前同级”和“后同级”轴。
Data nodes that use the "int64" and "uint64" built-in type SHOULD NOT be used within numeric or boolean expressions. There are boundary conditions in which the translation from the YANG 64-bit type to an XPath number can cause incorrect results. Specifically, an XPath "double" precision floating-point number cannot represent very large positive or negative 64-bit numbers because it only provides a total precision of 53 bits. The "int64" and "uint64" data types MAY be used in numeric expressions if the value can be represented with no more than 53 bits of precision.
在数值或布尔表达式中不应使用使用“int64”和“uint64”内置类型的数据节点。在某些边界条件下，从64位类型到XPath数的转换可能会导致不正确的结果。具体来说，XPath“双精度”浮点数字不能表示非常大的正或负64位数字，因为它只提供53位的总精度。如果值的表示精度不超过53位，“int64”和“uint64”数据类型可以在数值表达式中使用。
Data modelers need to be careful not to confuse the YANG value space and the XPath value space. The data types are not the same in both, and conversion between YANG and XPath data types SHOULD be considered carefully.
数据建模人员需要小心，不要混淆YANG值空间和XPath值空间。两者的数据类型不同，应该仔细考虑YANG和XPath数据类型之间的转换。
Explicit XPath data type conversions MAY be used (e.g., "string", "boolean", or "number" functions), instead of implicit XPath data type conversions.
可以使用显式XPath数据类型转换（例如，“字符串”、“布尔”或“数字”函数），而不是隐式XPath数据类型转换。
XPath expressions that contain a literal value representing a YANG identity SHOULD always include the declared prefix of the module where the identity is defined.
包含表示标识的文本值的XPath表达式应始终包含定义标识的模块的声明前缀。
XPath expressions for "when" statements SHOULD NOT reference the context node or any descendant nodes of the context node. They MAY reference descendant nodes if the "when" statement is contained within an "augment" statement, and the referenced nodes are not defined within the "augment" statement.
“when”语句的XPath表达式不应引用上下文节点或上下文节点的任何子节点。如果“when”语句包含在“augment”语句中，并且被引用的节点未在“augment”语句中定义，则它们可能引用子代节点。
Example:
例子：
augment "/rt:active-route/rt:input/rt:destination-address" {
when "rt:address-family='v4ur:ipv4-unicast'" {
description
"This augment is valid only for IPv4 unicast.";
}
// nodes defined here within the augment-stmt
// cannot be referenced in the when-stmt
}
augment "/rt:active-route/rt:input/rt:destination-address" {
when "rt:address-family='v4ur:ipv4-unicast'" {
description
"This augment is valid only for IPv4 unicast.";
}
// nodes defined here within the augment-stmt
// cannot be referenced in the when-stmt
}
It is possible to construct XPath expressions that will evaluate differently when combined with several modules within a server implementation rather than when evaluated within the single module. This is due to augmenting nodes from other modules.
可以构造XPath表达式，当与服务器实现中的多个模块组合时，其计算结果将不同于在单个模块中进行计算时的计算结果。这是由于增加了来自其他模块的节点。
Wildcard expansion is done within a server against all the nodes from all namespaces, so it is possible for a "must" or "when" expression that uses the '*' operator to always evaluate to false if processed within a single YANG module. In such cases, the "description" statement SHOULD clarify that augmenting objects are expected to match the wildcard expansion.
通配符扩展是在服务器中针对所有名称空间中的所有节点进行的，因此，如果在单个模块中处理，则使用“*”运算符的“必须”或“何时”表达式的计算结果可能始终为false。在这种情况下，“description”语句应该澄清扩充对象应该与通配符扩展相匹配。
when /foo/services/*/active {
description
"No services directly defined in this module.
Matches objects that have augmented the services container.";
}
when /foo/services/*/active {
description
"No services directly defined in this module.
Matches objects that have augmented the services container.";
}
The YANG "must" and "when" statements use an XPath boolean expression to define the test condition for the statement. It is important to specify these expressions in a way that will not cause inadvertent changes in the result if the objects referenced in the expression are updated in future revisions of the module.
YANG“must”和“when”语句使用XPath布尔表达式定义语句的测试条件。如果表达式中引用的对象在模块的未来版本中更新，则指定这些表达式的方式必须不会导致结果中的意外更改。
For example, the leaf "foo2" must exist if the leaf "foo1" is equal to "one" or "three":
例如，如果叶“foo1”等于“1”或“3”，则叶“foo2”必须存在：
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
}
}
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
}
}
leaf foo2 {
// INCORRECT
must "/f:foo1 != 'two'";
type string;
}
leaf foo2 {
// INCORRECT
must "/f:foo1 != 'two'";
type string;
}
leaf foo2 {
// CORRECT
must "/f:foo1 = 'one' or /f:foo1 = 'three'";
type string;
}
leaf foo2 {
// CORRECT
must "/f:foo1 = 'one' or /f:foo1 = 'three'";
type string;
}
In the next revision of the module, leaf "foo1" is extended with a new enum named "four":
在模块的下一个版本中，叶“foo1”使用名为“four”的新枚举进行扩展：
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
enum four;
}
}
leaf foo1 {
type enumeration {
enum one;
enum two;
enum three;
enum four;
}
}
Now the first XPath expression will allow the enum "four" to be accepted in addition to the "one" and "three" enum values.
现在，第一个XPath表达式将允许接受除“1”和“3”枚举值之外的枚举“4”。
The YANG status statement MUST be present within a definition if its value is "deprecated" or "obsolete". The status SHOULD NOT be changed from "current" directly to "obsolete". An object SHOULD be available for at least one year with a "deprecated" status before it is changed to "obsolete".
如果YANG status语句的值为“不推荐”或“过时”，则该语句必须存在于定义中。状态不应直接从“当前”更改为“过时”。在对象更改为“过时”之前，其状态为“已弃用”的对象应至少可用一年。
The module or submodule name MUST NOT be changed, once the document containing the module or submodule is published.
发布包含模块或子模块的文档后，不得更改模块或子模块名称。
The module namespace URI value MUST NOT be changed, once the document containing the module is published.
发布包含模块的文档后，不得更改模块命名空间URI值。
The revision date substatement within the import statement SHOULD be present if any groupings are used from the external module.
如果使用外部模块中的任何分组，则导入语句中应存在修订日期子语句。
The revision date substatement within the include statement SHOULD be present if any groupings are used from the external submodule.
如果使用外部子模块中的任何分组，则include语句中的修订日期子语句应该存在。
If an import statement is for a module from a stable source (e.g., an RFC for an IETF module), then a reference-stmt SHOULD be present within an import statement.
如果导入语句用于来自稳定源的模块（例如，IETF模块的RFC），则导入语句中应存在引用stmt。
import ietf-yang-types {
prefix yang;
reference "RFC 6991: Common YANG Data Types";
}
import ietf-yang-types {
prefix yang;
reference "RFC 6991: Common YANG Data Types";
}
If submodules are used, then the document containing the main module MUST be updated so that the main module revision date is equal to or more recent than the revision date of any submodule that is (directly or indirectly) included by the main module.
如果使用子模块，则必须更新包含主模块的文档，以便主模块修订日期等于或大于主模块（直接或间接）包含的任何子模块的修订日期。
Definitions for future use SHOULD NOT be specified in a module. Do not specify placeholder objects like the "reserved" example below:
不应在模块中指定将来使用的定义。不要像下面的“保留”示例那样指定占位符对象：
leaf reserved {
type string;
description
"This object has no purpose at this time, but a future
revision of this module might define a purpose
for this object.";
}
}
leaf reserved {
type string;
description
"This object has no purpose at this time, but a future
revision of this module might define a purpose
for this object.";
}
}
For published modules, the namespace MUST be a globally unique URI, as defined in [RFC3986]. This value is usually assigned by the IANA.
对于已发布的模块，命名空间必须是全局唯一的URI，如[RFC3986]中所定义。该值通常由IANA分配。
The "organization" statement MUST be present. If the module is contained in a document intended for IETF Standards Track status, then the organization SHOULD be the IETF working group (WG) chartered to write the document. For other standards organizations, a similar approach is also suggested.
“组织”声明必须存在。如果模块包含在用于IETF标准跟踪状态的文件中，则该组织应是IETF工作组（WG）特许编写该文件的机构。对于其他标准组织，也建议采用类似的方法。
The "contact" statement MUST be present. If the module is contained in a document intended for Standards Track status, then the WG web and mailing information SHOULD be present, and the main document author or editor contact information SHOULD be present. If additional authors or editors exist, their contact information MAY be present. There is no need to include the contact information for WG Chairs.
“联系人”声明必须存在。如果模块包含在用于标准跟踪状态的文档中，则应提供工作组web和邮件信息，并且应提供主要文档作者或编辑联系信息。如果存在其他作者或编辑，则可能存在他们的联系信息。不需要包括工作组主席的联系信息。
The "description" statement MUST be present. For modules published within IETF documents, the appropriate IETF Trust Copyright text MUST be present, as described in Section 3.1.
“描述”语句必须存在。对于在IETF文件中发布的模块，必须提供适当的IETF信托版权文本，如第3.1节所述。
If the module relies on information contained in other documents, which are not the same documents implied by the import statements present in the module, then these documents MUST be identified in the reference statement.
如果模块依赖于其他文档中包含的信息，而这些文档与模块中的导入声明暗示的文档不同，则必须在参考声明中标识这些文档。
A "revision" statement MUST be present for each published version of the module. The "revision" statement MUST have a "reference" substatement. It MUST identify the published document that contains the module. Modules are often extracted from their original documents, and it is useful for developers and operators to know how to find the original source document in a consistent manner. The "revision" statement MAY have a "description" substatement.
必须为模块的每个发布版本提供“修订”声明。“修订”语句必须有“引用”子语句。它必须标识包含模块的已发布文档。模块通常是从它们的原始文档中提取的，开发人员和操作员知道如何以一致的方式找到原始源文档是很有用的。“修订”语句可能有“说明”子语句。
The following example shows the revision statement for a published YANG module:
以下示例显示已发布模块的修订声明：
revision "2012-02-22" {
description
"Initial version";
reference
"RFC 8341: Network Configuration
Access Control Model";
}
revision "2012-02-22" {
description
"Initial version";
reference
"RFC 8341: Network Configuration
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 8407: Network Configuration Protocol (NETCONF)
Access Control Model";
}
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 8407: Network Configuration Protocol (NETCONF)
Access Control Model";
}
revision "2012-02-22" {
description
"Initial version";
reference
"RFC 8341: Network Configuration
Access Control Model";
}
revision "2012-02-22" {
description
"Initial version";
reference
"RFC 8341: Network Configuration
Access Control Model";
}
It is RECOMMENDED that only valid YANG modules be included in documents, whether or not the modules are published yet. This allows:
无论模块是否已发布，建议文档中只包含有效的模块。这允许：
o the module to compile correctly instead of generating disruptive fatal errors.
o 该模块需要正确编译，而不是生成破坏性的致命错误。
o early implementors to use the modules without picking a random value for the XML namespace.
o 早期的实现者使用这些模块，而无需为XML名称空间选择随机值。
o early interoperability testing since independent implementations will use the same XML namespace value.
o 早期互操作性测试，因为独立实现将使用相同的XML名称空间值。
Until a URI is assigned by the IANA, a proposed namespace URI MUST be provided for the namespace statement in a YANG module. A value SHOULD be selected that is not likely to collide with other YANG namespaces. Standard module names, prefixes, and URI strings already listed in the "YANG Module Names" registry MUST NOT be used.
在IANA分配URI之前，必须为模块中的namespace语句提供建议的名称空间URI。应选择不可能与其他名称空间冲突的值。不得使用“模块名称”注册表中已列出的标准模块名称、前缀和URI字符串。
A standard namespace statement value SHOULD have the following form:
标准命名空间语句值应具有以下形式：
<URN prefix string>:<module-name>
<URN prefix string>:<module-name>
The following URN prefix string SHOULD be used for published and unpublished YANG modules:
以下URN前缀字符串应用于已发布和未发布的模块：
urn:ietf:params:xml:ns:yang:
urn:ietf:params:xml:ns:yang:
The following example URNs would be valid namespace statement values for Standards Track modules:
以下示例URN将是标准跟踪模块的有效命名空间语句值：
urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
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 modules that are not Standards Track. The string SHOULD be selected according to the guidelines in [RFC7950].
请注意，对于非标准轨道的模块，应使用不同的URN前缀字符串。应根据[RFC7950]中的指南选择字符串。
The following URIs exemplify what might be used by modules that are not Standards Track. Note that the domain "example.com" SHOULD be used by example modules in IETF I-Ds. These URIs are not intended to be dereferenced. They are used for module namespace identification only.
以下URI举例说明了非标准跟踪模块可能使用的内容。请注意，IETF I-Ds中的示例模块应使用域“example.com”。这些URI不打算取消引用。它们仅用于模块名称空间标识。
Example URIs using URLs per [RFC3986]:
根据[RFC3986]使用URL的URI示例：
https://example.com/ns/example-interfaces
https://example.com/ns/example-interfaces
https://example.com/ns/example-system
https://example.com/ns/example-system
Example URIs using tags per [RFC4151]:
根据[RFC4151]使用标记的示例URI：
tag:example.com,2017:example-interfaces
标签：example.com，2017：示例接口
tag:example.com,2017:example-system
标签：example.com，2017：示例系统
The top-level data organization SHOULD be considered carefully, in advance. Data model designers need to consider how the functionality for a given protocol or protocol family will grow over time.
应提前仔细考虑顶级数据组织。数据模型设计者需要考虑给定协议或协议族的功能如何随着时间的增长而增长。
The separation of configuration data and operational state SHOULD be considered carefully. It is sometimes useful to define separate top-level containers for configuration and non-configuration data. For some existing top-level data nodes, configuration data was not in scope, so only one container representing operational state was created. Refer to NMDA [RFC8342] for details.
应仔细考虑配置数据和操作状态的分离。为配置和非配置数据定义单独的顶级容器有时很有用。对于一些现有的顶级数据节点，配置数据不在范围内，因此只创建了一个表示操作状态的容器。有关详细信息，请参阅NMDA[RFC8342]。
The number of top-level data nodes within a module SHOULD be minimized. It is often useful to retrieve related information within a single subtree. If data is too distributed, it becomes difficult to retrieve all at once.
一个模块中顶级数据节点的数量应该最小化。在单个子树中检索相关信息通常很有用。如果数据过于分散，则很难同时检索所有数据。
The names and data organization SHOULD reflect persistent information, such as the name of a protocol. The name of the working group SHOULD NOT be used because this may change over time.
名称和数据组织应该反映持久性信息，例如协议的名称。不应使用工作组的名称，因为这可能会随着时间的推移而改变。
A mandatory database data definition is defined as a node that a client must provide for the database to be valid. The server is not required to provide a value.
强制数据库数据定义定义为客户端必须提供的节点，以使数据库有效。服务器不需要提供值。
Top-level database data definitions MUST NOT be mandatory. If a mandatory node appears at the top level, it will immediately cause the database to be invalid. This can occur when the server boots or when a module is loaded dynamically at runtime.
顶级数据库数据定义不能是强制性的。如果强制节点出现在顶层，它将立即导致数据库无效。当服务器引导或在运行时动态加载模块时，可能会发生这种情况。
Selection of an appropriate data type (i.e., built-in type, existing derived type, or new derived type) is very subjective; therefore, few requirements can be specified on that subject.
选择适当的数据类型（即内置类型、现有派生类型或新派生类型）非常主观；因此，在该主题上可以指定的要求很少。
Data model designers SHOULD use the most appropriate built-in data type for the particular application.
数据模型设计者应该为特定的应用程序使用最合适的内置数据类型。
The signed numeric data types (i.e., "int8", "int16", "int32", and "int64") SHOULD NOT be used unless negative values are allowed for the desired semantics.
除非所需语义允许负值，否则不应使用有符号数字数据类型（即“int8”、“int16”、“int32”和“int64”）。
If the set of values is fixed and the data type contents are controlled by a single naming authority, then an enumeration data type SHOULD be used.
如果值集是固定的，并且数据类型内容由单个命名机构控制，则应使用枚举数据类型。
leaf foo {
type enumeration {
enum one;
enum two;
}
}
leaf foo {
type enumeration {
enum one;
enum two;
}
}
If extensibility of enumerated values is required, then the "identityref" data type SHOULD be used instead of an enumeration or other built-in type.
如果需要枚举值的扩展性，则应使用“identityref”数据类型，而不是枚举或其他内置类型。
identity foo-type {
description "Base for the extensible type";
}
identity foo-type {
description "Base for the extensible type";
}
identity one {
base f:foo-type;
}
identity two {
base f:foo-type;
}
identity one {
base f:foo-type;
}
identity two {
base f:foo-type;
}
leaf foo {
type identityref {
base f:foo-type;
}
}
leaf foo {
type identityref {
base f: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 to be qualified names.
请注意，任何模块都可以使用基“foo-type”声明一个对“foo”叶有效的标识。Identityref值被视为限定名称。
For string data types, if a machine-readable pattern can be defined for the desired semantics, then one or more pattern statements SHOULD be present. A single-quoted string SHOULD be used to specify the 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.
对于字符串数据类型，如果可以为所需的语义定义机器可读的模式，那么应该存在一个或多个模式语句。应该使用单引号字符串来指定模式，因为双引号字符串可以修改内容。如果类型定义中使用的模式具有已知的限制，如假阴性或假阳性匹配，则这些限制应记录在typedef或数据定义中。
The following typedef from [RFC6991] demonstrates the proper use of the "pattern" statement:
[RFC6991]中的以下typedef演示了“pattern”语句的正确使用：
typedef ipv4-address-no-zone {
type inet:ipv4-address {
pattern '[0-9\.]*';
}
...
}
typedef ipv4-address-no-zone {
type inet:ipv4-address {
pattern '[0-9\.]*';
}
...
}
For string data types, if the length of the string is required to be bounded in all implementations, then a length statement MUST be present.
对于字符串数据类型，如果在所有实现中都要求对字符串的长度进行限制，则必须存在一条长度语句。
The following typedef from [RFC6991] demonstrates the proper use of the "length" statement:
[RFC6991]中的以下typedef演示了“length”语句的正确使用：
typedef yang-identifier {
type string {
length "1..max";
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
}
...
}
typedef yang-identifier {
type string {
length "1..max";
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*';
pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
}
...
}
For numeric data types, if the values allowed by the intended semantics are different than those allowed by the unbounded intrinsic data type (e.g., "int32"), then a range statement SHOULD be present.
对于数字数据类型，如果预期语义允许的值不同于无界内在数据类型（例如，“int32”）允许的值，则应该存在一个range语句。
The following typedef from [RFC6991] demonstrates the proper use of the "range" statement:
[RFC6991]中的以下typedef演示了“range”语句的正确使用：
typedef dscp {
type uint8 {
range "0..63";
}
...
}
typedef dscp {
type uint8 {
range "0..63";
}
...
}
For "enumeration" or "bits" data types, the semantics for each "enum" or "bit" SHOULD be documented. A separate "description" statement (within each "enum" or "bit" statement) SHOULD be present.
对于“枚举”或“位”数据类型，应记录每个“枚举”或“位”的语义。应该有一个单独的“description”语句（在每个“enum”或“bit”语句中）。
leaf foo {
// INCORRECT
type enumeration {
enum one;
enum two;
}
description
"The foo enum...
one: The first enum
two: The second enum";
}
leaf foo {
// INCORRECT
type enumeration {
enum one;
enum two;
}
description
"The foo enum...
one: The first enum
two: The second enum";
}
leaf foo {
// CORRECT
type enumeration {
enum one {
description "The first enum";
}
enum two {
description "The second enum";
}
}
description
"The foo enum... ";
}
leaf foo {
// CORRECT
type enumeration {
enum one {
description "The first enum";
}
enum two {
description "The second enum";
}
}
description
"The foo enum... ";
}
The YANG "union" type is evaluated by testing a value against each member type in the union. The first type definition that accepts a value as valid is the member type used. In general, member types SHOULD be ordered from most restrictive to least restrictive types.
通过对联合中的每个成员类型测试一个值来评估“联合”类型。第一个接受有效值的类型定义是使用的成员类型。通常，成员类型应该从限制性最强的类型到限制性最低的类型排序。
In the following example, the "enumeration" type will never be matched because the preceding "string" type will match everything.
在下面的示例中，“枚举”类型将永远不会匹配，因为前面的“字符串”类型将匹配所有内容。
Incorrect:
不正确：
type union {
type string;
type enumeration {
enum up;
enum down;
}
}
type union {
type string;
type enumeration {
enum up;
enum down;
}
}
Correct:
对的：
type union {
type enumeration {
enum up;
enum down;
}
type string;
}
type union {
type enumeration {
enum up;
enum down;
}
type string;
}
It is possible for different member types to match, depending on the input encoding format. In XML, all values are passed as string nodes; but in JSON, there are different value types for numbers, booleans, and strings.
根据输入编码格式，不同的成员类型可以匹配。在XML中，所有值都作为字符串节点传递；但在JSON中，数字、布尔值和字符串有不同的值类型。
In the following example, a JSON numeric value will always be matched by the "int32" type, but in XML the string value representing a number will be matched by the "string" type. The second version will match the "int32" member type no matter how the input is encoded.
在下面的示例中，JSON数值将始终与“int32”类型匹配，但在XML中，表示数字的字符串值将与“string”类型匹配。第二个版本将匹配“int32”成员类型，无论输入如何编码。
Incorrect:
不正确：
type union {
type string;
type int32;
}
type union {
type string;
type int32;
}
Correct:
对的：
type union {
type int32;
type string;
}
type union {
type int32;
type string;
}
YANG provides an "empty" data type, which has one value (i.e., present). The default is "not present", which is not actually a value. When used within a list key, only one value can (and must) exist for this key leaf. The type "empty" SHOULD NOT be used for a key leaf since it is pointless.
YANG提供了一个“空”数据类型，它有一个值（即，present）。默认值为“not present”，它实际上不是一个值。在列表键中使用时，此键叶只能（且必须）存在一个值。类型“empty”不应用于键叶，因为它是无意义的。
There is really no difference between a leaf of type "empty" and a leaf-list of type "empty". Both are limited to one instance. The type "empty" SHOULD NOT be used for a leaf-list.
类型为“empty”的叶和类型为“empty”的叶列表之间实际上没有区别。两者仅限于一个实例。类型“empty”不应用于叶列表。
The advantage of using type "empty" instead of type "boolean" is that the default (not present) does not take up any bytes in a representation. The disadvantage is that the client may not be sure if an empty leaf is missing because it was filtered somehow or not implemented. The client may not have a complete and accurate schema for the data returned by the server and may not be aware of the missing leaf.
使用类型“empty”而不是类型“boolean”的优点是默认值（不存在）不会占用表示中的任何字节。缺点是，客户端可能无法确定是否缺少空叶，因为它是以某种方式过滤的或未实现的。对于服务器返回的数据，客户端可能没有完整准确的模式，并且可能不知道缺少的叶。
The YANG "boolean" data type provides two values ("true" and "false"). When used within a list key, two entries can exist for this key leaf. Default values are ignored for key leafs, but a default statement is often used for plain boolean leafs. The advantage of the "boolean" type is that the leaf or leaf-list has a clear representation for both values. The default value is usually not returned unless explicitly requested by the client, so no bytes are used in a typical representation.
“boolean”数据类型提供两个值（“true”和“false”）。在列表键中使用时，此键叶可以存在两个条目。键叶忽略默认值，但普通布尔叶通常使用默认语句。“boolean”类型的优点是叶或叶列表对这两个值都有清晰的表示。除非客户端明确请求，否则通常不会返回默认值，因此在典型表示中不使用字节。
In general, the "boolean" data type SHOULD be used instead of the "empty" data type, as shown in the example below:
通常，应使用“布尔”数据类型而不是“空”数据类型，如下例所示：
Incorrect:
不正确：
leaf flag1 {
type empty;
}
leaf flag1 {
type empty;
}
Correct:
对的：
leaf flag2 {
type boolean;
default false;
}
leaf flag2 {
type boolean;
default false;
}
If an appropriate derived type exists in any standard module, such as [RFC6991], then it SHOULD be used instead of defining a new derived type.
如果任何标准模块（如[RFC6991]）中存在适当的派生类型，则应使用它，而不是定义新的派生类型。
If an appropriate units identifier can be associated with the desired semantics, then a units statement SHOULD be present.
如果适当的单元标识符可以与所需的语义相关联，那么应该存在一个units语句。
If an appropriate default value can be associated with the desired semantics, then a default statement SHOULD be present.
如果适当的默认值可以与所需的语义相关联，那么应该存在一个默认语句。
If a significant number of derived types are defined, and it is anticipated that these data types will be reused by multiple modules, then these derived types SHOULD be contained in a separate module or submodule, to allow easier reuse without unnecessary coupling.
如果定义了大量的派生类型，并且预期这些数据类型将被多个模块重用，那么这些派生类型应该包含在单独的模块或子模块中，以便在没有不必要的耦合的情况下更容易重用。
The "description" statement MUST be present.
“描述”语句必须存在。
If the type definition semantics are defined in an external document (other than another YANG module indicated by an import statement), then the reference statement MUST be present.
如果类型定义语义是在外部文档中定义的（导入语句指示的另一个模块除外），则必须存在引用语句。
A reusable grouping is a YANG grouping that can be imported by another module and is intended for use by other modules. This is not the same as a grouping that is used within the module in which it is defined, but it happens to be exportable to another module because it is defined at the top level of the YANG module.
可重用分组是可由其他模块导入并供其他模块使用的分组。这与在定义分组的模块中使用的分组不同，但它恰好可以导出到另一个模块，因为它是在模块的顶层定义的。
The following guidelines apply to reusable groupings, in order to make them as robust as possible:
以下准则适用于可重用分组，以使其尽可能健壮：
o Clearly identify the purpose of the grouping in the "description" statement.
o 在“说明”语句中明确说明分组的目的。
o There are five different XPath contexts in YANG (rpc/input, rpc/ output, notification, "config true" data nodes, and all data nodes). Clearly identify which XPath contexts are applicable or excluded for the grouping.
o YANG中有五种不同的XPath上下文（rpc/input、rpc/output、notification、“config true”数据节点和所有数据节点）。清楚地确定哪些XPath上下文适用于分组或不适用于分组。
o Do not reference data outside the grouping in any "path", "must", or "when" statements.
o 不要在任何“路径”、“必须”或“何时”语句中引用分组之外的数据。
o Do not include a "default" substatement on a leaf or choice unless the value applies on all possible contexts.
o 除非该值适用于所有可能的上下文，否则不要在叶或选项上包含“default”子语句。
o Do not include a "config" substatement on a data node unless the value applies on all possible contexts.
o 除非该值适用于所有可能的上下文，否则不要在数据节点上包含“config”子语句。
o Clearly identify any external dependencies in the grouping "description" statement, such as nodes referenced by an absolute path from a "path", "must", or "when" statement.
o Clearly identify any external dependencies in the grouping "description" statement, such as nodes referenced by an absolute path from a "path", "must", or "when" statement.translate error, please retry
The "description" statement MUST be present in the following YANG statements:
“说明”语句必须出现在以下语句中：
o anyxml
o 任意XML
o augment
o 加强
o choice
o 选择
o container
o 容器
o extension
o 扩大
o feature
o 特色
o grouping
o 分组
o identity
o 身份
o leaf
o 叶
o leaf-list
o 叶列表
o list
o 列表
o notification
o 通知
o rpc
o rpc
o typedef
o 类型定义
If the data definition semantics are defined in an external document, (other than another YANG module indicated by an import statement), then a reference statement MUST be present.
如果数据定义语义是在外部文档中定义的（导入语句指示的另一个模块除外），则必须存在引用语句。
The "anyxml" construct may be useful to represent an HTML banner containing markup elements, such as "<b>" and "</b>", and MAY be used in such cases. However, this construct SHOULD NOT be used if other YANG data node types can be used instead to represent the desired syntax and semantics.
“anyxml”构造对于表示包含标记元素（如“<b>”和“</b>”）的HTML横幅可能很有用，并且可以在这种情况下使用。但是，如果可以使用其他数据节点类型来表示所需的语法和语义，则不应使用此构造。
It has been found that the "anyxml" statement is not implemented consistently across all servers. It is possible that mixed-mode XML will not be supported or that configuration anyxml nodes will not supported.
已经发现“anyxml”语句并不是在所有服务器上都一致地实现的。可能不支持混合模式XML，或者不支持配置anyxml节点。
If there are referential integrity constraints associated with the desired semantics that can be represented with XPath, then one or more "must" statements SHOULD be present.
如果存在与可以用XPath表示的所需语义相关联的引用完整性约束，那么应该存在一个或多个“必须”语句。
For list and leaf-list data definitions, if the number of possible instances is required to be bounded for all implementations, then the max-elements statements SHOULD be present.
对于列表和叶列表数据定义，如果所有实现都要求限制可能的实例数，则应显示max elements语句。
If any "must" or "when" statements are used within the data definition, then the data definition "description" statement SHOULD describe the purpose of each one.
如果在数据定义中使用了任何“必须”或“何时”语句，那么数据定义“描述”语句应该描述每一个语句的用途。
The "choice" statement is allowed to be directly present within a "case" statement in YANG 1.1. This needs to be considered carefully. Consider simply including the nested "choice" as additional "case" statements within the parent "choice" statement. Note that the "mandatory" and "default" statements within a nested "choice" statement only apply if the "case" containing the nested "choice" statement is first selected.
杨1.1中的“选择”语句可以直接出现在“案例”语句中。这需要仔细考虑。简单地考虑将嵌套的“选择”作为父“选择”语句中的附加“案例”语句。请注意，嵌套的“choice”语句中的“mandatory”和“default”语句仅在包含嵌套的“choice”语句的“case”被首次选中时才适用。
If a list defines any key leafs, then these leafs SHOULD be defined in order, as the first child nodes within the list. The key leafs MAY be in a different order in some cases, e.g., they are defined in a grouping, and not inline in the list statement.
如果列表定义了任何键叶，那么这些键叶应该按顺序定义，作为列表中的第一个子节点。在某些情况下，键叶的顺序可能不同，例如，它们在分组中定义，而不是在list语句中内联。
A non-presence container is used to organize data into specific subtrees. It is not intended to have semantics within the data model beyond this purpose, although YANG allows it (e.g., a "must" statement within the non-presence container).
无状态容器用于将数据组织到特定子树中。它并不打算在数据模型中包含超出此目的的语义，尽管YANG允许（例如，非存在容器中的“必须”语句）。
Example using container wrappers:
使用容器包装器的示例：
container top {
container foos {
list foo { ... }
}
container bars {
list bar { ... }
}
}
container top {
container foos {
list foo { ... }
}
container bars {
list bar { ... }
}
}
Example without container wrappers:
没有容器包装器的示例：
container top {
list foo { ... }
list bar { ... }
}
container top {
list foo { ... }
list bar { ... }
}
Use of non-presence containers to organize data is a subjective matter similar to use of subdirectories in a file system. Although these containers do not have any semantics, they can impact protocol operations for the descendant data nodes within a non-presence container, so use of these containers SHOULD be considered carefully.
使用不存在容器来组织数据是一个主观问题，类似于在文件系统中使用子目录。尽管这些容器没有任何语义，但它们可能会影响非存在容器中的后代数据节点的协议操作，因此应仔细考虑使用这些容器。
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).
NETCONF和RESTCONF协议目前不支持一次删除所有列表（或叶列表）项。有时通过使用父容器（即，删除容器也会删除所有子条目）可以避免此缺陷。
Use of top-level objects needs to be considered carefully:
需要仔细考虑顶级对象的使用：
o top-level siblings are not ordered
o 顶级同级未排序
o top-level siblings are not static and depend on the modules that are loaded
o 顶级同级不是静态的，取决于加载的模块
o for subtree filtering, retrieval of a top-level leaf-list will be treated as a content-match node for all top-level-siblings
o 对于子树筛选，顶级叶列表的检索将被视为所有顶级同级的内容匹配节点
o a top-level list with many instances may impact performance
o 包含多个实例的顶级列表可能会影响性能
If the operation semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement MUST be present.
如果操作语义是在外部文档中定义的（导入语句指示的另一个模块除外），则必须存在引用语句。
If the operation impacts system behavior in some way, it SHOULD be mentioned in the "description" statement.
如果操作以某种方式影响系统行为，则应在“描述”语句中提及。
If the operation is potentially harmful to system behavior in some way, it MUST be mentioned in the Security Considerations section of the document.
如果该操作在某种程度上可能对系统行为有害，则必须在文档的“安全注意事项”部分中提及。
The "description" statement MUST be present.
“描述”语句必须存在。
If the notification semantics are defined in an external document (other than another YANG module indicated by an import statement), then a reference statement MUST be present.
如果通知语义是在外部文档中定义的（导入语句指示的另一个模块除外），则必须存在引用语句。
If the notification refers to a specific resource instance, then this instance SHOULD be identified in the notification data. This is usually done by including "leafref" leaf nodes with the key leaf values for the resource instance. For example:
如果通知引用特定的资源实例，则应在通知数据中标识该实例。这通常是通过包含“leafref”叶节点和资源实例的关键叶值来实现的。例如：
notification interface-up {
description "Sent when an interface is activated.";
leaf name {
type leafref {
path "/if:interfaces/if:interface/if:name";
}
}
}
notification interface-up {
description "Sent when an interface is activated.";
leaf name {
type leafref {
path "/if:interfaces/if:interface/if:name";
}
}
}
Note that there are no formal YANG statements to identify any data node resources associated with a notification. The "description" statement for the notification SHOULD specify if and how the notification identifies any data node resources associated with the specific event.
请注意，没有正式的语句来标识与通知关联的任何数据节点资源。通知的“description”语句应指定通知是否以及如何标识与特定事件关联的任何数据节点资源。
The YANG "feature" statement is used to define a label for a set of optional functionality within a module. The "if-feature" statement is used in the YANG statements associated with a feature. The description-stmt within a feature-stmt MUST specify any interactions with other features.
“feature”语句用于定义模块内一组可选功能的标签。“if feature”语句用于与某个功能关联的语句中。功能stmt中的描述stmt必须指定与其他功能的任何交互。
The set of YANG features defined in a module should be considered carefully. Very fine granular features increase interoperability 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, then consider moving those objects to a separate module, instead of 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 within the entire YANG library is not as easy to identity. Module names with a common prefix can help readers identity the set of related modules, but this assumes the reader will have discovered and installed all the relevant modules.
如果有一组与阳特性相关联的对象，则考虑将这些对象移动到单独的模块，而不是使用阳特征。请注意，模块中的功能集很容易被读者发现，但整个YANG库中的相关模块集不容易识别。带有公共前缀的模块名称可以帮助读者识别一组相关模块，但前提是读者已经发现并安装了所有相关模块。
Another consideration for deciding whether to create a new module or add a YANG feature is the stability of the module in question. It may be desirable to have a stable base module that is not changed frequently. If new functionality is placed in a separate module, then the base module does not need to be republished. If it is designed as a YANG feature, then the module will need to be republished.
决定是否创建新模块或添加新功能的另一个考虑因素是相关模块的稳定性。可能需要一个不经常更换的稳定的基本模块。如果新功能放在单独的模块中，则不需要重新发布基本模块。如果设计为YANG功能，则需要重新发布模块。
If one feature requires implementation of another feature, then an "if-feature" statement SHOULD be used in the dependent "feature" statement.
如果一个功能需要实现另一个功能，那么在依赖的“功能”语句中应该使用“If-feature”语句。
For example, feature2 requires implementation of feature1:
例如，feature2需要实现feature1：
feature feature1 {
description "Some protocol feature";
}
feature feature1 {
description "Some protocol feature";
}
feature feature2 {
if-feature "feature1";
description "Another protocol feature";
}
feature feature2 {
if-feature "feature1";
description "Another protocol feature";
}
The "min-elements" and "max-elements" statements can be used to control how many list or leaf-list instances are required for a particular data node. YANG constraint statements SHOULD be used to identify conditions that apply to all implementations of the data model. If platform-specific limitations (e.g., the "max-elements" supported for a particular list) are relevant to operations, then a data model definition statement (e.g., "max-ports" leaf) SHOULD be used to identify the limit.
“最小元素”和“最大元素”语句可用于控制特定数据节点需要多少列表或叶列表实例。YANG约束语句应用于确定适用于数据模型的所有实现的条件。如果特定于平台的限制（例如，特定列表支持的“最大元素”）与操作相关，则应使用数据模型定义语句（例如，“最大端口”页）来识别限制。
"must" and "when" YANG statements are used to provide cross-object referential tests. They have very different behavior. The "when" statement causes data node instances to be silently deleted as soon as the condition becomes false. A false "when" expression is not considered to be an error.
“必须”和“当”语句用于提供跨对象引用测试。他们有非常不同的行为。“when”语句使数据节点实例在条件变为false时立即被静默删除。错误的“when”表达式不被视为错误。
The "when" statement SHOULD be used together with "augment" or "uses" statements to achieve conditional model composition. The condition SHOULD be based on static properties of the augmented entry (e.g., list key leafs).
“when”语句应与“augment”或“uses”语句一起使用，以实现条件模型组合。条件应基于扩展项的静态属性（例如，列表键叶）。
The "must" statement causes a datastore validation error if the condition is false. This statement SHOULD be used for enforcing parameter value restrictions that involve more than one data node (e.g., end-time parameter must be after the start-time parameter).
如果条件为false，“must”语句将导致数据存储验证错误。此语句应用于强制执行涉及多个数据节点的参数值限制（例如，结束时间参数必须在开始时间参数之后）。
The YANG "augment" statement is used to define a set of data definition statements that will be added as child nodes of a target data node. The module namespace for these data nodes will be the augmenting module, not the augmented module.
“augment”语句用于定义一组数据定义语句，这些语句将作为目标数据节点的子节点添加。这些数据节点的模块名称空间将是扩充模块，而不是扩充模块。
A top-level "augment" statement SHOULD NOT be used if the target data node is in the same module or submodule as the evaluated "augment" statement. The data definition statements SHOULD be added inline instead.
如果目标数据节点与求值的“augment”语句位于同一模块或子模块中，则不应使用顶级“augment”语句。数据定义语句应该以内联方式添加。
The "augment" statement is often used together with the "when" statement and/or "if-feature" statement to make the augmentation conditional on some portion of the data model.
“augment”语句通常与“when”语句和/或“if-feature”语句一起使用，以使扩展以数据模型的某些部分为条件。
The following example from [RFC7223] shows how a conditional container called "ethernet" is added to the "interface" list only for entries of the type "ethernetCsmacd".
[RFC7223]中的以下示例显示了如何将名为“ethernet”的条件容器添加到“interface”列表中，仅用于“ethernetCsmacd”类型的条目。
augment "/if:interfaces/if:interface" {
when "if:type = 'ianaift:ethernetCsmacd'";
augment "/if:interfaces/if:interface" {
when "if:type = 'ianaift:ethernetCsmacd'";
container ethernet {
leaf duplex {
...
}
}
}
container ethernet {
leaf duplex {
...
}
}
}
YANG has very specific rules about how configuration data can be updated in new releases of a module. These rules allow an "old client" to continue interoperating with a "new server".
YANG对如何在新版本的模块中更新配置数据有非常具体的规则。这些规则允许“旧客户端”继续与“新服务器”进行互操作。
If data nodes are added to an existing entry, the old client MUST NOT be required to provide any mandatory parameters that were not in the original module definition.
如果将数据节点添加到现有条目中，则不能要求旧客户端提供原始模块定义中没有的任何必需参数。
It is possible to add conditional "augment" statements such that the old client would not know about the new condition and would not specify the new condition. The conditional "augment" statement can contain mandatory objects only if the condition is false, unless explicitly requested by the client.
可以添加条件“augment”语句，以便旧客户端不知道新条件，也不指定新条件。只有当条件为false时，条件“augment”语句才能包含强制对象，除非客户机明确请求。
Only a conditional "augment" statement that uses the "when" statement form of a condition can be used in this manner. The YANG features enabled on the server cannot be controlled by the client in any way, so it is not safe to add mandatory augmenting data nodes based on the "if-feature" statement.
只有使用条件的“when”语句形式的条件“augment”语句才能以这种方式使用。服务器上启用的功能不能由客户端以任何方式控制，因此基于“if feature”语句添加强制增强数据节点是不安全的。
The XPath "when" statement condition MUST NOT reference data outside of the target data node because the client does not have any control over this external data.
XPath“when”语句条件不能引用目标数据节点之外的数据，因为客户端对该外部数据没有任何控制权。
In the following dummy example, it is okay to augment the "interface" entry with "mandatory-leaf" because the augmentation depends on support for "some-new-iftype". The old client does not know about this type, so it would never select this type; therefore, it would not add a mandatory data node.
在下面的虚拟示例中，可以使用“mandatory leaf”来扩充“interface”条目，因为扩充依赖于对“somenewiftype”的支持。旧客户端不知道此类型，因此它永远不会选择此类型；因此，它不会添加强制数据节点。
module example-module {
模块示例模块{
yang-version 1.1;
namespace "tag:example.com,2017:example-module";
prefix mymod;
yang-version 1.1;
namespace "tag:example.com,2017:example-module";
prefix mymod;
import iana-if-type { prefix iana; }
import ietf-interfaces { prefix if; }
import iana-if-type { prefix iana; }
import ietf-interfaces { prefix if; }
identity some-new-iftype {
base iana:iana-interface-type;
}
identity some-new-iftype {
base iana:iana-interface-type;
}
augment "/if:interfaces/if:interface" {
when "if:type = 'mymod:some-new-iftype'";
augment "/if:interfaces/if:interface" {
when "if:type = 'mymod:some-new-iftype'";
leaf mandatory-leaf {
type string;
mandatory true;
}
}
}
leaf mandatory-leaf {
type string;
mandatory true;
}
}
}
Note that this practice is safe only for creating data resources. It is not safe for replacing or modifying resources if the client does not know about the new condition. The YANG data model MUST be packaged in a way that requires the client to be aware of the mandatory data nodes if it is aware of the condition for this data. In the example above, the "some-new-iftype" identity is defined in the same module as the "mandatory-leaf" data definition statement.
请注意，这种做法仅适用于创建数据资源。如果客户端不知道新的情况，则更换或修改资源是不安全的。YANG数据模型的打包方式必须要求客户机知道强制数据节点（如果它知道该数据的条件）。在上面的示例中，“somenewiftype”标识在与“mandatory leaf”数据定义语句相同的模块中定义。
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 about "my-module" just because it knows about the "iana-if-type" module.
这种做法对于常见模块（如“iana if type”）中定义的标识是不安全的，因为客户端不需要仅仅因为知道“iana if type”模块就知道“我的模块”。
Per RFC 7950, Section 7.20.3, the YANG "deviation" statement is not allowed to appear in IETF YANG modules, but it can be useful for documenting server capabilities. Deviation statements are not reusable and typically not shared across all platforms.
根据RFC 7950第7.20.3节，IETF YANG模块中不允许出现YANG“偏差”语句，但它可用于记录服务器功能。偏差声明不可重用，通常不在所有平台上共享。
There are several reasons that deviations might be needed in an implementation, e.g., an object cannot be supported on all platforms, or feature delivery is done in multiple development phases. Deviation statements can also be used to add annotations to a module, which does not affect the conformance requirements for the module.
实现中可能需要偏差的原因有很多，例如，无法在所有平台上支持对象，或者功能交付是在多个开发阶段完成的。偏差语句还可用于向模块添加注释，这不会影响模块的一致性要求。
It is suggested that deviation statements be defined in separate modules from regular YANG definitions. This allows the deviations to be platform specific and/or temporary.
建议将偏差声明定义在不同于常规定义的模块中。这允许偏差是平台特定的和/或临时的。
The order that deviation statements are evaluated can affect the result. Therefore, multiple deviation statements in the same module, for the same target object, SHOULD NOT be used.
偏差陈述的评估顺序可能会影响结果。因此，对于同一目标对象，不应在同一模块中使用多个偏差语句。
The "max-elements" statement is intended to describe an architectural limit to the number of list entries. It is not intended to describe platform limitations. It is better to use a "deviation" statement for the platforms that have a hard resource limit.
“max elements”语句旨在描述列表条目数量的体系结构限制。其目的不是描述平台限制。对于具有硬资源限制的平台，最好使用“偏差”语句。
Example documenting platform resource limits:
记录平台资源限制的示例：
Wrong: (max-elements in the list itself)
错误：（列表本身中的最大元素数）
container backups {
list backup {
...
max-elements 10;
...
}
}
container backups {
list backup {
...
max-elements 10;
...
}
}
Correct: (max-elements in a deviation)
正确：（偏差中的最大元素）
deviation /bk:backups/bk:backup {
deviate add {
max-elements 10;
}
}
deviation /bk:backups/bk:backup {
deviate add {
max-elements 10;
}
}
The YANG "extension" statement is used to specify external definitions. This appears in the YANG syntax as an "unknown-statement". Usage of extension statements in a published module needs to be considered carefully.
“extension”语句用于指定外部定义。这在YANG语法中显示为“未知语句”。需要仔细考虑在已发布模块中使用扩展语句。
The following guidelines apply to the usage of YANG extensions:
以下指南适用于YANG extensions的使用：
o The semantics of the extension MUST NOT contradict any YANG statements. Extensions can add semantics not covered by the normal YANG statements.
o 扩展的语义不能与任何杨语句相矛盾。扩展可以添加正常YANG语句中未包含的语义。
o The module containing the extension statement MUST clearly identify the conformance requirements for the extension. It should be clear whether all implementations of the YANG module containing the extension need to also implement the extension. If not, identify what conditions apply that would require implementation of the extension.
o 包含扩展语句的模块必须明确标识扩展的一致性要求。应该清楚的是，是否所有包含扩展的模块的实现都需要实现扩展。如果没有，请确定需要实施扩展的适用条件。
o The extension MUST clearly identify where it can be used within other YANG statements.
o 扩展必须清楚地标识在其他语句中可以使用的位置。
o The extension MUST clearly identify if YANG statements or other extensions are allowed or required within the extension as substatements.
o 扩展必须清楚地标识扩展中是否允许或需要YANG语句或其他扩展作为子语句。
Data can be correlated in various ways, using common data types, common data naming, and common data organization. There are several ways to extend the functionality of a module, based on the degree of coupling between the old and new functionality:
可以使用公共数据类型、公共数据命名和公共数据组织以各种方式关联数据。根据新旧功能之间的耦合程度，有几种扩展模块功能的方法：
o inline: update the module with new protocol-accessible objects. The naming and data organization of the original objects is used. The new objects are in the original module namespace.
o 内联：使用新的协议可访问对象更新模块。使用原始对象的命名和数据组织。新对象位于原始模块命名空间中。
o augment: create a new module with new protocol-accessible objects that augment the original data structure. The naming and data organization of the original objects is used. The new objects are in the new module namespace.
o 扩充：使用新的协议可访问对象创建一个新模块，该对象扩充了原始数据结构。使用原始对象的命名和数据组织。新对象位于新模块命名空间中。
o mirror: create new objects in a new module or the original module, except use a new naming scheme and data location. The naming can be coupled in different ways. Tight coupling is achieved with a "leafref" data type, with the "require-instance" substatement set to "true". This method SHOULD be used.
o 镜像：在新模块或原始模块中创建新对象，但使用新命名方案和数据位置除外。命名可以以不同的方式耦合。通过“leafref”数据类型实现紧密耦合，“require instance”子状态设置为“true”。应该使用这种方法。
If the new data instances are not limited to the values in use in the original data structure, then the "require-instance" substatement MUST be set to "false". Loose coupling is achieved by using key leafs with the same data type as the original data structure. This has the same semantics as setting the "require-instance" substatement to "false".
如果新数据实例不限于原始数据结构中使用的值，则“require instance”子语句必须设置为“false”。松耦合是通过使用与原始数据结构具有相同数据类型的键叶来实现的。这与将“require instance”子语句设置为“false”具有相同的语义。
The relationship between configuration and operational state has been clarified in NMDA [RFC8342].
配置和运行状态之间的关系已在NMDA[RFC8342]中阐明。
Sometimes it is not practical to augment a data structure. For example, the correlated data could have different keys or contain mandatory nodes.
有时扩充数据结构是不实际的。例如，相关数据可能具有不同的键或包含必需的节点。
The following example shows the use of the "leafref" data type for data correlation purposes:
以下示例显示了出于数据关联目的而使用“leafref”数据类型：
Not preferred:
非首选：
list foo {
key name;
leaf name {
type string;
}
...
}
list foo {
key name;
leaf name {
type string;
}
...
}
list foo-addon {
key name;
config false;
leaf name {
type string;
}
...
}
list foo-addon {
key name;
config false;
leaf name {
type string;
}
...
}
Preferred:
首选：
list foo {
key name;
leaf name {
type string;
}
...
}
list foo {
key name;
leaf name {
type string;
}
...
}
list foo-addon {
key name;
config false;
leaf name {
type leafref {
path "/foo/name";
require-instance false;
}
}
leaf addon {
list foo-addon {
key name;
config false;
leaf name {
type leafref {
path "/foo/name";
require-instance false;
}
}
leaf addon {
type string;
mandatory true;
}
}
type string;
mandatory true;
}
}
The modeling of operational state with YANG has been refined over time. At first, only data that has a "config" statement value of "false" was considered to be operational state. This data was not considered to be part of any datastore, which made the YANG XPath definition much more complicated.
随着时间的推移，YANG的运行状态建模已经得到了改进。首先，只有“config”语句值为“false”的数据才被认为是操作状态。这些数据不被认为是任何数据存储的一部分，这使得XPath定义更加复杂。
Operational state is now modeled using YANG according to the new NMDA [RFC8342] and conceptually contained in the operational state datastore, which also includes the operational values of configuration data. There is no longer any need to duplicate data structures to provide separate configuration and operational state sections.
根据新的NMDA[RFC8342]，操作状态现在使用YANG建模，概念上包含在操作状态数据存储中，其中还包括配置数据的操作值。不再需要复制数据结构来提供单独的配置和操作状态部分。
This section describes some data modeling issues related to operational state and guidelines for transitioning YANG data model design to be NMDA compatible.
本节描述了与操作状态相关的一些数据建模问题，以及将数据模型设计转换为NMDA兼容的指南。
If possible, operational state SHOULD be combined with its associated configuration data. This prevents duplication of key leafs and ancestor nodes. It also prevents race conditions for retrieval of dynamic entries and allows configuration and operational state to be retrieved together with minimal message overhead.
如果可能，操作状态应与其相关的配置数据相结合。这可以防止关键叶和祖先节点的重复。它还可以防止检索动态条目的竞争条件，并允许以最小的消息开销检索配置和操作状态。
container foo {
...
// contains "config true" and "config false" nodes that have
// no corresponding "config true" object (e.g., counters)
}
container foo {
...
// contains "config true" and "config false" nodes that have
// no corresponding "config true" object (e.g., counters)
}
If possible, the same data type SHOULD be used to represent the configured value and the operational value, for a given leaf or leaf-list object.
如果可能，应使用相同的数据类型来表示给定叶或叶列表对象的配置值和操作值。
Sometimes the configured value set is different than the operational value set for that object, for example, the "admin-status" and "oper-status" leafs in [RFC8343]. In this case, a separate object MAY be used to represent the configured and operational values.
有时，配置的值集不同于该对象的操作值集，例如，“管理状态”和“操作状态”页[RFC8343]。在这种情况下，可以使用单独的对象来表示配置值和操作值。
Sometimes the list keys are not identical for configuration data and the corresponding operational state. In this case, separate lists MAY be used to represent the configured and operational values.
有时，配置数据和相应操作状态的列表键不相同。在这种情况下，可以使用单独的列表来表示配置值和操作值。
If it is not possible to combine configuration and operational state, then the keys used to represent list entries SHOULD be the same type. The "leafref" data type SHOULD be used in operational state for key leafs that have corresponding configuration instances. The "require-instance" statement MAY be set to "false" (in YANG 1.1 modules only) to indicate instances are allowed in the operational state that do not exist in the associated configuration data.
如果无法组合配置和操作状态，则用于表示列表项的键应为同一类型。对于具有相应配置实例的关键LEAF，应在操作状态下使用“leafref”数据类型。“require instance”语句可以设置为“false”（仅在YANG 1.1模块中），以指示允许实例处于运行状态，但相关配置数据中不存在这些实例。
The need to replicate objects or define different operational state objects depends on the data model. It is not possible to define one approach that will be optimal for all data models.
复制对象或定义不同操作状态对象的需要取决于数据模型。不可能定义一种适用于所有数据模型的最佳方法。
Designers SHOULD describe and justify any NMDA exceptions in detail, such as the use of separate subtrees and/or separate leafs. The "description" statements for both the configuration and the operational state SHOULD be used for this purpose.
设计者应详细描述并证明任何NMDA例外情况，例如使用单独的子树和/或单独的叶子。配置和运行状态的“说明”语句都应用于此目的。
YANG modules SHOULD be designed with the assumption that they will be used on servers supporting the operational state datastore. With this in mind, YANG modules SHOULD define "config false" nodes wherever they make sense to the data model. "Config false" nodes SHOULD NOT be defined to provide the operational value for configuration nodes, except when the value space of a configured and operational value may differ, in which case a distinct "config false" node SHOULD be defined to hold the operational value for the configured node.
YANG模块的设计应假定它们将在支持运行状态数据存储的服务器上使用。记住这一点，模块应该在对数据模型有意义的地方定义“config false”节点。“Config false”节点不应定义为提供配置节点的操作值，除非配置值和操作值的值空间可能不同，在这种情况下，应定义不同的“Config false”节点来保存配置节点的操作值。
The following guidelines are meant to help modelers develop YANG modules that will maximize the utility of the model with both current and new implementations.
以下指南旨在帮助建模人员开发模块，使模型在当前和新实现中的效用最大化。
New modules and modules that are not concerned with the operational state of configuration information SHOULD immediately be structured to be NMDA compatible, as described in Section 4.23.1. This transition MAY be deferred if the module does not contain any configuration datastore objects.
如第4.23.1节所述，新模块和与配置信息运行状态无关的模块应立即构建为与NMDA兼容。如果模块不包含任何配置数据存储对象，此转换可能会延迟。
The remaining are options that MAY be followed during the time that NMDA mechanisms are being defined.
剩下的是在定义NMDA机制期间可能遵循的选项。
(a) Modules that require immediate support for the NMDA features SHOULD be structured for NMDA. A temporary non-NMDA version of this type of module MAY exist, as either an existing model or a model created by hand or with suitable tools that mirror the current modeling strategies. Both the NMDA and the non-NMDA modules SHOULD 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 use of the non-NMDA module will allow temporary bridging of the time period until NMDA implementations are available.
(a) 需要立即支持NMDA功能的模块应针对NMDA构建。此类模块的临时非NMDA版本可能存在，既可以是现有模型，也可以是手工创建的模型，或者是使用反映当前建模策略的适当工具创建的模型。NMDA和非NMDA模块应在同一文件中发布，NMDA模块在文件主体中，非NMDA模块在非规范性附录中。使用非NMDA模块将允许临时桥接时间段，直到NMDA实施可用。
(b) For published models, the model should be republished with an NMDA-compatible structure, deprecating non-NMDA constructs. For example, the "ietf-interfaces" model in [RFC7223] has been restructured as an NMDA-compatible model in [RFC8343]. The "/interfaces-state" hierarchy has been marked "status deprecated". Models that mark their "/foo-state" hierarchy with "status deprecated" will allow NMDA-capable implementations to avoid the cost of duplicating the state nodes, while enabling non-NMDA-capable implementations to utilize them for access to the operational values.
(b) 对于已发布的模型，应使用与NMDA兼容的结构重新发布模型，不推荐非NMDA构造。例如，[RFC7223]中的“ietf接口”模型已在[RFC8343]中重组为NMDA兼容模型。“/接口状态”层次结构已标记为“状态不推荐”。将“/foo state”层次结构标记为“status deprecated”的模型将允许支持NMDA的实现避免复制状态节点的成本，同时允许不支持NMDA的实现利用它们访问操作值。
(c) For models that augment models that have not been structured with the NMDA, the modeler will have to consider the structure of the base model and the guidelines listed above. Where possible, such models should move to new revisions of the base model that are NMDA compatible. When that is not possible, augmenting "state" containers SHOULD be avoided, with the expectation that the base model will be re-released with the state containers marked as deprecated. It is RECOMMENDED to augment only the "/foo" hierarchy of the base model. Where this recommendation cannot be followed, then any new "state" elements SHOULD be included in their own module.
(c) 对于那些没有用NMDA构造模型的模型，建模者将不得不考虑基础模型的结构和上面列出的指导方针。在可能的情况下，此类模型应采用与NMDA兼容的基础模型的新版本。如果这是不可能的，那么应该避免增加“状态”容器，期望基本模型将被重新发布，状态容器标记为不推荐。建议仅扩展基本模型的“/foo”层次结构。如果无法遵循此建议，则任何新的“状态”元素都应包含在它们自己的模块中。
A temporary non-NMDA module allows a non-NMDA-aware client to access operational state from an NMDA-compliant server. It contains the top-level "config false" data nodes that would have been defined in a legacy YANG module (before NMDA).
临时非NMDA模块允许非NMDA感知客户端从符合NMDA的服务器访问运行状态。它包含在遗留模块（在NMDA之前）中定义的顶级“config false”数据节点。
A server that needs to support both NMDA and non-NMDA clients can advertise both the new NMDA module and the temporary non-NMDA module. A non-NMDA client can use separate "foo" and "foo-state" subtrees, except the "foo-state" subtree is located in a different (temporary)
需要同时支持NMDA和非NMDA客户端的服务器可以公布新的NMDA模块和临时非NMDA模块。非NMDA客户端可以使用单独的“foo”和“foo state”子树，但“foo state”子树位于不同的（临时）目录中除外
module. The NMDA module can be used by a non-NMDA client to access the conventional configuration datastores and the deprecated <get> operation to access nested "config false" data nodes.
单元非NMDA客户端可以使用NMDA模块访问传统配置数据存储，也可以使用弃用的<get>操作访问嵌套的“config false”数据节点。
To create the temporary non-NMDA model from an NMDA model, the following steps can be taken:
要从NMDA模型创建临时非NMDA模型，可以采取以下步骤：
o Change the module name by appending "-state" to the original module name
o 通过在原始模块名称后添加“-state”来更改模块名称
o Change the namespace by appending "-state" to the original namespace value
o 通过将“-state”附加到原始名称空间值来更改名称空间
o Change the prefix by appending "-s" to the original prefix value
o 通过将“-s”附加到原始前缀值来更改前缀
o Add an import to the original module (e.g., for typedef definitions)
o 向原始模块添加导入（例如，对于typedef定义）
o Retain or create only the top-level nodes that have a "config" statement value "false". These subtrees represent "config false" data nodes that were combined into the configuration subtree; therefore, they are not available to non-NMDA aware clients. Set the "status" statement to "deprecated" for each new node.
o 仅保留或创建具有“config”语句值“false”的顶级节点。这些子树表示组合到配置子树中的“config false”数据节点；因此，不支持NMDA的客户端无法使用这些功能。为每个新节点将“status”语句设置为“deprecated”。
o The module description SHOULD clearly identify the module as a temporary non-NMDA module
o 模块说明应清楚地将模块标识为临时非NMDA模块
Create an NMDA-compliant module, using combined configuration and state subtrees, whenever possible.
尽可能使用组合配置和状态子树创建符合NMDA的模块。
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain "config false" nodes as needed
}
}
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain "config false" nodes as needed
}
}
Do not remove non-compliant objects from existing modules. Instead, change the status to "deprecated". At some point, usually after 1 year, the status MAY be changed to "obsolete".
不要从现有模块中删除不兼容的对象。相反，将状态更改为“已弃用”。在某些情况下，通常在1年后，状态可能会更改为“过时”。
Old Module:
旧模块：
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
}
container foo {
// configuration data child nodes
}
container foo-state {
config false;
// operational state child nodes
}
}
container foo-state {
config false;
// operational state child nodes
}
}
Converted NMDA Module:
转换后的NMDA模块：
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
module example-foo {
namespace "urn:example.com:params:xml:ns:yang:example-foo";
prefix "foo";
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain "config false" nodes as needed
// will contain any data nodes from old foo-state
}
container foo {
// configuration data child nodes
// operational value in operational state datastore only
// may contain "config false" nodes as needed
// will contain any data nodes from old foo-state
}
// keep original foo-state but change status to deprecated
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
// keep original foo-state but change status to deprecated
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
Create a new module that contains the top-level operational state data nodes that would have been available before they were combined with configuration data nodes (to be NMDA compliant).
创建一个新模块，该模块包含顶级运行状态数据节点，这些节点在与配置数据节点组合（符合NMDA）之前是可用的。
module example-foo-state {
namespace "urn:example.com:params:xml:ns:yang:example-foo-state";
prefix "foo-s";
module example-foo-state {
namespace "urn:example.com:params:xml:ns:yang:example-foo-state";
prefix "foo-s";
// import new or converted module; not used in this example
import example-foo { prefix foo; }
// import new or converted module; not used in this example
import example-foo { prefix foo; }
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
container foo-state {
config false;
status deprecated;
// operational state child nodes
}
}
It is generally likely that certain YANG statements require more runtime resources than other statements. Although there are no performance requirements for YANG validation, the following information MAY be considered when designing YANG data models:
通常，某些语句比其他语句需要更多的运行时资源。虽然YANG验证没有性能要求，但在设计YANG数据模型时，可以考虑以下信息：
o Lists are generally more expensive than containers
o 列表通常比容器更昂贵
o "when" statement evaluation is generally more expensive than "if-feature" or "choice" statements
o “when”语句评估通常比“if-feature”或“choice”语句更昂贵
o "must" statements are generally more expensive than "min-entries", "max-entries", "mandatory", or "unique" statements
o “必须”语句通常比“最小条目”、“最大条目”、“必需”或“唯一”语句更昂贵
o "identityref" leafs are generally more expensive than "enumeration" leafs
o “identityref”叶通常比“枚举”叶更昂贵
o "leafref" and "instance-identifier" types with "require-instance" set to true are generally more expensive than if "require-instance" is set to false
o “require instance”设置为true的“leafref”和“instance identifier”类型通常比“require instance”设置为false更昂贵
Only the modules imported by a particular module can be assumed to be present in an implementation. An open system MAY include any combination of YANG modules.
只有由特定模块导入的模块才能假定存在于实现中。开放式系统可包括模块的任何组合。
The set of guidelines for YANG 1.1 will grow as operational experience is gained with the new language features. This section contains an initial set of guidelines for new YANG 1.1 language features.
YANG 1.1的指南集将随着新语言功能的运行经验的积累而不断增长。本节包含新YANG 1.1语言功能的初始指导原则。
Standard modules SHOULD NOT import multiple revisions of the same module into a module. This MAY be done if independent definitions (e.g., enumeration typedefs) from specific revisions are needed in the importing module.
标准模块不应将同一模块的多个修订导入到一个模块中。如果导入模块中需要特定修订版的独立定义（例如枚举类型定义），则可以执行此操作。
The YANG 1.1 feature logic is much more expressive than YANG 1.0. A "description" statement SHOULD describe the "if-feature" logic in text, to help readers understand the module.
YANG 1.1功能逻辑比YANG 1.0更具表现力。“描述”语句应在文本中描述“如果功能”逻辑，以帮助读者理解模块。
YANG features SHOULD be used instead of the "when" statement, if possible. Features are advertised by the server, and objects conditional by the "if-feature" statement are conceptually grouped together. There is no such commonality supported for "when" statements.
如果可能的话，应该使用YANG特性，而不是“when”语句。特性由服务器播发，而由“if feature”语句设置条件的对象在概念上分组在一起。“when”语句不支持这种通用性。
Features generally require less server implementation complexity and runtime resources than objects that use "when" statements. Features are generally static (i.e., set when a module is loaded and not changed at runtime). However, every client edit might cause a "when" statement result to change.
与使用“when”语句的对象相比，特性通常需要更少的服务器实现复杂性和运行时资源。特性通常是静态的（即，在加载模块时设置，并且在运行时不更改）。但是，每次客户端编辑都可能导致“when”语句结果更改。
The "anyxml" statement MUST NOT be used to represent a conceptual subtree of YANG data nodes. The "anydata" statement MUST be used for this purpose.
“anyxml”语句不能用于表示数据节点的概念子树。“anydata”语句必须用于此目的。
The use of "action" statements or "rpc" statements is a subjective design decision. RPC operations are not associated with any particular data node. Actions are associated with a specific data node definition. An "action" statement SHOULD be used if the protocol operation is specific to a subset of all data nodes instead of all possible data nodes.
使用“action”语句或“rpc”语句是一种主观的设计决策。RPC操作不与任何特定数据节点关联。操作与特定的数据节点定义相关联。如果协议操作特定于所有数据节点的子集，而不是所有可能的数据节点，则应使用“action”语句。
The same action name MAY be used in different definitions within different data node. For example, a "reset" action defined with a data node definition for an interface might have different parameters than for a power supply or a VLAN. The same action name SHOULD be used to represent similar semantics.
相同的操作名称可以在不同数据节点的不同定义中使用。例如，使用接口的数据节点定义定义的“重置”操作可能具有与电源或VLAN不同的参数。应该使用相同的操作名称来表示相似的语义。
The NETCONF Access Control Model (NACM) [RFC8341] does not support parameter-based access control for RPC operations. The user is given permission (or not) to invoke the RPC operation with any parameters. For example, if each client is only allowed to reset their own interface, then NACM cannot be used.
NETCONF访问控制模型（NACM）[RFC8341]不支持RPC操作的基于参数的访问控制。用户被授予（或不授予）使用任何参数调用RPC操作的权限。例如，如果只允许每个客户端重置其自己的接口，则不能使用NACM。
For example, NACM cannot enforce access control based on the value of the "interface" parameter, only the "reset" operation itself:
例如，NACM无法基于“接口”参数的值实施访问控制，只有“重置”操作本身：
rpc reset {
input {
leaf interface {
type if:interface-ref;
mandatory true;
description "The interface to reset.";
}
}
}
rpc reset {
input {
leaf interface {
type if:interface-ref;
mandatory true;
description "The interface to reset.";
}
}
}
However, NACM can enforce access control for individual interface instances, using a "reset" action. If the user does not have read access to the specific "interface" instance, then it cannot invoke the "reset" action for that interface instance:
但是，NACM可以使用“重置”操作对单个接口实例实施访问控制。如果用户没有特定“接口”实例的读取权限，则无法调用该接口实例的“重置”操作：
container interfaces {
list interface {
...
action reset { }
}
}
container interfaces {
list interface {
...
action reset { }
}
}
YANG modules can change over time. Typically, new data model definitions are needed to support new features. YANG update rules defined in Section 11 of [RFC7950] MUST be followed for published modules. They MAY be followed for unpublished modules.
杨氏模量可以随时间变化。通常，需要新的数据模型定义来支持新功能。发布的模块必须遵循[RFC7950]第11节中定义的更新规则。未发布的模块可能会遵循这些规则。
The YANG update rules only apply to published module revisions. Each organization will have their own way to identify published work that is considered to be stable and unpublished work that is considered to
更新规则仅适用于已发布的模块修订。每个组织都有自己的方法来确定被认为是稳定的已发表作品和被认为是稳定的未发表作品
be unstable. For example, in the IETF, the RFC document is used for published work, and the I-D is used for unpublished work.
不稳定。例如，在IETF中，RFC文档用于已发布的工作，I-D用于未发布的工作。
The following registration in the "ns" subregistry of the "IETF XML Registry" [RFC3688] was detailed in [RFC6087] and has been updated by IANA to reference this document.
以下在“IETF XML注册表”[RFC3688]的“ns”子区中的注册在[RFC6087]中有详细说明，并已由IANA更新以参考本文件。
URI: urn:ietf:params:xml:ns:yang:ietf-template
URI: urn:ietf:params:xml:ns:yang:ietf-template
Registrant Contact: The IESG.
注册人联系人：IESG。
XML: N/A, the requested URI is an XML namespace.
XML:N/A，请求的URI是一个XML名称空间。
The following assignment was detailed in [RFC6087] and has been updated by IANA in the "YANG Module Names" registry. This document has also been added as a reference for the "YANG Module Names" registry itself as it contains the template necessary for registration in Appendix B.
以下分配在[RFC6087]中有详细说明，并已由IANA在“YANG模块名称”注册表中更新。本文件还作为“YANG模块名称”注册表本身的参考添加，因为它包含附录B中注册所需的模板。
+-----------+-------------------------------------------+
| Field | Value |
+-----------+-------------------------------------------+
| Name | ietf-template |
| Namespace | urn:ietf:params:xml:ns:yang:ietf-template |
| Prefix | temp |
| Reference | RFC 8407 |
+-----------+-------------------------------------------+
+-----------+-------------------------------------------+
| Field | Value |
+-----------+-------------------------------------------+
| Name | ietf-template |
| Namespace | urn:ietf:params:xml:ns:yang:ietf-template |
| Prefix | temp |
| Reference | RFC 8407 |
+-----------+-------------------------------------------+
YANG Registry Assignment
杨氏注册分配
This document defines documentation guidelines for NETCONF or RESTCONF content defined with the YANG data modeling language; therefore, it does not introduce any new or increased security risks into the management system.
本文档定义了使用数据建模语言定义的NETCONF或RESTCONF内容的文档指南；因此，它不会给管理系统带来任何新的或增加的安全风险。
[ID-Guidelines] Housley, R., "Guidelines to Authors of Internet-Drafts", December 2010, <https://www.ietf.org/standards/ids/guidelines/>.
[ID指南]Housley，R.，“互联网草稿作者指南”，2010年12月<https://www.ietf.org/standards/ids/guidelines/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[RFC3688]Mealling，M.，“IETF XML注册表”，BCP 81，RFC 3688，DOI 10.17487/RFC3688，2004年1月<https://www.rfc-editor.org/info/rfc3688>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.
[RFC3986]Berners Lee，T.，Fielding，R.，和L.Masinter，“统一资源标识符（URI）：通用语法”，STD 66，RFC 3986，DOI 10.17487/RFC3986，2005年1月<https://www.rfc-editor.org/info/rfc3986>.
[RFC5378] Bradner, S., Ed. and J. Contreras, Ed., "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, DOI 10.17487/RFC5378, November 2008, <https://www.rfc-editor.org/info/rfc5378>.
[RFC5378]Bradner，S.，Ed.和J.Contreras，Ed.，“向IETF信托提供的权利出资人”，BCP 78，RFC 5378，DOI 10.17487/RFC5378，2008年11月<https://www.rfc-editor.org/info/rfc5378>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.
[RFC6020]Bjorklund，M.，Ed.“YANG-网络配置协议的数据建模语言（NETCONF）”，RFC 6020，DOI 10.17487/RFC6020，2010年10月<https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6241]Enns，R.，Ed.，Bjorklund，M.，Ed.，Schoenwaeld，J.，Ed.，和A.Bierman，Ed.，“网络配置协议（NETCONF）”，RFC 6241，DOI 10.17487/RFC6241，2011年6月<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.
[RFC6242]Wasserman，M.“在安全外壳上使用NETCONF协议（SSH）”，RFC 6242，DOI 10.17487/RFC6242，2011年6月<https://www.rfc-editor.org/info/rfc6242>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>.
[RFC7950]Bjorklund，M.，Ed.“YANG 1.1数据建模语言”，RFC 7950，DOI 10.17487/RFC7950，2016年8月<https://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8040]Bierman，A.，Bjorklund，M.，和K.Watsen，“RESTCONF协议”，RFC 8040，DOI 10.17487/RFC8040，2017年1月<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8174]Leiba，B.，“RFC 2119关键词中大写与小写的歧义”，BCP 14，RFC 8174，DOI 10.17487/RFC8174，2017年5月<https://www.rfc-editor.org/info/rfc8174>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8342]Bjorklund，M.，Schoenwaeld，J.，Shafer，P.，Watsen，K.，和R.Wilton，“网络管理数据存储体系结构（NMDA）”，RFC 8342，DOI 10.17487/RFC8342，2018年3月<https://www.rfc-editor.org/info/rfc8342>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8446]Rescorla，E.“传输层安全（TLS）协议版本1.3”，RFC 8446，DOI 10.17487/RFC8446，2018年8月<https://www.rfc-editor.org/info/rfc8446>.
[W3C.REC-xpath] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", W3C Recommendation REC-xpath-19991116, November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[W3C.REC xpath]Clark，J.和S.DeRose，“XML路径语言（xpath）1.0版”，W3C建议REC-xpath-19991116，1999年11月<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[IANA-MOD-NAMES] IANA, "YANG Module Names", <https://www.iana.org/assignments/yang-parameters/>.
[IANA-MOD-NAME]IANA，“阳模块名称”<https://www.iana.org/assignments/yang-parameters/>.
[IANA-XML] IANA, "IETF XML Registry", <https://www.iana.org/assignments/xml-registry/>.
[IANA-XML]IANA，“IETF XML注册表”<https://www.iana.org/assignments/xml-registry/>.
[RFC-STYLE] RFC Editor, "Style Guide", <http://www.rfc-editor.org/styleguide/>.
[RFC-STYLE]RFC编辑器，“样式指南”<http://www.rfc-editor.org/styleguide/>.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, <https://www.rfc-editor.org/info/rfc2026>.
[RFC2026]Bradner，S.，“互联网标准过程——第3版”，BCP 9，RFC 2026，DOI 10.17487/RFC2026，1996年10月<https://www.rfc-editor.org/info/rfc2026>.
[RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 4151, DOI 10.17487/RFC4151, October 2005, <https://www.rfc-editor.org/info/rfc4151>.
[RFC4151]Kindberg，T.和S.Hawke，“标记”URI方案，RFC 4151，DOI 10.17487/RFC4151，2005年10月<https://www.rfc-editor.org/info/rfc4151>.
[RFC4181] Heard, C., Ed., "Guidelines for Authors and Reviewers of MIB Documents", BCP 111, RFC 4181, DOI 10.17487/RFC4181, September 2005, <https://www.rfc-editor.org/info/rfc4181>.
[RFC4181]Heard，C.，Ed.，“MIB文件的作者和评审者指南”，BCP 111，RFC 4181，DOI 10.17487/RFC4181，2005年9月<https://www.rfc-editor.org/info/rfc4181>.
[RFC6087] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", RFC 6087, DOI 10.17487/RFC6087, January 2011, <https://www.rfc-editor.org/info/rfc6087>.
[RFC6087]Bierman，A.，“YANG数据模型文件的作者和评审者指南”，RFC 6087，DOI 10.17487/RFC6087，2011年1月<https://www.rfc-editor.org/info/rfc6087>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>.
[RFC6991]Schoenwaeld，J.，Ed.，“常见杨数据类型”，RFC 6991，DOI 10.17487/RFC69911913年7月<https://www.rfc-editor.org/info/rfc6991>.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, <https://www.rfc-editor.org/info/rfc7223>.
[RFC7223]Bjorklund，M.，“用于接口管理的YANG数据模型”，RFC 7223，DOI 10.17487/RFC7223，2014年5月<https://www.rfc-editor.org/info/rfc7223>.
[RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, DOI 10.17487/RFC7322, September 2014, <https://www.rfc-editor.org/info/rfc7322>.
[RFC7322]Flanagan，H.和S.Ginoza，“RFC风格指南”，RFC 7322，DOI 10.17487/RFC7322，2014年9月<https://www.rfc-editor.org/info/rfc7322>.
[RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., "RFC Streams, Headers, and Boilerplates", RFC 7841, DOI 10.17487/RFC7841, May 2016, <https://www.rfc-editor.org/info/rfc7841>.
[RFC7841]Halpern，J.，Ed.，Daigle，L.，Ed.，和O.Kolkman，Ed.，“RFC流，标题和样板”，RFC 7841，DOI 10.17487/RFC78412016年5月<https://www.rfc-editor.org/info/rfc7841>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.
[RFC8126]Cotton，M.，Leiba，B.，和T.Narten，“在RFC中编写IANA考虑事项部分的指南”，BCP 26，RFC 8126，DOI 10.17487/RFC8126，2017年6月<https://www.rfc-editor.org/info/rfc8126>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.
[RFC8340]Bjorklund，M.和L.Berger，编辑，“杨树图”，BCP 215，RFC 8340，DOI 10.17487/RFC8340，2018年3月<https://www.rfc-editor.org/info/rfc8340>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8341]Bierman，A.和M.Bjorklund，“网络配置访问控制模型”，STD 91，RFC 8341，DOI 10.17487/RFC8341，2018年3月<https://www.rfc-editor.org/info/rfc8341>.
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.
[RFC8343]Bjorklund，M.，“用于接口管理的YANG数据模型”，RFC 8343，DOI 10.17487/RFC8343，2018年3月<https://www.rfc-editor.org/info/rfc8343>.
[RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for Routing Management (NMDA Version)", RFC 8349, DOI 10.17487/RFC8349, March 2018, <https://www.rfc-editor.org/info/rfc8349>.
[RFC8349]Lhotka，L.，Lindem，A.，和Y.Qu，“路由管理的YANG数据模型（NMDA版本）”，RFC 8349，DOI 10.17487/RFC8349，2018年3月<https://www.rfc-editor.org/info/rfc8349>.
This section is adapted from RFC 4181.
本节改编自RFC 4181。
The purpose of a YANG module review is to review the YANG module for both technical correctness and adherence to IETF documentation requirements. The following checklist may be helpful when reviewing an I-D:
YANG模块审查的目的是审查YANG模块的技术正确性和是否符合IETF文件要求。审查身份证时，以下检查表可能会有所帮助：
o I-D Boilerplate -- verify that the document contains the required I-D boilerplate (see <https://www.ietf.org/id-info/ guidelines.html>), including the appropriate statement to permit publication as an RFC, and that the I-D boilerplate does not contain references or section numbers.
o I-D样板--验证文档是否包含所需的I-D样板（请参阅<https://www.ietf.org/id-info/ guidelines.html>），包括允许作为RFC发布的适当声明，以及I-D样板文件不包含参考或章节号。
o Abstract -- verify that the abstract does not contain references, that it does not have a section number, and that its content follows the guidelines in <https://www.ietf.org/id-info/ guidelines.html>.
o 摘要--验证摘要是否不包含引用，是否没有节号，以及其内容是否遵循中的指导原则<https://www.ietf.org/id-info/ guidelines.html>。
o Copyright Notice -- verify that the document has the appropriate text regarding the rights that document contributors provide to the IETF Trust [RFC5378]. Verify that it contains the full IETF Trust copyright notice at the beginning of the document. The IETF Trust Legal Provisions (TLP) can be found at:
o 版权声明——验证文档是否包含与文档贡献者向IETF信托基金提供的权利相关的适当文本[RFC5378]。验证文件开头是否包含完整的IETF信托版权声明。IETF信托法律条款（TLP）可在以下网址找到：
<https://trustee.ietf.org/license-info/>
<https://trustee.ietf.org/license-info/>
o Security Considerations section -- verify that the document uses the latest approved template from the Operations and Management (OPS) area website (see <https://trac.ietf.org/area/ops/trac/wiki/ yang-security-guidelines>) and that the guidelines therein have been followed.
o 安全注意事项部分--验证文档是否使用运营和管理（OPS）区域网站上最新批准的模板（请参阅<https://trac.ietf.org/area/ops/trac/wiki/ yang security guidelines>），并已遵守其中的指南。
o IANA Considerations section -- this section must always be present. For each module within the document, ensure that the IANA Considerations section contains entries for the following IANA registries:
o IANA注意事项部分——此部分必须始终存在。对于文档中的每个模块，确保IANA注意事项部分包含以下IANA注册的条目：
XML Namespace Registry: Register the YANG module namespace.
XML名称空间注册表：注册模块名称空间。
YANG Module Registry: Register the YANG module name, prefix, namespace, and RFC number, according to the rules specified in [RFC6020].
YANG模块注册表：根据[RFC6020]中指定的规则注册YANG模块名称、前缀、命名空间和RFC编号。
o References -- verify that the references are properly divided between normative and informative references, that RFCs 2119 and 8174 are included as normative references if the terminology defined therein is used in the document, that all references required by the boilerplate are present, that all YANG modules containing imported items are cited as normative references, and that all citations point to the most current RFCs, unless there is a valid reason to do otherwise (for example, it is okay to include an informative reference to a previous version of a specification to help explain a feature included for backward compatibility). Be sure citations for all imported modules are present somewhere in the document text (outside the YANG module). If a YANG module contains reference or "description" statements that refer to an I-D, then the I-D is included as an informative reference.
o 参考文件——验证参考文件是否正确划分为规范性参考文件和资料性参考文件，如果文件中使用了RFCs 2119和8174中定义的术语，则RFCs 2119和8174将作为规范性参考文件包括在内，样板文件要求的所有参考文件均已存在，包含导入项的所有模块均引用为规范性引用，所有引用均指向最新的RFC，除非有正当理由这样做（例如，可以包含对规范先前版本的信息性引用，以帮助解释包含的向后兼容性功能）. 确保所有导入模块的引用都出现在文档文本中的某个位置（模块之外）。如果模块包含引用I-D的引用或“描述”语句，则I-D将作为信息性引用包含在内。
o License -- verify that the document contains the Simplified BSD License in each YANG module or submodule. Some guidelines related to this requirement are described in Section 3.1. Make sure that the correct year is used in all copyright dates. Use the approved text from the latest TLP document, which can be found at:
o 许可证--验证文档在每个模块或子模块中是否包含简化的BSD许可证。第3.1节描述了与此要求相关的一些指南。确保在所有版权日期中使用正确的年份。使用最新TLP文件中的批准文本，可在以下网址找到：
<https://trustee.ietf.org/license-info/>
<https://trustee.ietf.org/license-info/>
o Other Issues -- check for any issues mentioned in <https://www.ietf.org/id-info/checklist.html> that are not covered elsewhere.
o 其他问题--检查中提到的任何问题<https://www.ietf.org/id-info/checklist.html>其他地方没有涉及到。
o Technical Content -- review the actual technical content for compliance with the guidelines in this document. The use of a YANG module compiler is recommended when checking for syntax errors. A list of freely available tools and other information, including formatting advice, can be found at:
o 技术内容——检查实际技术内容是否符合本文档中的指南。检查语法错误时，建议使用YANG模块编译器。免费提供的工具和其他信息列表，包括格式建议，可在以下位置找到：
<https://trac.ietf.org/trac/netconf/wiki>
and
<https://trac.ietf.org/trac/netmod/wiki>
<https://trac.ietf.org/trac/netconf/wiki>
and
<https://trac.ietf.org/trac/netmod/wiki>
Checking for correct syntax, however, is only part of the job. It is just as important to actually read the YANG module document from the point of view of a potential implementor. It is particularly important to check that "description" statements are sufficiently clear and unambiguous to allow interoperable implementations to be created.
然而，检查语法是否正确只是工作的一部分。从潜在实现者的角度实际阅读YANG模块文档同样重要。特别重要的是检查“描述”语句是否足够清晰和明确，以允许创建可互操作的实现。
<CODE BEGINS> file "ietf-template@2016-03-20.yang"
<CODE BEGINS> file "ietf-template@2016-03-20.yang"
module ietf-template {
yang-version 1.1;
module ietf-template {
yang-version 1.1;
// replace this string with a unique namespace URN value
//用唯一的命名空间URN值替换此字符串
namespace "urn:ietf:params:xml:ns:yang:ietf-template";
namespace "urn:ietf:params:xml:ns:yang:ietf-template";
// replace this string, and try to pick a unique prefix
//替换此字符串，并尝试选择唯一的前缀
prefix temp;
前缀temp；
// import statements here: e.g.,
// import ietf-yang-types { prefix yang; }
// import ietf-inet-types { prefix inet; }
// identify the IETF working group if applicable
// import statements here: e.g.,
// import ietf-yang-types { prefix yang; }
// import ietf-inet-types { prefix inet; }
// identify the IETF working group if applicable
organization "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
组织“IETF NETMOD（NETCONF数据建模语言）工作组”；
// update this contact statement with your info
//使用您的信息更新此联系人声明
contact
"WG Web: <http://datatracker.ietf.org/wg/your-wg-name/>
WG List: <mailto:your-wg-name@ietf.org>
contact
"WG Web: <http://datatracker.ietf.org/wg/your-wg-name/>
WG List: <mailto:your-wg-name@ietf.org>
Editor: your-name
<mailto:your-email@example.com>";
Editor: your-name
<mailto:your-email@example.com>";
// replace the first sentence in this description statement.
// replace the copyright notice with the most recent
// version, if it has been updated since the publication
// of this document
// replace the first sentence in this description statement.
// replace the copyright notice with the most recent
// version, if it has been updated since the publication
// of this document
description "This module defines a template for other YANG modules.
description“此模块定义了其他模块的模板。
Copyright (c) <insert year> IETF Trust and the persons identified as authors of the code. All rights reserved.
版权所有（c）<插入年份>IETF信托和被确定为代码作者的人员。版权所有。
Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions
根据IETF信托法律条款第4.c节规定的简化BSD许可证中包含的许可条款，允许以源代码和二进制格式重新分发和使用，无论是否修改
Relating to IETF Documents (http://trustee.ietf.org/license-info).
与IETF文件相关(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices.";
此模块的此版本是RFC XXXX的一部分；有关完整的法律通知，请参见RFC本身。“；
// RFC Ed.: replace XXXX with actual RFC number and remove
// this note
// RFC Ed.: replace XXXX with actual RFC number and remove
// this note
// replace '2016-03-20' with the module publication date
// the format is (year-month-day)
// replace '2016-03-20' with the module publication date
// the format is (year-month-day)
revision 2016-03-20 {
description
"what changed in this revision";
reference "RFC XXXX: <Replace With Document Title>";
}
revision 2016-03-20 {
description
"what changed in this revision";
reference "RFC XXXX: <Replace With Document Title>";
}
// extension statements
// feature statements
// identity statements
// typedef statements
// grouping statements
// data definition statements
// augment statements
// rpc statements
// notification statements
// DO NOT put deviation statements in a published module
}
// extension statements
// feature statements
// identity statements
// typedef statements
// grouping statements
// data definition statements
// augment statements
// rpc statements
// notification statements
// DO NOT put deviation statements in a published module
}
<CODE ENDS>
<代码结束>
Acknowledgments
致谢
The structure and contents of this document are adapted from "Guidelines for Authors and Reviewers of MIB Documents" [RFC4181], by C. M. Heard.
本文件的结构和内容改编自C.M.Heard的“MIB文件的作者和评审者指南”[RFC4181]。
The working group thanks Martin Bjorklund, Juergen Schoenwaelder, Ladislav Lhotka, Jernej Tuljak, Lou Berger, Robert Wilton, Kent Watsen, and William Lupton for their extensive reviews and contributions to this document.
工作组感谢Martin Bjorklund、Juergen Schoenwaeld、Ladislav Lhotka、Jernej Tuljak、Lou Berger、Robert Wilton、Kent Watsen和William Lupton对本文件的广泛审查和贡献。
Author's Address
作者地址
Andy Bierman YumaWorks
安迪·比尔曼·尤马沃斯
Email: andy@yumaworks.com
Email: andy@yumaworks.com