How to Validate a JSON File with Archify CLI: Complete Command Guide

Use node bin/archify.mjs validate <type> <file.json> followed by optional flags like --quality showcase and --json to validate diagrams and receive machine-readable receipts.

Archify provides a lightweight Node.js CLI for validating diagram JSON files against strict schemas and layout rules. Whether you're integrating validation into a CI pipeline or debugging a diagram locally, the validate command in archify.mjs offers deterministic feedback through structured receipts and detailed diagnostics.

Archify CLI Validate Command Syntax

The validation entry point is archify/bin/archify.mjs. As documented in the repository's README.md (line 21), the core syntax follows this pattern:

node bin/archify.mjs validate <type> <candidate.json> [--quality standard|showcase] [--json] [--layout-json] [--repo-root <path>]

Required Arguments

• <type> — The diagram category. Must be one of: architecture, workflow, sequence, dataflow, or lifecycle.
• <candidate.json> — Path to the JSON file you want to validate.

Optional Flags

Flag	Purpose
--quality	Set validation strictness: standard (looser checks) or showcase (full nine-check profile).
--json	Output only the machine-readable receipt, suppressing console logs.
--layout-json	Include the deterministic layout contract in output for geometry debugging.
--repo-root	Required for architecture diagrams with repository-evidence nodes (SRC n).

The Two-Step Validation Process

According to archify/SKILL.md (lines 19-28), Archify validates JSON files through sequential stages:

1. Parse + Schema Check — The CLI parses the input and validates it against schemas/<type>.schema.json. Schema violations fail fast with clear diagnostics.
2. Layout + Render Check — A deterministic renderer verifies geometry rules: label clearance, edge-through-node constraints, and spatial consistency. failures emit diagnostics; success yields a receipt with checksPassed reflecting your quality profile.

Practical Validation Examples

Basic Workflow Validation

Get human-readable output for quick manual checks:

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json

CI-Ready JSON Receipt

For programmatic consumption, use --json to receive clean output:

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

Expected output structure:

{"ok":true,"checksPassed":9,"checks":9,"diagnostics":[],"meta":{…}}

Architecture Diagram with Repository Evidence

When validating architecture diagrams containing SRC n nodes, supply --repo-root:

node bin/archify.mjs validate architecture examples/archify-repo.json \
    --repo-root /path/to/your/repo --quality showcase --json

Debug Layout Geometry

Request the layout contract to troubleshoot positioning issues:

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
    --layout-json --json

This emits both layout and diagnostics objects for granular analysis.

CI Pipeline Integration

The CLI returns standard exit codes: 0 for success, non-zero for failure. Use this pattern:

if ! node bin/archify.mjs validate architecture my-diagram.json --json; then
  echo "❌ Validation failed – see diagnostics above"
  exit 1
fi

Understanding the Validation Receipt

The receipt format, defined in archify/SKILL.md (lines 24-28), contains these key fields:

• ok — Boolean indicating overall success.
• checksPassed — Number of checks satisfied (9 for showcase quality).
• checks — Total checks attempted.
• diagnostics — Array of structured failure objects with locations and remediation hints.
• meta — Validation metadata including type, quality profile, and timestamps.

The archify/test/repair-receipt.test.mjs test suite enforces receipt structure and diagnostic presence, ensuring consistent output across versions.

Quality Profiles Explained

Profile	Checks	Use Case
standard	Fewer geometric constraints	Draft diagrams, rapid iteration.
showcase	All 9 checks including strict layout rules	Production assets, publication-ready diagrams.

Specify with --quality showcase or --quality standard. Default behavior may vary by diagram type; consult archify/SKILL.md for version-specific defaults.

Key Source Files Reference

• archify/bin/archify.mjs — CLI entry point, argument parsing, and receipt emission.
• archify/SKILL.md — Skill contract defining validation flow, receipt schema, and quality profiles (lines 19-28).
• archify/schemas/ — JSON Schema definitions for each diagram type.
• archify/test/repair-receipt.test.mjs — Receipt structure and diagnostic assertions.

Summary

• Primary command: node bin/archify.mjs validate <type> <file.json>
• Machine output: Add --json for parseable receipts in CI/CD.
• Strict validation: Use --quality showcase for full nine-check compliance.
• Repository linking: Include --repo-root for architecture diagrams with evidence nodes.
• Debug support: --layout-json exposes deterministic layout contracts.
• Exit codes: 0 on success, non-zero on failure—receipt prints regardless.

Frequently Asked Questions

What JSON schema does Archify use for validation?

Archify validates against type-specific schemas located in archify/schemas/. Each diagram type—architecture, workflow, sequence, dataflow, lifecycle—has its own schema.json file. The CLI automatically selects the appropriate schema based on the <type> argument you provide.

Can I validate JSON files in a CI pipeline without human-readable output?

Yes. Use the --json flag to suppress console logs and emit only the machine-readable receipt. Combine with shell exit code checking: the CLI returns 0 on success and non-zero on failure, allowing standard CI conditional logic.

What is the difference between standard and showcase quality?

standard quality applies looser geometric and layout constraints, suitable for drafts. showcase quality runs all nine validation checks including strict rules for label clearance and edge routing. Set with --quality showcase or --quality standard per your diagram maturity requirements.

Why does my architecture validation fail with missing repository errors?

Architecture diagrams containing SRC n nodes require the --repo-root flag pointing to your repository's root directory. This enables the CLI to verify that referenced source files exist and match the evidence claims in your diagram JSON.

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