Subject: [netmod] NonUnique leaf-list

From: Balazs Lengyel <[email-masked]>
Date: Wed, 5 Nov 2014 12:07:28 +0100

Hello,
As decided in one of the interim meetings here is my proposal for 
nonUnique leaf-lists in YANG 1.1.
I included a brief overview and the list of changes needed for the draft 
as well.
regards Balazs

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
Senior Specialist
ECN: 831 7320                        Tel: +36-1-437-7320
Mobile: +36-70-330-7909              email: [email-masked]

---

From: Ladislav Lhotka <[email-masked]>
Date: Wed, 05 Nov 2014 13:26:09 +0100

Hi Balazs,

a few questions and comments:

- I have doubts about the non-unique system-ordered case, especially
  because you also write that in this case "different leafs with the
  same value should be equivalent". So what's the point of having them
  there?

- How can addressing by value and by position be in conflict?

- Actually, I think the formulation "A leaf-list is a sequence of leaf
  nodes." is not correct. The term "(data) node" refers to the schema
  tree (see sec. 3), so a leaf-list is a data node but its entries
  aren't. It should be something like
  "A leaf-list is a sequence of scalar values of a particular type."

- Maybe it's time to move sections like 7.7.7 to the NETCONF spec. YANG
  should clearly define leaf-list semantics, and corresponding protocol
  issues should be dealt with in the protocol spec, be it NETCONF,
  RESTCONF or whatever.

- Would it make sense to do the same for lists, i.e. in terms of key
  uniqueness? It seems all non-unique leaf-list considerations are
  applicable to list keys as well.

Lada

Balazs Lengyel <[email-masked]> writes:

> Date: 2014-11-04
> rev 5
> Balazs Lengyel
> NonUnique leaf-list
> ########################################################################
>
> Summary:
> By introducing the unique-leaf-list true/false; statement it is allowed for leaf-lists to have multiple leafs with the same value. 
> The default behavior is that a leaf-list MUST have unique leafs which is fully compatible with the YANG 1.0.
>
> There are use cases for all four variants of a leaf-list 
> unique system-ordered: SCTP endpoint addresses
> unique user-ordered: list of authentication mechanism to use: radius, ldap, local
> non-unique system-ordered: unknown but it was indicated that some users need it
> non-unique user-ordered: list of AS-Paths, list of queueing weights in a scheduler 
>
> When a leaf in a leaf-list is addressed (by value as in YANG 1.0), if the value is present multiple times in the leaf-list, it is not trivial what is addressed, one specific leaf (which one?) or all the leafs with the specified value. For simplicity addressing by value will point at the first leaf with the specified value.
>
> To make handling the individual leafs easier addressing by position is also introduced for leaf-lists. Addressing by position is only allowed for user-ordered leaf-lists as the order in a system-ordered leaf-list might change. In unordered/system-ordered lists addressing by value is sufficient as the different leafs with the same value should be equivalent. 
> Any case when addressing by value and addressing by position conflicts is considered an error. 
>
> Some variants of the <edit-config> operation will have a changed behavior.
> - create will always succeed for a non-unique leaf-list even if the specified value already exists: in this case it does not mean recreating an existing value, it rather means creating one more leaf (instance) with the same value.
> - replace by position will allow changing the value at a specific position from x to y.
>
> Some restrictions are imposed on the allowed <edit-config> operations, as some variants can become too complicated both for humans to understand and implementers to implement, and there is no reasonable use case that needs them. (e.g. addressing some leafs by value and some by position in the same edit-config, creating, deleting, replacing and merging leafs with the same value in a single edit-config operation)
>
> ########################################################################
> Needed changes to the RFC:
>
> --- Change to chapter 3:
> leaf-list: Like the leaf node but defines a set of uniquely
>       identifiable nodes rather than a single node.  Each node has a
>       value but no child nodes.
>       
>       change to
>       
> leaf-list: Like the leaf node but defines a set of nodes rather 
>     than a single node.  Each node has a value but no child nodes.    
>     
> --- Change to chapter 4.2.2.2:
> A leaf-list is a sequence of leaf nodes with exactly one value of a
>    particular type per leaf.
>    
> What does this mean? Does it mean that leaf-lists need to have unique leafs?
> Change to:
>
> A leaf-list is a sequence of leaf nodes.
>
> --- Change to chapter 7.7
>     The values in a leaf-list MUST be unique.
> Change to:
>     The values in a leaf-list MAY be repeated or MUST be unique depending on the unique-leaf-list (see Section xxx). 
>     
>     
> --- Change to chapter 7.7.2
> Add:
>
> unique-leaf-list cardinality 0..1
>
> --- Add a level 3 chapter before 7.7.6
> 7.7.5b The unique-leaf-list Statement
> The "unique-leaf-list" statement takes as an argument the string "true" or
>    "false".  If "unique-leaf-list" is "true", values within the leaf-lists must be unique.
>    If "unique-leaf-list" is "false", values within the leaf-lists may be repeated. 
>    If "unique-leaf-list" is not specified, the default is true.
>
> --- Change chapter 7.7.7
> Change to:
>    Leaf-lists entries are handled as individual items by the <edit-config> 
>    operation. They can be created, deleted, and in some cases moved or 
>    replaced depending on the "operation", "insert", "value" and "position" 
>    attributes in the <edit-config> operation, and the "unique-leaf-list" 
>    statement.
>    
>    An individual leaf to be handled by the operation can be selected either 
>    based on its value or on it's position in the leaf-list.
>    When selected by value it is the first leaf with the specific value 
>    that will be handled, even if the value exists in the leaf-list multiple times. 
>    Selecting by position is only allowed in an "ordered-by user" leaf-list. 
>    Position must be between 1 and the length of the leaf-list, if it is not, it is an error. 
>    Selecting leafs within one specific leaf-list in one edit-config operation 
>    can be done either by value or by position, but using both selection 
>    by value and selection by position for the same leaf-list is an error.
>       
> ---Note:  Actualy I would allow selection by position for 
> system-ordered leaf-lists as well. Often the system 
> produces a well defined and stable order, so position is usable. We should not 
> explicitly forbid it, just state that as the order MIGHT not be stable or 
> predictable, results are implementation specific.   
>    
>    It is possible to handle multiple leafs with the same or different value in
>    the same <edit-config> request, the entries are handled one at the
>    time, in the order of the XML elements in the request. 
>       
>    In order to simplify handling, when an edit-config operation
>    - modifies a leaf-list with unique-leaf-list false and
>    - selection by value is used and
>    - the operation modifies multiple leafs from the leaf-list and
>    - multiple such leafs in the operation have the same value
>    the following rules apply:
>    - all leafs MUST have the same effective operation attribute, 
>    e.g. having create on some of them and merge on others is an error.
>    - the first leaf of a specific value will select the the first leaf 
>    with the same value in the datastore, the second leaf will select 
>    the second leaf from the datastore (if it exists) and so on. 
>    Which leafs are selected MUST be calculated before any 
>    modification to the leaf-list in the datastore.   
>    
> ---Note: We need the above special rule, to support the use cases of 
> simple additive merge and replacing many leafs.  Other extreme complicated 
> use cases are disallowed. 
>
>    When a NETCONF server processes an <edit-config> request, the
>    elements of procedure for a leaf-list node are:
>
>       If the operation is "remove", the entry is deleted from the leaf-
>       list if it exists.  
>    
>       If the operation is "delete", the entry is deleted from the leaf-
>       list if it exists. If the leaf-list entry does not exist, a
>       "data-missing" error is returned. 
>    
>       If the operation is "create", and the leaf-list is a unique-leaf-list 
>       and the entry does not yet exists, it is created as specified by the 
>       insert, value and position attributes. If the entry already exists 
>       an error is returned.
>       
>       If the operation is "create", and the leaf-list is not a unique-leaf-list 
>       the entry is created even if a leaf with the same value already exists. 
>       The create operation means adding one more leaf with the same value.
>                  
>       
>          In an "ordered-by user" leaf-list, the attributes "position", "insert" and
>          "value" in the YANG XML namespace (Section 5.3.1) can be used to
>          control where in the leaf-list the entry is inserted.  These can be
>          used during "create" operations to insert a new leaf-list entry, 
>          or during "merge" or "replace" operations to insert a new leaf-list
>          entry or to move or replace an existing one.
>       
>          The "insert" attribute can take the values "first", "last", "before",
>          and "after".  If the value is "before" or "after", exactly one of the "value" or the "position"
>          attributes MUST also be used to specify an existing entry in the leaf-
>          list. If the value is "first" or "last", neither the "position" nor the 
>          "value" attribute is allowed.
>          
>          If the "position" attribute is specified, but "insert" is not, "insert" 
>          defaults to the value "after".
>       
>          If no "insert" or "position" attributes are present in the "create", 
>          "replace" or "merge" operations, it defaults to "insert=last".                               
>          
>       If the operation is "replace" or "merge", and the position attribute is used 
>       replace the value specified by position. If both position and 
>       insert=after/before is specified, insert a new leaf with the value 
>       at the specified position. For unique-leaf-lists an operation MUST NOT result 
>       in two leafs with the same value.
>
>       If the operation is "replace" or "merge", and the position attribute is not used 
>       delete the first leaf with the specified value if it exist, and create 
>       it as specified by insert/value attributes. 
>       If the edit-config operation modifies multiple leafs with the same value, 
>       the special rules described above apply.
>              
>       In an <edit-config> with a "replace", or a a <copy-config> operation 
>       that covers the entire leaf-list, the leaf-list order is the same as
>       the order of the XML elements in the request.
>       
>             
> Usage example for position:
>
>
> <rpc message-id="101"
>           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
>           xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
>           xmlns:yang="urn:ietf:params:xml:ns:yang:1">
>        <edit-config>
>          <target>
>            <running/>
>          </target>
>          <config >
>            <top xmlns="http://example.com/schema/config">
>              <interface>
>                <name>Ethernet0/0</name>
>                <mtu>1500</mtu>
>                <address>
>                  <name>192.0.2.4</name>
>                  <prefix-length>24</prefix-length>
>                </address>
>                <alias nc:operation="create"
>                       yang:position="2"
>                       yang:insert="after">
>                </alias>
>              </interface>
>            </top>
>          </config>
>        </edit-config>
>      </rpc>
>      
>
> -- change 9.13
> TBD
>
> -- change 11.1
> Add:
> | unique-leaf-list | value | false |
>
> -- change 12
> TBD
> Add the unique-leaf-list statement
>
> -- change 13.1
> Modify so it applies to leaf-lists as well. 
> ---Note: This is an error correction, independent of the introduction of nonUnique leaf-lists
>
> -- change 13.8
> Modify to cover the position attribute
>
> -- change 13.x
> Add new chapters for the following errors
> - not allowed combinations of value, insert and position
> - position value out of range
> - mixed usage of selection by value and position for leaf-lists
> - mixed usage of the operation parameter for a nonUnique leaf-list when addressing by value
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C