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

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.

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:

{
  "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.

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