Network Working Group S. Dikshit Internet-Draft Aruba Networks, HPE Intended status: Standards Track 16 November 2026 Expires: 16 May 2027 A YANG Extension for Declaring the Comparability Scope of Operational State draft-dikshit-netmod-comparability-scope-extension-03 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 administrative or topological 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. A related but distinct axis, the measurement window or method over which a rate or average value was computed, is identified as a further gap this document's mechanism does not itself close, and is reported separately as a candidate for future work. 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 16 May 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 6.1. SR Policy Candidate Paths (RFC 9256) 6.2. A Related, Unsolved Axis: Measurement-Method Scope in draft-ietf-rtgwg-qos-model 6.3. A Worked Example: Published Instance Data, Before and After 6.4. Known Limitations of domain-id-ref 7. Relationship to Existing Work 8. Tooling Implications 9. IANA Considerations 10. Security Considerations 11. References 11.1. Normative References 11.2. Informative References Appendix A. Changes Between Revisions 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. A second, distinct axis of comparability, how long a rate or average value's own measurement window must match another reading's before the two are comparable, is identified separately in Section 6.2 as a related gap this mechanism does not itself close. 2. The Gap, With a Concrete Instance [RFC9256] defines the architecture for Segment Routing Policies. A candidate path of an SR Policy is identified by the tuple . Section 2.5 states that when a candidate path is provisioned by configuration, its Discriminator "is specific to the implementation's configuration model", with a default value of 0. Section 2.4 states that, in the same configuration-provisioned case, the Originator, itself an tuple, also has "the default value" of 0 "for both AS and node address". Two completely unrelated candidate paths, configured on two different headends, can therefore carry the identical tuple. Section 2.6 is explicit that this tuple only identifies a candidate path "in the context of a single SR Policy", and that an SR Policy is itself identified by . A YANG module exporting per-candidate-path counters that carries the bare tuple without also carrying its enclosing SR Policy context is, by RFC 9256's own definition, not exporting enough information for two readings to be safely compared across headends. Nothing requires such a module to carry that enclosing context next to the counter it scopes, nothing declares the requirement in the schema, and nothing lets a validator catch the omission before a collector aggregates two unrelated headends' counters under a coincidentally matching Discriminator. This is not an unknowable fact; RFC 9256 itself defines exactly the enclosing context needed to disambiguate it. The gap is narrower and more precise than "the scope cannot be known": it is that the schema does not require the context to be carried, declared, or checked alongside the value it scopes, so the invalid aggregation is exactly as easy to write in YANG as the valid one. 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 discriminator { type uint32; csc:comparability-scope "domain-local"; csc:domain-id-ref "../../sr-policy-key"; description "Discriminator of this candidate path, per RFC 9256 Section 2.5. Comparable only to Discriminator values read within the same enclosing SR 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 6.1. SR Policy Candidate Paths (RFC 9256) Applying comparability-scope to the gap identified in Section 2 requires exactly the leaf annotation shown in Section 4, with domain-id-ref pointing at the enclosing SR Policy's own key, , already present in the containing hierarchy of any YANG module exporting per-candidate-path state. No new counter, no new export mechanism, and no change to the Discriminator's wire encoding in RFC 9256 itself is required; the fix is confined to the exporting module's own schema. 6.2. A Related, Unsolved Axis: Measurement-Method Scope in draft-ietf-rtgwg-qos-model [I-D.ietf-rtgwg-qos-model] Section 4.4 defines a "classified-rate" leaf, typed as a bare gauge64 with units bits-per-second, described only as "Rate of average data flow through a classifier." Neither the module nor the gauge64 typedef itself [RFC6991] states or constrains the averaging window, sampling interval, or computation method the rate was derived over. Two implementations of the same module may legitimately use different windows, for example one second against five minutes, and produce numerically comparable-looking values that are not actually comparable. This is a real gap, and it shares the same shape as Section 2's: a value is exported with no machine-checkable statement of the condition under which it may be compared to another reading. It is not, however, an instance of administrative or topological scope, which is what the four-value lattice in Section 3 is built to express, and this document does not propose extending that lattice to cover it. It is reported here as a genuine, separate finding, worth its own extension statement or a future revision of this document, rather than folded into the current mechanism simply because it resembles it on the surface. 6.3. A Worked Example: Published Instance Data, Before and After The following shows the practical effect of applying comparability-scope to the gap in Section 2, using example instance data in the JSON encoding defined by [RFC7951]. Before the extension is applied, a module exporting per-candidate-path state typically carries only the bare identification tuple, with no indication of the enclosing SR Policy it belongs to: { "example-sr-policy-state:candidate-paths": [ { "protocol-origin": 20, "originator": 0, "discriminator": 0 }, { "protocol-origin": 20, "originator": 0, "discriminator": 0 } ] } These two entries, one exported by Headend A for an SR Policy with Color 100 and Endpoint P, the other by Headend B for an unrelated SR Policy with Color 200 and Endpoint Q, are byte- identical. Nothing in this instance data distinguishes them. After the module author applies comparability-scope as shown in Section 4, with domain-id-ref pointing at a sibling leaf already carrying the enclosing SR Policy's own key, the same two entries are exported as follows: { "example-sr-policy-state:candidate-paths": [ { "sr-policy-key": "HeadendA,Color100,EndpointP", "protocol-origin": 20, "originator": 0, "discriminator": 0 }, { "sr-policy-key": "HeadendB,Color200,EndpointQ", "protocol-origin": 20, "originator": 0, "discriminator": 0 } ] } Note that comparability-scope and domain-id-ref are themselves schema-level facts, declared once in the YANG module and never repeated in the instance data; a schema-aware tool that has already loaded the module knows, from the schema alone, that discriminator is domain-local and that sr-policy-key is its companion domain identifier. Applying the compatibility rule of Section 5 to the "after" instance data above, the tool observes that the two sr-policy-key values differ and correctly declines to treat the two discriminator readings as referring to the same candidate path, resolving the ambiguity shown in Section 2 without any change to the wire encoding of Discriminator itself. 6.4. Known Limitations of domain-id-ref Two limitations of the mechanism as currently specified are reported here directly, rather than left for a reviewer to discover independently. First, the compatibility rule in Section 5 establishes that two domain-local readings are incomparable if their domain-id-ref values differ, but it does not, and cannot by itself, establish that a given domain-id-ref value is unique across all contexts in which comparability-scope is applied. If the referenced identifier is itself drawn from a namespace that is not guaranteed collision-free across the administrative boundaries in scope, for example a private Autonomous System Number reused by two independently operated networks sharing one collector, two genuinely unrelated domains could be incorrectly treated as comparable. Implementers and module authors SHOULD ensure that any leaf referenced via domain-id-ref is itself drawn from a namespace that is unique across every administrative boundary the comparison is expected to span. Second, the compatibility rule treats domain-id-ref purely as an equality test, with no mechanism for expressing that two distinct domain-id-ref values refer, over time, to the same underlying administrative domain, for example following an Autonomous System renumbering or merger. Data tagged with the domain's former identifier becomes permanently incomparable to data tagged with its new identifier under the current mechanism, even where the underlying domain has not otherwise changed. Expressing domain identity succession is not addressed by this document and is reported here as a candidate for future work, in the same spirit as Section 6.2. A further, related question is the forward compatibility of the comparability-scope argument value itself. [RFC8407] states that a change to a YANG extension's argument value is backward- compatible only if it does not alter the semantics the extension expresses, and recommends that the extension's own definition state explicitly which kinds of changes are, and are not, backward-compatible. Because widening a value's declared scope, for example from node-local to domain-local, directly changes which aggregations become valid, such a change is a non-backward- compatible change under that general rule. A future revision of this document should state this explicitly in the extension definition in Section 4, rather than leaving it to be inferred. A module author applying domain-id-ref has a choice between referencing an identifier that already exists in the module for an unrelated, operationally load-bearing reason (for example, a BGP neighbor's Autonomous System Number, which the protocol itself cannot function without), or introducing a new leaf whose sole purpose is to serve as a domain identifier. The former is RECOMMENDED where a suitable existing identifier is available: an error in that identifier's configuration is independently caught by the protocol mechanism depending on it, keeping the identifier correct as a side effect of ordinary operation. A newly introduced, single-purpose identifier has no such independent check; an operator error in its configuration affects only the comparability-scope mechanism itself, is not otherwise observable, and may persist undetected. Module authors SHOULD prefer the former wherever one exists, and SHOULD document, if the latter is used, that the identifier's correctness depends entirely on operator-configured accuracy with no independent corroborating mechanism. 7. Relationship to Existing Work This is not the first time a counter has needed metadata beyond its type and range to be used correctly. [RFC8343] defines a mandatory "discontinuity-time" leaf for exactly this reason: a plain counter64 carries no information about whether it has been reset, so the base interfaces model had to add a dedicated leaf, by hand, to answer one narrow instance of the same general question this document generalizes, when is a reading of this value actually comparable to another reading of it. That leaf solves the temporal case. It does not, and was never intended to, solve the administrative or topological cases in Section 2. This document proposes doing once, at the language level, what RFC 8343 had to do once, by hand, for a single counter family. The averaging-window gap identified in Section 6.2 is a further, narrower instance again: discontinuity-time states when a counter was last reset; it says nothing about the window over which a derived rate or average was computed, which remains entirely unstated in RFC 6991's gauge64 typedef and in every module, including qos-model, that uses it. [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 a YANG module exporting RFC 9256 candidate-path state 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. Enforcement of the compatibility rule does not require a specialized data structure or a bespoke pairwise comparison algorithm. An implementation MAY instead partition the set of candidate readings by their declared domain-id-ref value before any aggregation operation is attempted, treating that value as an ordinary grouping key; two readings that fall into different partitions are, by construction, never combined. This reduces the compatibility rule to a conventional grouped-aggregation operation already supported by most collection and storage systems, rather than requiring new enforcement logic to be written for each module that adopts the extension. 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. [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, July 2013. [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, August 2016. [RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, March 2018. [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, October 2018. [RFC8911] "Metrics Registry Format Definition", RFC 8911. [RFC8912] "IANA Registry for the Registration of RFC 8911 Metrics", RFC 8912. [RFC9256] Filsfils, C., Talaulikar, K., Ed., Voyer, D., Bogdanov, A., and P. Mattes, "Segment Routing Policy Architecture", RFC 9256, July 2022. Appendix A. Changes Between Revisions From -02 to -03: * Added Section 6.3, a worked example showing the practical, before-and-after effect of the extension on actual published instance data, in response to review feedback that the document, while precise about the schema-level mechanism, did not show what a receiver actually sees on the wire. * Added Section 6.4, reporting two previously-unstated limitations of domain-id-ref directly: that it does not itself guarantee the referenced identifier's uniqueness, and that it has no mechanism for domain identity succession (for example, an Autonomous System renumbering or merger). Both are reported as open, acknowledged gaps rather than resolved in this revision. * Added a note on the forward compatibility of the comparability-scope argument value itself, with reference to [RFC8407]'s general rule for backward-compatible extension changes, identifying a widened scope value as a non-backward- compatible change that a future revision should state explicitly. * Added guidance in Section 6.4 recommending that domain-id-ref reference an existing, operationally load-bearing identifier in preference to a newly introduced, single-purpose one, and explaining why the latter lacks an independent mechanism for catching operator misconfiguration. * Added a note in Section 8 observing that the compatibility rule can be enforced by partitioning candidate readings on their declared domain-id-ref value, a conventional grouped- aggregation operation, rather than requiring bespoke enforcement logic. Author's Address Saumya Dikshit Aruba Networks, HPE Email: saumya.dikshit@hpe.com