Re: [netmod] Use XML namespaces in YANG document examples

[Carsten Bormann <[e-mail]>]

Let me try to restate in more general terms the technical side of what Tom said:

On 2022-02-12, at 13:54, tom petch <[e-mail]> wrote:
> 
> MUST be the same as the namespace prefix (i.e., 'nsfmi' in
>   the example) for urn:ietf:params:xml:ns:yang:ietf-i2nsf-nsf-
>   monitoring. 

This is confusing language.  I don’t know what “the namespace prefix for X” is.
(Of course, I know what xmlns attributes are; are these meant here?  Or the prefix declaration in the YANG that imports the module with this name?  Or the prefix declaration in the YANG of the module with this name?)

More importantly, this is a specific instance of an antipattern that needs to be stamped out:
Rephrasing requirements of a base normative reference (here: RFC 7950) in a derived specification.
This incurs a strong danger (which is NOT theoretical):

— the rephrasing may be inaccurate and thus create a fork of the actually intended general requirement of the base standard.
— the rephrasing may be misunderstood as a requirement specific to the derived standard, so implementers feel compelled to do something special for the derived standard, again creating a fork on the implementation side.

I would like to ask that we never ever do that, except possibly with a strong indication that the restatement is just a reminder rephrasing the normative requirements of the base document.  Such a restatement needs to be clearly labeled as an informational note and needs to reference the specific normative statement in the base document that it is an instance of.

More specifically, an RFC 2119 keyword is misplaced here — this is not a new normative requirement, just a factual statement about what that base standard already requires.

Grüße, Carsten