# How to Validate a Diagram JSON File Using the Archify CLI > Easily validate Archify diagram JSON files with the CLI. Learn the simple command to check your files against the AJV schema and get structured error reports. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: how-to-guide - Published: 2026-07-13 --- **To validate a diagram JSON file using the Archify CLI, run `archify validate ` which checks the file against the AJV schema for the specified diagram type and reports structured errors if validation fails.** The `tt-a1i/archify` repository provides a dedicated command-line interface for validating diagram specifications before rendering. This ensures your **architecture**, **workflow**, **sequence**, **dataflow**, or **lifecycle** diagrams conform to the expected JSON schema, catching structural errors early in your development pipeline. ## The `validate` Command Syntax The validation command follows a consistent pattern across all diagram types. You must specify the diagram type as the first argument, followed by the path to your JSON file. ```bash archify validate ``` Supported diagram types include `architecture`, `workflow`, `sequence`, `dataflow`, and `lifecycle`. The CLI entry point in `bin/archify.mjs` parses these sub-commands and routes them to the appropriate validation handlers. ## How Validation Works Under the Hood Understanding the validation pipeline helps you debug schema failures effectively. The process involves three distinct stages implemented across the shared renderer modules. ### Loading the Diagram File When you execute the validate command, the CLI first invokes `loadDiagram` from **`archify/renderers/shared/cli.mjs`**. This utility reads the specified JSON file (or falls back to a default example) and parses it into a JavaScript object. The function handles file system operations and basic JSON parsing before passing the data to the validator. ### Schema Validation Logic The core validation occurs in **`archify/renderers/shared/validator.mjs`**, which exports `validateSchema`. This function selects the appropriate **AJV validator** generated for the requested diagram type from `generated-validators.mjs`. It executes the compiled schema against your diagram object, checking type constraints, required fields, and relationship definitions. If the JSON structure violates the schema, the validator captures detailed error objects containing JSON pointer paths to the invalid properties. ### Error Formatting and Output Validation results are processed through `formatErrors` in the same validator module. The CLI presents errors in two formats: - **Human-readable**: Annotated paths with descriptive messages (e.g., `/edges/0/to unknown target "ghost"`) - **Machine-readable**: Structured JSON output when using the `--json` flag, suitable for CI integration The test suite in **`archify/test/cli.test.mjs`** demonstrates both output formats and verifies the exit code behavior for valid versus invalid inputs. ## Practical Examples ### Basic Validation Validate a workflow diagram from the examples directory to verify it meets the schema requirements: ```bash archify validate workflow examples/agent-tool-call.workflow.json ``` A successful validation prints a confirmation message indicating the workflow schema validation passed. ### Machine-Readable JSON Output For automation scripts or CI pipelines, request structured output using the `--json` flag: ```bash archify validate workflow examples/agent-tool-call.workflow.json --json ``` This returns a JSON object containing validation status, diagram type metadata, and check results: ```json {"ok":true,"type":"workflow","checks":[...],"meta":{...}} ``` ### Handling Validation Errors When validation fails, the CLI provides detailed error reporting. Consider an invalid target reference: ```bash archify validate workflow examples/bad.workflow.json ``` The output from `formatErrors` displays specific violations: ```text /edges/0/to unknown target "ghost" ``` Each error includes the JSON pointer path and a descriptive message, allowing you to locate and fix schema violations quickly. ## Summary - **Use `archify validate `** to verify diagram JSON against type-specific schemas. - **Validation relies on AJV validators** generated in `generated-validators.mjs` and executed via `validateSchema` in `archify/renderers/shared/validator.mjs`. - **File loading** is handled by `loadDiagram` in `archify/renderers/shared/cli.mjs`. - **Add `--json`** for machine-readable output suitable for automated testing and CI/CD integration. - **Error messages** include JSON pointer paths to help you pinpoint exactly where your diagram JSON violates the schema. ## Frequently Asked Questions ### What diagram types does Archify support for validation? Archify supports validation for five diagram types: **architecture**, **workflow**, **sequence**, **dataflow**, and **lifecycle**. Each type has a dedicated AJV validator compiled from JSON schema definitions, allowing the CLI to enforce type-specific structural requirements. ### How does Archify CLI report validation errors? Archify reports errors through the `formatErrors` function in `archify/renderers/shared/validator.mjs`. Errors include annotated JSON pointer paths (e.g., `/edges/0/target`) and descriptive messages indicating which constraints failed. By default, output is human-readable, but you can use `--json` to receive structured error data for programmatic processing. ### Can I use Archify validation in CI/CD pipelines? Yes. Run `archify validate --json` to receive machine-readable exit codes and structured output. The CLI exits with non-zero status on validation failures, and the JSON format allows build scripts to parse results without regex matching on human-readable text. ### Where are the validation schemas defined in the source code? The validation schemas are implemented in **`archify/renderers/shared/validator.mjs`** using pre-compiled AJV validators imported from `generated-validators.mjs`. The `validateSchema` function selects the appropriate validator based on the diagram type argument you provide to the CLI command.