# Types of Validation Checks Archify Performs: A Complete Technical Guide

> Discover the eight types of validation checks Archify performs, including JSON-Schema compliance, topological integrity, and geometric layout rules. Get structured diagnostic receipts with this technical guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-11

---

**Archify executes eight distinct validation categories—from JSON-Schema compliance and topological integrity to geometric layout rules and engineering-profile matching—through a deterministic, JSON-serializable pipeline that produces structured diagnostic receipts.**

Archify is an open-source diagram validation and rendering engine maintained in the `tt-a1i/archify` repository. Understanding the **types of validation checks Archify performs** is essential for CI/CD integration and ensuring architectural diagrams meet structural, geometric, and semantic standards before publishing.

## JSON-Schema and Structural Validation

Every validation run begins in `archify/renderers/shared/validator.mjs`, where Archify confirms the input document conforms to the official Archify JSON schema. This check supports multiple diagram types—including **architecture**, **workflow**, **dataflow**, and **lifecycle**—ensuring mandatory fields exist and data types match the schema definitions. The `validateSchema()` function returns a result object with an `ok` boolean and an `errors` array if the document violates structural constraints.

## Topology and Identity Checks

After schema validation, the system performs **topology and identity validation** to guarantee graph integrity. This phase detects:

- Duplicate IDs across nodes and edges
- Missing node references in edge definitions
- Malformed edge definitions lacking source or target identifiers

These checks ensure every graph element possesses a stable, unique identifier required for downstream rendering and contract validation.

## Geometric and Layout Validation

Geometric rules are enforced by `archify/renderers/shared/geometry.mjs`. This module validates:

- **Node overlap detection**: Ensures components do not occupy identical coordinates
- **Edge intersection rules**: Verifies edges do not traverse forbidden regions
- **Reserved-area compliance**: Confirms diagram elements respect exclusion zones
- **Edge-through-node violations**: Prevents lines from passing through component boundaries

The geometry engine operates on normalized coordinates and returns specific diagnostic codes (e.g., `clean-flow/edge-through-node`) when violations occur.

## Grid Placement Validation

For architecture diagrams utilizing matrix layouts, `archify/renderers/architecture/grid.mjs` executes **grid placement validation**. This check ensures:

- Row and column matrices are well-formed
- Each grid cell contains at most one component
- Explicit position overrides remain within matrix bounds
- Cell occupancy constraints are satisfied

Grid validation runs prior to geometric checks to establish the coordinate framework used by the layout engine.

## Visual Quality and Readability Checks

Archify applies the **"showcase" quality profile** through `archify/renderers/shared/desktop-readability.mjs`. These validation checks enforce:

- Minimum pixel clearance between elements (optimized for 1440 px viewports)
- Label readability standards (contrast ratios and font sizes)
- Edge-stroke width compliance
- Overall visual density limits

Enable these checks by passing `--quality showcase` to the CLI for publication-ready diagrams.

## Engineering Profile and Contract Validation

The system validates **engineering profiles** in `archify/renderers/shared/engineering-profiles.mjs`. This verification confirms that a diagram's declared profile (e.g., `deployment-ownership`) matches the required profile for the artifact type, linking the diagram to concrete deployment metadata and organizational ownership rules.

Additionally, `scripts/check-release-identity.mjs` performs **release manifest validation** via `validateLocalRelease()` and `validateStableUpdateManifest()` functions. These checks ensure packaging integrity when publishing Archify-based skills or stable updates.

## Diagnostics and Automated Repair

When validation fails, `archify/renderers/shared/diagnostics.mjs` generates structured diagnostic objects containing:

- Human-readable error messages
- Machine-readable error codes
- Subject references (node/edge IDs)
- Evidence objects with coordinates or values
- **Supported fixes** arrays with auto-repair instructions

The `repairReceipt()` function consumes these diagnostics to apply suggested fixes—such as rerouting edges through alternative nodes—and produces a modified diagram that can be re-validated.

## Running Validation: CLI and Programmatic Examples

### CLI Validation

Validate an architecture diagram and receive a JSON receipt:

```bash
archify validate architecture path/to/diagram.json --json

```

Apply the showcase quality profile for desktop readability checks:

```bash
archify validate architecture path/to/diagram.json --quality showcase --json

```

### Programmatic Validation

Import validation functions directly in Node.js applications:

```javascript
import { validateSchema } from './archify/renderers/shared/validator.mjs';
import { validateArchitecture } from './archify/renderers/architecture/render-architecture.mjs';
import { readFileSync } from 'fs';

const doc = JSON.parse(readFileSync('path/to/diagram.json', 'utf8'));

// Schema validation
const schemaResult = validateSchema('architecture', doc);
if (!schemaResult.ok) {
  console.error('Schema errors:', schemaResult.errors);
}

// Full validation with geometry and readability
const receipt = validateArchitecture(doc, { quality: 'showcase' });
console.log('Checks passed:', receipt.checksPassed);
console.log('Diagnostics:', receipt.diagnostics);

```

### Automated Repair Workflow

Apply suggested fixes programmatically:

```javascript
import { repairReceipt } from './archify/renderers/shared/diagnostics.mjs';

const receipt = validateArchitecture(doc, { quality: 'showcase' });
const fix = receipt.diagnostics.find(d => 
  d.code === 'clean-flow/edge-through-node'
);

if (fix && fix.suggestedFixes.length > 0) {
  const repaired = repairReceipt(receipt, fix.suggestedFixes[0]);
  // Save repaired.document for re-validation
}

```

## Summary

- **JSON-Schema validation** enforces document structure and data types via `validator.mjs`.
- **Topology checks** eliminate duplicate IDs and malformed graph references.
- **Geometry validation** prevents visual collisions and layout violations in `geometry.mjs`.
- **Grid validation** ensures matrix-based diagrams maintain proper cell occupancy.
- **Readability checks** apply showcase-quality standards for publication-ready output.
- **Engineering profiles** link diagrams to deployment metadata and organizational rules.
- **Release validation** secures packaging integrity through manifest checks.
- **Diagnostic receipts** provide structured error reports and auto-repair capabilities.

## Frequently Asked Questions

### How does Archify handle schema validation for different diagram types?

Archify dispatches to type-specific JSON schemas through the `validateSchema()` function in `archify/renderers/shared/validator.mjs`. Each diagram type (architecture, workflow, dataflow) loads its respective schema definition, validating mandatory fields and type constraints before proceeding to geometric checks.

### Can Archify automatically fix validation errors?

Yes. When the validation pipeline detects violations, `archify/renderers/shared/diagnostics.mjs` generates diagnostic objects containing `suggestedFixes` arrays. The `repairReceipt()` function consumes these suggestions to apply automated corrections—such as rerouting edges or adjusting node positions—returning a repaired diagram document ready for re-validation.

### What is the difference between geometry validation and grid placement validation?

**Grid placement validation** (`grid.mjs`) operates on the logical matrix structure of architecture diagrams, ensuring cells contain single components and coordinates fit the row/column schema. **Geometry validation** (`geometry.mjs`) operates on the rendered pixel coordinates, checking for physical overlaps, edge intersections, and viewport clearance regardless of the underlying grid system.

### How do I integrate Archify validation into a CI pipeline?

Invoke the CLI with the `--json` flag to receive machine-readable receipts. The exit code reflects validation status (`checksPassed`), while stdout contains a JSON object with `checkCount` and `diagnostics` arrays. Parse this output in GitHub Actions, GitLab CI, or Jenkins to gate merges based on diagram integrity or quality profile compliance.