Internet DRAFT - draft-vassilev-netmod-yang-direct-must-augment-ext
draft-vassilev-netmod-yang-direct-must-augment-ext
Network Working Group V. Vassilev
Internet-Draft Transpacket
Intended status: Standards Track June 12, 2015
Expires: December 14, 2015
YANG Direct Must Augment Extension
draft-vassilev-netmod-yang-direct-must-augment-ext-00
Abstract
This document introduces new YANG extension statement for assignment
of must sub-statements to existing data nodes through augment without
the requirement for a parent data node containing the must statement.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 14, 2015.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
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.
Vassilev Expires December 14, 2015 [Page 1]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 3
1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 4
1.3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Using Direct Must Augment Extension . . . . . . . . . . . . . 5
3. Direct Must Augment Extension Module . . . . . . . . . . . . . 6
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4.1. DIRECT-MUST-AUGMENT-EX XML Namespace . . . . . . . . . . . 8
4.2. DIRECT-MUST-AUGMENT-EX YANG Module . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Example Data Models . . . . . . . . . . . . . . . . . 11
A.1. Model of a Generic Entertainment Facility . . . . . . . . 11
A.2. Model of a Casino . . . . . . . . . . . . . . . . . . . . 13
A.3. Model of a Zoo . . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
Vassilev Expires December 14, 2015 [Page 2]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
1. Introduction
The possibility to introduce new sub-statements to existing data
nodes available in YANG [RFC6020] provides great flexibility to the
authors of data models. However not all sub-statements can be added
to existing data nodes through augment. It is not possible to add
new must sub-statements. In certain use cases this limitation
complicates the task of expressing valid data constraints as must
statements. This document explains the problem Section 1.2 and
proposes a solution Section 1.3.
1.1. Terminology
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119].
1.1.1. YANG
The following terms are defined in [RFC6020]:
o must statement
o augment statement
o context node
o container
o data node
o key leaf
o leaf
o leaf-list
o list
1.1.2. Tree Diagrams
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as
follows:
Vassilev Expires December 14, 2015 [Page 3]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration
(read-write) and "ro" state data (read-only).
o Symbols after data node names: "?" means an optional node and "*"
denotes a "list" and "leaf-list".
o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not
shown.
1.2. Problem Statement
This document attempts to address the problem YANG model authors
encounter when expressing valid data constraints with must statements
and wish to use existing model data node as context node for the
Xpath expression. The problem is significant in the cases where the
context data node has to be evaluated as part of a relative path
expressions using . or current(). An example where this problem is
encountered is the design of entertainment facility data model. The
existing model defines a list of facilities. Each with identity leaf
and list of visitors. The authors task is to design a model for a
casino and a zoo. For the casino he only needs to define the
identity and a constraint for the visitors to be adults older then
18. For the zoo except the identity definition he has to define a
constraint that allows only children with adult supervision to be
included in the visitors list.
1.3. Solution
This document defines a YANG extension of the augment statement -
ietf-direct-must-augment-extension:augment. The extension accepts
must as sub-statement. The extension enables model authors to
specify must statements with context nodes in existing models.
The extension is completely backward-compatible with the current
definitions in [RFC6020]. An old YANG parser will ignore any must
statements introduced by ietf-direct-must-augment-extension:augment
No existing models are affected by the new extension, so its
introduction will be transparent to the existing YANG parsers.
Vassilev Expires December 14, 2015 [Page 4]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
2. Using Direct Must Augment Extension
A YANG extension statement "ietf-direct-must-augment-
extension:augment" is introduced in the YANG module in Section 3.
Its intended use is to allow must as sub-statement which is not
possible with the augment statement defined in [RFC6020]. For
example:
module entertainment-facilities-casino {
...
identity casino {
base ef:entertainment-facility-generic;
}
direct-must-augment-ex:augment
"/ef:entertainment-facilities/ef:entertainment-facility" +
"ef:visitor" {
when "../ef:type='ef-casino:casino'";
must "(/people/person[name=current()]/age>=18)" {
error-message
"Only adults are allowed in a casino.";
}
}
}
Vassilev Expires December 14, 2015 [Page 5]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
3. Direct Must Augment Extension Module
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file
"ietf-direct-must-augment-extension@2015-06-12.yang"
module ietf-direct-must-augment-extension {
namespace
"urn:ietf:params:xml:ns:yang:ietf-direct-must-augment-extension";
prefix "direct-must-augment-ex";
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Editor: Vladimir Vassilev
<mailto:vladimir@transpacket.com>";
description
"This module contains extension of the standard augment statement.
Copyright (c) 2015 IETF Trust and the persons identified as
authors of the code. All rights reserved.
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).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision 2015-06-12 {
description
"Initial revision.";
Vassilev Expires December 14, 2015 [Page 6]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
reference
"RFC XXXX: Direct Must Augment Extension";
}
/*
* Extension
*/
extension augment {
argument target;
description
"This extension introduces a direct must augment statement
capable of augmenting existing data nodes with new must
sub-statements.";
}
}
<CODE ENDS>
Vassilev Expires December 14, 2015 [Page 7]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
4. IANA Considerations
4.1. DIRECT-MUST-AUGMENT-EX XML Namespace
This document registers a URI in the IETF XML registry [RFC3688].
Following the format in RFC 3688, the following registration is
requested:
URI: urn:ietf:params:xml:ns:yang:ietf-direct-must-augment-extension
Registrant Contact: The NETMOD WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
4.2. DIRECT-MUST-AUGMENT-EX YANG Module
This document registers 1 YANG module in the YANG Module Names
registry [RFC6020].
name: ietf-direct-must-augment-extension
namespace:
urn:ietf:params:xml:ns:yang:ietf-direct-must-augment-extension
prefix: direct-must-augment-ex
// RFC Ed. remove this line and replace XXXX in next line
reference: RFC XXXX
Vassilev Expires December 14, 2015 [Page 8]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
5. Security Considerations
This document does not introduce any new security concerns in
addition to those specified in [RFC6020], section 15.
Vassilev Expires December 14, 2015 [Page 9]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
6. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
[RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
July 2013.
[XSD] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
Vassilev Expires December 14, 2015 [Page 10]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
Appendix A. Example Data Models
A.1. Model of a Generic Entertainment Facility
The "entertainment-facilities" YANG module models a collection of
people and entertainment-facilities. Each person in the people
collection has a name and age. Each entertainment-facility has a
name, type and list of visitors referencing entries in the people
collection. This example model is the target module for direct must
augment extension statements defined in Appendix A.2 and
Appendix A.3.
module: entertainment-facilities
+--rw people
| +--rw person* [name]
| +--rw name string
| +--rw age uint32
+--rw entertainment-facilities
+--rw entertainment-facility* [name]
+--rw name string
+--rw type identityref
+--rw visitor* -> /people/person/name
module entertainment-facilities {
namespace "http://example.com/ns/entertainment-facilities";
prefix entertainment-facilities;
organization "Example, Inc.";
contact "support@example.com";
description
"Module used in DIRECT-MUST-AUGMENT-EX example.";
revision 2015-06-12 {
description "Initial version";
}
container people {
description
"Contains all people.";
list person {
key name;
leaf name {
type string;
}
Vassilev Expires December 14, 2015 [Page 11]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
leaf age {
type uint32;
mandatory true;
}
}
}
identity entertainment-facility-generic {
description
"Base identity from which specific" +
"entertainment facility types are derived.";
}
container entertainment-facilities {
description
"Container for all entertainment-facilities information.";
list entertainment-facility {
key name;
leaf name {
type string;
}
leaf type {
type identityref {
base entertainment-facility-generic;
}
mandatory true;
}
leaf-list visitor {
type leafref {
path "/people/person/name";
}
}
}
}
}
Vassilev Expires December 14, 2015 [Page 12]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
A.2. Model of a Casino
module entertainment-facilities-casino {
namespace "http://example.com/ns/entertainment-facilities-casino";
prefix ef-casino;
import ietf-direct-must-augment-extension
{ prefix direct-must-augment-ex; }
import entertainment-facilities { prefix ef; }
organization "Example, Inc.";
contact "support@example.com";
description
"Module used in DIRECT-MUST-AUGMENT-EX example. " +
"Defines entertainment facility of type casino where" +
"only adults are allowed.";
revision 2015-06-12 {
description "Initial version";
}
identity casino {
base ef:entertainment-facility-generic;
}
direct-must-augment-ex:augment
"/ef:entertainment-facilities/ef:entertainment-facility/" +
"ef:visitor" {
when "../ef:type='ef-casino:casino'";
must "(/people/person[name=current()]/age>=18)" {
error-message
"Only adults are allowed in a casino.";
}
}
}
A.3. Model of a Zoo
module: entertainment-facilities-zoo
augment /ef:entertainment-facilities/ef:entertainment-facility:
+--rw child-supervision* [child]
+--rw child -> ../../ef:visitor
+--rw adult -> ../../ef:visitor
module entertainment-facilities-zoo {
namespace "http://example.com/ns/entertainment-facilities-zoo";
prefix ef-zoo;
import ietf-direct-must-augment-extension
Vassilev Expires December 14, 2015 [Page 13]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
{ prefix direct-must-augment-ex; }
import entertainment-facilities { prefix ef; }
organization "Example, Inc.";
contact "support@example.com";
description
"Module used in DIRECT-MUST-AUGMENT-EX example. " +
"Defines entertainment facility of type zoo where" +
"no children without adult supervision are allowed.";
revision 2015-06-12 {
description "Initial version";
}
identity zoo {
base ef:entertainment-facility-generic;
}
augment
"/ef:entertainment-facilities/ef:entertainment-facility" {
when "ef:type='ef-zoo:zoo'";
list child-supervision {
key child;
leaf child {
type leafref {
path "../../ef:visitor";
}
must "/people/person[name=current()]/age<=14" {
error-message
"People older then 14 are not children.";
}
}
leaf adult {
mandatory true;
type leafref {
path "../../ef:visitor";
}
must "/people/person[name=current()]/age>=18" {
error-message
"People younger then 18 are not adults.";
}
}
}
}
direct-must-augment-ex:augment
"/ef:entertainment-facilities/ef:entertainment-facility/" +
"ef:visitor" {
when "../ef:type='ef-zoo:zoo'";
Vassilev Expires December 14, 2015 [Page 14]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
must "((../child-supervision[child=current()]) or
(/people/person[name=current()]/age>=14))" {
error-message
"Children without adult supervision are not allowed in a zoo.";
}
}
}
Vassilev Expires December 14, 2015 [Page 15]
Internet-Draft DIRECT-MUST-AUGMENT-EX June 2015
Author's Address
Vladimir Vassilev
Transpacket
Email: vladimir@transpacket.com
Vassilev Expires December 14, 2015 [Page 16]