| Internet-Draft | YANG Examples | October 2026 |
| Cardona & Claise | Expires 3 May 2027 | [Page] |
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.¶
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, 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.¶
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.¶
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.¶
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.¶
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:¶
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.¶
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] (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.¶
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.¶
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".¶
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.¶
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.¶
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.¶
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.¶
This document has no IANA actions.¶
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.¶