# How to Validate a Candidate JSON IR File Using the Archify CLI

> Validate JSON IR files with the Archify CLI. Use `archify validate` to check schema compliance and rendering pipeline compatibility for structured diagnostics. Learn more!

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

---

**Use `archify validate <type> <path-to-json-ir> [--json]` to check JSON IR files against Archify's schema and rendering pipeline, with structured diagnostics output for both success and failure cases.**

Archify provides a command-line interface for validating **candidate JSON IR files** before they are used in production diagrams. The validation command performs schema checking, geometric constraint validation, and render verification. This article explains how to use the Archify CLI validate command with practical examples drawn from the source code.

## The `archify validate` Command Syntax

The validation command follows a consistent pattern across IR types:

```bash
archify validate <type> <path-to-json-ir> [--json]

```

**Parameters:**
- `<type>` — either `workflow` or `architecture`, matching Archify's two top-level IR schemas.
- `<path-to-json-ir>` — path to the JSON IR file to validate.
- `--json` — optional flag to emit machine-readable output on stdout.

When invoked, the command executes two validation layers:

1. **Schema and layout validation** — parses the JSON against the Archify schema and checks geometric constraints (edge crossing, node overlap, reserved regions).
2. **Render verification** — generates a temporary HTML/SVG artifact and runs the internal check pipeline to confirm rendered output matches intent.

## JSON Output Format with `--json`

The `--json` flag produces a structured diagnostic object:

```json
{
  "ok": true,
  "checks": [],
  "composition": { }
}

```

**Fields:**
- `ok` — boolean indicating validation success or failure.
- `checks` — array of diagnostic messages (errors, warnings, or info).
- `composition` — trimmed diagram representation for downstream tooling.

**Critical behavior:** Archify returns a non-zero exit code on validation failure while still outputting the JSON payload. This allows programmatic inspection of failures without losing structured error data.

## Code Examples

### Validate a Workflow IR File from the Shell

```bash

# Get machine-readable validation report

archify validate workflow examples/rag-pipeline.architecture.json --json

```

This command validates a workflow IR file and prints JSON diagnostics. The example file is located at [`examples/rag-pipeline.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/rag-pipeline.architecture.json) in the repository.

### Programmatic Validation in Node.js

The smoke test suite demonstrates programmatic validation using helper functions:

```js
// From scripts/package-smoke.mjs — testing invalid input rejection
const failure = JSON.parse(
  runExpectFailure(['validate', 'workflow', invalidPath, '--json'])
);
// failure.ok === false
// failure.checks contains detailed error descriptions

```

This pattern captures validation failures for assertion in automated tests.

### Validating Architecture IR Files

```js
// From scripts/package-smoke.mjs — testing valid architecture IR
const result = JSON.parse(
  runExpectSuccess(['validate', 'architecture', archPath, '--json'])
);

if (result.ok) {
  console.log('✅ Architecture IR is valid!');
} else {
  console.error('Validation failed:', result.checks);
}

```

The same validation pattern applies to architecture-type IR files. The smoke tests verify both success and failure paths for architecture validation.

## Key Implementation Files

### CLI Entry Point: `archify/bin/archify.mjs`

The `archify.mjs` binary parses sub-commands and routes to the validate implementation. It handles argument parsing, invokes the validation pipeline, and formats the JSON receipt output.

### Test Harness: `scripts/package-smoke.mjs`

Contains working examples of `validate` command invocation. Lines 256 and 280 demonstrate failure and success cases respectively, showing how to capture and parse JSON diagnostics programmatically.

### Documentation: [`docs/research-visual-evolution-round-44.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-44.md)

Documents the CLI contract for `archify validate <type> <input> --json` and specifies the JSON output structure including all field definitions.

### Example IR File: [`examples/rag-pipeline.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/rag-pipeline.architecture.json)

A concrete JSON IR file suitable for testing validation commands.

## Error Handling and Exit Codes

Archify's validate command guarantees consistent behavior for automation:

- **Exit code 0** — validation passed (`ok: true`).
- **Non-zero exit code** — validation failed (`ok: false`), but JSON output is still produced.

This design supports CI/CD pipelines and test suites that need to distinguish success from failure while preserving full diagnostic information.

## Summary

- Use `archify validate <type> <file> --json` to validate JSON IR files with structured output.
- Add `--json` for machine-readable diagnostics in the `ok`/`checks`/`composition` format.
- Parse failures programmatically — Archify always outputs JSON even when returning non-zero exit codes.
- Reference `scripts/package-smoke.mjs` for production-ready validation patterns in automated tests.

## Frequently Asked Questions

### What IR types does Archify validate?

Archify validates two IR types: **workflow** and **architecture**. These correspond to the two top-level schemas used throughout the codebase. Specify the type as the first argument to the validate command.

### Does Archify validate work without the `--json` flag?

Yes. Without `--json`, the CLI prints human-readable status messages to stderr/stdout. However, `--json` is recommended for automation, CI pipelines, and programmatic error handling since it provides structured, parseable output.

### How do I capture validation errors in a script?

Always use `--json` and parse stdout. Even on validation failure, Archify outputs valid JSON with `ok: false` and a populated `checks` array describing the problems. Check the exit code to determine pass/fail status while using the JSON payload for detailed diagnostics.

### Where is the validate command implemented?

The command routing and JSON formatting logic resides in `archify/bin/archify.mjs`. The underlying validation pipeline (schema checking, layout validation, render verification) is invoked from this entry point.