# Archify Diagnostic Output Format: Complete JSON Receipt Schema for `validate` and `deliver` Commands

> Understand Archify's diagnostic output format. Get the complete JSON receipt schema for validate and deliver commands to view operation status and diagnostics.

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

---

**Archify's `validate` and `deliver` commands output a deterministic JSON receipt to STDOUT when invoked with the `--json` flag**, containing operation status, diagnostic entries, and optional composition data.

The `tt-a1i/archify` codebase implements a machine-first design for its command-line interface. Both validation and delivery workflows produce structured receipts that CI pipelines, agents, and external tools can parse without fragile text scraping. This article breaks down the exact schema, field semantics, and parsing patterns found in the source.

## JSON Receipt Structure

The **diagnostic output format** for both commands follows a single JSON object written exclusively to STDOUT. No other content contaminates the output stream.

### Top-Level Fields

| Field | Type | Presence | Description |
|-------|------|----------|-------------|
| `ok` | `boolean` | Required | Operation success indicator. `true` when all checks pass. |
| `checksPassed` | `number` | Required | Count of checks that satisfied constraints. |
| `checkCount` | `number` | Required | Total checks executed during the operation. |
| `diagnostics` | `Array<Diagnostic>` | Required | Diagnostic entries; empty array when `ok` is `true`. |
| `composition` | `object` | Optional | Deterministic layout or graph representation from validation. |
| `engineeringProfile` | `string` | Optional | Profile tag, e.g., `"deployment-ownership"`. Added by `deliver`. |
| `version` | `string` | Required | Archify version that generated the receipt. |
| `source` | `object` | Optional | Input metadata including `ref`, `path`, and related identifiers. |

### Diagnostic Object Schema

Each entry in the `diagnostics` array contains:

- `code` (`string`): Machine-readable identifier like `"workflow/column-capacity"`
- `message` (`string`): Human-readable problem description
- `subject` (`object`): Target reference with `id`, `type`, `path` properties
- `evidence` (`object`, optional): Concrete data such as geometry, obstacle IDs, or segment indices
- `severity` (`string`, optional): One of `"error"`, `"warning"`, `"info"`
- `supportedFixes` (`Array<string>`, optional): Auto-fix suggestions

## Exit Behavior and Stream Handling

Commands **always exit non-zero on failure**, but the JSON receipt prints to STDOUT regardless. Error stack traces route to STDERR exclusively. This separation guarantees parseable output even during runtime failures.

```bash

# Commands that fail still produce valid JSON on STDOUT

archify validate broken.json --json > receipt.json 2>errors.log
echo $?  # Non-zero exit code

jq . receipt.json  # Still valid and parseable

```

## Practical Usage Examples

### Validating a Workflow

```bash

# Generate validation receipt

archify validate workflow ./configs/pipeline.json --json > receipt.json

# Extract diagnostic count for CI gates

jq '.diagnostics | length' receipt.json

# Fail pipeline on any errors

jq -e '.ok' receipt.json > /dev/null || exit 1

```

### Delivery with Profile Tag

```bash

# Deliver architecture diagram with JSON receipt

archify deliver architecture diagram.json \
  --repo-root ./my-repo \
  --json > delivery.json

# Inspect added engineering profile

jq '.engineeringProfile' delivery.json

```

### Sample Receipt Output

```json
{
  "ok": true,
  "checksPassed": 1,
  "checkCount": 1,
  "diagnostics": [],
  "composition": {
    "nodes": [],
    "edges": []
  },
  "version": "2.14.0"
}

```

## Source Code Evidence

The implementation in `archify/bin/archify.mjs` handles CLI argument parsing and receipt serialization. Test coverage in `archify/test/repair-receipt.test.mjs` validates the schema through assertions on `receipt(validated).diagnostics`, `receipt.ok`, and `receipt.checksPassed` according to lines 67-73.

Documentation in [`docs/research-next-stability-delight-slice-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-stability-delight-slice-2026-07-23.md) (lines 86-108) explicitly contracts the output: `archify validate … --json` returns an object containing `checks`, `diagnostics`, and `composition`. The same document (lines 119-124) confirms `deliver --json` preserves this structure while appending `engineeringProfile`.

Additional validation logic appears in `archify/test/workflow-semantic-contract.test.mjs`, demonstrating how diagnostics accumulate and serialize during semantic analysis.

## Parsing Patterns for Automation

Scripts consuming Archify receipts should follow these patterns:

1. **Parse unconditionally** — `JSON.parse()` stdout without checking exit code first
2. **Gate on `ok` field** — Boolean success indicator is authoritative
3. **Iterate `diagnostics`** — Process severity levels for reporting granularity
4. **Version-check** — Compare `version` against known-compatible releases

```javascript
// Node.js example: robust receipt processing
import { execSync } from 'node:child_process';

function validateWorkflow(path) {
  const result = execSync(
    `archify validate workflow ${path} --json`,
    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }
  );
  
  const receipt = JSON.parse(result);
  
  return {
    success: receipt.ok,
    failures: receipt.diagnostics.filter(d => d.severity === 'error'),
    composition: receipt.composition
  };
}

```

## Summary

- Archify's **diagnostic output format** is a single JSON object written to STDOUT when `--json` is specified
- Both `validate` and `deliver` commands share the core schema; `deliver` adds optional `engineeringProfile`
- The `ok` boolean and `diagnostics` array provide machine-actionable operation status
- Exit codes indicate success/failure but do not affect JSON validity on STDOUT
- Source implementation resides in `archify/bin/archify.mjs` with test coverage in `archify/test/repair-receipt.test.mjs`

## Frequently Asked Questions

### What happens if validation passes with no issues?

The `diagnostics` array is empty (`[]`), `ok` is `true`, and `checksPassed` equals `checkCount`. The receipt still contains all required fields including `version` and optional `composition` data.

### Can I rely on JSON output when the command crashes?

Yes. Archify guarantees valid JSON on STDOUT even for non-zero exits. Error details and stack traces route to STDERR, keeping STDOUT parseable for pipeline resilience.

### How does the `deliver` receipt differ from `validate`?

The `deliver` command outputs the same base schema with an additional optional field: `engineeringProfile`. This string tag indicates the deployment ownership profile applied during delivery, as documented in the research notes for `archify deliver … --json`.

### Which Archify version introduced this JSON receipt format?

The source references in [`docs/research-next-stability-delight-slice-2026-07-23.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-next-stability-delight-slice-2026-07-23.md) and test files indicate this format is stable in version 2.14.0. The `version` field in receipts enables consumers to detect schema evolution.