[要約] RFC 7952は、YANGでメタデータを定義および使用するためのガイドラインを提供するものであり、YANGモデルに関連する情報を追加するための方法を示しています。目的は、YANGモデルの柔軟性と拡張性を向上させ、ネットワークデバイスやサービスの管理を容易にすることです。
Internet Engineering Task Force (IETF) L. Lhotka
Request for Comments: 7952 CZ.NIC
Updates: 6110 August 2016
Category: Standards Track
ISSN: 2070-1721
Defining and Using Metadata with YANG
YANGによるメタデータの定義と使用
Abstract
概要
This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes.
このドキュメントでは、YANGモジュールでメタデータアノテーションを定義できるYANG拡張機能を定義しています。このドキュメントでは、注釈のXMLおよびJSONエンコーディングと、YANGデータノードのインスタンスに注釈を付けるための他のルールも指定しています。
Status of This Memo
本文書の状態
This is an Internet Standards Track document.
これはInternet Standards Trackドキュメントです。
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（Internet Engineering Task Force）の製品です。これは、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/rfc7952.
このドキュメントの現在のステータス、エラータ、およびフィードバックの提供方法に関する情報は、http：//www.rfc-editor.org/info/rfc7952で入手できます。
Copyright Notice
著作権表示
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright（c）2016 IETF Trustおよびドキュメントの作成者として識別された人物。全著作権所有。
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）の対象であり、この文書の発行日に有効です。これらのドキュメントは、このドキュメントに関するあなたの権利と制限を説明しているため、注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust Legal Provisionsのセクション4.eに記載されているSimplified BSD Licenseのテキストが含まれている必要があり、Simplified BSD Licenseに記載されているように保証なしで提供されます。
Table of Contents
目次
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. Terms Defined in Other Documents . . . . . . . . . . . . 5
2.3. Namespaces and Prefixes . . . . . . . . . . . . . . . . . 7
2.4. Definitions of New Terms . . . . . . . . . . . . . . . . 7
3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 8
3.1. Example Definition . . . . . . . . . . . . . . . . . . . 9
4. Using Annotations . . . . . . . . . . . . . . . . . . . . . . 9
5. The Encoding of Annotations . . . . . . . . . . . . . . . . . 10
5.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 10
5.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 11
5.2.1. Metadata Object and Annotations . . . . . . . . . . . 11
5.2.2. Adding Annotations to anydata, container, and list
Entries . . . . . . . . . . . . . . . . . . . . . . . 12
5.2.3. Adding Annotations to anyxml and leaf Instances . . . 12
5.2.4. Adding Annotations to leaf-list Entries . . . . . . . 13
6. Representing Annotations in DSDL Schemas . . . . . . . . . . 14
7. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 16
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
9. Security Considerations . . . . . . . . . . . . . . . . . . . 18
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 19
10.1. Normative References . . . . . . . . . . . . . . . . . . 19
10.2. Informative References . . . . . . . . . . . . . . . . . 20
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21
There is a need to be able to annotate instances of YANG [RFC7950] data nodes with metadata. Typical use cases are as follows:
YANG [RFC7950]データノードのインスタンスにメタデータで注釈を付けることができる必要があります。一般的な使用例は次のとおりです。
o Complementing regular data model information with instance-specific metadata, comments, etc.
o 通常のデータモデル情報をインスタンス固有のメタデータ、コメントなどで補完する
o Providing information about the rendering of data in user interfaces.
o ユーザーインターフェイスでのデータのレンダリングに関する情報を提供します。
o Deactivating a subtree in a configuration datastore while keeping the data in place.
o データを保持したまま、構成データストアのサブツリーを非アクティブ化します。
o Network management protocols often use metadata annotations for various purposes in both operation requests and responses. For example, the <edit-config> operation in the Network Configuration Protocol (NETCONF) (see Section 7.2 of [RFC6241]) uses annotations in the form of XML attributes for identifying the location in a configuration datastore and the type of the operation.
o ネットワーク管理プロトコルは、多くの場合、操作要求と応答の両方でさまざまな目的でメタデータアノテーションを使用します。たとえば、ネットワーク構成プロトコル（NETCONF）の<edit-config>操作（[RFC6241]のセクション7.2を参照）は、XMLデータ形式の注釈を使用して、構成データストア内の場所と操作のタイプを識別します。
However, metadata annotations could potentially lead to interoperability problems if they are used in an ad hoc fashion by different parties and/or without proper documentation. A sound metadata framework for YANG should therefore satisfy these requirements:
ただし、メタデータアノテーションは、異なる当事者によってアドホックな方法で使用されたり、適切なドキュメントなしで使用されたりすると、相互運用性の問題を引き起こす可能性があります。したがって、YANGの適切なメタデータフレームワークは、次の要件を満たす必要があります。
1. The set of annotations must be extensible in a decentralized manner so as to allow for defining new annotations without running the risk of collisions with annotations defined and used by others.
1. アノテーションのセットは、他のユーザーが定義および使用するアノテーションとの衝突のリスクを冒すことなく新しいアノテーションを定義できるように、分散方式で拡張可能である必要があります。
2. The syntax and semantics of annotations must be documented, and the documentation must be easily accessible.
2. アノテーションの構文とセマンティクスは文書化する必要があり、文書は簡単にアクセスできる必要があります。
3. Clients of network management protocols such as NETCONF [RFC6241] or RESTCONF [RESTCONF] must be able to discover all annotations supported by a given server and identify each of them correctly.
3. NETCONF [RFC6241]やRESTCONF [RESTCONF]などのネットワーク管理プロトコルのクライアントは、特定のサーバーでサポートされているすべての注釈を検出して、それぞれを正しく識別できる必要があります。
4. Annotations sent by a server should not break clients that don't support them.
4. サーバーによって送信された注釈は、それらをサポートしないクライアントを壊してはなりません。
This document proposes a systematic way to define metadata annotations. For this purpose, the YANG extension "annotation" is defined in the module "ietf-yang-metadata" (Section 7). Other YANG modules importing this module can use the "annotation" statement for defining one or more annotations.
このドキュメントは、メタデータアノテーションを定義する体系的な方法を提案します。この目的のために、YANG拡張「注釈」がモジュール「ietf-yang-metadata」で定義されています（セクション7）。このモジュールをインポートする他のYANGモジュールは、「注釈」ステートメントを使用して1つ以上の注釈を定義できます。
The benefits of defining the metadata annotations in a YANG module are the following:
YANGモジュールでメタデータアノテーションを定義する利点は次のとおりです。
o Each annotation is bound to a YANG module name and namespace URI. This makes its encoding in instance documents (both XML and JSON) straightforward and consistent with the encoding of YANG data node instances.
o 各アノテーションは、YANGモジュール名と名前空間URIにバインドされています。これにより、インスタンスドキュメント（XMLとJSONの両方）でのエンコーディングが簡単になり、YANGデータノードインスタンスのエンコーディングと一致します。
o Annotations defined in IETF Standards Track documents are indirectly registered through IANA in the "YANG Module Names" registry [RFC6020].
o IETF Standards Trackドキュメントで定義された注釈は、「YANG Module Names」レジストリ[RFC6020]にIANAを介して間接的に登録されます。
o Annotations are included in the data model. YANG compilers and tools supporting a certain annotation can thus take them into account and modify their behavior accordingly.
o 注釈はデータモデルに含まれています。したがって、特定の注釈をサポートするYANGコンパイラとツールは、それらを考慮に入れて、それに応じて動作を変更できます。
o The semantics of an annotation are defined in the "description" and "reference" statements.
o 注釈のセマンティクスは、「説明」および「参照」ステートメントで定義されます。
o An annotation can be declared as conditional by using the "if-feature" statement.
o 「if-feature」ステートメントを使用して、アノテーションを条件付きとして宣言できます。
o The type of each annotation is explicitly specified; any YANG built-in or derived type that is available for leaf or leaf-list data nodes may be specified for annotations as well.
o 各注釈のタイプは明示的に指定されています。リーフまたはリーフリストのデータノードで使用できるYANG組み込み型または派生型は、アノテーションにも指定できます。
In the XML encoding, XML attributes are a natural instrument for attaching annotations to data node instances. This document deliberately adopts some restrictions in order to remain compatible with the XML encoding of YANG data node instances and limitations of XML attributes. Specifically,
XMLエンコーディングでは、XML属性はデータノードインスタンスに注釈を付けるための自然な手段です。このドキュメントでは、YANGデータノードインスタンスのXMLエンコーディングおよびXML属性の制限との互換性を維持するために、意図的にいくつかの制限を採用しています。具体的には
o annotations can only be scalar values.
o 注釈はスカラー値のみにすることができます。
o annotations cannot be attached to a whole list or leaf-list instance, only to individual list or leaf-list entries.
o 注釈は、リスト全体またはリーフリストインスタンスに添付することはできません。個々のリストまたはリーフリストエントリにのみ添付できます。
Due to the rules for YANG extensions (see Section 6.3.1 in [RFC7950]), annotation definitions posit relatively weak conformance requirements. The alternative of introducing a new built-in YANG statement for defining annotations was considered, but it was seen as a major change to the language that is inappropriate for YANG 1.1, which was chartered as a maintenance revision. After evaluating real-life usage of metadata annotations, it is conceivable that such a new built-in statement might be added in a future revision of YANG.
YANG拡張のルール（[RFC7950]のセクション6.3.1を参照）により、アノテーションの定義では比較的弱い適合要件が適用されます。アノテーションを定義するための新しい組み込みYANGステートメントの導入の代替案が検討されましたが、これは、メンテナンスリビジョンとしてチャーターされた、YANG 1.1に不適切な言語への主要な変更と見なされました。メタデータアノテーションの実際の使用法を評価した後、そのような新しい組み込みステートメントがYANGの将来のリビジョンで追加される可能性があると考えられます。
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].
このドキュメントのキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、および「OPTIONAL」は、 [RFC2119]で説明されているように解釈されます。
The following terms are defined in [RFC6241]:
以下の用語は[RFC6241]で定義されています：
o capability
o 能力
o client
o クライアント
o datastore
o データストア
o message
o メッセージ
o protocol operation
o プロトコル操作
o server
o サーバ
The following terms are defined in [RFC7950]:
以下の用語は[RFC7950]で定義されています：
o action
o アクション
o anydata
o anydata
o anyxml
o anyxml
o built-in type
o ビルトインタイプ
o container
o コンテナ
o data model
o データ・モデル
o data node
o だた ので
o data tree
o データツリー
o derived type
o 派生型
o extension
o 拡張
o leaf o leaf-list
oリーフoリーフリスト
o list
o リスト
o module
o モジュール
o Remote Procedure Call (RPC) input and output
o リモートプロシージャコール（RPC）の入力と出力
The following terms are defined in [XML-INFOSET]:
次の用語は、[XML-INFOSET]で定義されています。
o attribute
o 属性
o document
o 資料
o element
o 素子
The following terms are defined in [XML-NAMES]:
[XML-NAMES]には次の用語が定義されています。
o local name
o ローカル名
o namespace name
o 名前空間名
o prefix
o 接頭辞
o qualified name
o 修飾名
The following terms are defined in [RFC7159]:
以下の用語は[RFC7159]で定義されています：
o array
o アレイ
o member
o メンバー
o object
o オブジェクト
o primitive type
o プリミティブ型
In the following text, XML element names and YANG extension statements are always written with explicit namespace prefixes that are assumed to be bound to URI references as shown in Table 1.
次のテキストでは、XML要素名とYANG拡張ステートメントは常に、表1に示すように、URI参照にバインドされると想定される明示的な名前空間接頭辞を使用して記述されます。
+--------+------------------------------------------------+
| Prefix | URI Reference |
+--------+------------------------------------------------+
| elm | http://example.org/example-last-modified |
| md | urn:ietf:params:xml:ns:yang:ietf-yang-metadata |
| rng | http://relaxng.org/ns/structure/1.0 |
+--------+------------------------------------------------+
Table 1: Used Namespace Prefixes and Corresponding URI References
表1：使用される名前空間プレフィックスと対応するURI参照
o annotation: a single item of metadata that is attached to YANG data node instances.
o 注釈：YANGデータノードインスタンスに添付されるメタデータの単一のアイテム。
o metadata: additional information that complements a data tree.
o メタデータ：データツリーを補完する追加情報。
o metadata object: an object in JSON encoding that contains all annotations attached to a given data node instance.
o メタデータオブジェクト：特定のデータノードインスタンスに添付されたすべての注釈を含むJSONエンコーディングのオブジェクト。
Metadata annotations are defined by the YANG extension "md:annotation". This YANG language extension is defined in the module "ietf-yang-metadata" (Section 7).
メタデータアノテーションは、YANG拡張 "md：annotation"によって定義されます。このYANG言語拡張は、モジュール "ietf-yang-metadata"（セクション7）で定義されています。
Substatements of "md:annotation" are shown in Table 2. They are all core YANG statements, and the numbers in the second column refer to the corresponding section in [RFC7950] where each statement is described.
「md：annotation」のサブステートメントを表2に示します。これらはすべてコアYANGステートメントであり、2列目の番号は[RFC7950]の対応するセクションを参照しており、各ステートメントが説明されています。
+--------------+---------------------+-------------+
| substatement | section in RFC 7950 | cardinality |
+--------------+---------------------+-------------+
| description | 7.21.3 | 0..1 |
| if-feature | 7.20.2 | 0..n |
| reference | 7.21.4 | 0..1 |
| status | 7.21.2 | 0..1 |
| type | 7.6.3 | 1 |
| units | 7.3.3 | 0..1 |
+--------------+---------------------+-------------+
Table 2: Substatements of "md:annotation"
表2：「md：annotation」のサブステートメント
An annotation carries a single value. The "type" substatement, which MUST be present, takes as an argument the name of an existing built-in or derived type, and the value of the annotation MUST match this type. See Section 7.4 of [RFC7950] for details.
注釈には単一の値が含まれます。 「type」サブステートメントは存在する必要があり、既存の組み込み型または派生型の名前を引数として取り、注釈の値はこの型と一致する必要があります。詳細については、[RFC7950]のセクション7.4を参照してください。
An annotation can be made conditional by using one or more "if-feature" statements; the annotation is then supported only by servers that advertise the corresponding feature.
注釈は、1つ以上の「if-feature」ステートメントを使用して条件付きにすることができます。アノテーションは、対応する機能をアドバタイズするサーバーによってのみサポートされます。
The semantics and usage rules for an annotation SHOULD be fully specified in "description", "reference", and "units" statements.
注釈のセマンティクスと使用規則は、「description」、「reference」、および「units」ステートメントで完全に指定する必要があります（SHOULD）。
An annotation MUST NOT change the data tree semantics defined by YANG. For example, it is illegal to define and use an annotation that allows for overriding uniqueness of leaf-list entries.
アノテーションは、YANGによって定義されたデータツリーセマンティクスを変更してはなりません（MUST NOT）。たとえば、リーフリストエントリの一意性を上書きできるようにするアノテーションを定義して使用することは違法です。
The "status" statement can be used exactly as it is used for YANG data nodes.
「ステータス」ステートメントは、YANGデータノードで使用されているとおりに使用できます。
A YANG module containing one or more "md:annotation" statements SHOULD NOT be used for defining data nodes or groupings. Also, derived types, identities, and features SHOULD NOT be defined in such a module unless they are used by the definitions of annotations in that module.
1つ以上の「md：annotation」ステートメントを含むYANGモジュールは、データノードまたはグループを定義するために使用してはなりません（SHOULD NOT）。また、派生型、ID、および機能は、そのモジュールの注釈の定義で使用されない限り、そのようなモジュールで定義してはなりません（SHOULD NOT）。
The following module defines the "last-modified" annotation:
次のモジュールは、「最後に変更された」注釈を定義します。
module example-last-modified {
namespace "http://example.org/example-last-modified";
prefix "elm";
import ietf-yang-types {
prefix "yang";
}
import ietf-yang-metadata {
prefix "md";
}
md:annotation last-modified {
type yang:date-and-time;
description
"This annotation contains the date and time when the
annotated instance was last modified (or created).";
}
}
By advertising a YANG module in which a metadata annotation is defined using the "md:annotation" statement, a server indicates that it is prepared to handle that annotation according to the annotation's definition. That is, an annotation advertised by the server may be attached to an instance of a data node defined in any YANG module that is implemented by the server.
「md：annotation」ステートメントを使用してメタデータアノテーションが定義されているYANGモジュールをアドバタイズすることにより、サーバーは、アノテーションの定義に従ってそのアノテーションを処理する準備ができていることを示します。つまり、サーバーによってアドバタイズされた注釈は、サーバーによって実装された任意のYANGモジュールで定義されたデータノードのインスタンスに添付できます。
Depending on its semantics, an annotation may have an effect only in certain data trees and/or on instances of specific types of data nodes.
そのセマンティクスに応じて、注釈は特定のデータツリーや特定のタイプのデータノードのインスタンスにのみ影響を与える可能性があります。
A client MUST NOT add a specific annotation to data node instances if the server didn't advertise it.
サーバーがそれをアドバタイズしなかった場合、クライアントはデータノードインスタンスに特定のアノテーションを追加してはなりません（MUST NOT）。
Due care has to be exercised when introducing annotations in network management systems in order to avoid interoperability problems and software failures caused by a client that does not understand the annotations' semantics. Generally, it is safe for a server to use annotations in the following cases:
アノテーションのセマンティクスを理解していないクライアントによって引き起こされる相互運用性の問題やソフトウェア障害を回避するために、ネットワーク管理システムにアノテーションを導入するときは、十分な注意を払う必要があります。通常、次の場合にサーバーが注釈を使用しても安全です。
o An annotation is an integral part of a built-in or negotiated protocol capability.
o 注釈は、組み込みまたはネゴシエートされたプロトコル機能の不可欠な部分です。
o An annotation contains auxiliary information that is not critical for protocol operation.
o 注釈には、プロトコル操作に重要ではない補助情報が含まれています。
o The client explicitly asks the server, e.g., via a parameter of a protocol operation request, to include an annotation in the response.
o クライアントは、たとえばプロトコル操作要求のパラメータを介して、応答に注釈を含めるようにサーバーに明示的に要求します。
XML attributes are a natural choice for encoding metadata in XML instance documents. For JSON [RFC7159], there is no generally established method for encoding metadata. This document thus introduces a special encoding method that is consistent with the JSON encoding of YANG data node instances as defined in [RFC7951].
XML属性は、XMLインスタンスドキュメントのメタデータをエンコードするための自然な選択です。 JSON [RFC7159]の場合、メタデータをエンコードするための一般的に確立された方法はありません。したがって、このドキュメントでは、[RFC7951]で定義されているYANGデータノードインスタンスのJSONエンコーディングと一致する特別なエンコーディング方式を紹介します。
Metadata annotations are added to XML-encoded instances of YANG data nodes as XML attributes according to these rules:
メタデータアノテーションは、以下のルールに従って、YANGデータノードのXMLエンコードされたインスタンスにXML属性として追加されます。
o The local name of the attribute SHALL be the same as the name of the annotation specified in the argument of the corresponding "md:annotation" statement.
o 属性のローカル名は、対応する「md：annotation」ステートメントの引数で指定された注釈の名前と同じである必要があります。
o The namespace of the attribute SHALL be identified by the URI that appears as the argument of the "namespace" statement in the YANG module where the annotation is defined. It is RECOMMENDED that the prefix specified by the "prefix" statement in the same module be used in the qualified name of the attribute.
o 属性の名前空間は、アノテーションが定義されているYANGモジュールの「namespace」ステートメントの引数として表示されるURIによって識別されるものとします（SHALL）。同じモジュールの「prefix」ステートメントで指定された接頭辞を属性の修飾名で使用することをお勧めします。
o The attribute value SHALL be encoded in the same way as the value of a YANG leaf instance having the same type; see Section 9 of [RFC7950].
o 属性値は、同じタイプのYANGリーフインスタンスの値と同じ方法でエンコードする必要があります（SHALL）。 [RFC7950]のセクション9をご覧ください。
For example, the "last-modified" annotation defined in Section 3.1 may be encoded as follows:
たとえば、セクション3.1で定義された「最終変更」アノテーションは、次のようにエンコードされます。
<foo xmlns:elm="http://example.org/example-last-modified"
elm:last-modified="2015-09-16T10:27:35+02:00">
...
</foo>
The JSON metadata encoding defined in this section has the following properties:
このセクションで定義されているJSONメタデータエンコーディングには、次のプロパティがあります。
1. The encoding of YANG data node instances as defined in [RFC7951] does not change.
1. [RFC7951]で定義されているYANGデータノードインスタンスのエンコーディングは変更されません。
2. Namespaces of metadata annotations are encoded in the same way as namespaces of YANG data node instances; see [RFC7951].
2. メタデータアノテーションの名前空間は、YANGデータノードインスタンスの名前空間と同じ方法でエンコードされます。 [RFC7951]を参照してください。
All metadata annotations assigned to a YANG data node instance are encoded as members (name/value pairs) of a single JSON object, henceforth denoted as the metadata object. The placement and name of this object depend on the type of the data node as specified in the following subsections.
YANGデータノードインスタンスに割り当てられたすべてのメタデータアノテーションは、単一のJSONオブジェクトのメンバー（名前/値のペア）としてエンコードされます。以降、メタデータオブジェクトと呼びます。このオブジェクトの配置と名前は、以下のサブセクションで指定されているデータノードのタイプによって異なります。
The name of a metadata annotation (as a member of the metadata object) has the following ABNF syntax [RFC5234], where the production for "identifier" is defined in Section 14 of [RFC7950]:
メタデータアノテーションの名前（メタデータオブジェクトのメンバーとして）には、次のABNF構文があります[RFC5234]。ここで、「識別子」の生成は[RFC7950]のセクション14で定義されています。
annotation-name = identifier ":" identifier
アノテーション名=識別子「：」識別子
where the left identifier is the name of the YANG module in which the annotation is defined and the identifier on the right is the name of the annotation specified in the argument of the corresponding "md:annotation" statement.
ここで、左側の識別子は注釈が定義されているYANGモジュールの名前であり、右側の識別子は対応する「md：annotation」ステートメントの引数で指定された注釈の名前です。
Note that unlike member names of YANG data node instances in JSON encoding (see Section 4 in [RFC7951]), for annotations the explicit namespace identifier (module name) must always be present.
JSONエンコーディングのYANGデータノードインスタンスのメンバー名とは異なり（[RFC7951]のセクション4を参照）、アノテーションの場合、明示的な名前空間識別子（モジュール名）が常に存在している必要があります。
The value of a metadata annotation SHALL be encoded in exactly the same way as the value of a YANG leaf node having the same type as the annotation; see Section 6 of [RFC7951].
メタデータアノテーションの値は、アノテーションと同じタイプのYANGリーフノードの値とまったく同じ方法でエンコードする必要があります（SHALL）。 [RFC7951]のセクション6をご覧ください。
For a data node instance that is encoded as a JSON object (i.e., a container, list entry, or anydata node), the metadata object is added as a new member of that object with the name "@".
JSONオブジェクト（つまり、コンテナー、リストエントリ、またはanydataノード）としてエンコードされたデータノードインスタンスの場合、メタデータオブジェクトは、 "@"という名前のそのオブジェクトの新しいメンバーとして追加されます。
Examples:
例：
o "cask" is a container or anydata node:
o 「cask」はコンテナまたはanydataノードです。
"cask": {
"@": {
"example-last-modified:last-modified":
"2015-09-16T10:27:35+02:00"
},
...
}
o "seq" is a list whose key is "name"; annotation "last-modified" is added only to the first entry:
o 「seq」は「名前」をキーとするリストです。 「最後に変更された」注釈は、最初のエントリにのみ追加されます。
"seq": [
{
"@": {
"example-last-modified:last-modified":
"2015-09-16T10:27:35+02:00"
},
"name": "one",
...
},
{
"name": "two",
...
}
]
For an anyxml or leaf instance, the metadata object is added as a sibling name/value pair whose name is the symbol "@" concatenated with the name of the leaf or anyxml member that is being annotated. The namespace part (module name) is included if and only if it is in the name of the annotated member.
anyxmlまたはリーフインスタンスの場合、メタデータオブジェクトは兄弟名/値のペアとして追加され、その名前は、注釈が付けられているリーフまたはanyxmlメンバーの名前と連結された記号 "@"です。名前空間部分（モジュール名）は、注釈付きメンバーの名前に含まれている場合にのみ含まれます。
Examples:
例：
o "flag" is a leaf node of the "boolean" type defined in module "foo", and we assume that the namespace name has to be expressed in its JSON encoding:
o 「フラグ」はモジュール「foo」で定義された「ブール」タイプのリーフノードであり、ネームスペース名はそのJSONエンコーディングで表現する必要があると想定します。
"foo:flag": true,
"@foo:flag": {
"example-last-modified:last-modified":
"2015-09-16T10:27:35+02:00"
}
o "stuff" is an anyxml node:
o "stuff"はanyxmlノードです：
"stuff": [1, null, "three"],
"@stuff": {
"example-last-modified:last-modified":
"2015-09-16T10:27:35+02:00"
}
For a leaf-list entry, which is represented as a JSON array with values of a primitive type, annotations may be assigned to one or more entries by adding a name/array pair as a sibling of the leaf-list entry, where the name is the symbol "@" concatenated with the name of the leaf-list that is being annotated, and the value is a JSON array whose i-th element is the metadata object with annotations assigned to the i-th entry of the leaf-list entry, or null if the i-th entry has no annotations.
プリミティブ型の値を持つJSON配列として表されるリーフリストエントリの場合、名前/配列のペアをリーフリストエントリの兄弟として追加することにより、注釈を1つ以上のエントリに割り当てることができます。注釈が付けられているリーフリストの名前と連結された記号 "@"であり、値はJSON配列であり、そのi番目の要素は、リーフリストのi番目のエントリに割り当てられた注釈を持つメタデータオブジェクトです。エントリ。i番目のエントリに注釈がない場合はnull。
Trailing null values in that array, i.e., those following the last non-null metadata object, MAY be omitted.
その配列の後続のnull値、つまり最後のnull以外のメタデータオブジェクトに続くものは省略してもよい（MAY）。
For example, in the following leaf-list instance with four entries, the "last-modified" annotation is added to the second and third entries in the following way:
たとえば、4つのエントリを持つ次のリーフリストインスタンスでは、「最後に変更された」注釈が2番目と3番目のエントリに次のように追加されます。
"bibliomod:folio": [6, 3, 7, 8],
"@bibliomod:folio": [
null,
{ "example-last-modified:last-modified":
"2015-06-18T17:01:14+02:00"
},
{ "example-last-modified:last-modified":
"2015-09-16T10:27:35+02:00"
}
]
[RFC6110] defines the standard mapping of YANG data models to Document Schema Definition Languages (DSDL) [ISO.19757-1]. This section specifies the mapping for the extension statement "md:annotation" (Section 7), which enables validation of XML instance documents containing metadata annotations.
[RFC6110]は、YANGデータモデルのドキュメントスキーマ定義言語（DSDL）[ISO.19757-1]への標準マッピングを定義しています。このセクションでは、メタデータアノテーションを含むXMLインスタンスドキュメントの検証を可能にする拡張ステートメント "md：annotation"（セクション7）のマッピングを指定します。
The first step of the DSDL mapping procedure, i.e., the transformation of the YANG data model to the hybrid schema (see Section 6 in [RFC6110]), is modified as follows:
DSDLマッピング手順の最初のステップ、つまりYANGデータモデルからハイブリッドスキーマへの変換（[RFC6110]のセクション6を参照）は、次のように変更されています。
1. If the data model contains at least one "md:annotation" statement, then a RELAX NG [ISO.19757-2] named pattern definition MUST be added as a child of the root <rng:grammar> element in the hybrid schema. It is RECOMMENDED to use the name "__yang_metadata__" for this named pattern.
1. データモデルに少なくとも1つの "md：annotation"ステートメントが含まれている場合、RELAX NG [ISO.19757-2]名前付きパターン定義をハイブリッドスキーマのルート<rng：grammar>要素の子として追加する必要があります。この名前付きパターンには「__yang_metadata__」という名前を使用することをお勧めします。
2. A reference to the named pattern described in item 1 MUST be included as a child of every <rng:element> pattern that corresponds to an anydata, container, leaf, leaf-list, or list data node.
2. 項目1で説明されている名前付きパターンへの参照は、anydata、コンテナー、リーフ、リーフリスト、またはリストデータノードに対応するすべての<rng：element>パターンの子として含める必要があります。
3. Every metadata annotation definition in the form
3. フォーム内のすべてのメタデータアノテーション定義
md:annotation ARGUMENT {
...
}
is mapped to the following RELAX NG [ISO.19757-2] pattern:
は次のRELAX NG [ISO.19757-2]パターンにマップされます。
<rng:optional>
<rng:attribute name="PREFIX:ARGUMENT">
...
</rng:attribute>
</rng:optional>
where PREFIX is the prefix bound to the namespace URI of the YANG module that contains the "md:annotation" statement. The above pattern SHALL be inserted as a child of the named pattern described in item 1.
PREFIXは、「md：annotation」ステートメントを含むYANGモジュールの名前空間URIにバインドされた接頭辞です。上記のパターンは、項目1で説明した名前付きパターンの子として挿入する必要があります。
4. Substatements of "md:annotation" SHALL be mapped to children of the "rng:attribute" pattern exactly as described in Section 10 of [RFC6110].
4. [md：annotation]のサブステートメントは、[rng：attribute]パターンの子に、[RFC6110]のセクション10で説明されているとおりにマッピングする必要があります（SHALL）。
For example, the named pattern (item 1), when constructed only for the "last-modified" annotation, will have the following definition:
たとえば、名前付きパターン（アイテム1）は、「最後に変更された」アノテーションのみに対して作成された場合、次のように定義されます。
<rng:define name="__yang_metadata__">
<rng:optional>
<rng:attribute name="elm:last-modified">
<rng:ref name="ietf-yang-types__date-and-time"/>
</rng:attribute>
</rng:optional>
</rng:define>
Every "rng:element" pattern that corresponds to an anydata, container, leaf, list, or leaf-list data node will then contain a reference to the above named pattern; for example:
anydata、container、leaf、list、またはleaf-listデータノードに対応するすべての「rng：element」パターンには、上記の名前のパターンへの参照が含まれます。例えば：
<rng:element name="foo:bar">
<rng:ref name="__yang_metadata__"/>
...
</rng:element>
Note that it is not necessary to use such a reference for "rng:element" patterns corresponding to anyxml data nodes because they already permit any XML attributes to be attached to their instances.
anyxmlデータノードに対応する「rng：element」パターンには、そのような参照を使用する必要がないことに注意してください。これは、XML属性をインスタンスに付加することをすでに許可しているためです。
The second step of the DSDL mapping procedure, i.e., the transformation of the hybrid schema to RELAX NG [ISO.19757-2], Schematron [ISO.19757-3], and Document Semantics Renaming Language (DSRL) [ISO.19757-8] schemas, is unaffected by the inclusion of "md:annotation".
DSDLマッピング手順の2番目のステップ、つまり、ハイブリッドスキーマからRELAX NG [ISO.19757-2]、Schematron [ISO.19757-3]、およびDocument Semantics Renaming Language（DSRL）[ISO.19757- 8]スキーマ。 "md：annotation"を含めても影響を受けません。
<CODE BEGINS> file "ietf-yang-metadata@2016-08-05.yang"
module ietf-yang-metadata {
ietf-the-metadataモジュール{
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata";
prefix "md";
接頭辞 "md";
organization "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
組織「IETF NETMOD（NETCONFデータモデリング言語）ワーキンググループ」;
contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
WG Chair: Lou Berger
<mailto:lberger@labn.net>
WG Chair: Kent Watsen
<mailto:kwatsen@juniper.net>
Editor: Ladislav Lhotka
<mailto:lhotka@nic.cz>";
description "This YANG module defines an 'extension' statement that allows for defining metadata annotations.
説明「このYANGモジュールは、メタデータアノテーションを定義できる「拡張」ステートメントを定義します。
Copyright (c) 2016 IETF Trust and the persons identified as authors of the code. All rights reserved.
Copyright（c）2016 IETF Trustおよびコードの作成者として識別された人物。全著作権所有。
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 Relating to IETF Documents (http://trustee.ietf.org/license-info).
ソースおよびバイナリ形式での再配布および使用は、変更の有無にかかわらず、IETFドキュメントに関連するIETFトラストの法的規定のセクション4.cに記載されているSimplified BSD Licenseに準拠し、それに含まれるライセンス条項に従って許可されます（ http://trustee.ietf.org/license-info）。
This version of this YANG module is part of RFC 7952
(http://www.rfc-editor.org/info/rfc7952); see the RFC itself
for full legal notices.";
revision 2016-08-05 {
description
"Initial revision.";
reference
"RFC 7952: Defining and Using Metadata with YANG";
}
extension annotation {
argument name;
description
"This extension allows for defining metadata annotations in
YANG modules. The 'md:annotation' statement can appear only
at the top level of a YANG module or submodule, i.e., it
becomes a new alternative in the ABNF production rule for
'body-stmts' (Section 14 in RFC 7950).
The argument of the 'md:annotation' statement defines the name of the annotation. Syntactically, it is a YANG identifier as defined in Section 6.2 of RFC 7950.
「md：annotation」ステートメントの引数は、注釈の名前を定義します。構文的には、RFC 7950のセクション6.2で定義されているYANG識別子です。
An annotation defined with this 'extension' statement inherits the namespace and other context from the YANG module in which it is defined.
この「拡張」ステートメントで定義された注釈は、それが定義されているYANGモジュールから名前空間とその他のコンテキストを継承します。
The data type of the annotation value is specified in the same way as for a leaf data node using the 'type' statement.
注釈値のデータ型は、「type」ステートメントを使用してリーフデータノードと同じ方法で指定されます。
The semantics of the annotation and other documentation can be specified using the following standard YANG substatements (all are optional): 'description', 'if-feature', 'reference', 'status', and 'units'.
注釈およびその他のドキュメントのセマンティクスは、次の標準のYANGサブステートメント（すべてオプション）を使用して指定できます： 'description'、 'if-feature'、 'reference'、 'status'、および 'units'。
A server announces support for a particular annotation by including the module in which the annotation is defined among the advertised YANG modules, e.g., in a NETCONF <hello> message or in the YANG library (RFC 7950). The annotation can then be attached to any instance of a data node defined in any YANG module that is advertised by the server.
サーバーは、NETCONF <hello>メッセージやYANGライブラリー（RFC 7950）などの通知されたYANGモジュール間でアノテーションが定義されているモジュールを含めることにより、特定のアノテーションのサポートを発表します。その後、注釈は、サーバーによってアドバタイズされる任意のYANGモジュールで定義されたデータノードの任意のインスタンスに添付できます。
XML encoding and JSON encoding of annotations are defined in
RFC 7952.";
}
}
<CODE ENDS>
<コード終了>
This document registers a URI in the "IETF XML Registry" [RFC3688]. Following the format in RFC 3688, the following registration has been made.
このドキュメントは、「IETF XMLレジストリ」[RFC3688]にURIを登録します。 RFC 3688のフォーマットに従って、次の登録が行われました。
---------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-yang-metadata
Registrant Contact: The NETMOD WG of the IETF.
登録者の連絡先：IETFのNETMOD WG。
XML: N/A, the requested URI is an XML namespace.
---------------------------------------------------------------------
This document registers a YANG module in the "YANG Module Names" registry [RFC6020].
このドキュメントでは、「YANGモジュール名」レジストリ[RFC6020]にYANGモジュールを登録しています。
---------------------------------------------------------------------
Name: ietf-yang-metadata
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-metadata
Prefix: md
Reference: RFC 7952
---------------------------------------------------------------------
This document introduces a mechanism for defining metadata annotations in YANG modules and attaching them to instances of YANG data nodes. By itself, this mechanism represents no security threat. Security implications of a particular annotation defined using this mechanism MUST be duly considered and documented in the annotation's definition.
このドキュメントでは、YANGモジュールでメタデータアノテーションを定義し、それらをYANGデータノードのインスタンスにアタッチするメカニズムを紹介します。このメカニズム自体は、セキュリティ上の脅威にはなりません。このメカニズムを使用して定義された特定の注釈のセキュリティへの影響は、適切に検討され、注釈の定義に文書化されている必要があります。
An annotation SHOULD be subject to the same or stricter access control rules as the data node instance to which the annotation is attached. It is RECOMMENDED that security-sensitive or privacy-sensitive data be modeled as regular YANG data nodes rather than annotations.
アノテーションは、そのアノテーションが添付されているデータノードインスタンスと同じまたはより厳密なアクセス制御規則に従う必要があります（SHOULD）。セキュリティやプライバシーに配慮したデータは、アノテーションではなく通常のYANGデータノードとしてモデル化することをお勧めします。
[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>。
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <http://www.rfc-editor.org/info/rfc3688>.
[RFC3688] Mealling、M。、「The IETF XML Registry」、BCP 81、RFC 3688、DOI 10.17487 / RFC3688、2004年1月、<http://www.rfc-editor.org/info/rfc3688>。
[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]クロッカー、D。、エド。およびP. Overell、「構文仕様の拡張BNF：ABNF」、STD 68、RFC 5234、DOI 10.17487 / RFC5234、2008年1月、<http://www.rfc-editor.org/info/rfc5234>。
[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。、編、「YANG-ネットワーク構成プロトコル（NETCONF）のデータモデリング言語」、RFC 6020、DOI 10.17487 / RFC6020、2010年10月、<http：//www.rfc-editor。 org / info / rfc6020>。
[RFC6110] Lhotka, L., Ed., "Mapping YANG to Document Schema Definition Languages and Validating NETCONF Content", RFC 6110, DOI 10.17487/RFC6110, February 2011, <http://www.rfc-editor.org/info/rfc6110>.
[RFC6110] Lhotka、L。、編、「YANGをドキュメントスキーマ定義言語にマッピングしてNETCONFコンテンツを検証する」、RFC 6110、DOI 10.17487 / RFC6110、2011年2月、<http://www.rfc-editor.org/info / rfc6110>。
[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]ブレイ、T。、編、「JavaScript Object Notation（JSON）データ交換フォーマット」、RFC 7159、DOI 10.17487 / RFC7159、2014年3月、<http://www.rfc-editor.org/info/ rfc7159>。
[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。、編、「The YANG 1.1 Data Modeling Language」、RFC 7950、DOI 10.17487 / RFC7950、2016年8月、<http://www.rfc-editor.org/info/rfc7950>。
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <http://www.rfc-editor.org/info/rfc7951>.
[RFC7951] Lhotka、L。、「YANGでモデル化されたデータのJSONエンコーディング」、RFC 7951、DOI 10.17487 / RFC7951、2016年8月、<http://www.rfc-editor.org/info/rfc7951>。
[XML-INFOSET] Cowan, J. and R. Tobin, "XML Information Set (Second Edition)", World Wide Web Consortium Recommendation REC-xml-infoset-20040204, February 2004, <http://www.w3.org/TR/2004/REC-xml-infoset-20040204>.
[XML-INFOSET] Cowan、J。およびR. Tobin、「XML Information Set（Second Edition）」、World Wide Web Consortium Recommendation REC-xml-infoset-20040204、2004年2月、<http://www.w3.org / TR / 2004 / REC-xml-infoset-20040204>。
[XML-NAMES] Bray, T., Hollander, D., Layman, A., Tobin, R., and H. Thompson, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208, December 2009, <http://www.w3.org/TR/2009/REC-xml-names-20091208>.
[XML-NAMES] Bray、T.、Hollander、D.、Layman、A.、Tobin、R。、およびH. Thompson、「Namespaces in XML 1.0（Third Edition）」、World Wide Web Consortium Recommendation REC-xml- names-20091208、2009年12月、<http://www.w3.org/TR/2009/REC-xml-names-20091208>。
[ISO.19757-1] International Organization for Standardization, "Information Technology - Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, September 2008.
[ISO.19757-1]国際標準化機構、「情報技術-ドキュメントスキーマ定義言語（DSDL）-パート1：概要」、ISO / IEC 19757-1、2008年9月。
[ISO.19757-2] International Organization for Standardization, "Information technology -- Document Schema Definition Language (DSDL) -- Part 2: Regular-grammar-based validation -- RELAX NG", ISO/IEC 19757-2:2008, December 2008.
[ISO.19757-2]国際標準化機構、「情報技術-ドキュメントスキーマ定義言語（DSDL）-パート2：通常の文法ベースの検証-RELAX NG」、ISO / IEC 19757-2：2008、 2008年12月。
[ISO.19757-3] International Organization for Standardization, "Information technology -- Document Schema Definition Languages (DSDL) -- Part 3: Rule-based validation -- Schematron", ISO/IEC 19757-3:2016, January 2016.
[ISO.19757-3]国際標準化機構、「情報技術-ドキュメントスキーマ定義言語（DSDL）-パート3：ルールベースの検証-Schematron」、ISO / IEC 19757-3：2016、2016年1月。
[ISO.19757-8] International Organization for Standardization, "Information Technology - Document Schema Definition Languages (DSDL) - Part 8: Document Semantics Renaming Language - DSRL", ISO/IEC 19757-8:2008(E), December 2008.
[ISO.19757-8]国際標準化機構、「情報技術-ドキュメントスキーマ定義言語（DSDL）-パート8：ドキュメントセマンティクスの名前変更言語-DSRL」、ISO / IEC 19757-8：2008（E）、2008年12月。
[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 Protocol」、Work in Progress、draft-ietf-netconf-restconf-16、2016年8月。
[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。、編、Bjorklund、M。、編、Schoenwaelder、J。、編、およびA. Bierman、編、「Network Configuration Protocol（NETCONF）」、RFC 6241、DOI 10.17487 / RFC6241、2011年6月、<http://www.rfc-editor.org/info/rfc6241>。
Acknowledgements
謝辞
The author wishes to thank Andy Bierman, Martin Bjorklund, Benoit Claise, Juergen Schoenwaelder, and Kent Watsen for their helpful comments and suggestions.
著者は、アンディビアマン、マーティンビョークルンド、ブノワクレイズ、ユルゲンシェーンヴェルダー、およびケントワッセンに有益なコメントと提案を提供してくれたことに感謝します。
Author's Address
著者のアドレス
Ladislav Lhotka CZ.NIC
ラディスラフ・ロトカCZ.NIC
Email: lhotka@nic.cz