draft-ietf-netmod-yang-data-ext-04.txt   draft-ietf-netmod-yang-data-ext-05.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Updates: 8340 (if approved) M. Bjorklund Updates: 8340 (if approved) M. Bjorklund
Intended status: Standards Track Cisco Intended status: Standards Track Cisco
Expires: January 16, 2020 K. Watsen Expires: June 12, 2020 K. Watsen
Watsen Networks Watsen Networks
July 15, 2019 December 10, 2019
YANG Data Structure Extensions YANG Data Structure Extensions
draft-ietf-netmod-yang-data-ext-04 draft-ietf-netmod-yang-data-ext-05
Abstract Abstract
This document describes YANG mechanisms for defining abstract data This document describes YANG mechanisms for defining abstract data
structures with YANG. structures with YANG.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 16, 2020. This Internet-Draft will expire on June 12, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 12 skipping to change at page 2, line 12
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 4 3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 5
4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5 4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . 11 7.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11
A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11 A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11
A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13 A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13
A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13 A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13
A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14 A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14
A.5. "structure" example that defines a non-top-level A.5. "structure" example that defines a non-top-level
structure . . . . . . . . . . . . . . . . . . . . . . . . 14 structure . . . . . . . . . . . . . . . . . . . . . . . . 14
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
B.1. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 15
B.2. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 15
B.3. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 15
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
There is a need for standard mechanisms to allow the definition of There is a need for standard mechanisms to allow the definition of
abstract data that is not intended to be implemented as configuration abstract data that is not intended to be implemented as configuration
or operational state. The "yang-data" extension statement from RFC or operational state. The "yang-data" extension statement from RFC
8040 [RFC8040] was defined for this purpose but it is limited in its 8040 [RFC8040] was defined for this purpose but it is limited in its
functionality. functionality.
The intended use of the "yang-data" extension was to model all or The intended use of the "yang-data" extension was to model all or
part of a protocol message, such as the "errors" definition in the part of a protocol message, such as the "errors" definition in the
YANG module "ietf-restconf" [RFC8040], or the contents of a file. YANG module "ietf-restconf" [RFC8040], or the contents of a file.
However, protocols are often layered such that the header or payload However, protocols are often layered such that the header or payload
portions of the message can be extended by external documents. The portions of the message can be extended by external documents. The
YANG statements that model a protocol need to support this YANG statements that model a protocol need to support this
extensibility that is already found in that protocol. extensibility that is already found in that protocol.
The "yang-data" extension from [RFC8040] has been copied here, This document defines a new YANG extension statement called
renamed to "structure", and updated to be more flexible. There is no "structure", which is similar to but more flexible than the
assumption that a YANG data structure can only be used as a top-level "yang-data" extension from [RFC8040]. There is no assumption that a
abstraction, instead of nested within some other data structure. YANG data structure can only be used as a top-level abstraction, and
it may also be nested within some other data structure.
This document also defines a new YANG extension statement called This document also defines a new YANG extension statement called
"augment-structure", which allows abstract data structures to be "augment-structure", which allows abstract data structures to be
augmented from external modules, similar to the existing YANG augmented from external modules, similarly to the existing YANG
"augment" statement. Note that "augment" cannot be used to augment a "augment" statement. Note that "augment" cannot be used to augment a
YANG data structure since a YANG compiler or other tool is not YANG data structure since a YANG compiler or other tool is not
required to understand the "structure" extension. required to understand the "structure" extension.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The following terms are used within this document: The following terms are used within this document:
o YANG data structure: A data structure defined with the "structure" o YANG data structure: A data structure defined with the "structure"
statement. statement.
1.1.1. NMDA 1.1.1. NMDA
The following terms are defined in the Network Management Datastore The following terms are defined in the Network Management Datastore
Architecture (NMDA) [RFC8342]. and are not redefined here: Architecture (NMDA) [RFC8342], and are not redefined here:
o configuration o configuration
o operational state o operational state
1.1.2. YANG 1.1.2. YANG
The following terms are defined in [RFC7950]: The following terms are defined in [RFC7950]:
o absolute-schema-nodeid o absolute-schema-nodeid
skipping to change at page 4, line 4 skipping to change at page 3, line 46
o container o container
o data definition statement o data definition statement
o data node o data node
o leaf o leaf
o leaf-list o leaf-list
o list o list
2. Definitions 2. Definitions
A YANG Data Structure is defined with the "structure" extension A YANG data structure is defined with the "structure" extension
statement, defined in the YANG module "ietf-yang-structure-ext". The statement, defined in the YANG module "ietf-yang-structure-ext". The
argument to the "structure" extension statement is the name of the argument to the "structure" extension statement is the name of the
data structure. The data structures are considered to be in the same data structure. The data structures are considered to be in the same
identifier namespace as defined in section 6.2.1 of [RFC7950]. In identifier namespace as defined in section 6.2.1 of [RFC7950]. In
particular, bullet 7: particular, bullet 7:
All leafs, leaf-lists, lists, containers, choices, rpcs, actions, All leafs, leaf-lists, lists, containers, choices, rpcs, actions,
notifications, anydatas, and anyxmls defined (directly or through notifications, anydatas, and anyxmls defined (directly or through
a "uses" statement) within a parent node or at the top level of a "uses" statement) within a parent node or at the top level of
the module or its submodules share the same identifier namespace. the module or its submodules share the same identifier namespace.
This means that data structures defined with the "structure" This means that data structures defined with the "structure"
statement cannot have the same name as sibling nodes from regular statement cannot have the same name as sibling nodes from regular
YANG data definition statements or other "structure" statements in YANG data definition statements or other "structure" statements in
the same YANG module. the same YANG module.
This does not mean a YANG data structure has to be used as a top- This does not mean a YANG data structure, once defined, has to be
level protocol message or other top-level data structure. used as a top-level protocol message or other top-level data
structure.
A YANG data structure is encoded in the same way as an "anydata"
node. This means that the name of the structure is encoded as a
"container", with the instantiated children encoded as child nodes to
this node. For example, this structure:
module example-errors {
...
sx:structure my-error {
leaf error-number {
type int;
}
}
}
can be encoded in JSON as:
"example-errors:my-error": {
"error-number": 131
}
3. YANG Data Structures in YANG Tree Diagrams 3. YANG Data Structures in YANG Tree Diagrams
A YANG Data Structure can be printed in a YANG Tree Diagram A YANG data structure can be printed in a YANG Tree Diagram
[RFC8340]. This document updates RFC 8340 by defining two new [RFC8340]. This document updates RFC 8340 by defining two new
sections in the tree diagram for a module: sections in the tree diagram for a module:
1. YANG data structures, offset by two spaces and identified by the 1. YANG data structures, offset by two spaces and identified by the
keyword "structure" followed by the name of the YANG data keyword "structure" followed by the name of the YANG data
structure and a colon (":") character. structure and a colon (":") character.
2. YANG data structure augmentations, offset by 2 spaces and 2. YANG data structure augmentations, offset by 2 spaces and
identified by the keyword "augment-structure" followed by the identified by the keyword "augment-structure" followed by the
augment target structure name and a colon (":") character. augment target structure name and a colon (":") character.
The new sections, including spaces conventions is: The new sections, including spaces conventions is:
structure <structure-name>: structure <structure-name>:
+--<node> +--<node>
+--<node> +--<node>
| +--<node> | +--<node>
+--<node> +--<node>
structure <structure-name>: structure <structure-name>:
+--<node> +--<node>
augment-structure <structure-name>: augment-structure <structure-name>:
+--<node> +--<node>
+--<node> +--<node>
| +--<node> | +--<node>
+--<node> +--<node>
augment-structure <structure-name>: augment-structure <structure-name>:
+--<node> +--<node>
Nodes in YANG data structures are printed according to the rules
defined in section 2.6 in [RFC8340].
4. YANG Data Structure Extensions Module 4. YANG Data Structure Extensions Module
RFC Ed.: update the date below with the date of RFC publication and RFC Ed.: update the date below with the date of RFC publication and
remove this note. remove this note.
<CODE BEGINS> file "ietf-yang-structure-ext@2019-03-07.yang" <CODE BEGINS> file "ietf-yang-structure-ext@2019-03-07.yang"
module ietf-yang-structure-ext { module ietf-yang-structure-ext {
yang-version 1.1; yang-version 1.1;
skipping to change at page 6, line 8 skipping to change at page 6, line 27
description description
"This module contains conceptual YANG specifications for defining "This module contains conceptual YANG specifications for defining
abstract data structures. abstract data structures.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here. they appear in all capitals, as shown here.
Copyright (c) 2019 IETF Trust and the persons identified Copyright (c) 2019 IETF Trust and the persons identified as
as authors of the code. All rights reserved. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject to
to the license terms contained in, the Simplified BSD License the license terms contained in, the Simplified BSD License set
set forth in Section 4.c of the IETF Trust's Legal Provisions forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info)."; (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX
(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
for full legal notices.";
// RFC Ed.: update the date below with the date of RFC publication // RFC Ed.: update the date below with the date of RFC publication
// and remove this note. // and remove this note.
revision 2019-03-07 { revision 2019-03-07 {
description description
"Initial revision."; "Initial revision.";
// RFC Ed.: replace XXXX with RFC number and remove this note // RFC Ed.: replace XXXX with RFC number and remove this note
reference reference
"RFC XXXX: YANG Structure Extensions."; "RFC XXXX: YANG Structure Extensions.";
skipping to change at page 7, line 16 skipping to change at page 7, line 39
rules below, where the rules are defined in RFC 7950: rules below, where the rules are defined in RFC 7950:
*must-stmt *must-stmt
[status-stmt] [status-stmt]
[description-stmt] [description-stmt]
[reference-stmt] [reference-stmt]
*(typedef-stmt / grouping-stmt) *(typedef-stmt / grouping-stmt)
*data-def-stmt *data-def-stmt
A YANG data structure defined with this extension statement is A YANG data structure defined with this extension statement is
encoded in the same way as an 'anydata' statement. This means encoded in the same way as an 'anydata' node. This means
that the name of the structure is encoded as a 'container', that the name of the structure is encoded as a 'container',
with the instantiated child statements encoded as child nodes with the instantiated child statements encoded as child nodes
to this node. to this node.
The module name and namespace value for the YANG module using The module name and namespace value for the YANG module using
the extension statement is assigned to each of the data the extension statement is assigned to each of the data
definition statements resulting from the YANG data structure. definition statements resulting from the YANG data structure.
The XPath document element is the extension statement itself, The XPath document element is the extension statement itself,
such that the child nodes of the document element are such that the child nodes of the document element are
skipping to change at page 11, line 16 skipping to change at page 11, line 37
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020, the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010, DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>. <https://www.rfc-editor.org/info/rfc6020>.
7.3. URIs
[1] https://github.com/netmod-wg/yang-data-ext/issues
Appendix A. Examples Appendix A. Examples
A.1. "structure" Example A.1. "structure" Example
This example shows a simple address book that could be stored as an This example shows a simple address book that could be stored as an
artifact. artifact.
module example-module { module example-module {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:example-module"; namespace "urn:example:example-module";
skipping to change at page 14, line 13 skipping to change at page 14, line 13
This example shows how an address book can be encoded in XML: This example shows how an address book can be encoded in XML:
<address-book xmlns="urn:example:example-module"> <address-book xmlns="urn:example:example-module">
<address> <address>
<last>Flintstone</last> <last>Flintstone</last>
<first>Fred</first> <first>Fred</first>
<street>301 Cobblestone Way</street> <street>301 Cobblestone Way</street>
<city>Bedrock</city> <city>Bedrock</city>
<zipcode xmlns="urn:example:example-module-aug">70777</zipcode> <zipcode xmlns="urn:example:example-module-aug">70777</zipcode>
</address> </address>
<address>
<last>Root</last>
<first>Charlie</first>
<street>4711 Cobblestone Way</street>
<city>Bedrock</city>
<zipcode xmlns="urn:example:example-module-aug">70777</zipcode>
</address>
</address-book> </address-book>
A.4. JSON Encoding Example A.4. JSON Encoding Example
This example shows how an address book can be encoded in JSON: This example shows how an address book can be encoded in JSON:
"example-module:address-book": { "example-module:address-book": {
"address": [ "address": [
{ {
"city": "Bedrock", "city": "Bedrock",
"example-module-aug:zipcode": "70777", "example-module-aug:zipcode": "70777",
"first": "Fred", "first": "Fred",
"last": "Flintstone", "last": "Flintstone",
"street": "301 Cobblestone Way" "street": "301 Cobblestone Way"
},
{
"city": "Bedrock",
"example-module-aug:zipcode": "70777",
"first": "Charlie",
"last": "Root",
"street": "4711 Cobblestone Way"
} }
] ]
} }
A.5. "structure" example that defines a non-top-level structure A.5. "structure" example that defines a non-top-level structure
The following example defines a data structure with error The following example defines a data structure with error
information, that can be included in an <error-info> element in an information, that can be included in an <error-info> element in an
<rpc-error>. <rpc-error>.
skipping to change at page 15, line 22 skipping to change at page 15, line 40
<error-severity>error</error-severity> <error-severity>error</error-severity>
<error-info> <error-info>
<my-example-error-info <my-example-error-info
xmlns="urn:example:example-error-info"> xmlns="urn:example:example-error-info">
<error-code>42</error-code> <error-code>42</error-code>
</my-example-error-info> </my-example-error-info>
</error-info> </error-info>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
Appendix B. Change Log
RFC Ed.: remove this section before publication.
B.1. v02 to v03
o added YANG tree diagram syntax
o added more examples
B.2. v01 to v02
o terminology fixes (use the term "structure" instead of "template")
o renamed the statement to "structure" from "yang-data"
o removed limitations on if-feature and identities in YANG
structures
B.3. v00 to v01
o moved open issues to github
o added examples section
o filled in IANA considerations
Appendix C. Open Issues
RFC Ed.: remove this section before publication.
The YANG Data Structure Extensions issues are tracked on github.com:
https://github.com/netmod-wg/yang-data-ext/issues [1]
Authors' Addresses Authors' Addresses
Andy Bierman Andy Bierman
YumaWorks YumaWorks
Email: andy@yumaworks.com Email: andy@yumaworks.com
Martin Bjorklund Martin Bjorklund
Cisco Cisco
 End of changes. 24 change blocks. 
83 lines changed or deleted 84 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/