Re: [yang-doctors] [IANA #1289473] Revision statements in IANA-maintained YANG modules

[Martin Björklund <[e-mail]>]

Hi,

Ladislav Lhotka <ladislav.lhotka=[e-mail]> wrote:
> Hi Amanda,
> 
> "Amanda Baber via RT" <[e-mail]> writes:
> 
> > Hi,
> >
> > We came across an issue when attempting to validate RFC 9403's
> > [e-mail] module before posting.
> >
> > That module refers to [e-mail], and pyang is
> > refusing to validate it on the grounds that
> > [e-mail] doesn't have references for its
> > revision statements. (Which it indeed does not.)
> >
> > However, if we try to validate [e-mail]
> > directly, we don't get any errors.
> >
> > Which pyang reaction is correct?

When I validate this module directly with pyang, I get the errors:

  $ pyang --ietf [e-mail]
  [e-mail]:35: error: RFC 8407: 4.8: statement "revision" must have a "reference" substatement
  ...


> 
> RFC 8407 states in sec. 4.8:
> 
>   The "revision" statement MUST have a "reference" substatement.
> 
> The module description refers to RFC 8294 though, and I am not sure
> how this particular module is updated and whether there is always a
> relevant reference available for a given revision.
> 
> >
> > One larger issue is that we weren't aware that we needed to add
> > references for revision statements in the IANA-maintained modules. We
> > have no expertise in YANG and have been relying entirely on validation
> > tools (and on IANA Considerations sections for registry maintenance
> > instructions in general).
> >
> > Should we go back and add references to revision statements for all
> > the IANA-maintained modules?
> 
> This could lead to problems with versioning of modules. 
> 
> >
> > Do we need to do so only going forward?
> 
> I'd suggest to add reference statements to future (substantial)
> revisions of modules, perhaps even retroactively, but only where it
> makes sense.
> 
> >
> > Either way, we have two questions:
> >
> > 1) Many of the registries mirrored by the IANA-maintained modules have
> > First Come First Served or Expert Review ranges that don't require
> > that the applicant provide a specification. For those registrations,
> > we list the name of a contact person in the registry's "Reference"
> > field. In the module, would we continue to omit the reference field?
> 
> If there is no suitable document to refer to, it makes no sense to me
> to add any stub references. RFC 8407 is IMO unnecesarily strict here,
> and a SHOULD might suffice.

The full text in RFC 8407 is:

   A "revision" statement MUST be present for each published version of
   the module.  The "revision" statement MUST have a "reference"
   substatement.  It MUST identify the published document that contains
   the module.

In this case, there really isn't any "published document" - the module
is published directly on the web.  One option could be to add the URL
to the module in "reference".  The motivation for the rule is:

   Modules are often extracted from their original
   documents, and it is useful for developers and operators to know how
   to find the original source document in a consistent manner.

So the URL would help for this.


Side note.  In the description of the module it says:

     This version of this YANG module is part of RFC 8294; see
     the RFC itself for full legal notices.";

This isn't true... Should IANA change the description of the module
when it updates the module?  Perhaps to:

     This original version of this YANG module is part of RFC 8294; see
     the RFC itself for full legal notices.";


/martin




> 
> >
> > 2) When we need to correct an IANA-maintained module, in the absence
> > of a document to refer to, what can we do to make the revision
> > statement valid?
> 
> I'd say yes.
> 
> Best regards, Lada
> 
> >
> > Best regards,
> >
> > Amanda Baber
> > IANA Operations Manager
> >
> > _______________________________________________
> > yang-doctors mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/yang-doctors
> 
> -- 
> Ladislav Lhotka, CZ.NIC
> PGP Key ID: 0xB8F92B08A9F76C67
> 
> _______________________________________________
> yang-doctors mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/yang-doctors