]> Guidelines for YANG Example and Supporting Artifacts in IETF Documents NTT
164-168, Carrer de Numancia Barcelona Catalonia 08029 Spain camilo@gin.ntt.net
Everything OPS & Arrcus
benoit@everything-ops.net
Operations and Management Network Modeling YANG validation examples artifacts 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.
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. 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 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 is unchanged. See 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 when, and only when, they appear in all capitals, as shown here.
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. For XML or JSON instance examples covered by this section, authors MUST place the example in an RFCXML sourcecode element whose name attribute 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 . 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 instance data set, the portion following valid- SHOULD follow the filename conventions in . 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: ... ]]> And a JSON instance as: ... ]]> 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.
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 ) 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:
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.
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 (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 . 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 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 (with appropriate support for ) can then verify the embedded data content against the assembled schema. Validation of an instance data set follows the semantics defined in , including its rules for partial data sets.
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. Auxiliary YANG modules SHOULD use a logical artifact name under yang/auxiliary/, for example yang/auxiliary/example-foo.yang. In accordance with 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 , 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.
Updates to RFC 9907 This document updates Section 3.12 of 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.
IANA Considerations This document has no IANA actions.
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.
Normative References&RFC2119;&RFC8174; Informative References libyang and yanglint Repository CESNET