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

Run archify validate <type> <input.json> to check schema validity, layout rules, and rendering output for architecture, workflow, sequence, dataflow, or lifecycle diagrams.

The Archify CLI provides a deterministic validation pipeline that ensures your diagram specifications are well-formed before rendering. This guide explains how to use the validate command with all available options, based on the source code in tt-a1i/archify.

Understanding the Archify Validate Command

The validate subcommand is implemented in archify/bin/archify.mjs. It performs atomic validation by executing a type-specific renderer as a child process and parsing the diagnostic output.

The supported diagram types are:

• architecture – system and component diagrams
• workflow – process and decision flows
• sequence – interaction diagrams
• dataflow – data movement diagrams
• lifecycle – state transition diagrams

Syntax and Options

The basic command structure follows this pattern:

archify validate <type> <input.json> [options]

Available flags:

Flag	Description	Use Case
--json	Output machine-readable JSON receipt	CI/CD pipelines, automated testing
--layout-json	Return raw layout JSON (architecture only)	Advanced tooling, custom renderers

Running Validation: Practical Examples

Basic Validation with Human-Readable Output

The default mode prints user-friendly error messages and exits silently on success:

archify validate architecture examples/web-app.architecture.json

If validation fails, you'll see a formatted summary of schema errors, layout violations, or rendering issues.

Machine-Readable Output for Automation

The --json flag sets ARCHIFY_DIAGNOSTIC_FORMAT=json in the renderer's environment and returns the full receipt as JSON:

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

This output is ideal for:

• GitHub Actions workflows
• Pre-commit hooks
• Custom reporting tools

Extracting Layout Data for Architecture Diagrams

The --layout-json flag (valid only for architecture type) returns the computed layout structure:

archify validate architecture examples/web-app.architecture.json --layout-json

Use this for integrating Archify's layout engine with custom visualization tools.

How Validation Works Internally

The validation flow in archify/bin/archify.mjs follows four stages:

1. Parse arguments – Extract diagram type, input path, and flags
2. Load renderer – Resolve via rendererPath(type) to renderers/<type>/render-<type>.mjs
3. Execute renderer – Spawn child process with environment variables; capture JSON receipt containing diagnostics
4. Report results – Format output via reportValidateFailure for --json or human-readable summary otherwise

If the child process exits non-zero, the receipt is parsed and transformed into actionable error messages.

What Gets Validated

According to renderers/shared/generated-validators.mjs, the validator checks:

• Schema validity – Against schemas/<type>.schema.json definitions
• Layout rules – Component positioning, spacing, and alignment constraints
• HTML/SVG rendering – Output generation and structural integrity
• Route clearance – Connection path validity for diagrams with flows

The final checks are performed by scripts/check-render-output.mjs, which verifies SVG/HTML consistency and production readiness.

Key Source Files

Understanding these files helps when debugging validation failures:

• archify/bin/archify.mjs – CLI entry point; command parsing and diagnostic formatting
• renderers/<type>/render-<type>.mjs – Type-specific validation and layout logic
• renderers/shared/generated-validators.mjs – Shared schema validators and composition rules
• schemas/<type>.schema.json – JSON Schema definitions for each diagram type
• scripts/check-render-output.mjs – Post-rendering consistency checks

Exit Codes and Error Handling

Exit Code	Meaning
0	Validation passed, specification is valid
Non-zero	Validation failed; check output for diagnostic details

When --json is used, parse the receipt for structured error data including file locations, rule violations, and suggested fixes.

Summary

• Use archify validate <type> <file> for standard validation with human-readable output
• Add --json for machine-readable receipts in CI/CD pipelines
• Use --layout-json with architecture diagrams to extract computed layouts
• Validation covers schema, layout, rendering, and composition rules via generated-validators.mjs
• The renderer-based architecture ensures type-specific validation logic stays maintainable

Frequently Asked Questions

What diagram types does Archify validate?

Archify validates architecture, workflow, sequence, dataflow, and lifecycle diagrams. Each type has dedicated validation logic in its renderer at renderers/<type>/render-<type>.mjs.

How do I integrate validation into CI/CD pipelines?

Use the --json flag to get structured output that your pipeline can parse. The command returns exit code 0 on success and non-zero on failure, with full diagnostic details in the JSON receipt.

Why does architecture validation support --layout-json but other types don't?

Architecture diagrams have complex automatic layout computation that external tools may need to access. The flag exposes this internal structure from render-architecture.mjs; other diagram types either lack comparable layout engines or expose layout data through different mechanisms.

Where are the JSON Schema definitions located?

Schema files are in archify/schemas/<type>.schema.json. These define the valid structure for each diagram type and are referenced by the validators in renderers/shared/generated-validators.mjs.

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