ForgeJSON Pipeline Spec

A portable, inspectable JSON format for data transformation pipelines.

Define how JSON should be transformed without coupling the document to execution engines, prompts, or runtime behavior.

Why this exists

Modern systems rely on JSON pipelines for cleaning API responses, preparing data for LLMs, validating contracts, and transforming data between formats.

Too often, these pipelines are hidden in code, embedded in prompts, tied to a specific runtime, or difficult to inspect and validate. ForgeJSON Pipeline Spec defines a standard, portable document format for JSON pipelines.

What you get

• JSON Schema for validating pipeline documents
• TypeScript types for building compatible tooling
• Example pipelines for real-world patterns
• A lightweight runtime shape guard

What this is not

This package intentionally does not include:

• Execution engine
• Utility implementations
• AI Draft system
• Hosted API behavior

This is a format, not a runtime.

Example

{
  "kind": "forgejson.pipeline",
  "version": "1.0",
  "nodes": [
    { "id": "input", "type": "input" },
    {
      "id": "pick",
      "type": "step",
      "utility": "structure.pick-fields",
      "args": {
        "fields": ["id", "email", "total"]
      }
    },
    {
      "id": "redact",
      "type": "step",
      "utility": "cleanup.redact",
      "args": {
        "paths": ["email"]
      }
    },
    { "id": "output", "type": "output" }
  ],
  "edges": [
    { "from": "input", "to": "pick" },
    { "from": "pick", "to": "redact" },
    { "from": "redact", "to": "output" }
  ]
}

Installation

npm install @forgejson/pipeline-spec

Usage

TypeScript

import type { ForgeJsonPipeline } from "@forgejson/pipeline-spec";

Runtime guard

import { isForgeJsonPipeline } from "@forgejson/pipeline-spec";

if (isForgeJsonPipeline(data)) {
  // data has the public ForgeJSON pipeline shape
}

JSON Schema

import schema from "@forgejson/pipeline-spec/schema";

Use the schema with validators such as ajv.

Design principles

Portable

Pipelines are plain JSON. They can be stored, versioned, sent over APIs, and embedded in docs.

Declarative

Pipelines describe what should happen, not how it runs. Execution is left to ForgeJSON, your own engine, or third-party tooling.

Inspectable

Every transformation step is explicit. There is no hidden prompt parsing or runtime-specific graph state in the public format.

Extensible

The spec is strict on structure and flexible on execution. Utility arguments are intentionally not constrained by the schema, which allows new utilities, vendor extensions, and forward compatibility.

Versioning

The pipeline format uses semantic versioning:

• "1.0" is the current stable format.
• Additive changes use minor versions, such as "1.1".
• Breaking changes use major versions, such as "2.0".

The npm package version is independent from the schema version.

Use cases

• Preprocessing LLM inputs
• Postprocessing LLM outputs
• API response normalization
• Data contract enforcement
• Change detection and diff pipelines
• CSV and JSON transformations

Ecosystem vision

This spec enables pipeline editors, validators, static analyzers, execution engines, and AI-assisted pipeline generation to interoperate through a shared format.

Implementations

Current implementations of the ForgeJSON Pipeline Spec:

• ForgeJSON: https://forgejson.com
  Reference implementation with editor, execution engine, and API.

More implementations are welcome.

Status

Early public release (0.1.0).

The format is stable at version: "1.0" and designed for forward compatibility.

License

MIT

Links

• ForgeJSON: https://forgejson.com
• Docs: https://forgejson.com/docs