DEV Community

Cover image for We Open Sourced Our Core .NET JSON Data Mapping Engine (MIT Licensed)
Faraz Ahmed
Faraz Ahmed

Posted on Edited on

We Open Sourced Our Core .NET JSON Data Mapping Engine (MIT Licensed)

#opensource #webdev #showdev #dotnet

mapping image

Hey DEV! 👋

If you build web apps or data pipelines, you know the pain of writing repetitive, imperative code just to map one shape of JSON into another.

Today, we are incredibly excited to share that we have open-sourced the core engine behind SpanFlow's visual pipelines. The same engine that branches, loops, and merges JSON payloads in our cloud platform is now entirely open for you to run locally, embed in your own projects, or self-host.

Here is what we've open-sourced and how you can get started right now.

📦 1. Embed the Engine in your .NET Apps

The engine libraries are fully MIT-licensed and target .NET Standard 2.0, .NET 8, .NET 9, and .NET 10. This means it runs effortlessly on modern .NET as well as legacy .NET Framework 4.7.2+.

To run JSON-to-JSON visual mappings directly inside your own C# backend code, just pull down the NuGet packages:

# Contains the schema model and transformation validation rules
dotnet add package SpanFlow.Mapping.Core

# The execution engine that performs the transformations
dotnet add package SpanFlow.Mapping.Engine
Enter fullscreen mode Exit fullscreen mode

Executing a visual mapping model takes only a few lines of code:

using System.Text.Json;
using System.Text.Json.Nodes;
using SpanFlow.Mapping.Core.Models;
using SpanFlow.Mapping.Engine;

// Read and deserialize your pre-defined mapping JSON schema
var options = new JsonSerializerOptions { PropertyNameCaseInsensitive = true };
var mapping = JsonSerializer.Deserialize<MappingDefinition>(File.ReadAllText("mapping.json"), options)!;

// Parse your raw input payload
var input = JsonNode.Parse(File.ReadAllText("input.json"));

// Execute the transformation engine
JsonNode output = new MappingEngine().Execute(mapping, input);

// Outputs the cleanly transformed JSON structure
Console.WriteLine(output.ToJsonString());
Enter fullscreen mode Exit fullscreen mode

🐳 2. Run the Visual Designer Locally via Docker

We didn’t just open-source the console engine—we also packed up the drag-and-drop UI. You can run the entire hosted mapping studio layout on your local machine using a single Docker container.

No databases, no external dependencies, and absolutely no sign-in screens required.

docker run -p 8080:8080 ghcr.io/spanflow/mapping-designer
Enter fullscreen mode Exit fullscreen mode

Once running, spin up your browser to http://localhost:8080 to visually draw nodes, trace inputs/outputs, and manage pipelines locally.

(Note: The core engine libraries are MIT licensed; the designer API and front-end interface are licensed under the Functional Source License, which rolls over into Apache 2.0 after two years).

🎮 3. Test It Online Instantly (No Install)

If you just want to see how the engine behaves under the hood without adding dependencies or spinning up containers, we've set up a completely free, no-auth web playground.

You can paste a raw snippet of your target payload, draw your logic nodes, and watch your transformations run dynamically:

🔗 Open the SpanFlow Mapping Playground

You can also programmatically test the playground's sandbox endpoints by executing a direct POST to the hosted mapping execution API:

curl -X POST https://spanflow.app \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": {
      "target": {
        "type": "object",
        "mappings": [
          { "target": "employeeId", "from": "input.id" },
          { "target": "name", "from": "input.fullName" }
        ]
      }
    },
    "inputObject": {
      "id": 101,
      "fullName": "Alice Smith"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

💻 Open for Contributions

We’d love to know what you think! You can explore the internal architecture, report tracking bugs, submit features, or browse our engine tests directly over on GitHub:

🐙 Check out the SpanFlow GitHub Repository

Drop a comment below if you have any questions about embedding it into your .NET architectures, or if there are specific complex JSON mapping scenarios you want us to write recipes for!

Top comments (0)