Semantic Snapshots for Reliable Post-Change Proof

Introduction to Pre‑Change and Post‑Change Snapshots

Definition and Purpose

A snapshot is an immutable, point‑in‑time capture of a network system’s observable state, such as:

• Full running configuration (gNMI Get or CLI show running-config).
• Model‑driven telemetry export (YANG‑encoded JSON/XML) for interfaces, routing tables, ACLs, QoS, etc.
• Control‑plane dumps (OSPF LSDB, BGP RIB, MAC address table).

Snapshots enable us to answer the operational question:

Did the change produce the intended network state, and are any observed differences solely due to irrelevant formatting or representation noise?

Importance of Normalization and Semantic Diffing

Raw snapshots often contain formatting noise (extra whitespace, reordered optional fields, varying comment styles, different numeric precisions). Comparing snapshots without removing this noise can cause:

• False positives – harmless changes flagged as drift.
• False negatives – real drift hidden by noise.

Normalization transforms each snapshot into a canonical form where semantically equivalent representations become identical. Semantic diffing then compares these canonical forms, focusing on meaningful differences in data‑model instances rather than lexical tokens. The result is a trustworthy verification signal for CI/CD gating, change‑control audits, and closed‑loop automation.

Normalization Techniques

Text Normalization

Applied to the raw byte stream (CLI output, plain‑text configs). Typical steps:

What a graph proves: A stable snapshot_text_normalization_latency_seconds indicates repeatable performance; it does not guarantee semantic equivalence.
Missing signal: If only a pretty‑printed CLI view is available, comment stripping might drop device‑significant annotations.

Data Normalization

Treats the snapshot as a structured document (JSON, XML, protobuf) and applies schema‑aware transformations:

1. Canonical JSON (RFC 8785): lexicographically sort object keys, drop insignificant whitespace, enforce a single number format.
2. XML Canonicalization (C14N): exclusive C14N to remove namespace prefixes, default attributes, and reorder attributes.
3. Protobuf deterministic encoding: use --encode=canonical.
4. Default value insertion: add missing optional fields that have schema‑defined defaults.
5. Numeric precision normalization: round floating‑point numbers to a defined number of significant digits (e.g., 6).

What a graph proves: Rising snapshot_data_canonicalization_errors_total signals schema mismatches (vendor extensions); it does not confirm that the canonical form reflects intended behavior.
Missing signal: Using a YANG version that differs from the device’s firmware can cause false equivalence.

Code Normalization

For snapshots expressed as code (Ansible, Terraform, Python scripts):

• AST parsing – language‑specific parsers (ast for Python, javaparser for Java, go/ast for Go).
• Formatting stripping – discard whitespace, comments, and formatting nodes.
• Identifier renaming (α‑conversion) – consistently rename bound variables (var_0, var_1, …).
• Constant folding – evaluate safe constant expressions (2+2 → 4).
• Dead‑code elimination – optional removal of unreachable branches after constant propagation.

What a graph proves: A histogram of snapshot_ast_node_count shows code‑snapshot complexity; it does not guarantee identical device output.
Missing signal: Runtime‑resolved templating (e.g., Jinja2 loops with external data) cannot be captured without those inputs.

Semantic Diffing Approaches

Token‑Based Diffing

Treats the normalized snapshot as a lexical token sequence and applies Myers’ or Hunt‑Szymanski diff.

Pros: Low overhead (O(N + D)), easy to plug into existing diff/patch.
Cons: Still sensitive to token ordering if normalization missed a canonical order (e.g., ACL entry lists).

What a graph proves: snapshot_token_diff_count spikes may indicate substantive change, but could also stem from residual ordering differences.
Missing signal: Token streams lose hierarchical context, so they cannot distinguish a leaf moved under a different container from a value edit.

Syntax‑Based Diffing

Parses the snapshot into a formal syntax tree (AST, DOM, XML tree) and compares trees using Zhang‑Shasha tree edit distance or ordered/unordered tree diffs.

Ordered tree diff – respects child order (suitable for CLI lines).
Unordered tree diff – treats children as a set (suitable for JSON objects where key order is irrelevant).

What a graph proves: snapshot_tree_edit_distance quantifies the minimal insert/delete/update ops; zero distance signals structural equivalence. It does not prove semantic equivalence if the tree model omits constraints (e.g., leaf value ranges).
Missing signal: Incomplete schema (missing vendor extensions) can cause false equivalence.

Semantic‑Based Diffing

Evaluates meaning according to the underlying data model.

• Value‑based equality – compare leaf values with datatype‑specific comparators (IP prefix equality, range inclusion).
• Constraint‑aware normalization – apply model defaults, range clamping, enumeration canonicalization before diff.
• Semantic hashing – SHA‑256 over a normalized, constraint‑aware representation; equal hashes imply semantic equivalence with high probability.
• Model‑driven equivalence checking – instantiate two data trees with a YANG library (libyang, pyangbind) and use its == operator, which respects YANG identity, ordering, and mandatory/optional leaf handling.

What a graph proves: Gauge snapshot_semantic_diff_present (0 = no difference, 1 = difference) directly answers the operational question when the model is complete and correct. A rising trend signals accumulating drift. It does not guarantee that every semantic difference is actionable (e.g., ever‑increasing counters).
Missing signal: If the model omits operational state (transient hardware error flags), drift in those dimensions will never be detected, yielding false confidence.

Pre‑Change and Post‑Change Snapshot Comparison

Challenges

Strategies for Effective Comparison

1. Canonicalize first, diff second – Apply the full normalization pipeline (text → data → code → semantic) before any diff algorithm.
2. Layered diff – Run a fast token‑based diff to catch obvious changes; if the count is low, follow with syntax‑ or semantic‑based diff for deeper validation.
3. Ignore known‑noise fields – Exclude fields that are expected to vary (interface counters, timestamps) from the diff scope.
4. Version‑aligned models – Ensure the YANG/model used for normalization matches the exact firmware version running on the device.
5. Temporal alignment – Take pre‑ and post‑snapshots as close as possible in time, or use monotonic counters to normalize time‑varying values.
6. Automated gating – Feed the semantic‑diff result (snapshot_semantic_diff_present) into CI/CD pipelines; block promotion on any non‑zero value unless explicitly allowed.

By normalizing aggressively and diffing semantically, teams can trust that a clean diff truly reflects intentional network state changes, eliminating the noise that would otherwise obscure real drift or generate spurious alerts.