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

> Discover Archify workflow schema versions. Learn about current support for version 1 and its impact on contract validation, repair receipts, and migration. Understand what it means for your projects.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-10

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json)—must include this top-level field. The [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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:

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

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

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

```

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

```bash
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`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md) | Documents the required `schema_version` field for workflow sources and references the schema definition |
| [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.