# How to Validate Archify JSON IR Using the Built-in CLI

> Learn to validate Archify JSON IR using the CLI. Run archify validate with your diagram type and file path to check schema compliance and get JSON receipts.

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

---

**Use the `archify validate` command with a diagram type and file path to verify that your JSON Intermediate Representation conforms to Archify's schema, returning structured diagnostics via JSON receipts.**

Archify stores architectural artifacts as JSON-based Intermediate Representation (IR) files within the `tt-a1i/archify` repository. To ensure your workflow, architecture, or dataflow documents are structurally sound before visualization, you must validate Archify JSON IR against the project's strict schema definitions. The CLI provides a dedicated validation pipeline that checks syntax, schema compliance, and optional quality rules.

## Using the Archify CLI Validate Command

The primary interface for validation is the `archify validate` command, which accepts a diagram type and file path.

Supported diagram types include:

- **workflow** – Agent execution flows and tool-call sequences
- **architecture** – System component diagrams and repo structures
- **dataflow** – Data movement and transformation pipelines
- **legend** – Visual legend definitions

Basic syntax:

```bash
archify validate <diagram-type> <path-to-ir.json> [options]

```

Practical examples:

```bash

# Validate a workflow IR file

archify validate workflow path/to/my-workflow.json --json

# Validate an architecture with repository context

archify validate architecture path/to/arch.json --repo-root /my/repo --json

# Validate dataflow with quality checks

archify validate dataflow path/to/flow.json --quality showcase --json

```

The `--repo-root` flag resolves relative asset references, while `--quality` enables optional readability diagnostics.

## Inside the Validation Pipeline

When you run the validate command, the CLI executes a five-stage pipeline defined in `archify/renderers/shared/validator.mjs`.

### Stage 1: IR Loading

The CLI reads the specified JSON file into memory, parsing it as raw data.

### Stage 2: Schema Dispatch

The `validateSchema(diagramType, data)` function selects the appropriate JSON Schema validator for the requested diagram type. According to the source code in `archify/renderers/shared/validator.mjs`, this function throws an error for unknown diagram types immediately【/archify/renderers/shared/validator.mjs#L38-L41】.

### Stage 3: Schema Validation

The validator runs AJV (or similar) against type-specific JSON Schema definitions bundled with the package. This catches structural errors, type mismatches, and missing required fields.

### Stage 4: Receipt Generation

When `--json` is supplied, the CLI produces a structured receipt containing:
- `ok`: Boolean validation status
- `diagnostics`: Array of error objects with codes and messages
- `metadata`: Optional context about the validation run

### Stage 5: Exit Code Reporting

The process exits with code `0` for valid IR or non-zero for failures, enabling shell scripting integration.

## Handling Validation Output

The JSON receipt format provides machine-readable diagnostics for downstream tooling. As demonstrated in `archify/test/repair-receipt.test.mjs`, failed validations include diagnostic objects with specific error codes like `clean-flow/edge-through-node` and contextual messages【/archify/test/repair-receipt.test.mjs#L117-L124】.

Example receipt parsing:

```bash

# Validate and inspect results with jq

archify validate workflow examples/workflow-agent-tool-call.json --json | jq .

# Capture receipt to file

archify validate architecture examples/archify-repo.architecture.json \
  --repo-root . --json > receipt.json

# Use exit status in automation

if archify validate dataflow my-flow.json --json >/dev/null; then
  echo "✅ Dataflow IR is valid"
else
  echo "❌ Dataflow IR contains errors"
fi

```

## Core Validation Architecture

Several key files implement the validation logic:

- **`archify/renderers/shared/validator.mjs`** – Exports `validateSchema()`, the central dispatcher that routes diagram types to their respective validators【/archify/renderers/shared/validator.mjs#L38-L41】.

- **`archify/scripts/update-contract.mjs`** – Contains helper validators for domain-specific constraints like `validateCanonicalUtcTimestamp` for temporal data【/archify/scripts/update-contract.mjs#L92-L104】.

- **`archify/test/workflow-migration.test.mjs`** – Demonstrates CLI invocation via `spawnSync`, showing how the validate command is executed programmatically【/archify/test/workflow-migration.test.mjs#L52-L58】.

The CLI entry point is defined in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json), which registers the `archify` binary for global or local execution.

## Summary

- Use **`archify validate <type> <file>`** to check JSON IR files against Archify's schemas.
- Supported types include **workflow**, **architecture**, **dataflow**, and **legend**.
- The **`--json`** flag outputs structured receipts with diagnostics and exit codes for CI/CD integration.
- Validation logic resides in **`archify/renderers/shared/validator.mjs`**, which dispatches to type-specific AJV validators.
- Non-zero exit codes indicate validation failures with specific error codes like `clean-flow/edge-through-node`.

## Frequently Asked Questions

### What diagram types support validation in Archify?

Archify supports validating four diagram types: **workflow** (agent execution flows), **architecture** (system structures), **dataflow** (pipelines), and **legend** (visual definitions). The validator rejects unknown types immediately at the dispatch stage in `validator.mjs`.

### How do I interpret validation error codes?

Error codes appear in the `diagnostics` array of the JSON receipt, formatted as scoped strings like `clean-flow/edge-through-node`. Each diagnostic includes a human-readable message and contextual data pointing to the specific location in your IR file that violates the schema.

### Can I validate Archify IR files in a CI/CD pipeline?

Yes. The CLI returns exit code `0` for valid IR and non-zero for failures, making it ideal for continuous integration. Use the `--json` flag to capture structured receipts for build artifacts, or redirect stdout to `/dev/null` in shell scripts for silent status checks.

### Where are the JSON Schema definitions stored?

The schemas are bundled within the Archify package and referenced by the `validateSchema()` function in `archify/renderers/shared/validator.mjs`. Each diagram type has a dedicated schema definition that enforces structural requirements, type constraints, and optional quality rules based on the `--quality` flag.