]> Cisco Systems

rtv@cisco.com

Cisco Systems

saikarna@cisco.com

Cisco Systems

sarthakj@cisco.com

Cisco Systems

vemoorth@cisco.com

Cisco Systems

vnagaman@cisco.com

OPS NETMOD Working Group yang netconf yang-models deprecation model-evolution As YANG data models evolve over time, model nodes are often deprecated or made obsolete. Current practices for documenting replacement paths for these nodes rely on unstructured external documents, making it difficult to programmatically identify and migrate to replacement nodes. This document proposes a YANG extension mechanism that embeds replacement path information directly within YANG models, enabling automation tools to identify replacement nodes and assist users in migrating from deprecated elements to their replacements. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the NETMOD Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction YANG is a data modeling language used to define the configuration and operational data of network devices. As network technologies evolve, some nodes within YANG modules become deprecated or obsolete. Operators then need a reliable way to discover which schema nodes supersede the deprecated ones so they can migrate configuration and operational tooling. The YANG language provides the status statement to mark nodes as deprecated or obsolete, but it offers no standardized mechanism to point to the successor node(s). Current practice relies on unstructured documents, spreadsheets, or ad-hoc emails. The goal of this document is to embed that knowledge directly in the YANG modules so that both humans and automation can infer replacements programmatically. The term “replacement” in this document refers to guidance that accompanies deprecated or obsolete nodes. The intent is not to redefine YANG status values, but to provide structured metadata that helps operators and tooling identify where to migrate.

Problem Statement Currently, when YANG model nodes are deprecated or obsoleted, the information about replacement nodes is typically documented in separate, unstructured documents such as CSV files, release notes, or emails. This approach suffers from several significant drawbacks: Inefficiency: Network operators must manually search through external documentation to find replacement paths, often requiring correlation between multiple documents. Error-prone: External documentation can become outdated or may not accurately reflect the current node structure and paths defined in the YANG files, leading to incorrect migrations. Lack of automation: Without a standardized, machine-readable way to express replacement information, tools cannot programmatically identify replacement nodes or assist users in migration. Documentation fragmentation: Replacement information becomes scattered across multiple documents, making it difficult to maintain a complete view of model evolution. These challenges are particularly acute for large-scale network operators who must manage configuration across numerous devices with diverse YANG models, and for vendors who need to support customers through model transitions. It's worth noting that this functionality has been proposed as a potential enhancement to a future version of the YANG language itself (). However, developing and standardizing a new version of YANG would likely take a long while. The solution proposed in this document is designed to be standardized quickly and used with existing YANG modules and infrastructure. At IETF 123, the NETMOD working group expressed strong interest in addressing this problem statement with requests for additional clarification on the solution approach.

Solution To address the challenges associated with deprecated or obsolete nodes in YANG models, we propose an extension-based approach that embeds replacement information directly within the YANG models themselves. This approach follows the recommendations in for extending YANG functionality without modifying the core language.

Proposed Extension Mechanism Specifically, we introduce a custom extension, ietf-depr:deprecated-info, that authors attach to nodes marked status deprecated. This extension carries a structured tuple that documents the migration path during the deprecation window—the critical period when users are expected to transition to replacement nodes. This approach represents successor paths as structured tuples instead of opaque strings and enables the expression of one-to-many relationships through comma-separated paths within a single tuple. Importantly, this extension is designed for the deprecation phase only. When a node transitions from status deprecated to status obsolete, the extension MUST be removed. This design decision addresses a critical challenge in long-lived YANG modules: industry best practices (RFC 8407, BBF OD-360) mandate that obsolete nodes remain in modules indefinitely for backward compatibility. In large-scale production environments with hundreds or thousands of deprecated nodes across module portfolios, keeping structured metadata on obsolete nodes would result in permanent, ever-growing clutter with minimal benefit, since automated migration should occur during the deprecation window. Each extension statement carries a structured tuple that follows the ABNF in . The tuple consists of one or more path entries, where each entry specifies a path-type (absolute, relative, or none) and its corresponding path-target. When multiple path entries are provided as a comma-separated list, automated migration tools MUST process all paths, treating them as a one-to-many split of functionality where each target is mandatory for complete migration. Each path entry in a comma-separated list may use a different path-type as needed.

Lifecycle Tuple ABNF

Each path-entry is self-contained with its own path-type prefix. When path-type is absolute, path-target is an absolute-schema-nodeid that resolves from the module root. When path-type is relative, the path is interpreted relative to the schema node that instantiates the grouping containing the deprecated node. When path-type is none, path-target MUST be the literal none to indicate no direct replacement exists. Human-readable migration guidance, such as operational notes, migration complexity warnings, or removal timelines, SHOULD be documented in the node's description statement rather than in the structured tuple. This maintains a clear separation: the extension provides machine-readable migration paths for automation tools, while the description provides human-readable context for operators and developers. The benefits of this approach include: Backward compatibility: The extension approach doesn't require changes to the YANG language itself and is compatible with existing tools. Self-documenting models: Replacement information is embedded directly in the models, eliminating the need for external documentation. Automation enablement: Tools can programmatically identify replacement paths and assist with migration. Improved developer experience: YANG model developers and users gain clear guidance for transitions between deprecated and replacement nodes. Support for complex replacements: The tuple format with comma-separated paths allows one-to-many replacements with clear, unambiguous semantics for automated migration tools, including cases that cross module boundaries.

Allowed Placements and Lifecycle Rules The ietf-depr:deprecated-info extension MAY be applied to the following YANG statements: container, list, leaf, leaf-list, choice, case, anydata, and anyxml. This extension MUST NOT appear on RPC, action, or notification statements. The extension MUST be used only with status deprecated. Tooling MUST treat the presence of this extension on a node without status deprecated as an error. This normative pairing ensures the extension serves as structured lifecycle metadata rather than advisory hints. Each schema node SHOULD have at most one occurrence of the extension. When functionality splits across multiple replacement nodes (one-to-many migration), publishers MUST provide a comma-separated list of paths within a single extension statement. Automated migration tools MUST process all paths in such a list, treating them as mandatory targets for complete migration. This ensures unambiguous semantics: a single tuple defines the complete, deterministic migration path. Removal Upon Obsolescence: When a node's status transitions from deprecated to obsolete, the ietf-depr:deprecated-info extension MUST be removed. Rationale: Industry best practices mandate that obsolete nodes remain in YANG modules indefinitely for backward compatibility. Retaining structured migration metadata on obsolete nodes leads to unbounded accumulation—in high-volume environments, this can result in hundreds or thousands of unnecessary metadata entries for nodes that users should have migrated from years earlier. Migration guidance for obsolete nodes, if needed, belongs in human-readable description statements.

Design-Time Evaluation Rationale The ability to reason about replacements at design time is critical. Embedding the tuples directly in the YANG source enables: Model reviews: Working group and vendor reviewers can confirm that every deprecated node is paired with an up-to-date replacement before publishing modules. Toolchain validation: Compilers and CI pipelines can flag missing or malformed tuples while the module is being authored instead of deferring to deployment time. Automation planning: Operators and orchestrators can evaluate the impact of upcoming deprecations without requiring device connectivity. This approach aligns with the guidance in on providing migration help inside the model itself.

Extension Versus Instance Data Replacement paths are documented as extensions rather than instance data because the metadata must travel with the module revisions that introduce deprecations. Instance data is deployment-specific and would not be available to the many tools (IDEs, code generators, documentation sites) that process YANG modules in isolation during development and design-time validation.

Lifecycle Transitions and Module Maintainability Several YANG modules deprecate nodes for one or more releases before ultimately marking them status obsolete. This creates a three-stage lifecycle: Current phase: Node is in active use with no deprecation or obsoletion marking (the default state in YANG). No migration metadata is needed. Deprecation phase: Node carries status deprecated with ietf-depr:deprecated-info extension. This is the active migration window where users should transition to replacements and automated tooling can leverage the structured metadata. Obsolete phase: Node carries status obsolete and the ietf-depr:deprecated-info extension is removed. The node remains in the module indefinitely per industry best practices, with migration guidance provided in the description statement for any laggards. This approach balances the competing needs of: Automation support: Structured metadata during deprecation enables proactive, tool-assisted migration during the critical window. Long-term maintainability: Removing metadata at obsolescence prevents unbounded accumulation. In large-scale production environments with extensive module portfolios, retaining structured metadata on all obsolete nodes would create permanent clutter with minimal value—users encountering an obsolete node years after deprecation have long missed the automation window. When a deprecated node has no successor (functionality is being removed entirely), the tuple uses path-type = none and path-target = none. This signals to tooling that there is no automated migration target and manual intervention is required. Upon transition to obsolete, this extension is also removed.

Related Work and Alternatives Alternative approaches for documenting deprecation paths include model-specific conventions, instance-data catalogues, and proposals for future YANG language revisions (often referred to collectively as "YANG Next"). This document positions the extension as an immediately deployable option that complements those efforts. Publishers can still provide supplemental instance data where useful, but the extension ensures there is a normative pointer available inside the module itself.

Implementation Guidelines and Syntax The following sections demonstrate how the lifecycle extensions can be applied across different replacement scenarios. The examples illustrate common patterns encountered when evolving YANG models and show how the tuples provide clear migration paths for each situation.

Path Reference Types To accommodate different structural relationships between deprecated nodes and their replacements, we define three types of path references in the path-type field: absolute: Used when the replacement node can be directly referenced with an absolute schema path from the YANG module root. This is the most common case for nodes inside standard containers and lists. relative: Used when the replacement node appears in multiple places, such as within groupings or augments. The path is resolved relative to the instantiation of the grouping that contains the deprecated node. This approach ensures the reference remains valid regardless of where the grouping is used. none: Used to signal that no direct replacement exists. Human-readable migration guidance should be provided in the node's description statement. Each path reference type has specific syntax requirements and use cases, which are illustrated in the examples that follow.

Summary of Syntax Notations The following syntax notations are used for replacement paths: absolute:/{File_name}:{path}: Indicates the absolute path of the replacement node in a file. relative:/{File_name}:{grouping_name}/{rel_path_inside_grouping}: Indicates the relative path of the replacement node within a specified grouping in a file. none:none: Indicates that there is no replacement for the deprecated node. Human-readable migration guidance should be provided in the node's description statement. absolute:/path1,absolute:/path2: Multiple paths in a comma-separated list for one-to-many migrations. Each path has its own path-type prefix and all paths are mandatory for complete migration. absolute:/path1,relative:/grouping:path2: Mixed path types are allowed in comma-separated lists when replacements span different structural contexts.

Simple Node Replacement Example Description: a node is deprecated and has a replacement node in the same container. YANG Example:

No Replacement Example Description: a node is deprecated and there is no direct replacement node. YANG Example:

Grouping Examples Identifying XPath nodes within YANG models, particularly when dealing with groupings, presents a challenge. Nodes that are imported through grouping may not be easily pinpointed using absolute XPath. The solution is to uniquely identify the grouping using the file name and grouping name, then provide a relative XPath from the top level of the grouping. In all other cases, an absolute XPath can be provided. Utilize the file name and grouping name to uniquely identify the grouping within the YANG model. Provide a relative XPath from the top level of the grouping to pinpoint the node. This approach ensures that nodes within groupings can be accurately identified and referenced, while maintaining clarity and precision for nodes outside of groupings.

Node Deprecated Outside Grouping, Replacement Inside Grouping Description: a node that is deprecated outside a grouping structure but has a replacement node within a specific grouping. YANG Example:

Node Deprecated Inside Grouping, Replacement Outside in a Non-Group Description: a node that is deprecated within a grouping structure but has a replacement node outside any grouping. YANG Example:

Node Deprecated Inside Grouping, Replacement Inside Existing/New Grouping Description: a node that is deprecated within a grouping structure and has a replacement node within the same or a new grouping structure. YANG Example:

Node Deprecated Outside Grouping, Replacement Outside Grouping Description: a node that is deprecated outside a grouping structure and has a replacement node also outside any grouping. YANG Example:

Replacement Guidelines for Non-Leaf Level Deprecation When deprecating structures like container or list at their respective levels, it is essential to ensure that the replacement is explicitly mentioned at all sub-levels, including child elements such as leaf, leaf-list, or nested structures. This approach ensures clarity and provides a complete mapping of deprecated elements to their replacements, making it easier for users to transition to the new structure. YANG Example:

Example Implementation The following examples demonstrate how the lifecycle extensions can be implemented. These are vendor-neutral examples created specifically for this document to illustrate the functionality and are not intended to be actual YANG modules used in production environments.

ietf-deprecated-info.yang module YANG Example: "; description "This module defines an extension for documenting migration paths for deprecated YANG nodes. Copyright (c) 2024 IETF Trust and the persons identified as authors of the code. All rights reserved."; extension deprecated-info { argument "tuple"; description "Provides structured migration path for deprecated nodes. This extension MUST be used only with 'status deprecated'. The tuple provides machine-readable replacement paths for automated migration tools. Human-readable guidance (migration notes, operational considerations, timelines) SHOULD be documented in the node's description statement, maintaining clear separation between structured automation metadata and human-oriented documentation. When a node transitions from 'status deprecated' to 'status obsolete', this extension MUST be removed to prevent accumulation of unnecessary metadata on nodes that will never be removed from the module per industry best practices (RFC 8407, BBF OD-360). Rationale: Industry standards mandate that obsolete nodes remain in YANG modules indefinitely for backward compatibility. With high-volume deprecations in production environments, keeping structured metadata only during the active migration window (deprecated phase) balances automation needs with long-term module maintainability."; } } ]]>

ietf-deprecation-regression-test-17131.yang module YANG Example:

ietf-deprecation-regression-test-helper-module-17131.yang module YANG Example: "; import ietf-deprecated-info { prefix ietf-depr; } // Case 6 : Leaf inside a grouping deprecated, replaced in the same grouping but imported through // a different module and used in various modules. grouping groupCase6 { leaf case6 { type uint8; default 10; status deprecated; description "Case 6 - Leaf inside a grouping deprecated, replaced in the same grouping but imported through a different module and used in various modules, leaf case-6 (DEPRECATED)"; ietf-depr:deprecated-info "relative:/ietf-depr-reg-test-helper-17131:" "groupCase6/case6-replacement"; } leaf case6-replacement { type uint8; default 11; description "Case 6 - Leaf inside a grouping deprecated, replaced in the same grouping but imported through a different module and used in various modules, leaf case6-replacement (NEW)"; } } } ]]>

ietf-deprecation-regression-test-file-2-17131.yang module YANG Example:

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.

Operational Considerations Network operators and YANG model consumers can leverage the information provided by the ietf-depr:deprecated-info extension in several ways: Automated Migration Tools: Software tools can be developed to scan configurations using deprecated nodes and automatically suggest or implement replacements. Documentation Generation: Model documentation tools can highlight deprecated nodes and their replacements, making it easier for network operators to understand migration paths. Configuration Validation: Validation tools can warn about the use of deprecated nodes and suggest alternatives based on the extension data. Training and Knowledge Transfer: The explicit documentation of replacements can help in training and knowledge transfer as teams adopt newer model versions.

Security Considerations The extension defined in this document does not introduce new protocol behaviour or data plane interactions. The tuples are metadata that accompany YANG modules and are evaluated at design time. Consequently, the security considerations of apply. Incorrect or stale tuples could mislead automation systems or operators during migrations. Publishers SHOULD validate tuples during module reviews and CI testing, and consumers SHOULD treat the tuples as advisory rather than authoritative until verified in their environments. The tuples do not carry sensitive information beyond schema paths. They neither relax access control nor expose configuration data. Implementations SHOULD ensure that tuple parsing failures are handled gracefully (for example by logging warnings) to avoid denial-of-service conditions caused by malformed metadata.

IANA Considerations IANA is requested to add a new entry to the "IETF XML Registry" for the namespace urn:ietf:params:xml:ns:yang:ietf-deprecated-info with reference to this document. IANA is also requested to add a new entry to the "YANG Module Names" registry with the following values: name ietf-deprecated-info, namespace urn:ietf:params:xml:ns:yang:ietf-deprecated-info, prefix ietf-depr, reference this document. No other IANA actions are required.

Tail-f Systems YumaWorks Harvard University Huawei Technologies

Acknowledgments The authors would like to thank the NETMOD working group participants for their valuable feedback during the IETF 123 discussion. Special thanks to Kent Watsen, Lou Berger, Balazs Lengyel, Reshad Rahman, Deepak Rajaram, and Rob Wilton for their constructive comments that significantly shaped this specification. The authors acknowledge the ongoing YANG Next discussions captured in that provided initial inspiration for this proposal.

Change Log Changes from draft-rtv-netmod-yang-subtree-replacement-00 to draft-rtv-netmod-yang-subtree-replacement-01: Renamed extension from replacement-info to deprecated-info to reflect source node state rather than target, based on IETF 123 feedback from Kent Watsen Extension now mandatory only for status deprecated nodes; MUST be removed when transitioning to status obsolete to prevent unbounded metadata accumulation in long-lived modules Renamed module from ietf-replace-path-ext to ietf-deprecated-info to align with extension name and clarify purpose Changed path type syntax from REPLACEMENT_ABSOLUTE_PATH/REPLACEMENT_REL_PATH to lowercase absolute/relative/none for consistency with YANG conventions Added formal ABNF grammar definition for lifecycle tuple structure, with each path in a comma-separated list carrying its own path-type prefix to support mixed absolute/relative replacements in one-to-many migrations Added explicit rationale for extension-based approach versus instance data (portability and tool coverage requirements) Added design-time evaluation rationale section addressing IETF 123 feedback from Rob Wilton and others Added lifecycle transitions section explaining three-stage lifecycle (current, deprecated, obsolete) and metadata removal policy Clarified allowed statement types and validation rules for extension placement Restructured Section 4: moved "Summary of Syntax Notations" before case examples for improved readability Documented IETF 123 NETMOD working group chair poll outcome showing broad interest in addressing the problem statement