Internet Engineering Task Force (IETF) L. Lhotka
Request for Comments: 7951 CZ.NIC
Category: Standards Track August 2016
ISSN: 2070-1721
Internet Engineering Task Force (IETF) L. Lhotka
Request for Comments: 7951 CZ.NIC
Category: Standards Track August 2016
ISSN: 2070-1721
JSON Encoding of Data Modeled with YANG
用YANG建模的数据的JSON编码
Abstract
摘要
This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text.
本文档定义了编码规则，用于表示配置数据、状态数据、远程过程调用（RPC）操作或动作的参数，以及使用YANG作为JavaScript对象表示法（JSON）文本定义的通知。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
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 Internet Standards is available in Section 2 of RFC 7841.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关互联网标准的更多信息，请参见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7951.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc7951.
Copyright Notice
版权公告
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有（c）2016 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3
3. Properties of the JSON Encoding . . . . . . . . . . . . . . . 4
4. Names and Namespaces . . . . . . . . . . . . . . . . . . . . 5
5. Encoding of YANG Data Node Instances . . . . . . . . . . . . 7
5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . . . 7
5.2. The "container" Data Node . . . . . . . . . . . . . . . . 8
5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . . . 8
5.4. The "list" Data Node . . . . . . . . . . . . . . . . . . 9
5.5. The "anydata" Data Node . . . . . . . . . . . . . . . . . 9
5.6. The "anyxml" Data Node . . . . . . . . . . . . . . . . . 10
5.7. Metadata Objects . . . . . . . . . . . . . . . . . . . . 11
6. Representing YANG Data Types in JSON Values . . . . . . . . . 11
6.1. Numeric Types . . . . . . . . . . . . . . . . . . . . . . 11
6.2. The "string" Type . . . . . . . . . . . . . . . . . . . . 11
6.3. The "boolean" Type . . . . . . . . . . . . . . . . . . . 11
6.4. The "enumeration" Type . . . . . . . . . . . . . . . . . 12
6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . . . 12
6.6. The "binary" Type . . . . . . . . . . . . . . . . . . . . 12
6.7. The "leafref" Type . . . . . . . . . . . . . . . . . . . 12
6.8. The "identityref" Type . . . . . . . . . . . . . . . . . 12
6.9. The "empty" Type . . . . . . . . . . . . . . . . . . . . 13
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 14
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 15
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . . 16
9.2. Informative References . . . . . . . . . . . . . . . . . 17
Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 18
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3
3. Properties of the JSON Encoding . . . . . . . . . . . . . . . 4
4. Names and Namespaces . . . . . . . . . . . . . . . . . . . . 5
5. Encoding of YANG Data Node Instances . . . . . . . . . . . . 7
5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . . . 7
5.2. The "container" Data Node . . . . . . . . . . . . . . . . 8
5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . . . 8
5.4. The "list" Data Node . . . . . . . . . . . . . . . . . . 9
5.5. The "anydata" Data Node . . . . . . . . . . . . . . . . . 9
5.6. The "anyxml" Data Node . . . . . . . . . . . . . . . . . 10
5.7. Metadata Objects . . . . . . . . . . . . . . . . . . . . 11
6. Representing YANG Data Types in JSON Values . . . . . . . . . 11
6.1. Numeric Types . . . . . . . . . . . . . . . . . . . . . . 11
6.2. The "string" Type . . . . . . . . . . . . . . . . . . . . 11
6.3. The "boolean" Type . . . . . . . . . . . . . . . . . . . 11
6.4. The "enumeration" Type . . . . . . . . . . . . . . . . . 12
6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . . . 12
6.6. The "binary" Type . . . . . . . . . . . . . . . . . . . . 12
6.7. The "leafref" Type . . . . . . . . . . . . . . . . . . . 12
6.8. The "identityref" Type . . . . . . . . . . . . . . . . . 12
6.9. The "empty" Type . . . . . . . . . . . . . . . . . . . . 13
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 14
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 15
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
9.1. Normative References . . . . . . . . . . . . . . . . . . 16
9.2. Informative References . . . . . . . . . . . . . . . . . 17
Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 18
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
The Network Configuration Protocol (NETCONF) [RFC6241] uses XML [XML] for encoding data in its Content Layer. Other management protocols might want to use other encodings while still benefiting from using YANG [RFC7950] as the data modeling language.
网络配置协议（NETCONF）[RFC6241]使用XML[XML]对其内容层中的数据进行编码。其他管理协议可能希望使用其他编码，同时仍然受益于使用YANG[RFC7950]作为数据建模语言。
For example, the RESTCONF protocol [RESTCONF] supports two encodings: XML (media type "application/yang.data+xml") and JavaScript Object Notation (JSON) (media type "application/yang.data+json").
例如，RESTCONF协议[RESTCONF]支持两种编码：XML（媒体类型“application/yang.data+XML”）和JavaScript对象表示法（JSON）（媒体类型“application/yang.data+JSON”）。
The specification of the YANG 1.1 data modeling language [RFC7950] defines only XML encoding of data trees, i.e., configuration data, state data, input/output parameters of Remote Procedure Call (RPC) operations or actions, and notifications. The aim of this document is to define rules for encoding the same data as JSON text [RFC7159].
YANG 1.1数据建模语言[RFC7950]的规范仅定义数据树的XML编码，即配置数据、状态数据、远程过程调用（RPC）操作或动作的输入/输出参数以及通知。本文档的目的是定义编码与JSON文本相同数据的规则[RFC7159]。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
The following terms are defined in [RFC7950]:
[RFC7950]中定义了以下术语：
o action
o 行动
o anydata
o 任何数据
o anyxml
o 任意XML
o augment
o 加强
o container
o 容器
o data node
o 数据节点
o data tree
o 数据树
o identity
o 身份
o instance identifier
o 实例标示符
o leaf
o 叶
o leaf-list
o 叶列表
o list
o 列表
o module
o 单元
o RPC operation
o RPC操作
o submodule
o 子模块
The following terms are defined in [RFC6241]:
[RFC6241]中定义了以下术语：
o configuration data
o 配置数据
o notification
o 通知
o state data
o 状态数据
This document defines JSON encoding for YANG data trees and their subtrees. It is always assumed that the top-level structure in JSON-encoded data is an object.
本文档定义了数据树及其子树的JSON编码。通常假定JSON编码数据中的顶级结构是一个对象。
Instances of YANG data nodes (leafs, containers, leaf-lists, lists, anydata nodes, and anyxml nodes) are encoded as members of a JSON object, i.e., name/value pairs. Section 4 defines how the name part is formed, and the following sections deal with the value part. The encoding rules are identical for all types of data trees, i.e., configuration data, state data, parameters of RPC operations, actions, and notifications.
数据节点的实例（叶、容器、叶列表、列表、anydata节点和anyxml节点）被编码为JSON对象的成员，即名称/值对。第4节定义了名称部分是如何形成的，下面几节讨论了值部分。编码规则对于所有类型的数据树都是相同的，即配置数据、状态数据、RPC操作参数、操作和通知。
With the exception of "anydata" encoding (Section 5.5), all rules in this document are also applicable to YANG 1.0 [RFC6020].
除“anydata”编码（第5.5节）外，本文件中的所有规则也适用于YANG 1.0[RFC6020]。
Unlike XML element content, JSON values carry partial type information (number, string, boolean). The JSON encoding is defined so that this information is never in conflict with the data type of the corresponding YANG leaf or leaf-list.
与XML元素内容不同，JSON值携带部分类型信息（数字、字符串、布尔值）。JSON编码的定义使得该信息永远不会与相应的YANG叶或叶列表的数据类型冲突。
With the exception of anyxml and schema-less anydata nodes, it is possible to map a JSON-encoded data tree to XML encoding as defined in [RFC7950], and vice versa. However, such conversions require the YANG data model to be available.
除了anyxml和无模式的anydata节点外，可以将JSON编码的数据树映射为[RFC7950]中定义的XML编码，反之亦然。然而，这种转换要求YANG数据模型可用。
In order to achieve maximum interoperability while allowing implementations to use a variety of existing JSON parsers, the JSON encoding rules follow, as much as possible, the constraints of the I-JSON (Internet JSON) restricted profile [RFC7493]. Section 7 discusses I-JSON conformance in more detail.
为了实现最大的互操作性，同时允许实现使用各种现有的JSON解析器，JSON编码规则尽可能遵循I-JSON（Internet JSON）受限概要文件[RFC7493]的约束。第7节更详细地讨论了I-JSON一致性。
A JSON object member name MUST be in one of the following forms:
JSON对象成员名称必须采用以下形式之一：
o simple - identical to the identifier of the corresponding YANG data node.
o 简单-与相应数据节点的标识符相同。
o namespace-qualified - the data node identifier is prefixed with the name of the module in which the data node is defined, separated from the data node identifier by the colon character (":").
o namespace qualified（名称空间限定）-数据节点标识符以定义数据节点的模块名称作为前缀，以冒号（“：”）与数据节点标识符分隔。
The name of a module determines the namespace of all data node names defined in that module. If a data node is defined in a submodule, then the namespace-qualified member name uses the name of the main module to which the submodule belongs.
模块的名称确定该模块中定义的所有数据节点名称的命名空间。如果在子模块中定义了数据节点，则命名空间限定成员名称将使用子模块所属的主模块的名称。
ABNF syntax [RFC5234] of a member name is shown in Figure 1, where the production for "identifier" is defined in Section 14 of [RFC7950].
成员名称的ABNF语法[RFC5234]如图1所示，其中“标识符”的产生在[RFC7950]的第14节中定义。
member-name = [identifier ":"] identifier
member-name = [identifier ":"] identifier
Figure 1: ABNF Production for a JSON Member Name
图1:JSON成员名的ABNF生产
A namespace-qualified member name MUST be used for all members of a top-level JSON object and then also whenever the namespaces of the data node and its parent node are different. In all other cases, the simple form of the member name MUST be used.
顶级JSON对象的所有成员都必须使用名称空间限定的成员名称，并且在数据节点及其父节点的名称空间不同时也必须使用名称空间限定的成员名称。在所有其他情况下，必须使用成员名称的简单形式。
For example, consider the following YANG module:
例如，考虑以下杨氏模块：
module example-foomod {
模块示例foomod{
namespace "http://example.com/foomod";
namespace "http://example.com/foomod";
prefix "foomod";
前缀“foomod”；
container top {
leaf foo {
type uint8;
}
}
}
container top {
leaf foo {
type uint8;
}
}
}
If the data model consists only of this module, then the following is valid JSON-encoded configuration data:
如果数据模型仅包含此模块，则以下是有效的JSON编码配置数据：
{
"example-foomod:top": {
"foo": 54
}
}
{
"example-foomod:top": {
"foo": 54
}
}
Note that the member of the top-level object uses the namespace-qualified name but the "foo" leaf doesn't because it is defined in the same module as its parent container "top".
请注意，顶级对象的成员使用命名空间限定名，但“foo”叶不使用，因为它与其父容器“top”在同一模块中定义。
Now, assume that the container "top" is augmented from another module, "example-barmod":
现在，假设容器“top”是从另一个模块“example barmod”扩展而来的：
module example-barmod {
模块示例barmod{
namespace "http://example.com/barmod";
namespace "http://example.com/barmod";
prefix "barmod";
前缀“barmod”；
import example-foomod {
prefix "foomod";
}
import example-foomod {
prefix "foomod";
}
augment "/foomod:top" {
leaf bar {
type boolean;
}
}
}
augment "/foomod:top" {
leaf bar {
type boolean;
}
}
}
Valid JSON-encoded configuration data containing both leafs may then look like this:
包含两个leaf的有效JSON编码配置数据可能如下所示：
{
"example-foomod:top": {
"foo": 54,
"example-barmod:bar": true
}
}
{
"example-foomod:top": {
"foo": 54,
"example-barmod:bar": true
}
}
The name of the "bar" leaf is prefixed with the namespace identifier because its parent is defined in a different module.
“bar”叶的名称以名称空间标识符作为前缀，因为它的父级是在不同的模块中定义的。
Explicit namespace identifiers are sometimes needed when encoding values of the "identityref" and "instance-identifier" types. The same form of namespace-qualified name as defined above is then used. See Sections 6.8 and 6.11 for details.
在编码“identityref”和“instance identifier”类型的值时，有时需要显式命名空间标识符。然后使用与上面定义的名称空间限定名称相同的形式。详见第6.8节和第6.11节。
Every data node instance is encoded as a name/value pair where the name is formed from the data node identifier using the rules of Section 4. The value depends on the category of the data node, as explained in the following subsections.
每个数据节点实例被编码为名称/值对，其中名称是使用第4节的规则从数据节点标识符形成的。该值取决于数据节点的类别，如下小节所述。
Character encoding MUST be UTF-8.
字符编码必须是UTF-8。
A leaf instance is encoded as a name/value pair where the value can be a string, number, literal "true" or "false", or the special array "[null]", depending on the type of the leaf (see Section 6 for the type encoding rules).
叶实例被编码为名称/值对，其中值可以是字符串、数字、文字“true”或“false”，或特殊数组“[null]”，具体取决于叶的类型（类型编码规则见第6节）。
Example: For the leaf node definition
示例：用于叶节点定义
leaf foo {
type uint8;
}
leaf foo {
type uint8;
}
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"foo": 123
“福”：123
A container instance is encoded as a name/object pair. The container's child data nodes are encoded as members of the object.
容器实例编码为名称/对象对。容器的子数据节点被编码为对象的成员。
Example: For the container definition
示例：用于容器定义
container bar {
leaf foo {
type uint8;
}
}
container bar {
leaf foo {
type uint8;
}
}
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"bar": {
"foo": 123
}
"bar": {
"foo": 123
}
A leaf-list is encoded as a name/array pair, and the array elements are values of some scalar type, which can be a string, number, literal "true" or "false", or the special array "[null]", depending on the type of the leaf-list (see Section 6 for the type encoding rules).
叶列表编码为名称/数组对，数组元素是一些标量类型的值，可以是字符串、数字、文字“真”或“假”，或特殊数组“[null]”，具体取决于叶列表的类型（类型编码规则见第6节）。
The ordering of array elements follows the same rules as the ordering of XML elements representing leaf-list entries in the XML encoding. Specifically, the "ordered-by" properties (Section 7.7.7 in [RFC7950]) MUST be observed.
数组元素的顺序遵循与XML编码中表示叶列表项的XML元素的顺序相同的规则。具体而言，必须遵守“订购人”属性（RFC7950中的第7.7.7节）。
Example: For the leaf-list definition
示例：用于叶列表定义
leaf-list foo {
type uint8;
}
leaf-list foo {
type uint8;
}
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"foo": [123, 0]
"foo": [123, 0]
A list instance is encoded as a name/array pair, and the array elements are JSON objects.
列表实例编码为名称/数组对，数组元素是JSON对象。
The ordering of array elements follows the same rules as the ordering of XML elements representing list entries in the XML encoding. Specifically, the "ordered-by" properties (Section 7.7.7 in [RFC7950]) MUST be observed.
数组元素的顺序遵循与XML编码中表示列表项的XML元素的顺序相同的规则。具体而言，必须遵守“订购人”属性（RFC7950中的第7.7.7节）。
Unlike the XML encoding, where list keys are required to precede any other siblings within a list entry and appear in the order specified by the data model, the order of members in a JSON-encoded list entry is arbitrary because JSON objects are fundamentally unordered collections of members.
与XML编码不同，在XML编码中，列表键必须位于列表项中任何其他同级项之前，并按照数据模型指定的顺序显示，JSON编码列表项中的成员顺序是任意的，因为JSON对象基本上是无序的成员集合。
Example: For the list definition
示例：用于列表定义
list bar {
key foo;
leaf foo {
type uint8;
}
leaf baz {
type string;
}
}
list bar {
key foo;
leaf foo {
type uint8;
}
leaf baz {
type string;
}
}
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"bar": [
{
"foo": 123,
"baz": "zig"
},
{
"baz": "zag",
"foo": 0
}
]
"bar": [
{
"foo": 123,
"baz": "zig"
},
{
"baz": "zag",
"foo": 0
}
]
The anydata data node serves as a container for an arbitrary set of nodes that otherwise appear as normal YANG-modeled data. A data model for anydata content may or may not be known at runtime. In the latter case, converting JSON-encoded instances to the XML encoding defined in [RFC7950] may be impossible.
anydata数据节点用作任意一组节点的容器，否则这些节点将显示为正常数据。任何数据内容的数据模型在运行时可能已知，也可能未知。在后一种情况下，将JSON编码的实例转换为[RFC7950]中定义的XML编码可能是不可能的。
An anydata instance is encoded in the same way as a container, i.e., as a name/object pair. The requirement that anydata content can be modeled by YANG implies the following rules for the JSON text inside the object:
anydata实例的编码方式与容器相同，即名称/对象对。anydata内容可以由YANG建模的要求意味着对象内部JSON文本的以下规则：
o It is valid I-JSON [RFC7493].
o 它是有效的I-JSON[RFC7493]。
o All object member names satisfy the ABNF production in Figure 1.
o 所有对象成员名称都满足图1中的ABNF产品。
o Any JSON array contains either only unique scalar values (as a leaf-list; see Section 5.3) or only objects (as a list; see Section 5.4).
o 任何JSON数组要么只包含唯一的标量值（作为叶列表；请参见第5.3节），要么只包含对象（作为列表；请参见第5.4节）。
o The "null" value is only allowed in the single-element array "[null]" corresponding to the encoding of the "empty" type; see Section 6.9.
o 仅在与“空”类型编码对应的单元素数组“[null]”中允许使用“null”值；见第6.9节。
Example: For the anydata definition
示例：对于anydata定义
anydata data;
任何数据数据；
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"data": {
"ietf-notification:notification": {
"eventTime": "2014-07-29T13:43:01Z",
"example-event:event": {
"event-class": "fault",
"reporting-entity": {
"card": "Ethernet0"
},
"severity": "major"
}
}
}
"data": {
"ietf-notification:notification": {
"eventTime": "2014-07-29T13:43:01Z",
"example-event:event": {
"event-class": "fault",
"reporting-entity": {
"card": "Ethernet0"
},
"severity": "major"
}
}
}
An anyxml instance is encoded as a JSON name/value pair. The value MUST satisfy I-JSON constraints.
anyxml实例编码为JSON名称/值对。该值必须满足I-JSON约束。
Example: For the anyxml definition
示例：对于anyxml定义
anyxml bar;
anyxml条；
the following is a valid JSON-encoded instance:
以下是一个有效的JSON编码实例：
"bar": [true, null, true]
"bar": [true, null, true]
Apart from instances of YANG data nodes, a JSON document MAY contain special object members whose name starts with the "@" character (COMMERCIAL AT). Such members are used for special purposes, such as encoding metadata [RFC7952]. The exact syntax and semantics of such members are outside the scope of this document.
除了数据节点的实例外，JSON文档可能包含名称以“@”字符开头的特殊对象成员（商业地址）。这些成员用于特殊目的，例如编码元数据[RFC7952]。这些成员的确切语法和语义不在本文档的范围内。
The type of the JSON value in an instance of the leaf or leaf-list data node depends on the type of that data node, as specified in the following subsections.
叶或叶列表数据节点实例中JSON值的类型取决于该数据节点的类型，如下小节所述。
A value of the "int8", "int16", "int32", "uint8", "uint16", or "uint32" type is represented as a JSON number.
“int8”、“int16”、“int32”、“uint8”、“uint16”或“uint32”类型的值表示为JSON编号。
A value of the "int64", "uint64", or "decimal64" type is represented as a JSON string whose content is the lexical representation of the corresponding YANG type as specified in Sections 9.2.1 and 9.3.1 of [RFC7950].
“int64”、“uint64”或“decimal64”类型的值表示为JSON字符串，其内容是[RFC7950]第9.2.1节和第9.3.1节中规定的对应YANG类型的词汇表示。
For example, if the type of the leaf "foo" in Section 5.1 was "uint64" instead of "uint8", the instance would have to be encoded as
例如，如果第5.1节中叶“foo”的类型是“uint64”而不是“uint8”，则实例必须编码为
"foo": "123"
"foo": "123"
The special handling of 64-bit numbers follows from the I-JSON recommendation to encode numbers exceeding the IEEE 754-2008 double-precision range [IEEE754-2008] as strings; see Section 2.2 in [RFC7493].
64位数字的特殊处理遵循I-JSON建议，将超过IEEE 754-2008双精度范围[IEEE754-2008]的数字编码为字符串；参见[RFC7493]中的第2.2节。
A "string" value is represented as a JSON string, subject to JSON string encoding rules.
“string”值表示为JSON字符串，遵循JSON字符串编码规则。
A "boolean" value is represented as the corresponding JSON literal name "true" or "false".
“boolean”值表示为相应的JSON文字名称“true”或“false”。
An "enumeration" value is represented as a JSON string -- one of the names assigned by "enum" statements in YANG.
“enumeration”值表示为JSON字符串——YANG中“enum”语句指定的名称之一。
The representation is identical to the lexical representation of the "enumeration" type in XML; see Section 9.6 in [RFC7950].
该表示法与XML中“枚举”类型的词汇表示法相同；参见[RFC7950]中的第9.6节。
A "bits" value is represented as a JSON string -- a space-separated sequence of names of bits that are set. The permitted bit names are assigned by "bit" statements in YANG.
“bits”值表示为JSON字符串——一个由设置的位的名称组成的以空格分隔的序列。允许的位名称由YANG中的“bit”语句指定。
The representation is identical to the lexical representation of the "bits" type; see Section 9.7 in [RFC7950].
该表示法与“位”类型的词汇表示法相同；参见[RFC7950]中的第9.7节。
A "binary" value is represented as a JSON string -- base64 encoding of arbitrary binary data.
“二进制”值表示为JSON字符串——任意二进制数据的base64编码。
The representation is identical to the lexical representation of the "binary" type in XML; see Section 9.8 in [RFC7950].
该表示法与XML中“二进制”类型的词汇表示法相同；参见[RFC7950]中的第9.8节。
A "leafref" value is represented using the same rules as the type of the leaf to which the leafref value refers.
“leafref”值使用与leafref值引用的叶类型相同的规则表示。
An "identityref" value is represented as a string -- the name of an identity. If the identity is defined in a module other than the leaf node containing the identityref value, the namespace-qualified form (Section 4) MUST be used. Otherwise, both the simple and namespace-qualified forms are permitted.
“identityref”值表示为字符串——标识的名称。如果标识是在包含identityref值的叶节点以外的模块中定义的，则必须使用命名空间限定形式（第4节）。否则，允许使用简单形式和命名空间限定形式。
For example, consider the following schematic module:
例如，考虑下面的示意性模块：
module example-mod {
...
import ietf-interfaces {
prefix if;
}
...
leaf type {
type identityref {
base "if:interface-type";
}
}
}
module example-mod {
...
import ietf-interfaces {
prefix if;
}
...
leaf type {
type identityref {
base "if:interface-type";
}
}
}
A valid instance of the "type" leaf is then encoded as follows:
“类型”叶的有效实例编码如下：
"type": "iana-if-type:ethernetCsmacd"
"type": "iana-if-type:ethernetCsmacd"
The namespace identifier "iana-if-type" must be present in this case because the "ethernetCsmacd" identity is not defined in the same module as the "type" leaf.
在这种情况下，名称空间标识符“iana if type”必须存在，因为“ethernetCsmacd”标识没有在与“type”叶相同的模块中定义。
An "empty" value is represented as "[null]", i.e., an array with the "null" literal being its only element. For the purposes of this document, "[null]" is considered an atomic scalar value.
“空”值表示为“[null]”，即“null”文本是其唯一元素的数组。在本文档中，“[null]”被视为原子标量值。
This encoding of the "empty" type was chosen instead of using simply "null" in order to facilitate the use of empty leafs in common programming languages where the "null" value of a member is treated as if the member is not present.
选择“empty”类型的这种编码，而不是简单地使用“null”，以便于在通用编程语言中使用空叶，其中成员的“null”值被视为不存在。
Example: For the leaf definition
示例：用于叶定义
leaf foo {
type empty;
}
leaf foo {
type empty;
}
a valid instance is
一个有效的实例是
"foo": [null]
"foo": [null]
A value of the "union" type is encoded as the value of any of the member types.
“union”类型的值被编码为任何成员类型的值。
When validating a value of the "union" type, the type information conveyed by the JSON encoding MUST also be taken into account. JSON syntax thus provides additional means for resolving the member type of the union that are not available in XML encoding.
验证“union”类型的值时，还必须考虑JSON编码传递的类型信息。因此，JSON语法为解析在XML编码中不可用的联合成员类型提供了额外的方法。
For example, consider the following YANG definition:
例如，考虑下面的阳定义：
leaf bar {
type union {
type uint16;
type string;
}
}
leaf bar {
type union {
type uint16;
type string;
}
}
In RESTCONF [RESTCONF], it is possible to set the value of "bar" in the following way when using the "application/yang.data+xml" media type:
在RESTCONF[RESTCONF]中，使用“application/yang.data+xml”媒体类型时，可以通过以下方式设置“bar”的值：
<bar>13.5</bar>
<bar>13.5</bar>
because the value may be interpreted as a string, i.e., the second member type of the union. When using the "application/yang.data+json" media type, however, this is an error:
因为该值可以解释为字符串，即union的第二个成员类型。但是，当使用“application/yang.data+json”媒体类型时，这是一个错误：
"bar": 13.5
“巴”：13.5
In this case, the JSON encoding indicates that the value is supposed to be a number rather than a string, and it is not a valid "uint16" value.
在本例中，JSON编码表示该值应该是数字而不是字符串，并且它不是有效的“uint16”值。
Conversely, the value of
相反，价值
"bar": "1"
"bar": "1"
is to be interpreted as a string.
将被解释为字符串。
An "instance-identifier" value is encoded as a string that is analogical to the lexical representation in XML encoding; see Section 9.13.2 in [RFC7950]. However, the encoding of namespaces in instance-identifier values follows the rules stated in Section 4, namely:
“实例标识符”值被编码为字符串，类似于XML编码中的词汇表示；参见[RFC7950]中的第9.13.2节。但是，实例标识符值中名称空间的编码遵循第4节中规定的规则，即：
o The leftmost (top-level) data node name is always in the namespace-qualified form.
o 最左侧（顶级）数据节点名称始终采用命名空间限定形式。
o Any subsequent data node name is in the namespace-qualified form if the node is defined in a module other than its parent node, and the simple form is used otherwise. This rule also holds for node names appearing in predicates.
o 如果节点是在其父节点以外的模块中定义的，则任何后续数据节点名称都采用命名空间限定形式，否则使用简单形式。此规则也适用于谓词中出现的节点名称。
For example,
例如
/ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip
/ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip
is a valid instance-identifier value because the data nodes "interfaces", "interface", and "name" are defined in the module "ietf-interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip".
是有效的实例标识符值，因为数据节点“接口”、“接口”和“名称”在模块“ietf接口”中定义，而“ipv4”和“ip”在“ietf ip”中定义。
I-JSON [RFC7493] is a restricted profile of JSON that guarantees maximum interoperability for protocols that use JSON in their messages, no matter what JSON encoders/decoders are used in protocol implementations. The encoding defined in this document therefore observes the I-JSON requirements and recommendations as closely as possible.
I-JSON[RFC7493]是JSON的一个受限配置文件，它保证了在消息中使用JSON的协议的最大互操作性，而不管协议实现中使用了什么JSON编码器/解码器。因此，本文档中定义的编码尽可能遵守I-JSON要求和建议。
In particular, the following properties are guaranteed:
特别是，保证以下特性：
o Character encoding is UTF-8.
o 字符编码是UTF-8。
o Member names within the same JSON object are always unique.
o 同一JSON对象中的成员名称始终是唯一的。
o The order of JSON object members is never relied upon.
o 永远不依赖JSON对象成员的顺序。
o Numbers of any type supported by YANG can be exchanged reliably. See Section 6.1 for details.
o YANG支持的任何类型的号码都可以可靠地交换。详见第6.1节。
The JSON encoding defined in this document deviates from I-JSON only in the representation of the "binary" type. In order to remain compatible with XML encoding, the base64 encoding scheme is used (Section 6.6), whilst I-JSON recommends base64url instead.
本文档中定义的JSON编码仅在“二进制”类型的表示形式上与I-JSON不同。为了与XML编码保持兼容，使用了base64编码方案（第6.6节），而I-JSON建议使用base64url。
This document defines an alternative encoding for data modeled in the YANG data modeling language. As such, it doesn't contribute any new security issues beyond those discussed in Section 17 of [RFC7950].
本文档定义了用YANG数据建模语言建模的数据的替代编码。因此，除了[RFC7950]第17节中讨论的问题外，它不会带来任何新的安全问题。
This document defines no mechanisms for signing and encrypting data modeled with YANG. Under normal circumstances, data security and integrity are guaranteed by the management protocol in use, such as NETCONF [RFC6241] or RESTCONF [RESTCONF]. If this is not the case, external mechanisms, such as Public-Key Cryptography Standards (PKCS) #7 [RFC2315] or JSON Object Signing and Encryption (JOSE) [RFC7515] [RFC7516], need to be considered.
本文档未定义使用YANG建模的数据签名和加密机制。在正常情况下，数据安全性和完整性由正在使用的管理协议（如NETCONF[RFC6241]或RESTCONF[RESTCONF]）保证。如果情况并非如此，则需要考虑外部机制，如公钥加密标准（PKCS）#7[RFC2315]或JSON对象签名和加密（JOSE）[RFC7515][RFC7516]。
JSON processing is rather different from XML, and JSON parsers may thus suffer from different types of vulnerabilities than their XML counterparts. To minimize these new security risks, software on the receiving side SHOULD reject all messages that do not comply with the rules of this document and reply with an appropriate error message to the sender.
JSON处理与XML有很大不同，因此JSON解析器可能比XML解析器遭受不同类型的漏洞。为了将这些新的安全风险降至最低，接收方的软件应拒绝所有不符合本文档规则的消息，并向发送方回复适当的错误消息。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <http://www.rfc-editor.org/info/rfc5234>.
[RFC5234]Crocker，D.，Ed.和P.Overell，“语法规范的扩充BNF:ABNF”，STD 68，RFC 5234，DOI 10.17487/RFC5234，2008年1月<http://www.rfc-editor.org/info/rfc5234>.
[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, <http://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月<http://www.rfc-editor.org/info/rfc6241>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7159]Bray，T.，Ed.“JavaScript对象表示法（JSON）数据交换格式”，RFC 7159，DOI 10.17487/RFC7159，2014年3月<http://www.rfc-editor.org/info/rfc7159>.
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015, <http://www.rfc-editor.org/info/rfc7493>.
[RFC7493]Bray，T.，Ed.，“I-JSON消息格式”，RFC 7493，DOI 10.17487/RFC7493，2015年3月<http://www.rfc-editor.org/info/rfc7493>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <http://www.rfc-editor.org/info/rfc7950>.
[RFC7950]Bjorklund，M.，Ed.“YANG 1.1数据建模语言”，RFC 7950，DOI 10.17487/RFC7950，2016年8月<http://www.rfc-editor.org/info/rfc7950>.
[IEEE754-2008] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE 754-2008, DOI 10.1109/IEEESTD.2008.4610935, 2008, <http://standards.ieee.org/findstds/ standard/754-2008.html>.
[IEEE754-2008]IEEE，“IEEE浮点运算标准”，IEEE 754-2008，DOI 10.1109/IEEESTD.2008.46109352008<http://standards.ieee.org/findstds/ 标准/754-2008.html>。
[RESTCONF] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", Work in Progress, draft-ietf-netconf-restconf-16, August 2016.
[RESTCONF]Bierman，A.，Bjorklund，M.，和K.Watsen，“RESTCONF协议”，正在进行的工作，草稿-ietf-netconf-RESTCONF-162016年8月。
[RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998, <http://www.rfc-editor.org/info/rfc2315>.
[RFC2315]Kaliski，B.，“PKCS#7：加密消息语法版本1.5”，RFC 2315，DOI 10.17487/RFC2315，1998年3月<http://www.rfc-editor.org/info/rfc2315>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <http://www.rfc-editor.org/info/rfc6020>.
[RFC6020]Bjorklund，M.，Ed.“YANG-网络配置协议的数据建模语言（NETCONF）”，RFC 6020，DOI 10.17487/RFC6020，2010年10月<http://www.rfc-editor.org/info/rfc6020>.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, <http://www.rfc-editor.org/info/rfc7223>.
[RFC7223]Bjorklund，M.，“用于接口管理的YANG数据模型”，RFC 7223，DOI 10.17487/RFC7223，2014年5月<http://www.rfc-editor.org/info/rfc7223>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC7515]Jones，M.，Bradley，J.和N.Sakimura，“JSON网络签名（JWS）”，RFC 7515，DOI 10.17487/RFC7515，2015年5月<http://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, <http://www.rfc-editor.org/info/rfc7516>.
[RFC7516]Jones，M.和J.Hildebrand，“JSON Web加密（JWE）”，RFC 7516，DOI 10.17487/RFC7516，2015年5月<http://www.rfc-editor.org/info/rfc7516>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016, <http://www.rfc-editor.org/info/rfc7952>.
[RFC7952]Lhotka，L.，“与YANG一起定义和使用元数据”，RFC 7952，DOI 10.17487/RFC7952，2016年8月<http://www.rfc-editor.org/info/rfc7952>.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[XML]Bray，T.，Paoli，J.，Sperberg McQueen，M.，Maler，E.，和F.Yergeau，“可扩展标记语言（XML）1.0（第五版）”，万维网联盟建议REC-XML-20081126，2008年11月<http://www.w3.org/TR/2008/REC-xml-20081126>.
The JSON document shown below represents the same data as the reply to the NETCONF <get> request appearing in Appendix D of [RFC7223]. The data model is a combination of two YANG modules: "ietf-interfaces" and "ex-vlan" (the latter is an example module from Appendix C of [RFC7223]). The "if-mib" feature defined in the "ietf-interfaces" module is supported.
下面显示的JSON文档表示的数据与[RFC7223]附录D中出现的对NETCONF<get>请求的回复相同。数据模型是两个模块的组合：“ietf接口”和“ex vlan”（后者是[RFC7223]附录C中的示例模块）。支持“ietf接口”模块中定义的“if mib”功能。
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"enabled": false
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"enabled": true,
"ex-vlan:vlan-tagging": true
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"enabled": true,
"ex-vlan:base-interface": "eth1",
"ex-vlan:vlan-id": 10
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"enabled": true
}
]
},
"ietf-interfaces:interfaces-state": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 2,
"phys-address": "00:01:02:03:04:05",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"enabled": false
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"enabled": true,
"ex-vlan:vlan-tagging": true
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"enabled": true,
"ex-vlan:base-interface": "eth1",
"ex-vlan:vlan-id": 10
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"enabled": true
}
]
},
"ietf-interfaces:interfaces-state": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 2,
"phys-address": "00:01:02:03:04:05",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "up",
"oper-status": "up",
"if-index": 7,
"phys-address": "00:01:02:03:04:06",
"higher-layer-if": [
"eth1.10"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"admin-status": "up",
"oper-status": "up",
"if-index": 9,
"lower-layer-if": [
"eth1"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth2",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 8,
"phys-address": "00:01:02:03:04:07",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"admin-status": "up",
"oper-status": "up",
"if-index": 1,
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "up",
"oper-status": "up",
"if-index": 7,
"phys-address": "00:01:02:03:04:06",
"higher-layer-if": [
"eth1.10"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"admin-status": "up",
"oper-status": "up",
"if-index": 9,
"lower-layer-if": [
"eth1"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth2",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 8,
"phys-address": "00:01:02:03:04:07",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"admin-status": "up",
"oper-status": "up",
"if-index": 1,
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
}
]
}
}
}
}
]
}
}
Acknowledgements
致谢
The author wishes to thank Andy Bierman, Martin Bjorklund, Dean Bogdanovic, Balazs Lengyel, Juergen Schoenwaelder, and Phil Shafer for their helpful comments and suggestions.
作者希望感谢安迪·比尔曼、马丁·比约克隆德、迪安·博格达诺维奇、巴拉兹·伦杰尔、尤尔根·舍恩瓦埃尔德和菲尔·沙弗提出的有益意见和建议。
Author's Address
作者地址
Ladislav Lhotka CZ.NIC
拉迪斯拉夫·洛特卡CZ.NIC
Email: lhotka@nic.cz
Email: lhotka@nic.cz