Subject: [netmod] review of yang 02

From: Leif Johansson <[email-masked]>
Date: Fri, 21 Nov 2008 17:09:56 +0100

I have reviewed yang-02 focusing on the specification, not the language. 

My observations below may seem not communicate the fact that I am 
quite impressed with how far the yang community has come in such a
relatively short time.  The document shows definite signs of having 
revised too many times and I think at this point a rewrite should be
considered. I'll get back to why/how later on.

The major "beef" I have with the text is that there is too much mix-up 
between introductory and normative language. There are several layers
of introductory text and I have to go to section 7 for the real normative
text. Often the introduction is just a rewording of the specification that
comes later in the document making it a redundant addition to the 
document.

The text needs a revision of all RFC 2119 terms - There are several 
examples where I suspect the normative upper-case version of a word 
is actually implied.

Another major problem is that there are several examples of undefined
terms. For instance "node", "cardinality" and "root node". The problem
defining a language (especially if you are trying to avoid being just another
object oriented language where you can rely on common understanding
of certain concepts) is that you have to be _extremely_ careful to keep the
number of fundamental terms (stuff you don't define) as small as possible.

There are some hints in the document that there may be a runtime/
compiletime model for yang but that is never spelled out.

In fact this is part of a larger problem which also need work: There is 
no discussion of the underlying conceptual model of yang; i.e where 
does yang fit in among netconf clients and servers, managed entities,
management data, management agents, management data models etc. 

There is some introductory text around trees and such but for an outsider 
it isn't clear what relationships trees bear to anything netconf cares about.

My suggestion is that the yang core document be divided into a clean
minimal specification document where extreme care is taken not to 
duplicate text and a separate information document which explains how
to read the specification, the underlying assumptions, basic terminology,
runtime/compiletime models and advise for implementers.

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

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 21 Nov 2008 14:11:59 -0600 (CST)

Hi Leif,

Thanks for your comments!

> comes later in the document making it a redundant addition to the 

In fact, it's just section 4, YANG Overview, that is introductory.
We will add some text to try to communicate the intention better.

> examples where I suspect the normative upper-case version of a word 

Agreed.  We will go through occurences of these terms for the next
revision.

> terms. For instance "node", "cardinality" and "root node".

Ok.  If anyone has a proposal for definitions of the terms 'node',
'tree', etc, please let me know.

> compiletime model for yang but that is never spelled out.

If you refer to things like 'must' and 'when' constraints etc, we are
adding text that describes when and how the different constraints are
enforced.

> management data, management agents, management data models etc. 

This disussion is done in the NETMOD architecure document (which is
not yet published as a WG document).

> it isn't clear what relationships trees bear to anything netconf cares about.

Currently we say:

  YANG models the hierarchical organization of data as a tree in which
  each node has a name, and either a value or a set of child nodes.

Do we need more text?

> runtime/compiletime models and advise for implementers.

Ok.  We have also heard from other readers of the spec that they like
the introductory text, and they like having the examples in the text.

/martin

---

From: Leif Johansson <[email-masked]>
Date: Fri, 21 Nov 2008 21:30:45 +0100

On Friday 21 November 2008 21:11:59 Martin Bjorklund wrote:
> > text. Often the introduction is just a rewording of the specification
> > that comes later in the document making it a redundant addition to the
> > document.
>

They need definitions in the context of the yang/netconf/netmod !

> adding text that describes when and how the different constraints are

I don't understand that statement.

> not yet published as a WG document).

Good.

>   each node has a name, and either a value or a set of child nodes.

I should say so. That is a definition of a tree which I think we all share. 
What I'm missing is what the role of trees is in netconf and netmod and
in the models that underlie these protocols. Maybe this is the architecture
document again ...

> the introductory text, and they like having the examples in the text.

Right but i think the text needs to clearly separate introduction from 
specification.

	Cheers Leif

---

From: Andy Bierman <[email-masked]>
Date: Fri, 21 Nov 2008 21:05:42 -0800

> 'tree', etc, please let me know.

Add to list: complete mapping of XPath concepts to YANG database.

We must always distinguish schema nodes from database nodes
and PDU nodes. E.g., choice and case are schema nodes
that have names and take up a layer in the augment or refine target,
but they do not exist in the config database or PDUs.
Augment and uses nodes do not have names and do not show up
anywhere (in XPath).

The 'document root node' (/) for database XPath evaluation is
mapped to the conceptual <config> container. Lists and containers
generate complex content elements. Leaf and leaf-list nodes
generate simple content elements.  There are no comment,
processing-instruction, or attribute nodes in a YANG database.

>   each node has a name, and either a value or a set of child nodes.

How about changing 'name' to 'QName' and borrowing the
definition from XPath?

Is there text in the draft that says all NETCONF (or is it just YANG?)
content MUST use XML namespaces?   And the NULL namespace MUST NOT
be used (i.e., namespace ""; in a YANG file not allowed)?
Is this a NETCONF 1.1 issue?

> the introductory text, and they like having the examples in the text.

I agree.
IMO, learning XSD was harder because the details were spread out
in 3 specs instead of 1.  I prefer 1 YANG RFC.

> /martin

Andy