Subject: [YANG] import statement

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 13:07:13 +0200

Hi,

I have difficulties in understanding what happens when a module imports
another and the latter contains "real" data tree, not just groupings and
typedefs. For example:

module foo {
  namespace "urn:foo";
  prefix foo;
  container foo-cont {
    leaf foo-leaf {
      ...
    }
  }
}

module bar {
  namespace "urn:bar";
  prefix bar;
  import foo {
    prefix foo;
  }
  container bar-cont {
    leaf bar-leaf {
      ...
    }
  }
}  

Is now the data model expressed by bar affected in any way by the fact
that it imports foo?

Thanks, Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

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

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 3 May 2008 14:02:17 +0200

> another and the latter contains "real" data tree, not just groupings and

No. An import simply means that the names defined in the imported
module become known and accessible - there are no side-effects of
imports.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>
_______________________________________________
YANG mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/yang

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 16:00:37 +0200

> module become known and accessible - there are no side-effects of

Then the one and only way for utilizing the imported name "foo-cont" in
module bar is in 

  augment /foo:foo-cont {
    ...
  }

which results in placing (possibly augmented) copy of the "foo-cont"
container at the location of the augment statement. Or am I missing
something?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 3 May 2008 16:32:05 +0200

> container at the location of the augment statement. Or am I missing

You are missing something. ;-) Here is what the YANG ID says (section
7.15):

   The "augment" statement allows a module or submodule to add to the
   schema tree defined in another module or submodule.

And section 3:

   o  augment: Adds new nodes to a previously defined node.

And section 4.2.8:

   YANG allows a module to insert additional nodes into data models,
   including both the current module (and its submodules) or an external
   module.  This is useful e.g. for vendors to add vendor-specific
   parameters to standard data models in an interoperable way.

   The "augment" statement defines the location in the data model
   hierarchy where new nodes are inserted, and the "when" statement
   defines the conditions when the new nodes are valid.

There are also examples. An augment of foo-cont simply sticks nodes
into the foo-cont container; there is no new instantiation of
foo-cont.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sat, 03 May 2008 08:14:37 -0700

> into the foo-cont container; there is no new instantiation of

There is one somewhat non-intuitive aspect of augment,
which is demonstrated in the netconf.yang module. E.g:

   grouping RpcOperationSourceType {
       description "NETCONF 'source' Parameter contents.";

       uses CommonConfigSourceType;
       augment config-source {
         leaf url {
           description
             "URL pointing to config data. Only available
              if 'url' capability supported.";
           type ConfigURIType;
         }

         anyxml config {
           description "Inline configuration data";
         }
       }
    }

Implementation notes:

For local (i.e., same namespace) augments, you need to expand
any uses-stmts first, and then apply the augment-stmt.
It looks strange to augment stuff that isn't there (yet),
but that is the nature of grouping/uses.

There is also a 'ripple-effect' with groupings,
uses, and augment, because they can all be nested within
nodes, notifications, and rpcs, and there is no clause order
in YANG (so your code better not be sensitive to forward
references or the different ordering permutations that can occur).
Processing the tree correctly requires more than one pass, bottom to top.

> /js

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 17:31:03 +0200

> into the foo-cont container; there is no new instantiation of

Example on pages 82 and 83 contradicts what you are saying: the augment
statement in namespace http://example.com/schema/ds0 takes the schema
subtree defined by "container interfaces" in namespace
http://example.com/schema/interfaces, augments it and effectively places
the result at the spot of the augment statement in the
http://example.com/schema/ds0 namespace.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 3 May 2008 18:58:26 +0200

On Sat, May 03, 2008 at 05:31:03PM +0200, Ladislav Lhotka wrote:
> 
> Juergen Schoenwaelder p????e v So 03. 05. 2008 v 16:32 +0200:
> 

I don't see the contradiction.

     augment "/if:interfaces/if:ifEntry" {
         when "if:ifType='ds0'";
         leaf ds0ChannelNumber {
             type ChannelNumber;
         }
     }

This augment introduces a leaf ds0:ds0ChannelNumber that appears under
/if:interfaces/if:ifEntry and this is what the example shows. There
is no new instantiation of /if:interfaces/if:ifEntry.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sat, 03 May 2008 10:13:34 -0700

> http://example.com/schema/ds0 namespace.

It's a bit tricky.
Augment puts nodes from the augmenting namespace and
puts it 'someplace else', which could be the same namespace.

The uses-stmt takes nodes from 'somewhere else' and puts them 'here',
in the namespace for 'here'.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 20:03:39 +0200

> is no new instantiation of /if:interfaces/if:ifEntry.

Assume a device that supports the data model as in the XML snippet on
page 83. Which of the two namespace URIs will it advertise in the hello
message? I assume it is http://example.com/schema/ds0. Where is the
<interfaces> block then instantiated if the import statement just makes
the identifiers from http://example.com/schema/interfaces accessible and
the augment statement doesn't do it?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 20:44:41 +0200

> in the namespace for 'here'.

That's all right, but I still think one can imagine the augment
statement to be replaced by the content of its target node (augmented as
specified) and said content keeps its original namespace. If it is not
so, then I am seriously confused and don't really know why augment can
appear in different places in the schema tree (under module, container
and list).

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 03 May 2008 20:57:08 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> message? 

Both.  "augment" extends another data model.  Thus if the device
supports the extension, it must also support the thing to extend!

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 03 May 2008 21:10:49 +0200 (CEST)

> appear in different places in the schema tree (under module, container

"augment" just extends some other data model, identified by the target
node.  This target node expression can be absolute or relative
(descendant form).  When augment appears under container or list, the
descendant form must be used.  It will extend the current data model
in the same module.  The use case is this:

   module foo {
     grouping bar {
       container baz { ... }
     }
   }

   module x { 
     container y {
       uses foo:bar;      // adds nodes from the bar grouping into my module
       augment baz {      // augment the new nodes with stuff
         ...
       }
     }
   }

In this example the relative augment could be replaced by a slightly
more verbose top-level augment, but in the following case it's not as
easy:

   module z {
     grouping zz {
       uses foo:bar;
       augment baz {
         ...
       }
     }
   }

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 03 May 2008 13:09:29 -0700

> page 83. Which of the two namespace URIs will it advertise in the hello

Both namespaces.
Maybe it is easier to visualize in XML (NETCONF edit-config PDU):

<rpc message-id="101"
   xmlns="netconf-base-URI"
   xmlns:nc="netconf-base-URI"
   xmlns:if="IF-MIB-URI"
   xmlns:ds0="DS0-MIB-URI">
  <edit-config>
   <target><running/></target>
   <default-operation>none</default-operation>
   <test-option>test-then-set</test-option>
   <error-option>rollback-on-error</error-option>
   <config>
     <if:interfaces>
       <if:ifEntry>
         <if:ifIndex>17</if:ifIndex>
         <ds0:ds0ChannelNumber nc:operation="replace">
           1
         </ds0:ds0ChannelNumber>
       </if:ifEntry>
     </if:interfaces>
   </config>
  </edit-config>
</rpc>

I assume it is http://example.com/schema/ds0. Where is the

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 22:12:43 +0200

> in the same module.  The use case is this:

Then augment performs two fundamentally different things - it is not
very clear from sect. 7.15. With the descendant form, it would be IMO
better to pack the augment statement with the uses statement where the
augmented node appears, like this:

   module x { 
     container y {
       uses foo:bar {
       	 augment baz {
         ...
         }
       }
     }
   }

With the absolute form, can the target node be e.g., a container inside
a grouping?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Sat, 03 May 2008 13:24:36 -0700

> augmented node appears, like this:

Not sure if this has any semantic impact.
In my code, it doesn't really make any difference
if 'augment baz' was inside the 'uses foo:bar' or not.
It would be extra work to make sure it was one way or the other.

I think of the uses-stmt as containing the refinements
for the grouping.  I suppose it makes sense to have it
contain both the refinements and extensions.

> With the absolute form, can the target node be e.g., a container inside

no.  you cannot augment a grouping (from outside the grouping).

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 03 May 2008 22:24:59 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> Then augment performs two fundamentally different things

I don't agree.  Why?

> With the absolute form, can the target node be e.g., a container inside

Currently you cannot augment a grouping.  This is something we have
been talking about though.  We should probably discuss this in a
separate thread on the netmod list.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 23:10:48 +0200

> > Then augment performs two fundamentally different things  

With the absolute argument, augment inserts something carrying its own
namespace in between foreign namespace nodes. In particular, no name
conflicts can ever happen.

With uses and the descendant form of augment, you are first adopting
something to your namespace and then modifying it. Names can clash here.
For example, the author of the imported module may add an optional node
to a grouping that from his point of view is perfectly backward
compatible change. This may however break the importing module if a node
added by augment happens to have the same name and is added at the same
place.

The syntax

  uses foo:bar {
    augment baz {
     ...
    }
  }
  uses boo:hoo;

has at least the advantage that it doesn't matter if boo:hoo uses baz.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Ladislav Lhotka <[email-masked]>
Date: Sat, 03 May 2008 23:21:14 +0200

> has at least the advantage that it doesn't matter if boo:hoo uses baz.

Sorry, of course it does matter. So this syntax really doesn't help. 

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 03 May 2008 23:21:24 +0200 (CEST)

> added by augment happens to have the same name and is added at the same

This is more an effect of how uses work than how augment works.
Consider this case:

   uses foo:bar;
   uses goo:baz;

If foo:bar contains container 'a' and goo:baz container 'b',
everything is fine.  Now, if foo is updated and a container 'b' is
added to the bar grouping, there will be a name collision in my
module.

There are several solutions to this problem.  One is to use the
versioned imports we talk about in some other thread.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sat, 03 May 2008 14:24:13 -0700

> has at least the advantage that it doesn't matter if boo:hoo uses baz.

no -

If grouping 'boo:hoo' has a top-level node named 'baz' in it,
it will clash no matter where these clauses are placed.

Remember that a 'uses-stmt' does not add any containment,
and neither does the grouping being referenced.
Choices and cases do not add any containment.

All the child nodes of these constructs can clash, and the
compiler needs to generate a fatal error if that happens.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Sun, 04 May 2008 09:05:06 +0200

> This is more an effect of how uses work than how augment works.

Yes and no - in this case augment makes very little sense without the
corresponding use statement. Effectively, the semantics of the two cases
are:

1. Reuse a foreign grouping in the local module, with optional 
   modifications.

2. Modify a schema tree (non-grouping) node in the foreign model.

Is it right that with 1 the device normally wouldn't advertise the
imported URI along with the local URI in hello? In case 2 it has to
since the absolute form of augment has otherwise no effect.

RELAX NG has an extension construct that is almost identical to 1, but
no equivalent for 2.

> added to the bar grouping, there will be a name collision in my

True, but here the collision can only occur at the top level of both
groupings, which is not very likely and easy to spot,  whereas augment
can descend to any depth of the grouping hierarchy and cause the
conflict there.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Sun, 4 May 2008 12:42:47 +0200

Can we please start using [email-masked] when initiating new threads?
This list ([email-masked]) will stay open for a few more days to make
sure that all existing threads were exhausted and will be shut down soon
after. 

Thanks and Regards,

Dan

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On 
> Behalf Of Ladislav Lhotka
> Sent: Saturday, May 03, 2008 2:07 PM
> To: yang
> Subject: [YANG] import statement
> 
> Hi,
> 
> I have difficulties in understanding what happens when a 
> module imports another and the latter contains "real" data 
> tree, not just groupings and typedefs. For example:
> 
> module foo {
>   namespace "urn:foo";
>   prefix foo;
>   container foo-cont {
>     leaf foo-leaf {
>       ...
>     }
>   }
> }
> 
> module bar {
>   namespace "urn:bar";
>   prefix bar;
>   import foo {
>     prefix foo;
>   }
>   container bar-cont {
>     leaf bar-leaf {
>       ...
>     }
>   }
> }  
> 
> Is now the data model expressed by bar affected in any way by 
> the fact that it imports foo?
> 
> Thanks, Lada
> 
> --
> Ladislav Lhotka, CESNET
> PGP Key ID: E74E8C0C
>

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 04 May 2008 14:51:09 +0200 (CEST)

Ladislav Lhotka <[email-masked]> wrote:
> imported URI along with the local URI in hello?

Yes.

> In case 2 it has to

Yes.

/martin

---

From: "David Harrington" <[email-masked]>
Date: Mon, 5 May 2008 15:15:04 -0400

Hi,

Can we please move all discussion of YANG to the netmod ML, so the
whole community can see these discussions and understand the issues?
It would also be easier to follow all the threads related to such
discussions, compared to having to correlate different threads on
different mailing lists.

Thanks,
dbh 

> Sent: Saturday, May 03, 2008 7:07 AM
> To: yang
> module imports

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 05 May 2008 21:22:57 +0200

Hi Dave,

I consider that thread finished - should I send a summary to the netmod
list?

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C