Network Working Group S. Dikshit Internet-Draft Aruba Networks, HPE Intended status: Standards Track 18 November 2026 Expires: 22 May 2027 A YANG Extension for Declaring the Comparability Scope of Operational State draft-dikshit-netmod-comparability-scope-extension-04 Abstract A value exported from a YANG data tree is often unique only within its parent, for example an entry numbered 0 under two different parents. Once the value is exported without the parent's key, a collector cannot tell whether two such values refer to the same thing, and no collector-side normalization can recover the missing key. YANG (RFC 7950) has no way to state this dependency in the schema. This document defines a YANG extension statement, "csc:comparability-scope", a four-level scope lattice, a compatibility rule, and an export rule, so that the key needed to compare a value travels with it, and a schema-aware tool can detect an invalid comparison before any data is exported. 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 22 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 Problem in One Picture 2.1. Why Collector-Side Normalization Does Not Help 2.2. Beyond a Single Device 3. Terminology and the Scope Lattice 4. The comparability-scope Extension 5. The Compatibility Rule 6. The Export Rule: The Key Travels with the Value 7. Further Observations 7.1. Measurement-Method Scope in draft-ietf-rtgwg-qos-model 7.2. Known Limitations of domain-id-ref 8. Relationship to Existing Work 9. Tooling Implications 10. IANA Considerations 11. Security Considerations 12. References 12.1. Normative References 12.2. Informative References Appendix A. Worked Example: SR Policy Candidate Paths (RFC 9256) A.1. The Observation A.2. Applying the Extension A.3. Instance Data, Before and After Appendix B. Changes Between Revisions Author's Address 1. Introduction YANG [RFC7950] lets a module author state a value's type, range, and units. It has no construct to state the value's comparability: which other readings of the value, from other subtrees or other nodes, it can be meaningfully compared, summed, or differenced against. Today this is left to description prose, if it is stated at all. This document does not propose a new telemetry export mechanism. It proposes one small, reusable YANG statement that a module can attach to any leaf or leaf-list representing a measured or identifying value, declaring the scope over which that value is unique and comparable. 2. The Problem in One Picture Consider a list of parents, each holding a list of children whose key restarts at 0 under every parent. This is common and valid YANG. Figure 1 shows what happens when only the child subtree is exported. One device +-------------------------------+ | parent "A" | | +-- child id=0 value=7 | | parent "B" | | +-- child id=0 value=9 | +-------------------------------+ | | export the child only | (flat list, filtered YANG-Push, | database row, ...) v Collector receives: { "id": 0, "value": 7 } { "id": 0, "value": 9 } Same child, or two different ones? It cannot tell. Figure 1: The parent key is lost on export The parent key is what made "id=0" unique. Nothing in the schema says so, nothing requires the parent key to be exported with the child, and nothing lets a tool catch the omission before a collector merges, sums, or overwrites the two readings. Figure 2 shows the same export after the extension defined in Section 4 is applied to the "id" leaf. Schema (declared once): leaf id { csc:comparability-scope "domain-local"; csc:domain-id-ref "../../name"; // the parent key } Collector receives: { "parent": "A", "id": 0, "value": 7 } { "parent": "B", "id": 0, "value": 9 } Different parent -> never merged. Figure 2: The scope key travels with the value Appendix A shows the same pattern in a deployed protocol: the candidate paths of a Segment Routing Policy [RFC9256]. 2.1. Why Collector-Side Normalization Does Not Help Mediation between a device model and a canonical model (the classic EMS-to-NMS transformation) fixes representation: names, units, and structure. It cannot add a key that was never exported. In Figure 1 both records are already normalized; what is missing is not a format but a fact. A collector that reads the full tree from one live device can sometimes rebuild the parent context itself, but only if the module nests the child under its parent and the export keeps that nesting. A flat list, a subscription filtered down to the child leaf, or a stored record does not. 2.2. Beyond a Single Device Figure 1 needs only one device. The same pattern appears across devices under one controller, and across domains under separate administration, which is why Section 3 defines four scope levels rather than one. [I-D.dikshit-nmop-telemetry-identifier-scoping] records six independent instances of this pattern across five working groups, each currently addressed by its own prose. That document proposes textual requirements for exported identifiers in non-YANG formats. This document takes the complementary step for YANG-modeled data: it lets the schema state the requirement once, in a machine-checkable form. 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 [RFC2119] [RFC8174] 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: narrowest widest node-local < domain-local < controller-scoped < global | | | | one node one stated one controller everywhere domain or or orchestrator parent Figure 3: The scope lattice node-local: the value is comparable only to other values read from the same originating node. A node-local value read from two different nodes carries no defined relationship. domain-local: the value is comparable to values within a single stated domain or parent context (for example an enclosing list entry, an IGP area, a VRF, or a BGP Route Distinguisher's scope), identified by a companion leaf named by domain-id-ref, but not beyond that context. 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. A scope to the left of "<" is strictly narrower than one to 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". The full module text will be supplied in a future revision; the extension is 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, counted, or identifying value, declares the scope within which two readings of that value are comparable, per the four-value lattice in Section 3 of [this-document]. The scope-value argument MUST be one of 'node-local', 'domain-local', 'controller-scoped', or 'global'. When the value is 'domain-local', a 'domain-id-ref' substatement MUST name the leaf identifying the domain."; } A module author attaches it to a leaf exactly as they would attach "units" or "status". Using the structure of Figure 1: list parent { key name; leaf name { type string; } list child { key id; leaf id { type uint32; csc:comparability-scope "domain-local"; csc:domain-id-ref "../../name"; description "Unique only within the enclosing parent."; } leaf value { type uint64; } } } 5. The Compatibility Rule A tool or receiver comparing (summing, differencing, or averaging) two readings of a value from two different subtree instances: 1. MUST reject the comparison if either reading lacks a comparability-scope statement and the comparison spans more than one node, one controller, or one domain, as applicable. 2. MUST reject the comparison if both readings are domain-local and their domain-id-ref values differ. 3. MAY accept a comparison across two different scope values only if the narrower scope is also satisfied by the context of the read (for example, a domain-local reading and a controller-scoped reading MAY be compared only within the domain the domain-local reading names). 4. MUST reject a comparison of two node-local readings from different nodes. This is a static check: it needs no run-time state beyond what the schema and the domain-id-ref leaf already carry, so it can be enforced by a validator rather than discovered as an operational incident. 6. The Export Rule: The Key Travels with the Value The compatibility rule in Section 5 only works if the leaf named by domain-id-ref reaches the receiver. This document therefore proposes the following rule; whether it is normative or advisory is an open question for the working group. When a leaf carrying comparability-scope "domain-local" is included in exported data, for example in a YANG-Push [RFC8641] update, a filtered retrieval, or a flattened export, the leaf named by its domain-id-ref SHOULD be included in the same exported data. A publisher or tool that builds a subscription filter selecting a domain-local leaf SHOULD add the referenced leaf to the filter automatically. 7. Further Observations 7.1. 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 gauge64 with units bits-per-second and described as "Rate of average data flow through a classifier." The averaging window and computation method are left to the implementation, as is usual for gauge64 [RFC6991]. Two implementations may use different windows, for example one second and five minutes, and produce values that look comparable but are not. This observation has the same shape as Section 2: a value is exported with no machine-checkable statement of when it may be compared to another reading. It is, however, about measurement method rather than administrative or topological scope, which is what the lattice in Section 3 expresses. This document does not extend the lattice to cover it, and records it as a candidate for a separate extension or future revision. 7.2. Known Limitations of domain-id-ref First, the compatibility rule establishes that two domain-local readings are incomparable if their domain-id-ref values differ, but it cannot establish that a domain-id-ref value is unique across every context in which it is used. If the referenced identifier comes from a namespace that is not collision-free across the boundaries in scope, for example a private Autonomous System Number reused by two independently operated networks sharing one collector, two unrelated domains could be wrongly treated as comparable. Module authors SHOULD reference an identifier that is unique across every boundary the comparison is expected to span. Second, domain-id-ref is a pure equality test. It cannot express that two different values refer, over time, to the same domain, for example after an Autonomous System renumbering or merger. Domain identity succession is not addressed by this document and is a candidate for future work. Third, widening a value's declared scope, for example from node-local to domain-local, changes which comparisons are valid. Under the general rule in [RFC8407] such a change is not backward-compatible. A future revision will state this explicitly in the extension definition in Section 4. Finally, a module author can point domain-id-ref at an identifier that already exists for an operational reason (for example a BGP neighbor's Autonomous System Number, which the protocol cannot work without), or introduce a new leaf whose only purpose is to identify the domain. The former is RECOMMENDED where available: an error in it is caught by the protocol that depends on it. A single-purpose identifier has no such independent check, and an operator error in it may persist unnoticed. If one is used, the module SHOULD document that its correctness depends entirely on operator configuration. 8. Relationship to Existing Work [RFC8343] defines a mandatory "discontinuity-time" leaf because a plain counter64 does not say whether it has been reset. That leaf answers one narrow, temporal case of the question this document generalizes: when is a reading comparable to another reading. It was not intended to cover the administrative or topological cases in Section 2, nor the averaging-window case in Section 7.1. This document proposes doing once, in the language, what RFC 8343 did by hand for one counter family. [RFC8911] and [RFC8912] address the analogous question one layer up, for a metric's name, method, and applicability, through a registry. This document addresses value-level comparability as a YANG extension rather than a registry, because the property being declared, a scope over a data-tree instance, is a schema-level fact and is naturally stated where the value is defined. [I-D.dikshit-nmop-telemetry-identifier-scoping] and this document are complementary: the former gives textual requirements for identifiers exported in non-YANG formats (IPFIX Information Elements, BMP TLVs), and this document gives YANG-modeled data a language-level way to carry the same answer. 9. Tooling Implications Because the compatibility rule is static, it can be checked without executing the comparison. A pyang or yanglint plugin can inspect two subtrees named in an aggregation expression (for example in a dashboard configuration, or in a YANG-Push filter combining two subscriptions) and reject the combination at configuration time. The same plugin can check the export rule in Section 6 against a subscription filter. This document does not specify such a plugin; a reference implementation tested against existing WG modules, including the example in Appendix A, is future work. Enforcement does not need a bespoke algorithm. An implementation MAY partition readings by their domain-id-ref value before any aggregation, treating it as an ordinary grouping key, so that readings in different partitions are never combined. This is the grouped aggregation already supported by most collection and storage systems. 10. 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. 11. Security Considerations A misdeclared comparability-scope value does not by itself create a protocol vulnerability, but it can cause a monitoring or automated-remediation system to aggregate incomparable values and act on the wrong result. As telemetry increasingly drives closed-loop automation, an incorrectly widened scope (for example, a node-local value declared domain-local) becomes a data-integrity concern with an impact beyond the originating node. Implementations SHOULD treat a comparability-scope statement as subject to the same integrity protections as the rest of the schema, and MUST NOT allow it to be widened by any entity other than the module's author. 12. References 12.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. 12.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. [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, September 2019. [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. Worked Example: SR Policy Candidate Paths (RFC 9256) A.1. The Observation [RFC9256] identifies a candidate path of an SR Policy by the tuple . For a candidate path provisioned by configuration, Section 2.5 gives the Discriminator a default value of 0, and Section 2.4 gives the Originator (an pair) a default of 0 for both parts. Two unrelated configured candidate paths can therefore carry the identical tuple. Section 2.6 states that this tuple identifies a candidate path only "in the context of a single SR Policy", and that an SR Policy is itself identified by . This is exactly the parent/child pattern of Figure 1: the SR Policy is the parent, and the candidate-path tuple is the child key. One headend serving two SR Policies is enough to produce two identical tuples on a single device. A.2. Applying the Extension The annotation follows Section 4, with domain-id-ref pointing at the enclosing SR Policy's key: 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 within the same enclosing SR Policy."; } No new counter, no new export mechanism, and no change to the Discriminator's encoding in RFC 9256 is required; the change is confined to the exporting module's schema. A.3. Instance Data, Before and After Using the JSON encoding of [RFC7951], a module exporting per-candidate-path state without the parent key carries: { "example-sr-policy-state:candidate-paths": [ { "protocol-origin": 20, "originator": 0, "discriminator": 0 }, { "protocol-origin": 20, "originator": 0, "discriminator": 0 } ] } One entry belongs to an SR Policy with Color 100 and Endpoint P, the other to an unrelated SR Policy with Color 200 and Endpoint Q. The two entries are byte-identical. With the extension applied and the export rule of Section 6 followed, the same entries are: { "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 } ] } The comparability-scope and domain-id-ref statements are schema facts, declared once and never repeated in instance data. A tool that has loaded the module sees that the two sr-policy-key values differ and, by rule 2 of Section 5, does not treat the two discriminator readings as the same candidate path. Appendix B. Changes Between Revisions From -03 to -04 (restructuring for readability; the mechanism is unchanged except for the new Section 6): * Replaced the domain-specific example in Section 2 with a short, abstract parent/child example and two figures. Moved the SR Policy (RFC 9256) example, previously Sections 2, 6.1 and 6.3, to Appendix A. * Added Section 2.1, explaining why collector-side normalization (EMS-to-NMS mediation) does not recover a key that was never exported, and Section 2.2 on scope beyond a single device. * Added Section 6, an export rule proposing that the leaf named by domain-id-ref be exported together with the value it scopes, including in filtered YANG-Push subscriptions. Its normative strength is an open question for the WG. * Added a figure for the scope lattice in Section 3, and an abstract YANG example in Section 4. * Shortened the Abstract and Introduction; moved the measurement-method observation and domain-id-ref limitations under Section 7. No technical change to the lattice or the compatibility rule. From -02 to -03: * Added a worked before-and-after example of published instance data (now Appendix A.3). * Added limitations of domain-id-ref: identifier uniqueness and domain identity succession (now Section 7.2). * Added a note on the forward compatibility of the comparability-scope argument value, with reference to [RFC8407]. * Added guidance preferring an existing, operationally load-bearing identifier for domain-id-ref. * Added a note that the compatibility rule can be enforced as a grouped aggregation on the domain-id-ref value. Author's Address Saumya Dikshit Aruba Networks, HPE Email: saumya.dikshit@hpe.com