YANG Configuration Templates

YANG Configuration Templates Watsen Networks

kent+ietf@watsen.net

Huawei

101 Software Avenue, Yuhua District Jiangsu 210012 China maqiufang1@huawei.com

Nokia

India deepak.rajaram@nokia.com

Operations and Management Network Modeling YANG template NMDA This document defines a YANG-based configuration template mechanism whereby repetitive configuration data can be factored out into templates and applied where needed. This avoids the redundant definition of identical configuration and ensures the consistency of it, thus allowing configuration data to be managed more conveniently and efficiently. Discussion Venues Discussion of this document takes place on the Network Modeling Working Group mailing list (netmod@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction This document defines the "template" mechanism mentioned but not defined in Network Management Datastore Architecture (NMDA) . Templates enable repetitive configuration to be factored out into hierarchies of living templates and applied where the configuration is needed. This avoids the redundant definition of identical configuration and ensures the consistency of it, thus allowing configuration data to be managed more conveniently and efficiently. Templates are "hierarchal" in that templates may apply yet other templates. Templates are "living" in that their affect on configuration is maintained so long as the template is applied. Any change made to an applied template has immediate effect on the configuration. By example, an network management system (NMS) may manage many devices. Devices may be come from different vendors, each of which may have multiple types of devices (router, firewall, etc.), though sharing a common operating system. Further, each type of device may have different models (e.g., fw-100, fw-1000, etc.). In this case, common "fw-100" configuration could be put into a template called "common-fw-100-template", which itself inherits from a template called "common-fw-template", which itself inherits from a template called "common-vendor-template". Similarly, a "common-fw-1000-template" could inherit from "common-fw-template" and, likewise, a "common-rtr-template" could inherit from the "common-vendor-template". Templates are mostly for humans, but are still important even when the management of a server's configuration is fully automated. For instance, when provided templates, a server can optimize internal memory usage, enabling higher performance and scability. The solution presented in this document supports both servers that do and do not support NMDA. In both cases, templates are edited and applied as configuration in <running>. For servers supporting NMDA, templates may be defined in <system> , if supported by the server, and <intended> always returns the configuration with the templates expanded. For servers not supporting NMDA, a "with-templates-expanded" parameter may be passed by a client, when fetching configuration from <running>, to obtain the configuration with the templates expanded. However templates are expanded, a "with-template-inheritance" parameter may be passed by a client, when fetching expanded configuration, to obtain the expanded configuration with annotations indicating from which template values came from. Templates may be expanded off-box. If a client has knowledge of the complete contents of <running> and <system>, if supported by the server, the client can calculate the exact result of template expansion. Template expansion is independent of the server's operational state. Templates can be used with any YANG data model, including those defined with augmentations and/or deviations.

Editorial Note (To be removed by RFC Editor) Note to the RFC Editor: This section is to be removed prior to publication. This document contains placeholder values that need to be replaced with finalized values at the time of publication. This note summarizes all of the substitutions that are needed. No other RFC Editor instructions are specified elsewhere in this document. Please apply the following replacements:

XXXX --> the assigned RFC number for this draft
2026-07-03 --> the actual date of the publication of this document

Conventions and Definitions 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 BCP 14 when, and only when, they appear in all capitals, as shown here. The meanings of the symbols in tree diagrams are defined in . This document uses the terminology defined in and . This document uses the following terminology in :

configuration data

Besides, this document defines the following terminology:

configuration template:: A snippet of configuration data that may be applied to the configuration repeatedly, in order to simplify the delivery of network configuration and ensure the consistency of it. A configuration template is referred to interchangeably as "template" or "YANG template" throughout this document.

Examples used in this document encode YANG data using XML, as defined in . Other encodings such as JSON and CBOR could have been instead.

Applicability Statement The solution presented in this document can be implemented by any YANG-based server. The solution is data model independent and can be wholly realized as a preprocessor to the existing configuration management mechanism on a server.

Configuration Template Solution

Defining Templates Templates must first be defined before they can be applied (see ). Templates that are defined but not applied have no impact on configuration. The creation, modification, and deletion of references to templates is achieved by network management operations on the <running> datastore via YANG driven protocols such as NETCONF and RESTCONF . A server supporting templates MUST implement the "ietf-config-templates" YANG module defined in . This module defines a top-level "container" node called "templates" having a "list" node called "template". Each "template" node instance is a YANG configuration template containing the following descendant nodes:

id: a unique identifier for the template used when applying it.
description: an optional description for the template.
data-path: an optional schema location, if not root.
content: the configuration data the template holds.

Servers SHOULD validate templates at the time they are defined, that is, before they are applied, as described in . Validation is limited as templates do not need to, e.g., define mandatory nodes, but other checks are possible, such as ensuring nodes exist in the schema tree and that their values are of the correct type. The subsections below focus solely on how templates are defined, without any consideration for how they are applied.

Templates for Static Configuration Templates MAY be defined to set static configuration, i.e., configuration the is not repetitive, as described in . Such templates do not reduce the size of the configuration, but may be useful if wanting to group configuration scattered throughout the tree. For instance, for a server providing customer-facing services, there may be a group for each customer that sets all the configuration needed for the one customer. For example, the following template would, if applied, set the "/my-yang-module:top-level-node/foo/bar/baz" node to the "empty" value, creating any missing ancestor nodes as needed. The following template is identical to the one shown previously, but uses the "data-path" leaf to compress the "content" leaf's value. Templates can set values under "list" nodes as well. For instance, the following template would, if applied, set the "/my-yang-module:top-level-node/foo[key='f1']/bar[key='b1']/baz" node to the "empty" value, creating any missing ancestor nodes as needed. The following template is identical to the one shown previously, but uses the "data-path" leaf to compress the "content" leaf's value.

Templates for Repetitve Configuration The previous example shows a template setting configuration under a very specific list. But many times it is desirable to set the same configuration under any list or any list whose key values match a pattern. To allow a single template to apply to multiple list instances a wildcard pattern may be used within the key leafs to identify which list entries a template takes effect for. This only works for list keys with built-in type "string", or types derived from "string". The wildcard pattern MUST conform to the "Pattern Matching Notation" defined in Section 2.13 of IEEE-1003.1-2008. For example, the following template would, if applied, set the "baz" node to empty for any existing "bar" list beginning with 'b' under any existing "foo" list. The following template is identical to the one shown previously, but uses the "data-path" leaf to compress the "content" leaf's value.

Applying Templates Once templates have been defined (see , they may be applied (referenced) to the configuration where needed. Templates MUST be applied to have any effect on configuration. The creation, modification, and deletion of references to templates is achieved by network management operations on the <running> datastore via YANG driven protocols such as NETCONF and RESTCONF . Servers MUST validate templates at the time they are applied. Validation is achieved by first fully expanding the templates (see ) and then performing normal YANG validation on the expanded configuration. The subsections below focus solely on how templates are applied, without any consideration for how they are expanded.

Configuration Applying Templates A server supporting templates MUST conceptually use the "apply-templates" grouping, defined in the "ietf-config-templates" YANG module, in every "container" and "list" node in the configuration, excluding nodes defined by the "ietf-config-templates" YANG module itself. As seen in , the "apply-templates" grouping defines an ordered-by user "leaf-list" called "apply-templates". The "apply-templates" leaf-list is of type "leafref" having a "path" pointing to "/templates/template/name". That is, it identifies a list of templates to apply. That it is a list, and not a scalar, enables more than one template to be applied. That the list is ordered enables subsequent templates overriding values set by earlier templates. The algorithm for template expansion is discussed in . The following example illustrates the configuration's root node applying three templates.

Templates Applying Templates The template's "content" anydata node contains configuration, and therefore can apply templates like regular configuration. It is that templates can recursively apply templates that enables this enables templates to be "hierarchal". There MUST NOT be any circular chains of template applications. For example, if template "a" applies template "b", "b" cannot apply "a". The following example illustrates the configuration's root node applying a template that applies a template that applies a template.

Template Expansion Templates MUST be expanded, sometimes called "flattened", in order to produce a configuration that can be subject to YANG validation and applied by the server. Conceptually, template expansion is a generic (data-model independent) pre-processor to a server's backend that knows nothing about templates. That said, a server wishing to optimize internal memory usage to enable higher performance and scability may have a backend that is template-aware. This section presents an algorithm for how to expand templates.

Basic Rules When a configuration template is applied to a node in the data tree, it acts as if the configuration defined in the template is merged with the configuration provided explicitly at the corresponding level in the data tree, with the explicitly provided configuration taking precedence. The rules are as follows:

The value of a node in the expanded configuration is determined by using precedence to decide where to take the value from.
- Non-template configuration always has the highest precedence.
- When templates are applied from multiple ancestors and/or self, the innermost (furthest from root) applications takes precedence.
- When multiple templates are applied to a particular node, the order of application (as indicated by the client when applying the templates) determines the precedence within that node.
- When a template configuring list elements uses wildcards, and more than one matches, each match is applied in order, with the contents being merged.
When a template configures nodes higher (closer to the root node) in the configuration tree than where the template is applied, the template's higher-level nodes are ignored.

Merging Notes Merging configuration is a concept introduced in RFC 4741 without a formal definition, which is provided in this section for templates. Generally, when configuration C1 is merged into C2, nodes in C2 take precedence over nodes in C1. Details follow.

When "leaf" L1 is merged into a "leaf" L2, the L2 leaf is retained (L1 is discarded).
When "anydata" A1 is merged into a "anydata" A2, the A2 anydata is retained (A1 is discarded).
When "leaf-list" LL1 is merged into a "leaf-list" LL2, new values from LL1 are added (in order) to the end of LL2. Matching values are discarded.
When "container" C1 is merged into "container" C2, all non-matching descendant nodes are retained, and all matching descendant nodes are recursively merged.
When "list" LL1 is merged into a "list" LL2, all non-matching elements from LL1 are added (in order) to the end of LL2, and all matching elements are recursively merged.

For "ordered-by user" lists/leaf-lists, postpending new values/elements preserves the understanding that values/elements are processed Left to Right (or Top to Bottom). Thus, postpending values/elements causes the less important configuration (C1) to be processed after the more important configuration (C2). This may not be semantically accurate in all cases. For instance, the merging of two sorted lists of numbers should obstensibly be interleaved as necessary to produce an ordered list of numbers.

Algorithm This section describes an algorithm that implements the rules above. The algorithm walks the configuration tree from the root, and, at each node, merges the node's explicitly-provided configuration with the configuration contributed by any applied templates. The algorithm relies on the underlying YANG data model in order to classify each node (as a "container", "list", "leaf", "leaf-list", or "anydata") and to learn each list's key leaf(s), as the merging rules differ per node type and cannot be inferred from the encoded data alone.

Preparation Before expansion begins:

Index every template definition by its "name", so that an "apply-templates" reference can be resolved to a template's content.
Remove the template definitions from the configuration, as they are not themselves part of the expanded (<intended>) configuration.

Expansion then proceeds by processing the root node as a "container".

Collecting a Node's Sources (in Precedence Order) At each container (including each list entry, which is a container), the algorithm assembles an ordered list of "sources" that contribute configuration to that location, ordered from highest precedence to lowest:

The node's explicitly-provided configuration (i.e., everything except its "apply-templates" value) comes first.
For each name in the node's "apply-templates" value, in the order listed by the client, the template's content is resolved to this location (see below) and appended. Because a template's content may itself apply further templates, each template's content is processed recursively, so that templates applied by a template rank below the template that applied them.

Processing the sources in this order realizes the precedence rules: explicit configuration outranks templates, self-applied templates outrank ancestor-applied templates, and, among templates applied at the same node, earlier-listed templates outrank later ones. Applying a template that is already being applied further up the current chain is a circular reference and is an error.

Resolving a Template to the Applied Location ("ignore above") A template is authored as a full configuration subtree rooted at the top of the data tree, but it may be applied deep within the tree. To find the content a template contributes at the location where it is applied, the algorithm navigates from the template's root down the same path (the sequence of container and list-entry steps) that leads to the applied node. A list-entry step matches a template entry by comparing key values, honoring wildcards ("*" and "?") in the template's keys. If the template configures nothing at (or below) the applied location, it contributes nothing. Any nodes the template configures above the applied location are simply never reached by this navigation, which is how the "ignore above" rule is realized.

Merging the Sources Once a location's sources have been collected (highest precedence first), they are merged according to node type:

"container": The children of all sources are grouped by name, preserving the order in which each name is first seen (i.e., highest-precedence first). Each group is then merged recursively according to that child's node type.
"leaf" and "anydata"/"anyxml": The value from the highest-precedence source is kept; lower-precedence values are discarded.
"leaf-list": The higher-precedence values are kept, and any not-yet-present values from lower-precedence sources are appended, in order. Duplicate values are discarded.
"list": Entries are matched by their key value(s). Concrete (non- wildcard) entries establish the set of resulting entries, in order of first appearance. A wildcard entry contributes only to already- established (higher-precedence) entries that it matches; when several wildcard entries match the same entry, the later ones take precedence. Each resulting entry is then merged recursively as a container.

Protocol Query Parameters This section defines query parameters that can be used with YANG-driven protocols such as NETCONF and RESTCONF . For specific information regarding how these parameters are supported in NETCONF and RESTCONF, please see "I-D.ietf-netmod-config-templates-nc" and "I-D.ietf-netmod-config-templates-rc" respectively.

The "with-template-inheritance" Parameter When viewing configuration with templates expanded, it can sometimes become confusing where certain values were set. The "with-template-inheritance" parameter can be passed into configuration-fetching requests such as RESTCONF's GET or NETCONF's <get-data>. When the "with-template-inheritance" parameter is passed, the configuration returned is annotated with metadata indicating from which template values were set from, if any. The annotation is a string having a value following the pattern 'node-foo' was inherited from template 'template-bar'`.

The "with-templates-expanded" Parameter For servers supporting NMDA, templates are always expanded when the configuration is fetched from <intended>. For servers that do not support NMDA, the "with-templates-expanded" parameter can be passed into <running> configuration-fetching requests such as RESTCONF's GET or NETCONF's <get-config>. When the "with-templates-expanded" parameter is passed, the response is the same as if the configuration had been expanded.

The "with-inactive-removed" Parameter This paramter is NOT related to the template solution. It is a parameter that could be defined by some future "draft-ietf-netmod-inactive-config" I-D. The reason for this section is to lay bare logical extensions to the "with-template-expanded" parameter. That is, we could end up with a multiplicity of such parameters for servers that do not support NMDA to simulate fetching config from <intended>. Would a generic "get-intended" RPC for non-NMDA servers make more sense?

The "ietf-config-templates" YANG Module

Data Model Overview The following tree diagram illustrates the "ietf-config-templates" module: grouping apply-templates: +-- apply-templates* -> /templates/template/name ]]>

YANG Module Editor: Kent Watsen Editor: Qiufang Ma Editor: Deepak Rajaram "; description "This module defines a top-level 'templates' node, and an 'apply-templates' grouping. Copyright (c) 2026 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. 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 BCP 14 (RFC 2119) (RFC 8174) when, and only when, they appear in all capitals, as shown here."; revision 2026-07-03 { description "Initial revision."; reference "RFC XXXX: YANG Templates"; } list templates { key name; description "The list of templates managed on this device."; leaf name { type string; description "The name of the template."; } leaf description { type string; description "A textual description of the template."; } leaf data-path { type yang:xpath1.0; // FIXME: should be YPath? default "/"; description "The path location in the server's data tree that the ../content node is an instance of. The data-path MUST not begin with '/ietf-config-template:templates'."; } anydata content { mandatory true; description "A subset of server configuration beginning at the location identified by the ../data-path node. All top-level nodes MUST be namespace qualified. When ../data-path is '/', the content MUST NOT define any nodes under '/ietf-config-template:templates'."; } } grouping apply-templates { description "A grouping that is conceptually used (i.e., the 'uses' statement) at every 'container' and 'list' node in the configuration."; leaf-list apply-templates { type leafref { path /yct:templates/yct:name; } ordered-by user; description "A user-ordered list of template references."; } } // FIXME: augment "with-templates-expanded" into NETCONF RPCs, what about RESTCONF? } ]]>

Operational Considerations

Human Oriented

Smaller Footprint Configuration templates are designed to factor out repetititive configuration to a single definition that is applied repetitively. Use of templates therefore generally reduces the size of <running>.

Lower Cognative Load Configuration templates enable a label (i.e., the template's name) to be given for semantically related configuration, and then for that label to be referenced where needed. The additional structure provided by the template solution generally improves readability and understandability.

Machine Oriented

Scalability Concerns Large numbers of templates and/or large configurations may have performance issues during template expansion. Such issues may be improved by caching intermediate expansion results, trading CPU-time for storage.

One to Many Implications Configuration templates are designed to factor out configuration that is applied repetitively, possibly a large number of times. In some applications, (e.g., a network device controller), a single change to a single template could entail a potentially slow interaction with a large number of external systems.

Security Considerations

Access Control Editing configuration in a template MUST be authorized using the same access control settings used for standard configuration.

The "ietf-config-templates" Module This section is modelled after...FIXME.

IANA Considerations

The "IETF XML" Registry This document registers the following URI in the "IETF XML Registry" .

The "YANG Module Names" Registry This document registers the following YANG module in the "YANG Module Names" registry .

References Normative References Network Management Datastore Architecture (NMDA) Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The YANG 1.1 Data Modeling Language YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). Network Configuration Protocol (NETCONF) The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] The IETF XML Registry This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK] Informative References System-defined Configuration Huawei Huawei The Network Management Datastore Architecture (NMDA) in RFC 8342 defines several configuration datastores holding configuration. The contents of these configuration datastores are controlled by clients. This document introduces the concept of system configuration datastore holding configuration controlled by the system on which a server is running. The system configuration can be referenced (e.g., leafref) by configuration explicitly created by clients. This document updates RFC 8342. YANG Tree Diagrams This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language. JSON Encoding of Data Modeled with YANG This document defines encoding rules for representing configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using YANG as JavaScript Object Notation (JSON) text. Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR) YANG (RFC 7950) is a data modeling language used to model configuration data, state data, parameters and results of Remote Procedure Call (RPC) operations or actions, and notifications. This document defines encoding rules for YANG in the Concise Binary Object Representation (CBOR) (RFC 8949). RESTCONF Protocol This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).

Test Vectors This section provides normative vector tests for implementations.

Example YANG Module This section presents a YANG module that is used by the vector tests.

Original This is the original YANG module.

Annotated This is the original YANG module after it has been annotated with uses "yct:apply-templates" statements, as required by .

Basic Tests

No Templates Applied When the <running> datastore is: The <intended> datastore is:

All Configuration in a Single Template When the <running> datastore is: The <intended> datastore is:

All Configuration in a Multiplicity of Templates When the <running> datastore is: The <intended> datastore is:

Empty Node Tests

Empty "apply-template" List When the <running> datastore is: The <intended> datastore is:

Empty Template Content When the <running> datastore is: The <intended> datastore is:

Node "leaf" Tests

Hierarchal Precedence When the <running> datastore is: The <intended> datastore is: