# How to Validate a Diagram Specification with the Archify CLI: Complete Guide > Learn to validate diagram specifications with the Archify CLI. Ensure schema, layout, and rendering accuracy for your architecture, workflow, sequence, dataflow, or lifecycle diagrams. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-08-07 --- **Run `archify validate ` 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: ```bash archify validate [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: ```bash 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: ```bash 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: ```bash 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//render-.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/.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//render-.mjs`** – Type-specific validation and layout logic - **`renderers/shared/generated-validators.mjs`** – Shared schema validators and composition rules - **`schemas/.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 `** 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//render-.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/.schema.json`. These define the valid structure for each diagram type and are referenced by the validators in `renderers/shared/generated-validators.mjs`.