# How to Validate a Workflow Diagram with JSON Diagnostics Using Archify

> Validate workflow diagrams with Archify's JSON diagnostics. Inspect schema, layout, and logical consistency for auto-fixing issues before rendering.

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

---

**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:**

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

```

**Using the local binary:**

```bash
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:**

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/simple.workflow.json)):**

```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:**

```bash
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:

```json
{
  "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:**

```bash

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