Operations and Management Area Working Group A. Méndez
Internet-Draft D. López
Intended status: Standards Track Telefonica
Expires: 25 April 2027 22 October 2026
Normalized Representation of YANG Data for Equivalence Evaluation
draft-mendez-opsawg-yang-normalization-00
Abstract
This document defines a normalization procedure for YANG-modeled
information. The procedure enables different serialized
representations conveying equivalent information to produce the same
normalized representation independently of the input encoding and
applicable representation conventions. The normalized representation
is intended to support comparison, hashing, integrity verification,
provenance, and other procedures that require consistent
representation of equivalent YANG-modeled information.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at https://ana-
mp26.github.io/yang-state-normalization/draft-mendez-opsawg-yang-
normalization.html. Status information for this document may be
found at https://datatracker.ietf.org/doc/draft-mendez-opsawg-yang-
normalization/.
Discussion of this document takes place on the Operations and
Management Area Working Group Working Group mailing list
(mailto:opsawg@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/opsawg/. Subscribe at
https://www.ietf.org/mailman/listinfo/opsawg/.
Source for this draft and an issue tracker can be found at
https://github.com/ana-mp26/yang-state-normalization.
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/.
Méndez & López Expires 25 April 2027 [Page 1]
Internet-Draft yang-normalization October 2026
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 25 April 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. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Operational Use Cases . . . . . . . . . . . . . . . . . . 5
4. Normalization Procedure . . . . . . . . . . . . . . . . . . . 6
4.1. Abstract Syntax Tree . . . . . . . . . . . . . . . . . . 6
4.2. Tree Construction . . . . . . . . . . . . . . . . . . . . 7
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Relationship to Existing Work . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
9. Implementation status . . . . . . . . . . . . . . . . . . . . 12
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
10.1. Normative References . . . . . . . . . . . . . . . . . . 12
10.2. Informative References . . . . . . . . . . . . . . . . . 12
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
YANG is widely used to model configuration data, operational state,
notifications, and other information exchanged between network
management systems.
Méndez & López Expires 25 April 2027 [Page 2]
Internet-Draft yang-normalization October 2026
Data modeled using YANG can be represented through different
encodings, including XML, JSON, and CBOR. Furthermore, equivalent
YANG-modeled information may be serialized differently by distinct
implementations due to representation-specific conventions, ordering
choices, or encoding mechanisms.
These differences make it difficult to determine whether two
representations convey the same information. As a result, operations
such as datastore comparison, data deduplication, fingerprint
generation, integrity verification, provenance processing, and
message-broker compaction often depend on representation-specific
artifacts rather than on the underlying information itself.
Existing canonicalization mechanisms operate at the encoding level.
For example, XML, JSON, and CBOR provide independent procedures for
producing deterministic encodings of individual documents. However,
these mechanisms do not address the broader problem of obtaining a
common representation across different encodings.
This document defines a normalization procedure for YANG-modeled
information that produces a deterministic representation independent
of the original encoding. The procedure enables equivalent YANG-
modeled information to converge into the same normalized
representation, providing a stable basis for comparison, fingerprint
generation, integrity verification, and other operational uses.
1.1. Scope
This document focuses on representation equivalence of YANG-modeled
data. The procedure defined in this document is intended to identify
when different serialized representations convey equivalent
information. Semantic equivalence is outside the scope of this
document.
2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
* Representation: A concrete serialized einstance of YANG-modeled
data. Examples include XML, JSON, and CBOR encodings conveying
the same underlying information.
* Normalized Representation: A deterministic representation
generated by the normalization procedure defined in this document.
Méndez & López Expires 25 April 2027 [Page 3]
Internet-Draft yang-normalization October 2026
* Representation Equivalence: Two representations are
representation-equivalent when they produce identical normalized
representations.
* Fingerprint: A cryptographic digest calculated from a normalized
representation.
* Schema-Independent Normalization: A normalization procedure that
does not require access to the corresponding YANG schema during
processing.
* Semantic Equivalence: The property whereby two representations
correspond to the same YANG-modeled information after considering
all schema-dependent semantics.
3. Problem Statement
YANG-modeled data can be represented using different encodings,
including XML [RFC7950], JSON [RFC7951], and CBOR [RFC9254].
Existing canonicalization mechanisms operate within a particular
encoding and produce deterministic representations of individual
documents. Examples include XML Canonicalization (XML-C14N), the
JSON Canonicalization Scheme (JCS) [RFC8785], and the deterministic
encoding rules defined for CBOR [RFC8949].
These mechanisms enable a representation expressed using a particular
encoding to be transformed into a deterministic byte sequence.
However, they do not provide a common representation across different
encodings, nor do they necessarily address all representation
variations that may arise from encoding rules or implementation
choices.
Ordering is one possible source of such variation. These differences
may arise from implementation choices, internal datastore
representations, module augmentations, or serialization procedures.
For example, one implementation may produce:
while another implementation may produce:
Méndez & López Expires 25 April 2027 [Page 4]
Internet-Draft yang-normalization October 2026
If the order of these nodes is not semantically significant, both
serialized representations convey equivalent information despite
having different element ordering and byte sequences.
As a result, equivalent YANG-modeled information may produce
different serialized representations and therefore different
fingerprints, hashes, or signatures. Direct comparison of serialized
representations cannot reliably determine whether two representations
convey the same information.
A normalization procedure operating above the encoding-specific
representation layer is therefore needed to enable representation-
independent comparison of YANG-modeled data.
3.1. Operational Use Cases
The absence of a representation-independent form of YANG-modeled data
affects several operational scenarios, including:
* *Datastore State Comparison:* Network management systems
frequently compare datastore snapshots obtained from different
devices, controllers, or processing stages. Equivalent YANG-
modeled data represented through different encodings or ordering
conventions may appear different when compared directly, despite
conveying the same information.
* *Message Broker Applications:* YANG-modeled information is
increasingly exchanged through message broker infrastructures and
data distribution systems. Consistent representation of
equivalent information can support operations such as message
deduplication, topic compaction, change detection, and content
synchronization.
* *Data Synchronization and Replication:* Operational environments
frequently exchange YANG-modeled data between multiple systems. A
deterministic normalized representation can simplify data
comparison, synchronization procedures, and consistency
verification across distributed environments.
Méndez & López Expires 25 April 2027 [Page 5]
Internet-Draft yang-normalization October 2026
* *Data Deduplication:* Storage and processing systems may benefit
from the ability to identify equivalent information independently
of the original representation. A normalized representation
provides a stable basis for content identification and
deduplication.
* *Provenance and Integrity Verification:* Where stable and
deterministic representations are required to generate
reproducible fingerprints, hashes, and signatures and provenance
records.
4. Normalization Procedure
The normalization procedure takes a serialized YANG data document as
input and produces a deterministic normalized representation.
4.1. Abstract Syntax Tree
The procedure parses the input document according to its encoding and
constructs an abstract syntax tree (AST) of the serialized data
representation. Abstract syntax trees are described in Section 1.1
of [Harper2016].
For the purposes of this document, the AST does not represent every
detail of the concrete input syntax. It preserves only the
structural and content-related information required by the
normalization procedure. This information consists of node
identifiers, textual values, hierarchical relationships, and node
multiplicity.
The AST provides a common, encoding-independent representation of
serialized YANG-modeled data. It is constructed without consulting a
YANG schema. Consequently, it represents the observable structure
and textual values exposed by the serialized document but does not
resolve schema-dependent YANG semantics.
The tree contains a synthetic document root. The synthetic root
provides a common container for the top-level nodes of the serialized
input document. It does not correspond to a YANG data node and uses
an empty identifier reserved for this purpose.
Each node below the synthetic document root has a non-empty
identifier and is one of the following:
* a leaf node, which contains a textual value and has no child
nodes;
Méndez & López Expires 25 April 2027 [Page 6]
Internet-Draft yang-normalization October 2026
* an inner node, which contains zero or more child nodes and has no
textual value.
A node cannot contain both a textual value and child nodes. The
abstract syntax tree preserves node multiplicity. Multiple nodes may
have the same identifier, and identical nodes are not implicitly
removed.
4.2. Tree Construction
The input document is first parsed according to the syntax and
structure of the selected encoding. Malformed input or an
unsupported document structure causes normalization to fail.
The procedure creates the synthetic document root and adds the top-
level data nodes obtained from the serialized document as its
children.
The following conceptual rules are then applied:
1. An XML element, JSON object member, or CBOR map entry that
contains nested data is represented as an inner node.
2. An XML element, JSON object member, or CBOR map entry that
contains a scalar value is represented as a leaf node.
3. The name exposed by the input encoding is used to derive the node
identifier.
4. A sequence of data items is represented as sibling nodes having
the identifier associated with the sequence. The sequence itself
does not produce an additional node.
5. An empty sequence produces no nodes.
6. An empty structured value is represented as an inner node having
no children.
7. The encoding-specific representation of the YANG empty type is
represented as a leaf having an empty textual value.
8. Scalar values are converted to textual form.
9. The same construction rules are applied to every nested data item
until the complete abstract data tree has been constructed.
Méndez & López Expires 25 April 2027 [Page 7]
Internet-Draft yang-normalization October 2026
These rules are recursive in definition. An implementation is not
required to use recursion internally, provided that it produces the
same abstract data tree.
XML attributes are not represented in the abstract data tree defined
by this version, the treatment of attributes is TBD. XML elements
and their textual content are processed as data-tree nodes and
values, respectively.
*TBD:* Specify the treatment of YANG metadata annotations, namespace-
qualified identifiers, namespace declarations, format-specific
constructs, and malformed or unsupported input structures. This
initial version focuses on the fundamental normalization procedure.
The treatment of schema-specific semantics, including default values,
identityref and leafref resolution, and ordered-by-user semantics, is
TBD. Further versions of this document are expected to determine
whether these aspects require specific normalization rules or are
inherently addressed by the general normalization procedure. Where
specific handling is required to preserve equivalence, the
corresponding rules will be incorporated into the normalization
procedure.
The same YANG-modeled information MUST produce the same normalized
representation regardless of the original serialization format.
Serialized YANG Data Document
XML / JSON / CBOR
|
v
Encoding-Specific Parsing
|
v
Abstract Data Tree
|
v
Identifier and Value Processing
|
v
Deterministic Subtree Encoding
|
v
Child Node Sorting
|
v
Normalized Byte Representation
|
v
Comparison / Hashing / Signing /...
Méndez & López Expires 25 April 2027 [Page 8]
Internet-Draft yang-normalization October 2026
5. Examples
This section illustrates how equivalent YANG-modeled data represented
using different serialization formats and encodings can produce the
same normalized representation. The following XML and JSON
representations examples are based on the interface data model
originally defined in [RFC7223] and convey equivalent information.
eth0
iana-if-type:ethernetCsmacd
false
eth1
iana-if-type:ethernetCsmacd
true
true
eth1.10
iana-if-type:l2vlan
true
eth1
10
lo1
iana-if-type:softwareLoopback
true
Méndez & López Expires 25 April 2027 [Page 9]
Internet-Draft yang-normalization October 2026
{
"ietf-interfaces:interfaces": {
"interface": [
{
"enabled": true,
"name": "lo1",
"type": "iana-if-type:softwareLoopback"
},
{
"vlan:vlan-id": 10,
"enabled": true,
"type": "iana-if-type:l2vlan",
"vlan:base-interface": "eth1",
"name": "eth1.10"
},
{
"enabled": false,
"type": "iana-if-type:ethernetCsmacd",
"name": "eth0"
},
{
"vlan:vlan-tagging": true,
"name": "eth1",
"enabled": true,
"type": "iana-if-type:ethernetCsmacd"
}
]
}
}
The following non-normative textual tree illustrates the intended
outcome: equivalent XML, JSON, and CBOR representations are expected
to produce the same normalized representation.
Méndez & López Expires 25 April 2027 [Page 10]
Internet-Draft yang-normalization October 2026
interfaces
├─ interface
│ ├─ enabled = true
│ ├─ name = lo1
│ └─ type = iana-if-type:softwareLoopback
├─ interface
│ ├─ enabled = false
│ ├─ name = eth0
│ └─ type = iana-if-type:ethernetCsmacd
├─ interface
│ ├─ enabled = true
│ ├─ name = eth1
│ ├─ type = iana-if-type:ethernetCsmacd
│ └─ vlan-tagging = true
└─ interface
├─ base-interface = eth1
├─ enabled = true
├─ name = eth1.10
├─ type = iana-if-type:l2vlan
└─ vlan-id = 10
6. Relationship to Existing Work
The normalization procedure defined in this document is intended to
complement existing efforts related to the processing,
identification, and distribution of YANG-modeled information.
The YANG provenance mechanisms defined in
[I-D.ietf-opsawg-yang-provenance] operate on serialized
representations of YANG data and can benefit from a stable,
representation-independent normalization procedure capable of
producing equivalent representations across different serialization
formats.
Similarly, work related to message broker identification and key
generation for YANG-modeled information, such as
[I-D.ietf-nmop-yang-message-broker-message-key], may benefit from a
normalization procedure that produces stable representations for
equivalent information independently of their original encoding.
This document does not modify or replace such mechanisms. Instead,
it provides a potential foundation that can be used by higher-level
procedures requiring consistent representation of equivalent YANG-
modeled information.
Méndez & López Expires 25 April 2027 [Page 11]
Internet-Draft yang-normalization October 2026
7. Security Considerations
The normalization procedure defined in this document is intended to
provide a deterministic representation of YANG-modeled data. It does
not, by itself, provide integrity, authenticity, confidentiality, or
provenance guarantees.
Security properties may be obtained by applying appropriate
mechanisms, such as cryptographic hash functions, digital signatures,
or provenance procedures, to the resulting normalized representation.
Implementations relying on the normalized representation for
integrity verification or provenance applications MUST use
cryptographically secure algorithms appropriate for the intended use
case. Incorrect normalization procedures may result in different
representations producing the same normalized output or in equivalent
information producing different normalized representations. Such
situations may negatively affect comparison, fingerprint generation,
and verification procedures.
8. IANA Considerations
This document has no IANA actions.
9. Implementation status
An open-source reference implementation, written in Java, is
available at https://github.com/tefiros/yang-data-normalization.
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
10.2. Informative References
[Harper2016]
Harper, R., "Practical Foundations for Programming
Languages", Cambridge University Press, ISBN
978-1-107-15030-0, Second Edition , 2016.
Méndez & López Expires 25 April 2027 [Page 12]
Internet-Draft yang-normalization October 2026
[I-D.ietf-nmop-yang-message-broker-message-key]
Graf, T., Elhassany, A., Feng, A. H., Claise, B., and P.
Lucente, "YANG Message Keys for Message Broker
Integration", Work in Progress, Internet-Draft, draft-
ietf-nmop-yang-message-broker-message-key-02, 2 July 2026,
.
[I-D.ietf-opsawg-yang-provenance]
Lopez, D., Pastor, A., Feng, A. H., Pérez, A. M., and H.
Birkholz, "Applying COSE Signatures for YANG Data
Provenance", Work in Progress, Internet-Draft, draft-ietf-
opsawg-yang-provenance-07, 6 July 2026,
.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016,
.
[RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON
Canonicalization Scheme (JCS)", RFC 8785,
DOI 10.17487/RFC8785, June 2020,
.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
.
[RFC9254] Veillette, M., Ed., Petrov, I., Ed., Pelov, A., Bormann,
C., and M. Richardson, "Encoding of Data Modeled with YANG
in the Concise Binary Object Representation (CBOR)",
RFC 9254, DOI 10.17487/RFC9254, July 2022,
.
Méndez & López Expires 25 April 2027 [Page 13]
Internet-Draft yang-normalization October 2026
Acknowledgments
This document is based on work partially funded by the EU Horizon
Europe projects CYBERNEMO (grant 101168182) and 3C4AI (grant
101298630).
Authors' Addresses
Ana Méndez
Telefonica
Email: ana.mendezperez@telefonica.com
Diego López
Telefonica
Email: diego.r.lopez@telefonica.com
Méndez & López Expires 25 April 2027 [Page 14]