How to Validate JSON IR Generated by AI Agents Using Archify

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:

# 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, 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:

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
• Architecture diagrams – validated against archify/schemas/architecture.schema.json
• Dataflow graphs – validated against 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:

npm install ajv

Then compile the schema and validate the IR:

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 or 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 – Defines structure for workflow IR including nodes, edges, and tool calls
• archify/schemas/architecture.schema.json – Schema for high-level architecture diagrams and system components
• 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:

# 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), architectures (architecture.schema.json), and dataflows (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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}