Subject: [netmod] Replacing a YANG submodule with a module

From: William Lupton <[email-masked]>
Date: Wed, 8 Jun 2016 12:27:41 +0100

Hi,

Consider the YANG module, submodule and tree files shown below. Suppose that I regret the decision to make “submod” be a submodule and want to replace it with a module (see listings further down). This works, the tree file is identical, and pyang --check-update-from is happy, but strictly the interface has changed (the util grouping has moved from the urn:bbf:yang:test namespace to the urn:bbf:yang:mod namespace). Is this intended to be valid (I don’t see it mentioned in RFC 6020bis Section 11)?

Thanks,
William

% cat [email-masked] [email-masked] [email-masked] 
module test {
  namespace "urn:bbf:yang:test";
  prefix test;

  include submod {
    revision-date 2016-01-01;
  }

  revision 2016-01-01 {
  }

  uses util;
}
submodule submod {
  belongs-to test {
    prefix test;
  }

  revision 2016-01-01 {
  }

  grouping util {
    container util {
    }
  }
}
module: test
   +--rw util

Replacements with submod -> mod:

% cat [email-masked] [email-masked] [email-masked] 
module test {
  namespace "urn:bbf:yang:test";
  prefix test;

  import mod {
    prefix mod;
    revision-date 2016-06-08;
  }

  revision 2016-06-08 {
  }

  uses mod:util;
}
module mod {
  namespace "urn:bbf:yang:mod";
  prefix mod;

  revision 2016-06-08 {
  }

  grouping util {
    container util {
    }
  }
}
module: test
   +--rw util

pyang is happy:

% pyang --check-update-from=[email-masked] [email-masked]

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 08 Jun 2016 13:37:11 +0200 (CEST)

William Lupton <[email-masked]> wrote:
> Hi,
> 
> Consider the YANG module, submodule and tree files shown
> below. Suppose that I regret the decision to make “submod” be a
> submodule and want to replace it with a module (see listings further
> down). This works, the tree file is identical, and pyang
> --check-update-from is happy, but strictly the interface has changed
> (the util grouping has moved from the urn:bbf:yang:test namespace to
> the urn:bbf:yang:mod namespace).

You have removed the "util" grouping from the module "test".  This is
not allowed according to the upgrade rules.

(So yes, this is a bug in pyang --check-update-from; it doesn't work
well with this kind of structural change)

/martin

> Is this intended to be valid (I don’t
> see it mentioned in RFC 6020bis Section 11)?
> 
> Thanks,
> William
>

---

From: William Lupton <[email-masked]>
Date: Wed, 8 Jun 2016 13:38:15 +0100

Thanks. So the following would be valid I assume? Or (better because it doesn’t change the module/submodule interface?) the second option shown below (which simply defines a new module in order to make the grouping externally accessible). Cheers, W.

% cat [email-masked] 
module test {
  namespace "urn:bbf:yang:test";
  prefix test;

  import mod {
    prefix mod;

  revision 2016-06-08 {
  }

  grouping util {
    uses mod:util;
  }

  uses util;
}

Second option:

% cat [email-masked] [email-masked] [email-masked] [email-masked] 
module test {
  namespace "urn:bbf:yang:test";
  prefix test;

  include submod {
    revision-date 2016-06-09;
  }

  revision 2016-06-09 {
  }

  uses util;
}
submodule submod {
  belongs-to test {
    prefix test;
  }

  import mod {
    prefix mod;
    revision-date 2016-06-09;
  }

  revision 2016-06-09 {
  }

  grouping util {
    uses mod:util;
  }
}
module mod {

  revision 2016-06-09 {
  }

  grouping util {
    container util {
    }
  }
}
module: test
   +--rw util

> On 8 Jun 2016, at 12:37, Martin Bjorklund <[email-masked]> wrote:
>

---

From: [email-masked] (Dale R. Worley)
Date: Wed, 08 Jun 2016 10:47:56 -0400

William Lupton <[email-masked]> writes:
> below. Suppose that I regret the decision to make "submod" be a
> the urn:bbf:yang:mod namespace). Is this intended to be valid (I don't

I'm not sure what a "tree file" is.  But it turns out that the XML for
data trees doesn't change.  The reason for that is that in the second
example, the util *grouping* is in the module mod, but the schema node
(which is the prototype of an XML element in a data tree) is in the
module test, where the uses statement is, and so the "util" XML element
will be in the XML namespace of module test.  See section 7.13:

   The identifiers defined in the grouping are not bound to a namespace
   until the contents of the grouping are added to the schema tree via a
   "uses" statement that does not appear inside a "grouping" statement,
   at which point they are bound to the namespace of the current module.

In regard to assigning schema nodes to an XML namespace, the uses acts
like a macro expansion, while in regard to resolving references to Yang
identifiers, uses/grouping is lexically scoped.

> not allowed according to the upgrade rules.

["upgrade" means "updating" and refers to section 11.]

If I understand Yang correctly, that error can't be fixed by revising
the new module test to clone mod:util as test:util, because though the
new grouping is semantically identical to the old grouping, it's still a
change in its definition:

 module test {

   import mod {
     prefix mod;

   revision 2016-06-08 {
   }

   uses mod:util;

+  grouping util {
+    uses mod:util;
+  }
 }

Dale

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 09 Jun 2016 09:42:59 +0200 (CEST)

[email-masked] (Dale R. Worley) wrote:
> I'm not sure what a "tree file" is.

Most IETF documents that define YANG modules contain a simplified
"tree" view of the data models they define, in order for the reader to
quickly get an overview of the model.  See e.g.,
https://tools.ietf.org/html/rfc7223#page-5.  Such tree diagrams can be
produced with tools like "pyang" (pyang -f tree ...).  (The tree
diagrams are also very useful when reviewing modules).

> But it turns out that the XML for

Hmm, why do you think that this isn't allowed?  If the syntax and
semantics are the same it should be allowed.  Section 11 has:

- Any set of data definition nodes may be replaced with another set of
  syntactically and semantically equivalent nodes.  For example, a set
  of leafs may be replaced by a uses of a grouping with the same
  leafs.

/martin

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: William Lupton <[email-masked]>
Date: Thu, 9 Jun 2016 10:18:38 +0100

Martin,

I think that the answer is “yes” but please could you just confirm that the alternatives presented here are valid? In the real world I think I would usually follow the second approach of retaining the submodule (including its groupings) but simply breaking out the definitions of the bodies of its groupings into groupings defined in new module(s).

Thanks,
William

> On 8 Jun 2016, at 13:38, William Lupton <[email-masked]> wrote:
> 
> % cat [email-masked] <mailto:[email-masked]> 
> module test {
> % cat [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> 
> module test {
>> On 8 Jun 2016, at 12:37, Martin Bjorklund <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> William Lupton <[email-masked] <mailto:[email-masked]>> wrote:
>>> Hi,
>>> 
>>> % cat [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> 
>>> module test {
>>> % cat [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> [email-masked] <mailto:[email-masked]> 
>>> module test {
>>> % pyang --check-update-from=[email-masked] <mailto:check-update-from=[email-masked]> [email-masked] <mailto:[email-masked]>
>

---

From: [email-masked] (Dale R. Worley)
Date: Thu, 09 Jun 2016 15:54:02 -0400

>   of leafs may be replaced by a uses of a grouping with the same

Ugh, that's my mistake.  I started skimming the list of criteria and saw
that they were all specific changes as to what was allowed and didn't
realize that the ones near the bottom were quite general.  In that case,
this version should be OK in that the grouping util is still defined by
module test:

 module test {

   import mod {
     prefix mod;

   revision 2016-06-08 {
   }

   uses mod:util;

+  grouping util {
+    uses mod:util;
+  }
 }

Dale