# How to Migrate a Legacy v1 Workflow JSON to v2 Schema Using Archify CLI

> Easily migrate legacy v1 workflow JSON to v2 schema with Archify CLI. Convert old files to the new schema preserving geometry and validating output using archify migrate workflow.

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

---

**Archify ships a built-in migration command that automatically converts legacy v1 workflow JSON files to the v2 schema using `archify migrate workflow <old.json> <new.json> --to-schema 2`, preserving geometry and validating the output against the new schema.**

The Archify CLI provides a fully automated pipeline for upgrading workflow definitions from the original schema v1 to the richer, coordinate-centered schema v2. This process handles validation, geometry probing, and viewBox expansion without requiring manual edits to the source JSON.

## CLI Command Syntax and Options

The migration command follows a strict signature defined in `archify/bin/archify.mjs`:

```bash
archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]

```

- **`<old.json>`** – Path to the legacy workflow file. Must be valid JSON conforming to schema v1.
- **`<new.json>`** – Destination path for the migrated v2 workflow.
- **`--to-schema 2`** – Required flag that explicitly requests migration to schema v2. The CLI aborts if this flag is missing or set to a different value.
- **`--json`** – Optional flag that outputs a machine-readable migration report instead of human-friendly console messages.

## Step-by-Step Migration Process

When executed, Archify performs a logical sequence of operations to ensure safe and accurate transformation.

### Argument Validation

The CLI first verifies that the command name, source path, and destination path are present, and confirms that `--to-schema 2` is supplied. If any check fails, the utility aborts with a usage message defined at lines 65–75 of `archify/bin/archify.mjs`.

### Reading and Parsing the Source

The source file is read synchronously using `fs.readFileSync` and parsed as JSON. Errors during this phase are captured as diagnostics and reported immediately to the user (see lines 96–100 of `archify/bin/archify.mjs`).

### Core Migration Logic

The heart of the transformation resides in `archify/migrations/workflow-v2.mjs`. The `migrateWorkflowDocument` function executes the following sub-steps:

1. **Schema Validation** – The source document is validated against the v1 schema via `validateSchema`. If pre-existing diagnostics are found, migration stops early and returns a report containing those issues (lines 30–33).

2. **Legacy Layout Probing** – The system runs `legacyLayoutProbe` and `legacyRequirementProbe` to capture the intrinsic canvas capacity without relying on the author-provided `meta.viewBox`.

3. **Geometry Planning** – Using either an intrinsic rank mapper or a fallback planning workflow (`intrinsicWorkflow` / `planningWorkflow`), Archify calculates the target geometry for the v2 coordinate system.

4. **ViewBox Expansion** – The routine expands the viewBox as needed so that all absolute pins can be represented in the new rank-centered coordinate system.

5. **Final Validation** – After transformation, the workflow is compiled once more with the v2 compiler to ensure the result is error-free. The final `result` object returned at lines 84–112 contains the migrated document, diagnostics, and the old/new `viewBox` dimensions.

### Output and Idempotence

If migration succeeds, Archify writes the JSON representation of the migrated workflow to the destination path and prints a success message. If any step fails, a detailed diagnostic report is emitted (or printed as JSON when `--json` is used).

The process is idempotent: running the command on a document already at schema v2 simply re-validates the file and returns it unchanged. This early-exit branch is implemented at lines 38–58 of `archify/migrations/workflow-v2.mjs`.

## Practical Code Examples

### Basic Migration

Convert a legacy workflow with human-readable output:

```bash
archify migrate workflow legacy-workflow.json migrated-workflow.json --to-schema 2

```

Truncated output:

```

migrated workflow schema v1→v2: /path/legacy-workflow.json → /path/migrated-workflow.json

```

### Migration with JSON Report

Generate a machine-readable report for CI/CD pipelines:

```bash
archify migrate workflow legacy-workflow.json migrated-workflow.json --to-schema 2 --json

```

Sample output:

```json
{
  "ok": true,
  "command": "migrate",
  "type": "workflow",
  "source": {
    "path": "/path/legacy-workflow.json",
    "sha256": "a1b2c3…",
    "bytes": 1234
  },
  "destination": {
    "path": "/path/migrated-workflow.json",
    "sha256": "d4e5f6…",
    "bytes": 1300
  },
  "fromSchemaVersion": 1,
  "toSchemaVersion": 2,
  "preExistingDiagnostics": [],
  "migrationDiagnostics": [],
  "newSchemaDiagnostics": [],
  "changedCoordinates": [],
  "oldRequiredViewBox": [720, 240],
  "newRequiredViewBox": [768, 404]
}

```

### Programmatic Usage

Import the migration logic directly in Node.js applications:

```javascript
import { migrateWorkflowDocument } from './archify/migrations/workflow-v2.mjs';
import { readFileSync, writeFileSync } from 'fs';

const legacy = JSON.parse(readFileSync('legacy-workflow.json', 'utf8'));
const { ok, document, migrationDiagnostics } = migrateWorkflowDocument(legacy);

if (ok) {
  writeFileSync('migrated-workflow.json', JSON.stringify(document, null, 2));
  console.log('Migration succeeded');
} else {
  console.error('Migration failed:', migrationDiagnostics);
}

```

## Key Source Files and Architecture

Understanding the underlying implementation helps when debugging complex migrations:

- **`archify/bin/archify.mjs`** – CLI entry point that parses the `migrate` command and assembles the migration report.
- **`archify/migrations/workflow-v2.mjs`** – Core migration implementation containing `migrateWorkflowDocument`, validation logic, and geometry transformation routines.
- **`archify/renderers/workflow/workflow-compiler.mjs`** – Compiler used for both the legacy probe phase and final v2 validation.
- **[`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md)** – User documentation confirming exact CLI usage patterns.
- **`archify/test/workflow-migration.test.mjs`** – Test suite confirming correct behavior and idempotence guarantees.

## Summary

- **Archify CLI** provides a first-party `migrate workflow` command for upgrading v1 JSON files to schema v2.
- The **`--to-schema 2`** flag is mandatory and explicitly targets the v2 schema.
- Migration performs **geometry-preserving transformation** by probing legacy layouts and expanding viewBox coordinates to accommodate rank-centered positioning.
- The process is **idempotent**: running migration on an already-v2 file validates and returns it unchanged.
- Use the **`--json`** flag for machine-readable output suitable for automated build pipelines.
- Core logic resides in **`archify/migrations/workflow-v2.mjs`**, specifically the `migrateWorkflowDocument` function.

## Frequently Asked Questions

### What happens if my v1 workflow file contains validation errors?

If `validateSchema` detects pre-existing diagnostics during the initial check at lines 30–33 of `archify/migrations/workflow-v2.mjs`, the migration stops immediately. The CLI returns a report containing the specific validation errors without writing an output file, allowing you to fix the legacy document before retrying.

### Is the migration process idempotent?

Yes. According to the early-exit branch at lines 38–58 of `archify/migrations/workflow-v2.mjs`, Archify detects when a document is already at schema v2. In this case, it re-validates the file and returns it unchanged, making the command safe to run multiple times without side effects.

### Why does my viewBox change size during migration?

Archify probes the legacy layout using `legacyLayoutProbe` and `legacyRequirementProbe` to determine the intrinsic canvas capacity. It then expands the viewBox to ensure all absolute pins can be represented in the new rank-centered coordinate system. The final dimensions are reported in the `oldRequiredViewBox` and `newRequiredViewBox` fields of the migration report.

### Can I integrate this migration into my Node.js build scripts?

Yes. The `migrateWorkflowDocument` function exported from `archify/migrations/workflow-v2.mjs` can be imported directly into Node.js applications. Pass the parsed JSON object as an argument and handle the returned `ok` boolean and `document` properties to programmatically control file writing and error handling.