Subject: Re: [yang-doctors] RFC 2119 language in YANG models

From: Martin Bjorklund <[email-masked]>
Date: Fri, 01 Jul 2016 10:06:41 +0200 (CEST)

Mahesh Jethanandani <[email-masked]> wrote:
> As YANG modules are written in the context of a RFC standard, it is
> natural to see some of the RFC 2119 language in YANG models when
> citing some portion of the RFC to describe the attribute. But what
> does the language mean for the YANG model itself?
> 
> For example, if the standard says the default max-count value SHOULD
> be 32768, one can set the default value to 32768. But what happens if
> someone through deviation wants to set a different default value? Will
> that request be rejected? What happens if we s/SHOULD/MUST/?

If the standard says MUST use default max-count, it is pretty clear
that it is appropriate to use a "default" statement in the
corresponding YANG module.

If the statement says SHOULD use, maybe the YANG module shouldn't have
a default statement.  We can probably not have a clear rule anyway.

> Or how about this - This parameter MUST be generated
> pseudo-randomly. I do not know how to model this.

This is is fairly easy to model, but before theorizing, do you have a
concrete use case in mind?  I suspect that these exact words are not
very common for configuration parameters.

> My initial take is that one can try to model RFC 2119 language in
> YANG, but RFC 2119 language applies to implementation more than it
> applies to the YANG model itself. I certainly do not know how to model
> MAY or RECOMMEND or SHALL or SHALL NOT.

SHALL == MUST so that should be easy, right?

/martin

---

From: Jan Lindblad <[email-masked]>
Date: Fri, 1 Jul 2016 11:07:07 +0200

> As YANG modules are written in the context of a RFC standard, it is natural to see some of the RFC 2119 language in YANG models when citing some portion of the RFC to describe the attribute. But what does the language mean for the YANG model itself?
> 
> For example, if the standard says the default max-count value SHOULD be 32768, one can set the default value to 32768. But what happens if someone through deviation wants to set a different default value? Will that request be rejected? What happens if we s/SHOULD/MUST/?

The YANG modeler will have to make a call: inserting a default statement into the YANG effectively turns the SHOULD into a MUST. There may perhaps be situations where this is warranted, but the typical way to model this would probably be to have no YANG default stmt in the module, just keep the leaf optional and include the SHOULD passage in the description field for implementers to consider.

A side note may be that an RFC that uses SHOULD for a default value isn't promoting interoperability as much as it could.

Another related case is when an RFC says "the implementation SHOULD supply a configuration setting for xxx". I would say that translates to a leaf with an if-feature statement.

If the RFC test already says MUST, then things are easy. Just add default statements, leafs etc.

> Or how about this - This parameter MUST be generated pseudo-randomly. I do not know how to model this.

For config true elements, that would go in the description. For config false elements, I guess there's no need to include this in the YANG. The implementor would have to read the root (e.g. protocol) RFC to know what to implement. If the MUST passage is there, that should be enough.

> My initial take is that one can try to model RFC 2119 language in YANG, but RFC 2119 language applies to implementation more than it applies to the YANG model itself. I certainly do not know how to model MAY or RECOMMEND or SHALL or SHALL NOT.

As Martin noted, SHALL and SHALL NOT are probably easy (=MUST). MAY or RECOMMEND are harder, but in many cases if-feature might help.

/jan