# Archify Workflow Schema v1 vs v2: Core Differences and Migration Guide

> Compare Archify workflow schema v1 and v2. Understand explicit lanes, typed edges, and validation in v2. Get a migration guide to upgrade your Archify workflows.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: migration-guide
- Published: 2026-09-13

---

**Archify uses a versioned JSON intermediate representation (IR) where `schema_version: 1` relies on implicit coordinate-based layouts while `schema_version: 2` introduces explicit lanes, typed edges, and strict validation constraints.**

The **Archify** open-source project stores workflow definitions as structured JSON that is validated against a versioned schema. Understanding the differences between **schema v1** and **schema v2** is essential for maintaining existing diagrams and authoring new ones with proper type safety and automated validation.

## Understanding the Archify Workflow Schema

Archify workflows are stored as JSON IR files that declare nodes, edges, and layout metadata. The **schema version** is determined by the top-level `schema_version` field, which instructs the validator which JSON-Schema definition to apply. Version 1 represents the original permissive format, while Version 2 introduces architectural constraints that enforce security boundaries and visual semantics.

## Schema v1: Coordinate-Based Layout

### Basic Node and Edge Structure

In **schema v1**, nodes are simple objects containing `id`, `type`, `label`, and optional `row`/`col` coordinates. Edges are plain connections with `from`, `to`, `label`, and an optional `variant` string such as `"emphasis"` or `"security"`. However, **v1 does not enforce semantic meaning** for these variants—they are treated as free-form labels rather than typed constraints.

According to the source code in [`docs/gallery/sources/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/web-app.architecture.json), a typical v1 workflow relies solely on coordinate positioning without explicit lane boundaries:

```json
{
  "schema_version": 1,
  "nodes": [
    { "id": "ui", "type": "messagebus", "label": "UI", "row": 0, "col": 0 },
    { "id": "agent", "type": "messagebus", "label": "Agent", "row": 1, "col": 0 }
  ],
  "edges": [
    { "from": "ui", "to": "agent", "label": "Request", "variant": "emphasis" }
  ]
}

```

### Validation Approach

The v1 schema, defined in [`archify/schema/v1.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v1.json), uses AJV for validation but remains **relatively permissive**. It does not enforce edge-type safety or validate that `row`/`col` values respect lane boundaries, allowing diagrams with overlapping nodes or ambiguous security flows to pass validation.

## Schema v2: Explicit Lanes and Typed Edges

### Explicit Lane Abstraction

**Schema v2** introduces a first-class **lane** concept. Instead of inferring visual groups from coordinates, workflows declare a `lanes` array where each lane has its own `id`, `type`, and positional metadata. Nodes then reference their lane via a `lane` property rather than raw coordinates.

As implemented in [`docs/gallery/sources/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/docs/gallery/sources/agent-tool-call.workflow.json), lanes enable modularity by making visual grouping an intentional part of the IR:

```json
{
  "schema_version": 2,
  "lanes": [
    { "id": "ui", "type": "lane", "label": "User Interface", "row": 0, "col": 0 },
    { "id": "runtime", "type": "lane", "label": "Agent Runtime", "row": 1, "col": 0 }
  ],
  "nodes": [
    { "id": "request", "type": "messagebus", "label": "User Request", "lane": "ui" }
  ]
}

```

### Typed Edges and Security Models

Edges in v2 require a `variant` value that is validated against an **enumerated security model**. Variants like `"security"` (for approval-gate flows) and `"emphasis"` (for happy-path flows) are strictly validated against allowed values in [`archify/schema/v2.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v2.json). Additionally, the schema enforces **edge directionality rules**—for example, a `"security"` edge must originate from a lane of type `security` and terminate at a lane of type `approval`.

### Rich Metadata and Layout Constraints

Version 2 adds structured fields such as `sublabel`, `rowSpan`, `colSpan`, and `styleHints` to nodes. The top-level object includes a `meta` block containing `quality_profile`, `author`, and diagram `version`. Validation in [`archify/schema/v2.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v2.json) enforces that `row` and `col` values are non-negative integers and prevents overlapping nodes within lane boundaries.

## Key Differences Between v1 and v2

| Aspect | Schema v1 | Schema v2 | Impact |
|--------|-----------|-----------|---------|
| **Lane definition** | Implicit via `row`/`col` coordinates | Explicit `lanes` array with typed objects | Lanes can be reused, inspected programmatically, and rendered consistently across exporters |
| **Edge typing** | Free-form `variant` string | Enum-validated `variant` with security constraints | Enables automated policy enforcement and CI validation of security flows |
| **Metadata** | Minimal fields | `meta` block plus node styling properties | Allows downstream tools to make rich decisions without ad-hoc heuristics |
| **Validation strictness** | Loose AJV validation | Strict constraints on directionality and layout | Catches malformed diagrams early in CI pipelines |
| **Versioning** | Single schema file | Separate files per version ([`v1.json`](https://github.com/tt-a1i/archify/blob/main/v1.json), [`v2.json`](https://github.com/tt-a1i/archify/blob/main/v2.json)) | Future-proof format allowing independent evolution of major revisions |

## Practical Migration and Tooling

### Automatic Migration via CLI

Users can upgrade existing v1 diagrams to v2 using the migration utility located at [`archify/cli/migrate.js`](https://github.com/tt-a1i/archify/blob/main/archify/cli/migrate.js). The command `archify migrate <file>` automatically rewrites coordinate-based layouts into explicit lanes and maps free-form edge labels to the closest supported variant enum values.

### Validation Targets

Modern exporters, viewers, and CI validators in the tt-a1i/archify repository target `schema_version: 2` by default. To validate legacy diagrams, invoke the validator with the `--schema-version 1` flag, which references [`archify/schema/v1.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v1.json) instead of the v2 schema.

## Summary

- **Schema v1** uses simple coordinate-based nodes and permissive edge labels, validated against [`archify/schema/v1.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v1.json).

- **Schema v2** introduces explicit lanes, enum-typed security edges, and a `meta` block, with strict validation rules in [`archify/schema/v2.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v2.json).

- **Migration** is handled automatically via `archify migrate <file>`, which converts coordinates to lanes and normalizes edge variants.

- **New workflows** should use `schema_version: 2` to leverage type safety and automated security policy enforcement.

## Frequently Asked Questions

### How do I check which schema version my Archify workflow uses?

Open the JSON file and inspect the top-level `schema_version` field. If the field is missing or set to `1`, the workflow uses the legacy coordinate-based format. If set to `2`, the workflow includes explicit lanes and typed edges validated against [`archify/schema/v2.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v2.json).

### Can I still use schema v1 in new projects?

While the repository maintains backward compatibility through [`archify/schema/v1.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v1.json), new projects should adopt **schema v2** to access lane abstraction, strict validation, and security-typed edges. The v1 format is considered legacy and may not support upcoming exporter features.

### What happens to free-form edge labels during migration?

The [`archify/cli/migrate.js`](https://github.com/tt-a1i/archify/blob/main/archify/cli/migrate.js) tool maps free-form `variant` strings from v1 to the closest matching enum values defined in v2. Labels that do not match allowed variants are either converted to `"emphasis"` or flagged for manual review depending on their semantic context.

### Does schema v2 support custom lane types?

The v2 schema in [`archify/schema/v2.json`](https://github.com/tt-a1i/archify/blob/main/archify/schema/v2.json) validates lane types against a predefined set of architectural roles (such as `lane`, `security`, and `approval`). While you cannot define arbitrary custom types without modifying the schema, the built-in types cover most workflow segmentation patterns including human approval gates and agent runtimes.