Network Modeling C. Cardona Internet-Draft NTT Intended status: Informational B. Claise Expires: 19 March 2026 Everything OPS 15 September 2025 Guidelines for YANG Example Validation and Coverage Analysis in IETF Documents draft-cardona-claise-onion-yang-coverage-00 Abstract This document defines guidelines for including YANG example instances in IETF documents in a way that enables automatic extraction and validation. It introduces the concept of YANG module "coverage" to measure how thoroughly example instances exercise a YANG module's data nodes. The goal is to improve the quality and usability of YANG models in IETF documents by providing authors with tools to validate their examples and assess coverage completeness. Status of This Memo 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 19 March 2026. Copyright Notice Copyright (c) 2025 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 Cardona & Claise Expires 19 March 2026 [Page 1] Internet-Draft YANG Module Coverage September 2025 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Including YANG Example Instances in IETF Documents . . . . . 3 2.1. Types of Example Validation . . . . . . . . . . . . . . . 4 2.1.1. Simple Validation Examples . . . . . . . . . . . . . 5 2.1.2. Complex Examples with External References . . . . . . 5 2.2. Including Auxiliary YANG Modules for Examples . . . . . . 6 3. YANG Module Coverage by Examples . . . . . . . . . . . . . . 7 3.1. Coverage Example . . . . . . . . . . . . . . . . . . . . 8 3.2. Coverage Across Multiple Documents . . . . . . . . . . . 9 4. Implementation . . . . . . . . . . . . . . . . . . . . . . . 10 5. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 8.2. Informative References . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction Although the YANG data modeling language has been in use for over a decade, there remains a lack of tooling to help YANG model authors analyze and validate their YANG modules and example instances. People defining or evaluating YANG modules have limited guidance on how to include and test example data for those modules. Example data instances are vital to illustrate how a model is intended to be used, but the guidelines for presenting and validating these examples are scarce. The updated guidelines in RFC 8407bis improve the situation, but gaps still exist in providing tools that can automatically give authors feedback on what they might be missing in their models. The objective of this document is to define guidelines that enable the development of tools which, given one or more IETF documents (RFCs or drafts), can verify that the YANG model examples in those documents are correct and sufficiently comprehensive. To achieve this, we address two main aspects: Cardona & Claise Expires 19 March 2026 [Page 2] Internet-Draft YANG Module Coverage September 2025 * Guidelines for Including YANG Examples in RFCs: A clear method for authors to include example data instances of YANG models in IETF documents in a way that tools can automatically extract and validate them. In addition, we outline how tools can perform this extraction and validation, and we propose a method to include extra YANG modules (when necessary) for validating more complex examples without affecting the main normative content. * Definition of YANG Module "Coverage": A new concept to measure how much of a YANG module's data nodes are exercised by the example instances in a document. By analyzing the examples, a tool can inform authors which parts of their YANG model are covered and which are still missing from the examples. A proof-of-concept implementation for computing such coverage is also considered. Scope: The proposals in this document focus on typical use cases. It is expected that proof-of-concept tools will confirm the viability of these methods for moderately complex examples as this document progresses. If such automatic validation proves infeasible in practice, the approach may need adjustment. Extremely complex example scenarios (e.g., those involving schema mount or highly dynamic state) are outside the current scope and could be addressed in future work. 2. Including YANG Example Instances in IETF Documents When authors include example YANG instances in an RFC or Internet- Draft, those example instances SHOULD be formatted in a way that allows automatic extraction and validation by tools. Specifically, example instances SHOULD be enclosed as code blocks using the CODE BEGINS / CODE ENDS convention (as defined in the updated guidelines, e.g., draft-ietf-netmod-rfc8407bis). They should also be given a file name that clearly identifies them as examples, analogous to how YANG modules are named (see RFC 8407bis guidelines). We propose that the file name ends with the suffix .instance.xml for XML instances or .instance.json for JSON instances. This naming convention makes it easy for tools to identify which code snippets are YANG instance examples that can be parsed and validated. Each example file name SHOULD be unique within a document (and ideally unique across related documents being analyzed together). Tools may complain or error out if they encounter duplicate example file names, since that could indicate conflicting or repeated content. For example, an XML instance might be included as: Cardona & Claise Expires 19 March 2026 [Page 3] Internet-Draft YANG Module Coverage September 2025 // Not an actual instance file "interface-config.instance.xml" ... And a JSON instance as: // Not an actual instance file "interface-config.instance.json" { "interface": { ... } } By following this approach, a tool can scan the document for code blocks with filenames ending in .instance.xml or .instance.json, extract their contents, and validate them against the appropriate YANG modules. In cases where an included code snippet is not meant to represent a valid YANG instance (for instance, it might be pseudocode, a partial fragment, or intentionally invalid to illustrate an error), the author can indicate this so that automated validators skip it. For example, an author might choose not to use the CODE BEGINS/CODE ENDS markers or might omit the special .instance.xml/.json filename suffix for such a snippet. Without the markers or filename, the tool will know not to treat that snippet as a YANG instance example to be validated. An author could also include an explicit note in the text indicating that a given snippet is not for validation. Using these conventions strikes a balance between making examples machine- checkable and allowing flexibility for authors to include non-valid illustrative snippets when necessary. 2.1. Types of Example Validation Not all example instances are the same in terms of validation. Many YANG examples in documentation are simple and only involve the module defined in the document, but in more complex scenarios an example might span multiple modules or need knowledge of deviations, features, or other context. For the latter, wrapping the example in an instance data file format (defined by RFC 9195) can make explicit which modules and context are in use. This approach can handle more complicated example validation at the cost of a bit more verbosity. (If a given example scenario is too complex to easily capture even with the instance-data file format - for example, requiring extensive setup or dynamic state - it is considered out of scope for automatic validation in this document.) We distinguish between two categories Cardona & Claise Expires 19 March 2026 [Page 4] Internet-Draft YANG Module Coverage September 2025 of examples for validation purposes: 2.1.1. Simple Validation Examples These are straightforward examples that instantiate YANG modules defined in the same document, with a self-contained context. An extraction tool can load the YANG module(s) defined in the document (plus any standard modules they import) and then validate the example instance against those modules. For instance, if a draft defines a YANG module example-interfaces and provides a small XML snippet configuring an interface, the tool will use the example-interfaces module (and any of its dependencies) to verify that the XML conforms to the schema. In general, simple examples illustrate how to use the module(s) in the draft and can be validated with minimal additional information beyond what the document itself provides. 2.1.2. Complex Examples with External References These are examples that require additional context or external modules beyond those defined in the current document. For example, an instance data set may involve multiple modules (perhaps a module from this draft plus some from other RFCs), or it might describe operational state data that requires a specific datastore context or feature set. For such cases, we propose that the example be presented as a self-contained YANG instance data file using the standard format defined in RFC 9195 (the YANG Instance Data File Format). In practice, this means the example should be wrapped in the instance-data-set structure which includes the necessary metadata (such as module names, revisions, feature toggle states, and target datastore) for validation. For an XML-formatted complex example, the first element of the snippet should be , with the content formatted according to RFC 9195. Inside this element, sub-elements specify what YANG content schema the instance data conforms to (including module names, revision dates, features, deviations, and the intended datastore). Similarly, for a JSON- formatted complex example, the top-level JSON object should have a single key "ietf-yang-instance-data:instance-data-set", whose value is an object providing the same kind of metadata and the actual data set. By using the RFC 9195 instance-data-set wrapper, all the information needed to validate the instance is included within the text itself. A validation tool like yanglint (with appropriate support for RFC 9195) can read the instance-data-set, automatically load the indicated modules and their revisions, apply any stated deviations or feature enables, and then verify the embedded data content against the assembled schema. Note that if a tool detects Cardona & Claise Expires 19 March 2026 [Page 5] Internet-Draft YANG Module Coverage September 2025 that an example instance uses the RFC 9195 instance data format, it will attempt to validate it accordingly - and the example instance will fail validation if it does not conform to the declared schema or constraints. 2.2. Including Auxiliary YANG Modules for Examples Sometimes an example instance cannot be validated or understood without additional YANG definitions that are not part of the main module in the document. A common case is the use of YANG deviations or vendor-specific augmentations to adapt a base model. In principle, deviations are meant to be extraordinary measures (and their use is discouraged in final standards), but in practice they are sometimes used in industry deployments. To illustrate how a deviation or augmentation affects the data, an RFC might need to include a small auxiliary YANG module (for example, a module that contains deviation statements targeting the base model) purely for use in the example validation. The challenge is to do this without confusing readers or tools and without "contaminating" the main normative content of the document. We propose the following guidelines for including such auxiliary YANG modules in examples: * Use a Distinct File Extension: Include the auxiliary module as a code block with a filename that uses a different extension than ".yang". For example, use a suffix like .dyang for a deviation/ augmentation module that is only for the example. Using a non- standard extension ensures that general YANG module extraction tools will not treat it as a normative YANG module from the document. Any example that requires this auxiliary module can then reference it by its filename (with the .dyang extension) when running the validation tool. * Clearly Identify the Module as Non-Normative: The auxiliary module should be clearly identified as an example-only, non-normative module. This can be achieved through both its naming and its content. For instance, the CODE BEGINS label could name it something like "example-device-deviations.dyang" (including words like "example" or "dev" in the filename to signal its purpose). In the module source itself, use a module name and namespace that indicate it is not an official module. For example, use a namespace URI containing "example.com" or similar, and perhaps a module name ending in -example or with a clearly indicative name. * Explain in the Narrative: In the text surrounding the code, explicitly state that this module is an auxiliary construct provided for the sake of the example. For instance: "The following YANG module is an example showing how a deviation could Cardona & Claise Expires 19 March 2026 [Page 6] Internet-Draft YANG Module Coverage September 2025 be used for this scenario; it is not a normative part of this specification." This clarification is important for human readers and reviewers to avoid any confusion. By following these practices, authors can include necessary YANG deviations or supplemental modules to support their examples while making it clear that these are not part of the official data model being defined. Tools that extract and compile YANG modules from the document can be instructed to either ignore these example-only modules or handle them separately. For example, a tool might compile them only in the context of validating the corresponding example, and not raise an error about their presence or treat them as missing normative modules in the draft. 3. YANG Module Coverage by Examples Providing examples in YANG model documents is not just helpful for readers, but can also improve the quality of the model 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 schema nodes are present in at least one of the example instances. More specifically, we can define coverage as the set of data nodes (particularly leaf 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 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 model's functionality is demonstrated by the examples. Low coverage might suggest that important parts of the model 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 a "non-coverage 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 model remain unused in the examples. For example, a tool could output a tree or list of all leaf nodes not present in any example instance, indicating potential gaps in example coverage. Cardona & Claise Expires 19 March 2026 [Page 7] Internet-Draft YANG Module Coverage September 2025 This kind of feedback can help authors identify gaps and improve their documents. If a particular feature or branch of the model 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 model 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 under a list is covered if there is at least an example with an instance of the list that includes the leaf. That is, for a list with 2 different leafs, one leaf covered under one key and another under another one will still yield a 100% coverage of the list. 3.1. Coverage Example Consider this simple YANG module: module example-device { namespace "http://example.com/device"; prefix "dev"; container device { leaf hostname { type string; } leaf location { type string; } leaf admin-state { type boolean; } list interface { key "name"; leaf name { type string; } leaf enabled { type boolean; } leaf other { type boolean; } } } } And this example instance: Cardona & Claise Expires 19 March 2026 [Page 8] Internet-Draft YANG Module Coverage September 2025 file "device-config.instance.xml" router1 eth0 true Coverage analysis shows: - Total data nodes: 6 (hostname, location, admin-state, interface/ name, interface/enabled, interface/other) - Covered nodes: 3 (hostname, interface/name, interface/enabled) - Coverage percentage: 50% Non-coverage tree (missing nodes): device ├── location ├── admin-state └── interface └── other This analysis helps authors identify that the 'location' and 'admin- state' leafs need examples. 3.2. Coverage Across Multiple Documents 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 a 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. Cardona & Claise Expires 19 March 2026 [Page 9] Internet-Draft YANG Module Coverage September 2025 For the concept of YANG packages [I-D.ietf-netmod-yang-packages], the coverage across the entire package might be of interest. For the to-be-created ONIONS Working Group, the coverage across (service) abstractions might be of interest. 4. Implementation TODO. The progress of this document depends on the correct operation of its proposal in cases of relative complexity using an actual implementation. 5. Conclusion By standardizing how YANG examples are included and validated, we make it easier for implementers and reviewers to trust that the examples in a specification are correct and that a sufficient range of scenarios is covered. The concept of YANG module coverage, while exploratory, can further encourage authors to include more comprehensive examples and help pinpoint which parts of a data model might need additional illustration. Together, these measures aim to improve the overall quality and usability of YANG models in IETF documents. Ultimately, the success of these proposals will depend on tool support. As a next step, developing proof-of-concept tools or integrations (for example, enhancements to existing YANG validators like yanglint, or new scripts to extract and analyze examples) will be crucial. If moderately complex examples can be automatically extracted, validated, and measured for coverage with such tools, it will validate the approach. On the other hand, if significant obstacles arise during implementation, the recommendations in this document may need to be refined. Our hope is that these initial guidelines spark discussion and experimentation, leading to more robust support for YANG examples and better validation practices in the near future. 6. IANA Considerations This document has no IANA actions. Cardona & Claise Expires 19 March 2026 [Page 10] Internet-Draft YANG Module Coverage September 2025 7. Security Considerations This document defines guidelines for including and validating YANG examples in IETF documents. The recommendations do not introduce new security risks. However, implementers of validation tools should be aware of potential security considerations when processing example data from untrusted sources, such as denial of service attacks through maliciously crafted large or complex examples. 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9195] Lengyel, B. and B. Claise, "A File Format for YANG Instance Data", RFC 9195, DOI 10.17487/RFC9195, February 2022, . 8.2. Informative References [I-D.ietf-netmod-rfc8407bis] Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", Work in Progress, Internet-Draft, draft-ietf- netmod-rfc8407bis-28, 5 June 2025, . [I-D.ietf-netmod-yang-packages] Wilton, R., Rahman, R., Clarke, J., and J. Sterne, "YANG Packages", Work in Progress, Internet-Draft, draft-ietf- netmod-yang-packages-06, 7 July 2025, . Cardona & Claise Expires 19 March 2026 [Page 11] Internet-Draft YANG Module Coverage September 2025 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, DOI 10.17487/RFC8407, October 2018, . Authors' Addresses Camilo Cardona NTT 164-168, Carrer de Numancia 08029 Barcelona Catalonia Spain Email: camilo@gin.ntt.net Benoit Claise Everything OPS Email: benoit@everything-ops.net Cardona & Claise Expires 19 March 2026 [Page 12]