# Workflow Diagram Schema Versions in Archify: v1 vs v2 Explained

> Explore Archify's workflow diagram schema versions. Understand v1 for legacy support and v2 for the modern readable-v2 compiler. Get clear explanations now.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/release-delivery.workflow.json) implements a workflow diagram using the original schema:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-tool-call.workflow.json) demonstrates the updated schema:

```json
{
  "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:

```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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/.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.