How to Validate a JSON Diagram Against Its Schema Using Archify

Archify provides a self-contained CLI that validates any supported diagram JSON against its type-specific schema and returns a machine-readable JSON receipt indicating success or detailed validation errors.

The tt-a1i/archify repository ships with a schema-driven validation system designed to ensure diagram files conform to strict structural contracts before rendering. By leveraging ahead-of-time compiled validators, Archify checks your JSON against formal JSON Schema definitions stored in the source tree, providing immediate feedback on schema violations.

How Archify Validates JSON Diagrams

Validation in Archify follows a deterministic pipeline that begins at the CLI entry point and ends with a structured diagnostic report. The system uses pre-generated validators to eliminate runtime dependencies while maintaining strict adherence to the schemas defined in archify/schemas/.

The CLI Entry Point

The validation flow starts in archify/bin/archify.mjs, which parses command-line arguments through its internal usage() function. When you invoke the validate command, the CLI:

1. Reads the input file using fs.readFileSync and captures any I/O errors as inputDiagnostic messages.
2. Sets the environment variable ARCHIFY_DIAGNOSTIC_FORMAT=json to instruct renderers to emit structured output rather than human-readable text.
3. Dispatches to the type-specific renderer (e.g., render-architecture.mjs), which imports the generated validator and executes validator.validate(data).

The rendererFailure() function in the CLI normalizes any unexpected process failures into the standard diagnostic shape, ensuring consistent error handling across all diagram types.

Pre-Generated Validator Architecture

Validators are not interpreted at runtime; they are compiled ahead of time by archify/scripts/generate-validators.mjs. This build-time script uses Ajv 2020 to parse every schema in archify/schemas/ and generate a pure-ESM module at archify/renderers/shared/generated-validators.mjs. Because the script produces deterministic, self-contained code without external require calls, validation executes rapidly using only the core Node.js runtime.

Schema Definitions and Supported Types

Archify recognizes five distinct diagram types, each with its own JSON Schema file:

• architecture — archify/schemas/architecture.schema.json
• workflow
• sequence
• dataflow
• lifecycle

These schemas enforce required fields such as schema_version, diagram_type, meta, and type-specific structures. For example, the architecture schema requires that component id values match the regular expression pattern ^[A-Za-z_][A-Za-z0-9_-]*$.

Running Schema Validation from the Command Line

You can validate any supported diagram JSON using the Archify CLI. The command syntax requires specifying the diagram type and the path to your JSON file.

Installation and Basic Usage

If you have not installed Archify globally, add it to your environment:

npx skills add tt-a1i/archify -g

Run validation with the JSON receipt flag:

archify validate architecture my-diagram.json --json

Without the --json flag, the CLI prints human-readable validation errors to stderr. With the flag, it returns a structured JSON object to stdout.

Validating Different Diagram Types

The CLI accepts any of the five supported types as the first positional argument:

# Validate a workflow diagram

archify validate workflow examples/web-app.workflow.json --json

# Validate a dataflow diagram and save the receipt

archify validate dataflow examples/rag-pipeline.dataflow.json --json > receipt.json

Interpreting Validation Results

When you pass the --json flag, Archify prints a validation receipt containing an ok boolean and, on failure, a diagnostics array. The diagnostic() function in archify/bin/archify.mjs formats each schema violation into a consistent structure:

{
  "ok": false,
  "error": "validation failed",
  "diagnostics": [
    {
      "code": "components/0/id",
      "severity": "error",
      "message": "must match pattern \"^[A-Za-z_][A-Za-z0-9_-]*$\"",
      "subject": { "input": "my-diagram.json", "component": 0 },
      "evidence": { "value": "1InvalidId" }
    }
  ]
}

Each diagnostic includes:

• code — The JSON path to the invalid property
• severity — The error level (e.g., "error")
• message — The human-readable schema constraint description
• subject — Contextual metadata about the location in the input file
• evidence — The actual value that violated the constraint

If the diagram is valid, the receipt contains "ok": true and an empty diagnostics array.

Summary

• Archify validates JSON diagrams against type-specific JSON Schemas stored in archify/schemas/.
• The CLI entry point at archify/bin/archify.mjs orchestrates validation by setting ARCHIFY_DIAGNOSTIC_FORMAT=json and invoking type-specific renderers.
• Validators are pre-generated using Ajv 2020 via archify/scripts/generate-validators.mjs and stored in archify/renderers/shared/generated-validators.mjs for fast, dependency-free execution.
• The validate command accepts five diagram types: architecture, workflow, sequence, dataflow, and lifecycle.
• Use the --json flag to receive a machine-readable receipt with detailed diagnostics pinpointing every schema violation.

Frequently Asked Questions

What diagram types does Archify support for validation?

Archify supports five diagram types: architecture, workflow, sequence, dataflow, and lifecycle. Each type has a dedicated JSON Schema file located in the archify/schemas/ directory, ensuring that validators and renderers remain synchronized for every supported format.

How does Archify generate its validators?

Archify uses the script archify/scripts/generate-validators.mjs to compile JSON Schemas into pure-ESM JavaScript modules. This script leverages Ajv 2020 to create deterministic validator functions that are bundled into archify/renderers/shared/generated-validators.mjs, eliminating runtime schema compilation and external dependencies.

Can I validate diagrams without installing the CLI globally?

Yes. You can run validation using npx without a global installation, or install Archify locally within a project. The CLI operates locally regardless of installation method, requiring only a Node.js runtime to execute the pre-generated validators.

What information is included in a validation error diagnostic?

Each diagnostic object contains a code field indicating the JSON path of the error, a severity level, a descriptive message explaining the constraint violation, a subject object identifying the location in the input file, and an evidence object showing the actual invalid value. This structure allows automated tools to pinpoint and report schema violations precisely.

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