Workflow Diagram Schema Versions in Archify: v1 vs v2 Explained

Archify supports two schema versions for workflow diagrams—version 1 for legacy compatibility and version 2 for the modern readable-v2 compiler—while all other diagram types remain fixed at version 1.

The tt-a1i/archify repository uses a schema_version field to control how diagram JSON sources are parsed and rendered. Understanding these schema versions is essential when authoring or migrating workflow diagrams, as each version triggers different layout engines and rendering behaviors.

Supported Schema Versions for Workflow Diagrams

Archify defines two valid schema versions exclusively for the Workflow diagram type:

Schema Version	Purpose
1	Original immutable schema preserving legacy layout and rendering behavior from Archify's initial release.
2	Introduced specifically for Workflow diagrams; enables the new readable-v2 compiler with deterministic, modern layout algorithms.

According to the repository's authoring guide in docs/article-archify.md, "the first five diagram types are fixed at schema_version: 1"—Architecture, Sequence, Dataflow, Lifecycle, and the original Workflow implementation. Workflow is the clear exception: v1 remains legal for backward compatibility, and v2 explicitly selects the new readable-v2 compiler.

File Examples in the Repository

The docs/gallery/sources/ directory contains concrete implementations demonstrating both schema versions:

Legacy Workflow (Schema Version 1)

The file docs/gallery/sources/release-delivery.workflow.json implements a workflow diagram using the original schema:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  ...
}

This file validates successfully and renders with the legacy layout engine.

Modern Workflow (Schema Version 2)

The file docs/gallery/sources/agent-tool-call.workflow.json demonstrates the updated schema:

{
  "schema_version": 2,
  "diagram_type": "workflow",
  ...
}

Setting schema_version: 2 activates the readable-v2 compiler, which produces more predictable node positioning and improved edge routing.

Checking Schema Versions Programmatically

You can inspect the schema_version field in any workflow JSON file using Node.js:

import { readFile } from 'fs/promises';

// Load a workflow JSON file
const workflow = JSON.parse(
  await readFile('docs/gallery/sources/agent-tool-call.workflow.json', 'utf-8')
);

// Inspect the schema version
console.log('Workflow schema version:', workflow.schema_version);
// → Workflow schema version: 2

Validating Workflow Diagrams with the CLI

The Archify CLI accepts both schema versions for workflow diagrams. Validate legacy and modern workflows using these commands:

# Validate a version-1 workflow (still supported)

archify validate docs/gallery/sources/release-delivery.workflow.json --json

# Validate a version-2 workflow (uses the new readable-v2 compiler)

archify validate docs/gallery/sources/agent-tool-call.workflow.json --json

Both commands succeed, confirming backward compatibility for schema version 1 and full support for version 2.

Where Schema Versions Are Enforced

Several source files govern schema version behavior:

• docs/article-archify.md — Documents the policy: five core diagram types locked to version 1, with Workflow as the exception supporting versions 1 and 2.

• archify/schemas/README.md — Formal schema reference defining valid schema_version values per diagram type.

• archify/test/workflow-compiler.test.mjs — Test suite that validates both schema versions compile correctly for workflow diagrams.

Summary

• Only Workflow diagrams support multiple schema versions; all other Archify diagram types require schema_version: 1.

• Schema version 1 maintains backward compatibility with legacy layouts.

• Schema version 2 activates the readable-v2 compiler for improved, deterministic workflow rendering.

• Both versions validate successfully through the Archify CLI and test suite.

• Repository examples in docs/gallery/sources/ demonstrate real-world usage of each version.

Frequently Asked Questions

What happens if I use schema_version 2 on a non-Workflow diagram?

Archify will reject the diagram. According to docs/article-archify.md, Architecture, Sequence, Dataflow, and Lifecycle diagrams are fixed at schema_version: 1; the parser enforces this constraint during validation.

Can I mix schema versions in the same diagram project?

Yes. Each .workflow.json file declares its own schema_version independently. A project can contain both version-1 and version-2 workflow diagrams without conflict.

How do I migrate a workflow from schema version 1 to version 2?

Change "schema_version": 1 to "schema_version": 2 in your JSON source, then validate with archify validate. The readable-v2 compiler may produce different layout results; review the rendered output to confirm acceptable positioning.

Is schema version 2 planned for other diagram types?

The repository documentation does not indicate plans to extend schema version 2 beyond Workflow diagrams. The authoring guide explicitly describes Workflow as "the clear exception" to the version-1 policy.

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