Incremental migrations for your JSON files

Safely update JSON configuration files without overwriting installation-specific values. Write migrations in C# and run them in the correct order.

dotnet add package JsonMigrations

View on GitHub View on NuGet

Requires .NET 6.0 or later

.NET 6+

Platform

MIT

Open source licence

NuGet

Package manager

v3.0

Latest version

How does it work?

Three steps to safely update your JSON files.

Step 1

Configure

Set the behaviour for errors, invalid JSON or missing files. Sensible defaults work straight out of the box.

Step 2

Write migrations

Create C# classes that implement IJsonMigration. Each migration has an order and a key to group related migrations together.

Step 3

Run

Call Migrate() with a key and file paths. Only new migrations are executed — previously applied migrations are automatically skipped.

Why JsonMigrations?

Incremental updates

Migrations run in order and are tracked. On subsequent runs, only new migrations are applied, keeping existing changes intact.

Error handling

Choose per situation: ignore errors, throw an exception, or restore the file to its original state. You decide the behaviour.

Flexible configuration

Configure serialisation options, invalid JSON behaviour and missing file actions. Everything is optional with sensible defaults.

Automatic discovery

Preserves existing values

Installation-specific values like connection strings and API keys remain untouched. Only the changes from your migrations are applied.

Open source

Fully open source under the MIT licence. View the source code, contribute or adapt it to your own needs.

Quick start

From installation to working migrations in three steps.

1. Install the NuGet package

dotnet add package JsonMigrations

2. Write a migration

public class AddConnectionString : IJsonMigration
{
    public int Order => 0;
    public string MigrationKey => "AppSettings";

    public void Up(JsonObject jsonObject, JsonSerializerOptions options)
    {
        jsonObject.TryAdd("ConnectionString", "Server=localhost");
    }
}

3. Run the migrations

JsonMigrator.AddJsonMigrations(typeof(AddConnectionString).Assembly);
JsonMigrator.Migrate("AppSettings", "appsettings.json");

Ready to manage your JSON files?

Install JsonMigrations via NuGet and write your first migration in minutes.

dotnet add package JsonMigrations

View on NuGet View source code on GitHub