YANG Schema Comparison

6.1. YANG module revision scope extension annotations

6.2. Node compatibility extension statements

In addition to the revision extension statement in [I-D.ietf-netmod-yang-module-versioning], this document defines YANG extension statements to indicate compatibility information for individual schema nodes and certain YANG statements.¶

The node compatibility extension statements are applicable to schema nodes (e.g. leaf, rpc, choice) as defined in [RFC7950], as well as a set of YANG statements (e.g. typedef) as listed in the YANG definition of the nbc-change-at extension in the ietf-yang-revisions module in this document.¶

While the top level non-backwards-compatible-revision statement is mandatory when there is a non-backwards-compatible change, the node compatibility statements are optional.¶

For many YANG statements, programmatic tooling can determine whether the changes to a statement between two module revisions constitutes a backwards-compatible or non-backwards-compatible change. However, for some statements, it may be impractical for tooling to determine whether the changes are backwards-compatible or not. For example, in the general case, tooling cannot determine whether the change in a YANG description statement causes a change in the semantics of a YANG schema node. If the change is to fix a typo or spelling mistake then the change can be classified as an editorial backwards-compatible change. Conversely, if the change modifies the behavioral specification of the data node then the change would need to be classified as either a non editorial backwards-compatible change or a non-backwards-compatible change. Hence, extension statements are defined to annotate a YANG module with additional information to clarify the scope of changes in cases that cannot be determined by algorithmic comparison.¶

Three extensions are defined for schema node compatibility information:¶

nbc-change-at:

Indicates a specific YANG statement had a non-backwards-compatible change at a particular module or sub-module revision¶

bc-change-at:

Indicates a specific YANG statement had a backwards-compatible change at a particular module or sub-module revision¶

editorial-change-at:

Indicates a specific YANG statement had an editorial change at a particular module or sub-module revision. The meaning of an editorial change is as per YANG Semver [I-D.ietf-netmod-yang-semver]¶

When a node compatibility statement is added to a schema node in a sub-module, the revision indicated for the compatibility statement is that of the sub-module.¶

Adding, modifying or removing any of the node compatibility statements is considered to be a BC change.¶

The following example illustrates the node compatibility statements:¶

              container some-stuff {
                leaf used-to-be-a-string {
                  rev:nbc-change-at "3.0.0" {
                    description "Changed from a string to a uint32.";
                  }
                  type uint32;
                }
                leaf fixed-my-description-typo {
                  rev:editorial-change-at "2022-06-03";
                  type string;
                  description "This description used to have a typo."
                }
                list sir-changed-a-lot {
                  rev:editorial-change-at "3.0.0";
                  rev:bc-change-at "2.3.0";
                  rev:bc-change-at "1.2.1_non_compatible";
                  description "a list of stuff";
                  ordered-by user;
                  key "foo";
                  leaf foo {
                    type string;
                  }
                  leaf thing {
                    type uint8;
                  }
                }

Note that an individual YANG statement may have a backwards-compatible change in a revision that is non-backwards-compatible (e.g. some other node changed in a non-backwards-compatible fashion in that particular revision).¶

If changes are ported from one branch of YANG model revisions to another branch, care must be taken with any node compatibilty statements. A simple copy-n-paste should not be used. The node compatibilty statements may incorrectly reference a revision that is not in the history of the new revision. Further, the statements might not apply depending on what the history is like in that new branch (e.g., an NBC change that is ported might not be an NBC change in the new branch). Node compatiblity statements should not be copied over to the new branch. Instead, the changes should be considered as completely new on the new branch, and any compatibility information should be generated from scratch.¶

When a node compatibility statement is present, that compatibilty statement is the authoritative classification of the backwards compatibility of the change to the schema node in the specifed revision. This allows a human author to explicitly communicate the compatibilty and potentially override the rules specified in this document. This is useful in a number of situations including:¶

• When a tool may not be able to accurately determine the compatibilty of a change. For example, a change in a 'pattern' or 'must' statement can be difficult for a user or tool to determine if it is a compatible change.¶
• When a pattern, range or other statement is changed to more correctly define the server constraint. An example is correcting a pattern that incorrectly included 355.xxx.xxx.xxx as a possible IPv4 address to make it only accept up to 255.xxx.xxx.xxx.¶

Nothing about the backwards compatibility of a schema node is implied by the absence of a node compatibility statement. Hence, the schema node definition must be compared between the two revisions to determine the backwards compatibility.¶

If any nbc-change-at extension statements exists in a module or sub-module, then the module or sub-module MUST have non-backwards-compatible-revision substatements in each revision statement of the module or sub-module history where the revision matches the argument of any nbc-change-at statements. If any revision statements are removed, then all node compatibiilty statements that reference that revision MUST also be removed. Conversely, node compatibilty statements MUST NOT be removed unless the associated revision statement in the revision history is removed.¶

If a node compatiblity statement is added to a grouping, then all instances where the grouping is used in the module or by an importing module are also impacted by the compatibilty information. Similarly for a 'typedef', all leafs and leaf-lists that use that typedef share the specified compatibility classification. A non-backwards-compatible change to a typedef or grouping defined in one module that is used by an importing module, does not cause the importing module to add a non-backwards-compatible-revision statement to the revision history. Non-backwards-compatible marking does not carry through import statements.¶

A node compatibility statement at a leaf, leaf-list, or typedef context takes precedence over a node compatibility statement in a typedef used by the leaf, leaf-list, or typedef. If multiple typedefs with compatibility statements are used by a leaf, leaf-list, or typedef (e.g. a union), and there is no compatibility statement at the top leaf, leaf-list, or typedef context, then the order of precedence used to classify the compatibility of the top level leaf, leaf-list, or typedef is as follows: nbc-change-at, bc-change-at, and finally editorial-change-at. That is, the leaf, leaf-list, or typedef takes the most impactful change classification of all the underlying typedefs.¶

Node compatibility statements are not supported on YANG statements such as 'pattern' or 'range'. The compatibility statement instead goes against the leaf, leaf-list, or typedef context.¶

Node compatibility statements that refer to pre-release revisions of a module MUST be removed when a full release revision of the module is published.¶

Node compatibilty statements SHOULD NOT be used when it isn't clear which change the statement is referring to. For example: If a leaf is reordered within a container, a node compatibility statement SHOULD NOT be used against the parent container nor against the reordered leaf. Similarly, if a leaf is renamed or moved to another context without keeping the old leaf present in the model and marked obsolete, a node compatibilty statement SHOULD not be used.¶

8.1. Standard YANG schema comparison algorithm

The standard method for comparing two YANG schema versions is to individually compare the module revisions for each module implemented by the schema using the algorithm defined in Section 7 and then aggregating the results together:¶

• If all implemented modules in the schema have only changed in an editorial way then the schema is changed in an editorial way¶
• If all implemented modules in the schema have only been changed in an editorial or backwards-compatible way then the schema is changed in a backwards-compatible way¶
• Otherwise if any implemented module in the schema has been changed in a non-backwards-compatible way then the schema is changed in a non-backwards-compatible way.¶

The standard schema comparison method is the RECOMMENDED scheme to calculate the version number change for new versions of YANG packages, because it allows the package version to be calculated based on changes to implemented modules revision history (or YANG semantic version number if used to identify module revisions).¶

8.2. Filtered YANG schema comparison algorithm

Another method to compare YANG schema, that is less likely to report inconsequential differences, is to construct full schema trees for the two schema versions, directly apply a version of the comparison algorithm defined in Section 6. This may be particular useful when the schema represents a complete datastore schema for a server because it allows various filtered to the comparison algorithm to provide a more specific answer about what changes may impact a particular client.¶

The full schema tree can easily be constructed from a YANG package definition, or alternative YANG schema definition.¶

Controlled by input parameters to the comparison algorithm, the following parts of the schema trees can optionally be filtered during the comparison:¶

• All "grouping" statements can be ignored (after all "use" statements have been processed when constructing the schema).¶
• All module and submodule metadata information (i.e. module level description, contact, organization, reference) can be ignored.¶
• The comparison can be restricted to the set of features that are of interest (different sets of features may apply to each schema versions).¶
• The comparison can be restricted to the subset of data nodes, RPCs, notifications and actions, that are of interest (e.g., the subset actually used by a particular client), providing a more meaningful result.¶
• The comparison could filter out backwards-compatible 'editorial' changes.¶

In addition to reporting the overall scope of changes at the schema level, the algorithm output can also optionally generate a list of specific changes between the two schema, along with the classification of those individual changes.¶

13.1. YANG Module Registrations

The following YANG module is requested to be registered in the "IANA Module Names" registry:¶

The ietf-yang-rev-annotations module:¶

• Name: ietf-yang-rev-annotations¶
• XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-rev-annotations¶
• Prefix: rev-ext¶
• Reference: [RFCXXXX]¶