If you’ve ever managed a DHIS2 instance, you know the “Metadata Headache.”
As a project grows, the behind-the-scenes files that make everything work (the “metadata”) become massive. We’re talking about thousands of lines of complex code that define your clinics and patients. Eventually, you find yourself needing to compare two versions of these files. Maybe you’re moving updates from a test environment to your live system, or perhaps you’re trying to figure out exactly what changed between last month and today.
Until now, this has been a high-stakes game of “Spot the Difference.” Standard computer tools are often too literal; they get tripped up by a single extra space or a list that’s out of order, flagging “errors” that aren’t actually there. For a human, scrolling through these files to manually copy and paste changes is a recipe for accidental system crashes.
At EyeSeeTea, we believe that managing your health data system should be about making informed decisions, not squinting at brackets and commas.
That’s why we built the Metadata Comparator. It’s a smart, visual tool that understands your DHIS2 data the same way you do. Instead of a wall of code, it gives you a clear, side-by-side view where you can simply click to “keep” or “discard” changes.
In this post, we’ll show you how we’ve turned a complex technical bottleneck into a routine task that anyone on your team can handle with confidence.
The challenge: the complexity of DHIS2 metadata version control
Traditional “diff” tools compare text line-by-line. While this works for simple code, it fails for DHIS2 metadata for several reasons:
- Meaningless Mismatches: If a list of options is simply reordered, a standard tool sees it as a total change. Our tool uses ID-based matching, meaning it knows a “Clinic” is the same object regardless of where it sits in the file.
- The “Look but Don’t Touch” Limitation: Most tools show you the differences but don’t help you fix them. You’re left to manually reconstruct a new file, which is where human error creeps in.
- Scaling Walls: Once a file exceeds 10,000 lines, manual review becomes impractical. Small, nested changes deep within the data structure are easily overlooked.
Design principles
We built this tool with three guiding principles:
- User-Centric Control: You shouldn’t need to be a developer to use it. Upload two files, see the differences, and click to merge.
- Granular Precision: You can accept an entire file’s changes or pick and choose individual properties (like just updating a name but keeping the old ID).
- Instant Feedback: Your merged output is previewed in real-time. No “black box” processing—what you see is what you get.
The solution: the Metadata Comparator
The Metadata Comparator operates on a semantic level. Instead of just looking at characters, it parses the objects, matches them by their unique IDs, and detects “true” changes.
How it works:
- Upload: Drop in two JSON files.
- Normalize: The tool automatically sorts and cleans the files so you aren’t distracted by formatting “noise.”
- Compare & Merge: Use the interactive UI to select which data to keep.
- Download: Export a perfectly formatted, validated JSON file ready for DHIS2.
The Tech Stack:
For those interested in the engine under the hood:
- Frontend: React and TypeScript for a robust, type-safe UI.
- Editor: Monaco Editor (the power behind Visual Studio Code) for high-fidelity syntax highlighting.
- Performance: A specialized “comparator-only” build mode via Vite ensures the tool remains lightning-fast by avoiding unnecessary DHIS2 server requests during the merge.
If you want to know more, explore our github repository for this project!
Future work:
This is only the beginning. We are already looking toward future iterations, including Schema Validation to check your files against DHIS2 standards before you even download them, and Change History to track the “who” and “why” behind every modification.
At its heart, the Metadata Comparator is about confidence. We are making it easier to safely update and evolve your systems, ensuring your tech keeps pace with your health mission.
