draft-ietf-netmod-yang-data-ext-02.txt   draft-ietf-netmod-yang-data-ext-03.txt 
Network Working Group A. Bierman Network Working Group A. Bierman
Internet-Draft YumaWorks Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund Intended status: Standards Track M. Bjorklund
Expires: September 9, 2019 Cisco Expires: October 17, 2019 Cisco
K. Watsen K. Watsen
Watsen Networks Watsen Networks
March 8, 2019 April 15, 2019
YANG Data Structure Extensions YANG Data Structure Extensions
draft-ietf-netmod-yang-data-ext-02 draft-ietf-netmod-yang-data-ext-03
Abstract Abstract
This document describes YANG mechanisms for defining abstract data This document describes YANG mechanisms for defining abstract data
structures with YANG. It is intended to replace and extend the structures with YANG.
"yang-data" extension statement defined in RFC 8040.
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.
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 http://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 September 9, 2019. This Internet-Draft will expire on October 17, 2019.
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
(http://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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
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 Structure Extensions Module . . . . . . . . . . . . 4 3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 4
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5
4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6.1. Normative References . . . . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
6.2. Informative References . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . 10
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10 7.2. Informative References . . . . . . . . . . . . . . . . . 11
A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 10 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11
A.2. "augment-structure" Example . . . . . . . . . . . . . . . 11 A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11
A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 12 A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13
A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 12 A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13 A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14
B.1. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 13 A.5. "structure" example that defines a non-top-level
B.2. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 13 structure . . . . . . . . . . . . . . . . . . . . . . . . 14
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 13 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 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
skipping to change at page 4, line 27 skipping to change at page 4, line 28
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 has to be used as a top-
level protocol message or other top-level data structure. level protocol message or other top-level data structure.
3. YANG Data Structure Extensions Module 3. YANG Data Structures in YANG Tree Diagrams
A YANG Data Structure can be printed in a YANG Tree Diagram
[RFC8340]. This document defines two new sections in the tree
diagram for a module:
1. YANG data structures, offset by two spaces and identified by the
keyword "structure" followed by the name of the YANG data
structure and a colon (":") character.
2. YANG data structure augmentations, offset by 2 spaces and
identified by the keyword "augment-structure" followed by the
augment target structure name and a colon (":") character.
The new sections, including spaces conventions is:
structure <structure-name>:
+--<node>
+--<node>
| +--<node>
+--<node>
structure <structure-name>:
+--<node>
augment-structure <structure-name>:
+--<node>
+--<node>
| +--<node>
+--<node>
augment-structure <structure-name>:
+--<node>
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;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext";
prefix sx; prefix sx;
skipping to change at page 9, line 5 skipping to change at page 9, line 42
leaf add-leaf1 { type int32; } leaf add-leaf1 { type int32; }
leaf add-leaf2 { type string; } leaf add-leaf2 { type string; }
} }
} }
"; ";
} }
} }
<CODE ENDS> <CODE ENDS>
4. IANA Considerations 5. IANA Considerations
4.1. YANG Module Registry 5.1. YANG Module Registry
This document registers one URI as a namespace in the "IETF XML This document registers one URI as a namespace in the "IETF XML
Registry" [RFC3688]: Registry" [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A; the requested URI is an XML namespace. XML: N/A; the requested URI is an XML namespace.
This document registers one YANG module in the "YANG Module Names" This document registers one YANG module in the "YANG Module Names"
registry [RFC6020]: registry [RFC6020]:
name: ietf-yang-structure-ext name: ietf-yang-structure-ext
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext
prefix: sx prefix: sx
// RFC Ed.: replace XXXX with RFC number and remove this note // RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFC XXXX reference: RFC XXXX
5. Security Considerations 6. Security Considerations
This document defines YANG extensions that are used to define This document defines YANG extensions that are used to define
conceptual YANG data structures. It does not introduce any new conceptual YANG data structures. It does not introduce any new
vulnerabilities beyond those specified in YANG 1.1 [RFC7950]. vulnerabilities beyond those specified in YANG 1.1 [RFC7950].
6. References 7. References
6.1. Normative References 7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119,
RFC2119, March 1997, <https://www.rfc-editor.org/info/ DOI 10.17487/RFC2119, March 1997,
rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>. <https://www.rfc-editor.org/info/rfc8342>.
6.2. Informative References 7.2. Informative References
[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, <https://www.rfc- DOI 10.17487/RFC3688, January 2004,
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, <https://www.rfc- DOI 10.17487/RFC6020, October 2010,
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;
skipping to change at page 11, line 41 skipping to change at page 12, line 41
description "City name"; description "City name";
} }
leaf state { leaf state {
type string; type string;
description "State name"; description "State name";
} }
} }
} }
} }
Below is the tree diagram of this module.
module: example-module
structure address-book:
+-- address* [last first]
+-- last string
+-- first string
+-- street? string
+-- city? string
+-- state? string
A.2. "augment-structure" Example A.2. "augment-structure" Example
This example adds "county" and "zipcode" leafs to the address book: This example adds "county" and "zipcode" leafs to the address book:
module example-module-aug { module example-module-aug {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:example-module-aug"; namespace "urn:example:example-module-aug";
prefix exma; prefix exma;
import ietf-yang-structure-ext { import ietf-yang-structure-ext {
skipping to change at page 12, line 29 skipping to change at page 13, line 33
type string; type string;
description "County name"; description "County name";
} }
leaf zipcode { leaf zipcode {
type string; type string;
description "Postal zipcode"; description "Postal zipcode";
} }
} }
} }
Below is the tree diagram of this module.
module: example-module-aug
augment-structure /exm:address-book/exm:address:
+-- county? string
+-- zipcode? string
A.3. XML Encoding Example A.3. XML Encoding Example
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>
skipping to change at page 13, line 17 skipping to change at page 14, line 31
{ {
"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"
} }
] ]
} }
A.5. "structure" example that defines a non-top-level structure
The following example defines a data structure with error
information, that can be included in an <error-info> element in an
<rpc-error>.
module example-error-info {
yang-version 1.1;
namespace "urn:example:example-error-info";
prefix exei;
import ietf-yang-structure-ext {
prefix sx;
}
sx:structure my-example-error-info {
leaf error-code {
type uint32;
}
}
}
The example below shows how this structure can be used in an
<rpc-error>.
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>operation-failed</error-tag>
<error-severity>error</error-severity>
<error-info>
<my-example-error-info
xmlns="urn:example:example-error-info">
<error-code>42</error-code>
</my-example-error-info>
</error-info>
</rpc-error>
</rpc-reply>
Appendix B. Change Log Appendix B. Change Log
RFC Ed.: remove this section before publication. RFC Ed.: remove this section before publication.
B.1. v01 to v02 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 terminology fixes (use the term "structure" instead of "template")
o renamed the statement to "structure" from "yang-data" o renamed the statement to "structure" from "yang-data"
o removed limitations on if-feature and identities in YANG o removed limitations on if-feature and identities in YANG
structures structures
B.2. v00 to v01 B.3. v00 to v01
o moved open issues to github o moved open issues to github
o added examples section o added examples section
o filled in IANA considerations o filled in IANA considerations
Appendix C. Open Issues Appendix C. Open Issues
RFC Ed.: remove this section before publication. RFC Ed.: remove this section before publication.
The YANG Data Structure Extensions issues are tracked on github.com: The YANG Data Structure Extensions issues are tracked on github.com:
https://github.com/netmod-wg/yang-data-ext/issues 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
Email: mbj@tail-f.com Email: mbj@tail-f.com
Kent Watsen Kent Watsen
Watsen Networks Watsen Networks
Email: kent+ietf@watsen.net Email: kent+ietf@watsen.net
 End of changes. 26 change blocks. 
42 lines changed or deleted 152 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/