# Archify JSON Diagnostic Format: Structure, Schema, and Usage

> Understand the Archify JSON diagnostic format. Learn about its structure, schema, and usage for error reporting with code, severity, subject, evidence, and supportedFixes fields.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-29

---

**Archify reports validation and runtime errors through a structured JSON diagnostic object containing `code`, `severity`, `subject`, `evidence`, and `supportedFixes` fields, embedded in the receipt's `diagnostics[]` array.**

The `tt-a1i/archify` repository uses a machine-readable **JSON diagnostic format** to communicate precise problem reports during validation, delivery, and preview operations. Every command execution returns a receipt containing a `diagnostics` array that details exactly what went wrong, where it occurred, and how to resolve it.

## Core Schema of the JSON Diagnostic Format

Each diagnostic object in `receipt.diagnostics[]` follows a strict contract enforced by the test suite and architectural documentation.

### Required Fields

Every diagnostic must include three core fields:

- **`code`**: A stable string identifier for the rule that triggered the issue (e.g., `input/json-parse`, `viewer/visual-check-runtime`). As implemented in `archify/test/repair-receipt.test.mjs`, this field appears at index 0 of the diagnostics array.
- **`severity`**: One of `"error"`, `"warning"`, or `"info"`, indicating the criticality of the problem and whether the operation should halt.
- **`subject`**: An object describing the target of the diagnostic, such as a file path, JSON pointer, or UI element. The exact shape varies by diagnostic type.

### Contextual and Optional Fields

Additional fields provide debugging context and remediation paths:

- **`message`**: An optional human-readable description, often generated dynamically from evidence data. The visual-check test suite references this via `diagnostic?.message` in `archify/test/visual-check.test.mjs`.
- **`evidence`**: An object containing concrete data explaining the failure, such as offending JSON tokens, pixel measurements, or system reason strings like `ECONNRESET`. Accessed in `archify/test/visual-check.test.mjs` as `diagnostic?.evidence?.reason`.
- **`supportedFixes`**: An array of deterministic fix suggestions that clients can apply automatically without guessing. Each entry is either a command-line flag or a descriptive action like `"increase-gap-size"` or `"regenerate-layout"`.

## Real-World Diagnostic Examples

The test files demonstrate the format in practice. A typical validation failure receipt structure appears in `archify/test/repair-receipt.test.mjs`:

```json
{
  "receipt": {
    "stage": "validate",
    "diagnostics": [
      {
        "code": "viewer/visual-check-runtime",
        "severity": "error",
        "subject": { "input": "..." },
        "evidence": { 
          "reason": "ECONNRESET", 
          "scrollWidth": 1601 
        },
        "supportedFixes": [
          "increase-gap-size", 
          "regenerate-layout"
        ]
      }
    ]
  }
}

```

Visual validation failures in `archify/test/visual-check.test.mjs` utilize the same schema, accessing fields like `diagnostic?.evidence?.reason` and `diagnostic?.supportedFixes` to verify that the system generates actionable repair suggestions.

## Processing Diagnostics in JavaScript

When consuming Archify's JSON output programmatically, parse the receipt and iterate over the `diagnostics` array to handle issues appropriately.

**Reading and displaying all diagnostics:**

```javascript
import { readFileSync } from 'fs';

const receipt = JSON.parse(readFileSync('archify-output.json', 'utf8'));

if (receipt.diagnostics?.length) {
  for (const d of receipt.diagnostics) {
    console.log(`${d.severity.toUpperCase()}: ${d.code}`);
    console.log('  Subject:', d.subject);
    console.log('  Evidence:', d.evidence);
    console.log('  Fixes:', d.supportedFixes?.join(', ') || 'None');
  }
}

```

**Filtering for blocking errors only:**

```javascript
const errors = receipt.diagnostics.filter(d => d.severity === 'error');
if (errors.length) {
  console.error(`Found ${errors.length} critical errors. Aborting.`);
  process.exit(1);
}

```

## Stability and Deterministic Ordering

The JSON diagnostic format guarantees long-term stability for automation. According to [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md), diagnostic codes never change for existing rules, ensuring backwards compatibility. Furthermore, Archify sorts diagnostics by Unicode code-point order to produce deterministic output across runs. This prevents noisy diffs in version-controlled receipts and enables reliable diff-based testing.

## Summary

- The **JSON diagnostic format** in Archify uses a fixed schema with `code`, `severity`, `subject`, `evidence`, and `supportedFixes` fields.
- Diagnostics reside in `receipt.diagnostics[]` and appear in both success and failure receipts according to [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).
- Severity levels are strictly `"error"`, `"warning"`, or `"info"`.
- The format guarantees stable codes and deterministic Unicode sorting for reliable automation.
- Reference implementations appear in `archify/test/repair-receipt.test.mjs` and `archify/test/visual-check.test.mjs`.

## Frequently Asked Questions

### What fields are required in every Archify diagnostic object?

Every diagnostic must contain `code`, `severity`, and `subject`. The `code` identifies the rule (e.g., `input/json-parse`), `severity` indicates the impact level, and `subject` points to the affected resource. Optional fields like `message`, `evidence`, and `supportedFixes` provide additional context but are not guaranteed in every entry.

### How does Archify sort diagnostics in the JSON output?

Archify sorts diagnostics by Unicode code-point order to ensure deterministic output. This prevents arbitrary reordering between runs, making diffs predictable in version-controlled environments as documented in [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md).

### Can I rely on diagnostic codes remaining stable across Archify versions?

Yes. The diagnostic contract guarantees that `code` values remain immutable for existing rules. New diagnostics receive unique codes (e.g., `output/input-alias`), ensuring forwards and backwards compatibility for automated parsers and CI pipelines.

### Where is the JSON diagnostic format documented in the source code?

The definitive reference appears in `archify/test/repair-receipt.test.mjs`, which validates the `diagnostics[]` array structure including `supportedFixes`. Visual validation examples exist in `archify/test/visual-check.test.mjs`, while architectural stability guarantees are outlined in [`docs/research-architecture-delta-pr-proof-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-architecture-delta-pr-proof-2026-07-23.md) and [`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md).