| Internet-Draft | YANG Coverage | October 2026 |
| Cardona & Claise | Expires 3 May 2027 | [Page] |
This document introduces the concept of YANG module "coverage" to measure how thoroughly example instances exercise a YANG module's data nodes. Coverage analysis identifies the parts of a module that are and are not exercised by examples, helping authors, reviewers, and implementers understand the range of scenarios illustrated by a specification.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 3 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Although the YANG data modeling language has been in use for over a decade, tools can help YANG module authors analyze the example instances that illustrate their modules. Example data instances are vital to illustrate how a module is intended to be used. [RFC9907] provides guidelines for authors and reviewers of documents containing YANG data models, including recommendations for usage examples and validation of valid data instances.¶
Providing examples in YANG module documents is not just helpful for readers, but can also improve the quality of the module itself. We introduce the concept of YANG module coverage as a way to measure how thoroughly the provided examples exercise the data model.¶
By analogy to code coverage in software testing (which checks what fraction of code is executed by tests), YANG module coverage looks at what fraction of a module's data nodes are present in at least one of the example instances. For the baseline metric, coverage is defined over terminal data nodes, that is, leaf and leaf-list nodes from the YANG module that have a value in one or more example instances. A simple quantitative metric could be the percentage of the module's leaf and leaf-list nodes that appear in at least one example.¶
For instance, if a YANG module defines 100 configurable or state leaf nodes, and the examples collectively include 45 of those leaves, one could say the example coverage is 45%. This number, while not telling the whole story, gives an indication of how much of the module's functionality is demonstrated by the examples. Low coverage might suggest that important parts of the module are never shown in any example. This could mean those parts are either less relevant or simply that the document might benefit from additional examples to cover them.¶
Probably more helpful than the coverage percentage, we can also define an "uncovered-node tree" - essentially a view of the data model highlighting the nodes that were not covered by any example. This is perhaps the most direct way of showing the authors which portions of their module remain unused in the examples. For example, a tool could output a tree or list of all leaf and leaf-list nodes not present in any example instance, indicating potential gaps in example coverage.¶
This kind of feedback can help authors identify gaps and improve their documents. If a particular feature or branch of the module has no example, the authors might choose to add one for completeness or clarity. In some cases, it might reveal that certain parts of the module are hard to exemplify or not yet implemented, which could prompt re-thinking that part of the design or at least adding an explanation for why it's not covered by any example.¶
Coverage works directly on the data nodes from the YANG module. It should be as simple as possible, therefore, we will consider that any data leaf or leaf-list under a list is covered if there is at least an example with an instance of the list that includes it. That is, for a list with 2 different leaves, one leaf covered under one key and another under another one will still yield a 100% coverage of the list leaves.¶
Consider this simple YANG module:¶
module example-device {
yang-version 1.1;
namespace "http://example.com/device";
prefix "dev";
description
"This is a non-normative example module, provided only to
illustrate coverage analysis in this document.";
revision 2026-06-25 { description "Initial example revision."; }
container device {
description "Top-level device configuration.";
leaf hostname {
type string;
description "The device hostname.";
}
leaf location {
type string;
description "Physical location of the device.";
}
leaf admin-state {
type boolean;
description "Administrative state of the device.";
}
list interface {
key "name";
description "List of device interfaces.";
leaf name {
type string;
description "Interface name; the list key.";
}
leaf enabled {
type boolean;
description "Whether the interface is enabled.";
}
leaf other {
type boolean;
description "An additional example leaf.";
}
}
}
}
¶
And this example instance:¶
<device xmlns="http://example.com/device">
<hostname>router1</hostname>
<interface>
<name>eth0</name>
<enabled>true</enabled>
</interface>
</device>
¶
A potential coverage analysis tool could then show:¶
Uncovered-node tree (missing nodes):¶
device - location - admin-state - interface - other
This analysis helps authors identify that the 'location', 'admin-state', and 'interface/other' leaves need examples.¶
It is common that a YANG module defined in one document might be used, extended, or exemplified in another document. Examples could be spread across multiple RFCs or drafts (for instance, a base YANG module in an RFC and a usage guide in a separate draft that provides additional examples). While our primary focus is on coverage within a single document's scope (i.e. how well the examples in this document cover this document's module), one could imagine tooling that aggregates examples from multiple sources for a more holistic coverage analysis. For example, if module A is defined in RFC X, and RFC Y (perhaps a companion or an applicability statement) provides additional examples for module A, a combined coverage analysis across X and Y would give a better picture of how module A is covered in total. We will strive to define approaches that enable tooling to do this kind of multi-document coverage assessment automatically in the future.¶
For the concept of YANG packages [I-D.ietf-netmod-yang-packages], the coverage across the entire package might be of interest.¶
The baseline metric in this document is intentionally limited to leaf and leaf-list coverage. Feedback received on version -00 identified additional useful information that is not naturally represented by the baseline uncovered-node tree.¶
A proof-of-concept implementation has been developed in the yangson-coverage repository [YANGSON-COVERAGE]. The implementation uses Yangson [YANGSON] as a library for loading YANG modules and validating instance data, and then implements the coverage logic described in this document. We will attempt to push these ideas directly to Yangson as we continue our work.¶
Yangson already exposes validation counters for schema nodes and can print a complete schema tree annotated with those counters. This is useful input, but it is not the report format defined here. The proof of concept tracks covered leaves across validated examples and generates the uncovered-node tree described in this document: covered terminal nodes are removed, and parent nodes are kept only as context.¶
The proof of concept also provides a command-line interface to reset coverage state, validate examples while accumulating coverage, and print the uncovered-node report. It includes initial support for grouping-level reporting, while the exact grouping metrics remain future work.¶
Other related tooling includes yanglint [YANGLINT], example validation scripts such as yang-validation [YANG-VALIDATION], the "Internet-Draft with YANG Modules" template [I-D-WITH-YANG-TEMPLATE], and the associated I-D-with-yang-tools repository [I-D-WITH-YANG-TOOLS]. These tools and templates support validation of YANG modules, tree generation, and validation of examples.¶
This document has no IANA actions.¶
This document has no security considerations.¶