Network Working Group S. Dikshit Internet-Draft Aruba Networks, HPE Intended status: Standards Track 30 August 2026 Expires: 1 March 2027 A YANG Extension for Declaring the Comparability Scope of Operational State draft-dikshit-netmod-comparability-scope-extension-00 Abstract Several YANG modules currently in progress across multiple IETF working groups define counters, gauges, and other measured values that are exported from a network element and compared, summed, or averaged by a remote collector, either against the same node's history or against values from a different node. YANG (RFC 7950) has no first-class, machine-checkable way to state the domain within which two occurrences of such a value are comparable, so this determination is currently made, inconsistently or not at all, in prose. This document defines a YANG extension statement, "csc:comparability-scope", a four-value scope lattice, and a compatibility rule that lets a schema-aware tool statically detect an illegal aggregation across incomparable scopes, without waiting for it to happen at a collector. 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 1 March 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. Table of Contents 1. Introduction 2. The Gap, With a Concrete Instance 3. Terminology and the Scope Lattice 4. The comparability-scope Extension 5. The Compatibility Rule 6. Applying the Extension: draft-ietf-rtgwg-qos-model 7. Relationship to Existing Work 8. Tooling Implications 9. IANA Considerations 10. Security Considerations 11. References 11.1. Normative References 11.2. Informative References Author's Address 1. Introduction YANG (RFC 7950) gives a module author complete freedom to describe a counter's encoding -- its type, range, and units -- but no language construct to describe the counter's comparability: the set of other counters, on other nodes or in other subtrees, whose value can be meaningfully compared, summed, or differenced against it. That determination is left to prose in the module's description statements, if it is made at all. This is not a defect in any single module; it is a gap in the language every module author who defines a measured value has to independently fill in or, more commonly, silently skip. This document does not propose a new telemetry export mechanism. It proposes a small, reusable piece of the YANG language itself: a statement a module can attach to any leaf or leaf-list that represents a measured value, declaring which of four scopes that value's uniqueness and comparability holds over, so that a receiver, or better, a schema-aware tool running before any bytes are exported, can determine whether an aggregation is valid. 2. The Gap, With a Concrete Instance [I-D.ietf-rtgwg-qos-model] defines YANG models for Quality of Service in IP networks. Its per-interface QoS counters (Section 4.4) are anchored under /if:interfaces/if:interface, with no VRF or VPN awareness, and the uniqueness scope of the counter "name" field is not stated anywhere in the module. Two VRFs configured on the same physical interface can produce identically-named counters, and nothing in the schema, or in prose, tells a collector whether summing them is meaningful or a double-count. This is one instance of a pattern already documented six times independently across five other working groups in [I-D.dikshit-nmop-telemetry-identifier-scoping]: a Path Segment Identifier, a FlowMonID and Period Number, an optional flow-mon-id leaf, a percentile computation method, and VTEP MTU state all share the same shape of gap. That document proposes prose requirements for future documents defining exported identifiers. This document takes the complementary, lower-level step: instead of asking each WG to independently write the right paragraph, it gives YANG itself the vocabulary to say it once, in the schema, machine-checkably. 3. Terminology and the Scope Lattice 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. This document defines a total order over four comparability scopes, written narrowest to widest: node-local < domain-local < controller-scoped < global node-local: the value is comparable only to other values read from the same originating node. A value tagged node-local read from two different nodes carries no defined relationship. domain-local: the value is comparable to values from any node within a single stated administrative or protocol domain (an IGP area, a VRF, an SRv6 domain, a BGP Route Distinguisher's scope), identified by a companion domain-id leaf, but not beyond that domain's boundary. controller-scoped: the value is comparable across every node managed by a single controller or orchestration system, for as long as that controller's assignment record for the value is retained, and not beyond a change of controller. global: the value is comparable across every node and every domain, independent of controller or administrative boundary, for the lifetime the defining module states. The order matters for the compatibility rule in Section 5: a scope on the left of "<" is strictly narrower than one on the right, meaning fewer pairs of readings are guaranteed comparable. 4. The comparability-scope Extension This document defines the extension statement below, in a new module "ietf-comparability-scope" (full module text to be supplied in a future revision of this draft; the extension's substatements are specified here to the level needed for review): extension comparability-scope { argument scope-value; description "Attached to a leaf or leaf-list representing a measured or counted value, declares the scope within which two readings of that value are defined to be comparable, per the four-value lattice defined in [this-document] Section 3. The scope-value argument MUST be one of 'node-local', 'domain-local', 'controller-scoped', or 'global'. When the value is 'domain-local', the same node or grouping MUST also carry a leaf identifying the domain, referenced via a 'domain-id-ref' substatement (not detailed further in this early revision)."; } A module author attaches this to a counter leaf exactly as they would attach "units" or "status": leaf dropped-packets { type yang:counter64; csc:comparability-scope "domain-local"; csc:domain-id-ref "../../vrf-name"; description "Packets dropped by this QoS policy."; } 5. The Compatibility Rule A tool, or a receiver, comparing (summing, differencing, or averaging) two readings of a value from two different subtree instances: 1. MUST reject the aggregation if either reading lacks a comparability-scope statement and the aggregation spans more than one node, one controller, or one domain, as applicable. 2. MUST reject the aggregation if the two readings' declared scopes are both domain-local but their domain-id-ref values differ. 3. MAY accept an aggregation across two different scope values only if the narrower of the two scopes is also satisfied by the context of the read (for example, a domain-local reading and a controller-scoped reading MAY be aggregated only within the domain the domain-local reading names). 4. MUST reject an aggregation of two node-local readings from different nodes unconditionally; node-local is, by definition, never comparable across nodes. This is a static, syntactic check: it requires no run-time state beyond what the schema and the domain-id-ref leaf already carry, which is what makes it enforceable by a validator rather than discovered as an operational incident. 6. Applying the Extension: draft-ietf-rtgwg-qos-model Applying comparability-scope to the gap identified in Section 2 requires exactly the leaf annotation shown in Section 4, plus a domain-id-ref pointing at the VRF or VPN identifier already present in the interface's containing hierarchy. No new counter, no new export mechanism, and no change to the counter's wire encoding is required; the fix is confined to the module's own schema. 7. Relationship to Existing Work [RFC8911] and [RFC8912] solve the analogous problem one layer up: for a metric itself (its name, method, and applicability), rather than for a specific exported value's uniqueness scope, IPPM defines a structured Metrics Registry so that a metric's identity is looked up rather than re-described in prose in every document that uses it. This document proposes the same move for value-level comparability, expressed as a YANG language extension rather than as a registry, because the property being declared (a scope over a data-tree instance) is a schema-level fact, not a metric-level fact, and is naturally expressed where the value is defined. [I-D.dikshit-nmop-telemetry-identifier-scoping] proposes textual requirements for documents defining exported identifiers, covering six instances of this same underlying gap. That document and this one are complementary: the textual requirements apply to identifiers exported in non-YANG formats (IPFIX Information Elements, BMP TLVs) where no schema language extension is available, while this document's extension applies specifically to YANG-modeled operational state, where the language itself can carry the answer. 8. Tooling Implications Because the compatibility rule in Section 5 is syntactic, it is checkable by static tooling without executing the aggregation: a pyang or yanglint plugin can walk two subtree instances named in an aggregation expression (for example, in a controller's dashboard configuration or in a YANG-Push filter combining two subscriptions) and reject the combination at configuration time rather than at query time. This document does not specify such a plugin; a reference implementation demonstrating the check against a corpus of existing WG modules, including [I-D.ietf-rtgwg-qos-model] and the six instances in [I-D.dikshit-nmop-telemetry-identifier-scoping], is future work this draft intends to report on in a subsequent revision. 9. IANA Considerations This document defines a new YANG module, "ietf-comparability-scope" (module text to be supplied in a future revision), to be registered in the "YANG Module Names" registry per the procedures of [RFC7950] Section 5. 10. Security Considerations A misdeclared comparability-scope value does not, by itself, create a new protocol vulnerability, but it can cause a monitoring or automated-remediation system to aggregate incomparable values and act on the incorrect result. As telemetry increasingly feeds automated, closed-loop remediation ("agentic" network operations), an incorrectly widened scope claim (for example, a node-local value falsely declared domain-local) becomes a data-integrity concern with an operational blast radius larger than the originating node. Implementations SHOULD treat a comparability-scope statement as immutable configuration state subject to the same integrity protections as the rest of the YANG datastore, and MUST NOT allow it to be widened by any entity other than the module's schema author. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, August 2016. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017. 11.2. Informative References [I-D.ietf-rtgwg-qos-model] "YANG Models for Quality of Service (QoS) in IP networks", Work in Progress. [I-D.dikshit-nmop-telemetry-identifier-scoping] "Scoping and Comparability Requirements for Exported Network Telemetry Identifiers", Work in Progress. [RFC8911] "Metrics Registry Format Definition", RFC 8911. [RFC8912] "IANA Registry for the Registration of RFC 8911 Metrics", RFC 8912. Author's Address Saumya Dikshit Aruba Networks, HPE Email: saumya.dikshit@hpe.com