How to Migrate a Workflow Schema from v1 to v2 in Archify

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

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.

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:

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 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 <input> <output> --to-schema 2 --json to convert files while preserving original geometry.
• Validate migrations using validate workflow <file> --layout-json to confirm contract compliance and layout integrity.
• The process is idempotent and non-destructive by default, preventing accidental data loss.

Frequently Asked Questions

What is the difference between v1 and v2 workflow schemas in Archify?

The v1 schema stores absolute coordinate data (via, labelAt, channelX/Y) for fixed-geometry rendering, requiring manual updates when layouts change. The v2 schema uses a readable, adaptive layout compiler that interprets logical column relationships, allowing the renderer to calculate pixel positions automatically. As implemented in tt-a1i/archify, v2 is the modern default that produces more maintainable workflow definitions.

Is the migration process destructive to my original files?

No. According to the source code in archify/renderers/workflow/README.md, the migration command creates a new output file and never overwrites the source unless you explicitly provide the --overwrite flag. This design allows teams to maintain both versions in version control during transition periods.

How do I verify that my migrated workflow renders correctly?

Run the validation command node archify/bin/archify.mjs validate workflow <file> --layout-json on your migrated file. This outputs a layout receipt containing the viewBox, solved columns, and contract version, confirming that the geometry matches the original v1 intent while adhering to the v2 schema requirements.

Where is the workflow schema defined in the Archify source code?

The JSON Schema definition resides in archify/schemas/workflow.schema.json, which specifies the allowed schema_version values and structure. Example v2 workflows are documented in archify/examples/agent-tool-call.workflow.json, and the migration logic is implemented in the CLI at archify/bin/archify.mjs with detailed documentation in archify/renderers/workflow/README.md.

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