Subject: [yang-doctors] reference in import statement

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 15 Feb 2018 09:31:30 +0100

Hi,

I have just seen this pattern

   import ietf-inet-types {
     prefix "inet";
     reference "RFC 6991";
   }

and I wonder how people understand this. From the way this import
works, any (newer) version of ietf-inet-types is OK to use to resolve
the import but I could see that this statement makes people believe
they have to use the version of ietf-inet-types contained in RFC 6991
(but then this should have been import by revision). I know that we
had a common practice to have comments before this was possible, like

   import ietf-inet-types {             // RFC 6991
     prefix "inet";
   }

but then this was a comment, now the RFC numbers becomes part of the
definition. Should we be concerned about this? Or should we suggest
to be more clear about this, e.g.:

   import ietf-inet-types {
     prefix "inet";
     reference "RFC 6991 (at the time of this writing)";
   }

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 15 Feb 2018 09:40:02 +0100 (CET)

> they have to use the version of ietf-inet-types contained in RFC

I see what you mean, but suppose we didn't write the reference
statement.  In this case the RFC would still have a reference to RFC
6991, so that could also make people believe that the reference is
absolute.

I guess the problem is exposed more in the reference statement in the
YANG module though.

Maybe "reference" in "import" is actually a bad idea (except when used
with import-by-revision (which in itself is also bad idea)).

>      reference "RFC 6991 (at the time of this writing)";

  import ietf-inet-types {
    prefix inet;
    reference "RFC 6991: Common YANG Data Types
                 (at the time of this writing)";
  }

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 16 Feb 2018 16:56:06 +0100

> and I wonder how people understand this. From the way this import

I would say this tries to instruct the implementor that *at least*
the revision from RFC 6991 has to be used, perhaps because the new types
like "ip-address-no-zone" are used.

Using import by revision would mean that newer versions cannot be used
even though they are OK.

Lada

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

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Mahesh Jethanandani <[email-masked]>
Date: Tue, 20 Feb 2018 18:36:23 -0800

I agree that this is grounds for confusion. 

My preference would be that we NOT have a reference statement for import, or a comment for that matter, unless the module is doing import by revision. The text of the document is already required to have normative references to whatever the module imports.

Cheers.

> On Feb 15, 2018, at 12:31 AM, Juergen Schoenwaelder <[email-masked]> wrote:
> 
> Hi,
> 

Mahesh Jethanandani
[email-masked]

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 22 Feb 2018 08:53:23 +0100 (CET)

Hi,

Mahesh Jethanandani <[email-masked]> wrote:
> My preference would be that we NOT have a reference statement for
> import, or a comment for that matter, unless the module is doing
> import by revision. The text of the document is already required to
> have normative references to whatever the module imports.

I think this would be quite unfortunate, even though I agree that it
might be confusing to have the reference.  The problem with having
the reference only in the main body is that modules are typically
extracted from the RFCs and live their own life.  So all you have is a
list of various imported modules, and it is not obvious where to find
them.

We added the "reference" statement to "import" for this very reason in
YANG 1.1.

So maybe the best solution is the one suggested by Juergen initially:

Or maybe we declare that in fact this is not confusing (or at least it
is not a major issue) - people are aware of the fact that documents
evolve, and that there might be a more recent version available.

/martin

> 
> Cheers.
> 
> > On Feb 15, 2018, at 12:31 AM, Juergen Schoenwaelder
> > <[email-masked]> wrote:
> > 
> > Hi,
> >

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 22 Feb 2018 09:25:44 -0800

Hi Martin,

> On Feb 21, 2018, at 11:53 PM, Martin Bjorklund <[email-masked]> wrote:
> 
> Hi,
> 

Wasn’t the idea to not have the relationship between RFC number and a YANG model because of some of these very reasons, and move to IANA maintaining a copy of all version of the YANG models? If so, would it not make sense to refer to the IANA registry, rather than point to the RFC?

Mahesh Jethanandani
[email-masked]

---

From: Benoit Claise <[email-masked]>
Date: Thu, 22 Feb 2018 13:36:46 -0500

Dear all,

I think that keeping the reference is good thing. Btw, this is not 
specifically a reference to where the YANG module is, but mainly where 
the supporting document is.
I think that having the reference pointing to where the extracted YANG 
module is (read the IANA registry, as Mahesh suggested) misses the 
pointer to the supporting document.
I think that this problem is maybe not that confusing. Either people 
find the YANG module from the RFCs and they would see RFCbis links, or 
people find YANG module from a repo (IANA, yangcatalog.org, github) and 
they would directly discover the latest revision. So adding "(at the 
time of this writing)" doesn't hurt but doesn't add a lot of value. 
Actually, this is typically the type of rules that hurts if not done 
consistently. Ex: 90% of YANG modules contains "(at the time of this 
writing)", while the complementary 10% doesn't. What should I conclude 
for the 10%? Something special or simply an oversight?

Regards, Benoit (as a contributor)

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 22 Feb 2018 11:02:30 -0800

Benoit,

> On Feb 22, 2018, at 10:36 AM, Benoit Claise <[email-masked]> wrote:
> 
> Dear all,
> 
> I think that keeping the reference is good thing. Btw, this is not specifically a reference to where the YANG module is, but mainly where the supporting document is.
> I think that having the reference pointing to where the extracted YANG module is (read the IANA registry, as Mahesh suggested) misses the pointer to the supporting document.

I was thinking the registry would be of this format:

ID                                                  URI                                                             Filename                                          Reference

ietf-interfaces@2014-05-08               urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked]         RFC7223
ietf-interfaces@2018-02-22               urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked] <mailto:[email-masked]>         RFCXXXX

where the last column would be a hyperlink to the supporting document. No?

> I think that this problem is maybe not that confusing. Either people find the YANG module from the RFCs and they would see RFCbis links, or people find YANG module from a repo (IANA, yangcatalog.org, github) and they would directly discover the latest revision. So adding "(at the time of this writing)" doesn't hurt but doesn't add a lot of value. Actually, this is typically the type of rules that hurts if not done consistently. Ex: 90% of YANG modules contains "(at the time of this writing)", while the complementary 10% doesn't. What should I conclude for the 10%? Something special or simply an oversight?
> 

Mahesh Jethanandani
[email-masked]

---

From: Ebben Aries <[email-masked]>
Date: Thu, 22 Feb 2018 13:59:14 -0700

> where the last column would be a hyperlink to the supporting document. No?

I agree w/ Martin's comments below regarding modules being detached and
living their own life outside of the originating document.  With that
said each module will have its revision-date w/ a reference to its
supporting document.  Isn't this all you are describing in the above
registry example?

What we're talking about here is a reference on import w/o an import by
revision (Otherwise this reference should match up cleanly).  To a
module consumer, this can prove handy if they are just dealing w/ the
modules offline but this reference is detached from the possible
iterations that have come over separate supporting documents over time
thus creating this confusion of a potential soft relationship to a
specific revision.

If you aren't importing by revision then this really means the
dependency can be fulfilled by any revision you have accessible or
assume the latest.  These dependency modules will have their respective
references encoded within each so I'm not sure there is that much of a
need to have this encoded in each import statement tbh

If we leave out the reference, a consumer has to find another way to
resolve the dependency and find a module other than going to the
supporting document referenced (Which really shouldn't be the preferred
way in which folks resolve dependencies).  If we leave in the reference
and that dependency iterates over time, this can become out of date and
in need of update to all modules referencing said dependency even though
we are not importing by revision.

> >>>>> Fax:   +49 421 200 3103         <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=veqwbYHV1hLJdgQPus6LkKH-qWMRlJYVp3UMxeQ9_r0&e=>
> >>>>> 
> >>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=
> >>>> Mahesh Jethanandani
> >>>> [email-masked]
> >>>> 
> >>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=
> >>>> 
> >> Mahesh Jethanandani
> >> [email-masked]
> >> 
> >> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=
> > 
> 
> Mahesh Jethanandani
> [email-masked]
> 

> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 22 Feb 2018 23:04:15 -0800

Ebben,

> On Feb 22, 2018, at 12:59 PM, Ebben Aries <[email-masked]> wrote:
> 
>> ietf-interfaces@2018-02-22               urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked] <mailto:[email-masked]><mailto:[email-masked] <mailto:[email-masked]>>         RFCXXXX
>> 

I should have added one more line to the example above to demonstrate the point I was trying to make:

ietf-interfaces@2014-05-08               urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked]         RFC7223
ietf-interfaces@2018-02-22               urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked]         RFCXXXX (where XXXX is the RFC number that is assigned to rfc7223bis)
ietf-interface                                       urn:ietf:params:xml:ns:yang:ietf-interfaces      [email-masked]         RFCXXXX

The last entry, without a revision number, is entry for the latest version of the model and in this case will point to the latest ietf-interfaces model that is released as part of rfc7223bis.

The idea being that models importing ietf-interfaces without revision, have a reference to the last line in the IANA registry. And that line gets updated every time the ietf-interfaces model is updated. That way none of the models that import without revision need to be updated, because their reference would always be to the latest version of the model.

It solves the problem of consumers looking for references, and it also solves the problem of updating all module references when a dependent module is changed.

>>> I think that this problem is maybe not that confusing. Either people find the YANG module from the RFCs and they would see RFCbis links, or people find YANG module from a repo (IANA, yangcatalog.org <http://yangcatalog.org/>, github) and they would directly discover the latest revision. So adding "(at the time of this writing)" doesn't hurt but doesn't add a lot of value. Actually, this is typically the type of rules that hurts if not done consistently. Ex: 90% of YANG modules contains "(at the time of this writing)", while the complementary 10% doesn't. What should I conclude for the 10%? Something special or simply an oversight?
>>> 
>>>>> On Feb 21, 2018, at 11:53 PM, Martin Bjorklund <[email-masked] <mailto:[email-masked]>> wrote:
>>>>> 
>>>>> Hi,
>>>>> 
>>>>> Mahesh Jethanandani <[email-masked] <mailto:[email-masked]>> wrote:
>>>>>>> <[email-masked] <mailto:[email-masked]>> wrote:
>>>>>>> 
>>>>>>> Hi,
>>>>>>> 
>>>>>>> Fax:   +49 421 200 3103         <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=veqwbYHV1hLJdgQPus6LkKH-qWMRlJYVp3UMxeQ9_r0&e= <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=veqwbYHV1hLJdgQPus6LkKH-qWMRlJYVp3UMxeQ9_r0&e=>>
>>>>>>> 
>>>>>>> [email-masked] <mailto:[email-masked]>
>>>>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e= <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=>
>>>>>> Mahesh Jethanandani
>>>>>> [email-masked] <mailto:[email-masked]>
>>>>>> 
>>>>>> [email-masked] <mailto:[email-masked]>
>>>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e= <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=>
>>>>>> 
>>>> Mahesh Jethanandani
>>>> [email-masked] <mailto:[email-masked]>
>>>> 
>>>> [email-masked] <mailto:[email-masked]>
>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e= <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIFaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=>
>>> 
>> 
>> Mahesh Jethanandani
>> [email-masked] <mailto:[email-masked]>
>> 
> 
>> [email-masked] <mailto:[email-masked]>
>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e= <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=GIehbDpQlo31lSi6WbnEkA&m=TSpyWMoMJVbOm9RsA5dcAUNf05lE1Hp1OHroK2hNyg4&s=XLWOHjJF8xVeSkfUDdIhoY6xKJcem_73Vc0dVH5WsEw&e=>
Mahesh Jethanandani
[email-masked]