Archify Workflow Schema Versions: What’s Supported and What It Means

Archify currently supports only workflow schema version 1, which controls contract validation, repair receipt formatting, and future migration capabilities.

Archify is a workflow validation and rendering engine that enforces strict schema versioning to ensure deterministic processing. According to the tt-a1i/archify source code, all workflow JSON files must declare "schemaVersion": 1 to pass validation, generate compatible repair receipts, and render correctly in the workflow visualization pipeline.

The Only Supported Workflow Schema Version

Archify defines a single, immutable workflow schema version: schemaVersion: 1. This requirement is documented in docs/authoring-cookbook.md and enforced across the entire toolchain, from validation to rendering.

Every workflow file—including the canonical examples/agent-tool-call.workflow.json—must include this top-level field. The archify/schemas/README.md serves as the master reference, defining the allowed values for schemaVersion and establishing the contract that downstream tools must honor.

Three Critical Implications of Schema Version 1

The version number operates as a strict compatibility gate across three internal systems:

Contract Validation

When workflows are passed to validate, compare, or deliver operations, Archify checks that schemaVersion matches exactly 1. Any other value triggers an "unsupported schemaVersion" diagnostic and aborts the operation immediately.

This validation occurs in the core processing pipeline, ensuring that only compatible workflow structures reach the renderer or comparison engine.

Repair Receipt Format

A successful validation produces a Repair Receipt (JSON) that always contains schemaVersion: 1. This receipt structure includes:

• A diagnostics[] array describing rule codes, severities, and subjects
• supportedFixes listing automatically applicable repairs
• Measured evidence for each diagnostic

As tested in archify/test/v1-compatibility.test.mjs, this version-locked design guarantees deterministic repair loops. The renderer in archify/renderer/workflow/render-workflow.mjs expects this specific receipt format and throws errors for version mismatches.

Future-Proofing Extensibility

The mandatory version field provides a clean migration point for backward-incompatible changes. If Archify introduces new workflow features—such as modified edges or nodes structures—a new schemaVersion: 2 can be implemented while tooling continues to process version 1 files.

This architecture allows dedicated schema upgrade steps without breaking existing pipelines, as implemented in the validation layer.

Validating Schema Version in Practice

Workflow authors must explicitly declare version compliance. Here is the minimal required structure:

{
  "schemaVersion": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Simple approval flow"
  },
  "nodes": [
    { "id": "start", "type": "start", "label": "Start" },
    { "id": "approve", "type": "task", "label": "Approve" },
    { "id": "end", "type": "end", "label": "Done" }
  ],
  "edges": [
    { "from": "start", "to": "approve" },
    { "from": "approve", "to": "end" }
  ]
}

To validate that your workflow meets the schema version requirement, use the CLI:

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
  --quality showcase --json

This command rejects files missing "schemaVersion": 1 or containing unsupported values.

The resulting Repair Receipt confirms the version lock:

{
  "schemaVersion": 1,
  "stage": "validate",
  "diagnostics": [],
  "supportedFixes": []
}

When comparing workflow iterations, both files must share the same schema version:

node bin/archify.mjs compare workflow base.workflow.json head.workflow.json \
  workflow-delta.html --quality showcase --json

Key Files Controlling Schema Version Behavior

File	Purpose
docs/authoring-cookbook.md	Documents the required schema_version field for workflow sources and references the schema definition
archify/schemas/README.md	Master schema reference defining allowed schemaVersion values and top-level field constraints
archify/test/v1-compatibility.test.mjs	Validates that the system correctly handles schemaVersion: 1 receipts and rejects incompatible versions
examples/agent-tool-call.workflow.json	Canonical example workflow demonstrating proper "schemaVersion": 1 declaration
archify/renderer/workflow/render-workflow.mjs	Renderer implementation that enforces the version-1 contract and errors on mismatch

Summary

• Archify supports exactly one workflow schema version: schemaVersion: 1.
• The validate, compare, and deliver methods enforce this version strictly, aborting operations if mismatched.
• Repair Receipts always echo schemaVersion: 1 alongside diagnostics and supported fixes.
• The versioning system enables future migration to version 2 without breaking existing version 1 pipelines.
• Omitting the field or using incorrect values causes immediate validation failures across the entire toolchain.

Frequently Asked Questions

What happens if I omit schemaVersion from my workflow file?

Archify rejects the file during validation with an "unsupported schemaVersion" diagnostic. The validate operation aborts immediately, preventing the workflow from reaching the renderer or comparison engine. All workflow JSON files must explicitly declare "schemaVersion": 1 to process successfully.

Does Archify support workflow schema version 2?

No. Currently, only schemaVersion: 1 is implemented and recognized. However, the codebase architecture—including the validation layer and receipt format—reserves the version field as an extension point. Future backward-incompatible changes could introduce version 2 while maintaining support for version 1 files.

How does the Repair Receipt use the schema version?

The Repair Receipt always returns "schemaVersion": 1 alongside the diagnostics[] array and supportedFixes list. This version guarantee ensures that automated repair loops and downstream tooling can parse the receipt deterministically, as verified by the v1-compatibility test suite.

Where is schema version validation enforced in the codebase?

Validation occurs in the core processing functions exposed through the CLI: validate, compare, and deliver. The archify/renderer/workflow/render-workflow.mjs module additionally enforces version compliance when rendering workflows, throwing errors for any schema version other than 1.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}