7.1 “模块”声明

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

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

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

模块通常具有以下布局：

module <module-name> {
  // header information
  <yang-version statement>
  <namespace statement>
  <prefix statement>
  // linkage statements
  <import statements>
  <include statements>
  // meta-information
  <organization statement>
  <contact statement>
  <description statement>
  <reference statement>
  // revision history
  <revision statements>
  // module definitions
  <other statements>
}

7.1.1. 模块的子语句

RFC原表

+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| 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           |
+--------------+---------+-------------+

7.1.2. “yang-version”声明

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

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

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

有关YANG版本1和1.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的可读性，生成使用前缀的XML或XPath的NETCONF客户机或服务器应该使用模块定义的前缀作为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的子语句

+---------------+---------+-------------+
| substatement  | section | cardinality |
+---------------+---------+-------------+
| description   | 7.21.3  | 0..1        |
| prefix        | 7.1.4   | 1           |
| reference     | 7.21.4  | 0..1        |
| revision-date | 7.1.5.1 | 0..1        |
+---------------+---------+-------------+

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的子语句

+---------------+---------+-------------+
| substatement  | section | cardinality |
+---------------+---------+-------------+
| description   | 7.21.3  | 0..1        |
| reference     | 7.21.4  | 0..1        |
| revision-date | 7.1.5.1 | 0..1        |
+---------------+---------+-------------+

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的子语句

+--------------+---------+-------------+
| substatement | section | cardinality |
+--------------+---------+-------------+
| description  | 7.21.3  | 0..1        |
| reference    | 7.21.4  | 0..1        |
+--------------+---------+-------------+

7.1.10. 使用示例

以下示例依赖于[RFC6991]。

module example-system {
  yang-version 1.1;
  namespace "urn:example:system";
  prefix "sys";
  import ietf-yang-types {
    prefix "yang";
    reference "RFC 6991: Common YANG Data Types";
  }
  include example-types;
  organization "Example Inc.";
  contact
    "Joe L. User
     Example Inc.
     42 Anywhere Drive
     Nowhere, CA 95134
     USA
     Phone: +1 800 555 0100
     Email: joe@example.com";
  description
    "The module for entities implementing the Example system.";
  revision 2007-06-09 {
    description "Initial revision.";
  }
  // definitions follow...
}