# How to Migrate a Workflow Schema from v1 to v2 in Archify
> Migrate your Archify workflow schema from v1 to v2 easily using the CLI command. Convert absolute coordinates to logical column formats automatically.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: migration-guide
- Published: 2026-09-04
---
**To migrate a workflow schema from v1 to v2 in Archify, use the built-in CLI command `node archify/bin/archify.mjs migrate workflow` with the `--to-schema 2` flag, which automatically converts absolute coordinate data into the logical column-based format.**
Archify distinguishes between two distinct workflow JSON schema versions that determine how diagrams are rendered. If you have existing workflows using the legacy **v1** fixed-geometry layout, upgrading to the adaptive **v2** contract simplifies maintenance and improves readability. According to the `tt-a1i/archify` source code, the migration process is fully automated, idempotent, and preserves the original visual geometry while updating the underlying data structure.
## Understanding v1 and v2 Workflow Contracts
Archify maintains two layout contracts differentiated by the `schema_version` field:
- **v1 (`"schema_version": 1`)**: Uses fixed-geometry layout with absolute coordinates (`via`, `labelAt`, `channelX/Y`). This legacy contract stores pixel-perfect positions but requires manual updates when diagrams change.
- **v2 (`"schema_version": 2`)**: Implements a readable, adaptive layout compiler that calculates pixel positions automatically. This is the new default for fresh workflows and produces cleaner, more maintainable JSON.
The migration translates absolute coordinate data into logical column-based relationships, allowing the renderer in [`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md) to compute positions dynamically rather than relying on hardcoded values.
## Running the Migration Command
The migration is handled entirely through the CLI entry point at `archify/bin/archify.mjs`. The process reads your legacy file, transforms the geometry data, and writes a new v2-compliant file.
```bash
node archify/bin/archify.mjs migrate workflow \
path/to/old-workflow.json \
path/to/new-workflow.json \
--to-schema 2 \
--json
```
**Key parameters:**
- **`workflow`**: Specifies the document type being migrated.
- **`--to-schema 2`**: Target version identifier (required for v2 output).
- **`--json`**: Outputs formatted JSON for readability.
- **`--overwrite`**: Optional flag to replace the source file (disabled by default for safety).
The command automatically injects `"schema_version": 2` into the output file as required by the schema definition in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json).
## Validating the Migrated Schema
After migration, verify that the conversion preserved your geometry and that the new file conforms to the v2 contract using the validate command:
```bash
node archify/bin/archify.mjs validate workflow \
path/to/new-workflow.json \
--layout-json
```
This command prints a layout receipt showing the selected contract, measured `viewBox`, solved columns, and any diagnostic warnings. The validation step confirms that no geometry was silently altered during the migration process and that the destination bytes match the expected v2 layout specifications.
## Key Migration Considerations
When upgrading production workflows, keep these technical details in mind:
- **Non-destructive by default**: The migration command never overwrites the source file unless you explicitly pass `--overwrite`. Archify encourages keeping original v1 files in version control while pointing active projects to the new v2 files.
- **Idempotent process**: You can safely run the migration multiple times on the same file; the output remains consistent.
- **Rendering changes**: Once migrated, the workflow renderer computes pixel positions automatically. While the visual output remains equivalent to the original, the JSON structure shifts from absolute coordinates to logical column relationships.
- **Schema enforcement**: The [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) file strictly defines allowed `schema_version` values as integers `1` or `2`, ensuring type safety across the ecosystem.
## Summary
- Archify provides a built-in CLI command at `archify/bin/archify.mjs` to migrate workflow schemas from v1 to v2 automatically.
- The v1 contract uses fixed-geometry with absolute coordinates, while v2 uses an adaptive layout compiler with logical columns.
- Use `migrate workflow