# How to Validate a JSON Diagram Against Its Schema Using Archify

> Learn how to validate JSON diagrams against schemas with Archify's CLI. Get a clear, machine-readable receipt of success or detailed validation errors.

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

---

**Archify provides a self-contained CLI that validates any supported diagram JSON against its type-specific schema and returns a machine-readable JSON receipt indicating success or detailed validation errors.**

The `tt-a1i/archify` repository ships with a schema-driven validation system designed to ensure diagram files conform to strict structural contracts before rendering. By leveraging ahead-of-time compiled validators, Archify checks your JSON against formal JSON Schema definitions stored in the source tree, providing immediate feedback on schema violations.

## How Archify Validates JSON Diagrams

Validation in Archify follows a deterministic pipeline that begins at the CLI entry point and ends with a structured diagnostic report. The system uses pre-generated validators to eliminate runtime dependencies while maintaining strict adherence to the schemas defined in `archify/schemas/`.

### The CLI Entry Point

The validation flow starts in `archify/bin/archify.mjs`, which parses command-line arguments through its internal `usage()` function. When you invoke the `validate` command, the CLI:

1. Reads the input file using `fs.readFileSync` and captures any I/O errors as `inputDiagnostic` messages.
2. Sets the environment variable `ARCHIFY_DIAGNOSTIC_FORMAT=json` to instruct renderers to emit structured output rather than human-readable text.
3. Dispatches to the type-specific renderer (e.g., `render-architecture.mjs`), which imports the generated validator and executes `validator.validate(data)`.

The `rendererFailure()` function in the CLI normalizes any unexpected process failures into the standard diagnostic shape, ensuring consistent error handling across all diagram types.

### Pre-Generated Validator Architecture

Validators are not interpreted at runtime; they are compiled ahead of time by `archify/scripts/generate-validators.mjs`. This build-time script uses **Ajv 2020** to parse every schema in `archify/schemas/` and generate a pure-ESM module at `archify/renderers/shared/generated-validators.mjs`. Because the script produces deterministic, self-contained code without external `require` calls, validation executes rapidly using only the core Node.js runtime.

### Schema Definitions and Supported Types

Archify recognizes five distinct diagram types, each with its own JSON Schema file:

- **architecture** — [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)
- **workflow**
- **sequence**
- **dataflow**
- **lifecycle**

These schemas enforce required fields such as `schema_version`, `diagram_type`, `meta`, and type-specific structures. For example, the architecture schema requires that component `id` values match the regular expression pattern `^[A-Za-z_][A-Za-z0-9_-]*$`.

## Running Schema Validation from the Command Line

You can validate any supported diagram JSON using the Archify CLI. The command syntax requires specifying the diagram type and the path to your JSON file.

### Installation and Basic Usage

If you have not installed Archify globally, add it to your environment:

```bash
npx skills add tt-a1i/archify -g

```

Run validation with the JSON receipt flag:

```bash
archify validate architecture my-diagram.json --json

```

Without the `--json` flag, the CLI prints human-readable validation errors to stderr. With the flag, it returns a structured JSON object to stdout.

### Validating Different Diagram Types

The CLI accepts any of the five supported types as the first positional argument:

```bash

# Validate a workflow diagram

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

# Validate a dataflow diagram and save the receipt

archify validate dataflow examples/rag-pipeline.dataflow.json --json > receipt.json

```

## Interpreting Validation Results

When you pass the `--json` flag, Archify prints a validation receipt containing an `ok` boolean and, on failure, a `diagnostics` array. The `diagnostic()` function in `archify/bin/archify.mjs` formats each schema violation into a consistent structure:

```json
{
  "ok": false,
  "error": "validation failed",
  "diagnostics": [
    {
      "code": "components/0/id",
      "severity": "error",
      "message": "must match pattern \"^[A-Za-z_][A-Za-z0-9_-]*$\"",
      "subject": { "input": "my-diagram.json", "component": 0 },
      "evidence": { "value": "1InvalidId" }
    }
  ]
}

```

Each diagnostic includes:

- **code** — The JSON path to the invalid property
- **severity** — The error level (e.g., "error")
- **message** — The human-readable schema constraint description
- **subject** — Contextual metadata about the location in the input file
- **evidence** — The actual value that violated the constraint

If the diagram is valid, the receipt contains `"ok": true` and an empty diagnostics array.

## Summary

- Archify validates JSON diagrams against type-specific JSON Schemas stored in `archify/schemas/`.
- The CLI entry point at `archify/bin/archify.mjs` orchestrates validation by setting `ARCHIFY_DIAGNOSTIC_FORMAT=json` and invoking type-specific renderers.
- Validators are pre-generated using **Ajv 2020** via `archify/scripts/generate-validators.mjs` and stored in `archify/renderers/shared/generated-validators.mjs` for fast, dependency-free execution.
- The `validate` command accepts five diagram types: `architecture`, `workflow`, `sequence`, `dataflow`, and `lifecycle`.
- Use the `--json` flag to receive a machine-readable receipt with detailed diagnostics pinpointing every schema violation.

## Frequently Asked Questions

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

Archify supports five diagram types: **architecture**, **workflow**, **sequence**, **dataflow**, and **lifecycle**. Each type has a dedicated JSON Schema file located in the `archify/schemas/` directory, ensuring that validators and renderers remain synchronized for every supported format.

### How does Archify generate its validators?

Archify uses the script `archify/scripts/generate-validators.mjs` to compile JSON Schemas into pure-ESM JavaScript modules. This script leverages **Ajv 2020** to create deterministic validator functions that are bundled into `archify/renderers/shared/generated-validators.mjs`, eliminating runtime schema compilation and external dependencies.

### Can I validate diagrams without installing the CLI globally?

Yes. You can run validation using `npx` without a global installation, or install Archify locally within a project. The CLI operates locally regardless of installation method, requiring only a Node.js runtime to execute the pre-generated validators.

### What information is included in a validation error diagnostic?

Each diagnostic object contains a `code` field indicating the JSON path of the error, a `severity` level, a descriptive `message` explaining the constraint violation, a `subject` object identifying the location in the input file, and an `evidence` object showing the actual invalid value. This structure allows automated tools to pinpoint and report schema violations precisely.