How to Validate a Workflow Diagram with JSON Diagnostics Using Archify

Archify validates workflow diagrams through a built-in validator that checks schema, layout constraints, and logical consistency, returning a machine-readable JSON receipt containing an array of diagnostics that can be inspected or used to auto-fix issues before rendering.

Archify treats workflow diagrams as typed JSON intermediate representations (IR) before rendering them as visual artifacts. The validation engine, implemented in the tt-a1i/archify repository, ensures that every workflow meets strict structural and semantic requirements through a command-line interface that emits detailed diagnostic reports. By validating workflows early in the pipeline, developers can catch schema violations and logical inconsistencies before generating final HTML or SVG outputs.

Understanding the Validation Pipeline

Archify processes workflow validation through a three-stage pipeline that separates generation from verification.

Generate Stage

An agent or user produces a JSON file describing workflow nodes, edges, and optional layout hints. The file must conform to Archify's workflow schema, specifying elements such as node IDs, labels, and edge connections.

Validate Stage

The CLI command archify.mjs validate workflow <path-to-json> --json loads the file and executes the validation logic. In archify/renderers/workflow/workflow-compiler.mjs, the validateWorkflow function performs schema checks, validates layout constraints, and verifies logical consistency between nodes and edges.

Interpret Stage

The validator emits a JSON object containing a diagnostics array. Each diagnostic entry includes a machine-readable code (such as workflow/required-edge), a human-readable message, a JSON path pointing to the offending element, and an optional supportedFixes array listing possible automatic resolutions.

CLI Validation Command Syntax

You can invoke the validator using the packaged skill wrapper or by calling the CLI binary directly.

Using npx skills:

npx skills use tt-a1i/archify@archify --agent codex \
  -- validate workflow examples/agent-tool-call.workflow.json --json

Using the local binary:

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json

Both commands output a JSON receipt to stdout. A successful validation returns "diagnostics": [], while failures return populated diagnostic objects.

Anatomy of a JSON Diagnostic Receipt

When validation fails, Archify returns structured error data that enables automated parsing and fixes. Each diagnostic object contains four key fields:

• code: A namespaced identifier (e.g., workflow/required-edge, workflow/column-capacity) that categorizes the error type
• message: A human-readable description of the violation
• path: A JSON Pointer-style string locating the error within the source document (e.g., /edges/5)
• supportedFixes: An array of strings describing automated remediation options, or an empty array if manual intervention is required

Example diagnostic output:

{
  "diagnostics": [
    {
      "code": "workflow/required-edge",
      "message": "Edge missing between nodes 'Start' → 'Deploy'",
      "path": "/edges/5",
      "supportedFixes": [
        "Add edge from Start to Deploy"
      ]
    },
    {
      "code": "workflow/column-capacity",
      "message": "Column 3 exceeds its capacity of 2 nodes",
      "path": "/columns/3",
      "supportedFixes": []
    }
  ]
}

Validating Workflow Schema and Layout

The validateWorkflow function in archify/renderers/workflow/workflow-compiler.mjs enforces semantic contracts beyond basic JSON schema validation. It checks that required edges exist between nodes, that column capacities are not exceeded, and that all referenced node IDs in edges actually exist in the nodes array.

Minimal valid workflow example (simple.workflow.json):

{
  "diagram_type": "workflow",
  "nodes": [
    { "id": "Start", "label": "Start" },
    { "id": "Build", "label": "Build" },
    { "id": "Deploy", "label": "Deploy" }
  ],
  "edges": [
    { "source": "Start", "target": "Build" },
    { "source": "Build", "target": "Deploy" }
  ]
}

Running validation:

npx skills use tt-a1i/archify@archify --agent codex \
  -- validate workflow simple.workflow.json --json

If the workflow omits a required edge, the validator returns a specific diagnostic:

{
  "diagnostics": [
    {
      "code": "workflow/required-edge",
      "message": "Edge missing between nodes 'Start' → 'Deploy'",
      "path": "/edges/1",
      "supportedFixes": ["Add edge from Start to Deploy"]
    }
  ]
}

Interpreting Diagnostic Codes

Archify uses hierarchical error codes to classify validation failures. The test suite in archify/test/workflow-semantic-contract.test.mjs verifies that these codes trigger correctly under specific violation conditions.

Common diagnostic codes include:

• workflow/required-edge: Indicates a missing connection between mandatory nodes in the flow
• workflow/column-capacity: Signals that a layout column contains more nodes than its configured maximum

The path field uses JSON Pointer syntax to pinpoint errors. For edge-related errors, paths typically follow /edges/<index> patterns, while layout errors reference /columns/<index>.

From Validation to Delivery

Only workflows with an empty diagnostics array should proceed to the delivery stage. The deliver sub-command in archify/renderers/workflow/render-workflow.mjs generates HTML or SVG artifacts from validated JSON.

Complete validation-to-delivery workflow:

# 1. Validate and capture receipt

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --json > receipt.json

# 2. Check if diagnostics array is empty (using jq or similar)

if [ "$(jq '.diagnostics | length' receipt.json)" -eq 0 ]; then
  # 3. Proceed to delivery

  node archify/bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \
    output/agent-tool-call.workflow.html --json
fi

The CI script in scripts/package-smoke.mjs automates this pattern, running validate workflow … --json against both valid and intentionally broken examples to ensure the validation engine catches expected errors.

Summary

• Archify validates workflow diagrams as typed JSON IR before rendering, using the validateWorkflow function in archify/renderers/workflow/workflow-compiler.mjs
• The CLI command archify.mjs validate workflow <file> --json returns a machine-readable receipt containing a diagnostics array
• Each diagnostic includes a code, message, path, and supportedFixes array for automated remediation
• Common error codes include workflow/required-edge for missing connections and workflow/column-capacity for layout violations
• Workflows must return an empty diagnostics array before proceeding to the deliver stage, which generates final HTML/SVG artifacts in archify/renderers/workflow/render-workflow.mjs

Frequently Asked Questions

What does the --json flag return when validation succeeds?

When validation succeeds, the --json flag outputs a JSON object containing "diagnostics": [] along with metadata about the validated workflow. This empty array signals that the workflow meets all schema requirements, layout constraints, and logical consistency checks, making it safe to proceed to the deliver stage for artifact generation.

How do I locate the specific element causing a validation error?

Each diagnostic entry includes a path field formatted as a JSON Pointer (e.g., /edges/5 or /columns/3). This path directly references the location of the violation within the source JSON file, allowing you to navigate immediately to the offending node, edge, or layout configuration without manual searching.

Can Archify automatically fix workflow validation errors?

Archify indicates potential automatic fixes through the supportedFixes array in each diagnostic object. When this array contains entries (such as "Add edge from Start to Deploy"), the CLI may support auto-applying these fixes in future versions or through specific repair flags. However, some errors return empty supportedFixes arrays, requiring manual correction of the source JSON.

Where is the validation logic implemented in the Archify source code?

The core validation logic resides in archify/renderers/workflow/workflow-compiler.mjs, specifically within the validateWorkflow function. This module performs schema validation, layout constraint checking, and logical consistency verification. The corresponding test suite in archify/test/workflow-semantic-contract.test.mjs verifies that diagnostic codes like workflow/required-edge trigger correctly under specific violation conditions.

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