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

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:

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

Practical examples:

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

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

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