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

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:

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:

{
  "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

# 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 in the repository.

Programmatic Validation in Node.js

The smoke test suite demonstrates programmatic validation using helper functions:

// 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

// 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

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

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.

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