Subject: [Netconf] RESTCONF #15: usage of groupings

From: Andy Bierman <[email-masked]>
Date: Tue, 9 Dec 2014 10:43:52 -0800

Hi,

A new issue has been added to the tracker:

https://github.com/netconf-wg/restconf/issues/15

There are 3 solutions mentioned.
The default solution is S1, which will be implemented
unless there is WG consensus demonstrated to
do something else.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Wed, 10 Dec 2014 14:40:23 -0500

I dislike S1, since it attempts to reuse a standard yang construct
in a way that is confusing and misleading.  My comment at the last
meeting was something like, wouldn't we be upset of some other
working group did something like this?  I sure would be.  It's
a bad precedent and we shouldn't be doing it.

S2 is acceptable.

Thanks,
 Phil

Andy Bierman writes:
>_______________________________________________
>Netconf mailing list
>[email-masked]
>https://www.ietf.org/mailman/listinfo/netconf

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 10:06:50 +0100

> unless there is WG consensus demonstrated to

The biggest problem with S1 is that it may mislead readers into
thinking: "Hey, now I understand how namespaces work in groupings!"

I also don't like the idea of defining an ad hoc extension. If we want
to turn YANG into a general schema language, it should be done properly.

I think the simplest solution would be to remove the groupings and have
"errors", "restconf", "collection" and "notification" as top-level
containers. The namespace assignment then follows YANG rules.

S3 should IMO be fine, too, the structures aren't that complicated. 

Lada

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

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Dec 2014 12:49:22 +0100 (CET)

Ladislav Lhotka <[email-masked]> wrote:
> I also don't like the idea of defining an ad hoc extension.

I disagree.  I think an extension is the best solution in this case.
However, we can use a different name than 'structure'.  'structure'
was originally my proposal for a built-in statement (YANG 1.1) for
this purpose.  We can call it 'restconf-structure' or 'restconf-data'
or something.

> If we want

This is also _very_ misleading, b/c then it looks like a normal config
or state module, which one would expect a server to implement in the
normal way.

> S3 should IMO be fine, too, the structures aren't that complicated. 

I can see only drawbacks compared to S2.  Whatever we do in text it
will be less precise than an extension.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 13:35:46 +0100

> On 11 Dec 2014, at 12:49, Martin Bjorklund <[email-masked]> wrote:
> 

So another document that wants to do the same should define its own ad hoc extension? Or import the ietf-restconf module?

> or state module, which one would expect a server to implement in the

What makes the solutions with groupings or extensions different? In any case, the module description has to state very clearly that it is a strawman module that’s not supposed to be used in the normal NETCONF/RESTCONF way. But if you above that deviate from YANG semantics, as the groupings do, you cannot even use standard YANG tools because they would produce wrong results.

If the module is as I proposed, I can still use pyang for generating correct DSDL schemas, XML-JSON mapping etc.

And if a server implementor likes the module and decides to implement it as if it was a normal module, so what? 

> will be less precise than an extension.

I prefer less precise to precise but wrong. Keep in mind that you are a YANG designer so you are not as likely to get confused by language anomalies as an average reader of the RESTCONF document.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Dec 2014 13:48:43 +0100 (CET)

Ladislav Lhotka <[email-masked]> wrote:
> So another document that wants to do the same should define its own ad
> hoc extension? Or import the ietf-restconf module?

Suppose we make a new document that defines a new RESTCONF resource
type, and we need a structure for it, then that document would import
and use 'restconf-structure'.

> What makes the solutions with groupings or extensions different?

I agree that groupings are misleading.  But using an extension would
be different, b/c the extension defines the semantics - this is not
config or oper state, but something else.

> In
> any case, the module description has to state very clearly that it is
> a strawman module that’s not supposed to be used in the normal
> NETCONF/RESTCONF way. But if you above that deviate from YANG
> semantics, as the groupings do, you cannot even use standard YANG
> tools because they would produce wrong results.
> 
> If the module is as I proposed, I can still use pyang for generating
> correct DSDL schemas, XML-JSON mapping etc.
> 
> And if a server implementor likes the module and decides to implement
> it as if it was a normal module, so what?
> 
> > 
> I prefer less precise to precise but wrong.

An extension is in no way wrong.

> Keep in mind that you are
> a YANG designer so you are not as likely to get confused by language
> anomalies as an average reader of the RESTCONF document.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 14:07:59 +0100

> On 11 Dec 2014, at 13:48, Martin Bjorklund <[email-masked]> wrote:
> 
> and use 'restconf-structure’.

I am talking about an author of an unrelated document who just wants to use YANG as a schema language.

> config or oper state, but something else.

If it is neither config nor state data, then a number of things such as XPath context are undefined. Is every list then required to have a key or not? This is a slippery slope, turning YANG into a schema language is not as easy as this.

> An extension is in no way wrong.

An extension that changes normal YANG semantics is wrong.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Dec 2014 14:11:45 +0100 (CET)

> to use YANG as a schema language.

They wouldn't use 'restconf-structure', but are free to define their
own extensions.

> If it is neither config nor state data, then a number of things such
> as XPath context are undefined.

Correct; this needs to be taken care of for each extension.

> Is every list then required to have a
> key or not? This is a slippery slope, turning YANG into a schema
> language is not as easy as this.
> 
> > 
> >> In

But this one doesn't change normal YANG semantics.

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 14:23:17 +0100

> On 11 Dec 2014, at 14:11, Martin Bjorklund <[email-masked]> wrote:
> 

It does, already because it defines neither config nor state data. What happens if

config false;

is used inside such an extension?

Lada

---

From: Andy Bierman <[email-masked]>
Date: Thu, 11 Dec 2014 06:52:53 -0800

> config or oper state, but something else.

I do not understand why these are special or misleading groupings.
I cannot find any text in any RFC that says a YANG module with
just groupings in it is invalid, improper, or even discouraged.

I am already using 1 of these groupings in a logging model.
Please explain why these are special groupings that cannot
be used in a normal data model in another module.

That is why I prefer solution S2-B

  rc:structure errors {
     uses errors;
  }

This assigns a module-name and a namespace and does not
preclude re-usage of the data within a larger data structure.

> An extension is in no way wrong.

agreed

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 16:07:19 +0100

> On 11 Dec 2014, at 15:52, Andy Bierman <[email-masked]> wrote:
> 

This is not the problem - what I consider seriously broken is the handling of the namespace. The description of the issue says:

    The namespace and module-name of the content are not identified in YANG.

However, in the draft the content happens to receive the namespace and module-name of the ietf-restconf module. There is no way how this can be achieved unless these groupings are used in that module.

Lada

---

From: Andy Bierman <[email-masked]>
Date: Thu, 11 Dec 2014 07:12:23 -0800

>     The namespace and module-name of the content are not identified in YANG.

That is not solution S2-B.
That is solution S-1, which Phil also rejected.

> However, in the draft the content happens to receive the namespace and module-name of the ietf-restconf module. There is no way how this can be achieved unless these groupings are used in that modu…

Solution S2-B would assign a module-name and namespace
as defined by the extension we add.  The extension, groupings
and extension usage would all be in ietf-restconf.yang.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Thu, 11 Dec 2014 16:35:31 +0100

> On 11 Dec 2014, at 16:12, Andy Bierman <[email-masked]> wrote:
> 

Such an extension changes the semantics of the built-in “grouping” statement. Let’s start designing YANG 2.0 as a general multi-encoding schema language, but please don’t do this. If it is only to be used in one or two modules, it is not worth the hassle and confusion.

Lada

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Dec 2014 16:42:03 +0100 (CET)

Ladislav Lhotka <[email-masked]> wrote:
> >> This is not the problem - what I consider seriously broken is the
> >> handling of the namespace. The description of the issue says:
> >> 
> >> However, in the draft the content happens to receive the namespace and
> >> module-name of the ietf-restconf module. There is no way how this can
> >> be achieved unless these groupings are used in that module.
> > 
> Such an extension changes the semantics of the built-in “grouping”
> statement.

No!  The grouping is just like any other grouping.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Thu, 11 Dec 2014 08:04:53 -0800

> No!  The grouping is just like any other grouping.

Yes -- in order to apply YANG constraints like must/when, the
context node has to be specified with a uses-stmt.
This has always been true for groupings.  The must/when
expressions need to be considered carefully, since YANG
does not constrain the context of the uses-stmt.

YANG constraints do not apply when used inside an extension
because the context is not any of the ones specified in the RFC.

Andy

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 15 Dec 2014 19:49:59 +0100

> preclude re-usage of the data within a larger data structure.

I don't want to block the resolution of this issue, so I propose that you
write a concrete definition of the extension, and I will then comment on
that.

Lada

---

From: Andy Bierman <[email-masked]>
Date: Mon, 22 Dec 2014 09:09:10 -0800

Hi,

I updated the issue tracker with the concrete proposal for
ietf-restconf groupings.

I forgot to mention that ietf-yang-patch.yang already uses the "errors" grouping
within the rpc output parameters, so removing it will break YANG Patch.

Andy