How to Validate a Workflow Diagram with the Archify CLI: A Complete Guide

The Archify CLI provides a built-in validate command that checks workflow JSON files against the official schema and runs renderer-specific validation, exiting with status 0 on success or printing detailed error paths on failure.

The Archify CLI from the tt-a1i/archify repository includes a robust validation system for workflow diagrams. You can validate your workflow JSON files before rendering to catch schema errors, missing properties, or invalid references. This guide covers how to use the validate command with practical examples and source code references.

Understanding the Validation Pipeline

The validation process in archify/bin/archify.mjs performs three distinct checks:

• Schema validation using the compiled AJV validator located in archify/renderers/shared/generated-validators.mjs
• Renderer-specific validation via the validateWorkflow() function in archify/renderers/workflow/render-workflow.mjs
• Temporary-directory hygiene to ensure isolated execution without leaving artifacts behind

Prerequisites and Setup

No additional Node modules are required. The bundled validators ship with the skill. Install Archify globally via:

npx skills add tt-a1i/archify -g

Validating a Workflow Diagram

Prepare Your Workflow JSON

Create a file following the schema defined in archify/schemas/workflow.schema.json:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Login flow" },
  "lanes": [
    { "id": "browser", "label": "Browser" },
    { "id": "api", "label": "API" }
  ],
  "nodes": [
    { "id": "login", "label": "Login", "lane": "browser" },
    { "id": "validate", "label": "Validate JWT", "lane": "api" }
  ],
  "edges": [
    { "from": "login", "to": "validate" }
  ],
  "mainPath": ["login", "validate"]
}

Run the Validate Command

Execute the validator from your terminal:

node archify/bin/archify.mjs validate workflow workflow.json

Add --json for machine-readable output suitable for CI pipelines:

node archify/bin/archify.mjs validate workflow workflow.json --json > report.json

Add --layout-json to include computed layout information:

node archify/bin/archify.mjs validate workflow workflow.json --layout-json > layout.json

Interpret the Results

A successful validation exits with status 0 and prints:

✔ workflow.json is valid

Failed validation provides specific error paths pointing to the offending property:

✖ workflow.json schema validation failed:
  /lanes/0/id: must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$"

How Validation Works Under the Hood

According to the source code in tt-a1i/archify, the validation process:

1. Dispatches to the AJV validator through archify/renderers/shared/validator.mjs, which uses the compiled schemas in generated-validators.mjs
2. Executes renderer validation by calling validateWorkflow() in archify/renderers/workflow/render-workflow.mjs (lines 95-99)
3. Runs in isolation using a temporary directory that gets cleaned up automatically (lines 202-209)

Summary

• The Archify CLI provides built-in workflow validation via the validate command
• Validation checks schema compliance, renderer requirements, and file hygiene
• Use --json for CI-friendly machine-readable output
• Use --layout-json to preview computed layout data
• The AJV validator in generated-validators.mjs handles schema validation against workflow.schema.json
• Exit code 0 indicates success; errors include precise JSON paths to invalid properties

Frequently Asked Questions

What exit code does the Archify CLI return on validation failure?

The CLI returns a non-zero exit status when validation fails. A status 0 indicates the workflow JSON is valid according to both the schema and renderer requirements.

Can I validate workflow diagrams without installing additional dependencies?

Yes. The validation system is self-contained and ships with the bundled AJV validators in archify/renderers/shared/generated-validators.mjs. No extra Node modules are required beyond the core Archify installation.

How do I interpret schema validation errors?

Error messages include the JSON path to the offending property, such as /lanes/0/id: must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$". This indicates the first lane's ID violates the naming convention and must start with a letter followed by alphanumeric characters, underscores, or hyphens.

Where can I find the official workflow schema definition?

The canonical schema resides at archify/schemas/workflow.schema.json in the repository. This file defines required properties including schema_version, diagram_type, lanes, nodes, and edges.

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