Skip to main content

Guidelines for YANG Example and Supporting Artifacts in IETF Documents
draft-cardona-claise-netmod-yang-examples-00

Document Type Active Internet-Draft (individual)
Authors Camilo Cardona , Benoît Claise
Last updated 2026-11-02
RFC stream (None)
Intended RFC status (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-cardona-claise-netmod-yang-examples-00
Network Modeling                                              C. Cardona
Internet-Draft                                                       NTT
Updates: 9907 (if approved)                                    B. Claise
Intended status: Best Current Practice           Everything OPS & Arrcus
Expires: 3 May 2027                                      30 October 2026

 Guidelines for YANG Example and Supporting Artifacts in IETF Documents
              draft-cardona-claise-netmod-yang-examples-00

Abstract

   This document updates RFC 9907 guidance for including YANG-related
   examples and supporting artifacts in IETF documents.  It defines
   naming conventions that make those artifacts easier for tools to
   identify, extract, organize, and validate.

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 3 May 2027.

Copyright Notice

   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.

Cardona & Claise           Expires 3 May 2027                   [Page 1]
Internet-Draft                YANG Examples                 October 2026

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Including YANG Example Instances in IETF Documents  . . . . .   2
     2.1.  Types of Example Validation . . . . . . . . . . . . . . .   4
       2.1.1.  Simple Validation Examples  . . . . . . . . . . . . .   4
       2.1.2.  Complex Examples with External References . . . . . .   4
     2.2.  Including Auxiliary YANG Modules for Examples . . . . . .   5
   3.  Updates to RFC 9907 . . . . . . . . . . . . . . . . . . . . .   6
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   6.  Normative References  . . . . . . . . . . . . . . . . . . . .   7
   7.  Informative References  . . . . . . . . . . . . . . . . . . .   7
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   Although the YANG data modeling language has been in use for over a
   decade, people defining or evaluating YANG modules have limited
   guidance on how to include, extract, and test example data for those
   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
   some recommendations for usage examples and validation of valid data
   instances, but it still lacks an exact methodology that tools could
   use to work with them.

   This document defines conventions that allow tools to identify,
   extract, organize, and validate YANG-related examples and supporting
   artifacts.  It updates the usage-example guidance in Section 3.12 of
   [RFC9907] by requiring examples that illustrate a valid data instance
   to follow the naming conventions defined in this document
   (Section 2).  All other example and validation guidance in [RFC9907]
   is unchanged.  See Section 3 for the precise update.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119] [RFC8174] when, and only when, they appear in all capitals,
   as shown here.

2.  Including YANG Example Instances in IETF Documents

   When authors include example YANG instances in an RFC or Internet-
   Draft, examples that are meant to illustrate a valid data instance
   MUST use the conventions in this section.  Other example instances
   MAY use different conventions.

Cardona & Claise           Expires 3 May 2027                   [Page 2]
Internet-Draft                YANG Examples                 October 2026

   For XML or JSON instance examples covered by this section, authors
   MUST place the example in an RFCXML sourcecode element whose name
   attribute [RFC7991] gives the logical name of the artifact.  Tools
   implementing this specification MUST use the sourcecode name to
   identify examples for extraction and validation.  Code markers are
   not part of the identification mechanism defined by this document;
   their use remains governed by [RFC9907].  This document defines path-
   like conventions for the logical name, similar to, but not the same
   as, a file system path.

   Example instances that are meant to illustrate a valid data instance
   MUST use the logical artifact names yang/examples/valid-<name>.xml
   for XML instances and yang/examples/valid-<name>.json for JSON
   instances.  Each name SHOULD be unique within a document (and ideally
   unique across related documents being analyzed together).  For an
   [RFC9195] instance data set, the portion following valid- SHOULD
   follow the filename conventions in [RFC9195].  The valid- prefix is
   added by this document to identify an instance intended for automatic
   validation.

   The hierarchical filename is primarily a logical artifact name and
   classification.  During draft development, an accompanying Git
   repository or other external artifact collection MAY mirror the same
   logical layout.  Where practical, an external repository SHOULD
   mirror the logical hierarchy.  This document does not define the
   structure of such repositories.

   For example, the following RFCXML markup illustrates how an XML
   instance might be included:

   <sourcecode type="xml"
               name="yang/examples/valid-interface-config.xml">
     ...
   </sourcecode>

   And a JSON instance as:

   <sourcecode type="json"
               name="yang/examples/valid-interface-config.json">
     ...
   </sourcecode>

   By following this approach, a tool can scan the RFCXML source for
   sourcecode elements whose logical names are under yang/examples/,
   start with valid-, and end in .xml or .json, extract their contents,
   and validate them against the appropriate YANG modules.

Cardona & Claise           Expires 3 May 2027                   [Page 3]
Internet-Draft                YANG Examples                 October 2026

   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 not place the snippet under yang/examples/,
   or might not use the valid- prefix.  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 extractable 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 [RFC9195]) 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.
   We distinguish between two categories 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 the draft where the module is defined plus some from another
   draft with another module), 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 YANG
   instance data file using the standard format defined in [RFC9195]

Cardona & Claise           Expires 3 May 2027                   [Page 4]
Internet-Draft                YANG Examples                 October 2026

   (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, and
   target datastore) for validation.

   For an XML complex example, the first element of the snippet should
   be <instance-data-set xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-
   instance-data">, with the content formatted according to [RFC9195].
   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 [RFC9195] instance-data-set wrapper,
   the metadata needed to identify the intended content schema can be
   carried with the example.  A validation tool can use that metadata
   together with the available YANG modules to construct the appropriate
   schema context.  A validation tool such as [YANGLINT] (with
   appropriate support for [RFC9195]) can then verify the embedded data
   content against the assembled schema.  Validation of an [RFC9195]
   instance data set follows the semantics defined in [RFC9195],
   including its rules for partial data sets.

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.  One common case is when the module includes
   groupings that are meant to be used by other modules.  In those
   cases, the document might contain an example module (not official)
   that uses the groupings.  Another common case is the use of YANG
   deviations or vendor-specific augmentations to adapt a base module.
   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
   module) purely for use in example validation.  The challenge is to do
   this without confusing readers or tools and without "contaminating"
   the main normative content of the document.  This document defines
   yang/examples/ and yang/auxiliary/ as logical artifact categories;
   other YANG-related artifact categories could be defined later.

Cardona & Claise           Expires 3 May 2027                   [Page 5]
Internet-Draft                YANG Examples                 October 2026

   Auxiliary YANG modules SHOULD use a logical artifact name under yang/
   auxiliary/, for example yang/auxiliary/example-foo.yang.  In
   accordance with [RFC9907] Section 3.2.1, example YANG modules MUST
   NOT use the CODE BEGINS / CODE ENDS convention.  They can
   nevertheless be represented by a sourcecode element with a machine-
   readable name attribute, without markers="true".

   *  Keep Auxiliary Modules Separate: Include the auxiliary module in a
      way that makes it clear that it is not a normative YANG module
      from the document.  A validation tool processing an example that
      requires the auxiliary module would make that module available as
      part of the example's schema context.

   *  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.  In the module source itself, the module name SHOULD use
      the example- prefix as specified in [RFC9907], and the namespace
      should indicate that it is not an official module.  For example,
      use a namespace URI containing "example.com" or similar.

   *  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
      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.  Updates to RFC 9907

   This document updates Section 3.12 of [RFC9907] as follows.

   OLD:

   |  In order to ease extraction and validation of examples, it is
   |  RECOMMENDED to use code markers.

Cardona & Claise           Expires 3 May 2027                   [Page 6]
Internet-Draft                YANG Examples                 October 2026

   NEW:

   |  In order to ease extraction and validation of examples, it is
   |  RECOMMENDED to use code markers.  Examples that are meant to
   |  illustrate a valid data instance MUST follow the naming
   |  conventions defined in RFC XXXX.

   Note to the RFC Editor: please replace XXXX with the RFC number
   assigned to this document, and remove this note.

4.  IANA Considerations

   This document has no IANA actions.

5.  Security Considerations

   Tools that extract artifacts using logical names MUST prevent a
   logical name from escaping the intended extraction location.  Tools
   that process untrusted XML, JSON, or YANG artifacts should apply
   appropriate resource limits.

6.  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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
              RFC 7991, DOI 10.17487/RFC7991, December 2016,
              <https://www.rfc-editor.org/info/rfc7991>.

   [RFC9195]  Lengyel, B. and B. Claise, "A File Format for YANG
              Instance Data", RFC 9195, DOI 10.17487/RFC9195, February
              2022, <https://www.rfc-editor.org/info/rfc9195>.

   [RFC9907]  Bierman, A., Boucadair, M., Ed., and Q. Wu, "Guidelines
              for Authors and Reviewers of Documents Containing YANG
              Data Models", BCP 216, RFC 9907, DOI 10.17487/RFC9907,
              March 2026, <https://www.rfc-editor.org/info/rfc9907>.

7.  Informative References

Cardona & Claise           Expires 3 May 2027                   [Page 7]
Internet-Draft                YANG Examples                 October 2026

   [YANGLINT] CESNET, "libyang and yanglint Repository",
              <https://github.com/CESNET/libyang>.

Authors' Addresses

   Camilo Cardona
   NTT
   164-168, Carrer de Numancia
   08029 Barcelona Catalonia
   Spain
   Email: camilo@gin.ntt.net

   Benoit Claise
   Everything OPS & Arrcus
   Email: benoit@everything-ops.net

Cardona & Claise           Expires 3 May 2027                   [Page 8]