[MathiasVDA]

Requested by Mathias · project thread

Plan step 3: version comparison. Stacked on #2 (viewer-mvp).

Core (crates/core/src/diff.rs, report.rs)

• diff(old, new, &DiffOptions) -> SchemaDiff (serde, DIFF_FORMAT = 1, wasm-safe).
• Matching by qualified name, then by kind + local name when the target namespace changed (railML …/3.2 → …/3.3); the namespace map is derived and used to compare references. match_local_names, docs, renames options.
• Added / removed / changed complex and simple types, elements, attributes, groups and attribute groups, with fine-grained changes: base/derivation, abstract/final/block/mixed/nillable, child added/removed/retyped/cardinality (effective, compositors included)/moved/reordered, compositor structure, attributes (added/removed/retyped/use/default/fixed, anyAttribute), enumerations, facets (tightened vs loosened), list/union types, asserts, substitution group heads and members, documentation (both texts). Anonymous types are compared in depth.
• Each change is breaking / non-breaking / info; possible renames (removed + added with near-identical content); a retype to the renamed type is downgraded to non-breaking.
• Summary per kind, namespace and file. Markdown (release notes) and standalone HTML reports.

CLI

schema-explorer diff <old> <new> [-o file] [--format json|md|html] [--strict-namespaces] [--no-docs] [--titles OLD NEW] [--fail-on-breaking]. Each side is files, directories or a bundle; commas join several paths.

Viewer

• "Compare two versions" card on the open page (two drop zones or addresses) and ?bundle=<new>&compare=<old>; share links keep compare.
• Changes overview: counts, namespace change note, tables per kind/namespace/file, list filterable by status, kind, impact, namespace and name (filters in the link), Markdown/HTML/JSON downloads.
• Per-component diff page: change list, old vs new side by side for content model, attributes, base and facets, enumerations and documentation.
• Diagram and content tree marks: added green +, removed red − struck through, changed amber ~, for boxes, lines and arrows; removed children/attributes appear as struck-through lines. Light and dark themes.

Results

• railML 3.2 → 3.3: 169 added, 35 removed, 261 changed; 128 components breaking (217 breaking changes); 108 documentation only; 3 possible renames (e.g. tWeightTons → tWeightTonnes).
• TAF 3.5.1 → current: 9 added, 1 removed, 19 changed; 6 components breaking.

Tests

Hand-written v1/v2 pair in crates/core/tests/data/diff (namespace change included) with 10 unit tests; fixture tests (skipped without SCHEMA_FIXTURES) for railML 3.1→3.2, 3.2→3.3 and TAF.

Known gaps

Identity constraints (key/keyref/unique) are not compared; groups referenced in content models are compared on their own, not expanded; moves between two compositors of the same kind path are not detected.

---

Generated by Claude Code