# How to Validate JSON Input for Archify Diagrams

> Learn to validate Archify diagram JSON inputs using the archify validate command. Get human-readable messages or JSON reports for CI.

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

---

**Use the `archify validate` command to check diagram JSON files against type-specific AJV schemas, with support for human-readable success messages or machine-readable JSON reports for CI integration.**

Validating JSON input for Archify diagrams ensures your architecture, workflow, sequence, dataflow, or lifecycle definitions conform to the expected schema before rendering. The `tt-a1i/archify` repository provides a dedicated CLI command that leverages auto-generated AJV validators to verify syntax and structure. This guide explains how to use the validation pipeline, interpret error messages, and integrate checks into your development workflow.

## The `archify validate` Command

The CLI exposes a `validate` subcommand that performs three distinct operations: loading the JSON file, executing the appropriate schema validator, and formatting the results. Located in the entry point at `bin/archify.mjs`, this command delegates to shared utilities in `archify/renderers/shared/cli.mjs` and `archify/renderers/shared/validator.mjs`.

When you invoke the command, the system:

1. **Loads the diagram** using `loadDiagram`, which reads the specified file or defaults to an example file if none is provided.
2. **Selects the validator** via `validateSchema`, picking the AJV validator from `generated-validators.mjs` that corresponds to your diagram type.
3. **Reports results** through `formatErrors`, which converts validation failures into annotated JSON-pointer paths with line and column information.

## Step-by-Step Validation Workflow

### Loading Diagrams with `loadDiagram`

The `loadDiagram` function, implemented in `archify/renderers/shared/cli.mjs`, handles file system operations and JSON parsing. It accepts a file path argument and returns a parsed JavaScript object ready for validation.

### Schema Validation with `validateSchema`

The core validation logic resides in `archify/renderers/shared/validator.mjs`. The `validateSchema` function imports the pre-compiled AJV validators from `generated-validators.mjs` and executes the specific validator for the requested diagram type. This approach ensures high-performance validation without runtime schema compilation.

### Error Formatting and Reporting

When validation fails, the `formatErrors` function generates human-readable messages that include JSON-pointer paths (e.g., `/edges/0/to`) indicating exactly where the error occurred. The CLI catches these errors and prints them to stderr with exit codes appropriate for scripting environments.

## Supported Diagram Types

Archify supports validation for five distinct diagram categories:

- **architecture** - System architecture diagrams
- **workflow** - Process and agent-tool-call workflows  
- **sequence** - Sequence diagrams for interactions
- **dataflow** - Data flow diagrams
- **lifecycle** - Lifecycle state diagrams

## CLI Usage Examples

Validate a workflow diagram with default human-readable output:

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

```

Generate a machine-readable JSON report for CI integration:

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

```

Validate any supported diagram type by replacing `<type>` with the appropriate category:

```bash
archify validate <type> path/to/diagram.json

```

Example of a validation failure showing JSON-pointer error paths:

```bash
archify validate workflow examples/bad.workflow.json

# Output:

# /edges/0/to unknown target "ghost"

# ... (additional line/column info)

```

## Key Source Files

The validation system spans several critical files in the repository:

- **`archify/renderers/shared/validator.mjs`** - Contains `validateSchema` and `formatErrors` functions that execute AJV validation and format error messages.
- **`archify/renderers/shared/cli.mjs`** - Implements `loadDiagram` and other CLI utilities used by the validate command.
- **`bin/archify.mjs`** - Entry point that parses the `validate` subcommand and wires it to validation logic.
- **`archify/test/cli.test.mjs`** - Test suite demonstrating expected exit codes and JSON output shapes for the validate command.

## Summary

- Use `archify validate <type> <file>` to check JSON input against type-specific schemas.
- The validation pipeline uses `loadDiagram` to parse files, `validateSchema` to run AJV validators from `generated-validators.mjs`, and `formatErrors` to annotate failures.
- Append `--json` to receive machine-readable output suitable for CI pipelines.
- Supported types include architecture, workflow, sequence, dataflow, and lifecycle.
- Error messages include JSON-pointer paths (e.g., `/edges/0/to`) for precise debugging.

## Frequently Asked Questions

### How do I validate an Archify diagram JSON file from the command line?

Run the `archify validate` command followed by the diagram type and file path. For example, `archify validate workflow diagram.json` checks the file against the workflow schema. The command exits with code 0 on success or a non-zero code on failure, making it suitable for pre-commit hooks and CI scripts.

### What diagram types does Archify support for validation?

Archify supports validation for five diagram types: **architecture**, **workflow**, **sequence**, **dataflow**, and **lifecycle**. Each type uses a distinct AJV validator generated from its JSON schema, ensuring type-specific validation rules are enforced.

### How can I get machine-readable validation output for CI pipelines?

Append the `--json` flag to any validate command to receive structured JSON output instead of human-readable text. This outputs an object with `ok`, `type`, `checks`, and `meta` properties that CI systems can parse programmatically, as demonstrated in `archify/test/cli.test.mjs`.

### Where does Archify store the validation schema logic?

The validation logic resides in `archify/renderers/shared/validator.mjs`, which imports pre-compiled validators from `generated-validators.mjs`. The CLI entry point at `bin/archify.mjs` and shared utilities in `archify/renderers/shared/cli.mjs` orchestrate the validation process.