# How Archify's Validation Process Identifies Repairs in Machine-Readable JSON

> Archify's validation pipeline converts schema and layout violations into diagnostic objects with machine-actionable supportedFixes, identifying repairs in machine-readable JSON.

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

---

**Archify identifies repairs in machine-readable JSON through a two-stage validation pipeline that converts schema and layout violations into structured diagnostic objects containing machine-actionable `supportedFixes`.**

The Archify validation process transforms workflow document errors into actionable repair suggestions by combining schema validation with geometric relational checks. When processing JSON workflow definitions, the compiler generates structured diagnostics that specify exactly how to fix each violation. This enables automated repair workflows in CLI tools, UI previews, and CI pipelines without manual JSON editing.

## Two-Stage Validation Architecture

Archify's validation engine operates sequentially, first verifying structural compliance then examining spatial and relational constraints. Each stage accumulates violations into a `problems` array that is later converted into standardized diagnostic objects.

### Stage 1: Schema Validation

The validator first ensures the document conforms to the core Archify JSON schema using AJV-generated validators located in `archify/renderers/shared/generated-validators.mjs`. This initial pass checks critical fields such as `schema_version`, `diagram_type`, and required meta information. It also verifies that mandatory arrays including `lanes`, `nodes`, and `edges` exist and contain valid types.

According to the source code in `archify/renderers/workflow/workflow-compiler.mjs` (lines 90-106), schema violations are collected in a `problems` array and associated with a subject identifier like `{ diagramType: 'workflow' }`. These problems serve as the foundation for the diagnostic objects created in the second stage.

### Stage 2: Layout and Relational Checks

After schema validation passes, Archify performs geometric and relational validations to ensure the workflow is renderable:

- **Uniqueness constraints**: Duplicate IDs across lanes, nodes, phases, and groups are flagged
- **Spatial consistency**: Node-to-lane alignment, column bounds, and finite coordinate checks prevent rendering errors
- **Dimension validation**: Node sizes are checked against label widths, sub-label/tag widths, and lane boundaries
- **Containment rules**: Phase and group column ranges are validated for overlaps and proper node containment
- **Edge integrity**: Source and target node existence is verified alongside pin-placement conflicts

Each violation pushes a descriptive string onto the `problems` array (for example, *"Node 'A' uses unknown lane 'B'"*). The system then invokes `throwDiagnosticProblems` to convert these strings into structured diagnostic records.

## Diagnostic Structure and Machine-Readable Repairs

Archify transforms accumulated validation errors into diagnostic objects containing four critical fields that enable automated repair. As implemented in `archify/renderers/workflow/workflow-compiler.mjs` (lines 121-135), each diagnostic includes:

- **`code`**: A machine-readable identifier for the specific rule that failed (e.g., `schema/additionalProperties`)
- **`subject`**: The precise location within the JSON document that triggered the error, including the path and relevant property names
- **`evidence`**: Contextual data such as offending node IDs, lane references, or numeric values that caused the violation
- **`supportedFixes`**: An array of machine-readable repair actions that can automatically resolve the issue, such as *"remove unsupported property 'unexpected'"*

This structure allows downstream tools to parse exactly what is wrong and how to fix it without human interpretation.

## Repair Receipt Generation

When the validator throws a diagnostic, Archify captures it into a **repair receipt** JSON file. This receipt contains the original diagnostics together with the exact JSON patches required to fix each problem.

The test suite in `archify/test/repair-receipt.test.mjs` (lines 70-80) asserts that these receipts correctly record the `subject`, `evidence`, and human-readable `supportedFixes` array. By persisting both the error description and the correction logic, the system enables non-destructive editing workflows where repairs can be reviewed before automatic application.

## Implementing Validation in Practice

Use the `compileWorkflow` function from `workflow-compiler.mjs` to trigger validation and access repair suggestions programmatically.

```javascript
import { compileWorkflow } from './archify/renderers/workflow/workflow-compiler.mjs';
import fs from 'fs';

// Load a workflow JSON file (may contain errors)
const raw = fs.readFileSync('my-workflow.json', 'utf8');
const workflow = JSON.parse(raw);

// Run validation + compilation
const result = compileWorkflow({ workflow, qualityProfile: 'standard' });

if (!result.ok) {
  // result.diagnostics is an array of objects describing each problem
  console.log('Validation failed with diagnostics:');
  console.dir(result.diagnostics, { depth: null });

  // Each diagnostic includes a `supportedFixes` field – a machine-readable repair
  result.diagnostics.forEach(d => {
    console.log(`Problem: ${d.code}`);
    console.log(`Repair options: ${d.supportedFixes.join(', ')}`);
  });
}

```

Internally, `compileWorkflow` invokes `validateWorkflow()`. When validation fails, it returns an object structured like this:

```json
{
  "ok": false,
  "diagnostics": [
    {
      "code": "schema/additionalProperties",
      "subject": { "path": "/nodes/0", "property": "unexpected" },
      "evidence": { "additionalProperty": "unexpected" },
      "supportedFixes": [ "remove unsupported property \"unexpected\"" ]
    }
  ]
}

```

These JSON objects represent the **machine-readable repairs** that Archify's validation process identifies, allowing automated tools to apply corrections via standard JSON patch operations.

## Summary

- Archify employs a **two-stage validator** that combines AJV schema checks in `generated-validators.mjs` with geometric relational rules in `workflow-compiler.mjs`
- Violations accumulate in a `problems` array processed by `throwDiagnosticProblems` to create standardized diagnostics
- Each diagnostic contains `code`, `subject`, `evidence`, and `supportedFixes` fields that enable machine parsing of both errors and solutions
- **Repair receipts** generated during validation persist diagnostics and JSON patches for automated resolution workflows
- The `compileWorkflow` API exposes this data through a simple interface accepting a `qualityProfile` parameter and returning an `ok` status boolean

## Frequently Asked Questions

### What is the Archify validation process?

The Archify validation process is a two-stage pipeline that first validates JSON documents against core schema definitions using AJV, then performs geometric and relational checks on workflow elements like nodes, lanes, and edges. This process converts all detected violations into structured diagnostic objects containing machine-readable repair instructions in the `supportedFixes` field.

### How does Archify represent repair suggestions in JSON?

Archify represents repairs through the `supportedFixes` array within diagnostic objects. Each entry is a human-readable description that maps to an automated JSON patch operation, such as removing unsupported properties or adjusting column indices. These arrays are contained within diagnostics that also specify the exact `subject` path and `evidence` data explaining the violation.

### Can Archify automatically apply the repairs it identifies?

Yes, while Archify identifies and structures the repairs, downstream tools including the CLI, UI preview, and CI pipelines can consume the `supportedFixes` data to automatically apply the suggested JSON patches. The repair receipt system in `repair-receipt.test.mjs` demonstrates how these fixes can be persisted and applied without manual editing of the source workflow files.

### Which source files handle the core validation logic?

The primary validation logic resides in `archify/renderers/workflow/workflow-compiler.mjs`, which contains both the `validateWorkflow()` function and `throwDiagnosticProblems()` method used to assemble diagnostics. Schema-specific validation uses `archify/renderers/shared/generated-validators.mjs` for AJV-based structural checks, while `archify/test/repair-receipt.test.mjs` validates the repair receipt generation functionality.