Network Working Group                                       M. Bjorklund
Internet-Draft                                            Tail-f Systems
Intended status: Informational                          January 25,                         February 18, 2015
Expires: July 29, August 22, 2015

                      The YANG Conformance Problem
              draft-bjorklund-yang-conformance-problem-00
              draft-bjorklund-yang-conformance-problem-01

Abstract

   This document describes the YANG conformance problem.  It is intended
   as a temporary document to help the NETMOD WG in the design of YANG
   1.1.

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 July 29, August 22, 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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Axioms
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Axioms and Requirements . . . . . . . . . . . . . . . . . . .   3
   3.  Problems  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Problem P1 P1: Conformance Drift - background  . . . . . . .   4
     3.2.  Problem P1a: Conformance Drift with import-by revision  .   6
       3.2.1.  Solution P1a-01 . . . . . . . . .   4
     3.2.  Problem P1a . . . . . . . . . .   6
       3.2.2.  Solution P1a-02 . . . . . . . . . . . . .   5
       3.2.1. . . . . . .   6
     3.3.  Problem P1b: Conformance Drift without import-by revision   7
       3.3.1.  Solution P1a-01 P1b-01 . . . . . . . . . . . . . . . . . . .   5
       3.2.2.   7
       3.3.2.  Solution P1a-02 P1b-02 . . . . . . . . . . . . . . . . . . .   5
     3.3.   7
       3.3.3.  Solution P1b-03 . . . . . . . . . . . . . . . . . . .   7
     3.4.  Problem P1b P2: Conformance Ambiguity . . . . . . . . . . . .   8
       3.4.1.  Solution P2-01  . . . . . . . . . . .   6
       3.3.1. . . . . . . . .   8
       3.4.2.  Solution P1b-01 P2-02  . . . . . . . . . . . . . . . . . . .   6
       3.3.2.   9
       3.4.3.  Solution P1b-02 P2-03  . . . . . . . . . . . . . . . . . . .   7
     3.4.   9
     3.5.  Problem P2 - import-by revision everywhere P3: Deprecated and Obsolete Nodes . . . . . . .   7
       3.4.1. .   9
       3.5.1.  Solution P2-01 P3-01  . . . . . . . . . . . . . . . . . . .   8
       3.4.2.   9
     3.6.  Problem P4: Augmenting Obsolete Nodes . . . . . . . . . .   9
       3.6.1.  Solution P2-02 P4-01  . . . . . . . . . . . . . . . . . . .   8
       3.4.3.  Solution P2-03  10
     3.7.  Problem P5: Partial Import  . . . . . . . . . . . . . . .  10
       3.7.1.  Solution P5-01  . . . .   8
     3.5.  Problem P3 . . . . . . . . . . . . . . .  11
       3.7.2.  Solution P5-02  . . . . . . . .   8
     3.6. . . . . . . . . . . .  11
     3.8.  Problem P4 P6: Identityref Value Sets  . . . . . . . . . . .  11
       3.8.1.  Solution P6-01  . . . . . . . . . . . .   8
       3.6.1.  Solution P4-01 . . . . . . .  12
   4.  Solutions . . . . . . . . . . . . .   9
     3.7.  Problem P5 . . . . . . . . . . . . .  12
     4.1.  Solution S1 . . . . . . . . . .   9
       3.7.1. . . . . . . . . . . . . .  12
     4.2.  Solution P5-01 S2 . . . . . . . . . . . . . . . . . . .  10
       3.7.2. . . . .  12
     4.3.  Solution P5-02 S3 . . . . . . . . . . . . . . . . . . .  10 . . . .  12
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  10  13

1.  Introduction

   This document describes the YANG conformance problem.  It is intended
   as a temporary document to help the NETMOD WG in the design of YANG
   1.1.  It defines some terminology, lists some use cases to be used
   when evaluating solutions, and finally lists some (partial)
   solutions.

   Wikipedia defines "conformance" as "how well something, such as a
   product or system, meets a specified standard".

   There are two parts to the the conformance problem:

   o  The mechanisms available for the data model designer to define
      compliance levels, i.e., what parts of a data model are mandatory
      vs. optional to implement.  In YANG, there are two such
      mechanisms, modules and features.  For comparison, in SMIv2 this
      is done with the MODULE-COMPLIANCE macro.

   o  The mechanism by which an implementation specifies how well it
      conforms to the data model specification.  In YANG, a server
      claims conformance to a module it implements by advertising the
      module and the features it implements.  A server can also
      advertise how it deviates from the module specification by using
      the deviate statement.  For comparison, in SMIv2 this is done with
      the AGENT-CAPABILITIES macro.

   A related question is *how* a server advertises which modules and
   features it implements.  This is a separate problem, and is not
   further discussed here.

1.1.  Terminology

   The following terms are used within this document:

   o  Protocol Accessible Nodes: A data node, rpc or notification.

2.  Axioms and Requirements

   If a server advertises module A with some features, it means that it
   implements all data nodes, rpcs, and notifications defined in module
   A with these features.  It also means that it understands all
   identities defined in module A.

     Axiom A1: A server must implement all data nodes, rpcs, and
              notifications protocol accessible nodes
             (modulo supported features) in the module it
             advertises.  If the server doesn't implement RFC 5277, the
             notifications in a module do not have to be implemented.

   Note that the statement above doesn't say anything about typedefs and
   groupings - more on that later.

   If module A augments module B, A cannot be implemented without also
   implementing the augment's target node.  From A1 follows:

    Corollary C1: If a server advertises module A that augments a module
            B, it must also implement and advertise module B.

   And we have:

     Axiom A2: A server implements the protocol accessible nodes in one
             and only one specific revision of a module.

   Note that from

   From A2 only it does not follow and A1 is follows that a server cannot conform to and
   advertise multiple revisions of a module.  But this is
   not how YANG has been understood, thus  Thus we have:

     Axiom A3:

     Corollary C2: A server must not advertise more than
             one revision of a module.

   It is important that the client knows what to expect from a server:

    Axiom A4:

    Requirement R1: A client must be able to tell which data nodes, rpcs,
              and notifications protocol
            accessible nodes a server implements, including the types
            of all leafs and leaf-lists.

    Requirement R2: The solution must be maintainable and understandable
            by humans.

3.  Problems

3.1.  Problem P1 P1: Conformance Drift - background

   Consider the following situation:

     module mod-a {
       ...
       revision 2001-01-01;        // inital initial version
       typedef foo {
         type enumeration {
           enum q;
         }
       }
       grouping bar {
         leaf x { type string; }
       }
     }

     module mod-a {
       ...
       revision 2002-01-01;        // new version
       typedef foo {
         type enumeration {
           enum q;
           enum w;                 // enum added
         }
       }
       grouping bar {
         leaf x { type string; }
         leaf y { type string; }   // grouping extended
       }
     }
     module mod-b {
       ...
       import mod-a {
         prefix a;
         revision 2001-01-01;      // uses initial vsn of mod-a
       }
       leaf b {
         type a:foo;
       }
       container b2 {
         uses a:bar;
       }

     }

     module mod-c {
       ...
       import mod-a {
         prefix a;
         revision 2002-01-01;      // uses new vsn of mod-a
       }
       leaf c {
         type a:foo;
       }
       container c2 {
         uses a:bar;
       }
     }

     module mod-d {
       ...
       import mod-a                // uses unknown vsn of mod-a
         prefix a;
       }
       leaf d {
         type a:foo;
       }
       container d2 {
         uses a:bar;
       }
     }

   See also section 3.1 of draft-bierman-netmod-yang-conformance-04.

3.2.  Problem P1a P1a: Conformance Drift with import-by revision

   Suppose a server implements and advertises mod-b, mod-c and mod-d.

   What are the types of leafs b,c? (typedef drift)

   Which of /b2/y are and /c2/y are implemented? (grouping drift)

3.2.1.  Solution P1a-01

   Fix the type and grouping when using import-by revision.  In this
   case, it is clear what the types of leaf b and c are, and /b2/y is
   not supported, but /c2/y is.

3.2.2.  Solution P1a-02

   Do not use import-by revision (deprecate?), and make it illegal to
   extend the value space of a typedef, or add nodes to a grouping.  In
   this case, we would have:

     module mod-a {
       ...
       revision 2002-01-01;
       typedef foo {
         type enumeration {
           enum q;
         }
         // possibly status deprecated
       }
       typedef foo2 {
         type enumeration {
           enum q;
           enum w;
         }
       }
       grouping bar {
         leaf x { type string; }
         // possibly status deprecated
       }
       grouping bar2 {
         leaf x { type string; }
         leaf y { type string; }
       }
     }

   An advantage of this is that it allows all nodes that reference a
   typedef or grouping to receive bug fixes.  This works because the
   type or grouping is never fixed.

3.3.  Problem P1b P1b: Conformance Drift without import-by revision

   Suppose a server implements and advertises mod-b, mod-c and mod-d.

   What is the type if of leaf d? (typedef drift)

   Is /d2/y implemented? (grouping drift)

3.3.1.  Solution P1b-01

   Require the server to advertise mod-a, but mark the advertisement as
   being "no nodes implemented".

   This means that all modules that uses use a typedef or grouping without
   importing by revision will get the same version of the typedef.

3.3.2.  Solution P1b-02

   Require import-by revision everywhere.  See P6 P2 though.

3.3.3.  Solution P1b-03

   To protect against typedef drift, a mod-d can be revised when the new
   version of mod-a is gets published, and use the updated type with a
   restriction:

     module mod-d {
       ...
       import mod-a {
         prefix a;
       }
       leaf d {
         type a:foo {
           enum q; // explicitly add the original restriction
         }
       }
       container d2 {
         uses a:bar;
       }
     }

   This can be done even in the initial version of mod-d, in order to be
   future-proof.

   For groupings, no such mechanism exist.

3.4.  Problem P2 - import-by revision everywhere P2: Conformance Ambiguity

   Consider the following situation:

     module mod-e {
       ...
       revision 2001-01-01;           // initial version
       container x;
     }

     module mod-e {
       ...
       revision 2002-01-01;           // new version
       container x;
       container y;                   // added data node
     }

     module mod-f {
       ...
       revision 2001-04-01;
       import mod-a {
         prefix a;
         revision-date 2001-01-01;    // uses initial vsn of mod-e
       }
       augment /a:x { ... }
     }

     module mod-g {
       ...
       revision 2002-04-01;           // uses new vsn of mod-e
       import mod-e {
         prefix e;
         revision-date 2002-01-01;
       }
       augment /e:y { ... }
     }

   Suppose that a server wants to implement both mod-f and mod-g.  From
   C1, it follows that it also must implement and advertise mod-
   e@2001-01-01 and mod-e@2002-01-01.  But this contradicts axiom A3. A2.

   See also section 3.2.1 of draft-bierman-netmod-yang-conformance-04.

3.4.1.  Solution P2-01

   Do not allow import-by revision.

3.4.2.  Solution P2-02

   Relax A3. A2.  Let the server advertise both revisions of mod-e.

   This solution then has the same problem as described in P1b.

3.4.3.  Solution P2-03

   Relax the meaning of import-by revision, to mean "import by minimum
   revision".  Alternatively add a new statement with this meaning, and
   deprecate (?) import-by revision.

   This solution then has the same problem as described in P1b.

3.5.  Problem P3 P3: Deprecated and Obsolete Nodes

   A server may choose to not implement nodes with status "deprecated"
   or "obsolete".  However, there is no mechanism to advertise which
   such nodes are actually implemented on a server.

3.5.1.  Solution P3-01

   Tighten the rules for "deprecated" and "obsolete".  A "deprecated"
   node MUST be implemented, and an "obsolete" node MUST NOT be
   implemented.

3.6.  Problem P4 P4: Augmenting Obsolete Nodes

   Consider the following siutation: situation:

     module mod-h {
       ...
       revision 2001-01-01;
       ...
       container x { ... }
     }

     module mod-i {
       ...
       revision 2001-04-01;
       import mod-h {
         prefix h;
       }

       augment /h:x {
         container y { ... }
     }

   A server advertises mod-h@2001-01-01 and mod-i@2001-04-01.

   Now, mod-h is revised:

     module mod-h {
       ...
       revision 2004-01-01;
       ...
       container x {
         status deprecated;
       }
       container much-better-x { ... }
     }

   The server picks up the new revision of mod-h, and advertises mod-
   h@2004-01-01 and mod-i@2001-04-01.

   Next, mod-h is revised again:

     module mod-h {
       ...
       revision 2010-01-01;
       ...
       container x {
         status obsolete;
       }
       container much-better-x { ... }
     }

   The server picks up the new revision of mod-h, but it does not want
   to / cannot implement the obsolete container "x".  But this means it
   cannot implement mod-i faithfully.

3.6.1.  Solution P4-01

   This is the way it works.  mod-i should be revised, or the server
   will have to advertise a devation deviation to mod-i, where the augmented
   nodes are not implemented.

3.7.  Problem P5 P5: Partial Import

   Consider the following situation:

     module mod-system {
       ...
       container system {
         container users { ... }
         container logging { ... }
       }
     }

     module mod-dns {
       ...
       import mod-system {
         prefix sys;
       }

       augment /sys:system {
         container dns { ... }
       }
     }

   If a server wants to implement mod-dns, it follows from C1 that it
   must also implement all of mod-system (minus if-featured nodes), even
   though the only node that is really necessary is the NP-container non-presence-
   container "system".

3.7.1.  Solution P5-01

   Relax C1, so that a module does not have to be implemented (and thus
   not claimed conformance to) because of an augmentation.

   The problem with this solution is that it might work for NP-
   containers, non-
   presence-containers, but what if the target node lies with a list?

3.7.2.  Solution P5-02

   Do nothing.  This is an educational issue.  Make sure generic
   containers like this "system" do not require the implementation of
   many other nodes.

3.8.  Problem P6: Identityref Value Sets

   This problem is explained in section 3.2.3 of draft-bierman-netmod-
   yang-conformance-04.

   The problem and its solution is listed here for completeness.

3.8.1.  Solution P6-01

   Add a new rpc like "get-allowed-identities", defined in 6.2 of draft-
   bierman-netmod-yang-conformance-04.

4.  Solutions

   This section lists some solution proposals for P1 and P2.

4.1.  Solution S1

   Do not allow import-by revision (solves P2).

   Do not allow an updated typedef to get its value space expanded
   (solves P1, typedef drift).

   Do not allow an updated grouping to get additional nodes (solves P1,
   grouping drift).

   This is a simple, but pretty inflexible solution.

4.2.  Solution S2

   Do not allow import-by revision (solves P2).

   Allow an updated typedef to get its value space expanded, but
   describe the trade-offs and tell people to be careful.  In order to
   avoid typedef drift, use solution P1b-03.

   Allow an updated grouping to get additional nodes, but describe the
   trade-offs and tell people to be careful.  In order to avoid grouping
   drift, use a solution similar P1b-03.  This requires new statements
   to be added to YANG, something like "refine X not-implemented".

4.3.  Solution S3

   Do not allow import-by revision (solves P2).

   Allow an updated typedef to get its value space expanded, but
   describe the trade-offs and tell people to be careful.  All leafs of
   a certain type have exactly one implementation in a given server.  (A
   solution like P1b-03 can of course be used).

   Allow an updated grouping to get additional nodes, but describe the
   trade-offs and tell people to be careful.  All uses of a grouping
   have the same version of the grouping expanded.

Author's Address

   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com