Subject: Re: [netmod] yang usage: temporary URI issue

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 1 Aug 2009 23:54:30 +0200

On Fri, Jul 31, 2009 at 12:34:35AM +0200, Andy Bierman wrote:
 
> Uh-oh, another detail:  Should 'yang' really be 'netmod'?  IMO, yes.
> The naming authority is the NETMOD WG, not the YANG language.

Its called yang because the module is yang. The naming authority is
the IETF.
 
>     namespace urn:ietf:params:xml:ns:netmod:DRAFT:foo-03
>     namespace urn:ietf:params:xml:ns:netmod:DRAFT:foo-04
>     namespace urn:ietf:params:xml:ns:netmod:DRAFT:bar-00
> 
> So what is a real YANG module URN supposed to look like?
> 
>     namespace urn:ietf:params:xml:ns:netmod:RFC5991:foo
>     namespace urn:ietf:params:xml:ns:netmod:RFC6210:foo
>     namespace urn:ietf:params:xml:ns:netmod:RFC5991:bar

No.

> Where is this registry and template defined?

In the YANG language definition.

/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/>

---

From: Andy Bierman <[email-masked]>
Date: Sun, 02 Aug 2009 10:24:01 -0700

> Its called yang because the module is yang. The naming authority is

OK -- but it is confusing that this is set to the WG name
in every other usage.

Here are the data model namespaces we have in RFCs already:

   urn:ietf:params:xml:ns:netconf:base:1.0
   urn:ietf:params:xml:ns:netconf:notification:1.0
   urn:ietf:params:xml:ns:netmod:notification

Here are the temporary namespaces that have been used so far in I-Ds:

   urn:ietf:params:xml:ns:netconf:partial-lock:1.0
   urn:ietf:params:xml:ns:netconf:state
   urn:ietf:params:xml:ns:netconf:with-defaults:1.0

Now you can see why I raised this issue.

So, what is the temporary URI format that should be used in
these drafts?

What about version numbers in the namespace?
We should not do that! We should use revision-date (or
version in XSD) to distinguish versions.

Both temporary and permanent namespace URIs should
use the revision date instead of the namespace.
Otherwise it is inconsistent, and we will be asking
every YANG author from now on to bother IANA every
time they update their I-D.

The module 'yang' seems wrong to me.
The namespace becomes the targetNamespace in XSD.
It is not YANG specific at all.  I think
it is NETCONF-specific, since all our YANG
modules are currently written for use with NETCONF.

Here is another attempt:

temporary URIs:

   urn:ietf:params:xml:ns:netconf:partial-lock:DRAFT
   urn:ietf:params:xml:ns:netconf:state:DRAFT
   urn:ietf:params:xml:ns:netconf:with-defaults:DRAFT

real URIs:

   urn:ietf:params:xml:ns:netconf:partial-lock
   urn:ietf:params:xml:ns:netconf:state
   urn:ietf:params:xml:ns:netconf:with-defaults

IANA just needs to drop the :DRAFT at RFC publication time.
Simple.  It works.  Can we move on?

> In the YANG language definition.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 2 Aug 2009 19:46:59 +0200

>    urn:ietf:params:xml:ns:netmod:notification

You confuse protocol capability URNs with data model namespaces. And I
agree that the 3rd one was a rather poor choice.
 
> So, what is the temporary URI format that should be used in

urn:ietf:params:xml:ns:yang:netconf-partial-lock:DRAFT-09
urn:ietf:params:xml:ns:yang:netconf-state:DRAFT-07

The with-defaults is again a capability URI, so it should follow the
other capability URIs in format:

> version in XSD) to distinguish versions.

The Version Number is the version of the Internet-Draft and will go
away once an RFC the official IANA assignment is being made.

> time they update their I-D.

The string in an ID is a placeholder until IANA does the final
assignment.

> The module 'yang' seems wrong to me.

It is a namespace assigned for use with the YANG data modeling
language. For me, WG names are pointless since they come and go.

> The namespace becomes the targetNamespace in XSD.

Yes.

> modules are currently written for use with NETCONF.

The data model are written in YANG and conform to the YANG
restrictions of NETCONF content and so I believe yang is correct.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sun, 02 Aug 2009 11:09:50 -0700

> urn:ietf:params:xml:ns:yang:netconf-state:DRAFT-07

So you want every YANG I-D author
to be forced to update the IANA registry
every time the I-D is updated?
Because if the version number is in the string,
that is what will be required.

The registry might get really big after only a few years.
IMO, it is better to get the IANA assignment at
the time of the -00 draft only.

There is no point in letting authors make up their
own namespace strings that look like IANA assignments.
(But that's what we've been doing.)

These are supposed to be globally unique strings that never get reused,
so a real registry entry is needed.  Either that, or
leave the field broken (like in SMIv2) in I-Ds.

Why is the revision-date good enough between RFC versions,
but not between draft versions?

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sun, 02 Aug 2009 11:35:15 -0700

....
> urn:ietf:params:xml:ns:netconf:with-defaults:1.0

The <with-defaults> element is defined in a targetNamespace
with the same value as the capability URI.

It is also incorrectly specified in the XSD in section 4.
The <with-defaults> parameter is a leaf, not an XML attribute.

IMO, the ":1.0" should be left out of the XML namespace.

> ....

OK

So, when the -00 I-D is published, the main part
of the URI is requested from IANA.  The :DRAFT-XX
is added by the author without any IANA involvement.

The 3 I-D namespace URIs should be:

    urn:ietf:params:xml:ns:yang:ietf-partial-lock:DRAFT-09
    urn:ietf:params:xml:ns:yang:ietf-netconf-state:DRAFT-07
    urn:ietf:params:xml:ns:yang:ietf-with-defaults:DRAFT-02

Not only are the versions wrong, the names are wrong too.

So the process almost works:

 1) publish draft -00; get IANA assignment
 2) publish DRAFT-nn versions
 3) publish the 1st RFC version
 4) publish RFC-bis draft -00 version
    oops: the DRAFT-00 URI was used already way back in step 1

Another issue: people who reference the IANA registry
do not know if an entry is published at RFC or DRAFT status,
or which RFC number or I-D name.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 2 Aug 2009 20:51:00 +0200

> the time of the -00 draft only.

Except you, I have not heard anyone suggesting this.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 2 Aug 2009 21:00:21 +0200

> is added by the author without any IANA involvement.

No. The IANA assignment is made after IESG approval with a
recommendation already in the ID with an added :DRAFT-xx to mark it
clearly as a non-official URI.
 
> Not only are the versions wrong, the names are wrong too.

I still can't find the YANG data model in
draft-ietf-netconf-with-defaults-02.txt. and the module name in
draft-ietf-netconf-partial-lock-09.txt is ietf-netconf-partial-lock;
so yes, your names are wrong.

>     oops: the DRAFT-00 URI was used already way back in step 1

I think this is not what was discussed in Stockholm.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sun, 02 Aug 2009 14:32:11 -0700

> clearly as a non-official URI.

Then I'm not clear on the value of the registry.
I would think it was important to choose unique URIs
from Day One.  I would think that any early implementations
using these URIs expect them to be unique.

So it is the author's responsibility to make sure nobody
ever starts working on module with the same name, during
the several years it may take to reach RFC publication?

> so yes, your names are wrong.

The module names for IETF modules are supposed
to start with "ietf-". The NETCONF WG already
agreed to this.  If the URI is supposed to
contain the module name, then it needs to match.

> I think this is not what was discussed in Stockholm.

How does one distinguish foo:DRAFT-00 done in one year
from another foo:DRAFT-00 several years later
when the WG is rechartered to update the original RFC?

I must have missed that part of the meeting.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 9 Aug 2009 23:03:06 +0200

> the several years it may take to reach RFC publication?

While name clashes are in principle possible, they are also pretty
unlikely to happen in practice.

> I must have missed that part of the meeting.

Good catch - we can use DRAFT-XXXXBIS-00 in that case, where XXXX is
the RFC number of the most recent published version of the module.

/js

---

From: Andy Bierman <[email-masked]>
Date: Sun, 09 Aug 2009 14:24:17 -0700

OK

just 1 more issue on this section, which is when the IANA
request is made.  It needs to be at the time of the -00 draft.
The foo.yang author has no way of knowing who else might
want to use foo.yang.  The only way to find out is to
search the published I-Ds, but by that time it is too late.

It is not the RFC Editor's responsibility to check for any
uniqueness except the draft name itself.  The 'thing' we use to
let the authors check on their own is an IANA registry.
Perhaps an on-line script will automate this function and
a simple database can be maintained somewhere in ietf.org
so the names and prefixes already in use can be viewed or searched.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 9 Aug 2009 23:48:21 +0200

> let the authors check on their own is an IANA registry.

I doubt that IANA assignments for -00 IDs is going to be practical nor
to I believe the likelyhood of name clashes is high enough to waste
lots of bandwidth on this.  And even if a clash happens, then all this
only becomes an issue when someone implements and ships the clashing
IDs implemented on the same server and I assume this someone will
detect the problem and take proper action.

Perhaps the YANG usage draft needs a sentence that iterates "You
should not ship YANG models that have not been formerly published. If
you want to implement early (which is encouraged), rename the model so
that it falls under your enterprises namespace."

/js

---

From: Andy Bierman <[email-masked]>
Date: Sun, 09 Aug 2009 15:49:35 -0700

> detect the problem and take proper action.

Sometimes I-Ds in progress last for several years.
Sometimes the RFC never gets published.
The purpose of the registry is to help early implementors
maintain unique names.

If unique names in I-Ds is not a concern, then
we should just tell WGs to put whatever they want,
but IANA may change it in the end.  If another WG wants
a module with the same name, the first WG better hurry up
and publish their RFC before the other WG.  We don't need a lot
of CLRs for something that does not matter.

There is no point in a registry for reserving unique identifiers
that have been in use for several years already.  The 'DRAFT'
string in the URI SHOULD be used, to indicate the assignment is not
from IANA.

> that it falls under your enterprises namespace."

no -- this does not help early implementors at all,
especially if an I-D reaches a 'stable-snapshot' state.
(We haven't had one of those around here for awhile ;-)

We should leave the namespace empty if we want vendors to change it.
Otherwise they won't.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Sun, 09 Aug 2009 16:01:08 -0700

> detect the problem and take proper action.

actually -- the module names are just as important wrt/ uniqueness
as the namespace URI -- maybe more because humans will start
remembering the module names.  The import-stmt expects the
module name to be unique.

But that is good -- if somebody sees a new I-D with ietf-foo.yang
in it, they will hopefully say something.  Otherwise, the module
name will get changed before RFC publication.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Mon, 10 Aug 2009 09:23:54 -0400

>the RFC number of the most recent published version of the module.

I thought (but may be wrong) that URN space was hierarchically
managed.   So putting "DRAFT" in the middle allows that whole
subhierarchy to be labeled as swamp water.  Putting it at the
end means the drafts are polluting someone else's domain.

Thanks,
 Phil

---

From: Phil Shafer <[email-masked]>
Date: Mon, 10 Aug 2009 09:32:19 -0400

>module name to be unique.

I don't think yang requires unique module names, since independent
parties may each decide to name their module "fred" or "cool" or
"cooler-still".  Yang suggests (SHOULD) but without a responsible
naming scheme, you can't depend on it.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Mon, 10 Aug 2009 08:34:50 -0700

> naming scheme, you can't depend on it.

I disagree.
This needs to be clarified in the YANG spec.

module A {
  ...
  import X { prefix x; revision 2009-01-01; }
  ...
}

module B {
  ...
  import X { prefix x; revision 2009-01-01; }
  ...
}

The same module X MUST be used, at least on the same agent.
The import-stmt and include-stmt do not have any way of
differentiating modules with the same name.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Mon, 10 Aug 2009 12:42:02 -0400

>This needs to be clarified in the YANG spec.

7.1. The module Statement
   ...
   Private module names are assigned by the organization owning the
   module without a central registry.  It is RECOMMENDED to choose
   module names that will have a low probability of colliding with
   standard or other enterprise modules and submodules, e.g., by using
   the enterprise or organization name as a prefix.

The namespace is the unique key, not the module name.  Module names
are like file names: try to be unique, use directories to keep them
separate.

Thanks,
 Phil

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 11 Aug 2009 17:07:36 +0200

> are like file names: try to be unique, use directories to keep them

Then the language is broken. For me, the XML namespace is used on the
wire to identify elements in instance documents while the module name
is used to refer to YANG modules. We now use prefixed module names
like ietf-yang-types and we RECOMMEND that other organizations also
properly prefix module names. Of course, there is no guarantee of
clashes but the probability should be small and in cases there is a
clash, you need to resolve it somehow at module compile time by some
renaming exercise. Since on the wire XML namespaces are used that we
designed to be name clash free (nobody stops a poor implementor of
course to screw things up), I think we are fine.

/js