How to Validate JSON Input for Archify Diagrams

Use the archify validate command to check diagram JSON files against type-specific AJV schemas, with support for human-readable success messages or machine-readable JSON reports for CI integration.

Validating JSON input for Archify diagrams ensures your architecture, workflow, sequence, dataflow, or lifecycle definitions conform to the expected schema before rendering. The tt-a1i/archify repository provides a dedicated CLI command that leverages auto-generated AJV validators to verify syntax and structure. This guide explains how to use the validation pipeline, interpret error messages, and integrate checks into your development workflow.

The archify validate Command

The CLI exposes a validate subcommand that performs three distinct operations: loading the JSON file, executing the appropriate schema validator, and formatting the results. Located in the entry point at bin/archify.mjs, this command delegates to shared utilities in archify/renderers/shared/cli.mjs and archify/renderers/shared/validator.mjs.

When you invoke the command, the system:

1. Loads the diagram using loadDiagram, which reads the specified file or defaults to an example file if none is provided.
2. Selects the validator via validateSchema, picking the AJV validator from generated-validators.mjs that corresponds to your diagram type.
3. Reports results through formatErrors, which converts validation failures into annotated JSON-pointer paths with line and column information.

Step-by-Step Validation Workflow

Loading Diagrams with loadDiagram

The loadDiagram function, implemented in archify/renderers/shared/cli.mjs, handles file system operations and JSON parsing. It accepts a file path argument and returns a parsed JavaScript object ready for validation.

Schema Validation with validateSchema

The core validation logic resides in archify/renderers/shared/validator.mjs. The validateSchema function imports the pre-compiled AJV validators from generated-validators.mjs and executes the specific validator for the requested diagram type. This approach ensures high-performance validation without runtime schema compilation.

Error Formatting and Reporting

When validation fails, the formatErrors function generates human-readable messages that include JSON-pointer paths (e.g., /edges/0/to) indicating exactly where the error occurred. The CLI catches these errors and prints them to stderr with exit codes appropriate for scripting environments.

Supported Diagram Types

Archify supports validation for five distinct diagram categories:

• architecture - System architecture diagrams
• workflow - Process and agent-tool-call workflows
• sequence - Sequence diagrams for interactions
• dataflow - Data flow diagrams
• lifecycle - Lifecycle state diagrams

CLI Usage Examples

Validate a workflow diagram with default human-readable output:

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

Generate a machine-readable JSON report for CI integration:

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

Validate any supported diagram type by replacing <type> with the appropriate category:

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

Example of a validation failure showing JSON-pointer error paths:

archify validate workflow examples/bad.workflow.json

# Output:

# /edges/0/to unknown target "ghost"

# ... (additional line/column info)

Key Source Files

The validation system spans several critical files in the repository:

• archify/renderers/shared/validator.mjs - Contains validateSchema and formatErrors functions that execute AJV validation and format error messages.
• archify/renderers/shared/cli.mjs - Implements loadDiagram and other CLI utilities used by the validate command.
• bin/archify.mjs - Entry point that parses the validate subcommand and wires it to validation logic.
• archify/test/cli.test.mjs - Test suite demonstrating expected exit codes and JSON output shapes for the validate command.

Summary

• Use archify validate <type> <file> to check JSON input against type-specific schemas.
• The validation pipeline uses loadDiagram to parse files, validateSchema to run AJV validators from generated-validators.mjs, and formatErrors to annotate failures.
• Append --json to receive machine-readable output suitable for CI pipelines.
• Supported types include architecture, workflow, sequence, dataflow, and lifecycle.
• Error messages include JSON-pointer paths (e.g., /edges/0/to) for precise debugging.

Frequently Asked Questions

How do I validate an Archify diagram JSON file from the command line?

Run the archify validate command followed by the diagram type and file path. For example, archify validate workflow diagram.json checks the file against the workflow schema. The command exits with code 0 on success or a non-zero code on failure, making it suitable for pre-commit hooks and CI scripts.

What diagram types does Archify support for validation?

Archify supports validation for five diagram types: architecture, workflow, sequence, dataflow, and lifecycle. Each type uses a distinct AJV validator generated from its JSON schema, ensuring type-specific validation rules are enforced.

How can I get machine-readable validation output for CI pipelines?

Append the --json flag to any validate command to receive structured JSON output instead of human-readable text. This outputs an object with ok, type, checks, and meta properties that CI systems can parse programmatically, as demonstrated in archify/test/cli.test.mjs.

Where does Archify store the validation schema logic?

The validation logic resides in archify/renderers/shared/validator.mjs, which imports pre-compiled validators from generated-validators.mjs. The CLI entry point at bin/archify.mjs and shared utilities in archify/renderers/shared/cli.mjs orchestrate the validation process.

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