YANG Versioning

Introduction

The YANG data modeling language [RFC7950] and the associated protocols NETCONF [RFC6241] and RESTCONF [RFC8040] use a naming scheme that essentially consists of tuples of the form (module, path). The tuple (ietf-system, /system/contact) is an example uniquely identifying the leaf /system/contact in the YANG data tree of the module ietf-system. (The module may be identified by the module name or a module namespace but since there is 1:1 mapping between the two, the difference is not relevant for the discussion here and we simply use the module name.)

The module update rules defined in [RFC7950] ensure that a published module is never changed in a way that causes a client implementing an old module to stop working with a server implementing an updated module. This means that non-backwards compatible changes are not allowed and if they are necessary, then new definitions must be created with a new (module, path) name. Note the use of the word ‘updates’, which should not be confused with bug fixes.

Versioning and Naming

Proposals have been made to add semantic version numbers to the YANG language and to change the update rules such that non-backwards compatible changes can be made if they are protected by semantic version numbers. From an architectural perspective, this means we move from a (module, path) naming scheme to a (module, path, version) 1naming scheme. There are two important aspects to consider here:

  1. The version component may be ignored by simple clients (e.g., scripts) that are willing to take the risk that they may fail in interesting ways if they hit a server implementing a module with different semantics. When this happens, simple clients may get patched with a version check to prevent bad failures in the future. This essentially means to ignore the version component of the naming scheme until it failures indicate that version number checks are necessary.
  2. More advanced clients will pay attention to the version component and they may use more complex expressions instead of a simple version numbers, i.e., wildcarded version matches like 1.2.* or version expressions like (> 1.2.3 && < 1.6.0) || (> 2.0.0).
  3. The current (module, path) naming scheme requires to change the module name or the path and non-backwards compatible changes are made. This makes it easy to implement both an old and a new definition concurrently so that clients can gradually upgrade. With the (module, path, version) naming scheme, old clients may have to negotiate a server the version they want to use for their interaction with the server.

The proponents of the (module, path, version) naming scheme argue that allowing non-backwards compatible changes while keeping the (module, path) tuple unchanged is simpler and better aligned with common development practices. Whether this is true remains to be seen. It will be interesting to see how many simple clients are out there that will first fail and then (hopefully) get fixed to handle the new versioned naming scheme properly

Conclusions

The consequences of moving from a (module, path) naming scheme to a (module, path, version) naming scheme are significant. Any place where we make references in YANG and in protocols carrying YANG defined data, we have to define how the new version context is provided. And as explained above, the version component or version context most likely must allow for a complex matches or expression in the version name space component.

Moving from a (module, path) to a (module, path, version) naming scheme requires fundamental changes to both YANG and the associated protocols. Thus a new version of YANG and most likely new versions or at least substantial extensions of the protocols NETCONF and RESTCONF, will be needed (for example to support multiple versions of a module). Depending on the details of the solution, updates may also be required to core components such as the YANG Library [RFC8525] and the NETCONF Access Control Model [RFC8341].

The IETF started to discuss concrete proposals for this change, but I fear not all people have understood yet the far reaching consequences of a change of the naming scheme. While people initially proposed to use semantic version numbers, discussions started already concerning extensions or generalizations to support multiple different versioning schemes. I expect this to become a long journey.