Understanding the Archify Authoring Contract for JSON IR

The Archify authoring contract for JSON IR is a strict specification in 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, 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.

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

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.

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

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.
• 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 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.

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