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

> Easily validate JSON files using Archify CLI. Learn the command `node bin/archify.mjs validate <type> <file.json>` and optional flags for quality and machine-readable output.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/tt-a1i/archify/blob/main/README.md) (line 21), the core syntax follows this pattern:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
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:

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

```

Expected output structure:

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

```

### Architecture Diagram with Repository Evidence

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

```bash
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:

```bash
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:

```bash
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.