Version-controlled by design

Roelant Vos · 1 Jun 2026 · 4 min read

Versioning in conventional modeling tools is reliably one of three things: slow, complex, or prone to conflicts - and usually all three. The metadata sits in the tool’s database repository, the tool often is the only thing that can reliably read it, and the way you interact with history follows from that constraint. To track changes you often wait on a check-in dialog. To compare versions you open a proprietary viewer proved by the tool. To collaborate you negotiate around object locks. The version system is whatever the tool decided to remember, executed at whatever speed its server can manage, with merge conflicts handled inside a vendor UI that can be a bit of an acquired taste.

ADL provides an alternative to this, one that removes the constraints that a proprietary versioning approach has. Using an open and interoperable format in JSON, any and all metadata changes can simply be managed through Git.

Metadata as files, history through Git

Your design metadata in ADL is managed as a set of plain JSON files in your own local environment. Open them in any editor, and diff them in your preferred tool.

There is no central database. No proprietary format. No hidden state. The metadata is just files - and Git already knows how to version files very well.

So ADL’s versioning is not a feature it needs to implement. Instead, it is a property of the architecture. Your design metadata is in it from the start. You do not need configure it. It is just where things are.

What ‘by design’ actually means

Handling this well, without friction, takes more than simply creating an app that ‘writes JSON’. The app makes deliberate choices so that Git sees clean, reviewable diffs. For example:

• Each object is stored as a dedicated file. For instance, a Customer Data Object lives in Metadata/DataObjects/Customer.json. Rename it and Git sees a file rename. Add a column and Git sees a single-line diff in that one file. Delete it and Git sees one file removed.
• Properties serialize in a stable order, keys use camelCase, null and empty values are omitted, output is indented and human-readable. Two saves of the same model produce identical files, avoiding reshuffling noise.
• No timestamps, no author IDs, no version numbers, no hashes baked into the JSON. The history is Git’s job, not the file’s. The files stay clean and human-authored.
• ADL reads from whatever folder you open. If that folder is your repo on main, you are working on main. If you checked out feature/new-pii-rules first, you are working there. ADL has no opinion. Branching, merging, cherry-picking — that is Git’s domain.

The folder you point ADL at is the folder git tracks — nothing more.

Below is what a typical metadata change can look like in a typical Git tool. Three JSON files affected, with the actual edit - a Customer notes-field update - visible as a one-line diff.

What this gets you

Once the metadata is in Git, the workflows your team is already used to starts working on the design metadata too:

• When you add an audit column and update the loading procedure that populates it, both changes ship in one commit. The design and the implementation never drift.
• A change to a classification or a mapping is a normal PR with normal review. Reviewers see exactly what changed, comment line by line, request adjustments. Same flow as a code review — because at the file level it is a code review.
• Spin up a branch, try a different Data Vault hashing strategy, regenerate, see the output diff. Don’t like it? Throw the branch away. The cost of trying something is roughly zero.
• Wondering why that column is NOT NULL? Right-click in your editor. The commit that made it so, the message that explained why, and the PR it came from are already there.
• If you ever stop using ADL (we hope you won’t, but the option matters) your full design history travels with you. It was never in our app.

Design metadata is the long-lived artifact of any data solution; the technology underneath changes, but the design, the concepts, and the metadata remain.

ADL’s job is to be a good metadata editor that writes clean files. Git’s job is to remember what changed. Your review tooling’s job is to surface diffs. Each tool does the part it is good at, and the result is that your design metadata gets treated like every other artifact in your codebase.