# How to Validate JSON IR Generated by AI Agents Using Archify

> Validate AI generated JSON IR with Archify using CLI or AJV for reliable processing. Ensure downstream tools can process agent outputs successfully.

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

---

**Archify validates AI-generated JSON intermediate representation (IR) against strict JSON schemas using either the built-in CLI command `archify validate` or programmatic AJV validation in Node.js to ensure downstream tools can reliably process agent outputs.**

The tt-a1i/archify repository captures AI agent execution plans as structured JSON IR. Before feeding these artifacts into visualization tools or execution engines, you must validate the JSON IR generated by AI agents using Archify to ensure schema compliance and prevent runtime errors.

## Using the Archify CLI for Schema Validation

Archify ships with a command-line interface that bundles the validation schemas and runs a validator powered by AJV. This approach requires no additional code and provides immediate feedback on schema violations.

### Installation and Setup

Install Archify globally to access the CLI from anywhere, or use `npx` to run it without installation:

```bash

# Install globally

npm install -g archify

# Or use npx without installing

npx archify validate path/to/agent-output.json

```

The CLI is defined as the binary entry point in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json), which declares AJV as a core dependency for schema validation.

### Running Validation Commands

Execute the `validate` command followed by the path to your AI-generated JSON IR file:

```bash
archify validate path/to/agent-output.json

```

The CLI prints a success message when the JSON conforms to the schema, or a detailed error list specifying missing required fields, type mismatches, or disallowed enum values. The command automatically detects and applies the correct schema based on the IR type:

- **Workflow IR** – validated against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)
- **Architecture diagrams** – validated against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)
- **Dataflow graphs** – validated against [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)

## Programmatic Validation with AJV

For integration into larger Node.js pipelines or custom agent orchestration logic, import the JSON schemas directly and run AJV programmatically.

### Implementing Schema Validation in Code

First, ensure AJV is installed in your project:

```bash
npm install ajv

```

Then compile the schema and validate the IR:

```javascript
import Ajv from "ajv";
import workflowSchema from "./archify/schemas/workflow.schema.json";
import fs from "fs";

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(workflowSchema);

// Load the IR that an AI model just produced
const ir = JSON.parse(fs.readFileSync("agent-output.json", "utf8"));

const valid = validate(ir);
if (valid) {
  console.log("✅ JSON IR is valid!");
} else {
  console.error("❌ JSON IR failed validation:");
  console.error(validate.errors);
}

```

Replace `workflowSchema` with [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) or [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) depending on the specific IR variant your agent generated. The `allErrors: true` configuration ensures you capture all validation failures in a single pass rather than stopping at the first error.

## Understanding the Schema Structure

Archify provides strict type definitions for three primary IR categories, each stored in the `archify/schemas/` directory:

- **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)** – Defines structure for workflow IR including nodes, edges, and tool calls
- **[`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)** – Schema for high-level architecture diagrams and system components
- **[`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)** – Schema for data-flow graph IR representing information pipelines

These schemas enforce type safety for fields such as node identifiers, connection types, and metadata attributes, ensuring that AI-generated plans contain all necessary execution context.

## Integrating Validation into CI/CD Pipelines

The repository includes `scripts/run-tests.mjs`, which executes the test suite including schema validation checks. You can incorporate validation into your deployment pipeline by invoking this script or by running the CLI validation step as a pre-deployment gate:

```bash

# Example CI step

archify validate ./output/agent-plan.json || exit 1

```

This prevents malformed IR from reaching production execution environments or visualization dashboards.

## Summary

- **Archify CLI** provides immediate validation via `archify validate <file>` without requiring code changes
- **Programmatic validation** uses AJV with schemas from `archify/schemas/` for embedded pipeline integration
- **Three schema types** cover workflows ([`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)), architectures ([`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)), and dataflows ([`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json))
- **Early validation** prevents runtime errors in downstream visualization and execution tools

## Frequently Asked Questions

### What is JSON IR in the context of Archify?

JSON IR (Intermediate Representation) is the structured JSON format that Archify uses to capture AI agent execution plans. It serves as a standardized bridge between AI-generated outputs and downstream processing tools like visualizers, exporters, or runtime executors.

### Can I validate multiple JSON IR files at once using the Archify CLI?

The Archify CLI processes one file per invocation. To batch validate multiple files, wrap the command in a shell loop or use a Node.js script that iterates over files and calls the AJV validation logic programmatically.

### Which Node.js versions are compatible with Archify's validation features?

Archify relies on modern ES modules syntax (`import` statements) and AJV v8 or higher. Node.js versions 14.x and above support these features, though 16.x or later is recommended for full ES module compatibility without additional configuration flags.

### How do I extend the built-in schemas for custom agent behaviors?

Copy the base schema from [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (or the relevant variant) to your project directory, modify the definitions to include your custom fields, and reference your local schema file when calling `ajv.compile()` instead of the built-in import path.