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

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, a typical v1 workflow relies solely on coordinate positioning without explicit lane boundaries:

{
  "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, 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, lanes enable modularity by making visual grouping an intentional part of the IR:

{
  "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. 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 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, 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. 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 instead of the v2 schema.

Summary

• Schema v1 uses simple coordinate-based nodes and permissive edge labels, validated against 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.

• 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.

Can I still use schema v1 in new projects?

While the repository maintains backward compatibility through 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 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 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.

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