7.1 “模块”声明

module”语句定义了模块的名称,并将属于该模块的所有语句分组在一起。 “module”语句的参数是模块的名称,后面跟着一个包含详细模块信息的子语句块。 模块名称是一个标识符(见第6.2节)。

RFC流中发布的模块的名称[RFC4844]必须由IANA分配; 参见[RFC6020]中的第14节

私有模块名称由拥有该模块的组织分配,没有中央注册表。 有关如何命名模块的建议,请参见第5.1节

模块通常具有以下布局:

  1. module <module-name> {
  2. // header information
  3. <yang-version statement>
  4. <namespace statement>
  5. <prefix statement>
  6. // linkage statements
  7. <import statements>
  8. <include statements>
  9. // meta-information
  10. <organization statement>
  11. <contact statement>
  12. <description statement>
  13. <reference statement>
  14. // revision history
  15. <revision statements>
  16. // module definitions
  17. <other statements>
  18. }

7.1.1. 模块的子语句

子语句 章节 基数
anydata 7.10 0..n
anyxml 7.11 0..n
augment 7.17 0..n
choice 7.9 0..n
contact 7.1.8 0..1
container 7.5 0..n
description 7.21.3 0..1
deviation 7.20.3 0..n
extension 7.19 0..n
feature 7.20.1 0..n
grouping 7.12 0..n
identity 7.18 0..n
import 7.1.5 0..n
include 7.1.6 0..n
leaf 7.6 0..n
leaf-list 7.7 0..n
list 7.8 0..n
namespace 7.1.3 1
notification 7.16 0..n
organization 7.1.7 0..1
prefix 7.1.4 1
reference 7.21.4 0..1
revision 7.1.9 0..n
rpc 7.14 0..n
typedef 7.3 0..n
uses 7.13 0..n
yang-version 7.1.2 1

RFC原表

  1. +--------------+---------+-------------+
  2. | substatement | section | cardinality |
  3. +--------------+---------+-------------+
  4. | anydata | 7.10 | 0..n |
  5. | anyxml | 7.11 | 0..n |
  6. | augment | 7.17 | 0..n |
  7. | choice | 7.9 | 0..n |
  8. | contact | 7.1.8 | 0..1 |
  9. | container | 7.5 | 0..n |
  10. | description | 7.21.3 | 0..1 |
  11. | deviation | 7.20.3 | 0..n |
  12. | extension | 7.19 | 0..n |
  13. | feature | 7.20.1 | 0..n |
  14. | grouping | 7.12 | 0..n |
  15. | identity | 7.18 | 0..n |
  16. | import | 7.1.5 | 0..n |
  17. | include | 7.1.6 | 0..n |
  18. | leaf | 7.6 | 0..n |
  19. | leaf-list | 7.7 | 0..n |
  20. | list | 7.8 | 0..n |
  21. | namespace | 7.1.3 | 1 |
  22. | notification | 7.16 | 0..n |
  23. | organization | 7.1.7 | 0..1 |
  24. | prefix | 7.1.4 | 1 |
  25. | reference | 7.21.4 | 0..1 |
  26. | revision | 7.1.9 | 0..n |
  27. | rpc | 7.14 | 0..n |
  28. | typedef | 7.3 | 0..n |
  29. | uses | 7.13 | 0..n |
  30. | yang-version | 7.1.2 | 1 |
  31. +--------------+---------+-------------+

7.1.2. “yang-version”声明

yang-version”语句指定在开发模块时使用了哪种版本的YANG语言。 声明的参数是一个字符串。 它必须包含根据此规范定义的YANG模块的值“1.1”。

不包含“yang-version”语句的模块或子模块,或者包含值“1”的模块或子模块是针对[RFC6020]中定义的YANG版本1开发的。

处理“1.1”(此处定义的版本)以外版本的“yang-version”语句超出了本规范的范围。 任何定义更高版本的文档都需要定义这种更高版本的后向兼容性。

有关YANG版本11.1之间的兼容性,请参见第12节

7.1.3. “namespace”声明

namespace”语句定义了XML名称空间,模块定义的所有标识符都以XML编码进行了限定,除了分组内定义的数据节点(data nodes),动作节点(action nodes)和通知节点(notification nodes)的标识符(详见7.13节)。 “namespace”语句的参数是命名空间的URI

另见第5.3节

7.1.4. “prefix”声明

prefix”语句用于定义与模块及其名称空间关联的前缀。 “prefix”语句的参数是用作访问模块前缀的前缀字符串。前缀字符串可以与模块一起用于引用模块中包含的定义,例如“if:ifName”。前缀是一个标识符(见第6.2节)。

在“module”语句中使用时,“prefix”语句定义了在导入模块时建议使用的前缀。

为了提高NETCONF XML的可读性,生成使用前缀的XMLXPathNETCONF客户机或服务器应该使用模块定义的前缀作为XML命名空间前缀,除非存在冲突。

在“import”语句中使用时,“prefix”语句定义在导入模块中访问定义时要使用的前缀。当使用从导入的模块引用标识符时,使用导入模块的前缀字符串,后跟冒号(“:”)和标识符,例如“if:ifIndex”。为了提高YANG模块的可读性,在模块导入时,应该使用模块定义的前缀,除非有冲突。如果存在冲突,即两个已定义相同前缀的不同模块被导入,则至少其中一个模块必须以不同的前缀导入。

所有前缀,包括模块本身的前缀,必须在模块或子模块中是唯一的。

7.1.5. “import”声明

import”语句使得一个模块的定义在另一个模块或子模块中可用。参数是要导入的模块的名称,语句之后是一个包含详细导入信息的子状态块。导入模块时,导入模块可以:

  • 使用导入模块或其子模块顶层定义的任何分组和typedef

  • 使用导入模块或其子模块中定义的任何扩展名,特性和标识。

  • 在“must”,“path”和“when”语句中使用导入模块的模式树中的任何节点,或者在“augment”和“deviation”语句中使用目标节点。

强制的“prefix”子语句为导入的模块分配一个前缀,该前缀的作用域是导入模块或子模块。可以指定多个“import”语句从不同的模块导入。

当存在可选的“revision-date”子语句时,本地模块中由定义引用的任何typedef,分组(grouping),扩展(extension),特征(feature)和标识(identity)都将取自导入模块的指定修订版本。如果导入的模块的指定修订版不存在,则为错误。如果不存在“修订日期(revision-data)”子语句,则取决于所取模块的哪个版本。

只要使用不同的前缀,可以导入同一模块的多个修订版本。

import的子语句

  1. +---------------+---------+-------------+
  2. | substatement | section | cardinality |
  3. +---------------+---------+-------------+
  4. | description | 7.21.3 | 0..1 |
  5. | prefix | 7.1.4 | 1 |
  6. | reference | 7.21.4 | 0..1 |
  7. | revision-date | 7.1.5.1 | 0..1 |
  8. +---------------+---------+-------------+

7.1.5.1. import的“revision-date”声明

导入的“修订日期(revision-date)”语句用于指定要导入的模块的版本。

7.1.6. “include”声明

include”语句用于使子模块的内容可用于该子模块的父模块。参数是一个标识符,是要包含的子模块的名称。模块只允许包含属于该模块的子模块,如“belongs-to”语句所定义的(参见第7.2.2节)。

当模块包含子模块时,它将子模块的内容合并到模块的节点层次结构中。

为了向后兼容YANG版本1,子模块允许包含属于同一个模块的另一个子模块,但在版本1.1(见5.1节)中这不是必需的。

当存在可选的“revision-date”子状态时,子模块的指定修订包含在模块中。如果子模块的指定修订版不存在,则是错误的。如果没有“revision-date”子语句,则不定义包含子模块的哪个版本。

不得包含同一子模块的多个版本。

include的子语句

  1. +---------------+---------+-------------+
  2. | substatement | section | cardinality |
  3. +---------------+---------+-------------+
  4. | description | 7.21.3 | 0..1 |
  5. | reference | 7.21.4 | 0..1 |
  6. | revision-date | 7.1.5.1 | 0..1 |
  7. +---------------+---------+-------------+

7.1.7. “organization”声明

“组织”(organization)声明定义了对此模块负责的一方。 参数是一个字符串,用于指定由本模块开发的组织的文本描述。

7.1.8. “contact”声明

“联系”(contact)声明提供模块的联系信息。 参数是一个字符串,用于指定应该发送有关该模块的技术查询的人员的联系信息,如姓名,邮政地址,电话号码和电子邮件地址。

7.1.9. “revision”声明

“修订”(revision)语句指定模块的编辑修订历史,包括初始修订。 一系列“revision”语句详细说明了模块定义中的变化。 参数是格式为“YYYY-MM-DD”的日期字符串,后跟一个包含详细修订信息的子状态块。 一个模块应该至少有一个“revision”语句。 对于每个已发表的编辑变更,应在修订顺序前添加一个新的修订顺序,以便所有修订顺序都是相反的。

7.1.9.1. revision的子语句

  1. +--------------+---------+-------------+
  2. | substatement | section | cardinality |
  3. +--------------+---------+-------------+
  4. | description | 7.21.3 | 0..1 |
  5. | reference | 7.21.4 | 0..1 |
  6. +--------------+---------+-------------+

7.1.10. 使用示例

以下示例依赖于[RFC6991]。

  1. module example-system {
  2. yang-version 1.1;
  3. namespace "urn:example:system";
  4. prefix "sys";
  5. import ietf-yang-types {
  6. prefix "yang";
  7. reference "RFC 6991: Common YANG Data Types";
  8. }
  9. include example-types;
  10. organization "Example Inc.";
  11. contact
  12. "Joe L. User
  13. Example Inc.
  14. 42 Anywhere Drive
  15. Nowhere, CA 95134
  16. USA
  17. Phone: +1 800 555 0100
  18. Email: joe@example.com";
  19. description
  20. "The module for entities implementing the Example system.";
  21. revision 2007-06-09 {
  22. description "Initial revision.";
  23. }
  24. // definitions follow...
  25. }