How to Validate a Diagram JSON File Using the Archify CLI

To validate a diagram JSON file using the Archify CLI, run archify validate <type> <file.json> which checks the file against the AJV schema for the specified diagram type and reports structured errors if validation fails.

The tt-a1i/archify repository provides a dedicated command-line interface for validating diagram specifications before rendering. This ensures your architecture, workflow, sequence, dataflow, or lifecycle diagrams conform to the expected JSON schema, catching structural errors early in your development pipeline.

The validate Command Syntax

The validation command follows a consistent pattern across all diagram types. You must specify the diagram type as the first argument, followed by the path to your JSON file.

archify validate <type> <path-to-diagram.json>

Supported diagram types include architecture, workflow, sequence, dataflow, and lifecycle. The CLI entry point in bin/archify.mjs parses these sub-commands and routes them to the appropriate validation handlers.

How Validation Works Under the Hood

Understanding the validation pipeline helps you debug schema failures effectively. The process involves three distinct stages implemented across the shared renderer modules.

Loading the Diagram File

When you execute the validate command, the CLI first invokes loadDiagram from archify/renderers/shared/cli.mjs. This utility reads the specified JSON file (or falls back to a default example) and parses it into a JavaScript object. The function handles file system operations and basic JSON parsing before passing the data to the validator.

Schema Validation Logic

The core validation occurs in archify/renderers/shared/validator.mjs, which exports validateSchema. This function selects the appropriate AJV validator generated for the requested diagram type from generated-validators.mjs. It executes the compiled schema against your diagram object, checking type constraints, required fields, and relationship definitions.

If the JSON structure violates the schema, the validator captures detailed error objects containing JSON pointer paths to the invalid properties.

Error Formatting and Output

Validation results are processed through formatErrors in the same validator module. The CLI presents errors in two formats:

• Human-readable: Annotated paths with descriptive messages (e.g., /edges/0/to unknown target "ghost")
• Machine-readable: Structured JSON output when using the --json flag, suitable for CI integration

The test suite in archify/test/cli.test.mjs demonstrates both output formats and verifies the exit code behavior for valid versus invalid inputs.

Practical Examples

Basic Validation

Validate a workflow diagram from the examples directory to verify it meets the schema requirements:

archify validate workflow examples/agent-tool-call.workflow.json

A successful validation prints a confirmation message indicating the workflow schema validation passed.

Machine-Readable JSON Output

For automation scripts or CI pipelines, request structured output using the --json flag:

archify validate workflow examples/agent-tool-call.workflow.json --json

This returns a JSON object containing validation status, diagram type metadata, and check results:

{"ok":true,"type":"workflow","checks":[...],"meta":{...}}

Handling Validation Errors

When validation fails, the CLI provides detailed error reporting. Consider an invalid target reference:

archify validate workflow examples/bad.workflow.json

The output from formatErrors displays specific violations:

/edges/0/to unknown target "ghost"

Each error includes the JSON pointer path and a descriptive message, allowing you to locate and fix schema violations quickly.

Summary

• Use archify validate <type> <file.json> to verify diagram JSON against type-specific schemas.
• Validation relies on AJV validators generated in generated-validators.mjs and executed via validateSchema in archify/renderers/shared/validator.mjs.
• File loading is handled by loadDiagram in archify/renderers/shared/cli.mjs.
• Add --json for machine-readable output suitable for automated testing and CI/CD integration.
• Error messages include JSON pointer paths to help you pinpoint exactly where your diagram JSON violates the schema.

Frequently Asked Questions

What diagram types does Archify support for validation?

Archify supports validation for five diagram types: architecture, workflow, sequence, dataflow, and lifecycle. Each type has a dedicated AJV validator compiled from JSON schema definitions, allowing the CLI to enforce type-specific structural requirements.

How does Archify CLI report validation errors?

Archify reports errors through the formatErrors function in archify/renderers/shared/validator.mjs. Errors include annotated JSON pointer paths (e.g., /edges/0/target) and descriptive messages indicating which constraints failed. By default, output is human-readable, but you can use --json to receive structured error data for programmatic processing.

Can I use Archify validation in CI/CD pipelines?

Yes. Run archify validate <type> <file> --json to receive machine-readable exit codes and structured output. The CLI exits with non-zero status on validation failures, and the JSON format allows build scripts to parse results without regex matching on human-readable text.

Where are the validation schemas defined in the source code?

The validation schemas are implemented in archify/renderers/shared/validator.mjs using pre-compiled AJV validators imported from generated-validators.mjs. The validateSchema function selects the appropriate validator based on the diagram type argument you provide to the CLI command.

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