Subject: [netmod] comments on bierman-netmod-yang-usage-00

From: Martin Bjorklund <[email-masked]>
Date: Mon, 06 Apr 2009 23:03:52 +0200 (CEST)

Hi,

I have some comments on this document.

o  The Virtual Module concept is a bit unclear, but I believe it will
   be removed.

o  section 3.6:

   Should documents listed in 'reference' statements also be included
   in (at least) the non-normative reference section?

o  section 4.4, second bullet:

      Until a URI is assigned by the IANA, a temporary namespace string
      SHOULD be selected which is not likely to collide with other YANG
      namespaces, such as the filename of the Internet Draft containing
      the YAM.

  I guess there is a similar rule for assgnments under mib-2 for SMIv2
  modules, so maybe this rule should be followed.  But I just note
  that the current I-D YANG modules don't follow this, and I have not
  seen this being used in XSDs (targetNamespace) in I-Ds.

o  section 4.5:

     The description statement MUST be present.

   It is not clear which description statement you refer to.  Typedef?
   Leaf?

o  section 4.5:

      For string data types, if the length of the string is not
      unbounded in all implementations, then a length statement SHOULD
      be present.

  [I don't want to restart the discussion on unbounded strings here!]

  I think it is obvious that no implementation will support unbounded
  strings, so I think this rule should be rephrased.  My initial
  suggestion was to:
     s/is not unbounded/is not required to be unbounded/ 
  but I'm not sure if that is more clear or not.

o  section 4.6, last bullet.

  Similar to the previous comment.  I don't think max-elements should
  be used unless it makes sense for the data being modelled.  I.e. I
  think people should be careful not to add "arbitrary" limits...

o  section 4.6:

   Do we also want to say that if must/when expressions are present,
   then their meaning SHOULD be described in the description?

o  Maybe add a section on naming conventions?  We should list our rule
   that IETF modules use the prefix 'ietf-'.  Say that the prefix in
   IETF modules SHOULD be unique?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Fri, 10 Apr 2009 17:56:39 -0700

> o  The Virtual Module concept is a bit unclear, but I believe it will

yes it will be removed.
The idea was to prevent the republication of an
RPC just to an an 'include-stmt' for a new submodule.
But this will not work.  For many reasons, a statically
published RFC is needed every time a module is changed.

>    in (at least) the non-normative reference section?

hmmm...
usually only the imports are normative references.
I guess some text about the reference clause(s)
needs to be mentioned as well.

>   seen this being used in XSDs (targetNamespace) in I-Ds.

This is controversial.
The practice for MIBs is to intentionally publish I-D MIBs
so they do not compile.  Instead they crash with an invalid
module assignment OID.

IMO, this is really overboard.
Instead, a well-known formula (e.g., I-D draft name)
for a temporary namespace URI seems more useful.  In reality,
since this field is just a 'string', any value including ''
will be accepted by a tool, but using random strings in NETCONF
namespace URIs may cause problems, especially ''.

My formula works fine for NETCONF.
E.g., if the agent advertises 'draft-ietf-netconf-with-defaults-01'
as the namespace URI, then it is absolutely clear what is
in the implementation, and early interoperability testing
is not suppressed by IETF policy.

>    It is not clear which description statement you refer to.  Typedef?

typedef.  I will make it clear.

for object definitions, it is not as clear.
For example, a bits or enumeration object SHOULD
use individual description-stmt in the enum/bit
statements, so maybe the main description has nothing
to say.  Balazs also mentioned obvious, well-known
objects, like 'name' ("The name of the foo entry.")

Description clauses are meant to add additional
information beyond the most obvious.  Usually in a standard
data model, there is *something* that needs to be mentioned
about every object.

>   but I'm not sure if that is more clear or not.

OK - I will make this edit.
The reason many standard MIB objects have length limits,
even descriptive ones (SnmpAdminString is 0..255 octets (!))
is that every implementation MUST support this limit.
Unbounded mandatory-to-implement strings rarely get
approved by WGs.

>   think people should be careful not to add "arbitrary" limits...

I will say that min and max should be used when there are
design limits, not implementation limits, to consider.

>    then their meaning SHOULD be described in the description?

yes

>    IETF modules SHOULD be unique?

yes -- I was going to add a section on module naming.

I am hesitant to say anything about camelCase or anything
else style-related (SMIv2 forces people to look up the plural form
of every counter name they want to define).  I will
say that naming conventions SHOULD remain consistent
within the same module.

> /martin

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 14 Apr 2009 08:21:06 +0200 (CEST)

> namespace URIs may cause problems, especially ''.

The namespace value is not a string, it is a URI.  The <capability>
element in the XSD in 4741 is an xs:anyURI.

My tool gives an error if you don't have a prooper URI as namespace.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 14 Apr 2009 00:28:15 -0700

> My tool gives an error if you don't have a prooper URI as namespace.

So what value should we use for the IANA-assigned URI field
in I-Ds, obviously before IANA has assigned any value?

It would not be hard to invent a new schema, like 'temp-ns':

   temp-ns://draft-foo-bar-who-cares-00

Or just 'file':

    file://draft-foo-bar-who-cares-00.txt

That would be a proper URI and your tool will be happy again.

Andy