version-json

Effortless versioning for long-lived JSON payloads.

version-json is a lightweight utility for managing and upgrading long-lived JSON data structures. You define transformation functions for each version, and it upgrades incoming payloads to the latest shape—keeping your data consistent as your schema evolves.

Links:

• GitHub: https://github.com/odama626/version-json
• npm: https://www.npmjs.com/package/version-json

What it does

• Version-aware transformations
  Define a chain of upgrades that move payloads from one version to the next.

• Flexible version detection
  Use a dedicated version field (like version) or provide a custom function that infers the version from the payload shape.

• Simple integration
  Small API surface: describe upgrades with .add(), then normalize data with .process().

Example

const upVersion = new VersionJson("version");

upVersion
  .add(1, (p) => p)
  .add(2, (p) => {
    p.newData = p.data;
    delete p.data;
    return p;
  });

const newData = upVersion.process({ version: 1, data: "hello world" });
// => { version: 2, newData: "hello world" }

Why it exists

If you persist JSON in a database, local cache, config files, or synced documents, schemas inevitably change. version-json gives you a clear, explicit place to keep migrations so you can accept older payloads without scattering compatibility logic throughout your codebase.

“We created version-json to simplify the process of managing evolving JSON data structures, making data migrations effortless and reliable.” — The Sparkstone Team

This remind you of a problem you've been dealing with?

I'd be happy to discuss it with you and see if it's something we could turn into a solution.