# Understanding the Archify Authoring Contract for JSON IR

> Learn about the Archify authoring contract for JSON IR. Discover syntax rules, required fields, and rendering behavior for diagram intermediate representations. Ensure valid diagram data.

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

---

**The Archify authoring contract for JSON IR is a strict specification in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) that defines valid syntax, required fields, and rendering behavior for all diagram intermediate representations.**

Every diagram consumed by the `tt-a1i/archify` tool must conform to this typed JSON IR (Intermediate Representation). The contract governs everything from schema versioning to geometric spacing rules, ensuring deterministic rendering across the architecture, workflow, sequence, dataflow, and lifecycle diagram modes.

## Core Schema Requirements

All JSON IR documents must satisfy immutable schema rules enforced by the validator in `archify/bin/archify.mjs`.

### Schema Version

Every JSON IR must declare `"schema_version": 1`. This version is immutable; any breaking change forces a version bump. According to [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md), the validator rejects documents missing this field or containing unrecognized versions.

### Component Type and Variant Enums

The `componentType` field accepts only specific string values: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, or `external`. The `variant` property supports `default`, `emphasis`, `security`, or `dashed`. These enums control visual styling and must match exactly as defined in the contract.

### Relationship IDs

All node and edge identifiers must follow the shared identifier pattern and remain **unique** within the diagram scope. Duplicate IDs trigger a schema validation error via `ajv`.

## Metadata and Localization

The `meta` object controls presentation, locale, and visual presets.

### Locale Settings

Authors must specify a single primary language. Set `meta.locale` to `"en"` or `"zh-CN"` for supported locales. If authoring in any other language, you **must omit** `meta.locale` entirely; the UI defaults to English and displays a warning that renderer-owned UI elements remain untranslated. The locale affects only interface chrome, never authored content.

### Visual Presets

The optional `meta.visual_preset` accepts `classic`, `signal-flow`, `blueprint`, or `editorial`. This preset operates independently of light/dark mode. The default state omits this key entirely.

### Engineering Profiles

Omit `meta.engineering_profile` unless generating a deployment-ownership diagram. When required, this profile distinguishes between architectural views and operational ownership views.

### Title Hierarchy

Only `meta.title` is mandatory. The `meta.subtitle` field defaults to omission; if present, it must contain non-empty content and must not create empty visual rows in the rendered output.

## Visual Geometry and Layout Rules

The contract prescribes exact geometric calculations to prevent visual defects.

### Port Spreading and Geometry

Node ports anchor at side mid-points. **Automatic Port Spread** is the default behavior, applying a 16 px corner gutter, 8 px minimum segment length, and 16 px interior segment length. Edges crossing through nodes constitute a hard failure and violate the contract.

```json
{
  "schema_version": 1,
  "title": "Two-Tier App",
  "nodes": [
    { "id": "frontend", "type": "frontend", "pos": [100, 100], "size": [120, 60] },
    { "id": "backend",  "type": "backend",  "pos": [300, 100], "size": [120, 60] }
  ],
  "edges": [
    {
      "source": "frontend",
      "target": "backend",
      "ports": { "source": "right", "target": "left" }
    }
  ]
}

```

### Label Clearance Calculations

Labels require a clear gap greater than `label mask width + 8 px`. The mask width calculates as approximately `6.5 px × ASCII units + 13 px`, where CJK characters count as two units. This ensures text remains legible and unobstructed by connecting edges.

### Deterministic Repair Order

When the renderer fixes layout issues, it follows a strict sequence: quality profile → node overlap → edge-through-node violations → crossing reduction → label clearance. This deterministic order ensures consistent output across renders, as documented in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).

## Special Modes and Evidence

### Legend Configuration

The `meta.legend` object defaults to `auto` (omitted). Set `mode` to `"all"` to display the full legend or `"hidden"` to suppress it. Only schema-defined keys may appear under `entries`, each supporting `label` and `visible` boolean properties.

```json
{
  "schema_version": 1,
  "title": "Auth Service",
  "meta": {
    "legend": {
      "mode": "all",
      "entries": {
        "backend": { "label": "Backend Service", "visible": true },
        "frontend": { "label": "Frontend UI", "visible": false }
      }
    }
  }
}

```

### Repository Evidence

When diagrams reflect real codebases, authors must supply verified evidence using the `--repo-root <path>` flag. The CLI inspects entry points, runtime boundaries, storage, transports, and deployment configuration to validate that referenced artifacts exist.

```bash
archify render architecture diagram.json --repo-root /path/to/source

```

### Hand-Placed Fallback

If the renderer cannot execute, the contract mandates falling back to a hand-crafted HTML template. This fallback must preserve semantic CSS classes and SVG accessibility structure, ensuring diagrams remain usable even without JavaScript execution.

## Validation and Enforcement

The contract is authoritative. `archify/bin/archify.mjs` loads the contract definitions and validates input JSON using `ajv`. Any deviation produces an error with a precise diagnostic path. The test suite in `archify/test/authoring-safety-contract.test.mjs` continuously verifies that violations are caught early, preventing invalid diagrams from reaching the rendering pipeline.

## Summary

- **Schema Version**: Every JSON IR must specify `"schema_version": 1` as defined in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md).
- **Strict Enums**: Use only approved values for `componentType` and `variant` to avoid validation failures.
- **Geometric Precision**: Automatic port spreading and label mask calculations follow fixed mathematical rules.
- **Authoritative Validation**: The CLI enforces the contract via `ajv`, rejecting documents with precise error messages.
- **Repository Integration**: Use `--repo-root` to validate diagrams against actual source code artifacts.

## Frequently Asked Questions

### What happens if I omit the schema_version field?

The validator in `archify/bin/archify.mjs` rejects the document immediately. The `ajv` schema validator requires `schema_version: 1` as a mandatory property, and missing fields generate a precise diagnostic path indicating the violation location.

### Can I use custom component types not listed in the contract?

No. The `componentType` field is restricted to `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`. Any other value fails schema validation. To request support for new types, you must modify the contract in [`archify/references/authoring-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/authoring-contract.md) and bump the schema version.

### How does Archify handle diagrams when the renderer fails?

The authoring contract specifies a hand-placed HTML fallback that preserves semantic CSS classes and SVG accessibility structure. This ensures diagrams remain readable and standards-compliant even when the JavaScript rendering engine cannot execute.

### What is the correct way to specify a non-English language in the metadata?

For supported locales, set `meta.locale` to `"en"` or `"zh-CN"`. For any other language, you must omit the `meta.locale` field entirely; the system defaults to English UI and warns users that renderer interface elements remain untranslated. The locale setting never translates authored diagram content, only renderer-owned chrome.